idnits 2.17.1 draft-ietf-httpbis-semantics-19.txt: -(11135): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(11139): 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 (10 September 2021) is 953 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 9555, but no explicit reference was found in the text == Unused Reference: 'RFC2617' is defined on line 9579, but no explicit reference was found in the text == Unused Reference: 'RFC7234' is defined on line 9658, but no explicit reference was found in the text == Unused Reference: 'RFC7617' is defined on line 9687, but no explicit reference was found in the text -- 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 (~~), 7 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: 14 March 2022 10 September 2021 10 HTTP Semantics 11 draft-ietf-httpbis-semantics-19 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.20. 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 14 March 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 . . . . . . . . . . . . . . . . 23 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 . . . . . . . . . . . . . . . . 165 295 15.5.4. 403 Forbidden . . . . . . . . . . . . . . . . . . . 165 296 15.5.5. 404 Not Found . . . . . . . . . . . . . . . . . . . 165 297 15.5.6. 405 Method Not Allowed . . . . . . . . . . . . . . . 165 298 15.5.7. 406 Not Acceptable . . . . . . . . . . . . . . . . . 166 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 . . . . . . . . . . . . . . . 168 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 . . . . . . . . . . . . . 169 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 . . . . . . . . . . . . . . 172 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 . . . . . . . . 175 328 16.3. Field Extensibility . . . . . . . . . . . . . . . . . . 176 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 . . . . . . . . . . . . . . . . 182 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 . . . . . . 188 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 C.20. Since draft-ietf-httpbis-semantics-18 . . . . . . . . . . 239 411 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 240 412 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 413 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 252 415 1. Introduction 417 1.1. Purpose 419 The Hypertext Transfer Protocol (HTTP) is a family of stateless, 420 application-level, request/response protocols that share a generic 421 interface, extensible semantics, and self-descriptive messages to 422 enable flexible interaction with network-based hypertext information 423 systems. 425 HTTP hides the details of how a service is implemented by presenting 426 a uniform interface to clients that is independent of the types of 427 resources provided. Likewise, servers do not need to be aware of 428 each client's purpose: a request can be considered in isolation 429 rather than being associated with a specific type of client or a 430 predetermined sequence of application steps. This allows general- 431 purpose implementations to be used effectively in many different 432 contexts, reduces interaction complexity, and enables independent 433 evolution over time. 435 HTTP is also designed for use as an intermediation protocol, wherein 436 proxies and gateways can translate non-HTTP information systems into 437 a more generic interface. 439 One consequence of this flexibility is that the protocol cannot be 440 defined in terms of what occurs behind the interface. Instead, we 441 are limited to defining the syntax of communication, the intent of 442 received communication, and the expected behavior of recipients. If 443 the communication is considered in isolation, then successful actions 444 ought to be reflected in corresponding changes to the observable 445 interface provided by servers. However, since multiple clients might 446 act in parallel and perhaps at cross-purposes, we cannot require that 447 such changes be observable beyond the scope of a single response. 449 1.2. History and Evolution 451 HTTP has been the primary information transfer protocol for the World 452 Wide Web since its introduction in 1990. It began as a trivial 453 mechanism for low-latency requests, with a single method (GET) to 454 request transfer of a presumed hypertext document identified by a 455 given pathname. As the Web grew, HTTP was extended to enclose 456 requests and responses within messages, transfer arbitrary data 457 formats using MIME-like media types, and route requests through 458 intermediaries. These protocols were eventually defined as HTTP/0.9 459 and HTTP/1.0 (see [HTTP/1.0]). 461 HTTP/1.1 was designed to refine the protocol's features while 462 retaining compatibility with the existing text-based messaging 463 syntax, improving its interoperability, scalability, and robustness 464 across the Internet. This included length-based data delimiters for 465 both fixed and dynamic (chunked) content, a consistent framework for 466 content negotiation, opaque validators for conditional requests, 467 cache controls for better cache consistency, range requests for 468 partial updates, and default persistent connections. HTTP/1.1 was 469 introduced in 1995 and published on the standards track in 1997 470 [RFC2068], revised in 1999 [RFC2616], and revised again in 2014 471 ([RFC7230] - [RFC7235]). 473 HTTP/2 ([HTTP/2]) introduced a multiplexed session layer on top of 474 the existing TLS and TCP protocols for exchanging concurrent HTTP 475 messages with efficient field compression and server push. HTTP/3 476 ([HTTP/3]) provides greater independence for concurrent messages by 477 using QUIC as a secure multiplexed transport over UDP instead of TCP. 479 All three major versions of HTTP rely on the semantics defined by 480 this document. They have not obsoleted each other because each one 481 has specific benefits and limitations depending on the context of 482 use. Implementations are expected to choose the most appropriate 483 transport and messaging syntax for their particular context. 485 This revision of HTTP separates the definition of semantics (this 486 document) and caching ([CACHING]) from the current HTTP/1.1 messaging 487 syntax ([HTTP/1.1]) to allow each major protocol version to progress 488 independently while referring to the same core semantics. 490 1.3. Core Semantics 492 HTTP provides a uniform interface for interacting with a resource 493 (Section 3.1) - regardless of its type, nature, or implementation - 494 by sending messages that manipulate or transfer representations 495 (Section 3.2). 497 Each message is either a request or a response. A client constructs 498 request messages that communicate its intentions and routes those 499 messages toward an identified origin server. A server listens for 500 requests, parses each message received, interprets the message 501 semantics in relation to the identified target resource, and responds 502 to that request with one or more response messages. The client 503 examines received responses to see if its intentions were carried 504 out, determining what to do next based on the status codes and 505 content received. 507 HTTP semantics include the intentions defined by each request method 508 (Section 9), extensions to those semantics that might be described in 509 request header fields, status codes that describe the response 510 (Section 15), and other control data and resource metadata that might 511 be given in response fields. 513 Semantics also include representation metadata that describe how 514 content is intended to be interpreted by a recipient, request header 515 fields that might influence content selection, and the various 516 selection algorithms that are collectively referred to as _content 517 negotiation_ (Section 12). 519 1.4. Specifications Obsoleted by this Document 521 This document obsoletes the following specifications: 523 +============================================+===========+=========+ 524 | Title | Reference | Changes | 525 +============================================+===========+=========+ 526 | HTTP Over TLS | [RFC2818] | B.1 | 527 +--------------------------------------------+-----------+---------+ 528 | HTTP/1.1 Message Syntax and Routing [*] | [RFC7230] | B.2 | 529 +--------------------------------------------+-----------+---------+ 530 | HTTP/1.1 Semantics and Content | [RFC7231] | B.3 | 531 +--------------------------------------------+-----------+---------+ 532 | HTTP/1.1 Conditional Requests | [RFC7232] | B.4 | 533 +--------------------------------------------+-----------+---------+ 534 | HTTP/1.1 Range Requests | [RFC7233] | B.5 | 535 +--------------------------------------------+-----------+---------+ 536 | HTTP/1.1 Authentication | [RFC7235] | B.6 | 537 +--------------------------------------------+-----------+---------+ 538 | HTTP Status Code 308 (Permanent Redirect) | [RFC7538] | B.7 | 539 +--------------------------------------------+-----------+---------+ 540 | HTTP Authentication-Info and Proxy- | [RFC7615] | B.8 | 541 | Authentication-Info Response Header Fields | | | 542 +--------------------------------------------+-----------+---------+ 543 | HTTP Client-Initiated Content-Encoding | [RFC7694] | B.9 | 544 +--------------------------------------------+-----------+---------+ 546 Table 1 548 [*] This document only obsoletes the portions of RFC 7230 that are 549 independent of the HTTP/1.1 messaging syntax and connection 550 management; the remaining bits of RFC 7230 are obsoleted by 551 "HTTP/1.1" [HTTP/1.1]. 553 2. Conformance 555 2.1. Syntax Notation 557 This specification uses the Augmented Backus-Naur Form (ABNF) 558 notation of [RFC5234], extended with the notation for case- 559 sensitivity in strings defined in [RFC7405]. 561 It also uses a list extension, defined in Section 5.6.1, that allows 562 for compact definition of comma-separated lists using a "#" operator 563 (similar to how the "*" operator indicates repetition). Appendix A 564 shows the collected grammar with all list operators expanded to 565 standard ABNF notation. 567 As a convention, ABNF rule names prefixed with "obs-" denote 568 "obsolete" grammar rules that appear for historical reasons. 570 The following core rules are included by reference, as defined in 571 Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), 572 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 573 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF 574 (line feed), OCTET (any 8-bit sequence of data), SP (space), and 575 VCHAR (any visible US-ASCII character). 577 Section 5.6 defines some generic syntactic components for field 578 values. 580 This specification uses the terms "character", "character encoding 581 scheme", "charset", and "protocol element" as they are defined in 582 [RFC6365]. 584 2.2. Requirements Notation 586 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 587 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 588 "OPTIONAL" in this document are to be interpreted as described in BCP 589 14 [RFC2119] [RFC8174] when, and only when, they appear in all 590 capitals, as shown here. 592 This specification targets conformance criteria according to the role 593 of a participant in HTTP communication. Hence, requirements are 594 placed on senders, recipients, clients, servers, user agents, 595 intermediaries, origin servers, proxies, gateways, or caches, 596 depending on what behavior is being constrained by the requirement. 597 Additional requirements are placed on implementations, resource 598 owners, and protocol element registrations when they apply beyond the 599 scope of a single communication. 601 The verb "generate" is used instead of "send" where a requirement 602 applies only to implementations that create the protocol element, 603 rather than an implementation that forwards a received element 604 downstream. 606 An implementation is considered conformant if it complies with all of 607 the requirements associated with the roles it partakes in HTTP. 609 A sender MUST NOT generate protocol elements that do not match the 610 grammar defined by the corresponding ABNF rules. Within a given 611 message, a sender MUST NOT generate protocol elements or syntax 612 alternatives that are only allowed to be generated by participants in 613 other roles (i.e., a role that the sender does not have for that 614 message). 616 Conformance to HTTP includes both conformance to the particular 617 messaging syntax of the protocol version in use and conformance to 618 the semantics of protocol elements sent. For example, a client that 619 claims conformance to HTTP/1.1 but fails to recognize the features 620 required of HTTP/1.1 recipients will fail to interoperate with 621 servers that adjust their responses in accordance with those claims. 622 Features that reflect user choices, such as content negotiation and 623 user-selected extensions, can impact application behavior beyond the 624 protocol stream; sending protocol elements that inaccurately reflect 625 a user's choices will confuse the user and inhibit choice. 627 When an implementation fails semantic conformance, recipients of that 628 implementation's messages will eventually develop workarounds to 629 adjust their behavior accordingly. A recipient MAY employ such 630 workarounds while remaining conformant to this protocol if the 631 workarounds are limited to the implementations at fault. For 632 example, servers often scan portions of the User-Agent field value, 633 and user agents often scan the Server field value, to adjust their 634 own behavior with respect to known bugs or poorly chosen defaults. 636 2.3. Length Requirements 638 A recipient SHOULD parse a received protocol element defensively, 639 with only marginal expectations that the element will conform to its 640 ABNF grammar and fit within a reasonable buffer size. 642 HTTP does not have specific length limitations for many of its 643 protocol elements because the lengths that might be appropriate will 644 vary widely, depending on the deployment context and purpose of the 645 implementation. Hence, interoperability between senders and 646 recipients depends on shared expectations regarding what is a 647 reasonable length for each protocol element. Furthermore, what is 648 commonly understood to be a reasonable length for some protocol 649 elements has changed over the course of the past two decades of HTTP 650 use and is expected to continue changing in the future. 652 At a minimum, a recipient MUST be able to parse and process protocol 653 element lengths that are at least as long as the values that it 654 generates for those same protocol elements in other messages. For 655 example, an origin server that publishes very long URI references to 656 its own resources needs to be able to parse and process those same 657 references when received as a target URI. 659 Many received protocol elements are only parsed to the extent 660 necessary to identify and forward that element downstream. For 661 example, an intermediary might parse a received field into its field 662 name and field value components, but then forward the field without 663 further parsing inside the field value. 665 2.4. Error Handling 667 A recipient MUST interpret a received protocol element according to 668 the semantics defined for it by this specification, including 669 extensions to this specification, unless the recipient has determined 670 (through experience or configuration) that the sender incorrectly 671 implements what is implied by those semantics. For example, an 672 origin server might disregard the contents of a received 673 Accept-Encoding header field if inspection of the User-Agent header 674 field indicates a specific implementation version that is known to 675 fail on receipt of certain content codings. 677 Unless noted otherwise, a recipient MAY attempt to recover a usable 678 protocol element from an invalid construct. HTTP does not define 679 specific error handling mechanisms except when they have a direct 680 impact on security, since different applications of the protocol 681 require different error handling strategies. For example, a Web 682 browser might wish to transparently recover from a response where the 683 Location header field doesn't parse according to the ABNF, whereas a 684 systems control client might consider any form of error recovery to 685 be dangerous. 687 Some requests can be automatically retried by a client in the event 688 of an underlying connection failure, as described in Section 9.2.2. 690 2.5. Protocol Version 692 HTTP's version number consists of two decimal digits separated by a 693 "." (period or decimal point). The first digit ("major version") 694 indicates the messaging syntax, whereas the second digit ("minor 695 version") indicates the highest minor version within that major 696 version to which the sender is conformant (able to understand for 697 future communication). 699 While HTTP's core semantics don't change between protocol versions, 700 the expression of them "on the wire" can change, and so the HTTP 701 version number changes when incompatible changes are made to the wire 702 format. Additionally, HTTP allows incremental, backwards-compatible 703 changes to be made to the protocol without changing its version 704 through the use of defined extension points (Section 16). 706 The protocol version as a whole indicates the sender's conformance 707 with the set of requirements laid out in that version's corresponding 708 specification of HTTP. For example, the version "HTTP/1.1" is 709 defined by the combined specifications of this document, "HTTP 710 Caching" [CACHING], and "HTTP/1.1" [HTTP/1.1]. 712 HTTP's major version number is incremented when an incompatible 713 message syntax is introduced. The minor number is incremented when 714 changes made to the protocol have the effect of adding to the message 715 semantics or implying additional capabilities of the sender. 717 The minor version advertises the sender's communication capabilities 718 even when the sender is only using a backwards-compatible subset of 719 the protocol, thereby letting the recipient know that more advanced 720 features can be used in response (by servers) or in future requests 721 (by clients). 723 When a major version of HTTP does not define any minor versions, the 724 minor version "0" is implied. The "0" is used when referring to that 725 protocol within elements that require a minor version identifier. 727 3. Terminology and Core Concepts 729 HTTP was created for the World Wide Web (WWW) architecture and has 730 evolved over time to support the scalability needs of a worldwide 731 hypertext system. Much of that architecture is reflected in the 732 terminology used to define HTTP. 734 3.1. Resources 736 The target of an HTTP request is called a _resource_. HTTP does not 737 limit the nature of a resource; it merely defines an interface that 738 might be used to interact with resources. Most resources are 739 identified by a Uniform Resource Identifier (URI), as described in 740 Section 4. 742 One design goal of HTTP is to separate resource identification from 743 request semantics, which is made possible by vesting the request 744 semantics in the request method (Section 9) and a few request- 745 modifying header fields. A resource cannot treat a request in a 746 manner inconsistent with the semantics of the method of the request. 747 For example, though the URI of a resource might imply semantics that 748 are not safe, a client can expect the resource to avoid actions that 749 are unsafe when processing a request with a safe method (see 750 Section 9.2.1). 752 HTTP relies upon the Uniform Resource Identifier (URI) standard [URI] 753 to indicate the target resource (Section 7.1) and relationships 754 between resources. 756 3.2. Representations 758 A _representation_ is information that is intended to reflect a past, 759 current, or desired state of a given resource, in a format that can 760 be readily communicated via the protocol. A representation consists 761 of a set of representation metadata and a potentially unbounded 762 stream of representation data (Section 8). 764 HTTP allows "information hiding" behind its uniform interface by 765 defining communication with respect to a transferable representation 766 of the resource state, rather than transferring the resource itself. 767 This allows the resource identified by a URI to be anything, 768 including temporal functions like "the current weather in Laguna 769 Beach", while potentially providing information that represents that 770 resource at the time a message is generated [REST]. 772 The uniform interface is similar to a window through which one can 773 observe and act upon a thing only through the communication of 774 messages to an independent actor on the other side. A shared 775 abstraction is needed to represent ("take the place of") the current 776 or desired state of that thing in our communications. When a 777 representation is hypertext, it can provide both a representation of 778 the resource state and processing instructions that help guide the 779 recipient's future interactions. 781 A target resource might be provided with, or be capable of 782 generating, multiple representations that are each intended to 783 reflect the resource's current state. An algorithm, usually based on 784 content negotiation (Section 12), would be used to select one of 785 those representations as being most applicable to a given request. 786 This _selected representation_ provides the data and metadata for 787 evaluating conditional requests (Section 13) and constructing the 788 content for 200 (OK), 206 (Partial Content), and 304 (Not Modified) 789 responses to GET (Section 9.3.1). 791 3.3. Connections, Clients and Servers 793 HTTP is a client/server protocol that operates over a reliable 794 transport- or session-layer _connection_. 796 An HTTP _client_ is a program that establishes a connection to a 797 server for the purpose of sending one or more HTTP requests. An HTTP 798 _server_ is a program that accepts connections in order to service 799 HTTP requests by sending HTTP responses. 801 The terms "client" and "server" refer only to the roles that these 802 programs perform for a particular connection. The same program might 803 act as a client on some connections and a server on others. 805 HTTP is defined as a stateless protocol, meaning that each request 806 message's semantics can be understood in isolation, and that the 807 relationship between connections and messages on them has no impact 808 on the interpretation of those messages. For example, a CONNECT 809 request (Section 9.3.6) or a request with the Upgrade header field 810 (Section 7.8) can occur at any time, not just in the first message on 811 a connection. Many implementations depend on HTTP's stateless design 812 in order to reuse proxied connections or dynamically load balance 813 requests across multiple servers. 815 As a result, a server MUST NOT assume that two requests on the same 816 connection are from the same user agent unless the connection is 817 secured and specific to that agent. Some non-standard HTTP 818 extensions (e.g., [RFC4559]) have been known to violate this 819 requirement, resulting in security and interoperability problems. 821 3.4. Messages 823 HTTP is a stateless request/response protocol for exchanging 824 _messages_ across a connection. The terms _sender_ and _recipient_ 825 refer to any implementation that sends or receives a given message, 826 respectively. 828 A client sends requests to a server in the form of a _request_ 829 message with a method (Section 9) and request target (Section 7.1). 830 The request might also contain header fields (Section 6.3) for 831 request modifiers, client information, and representation metadata, 832 content (Section 6.4) intended for processing in accordance with the 833 method, and trailer fields (Section 6.5) to communicate information 834 collected while sending the content. 836 A server responds to a client's request by sending one or more 837 _response_ messages, each including a status code (Section 15). The 838 response might also contain header fields for server information, 839 resource metadata, and representation metadata, content to be 840 interpreted in accordance with the status code, and trailer fields to 841 communicate information collected while sending the content. 843 3.5. User Agents 845 The term _user agent_ refers to any of the various client programs 846 that initiate a request. 848 The most familiar form of user agent is the general-purpose Web 849 browser, but that's only a small percentage of implementations. 850 Other common user agents include spiders (web-traversing robots), 851 command-line tools, billboard screens, household appliances, scales, 852 light bulbs, firmware update scripts, mobile apps, and communication 853 devices in a multitude of shapes and sizes. 855 Being a user agent does not imply that there is a human user directly 856 interacting with the software agent at the time of a request. In 857 many cases, a user agent is installed or configured to run in the 858 background and save its results for later inspection (or save only a 859 subset of those results that might be interesting or erroneous). 860 Spiders, for example, are typically given a start URI and configured 861 to follow certain behavior while crawling the Web as a hypertext 862 graph. 864 Many user agents cannot, or choose not to, make interactive 865 suggestions to their user or provide adequate warning for security or 866 privacy concerns. In the few cases where this specification requires 867 reporting of errors to the user, it is acceptable for such reporting 868 to only be observable in an error console or log file. Likewise, 869 requirements that an automated action be confirmed by the user before 870 proceeding might be met via advance configuration choices, run-time 871 options, or simple avoidance of the unsafe action; confirmation does 872 not imply any specific user interface or interruption of normal 873 processing if the user has already made that choice. 875 3.6. Origin Server 877 The term _origin server_ refers to a program that can originate 878 authoritative responses for a given target resource. 880 The most familiar form of origin server are large public websites. 881 However, like user agents being equated with browsers, it is easy to 882 be misled into thinking that all origin servers are alike. Common 883 origin servers also include home automation units, configurable 884 networking components, office machines, autonomous robots, news 885 feeds, traffic cameras, real-time ad selectors, and video-on-demand 886 platforms. 888 Most HTTP communication consists of a retrieval request (GET) for a 889 representation of some resource identified by a URI. In the simplest 890 case, this might be accomplished via a single bidirectional 891 connection (===) between the user agent (UA) and the origin server 892 (O). 894 request > 895 UA ======================================= O 896 < response 898 Figure 1 900 3.7. Intermediaries 902 HTTP enables the use of intermediaries to satisfy requests through a 903 chain of connections. There are three common forms of HTTP 904 _intermediary_: proxy, gateway, and tunnel. In some cases, a single 905 intermediary might act as an origin server, proxy, gateway, or 906 tunnel, switching behavior based on the nature of each request. 908 > > > > 909 UA =========== A =========== B =========== C =========== O 910 < < < < 912 Figure 2 914 The figure above shows three intermediaries (A, B, and C) between the 915 user agent and origin server. A request or response message that 916 travels the whole chain will pass through four separate connections. 917 Some HTTP communication options might apply only to the connection 918 with the nearest, non-tunnel neighbor, only to the endpoints of the 919 chain, or to all connections along the chain. Although the diagram 920 is linear, each participant might be engaged in multiple, 921 simultaneous communications. For example, B might be receiving 922 requests from many clients other than A, and/or forwarding requests 923 to servers other than C, at the same time that it is handling A's 924 request. Likewise, later requests might be sent through a different 925 path of connections, often based on dynamic configuration for load 926 balancing. 928 The terms _upstream_ and _downstream_ are used to describe 929 directional requirements in relation to the message flow: all 930 messages flow from upstream to downstream. The terms "inbound" and 931 "outbound" are used to describe directional requirements in relation 932 to the request route: _inbound_ means toward the origin server and 933 _outbound_ means toward the user agent. 935 A _proxy_ is a message-forwarding agent that is chosen by the client, 936 usually via local configuration rules, to receive requests for some 937 type(s) of absolute URI and attempt to satisfy those requests via 938 translation through the HTTP interface. Some translations are 939 minimal, such as for proxy requests for "http" URIs, whereas other 940 requests might require translation to and from entirely different 941 application-level protocols. Proxies are often used to group an 942 organization's HTTP requests through a common intermediary for the 943 sake of security services, annotation services, or shared caching. 944 Some proxies are designed to apply transformations to selected 945 messages or content while they are being forwarded, as described in 946 Section 7.7. 948 A _gateway_ (a.k.a. _reverse proxy_) is an intermediary that acts as 949 an origin server for the outbound connection but translates received 950 requests and forwards them inbound to another server or servers. 951 Gateways are often used to encapsulate legacy or untrusted 952 information services, to improve server performance through 953 _accelerator_ caching, and to enable partitioning or load balancing 954 of HTTP services across multiple machines. 956 All HTTP requirements applicable to an origin server also apply to 957 the outbound communication of a gateway. A gateway communicates with 958 inbound servers using any protocol that it desires, including private 959 extensions to HTTP that are outside the scope of this specification. 960 However, an HTTP-to-HTTP gateway that wishes to interoperate with 961 third-party HTTP servers needs to conform to user agent requirements 962 on the gateway's inbound connection. 964 A _tunnel_ acts as a blind relay between two connections without 965 changing the messages. Once active, a tunnel is not considered a 966 party to the HTTP communication, though the tunnel might have been 967 initiated by an HTTP request. A tunnel ceases to exist when both 968 ends of the relayed connection are closed. Tunnels are used to 969 extend a virtual connection through an intermediary, such as when 970 Transport Layer Security (TLS, [TLS13]) is used to establish 971 confidential communication through a shared firewall proxy. 973 The above categories for intermediary only consider those acting as 974 participants in the HTTP communication. There are also 975 intermediaries that can act on lower layers of the network protocol 976 stack, filtering or redirecting HTTP traffic without the knowledge or 977 permission of message senders. Network intermediaries are 978 indistinguishable (at a protocol level) from an on-path attacker, 979 often introducing security flaws or interoperability problems due to 980 mistakenly violating HTTP semantics. 982 For example, an _interception proxy_ [RFC3040] (also commonly known 983 as a _transparent proxy_ [RFC1919]) differs from an HTTP proxy 984 because it is not chosen by the client. Instead, an interception 985 proxy filters or redirects outgoing TCP port 80 packets (and 986 occasionally other common port traffic). Interception proxies are 987 commonly found on public network access points, as a means of 988 enforcing account subscription prior to allowing use of non-local 989 Internet services, and within corporate firewalls to enforce network 990 usage policies. 992 3.8. Caches 994 A _cache_ is a local store of previous response messages and the 995 subsystem that controls its message storage, retrieval, and deletion. 996 A cache stores cacheable responses in order to reduce the response 997 time and network bandwidth consumption on future, equivalent 998 requests. Any client or server MAY employ a cache, though a cache 999 cannot be used while acting as a tunnel. 1001 The effect of a cache is that the request/response chain is shortened 1002 if one of the participants along the chain has a cached response 1003 applicable to that request. The following illustrates the resulting 1004 chain if B has a cached copy of an earlier response from O (via C) 1005 for a request that has not been cached by UA or A. 1007 > > 1008 UA =========== A =========== B - - - - - - C - - - - - - O 1009 < < 1011 Figure 3 1013 A response is _cacheable_ if a cache is allowed to store a copy of 1014 the response message for use in answering subsequent requests. Even 1015 when a response is cacheable, there might be additional constraints 1016 placed by the client or by the origin server on when that cached 1017 response can be used for a particular request. HTTP requirements for 1018 cache behavior and cacheable responses are defined in [CACHING]. 1020 There is a wide variety of architectures and configurations of caches 1021 deployed across the World Wide Web and inside large organizations. 1022 These include national hierarchies of proxy caches to save bandwidth 1023 and reduce latency, Content Delivery Networks that use gateway 1024 caching to optimise regional and global distribution of popular 1025 sites, collaborative systems that broadcast or multicast cache 1026 entries, archives of pre-fetched cache entries for use in off-line or 1027 high-latency environments, and so on. 1029 3.9. Example Message Exchange 1031 The following example illustrates a typical HTTP/1.1 message exchange 1032 for a GET request (Section 9.3.1) on the URI "http://www.example.com/ 1033 hello.txt": 1035 Client request: 1037 GET /hello.txt HTTP/1.1 1038 User-Agent: curl/7.64.1 1039 Host: www.example.com 1040 Accept-Language: en, mi 1042 Server response: 1044 HTTP/1.1 200 OK 1045 Date: Mon, 27 Jul 2009 12:28:53 GMT 1046 Server: Apache 1047 Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT 1048 ETag: "34aa387-d-1568eb00" 1049 Accept-Ranges: bytes 1050 Content-Length: 51 1051 Vary: Accept-Encoding 1052 Content-Type: text/plain 1054 Hello World! My content includes a trailing CRLF. 1056 4. Identifiers in HTTP 1058 Uniform Resource Identifiers (URIs) [URI] are used throughout HTTP as 1059 the means for identifying resources (Section 3.1). 1061 4.1. URI References 1063 URI references are used to target requests, indicate redirects, and 1064 define relationships. 1066 The definitions of "URI-reference", "absolute-URI", "relative-part", 1067 "authority", "port", "host", "path-abempty", "segment", and "query" 1068 are adopted from the URI generic syntax. An "absolute-path" rule is 1069 defined for protocol elements that can contain a non-empty path 1070 component. (This rule differs slightly from the path-abempty rule of 1071 RFC 3986, which allows for an empty path, and path-absolute rule, 1072 which does not allow paths that begin with "//".) A "partial-URI" 1073 rule is defined for protocol elements that can contain a relative URI 1074 but not a fragment component. 1076 URI-reference = 1077 absolute-URI = 1078 relative-part = 1079 authority = 1080 uri-host = 1081 port = 1082 path-abempty = 1083 segment = 1084 query = 1086 absolute-path = 1*( "/" segment ) 1087 partial-URI = relative-part [ "?" query ] 1089 Each protocol element in HTTP that allows a URI reference will 1090 indicate in its ABNF production whether the element allows any form 1091 of reference (URI-reference), only a URI in absolute form (absolute- 1092 URI), only the path and optional query components (partial-URI), or 1093 some combination of the above. Unless otherwise indicated, URI 1094 references are parsed relative to the target URI (Section 7.1). 1096 It is RECOMMENDED that all senders and recipients support, at a 1097 minimum, URIs with lengths of 8000 octets in protocol elements. Note 1098 that this implies some structures and on-wire representations (for 1099 example, the request line in HTTP/1.1) will necessarily be larger in 1100 some cases. 1102 4.2. HTTP-Related URI Schemes 1104 IANA maintains the registry of URI Schemes [BCP35] at 1105 . Although requests 1106 might target any URI scheme, the following schemes are inherent to 1107 HTTP servers: 1109 +============+====================================+=======+ 1110 | URI Scheme | Description | Ref. | 1111 +============+====================================+=======+ 1112 | http | Hypertext Transfer Protocol | 4.2.1 | 1113 +------------+------------------------------------+-------+ 1114 | https | Hypertext Transfer Protocol Secure | 4.2.2 | 1115 +------------+------------------------------------+-------+ 1117 Table 2 1119 Note that the presence of an "http" or "https" URI does not imply 1120 that there is always an HTTP server at the identified origin 1121 listening for connections. Anyone can mint a URI, whether or not a 1122 server exists and whether or not that server currently maps that 1123 identifier to a resource. The delegated nature of registered names 1124 and IP addresses creates a federated namespace whether or not an HTTP 1125 server is present. 1127 4.2.1. http URI Scheme 1129 The "http" URI scheme is hereby defined for minting identifiers 1130 within the hierarchical namespace governed by a potential HTTP origin 1131 server listening for TCP ([TCP]) connections on a given port. 1133 http-URI = "http" "://" authority path-abempty [ "?" query ] 1135 The origin server for an "http" URI is identified by the authority 1136 component, which includes a host identifier ([URI], Section 3.2.2) 1137 and optional port number ([URI], Section 3.2.3). If the port 1138 subcomponent is empty or not given, TCP port 80 (the reserved port 1139 for WWW services) is the default. The origin determines who has the 1140 right to respond authoritatively to requests that target the 1141 identified resource, as defined in Section 4.3.2. 1143 A sender MUST NOT generate an "http" URI with an empty host 1144 identifier. A recipient that processes such a URI reference MUST 1145 reject it as invalid. 1147 The hierarchical path component and optional query component identify 1148 the target resource within that origin server's name space. 1150 4.2.2. https URI Scheme 1152 The "https" URI scheme is hereby defined for minting identifiers 1153 within the hierarchical namespace governed by a potential origin 1154 server listening for TCP connections on a given port and capable of 1155 establishing a TLS ([TLS13]) connection that has been secured for 1156 HTTP communication. In this context, _secured_ specifically means 1157 that the server has been authenticated as acting on behalf of the 1158 identified authority and all HTTP communication with that server has 1159 confidentiality and integrity protection that is acceptable to both 1160 client and server. 1162 https-URI = "https" "://" authority path-abempty [ "?" query ] 1164 The origin server for an "https" URI is identified by the authority 1165 component, which includes a host identifier ([URI], Section 3.2.2) 1166 and optional port number ([URI], Section 3.2.3). If the port 1167 subcomponent is empty or not given, TCP port 443 (the reserved port 1168 for HTTP over TLS) is the default. The origin determines who has the 1169 right to respond authoritatively to requests that target the 1170 identified resource, as defined in Section 4.3.3. 1172 A sender MUST NOT generate an "https" URI with an empty host 1173 identifier. A recipient that processes such a URI reference MUST 1174 reject it as invalid. 1176 The hierarchical path component and optional query component identify 1177 the target resource within that origin server's name space. 1179 A client MUST ensure that its HTTP requests for an "https" resource 1180 are secured, prior to being communicated, and that it only accepts 1181 secured responses to those requests. Note that the definition of 1182 what cryptographic mechanisms are acceptable to client and server are 1183 usually negotiated and can change over time. 1185 Resources made available via the "https" scheme have no shared 1186 identity with the "http" scheme. They are distinct origins with 1187 separate namespaces. However, extensions to HTTP that are defined as 1188 applying to all origins with the same host, such as the Cookie 1189 protocol [COOKIE], allow information set by one service to impact 1190 communication with other services within a matching group of host 1191 domains. Such extensions ought to be designed with great care to 1192 prevent information obtained from a secured connection being 1193 inadvertently exchanged within an unsecured context. 1195 4.2.3. http(s) Normalization and Comparison 1197 The "http" and "https" URI are normalized and compared according to 1198 the methods defined in Section 6 of [URI], using the defaults 1199 described above for each scheme. 1201 HTTP does not require use of a specific method for determining 1202 equivalence. For example, a cache key might be compared as a simple 1203 string, after syntax-based normalization, or after scheme-based 1204 normalization. 1206 Scheme-based normalization (Section 6.2.3 of [URI]) of "http" and 1207 "https" URIs involves the following additional rules: 1209 * If the port is equal to the default port for a scheme, the normal 1210 form is to omit the port subcomponent. 1212 * When not being used as the target of an OPTIONS request, an empty 1213 path component is equivalent to an absolute path of "/", so the 1214 normal form is to provide a path of "/" instead. 1216 * The scheme and host are case-insensitive and normally provided in 1217 lowercase; all other components are compared in a case-sensitive 1218 manner. 1220 * Characters other than those in the "reserved" set are equivalent 1221 to their percent-encoded octets: the normal form is to not encode 1222 them (see Sections 2.1 and 2.2 of [URI]). 1224 For example, the following three URIs are equivalent: 1226 http://example.com:80/~smith/home.html 1227 http://EXAMPLE.com/%7Esmith/home.html 1228 http://EXAMPLE.com:/%7esmith/home.html 1230 Two HTTP URIs that are equivalent after normalization (using any 1231 method) can be assumed to identify the same resource, and any HTTP 1232 component MAY perform normalization. As a result, distinct resources 1233 SHOULD NOT be identified by HTTP URIs that are equivalent after 1234 normalization (using any method defined in Section 6.2 of [URI]). 1236 4.2.4. Deprecation of userinfo in http(s) URIs 1238 The URI generic syntax for authority also includes a userinfo 1239 subcomponent ([URI], Section 3.2.1) for including user authentication 1240 information in the URI. In that subcomponent, the use of the format 1241 "user:password" is deprecated. 1243 Some implementations make use of the userinfo component for internal 1244 configuration of authentication information, such as within command 1245 invocation options, configuration files, or bookmark lists, even 1246 though such usage might expose a user identifier or password. 1248 A sender MUST NOT generate the userinfo subcomponent (and its "@" 1249 delimiter) when an "http" or "https" URI reference is generated 1250 within a message as a target URI or field value. 1252 Before making use of an "http" or "https" URI reference received from 1253 an untrusted source, a recipient SHOULD parse for userinfo and treat 1254 its presence as an error; it is likely being used to obscure the 1255 authority for the sake of phishing attacks. 1257 4.2.5. http(s) References with Fragment Identifiers 1259 Fragment identifiers allow for indirect identification of a secondary 1260 resource, independent of the URI scheme, as defined in Section 3.5 of 1261 [URI]. Some protocol elements that refer to a URI allow inclusion of 1262 a fragment, while others do not. They are distinguished by use of 1263 the ABNF rule for elements where fragment is allowed; otherwise, a 1264 specific rule that excludes fragments is used. 1266 | *Note:* The fragment identifier component is not part of the 1267 | scheme definition for a URI scheme (see Section 4.3 of [URI]), 1268 | thus does not appear in the ABNF definitions for the "http" and 1269 | "https" URI schemes above. 1271 4.3. Authoritative Access 1273 Authoritative access refers to dereferencing a given identifier, for 1274 the sake of access to the identified resource, in a way that the 1275 client believes is authoritative (controlled by the resource owner). 1276 The process for determining whether access is granted is defined by 1277 the URI scheme and often uses data within the URI components, such as 1278 the authority component when the generic syntax is used. However, 1279 authoritative access is not limited to the identified mechanism. 1281 Section 4.3.1 defines the concept of an origin as an aid to such 1282 uses, and the subsequent subsections explain how to establish that a 1283 peer has the authority to represent an origin. 1285 See Section 17.1 for security considerations related to establishing 1286 authority. 1288 4.3.1. URI Origin 1290 The _origin_ for a given URI is the triple of scheme, host, and port 1291 after normalizing the scheme and host to lowercase and normalizing 1292 the port to remove any leading zeros. If port is elided from the 1293 URI, the default port for that scheme is used. For example, the URI 1295 https://Example.Com/happy.js 1297 would have the origin 1299 { "https", "example.com", "443" } 1301 which can also be described as the normalized URI prefix with port 1302 always present: 1304 https://example.com:443 1306 Each origin defines its own namespace and controls how identifiers 1307 within that namespace are mapped to resources. In turn, how the 1308 origin responds to valid requests, consistently over time, determines 1309 the semantics that users will associate with a URI, and the 1310 usefulness of those semantics is what ultimately transforms these 1311 mechanisms into a "resource" for users to reference and access in the 1312 future. 1314 Two origins are distinct if they differ in scheme, host, or port. 1315 Even when it can be verified that the same entity controls two 1316 distinct origins, the two namespaces under those origins are distinct 1317 unless explicitly aliased by a server authoritative for that origin. 1319 Origin is also used within HTML and related Web protocols, beyond the 1320 scope of this document, as described in [RFC6454]. 1322 4.3.2. http origins 1324 Although HTTP is independent of the transport protocol, the "http" 1325 scheme (Section 4.2.1) is specific to associating authority with 1326 whomever controls the origin server listening for TCP connections on 1327 the indicated port of whatever host is identified within the 1328 authority component. This is a very weak sense of authority because 1329 it depends on both client-specific name resolution mechanisms and 1330 communication that might not be secured from an on-path attacker. 1331 Nevertheless, it is a sufficient minimum for binding "http" 1332 identifiers to an origin server for consistent resolution within a 1333 trusted environment. 1335 If the host identifier is provided as an IP address, the origin 1336 server is the listener (if any) on the indicated TCP port at that IP 1337 address. If host is a registered name, the registered name is an 1338 indirect identifier for use with a name resolution service, such as 1339 DNS, to find an address for an appropriate origin server. 1341 When an "http" URI is used within a context that calls for access to 1342 the indicated resource, a client MAY attempt access by resolving the 1343 host identifier to an IP address, establishing a TCP connection to 1344 that address on the indicated port, and sending over that connection 1345 an HTTP request message containing a request target that matches the 1346 client's target URI (Section 7.1). 1348 If the server responds to such a request with a non-interim HTTP 1349 response message, as described in Section 15, then that response is 1350 considered an authoritative answer to the client's request. 1352 Note, however, that the above is not the only means for obtaining an 1353 authoritative response, nor does it imply that an authoritative 1354 response is always necessary (see [CACHING]). For example, the Alt- 1355 Svc header field [ALTSVC] allows an origin server to identify other 1356 services that are also authoritative for that origin. Access to 1357 "http" identified resources might also be provided by protocols 1358 outside the scope of this document. 1360 4.3.3. https origins 1362 The "https" scheme (Section 4.2.2) associates authority based on the 1363 ability of a server to use the private key corresponding to a 1364 certificate that the client considers to be trustworthy for the 1365 identified origin server. The client usually relies upon a chain of 1366 trust, conveyed from some prearranged or configured trust anchor, to 1367 deem a certificate trustworthy (Section 4.3.4). 1369 In HTTP/1.1 and earlier, a client will only attribute authority to a 1370 server when they are communicating over a successfully established 1371 and secured connection specifically to that URI origin's host. The 1372 connection establishment and certificate verification are used as 1373 proof of authority. 1375 In HTTP/2 and HTTP/3, a client will attribute authority to a server 1376 when they are communicating over a successfully established and 1377 secured connection if the URI origin's host matches any of the hosts 1378 present in the server's certificate and the client believes that it 1379 could open a connection to that host for that URI. In practice, a 1380 client will make a DNS query to check that the origin's host contains 1381 the same server IP address as the established connection. This 1382 restriction can be removed by the origin server sending an equivalent 1383 ORIGIN frame [RFC8336]. 1385 The request target's host and port value are passed within each HTTP 1386 request, identifying the origin and distinguishing it from other 1387 namespaces that might be controlled by the same server (Section 7.2). 1388 It is the origin's responsibility to ensure that any services 1389 provided with control over its certificate's private key are equally 1390 responsible for managing the corresponding "https" namespaces, or at 1391 least prepared to reject requests that appear to have been 1392 misdirected (Section 7.4). 1394 An origin server might be unwilling to process requests for certain 1395 target URIs even when they have the authority to do so. For example, 1396 when a host operates distinct services on different ports (e.g., 443 1397 and 8000), checking the target URI at the origin server is necessary 1398 (even after the connection has been secured) because a network 1399 attacker might cause connections for one port to be received at some 1400 other port. Failing to check the target URI might allow such an 1401 attacker to replace a response to one target URI (e.g., 1402 "https://example.com/foo") with a seemingly authoritative response 1403 from the other port (e.g., "https://example.com:8000/foo"). 1405 Note that the "https" scheme does not rely on TCP and the connected 1406 port number for associating authority, since both are outside the 1407 secured communication and thus cannot be trusted as definitive. 1408 Hence, the HTTP communication might take place over any channel that 1409 has been secured, as defined in Section 4.2.2, including protocols 1410 that don't use TCP. 1412 When an "https" URI is used within a context that calls for access to 1413 the indicated resource, a client MAY attempt access by resolving the 1414 host identifier to an IP address, establishing a TCP connection to 1415 that address on the indicated port, securing the connection end-to- 1416 end by successfully initiating TLS over TCP with confidentiality and 1417 integrity protection, and sending over that connection an HTTP 1418 request message containing a request target that matches the client's 1419 target URI (Section 7.1). 1421 If the server responds to such a request with a non-interim HTTP 1422 response message, as described in Section 15, then that response is 1423 considered an authoritative answer to the client's request. 1425 Note, however, that the above is not the only means for obtaining an 1426 authoritative response, nor does it imply that an authoritative 1427 response is always necessary (see [CACHING]). 1429 4.3.4. https certificate verification 1431 To establish a secured connection to dereference a URI, a client MUST 1432 verify that the service's identity is an acceptable match for the 1433 URI's origin server. Certificate verification is used to prevent 1434 server impersonation by an on-path attacker or by an attacker that 1435 controls name resolution. This process requires that a client be 1436 configured with a set of trust anchors. 1438 In general, a client MUST verify the service identity using the 1439 verification process defined in Section 6 of [RFC6125]. The client 1440 MUST construct a reference identity from the service's host: if the 1441 host is a literal IP address (Section 4.3.5), the reference identity 1442 is an IP-ID, otherwise the host is a name and the reference identity 1443 is a DNS-ID. 1445 A reference identity of type CN-ID MUST NOT be used by clients. As 1446 noted in Section 6.2.1 of [RFC6125] a reference identity of type CN- 1447 ID might be used by older clients. 1449 A client might be specially configured to accept an alternative form 1450 of server identity verification. For example, a client might be 1451 connecting to a server whose address and hostname are dynamic, with 1452 an expectation that the service will present a specific certificate 1453 (or a certificate matching some externally defined reference 1454 identity) rather than one matching the target URI's origin. 1456 In special cases, it might be appropriate for a client to simply 1457 ignore the server's identity, but it must be understood that this 1458 leaves a connection open to active attack. 1460 If the certificate is not valid for the target URI's origin, a user 1461 agent MUST either obtain confirmation from the user before proceeding 1462 (see Section 3.5) or terminate the connection with a bad certificate 1463 error. Automated clients MUST log the error to an appropriate audit 1464 log (if available) and SHOULD terminate the connection (with a bad 1465 certificate error). Automated clients MAY provide a configuration 1466 setting that disables this check, but MUST provide a setting which 1467 enables it. 1469 4.3.5. IP-ID reference identity 1471 A server that is identified using an IP address literal in the "host" 1472 field of an "https" URI has a reference identity of type IP-ID. An 1473 IP version 4 address uses the "IPv4address" ABNF rule and an IP 1474 version 6 address uses the "IP-literal" production with the 1475 "IPv6address" option; see Section 3.2.2 of [URI]. A reference 1476 identity of IP-ID contains the decoded bytes of the IP address. 1478 An IP version 4 address is 4 octets and an IP version 6 address is 16 1479 octets. Use of IP-ID is not defined for any other IP version. The 1480 iPAddress choice in the certificate subjectAltName extension does not 1481 explicitly include the IP version and so relies on the length of the 1482 address to distinguish versions; see Section 4.2.1.6 of [RFC5280]. 1484 A reference identity of type IP-ID matches if the address is 1485 identical to an iPAddress value of the subjectAltName extension of 1486 the certificate. 1488 5. Fields 1490 HTTP uses _fields_ to provide data in the form of extensible key/ 1491 value pairs with a registered key namespace. Fields are sent and 1492 received within the header and trailer sections of messages 1493 (Section 6). 1495 5.1. Field Names 1497 A field name labels the corresponding field value as having the 1498 semantics defined by that name. For example, the Date header field 1499 is defined in Section 6.6.1 as containing the origination timestamp 1500 for the message in which it appears. 1502 field-name = token 1504 Field names are case-insensitive and ought to be registered within 1505 the "Hypertext Transfer Protocol (HTTP) Field Name Registry"; see 1506 Section 16.3.1. 1508 The interpretation of a field does not change between minor versions 1509 of the same major HTTP version, though the default behavior of a 1510 recipient in the absence of such a field can change. Unless 1511 specified otherwise, fields are defined for all versions of HTTP. In 1512 particular, the Host and Connection fields ought to be recognized by 1513 all HTTP implementations whether or not they advertise conformance 1514 with HTTP/1.1. 1516 New fields can be introduced without changing the protocol version if 1517 their defined semantics allow them to be safely ignored by recipients 1518 that do not recognize them; see Section 16.3. 1520 A proxy MUST forward unrecognized header fields unless the field name 1521 is listed in the Connection header field (Section 7.6.1) or the proxy 1522 is specifically configured to block, or otherwise transform, such 1523 fields. Other recipients SHOULD ignore unrecognized header and 1524 trailer fields. Adhering to these requirements allows HTTP's 1525 functionality to be extended without updating or removing deployed 1526 intermediaries. 1528 5.2. Field Lines and Combined Field Value 1530 Field sections are composed of any number of _field lines_, each with 1531 a _field name_ (see Section 5.1) identifying the field, and a _field 1532 line value_ that conveys data for that instance of the field. 1534 When a field name is only present once in a section, the combined 1535 _field value_ for that field consists of the corresponding field line 1536 value. When a field name is repeated within a section, its combined 1537 field value consists of the list of corresponding field line values 1538 within that section, concatenated in order, with each field line 1539 value separated by a comma. 1541 For example, this section: 1543 Example-Field: Foo, Bar 1544 Example-Field: Baz 1546 contains two field lines, both with the field name "Example-Field". 1547 The first field line has a field line value of "Foo, Bar", while the 1548 second field line value is "Baz". The field value for "Example- 1549 Field" is the list "Foo, Bar, Baz". 1551 5.3. Field Order 1553 A recipient MAY combine multiple field lines within a field section 1554 that have the same field name into one field line, without changing 1555 the semantics of the message, by appending each subsequent field line 1556 value to the initial field line value in order, separated by a comma 1557 (",") and optional whitespace (OWS, defined in Section 5.6.3). For 1558 consistency, use comma SP. 1560 The order in which field lines with the same name are received is 1561 therefore significant to the interpretation of the field value; a 1562 proxy MUST NOT change the order of these field line values when 1563 forwarding a message. 1565 This means that, aside from the well-known exception noted below, a 1566 sender MUST NOT generate multiple field lines with the same name in a 1567 message (whether in the headers or trailers), or append a field line 1568 when a field line of the same name already exists in the message, 1569 unless that field's definition allows multiple field line values to 1570 be recombined as a comma-separated list [i.e., at least one 1571 alternative of the field's definition allows a comma-separated list, 1572 such as an ABNF rule of #(values) defined in Section 5.6.1]. 1574 | *Note:* In practice, the "Set-Cookie" header field ([COOKIE]) 1575 | often appears in a response message across multiple field lines 1576 | and does not use the list syntax, violating the above 1577 | requirements on multiple field lines with the same field name. 1578 | Since it cannot be combined into a single field value, 1579 | recipients ought to handle "Set-Cookie" as a special case while 1580 | processing fields. (See Appendix A.2.3 of [Kri2001] for 1581 | details.) 1583 The order in which field lines with differing field names are 1584 received in a section is not significant. However, it is good 1585 practice to send header fields that contain additional control data 1586 first, such as Host on requests and Date on responses, so that 1587 implementations can decide when not to handle a message as early as 1588 possible. 1590 A server MUST NOT apply a request to the target resource until it 1591 receives the entire request header section, since later header field 1592 lines might include conditionals, authentication credentials, or 1593 deliberately misleading duplicate header fields that could impact 1594 request processing. 1596 5.4. Field Limits 1598 HTTP does not place a predefined limit on the length of each field 1599 line, field value, or on the length of a header or trailer section as 1600 a whole, as described in Section 2. Various ad hoc limitations on 1601 individual lengths are found in practice, often depending on the 1602 specific field's semantics. 1604 A server that receives a request header field line, field value, or 1605 set of fields larger than it wishes to process MUST respond with an 1606 appropriate 4xx (Client Error) status code. Ignoring such header 1607 fields would increase the server's vulnerability to request smuggling 1608 attacks (Section 11.2 of [HTTP/1.1]). 1610 A client MAY discard or truncate received field lines that are larger 1611 than the client wishes to process if the field semantics are such 1612 that the dropped value(s) can be safely ignored without changing the 1613 message framing or response semantics. 1615 5.5. Field Values 1617 HTTP field values consist of a sequence of characters in a format 1618 defined by the field's grammar. Each field's grammar is usually 1619 defined using ABNF ([RFC5234]). 1621 field-value = *field-content 1622 field-content = field-vchar 1623 [ 1*( SP / HTAB / field-vchar ) field-vchar ] 1624 field-vchar = VCHAR / obs-text 1625 obs-text = %x80-FF 1627 A field value does not include leading or trailing whitespace. When 1628 a specific version of HTTP allows such whitespace to appear in a 1629 message, a field parsing implementation MUST exclude such whitespace 1630 prior to evaluating the field value. 1632 Field values are usually constrained to the range of US-ASCII 1633 characters [USASCII]. Fields needing a greater range of characters 1634 can use an encoding, such as the one defined in [RFC8187]. 1635 Historically, HTTP allowed field content with text in the ISO-8859-1 1636 charset [ISO-8859-1], supporting other charsets only through use of 1637 [RFC2047] encoding. Specifications for newly defined fields SHOULD 1638 limit their values to visible US-ASCII octets (VCHAR), SP, and HTAB. 1639 A recipient SHOULD treat other allowed octets in field content (i.e., 1640 obs-text) as opaque data. 1642 Field values containing CR, LF, or NUL characters are invalid and 1643 dangerous, due to the varying ways that implementations might parse 1644 and interpret those characters; a recipient of CR, LF, or NUL within 1645 a field value MUST either reject the message or replace each of those 1646 characters with SP before further processing or forwarding of that 1647 message. Field values containing other CTL characters are also 1648 invalid; however, recipients MAY retain such characters for the sake 1649 of robustness when they appear within a safe context (e.g., an 1650 application-specific quoted string that will not be processed by any 1651 downstream HTTP parser). 1653 Fields that only anticipate a single member as the field value are 1654 referred to as _singleton fields_. 1656 Fields that allow multiple members as the field value are referred to 1657 as _list-based fields_. The list operator extension of Section 5.6.1 1658 is used as a common notation for defining field values that can 1659 contain multiple members. 1661 Because commas (",") are used as the delimiter between members, they 1662 need to be treated with care if they are allowed as data within a 1663 member. This is true for both list-based and singleton fields, since 1664 a singleton field might be erroneously sent with multiple members and 1665 detecting such errors improves interoperability. Fields that expect 1666 to contain a comma within a member, such as within an HTTP-date or 1667 URI-reference element, ought to be defined with delimiters around 1668 that element to distinguish any comma within that data from potential 1669 list separators. 1671 For example, a textual date and a URI (either of which might contain 1672 a comma) could be safely carried in list-based field values like 1673 these: 1675 Example-URIs: "http://example.com/a.html,foo", 1676 "http://without-a-comma.example.com/" 1677 Example-Dates: "Sat, 04 May 1996", "Wed, 14 Sep 2005" 1679 Note that double-quote delimiters are almost always used with the 1680 quoted-string production (Section 5.6.4); using a different syntax 1681 inside double-quotes will likely cause unnecessary confusion. 1683 Many fields (such as Content-Type, defined in Section 8.3) use a 1684 common syntax for parameters that allows both unquoted (token) and 1685 quoted (quoted-string) syntax for a parameter value (Section 5.6.6). 1687 Use of common syntax allows recipients to reuse existing parser 1688 components. When allowing both forms, the meaning of a parameter 1689 value ought to be the same whether it was received as a token or a 1690 quoted string. 1692 | *Note:* For defining field value syntax, this specification 1693 | uses an ABNF rule named after the field name to define the 1694 | allowed grammar for that field's value (after said value has 1695 | been extracted from the underlying messaging syntax and 1696 | multiple instances combined into a list). 1698 5.6. Common Rules for Defining Field Values 1700 5.6.1. Lists (#rule ABNF Extension) 1702 A #rule extension to the ABNF rules of [RFC5234] is used to improve 1703 readability in the definitions of some list-based field values. 1705 A construct "#" is defined, similar to "*", for defining comma- 1706 delimited lists of elements. The full form is "#element" 1707 indicating at least and at most elements, each separated by a 1708 single comma (",") and optional whitespace (OWS, defined in 1709 Section 5.6.3). 1711 5.6.1.1. Sender Requirements 1713 In any production that uses the list construct, a sender MUST NOT 1714 generate empty list elements. In other words, a sender has to 1715 generate lists that satisfy the following syntax: 1717 1#element => element *( OWS "," OWS element ) 1719 and: 1721 #element => [ 1#element ] 1723 and for n >= 1 and m > 1: 1725 #element => element *( OWS "," OWS element ) 1727 Appendix A shows the collected ABNF for senders after the list 1728 constructs have been expanded. 1730 5.6.1.2. Recipient Requirements 1732 Empty elements do not contribute to the count of elements present. A 1733 recipient MUST parse and ignore a reasonable number of empty list 1734 elements: enough to handle common mistakes by senders that merge 1735 values, but not so much that they could be used as a denial-of- 1736 service mechanism. In other words, a recipient MUST accept lists 1737 that satisfy the following syntax: 1739 #element => [ element ] *( OWS "," OWS [ element ] ) 1741 Note that because of the potential presence of empty list elements, 1742 the RFC 5234 ABNF cannot enforce the cardinality of list elements, 1743 and consequently all cases are mapped as if there was no cardinality 1744 specified. 1746 For example, given these ABNF productions: 1748 example-list = 1#example-list-elmt 1749 example-list-elmt = token ; see Section 5.6.2 1751 Then the following are valid values for example-list (not including 1752 the double quotes, which are present for delimitation only): 1754 "foo,bar" 1755 "foo ,bar," 1756 "foo , ,bar,charlie" 1758 In contrast, the following values would be invalid, since at least 1759 one non-empty element is required by the example-list production: 1761 "" 1762 "," 1763 ", ," 1765 5.6.2. Tokens 1767 Tokens are short textual identifiers that do not include whitespace 1768 or delimiters. 1770 token = 1*tchar 1772 tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" 1773 / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" 1774 / DIGIT / ALPHA 1775 ; any VCHAR, except delimiters 1777 Many HTTP field values are defined using common syntax components, 1778 separated by whitespace or specific delimiting characters. 1779 Delimiters are chosen from the set of US-ASCII visual characters not 1780 allowed in a token (DQUOTE and "(),/:;<=>?@[\]{}"). 1782 5.6.3. Whitespace 1784 This specification uses three rules to denote the use of linear 1785 whitespace: OWS (optional whitespace), RWS (required whitespace), and 1786 BWS ("bad" whitespace). 1788 The OWS rule is used where zero or more linear whitespace octets 1789 might appear. For protocol elements where optional whitespace is 1790 preferred to improve readability, a sender SHOULD generate the 1791 optional whitespace as a single SP; otherwise, a sender SHOULD NOT 1792 generate optional whitespace except as needed to overwrite invalid or 1793 unwanted protocol elements during in-place message filtering. 1795 The RWS rule is used when at least one linear whitespace octet is 1796 required to separate field tokens. A sender SHOULD generate RWS as a 1797 single SP. 1799 OWS and RWS have the same semantics as a single SP. Any content 1800 known to be defined as OWS or RWS MAY be replaced with a single SP 1801 before interpreting it or forwarding the message downstream. 1803 The BWS rule is used where the grammar allows optional whitespace 1804 only for historical reasons. A sender MUST NOT generate BWS in 1805 messages. A recipient MUST parse for such bad whitespace and remove 1806 it before interpreting the protocol element. 1808 BWS has no semantics. Any content known to be defined as BWS MAY be 1809 removed before interpreting it or forwarding the message downstream. 1811 OWS = *( SP / HTAB ) 1812 ; optional whitespace 1813 RWS = 1*( SP / HTAB ) 1814 ; required whitespace 1815 BWS = OWS 1816 ; "bad" whitespace 1818 5.6.4. Quoted Strings 1820 A string of text is parsed as a single value if it is quoted using 1821 double-quote marks. 1823 quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE 1824 qdtext = HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text 1826 The backslash octet ("\") can be used as a single-octet quoting 1827 mechanism within quoted-string and comment constructs. Recipients 1828 that process the value of a quoted-string MUST handle a quoted-pair 1829 as if it were replaced by the octet following the backslash. 1831 quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) 1833 A sender SHOULD NOT generate a quoted-pair in a quoted-string except 1834 where necessary to quote DQUOTE and backslash octets occurring within 1835 that string. A sender SHOULD NOT generate a quoted-pair in a comment 1836 except where necessary to quote parentheses ["(" and ")"] and 1837 backslash octets occurring within that comment. 1839 5.6.5. Comments 1841 Comments can be included in some HTTP fields by surrounding the 1842 comment text with parentheses. Comments are only allowed in fields 1843 containing "comment" as part of their field value definition. 1845 comment = "(" *( ctext / quoted-pair / comment ) ")" 1846 ctext = HTAB / SP / %x21-27 / %x2A-5B / %x5D-7E / obs-text 1848 5.6.6. Parameters 1850 Parameters are instances of name=value pairs; they are often used in 1851 field values as a common syntax for appending auxiliary information 1852 to an item. Each parameter is usually delimited by an immediately 1853 preceding semicolon. 1855 parameters = *( OWS ";" OWS [ parameter ] ) 1856 parameter = parameter-name "=" parameter-value 1857 parameter-name = token 1858 parameter-value = ( token / quoted-string ) 1860 Parameter names are case-insensitive. Parameter values might or 1861 might not be case-sensitive, depending on the semantics of the 1862 parameter name. Examples of parameters and some equivalent forms can 1863 be seen in media types (Section 8.3.1) and the Accept header field 1864 (Section 12.5.1). 1866 A parameter value that matches the token production can be 1867 transmitted either as a token or within a quoted-string. The quoted 1868 and unquoted values are equivalent. 1870 | *Note:* Parameters do not allow whitespace (not even "bad" 1871 | whitespace) around the "=" character. 1873 5.6.7. Date/Time Formats 1875 Prior to 1995, there were three different formats commonly used by 1876 servers to communicate timestamps. For compatibility with old 1877 implementations, all three are defined here. The preferred format is 1878 a fixed-length and single-zone subset of the date and time 1879 specification used by the Internet Message Format [RFC5322]. 1881 HTTP-date = IMF-fixdate / obs-date 1883 An example of the preferred format is 1885 Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate 1887 Examples of the two obsolete formats are 1889 Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format 1890 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format 1892 A recipient that parses a timestamp value in an HTTP field MUST 1893 accept all three HTTP-date formats. When a sender generates a field 1894 that contains one or more timestamps defined as HTTP-date, the sender 1895 MUST generate those timestamps in the IMF-fixdate format. 1897 An HTTP-date value represents time as an instance of Coordinated 1898 Universal Time (UTC). The first two formats indicate UTC by the 1899 three-letter abbreviation for Greenwich Mean Time, "GMT", a 1900 predecessor of the UTC name; values in the asctime format are assumed 1901 to be in UTC. 1903 A _clock_ is an implementation capable of providing a reasonable 1904 approximation of the current instant in UTC. A clock implementation 1905 ought to use NTP ([RFC5905]), or some similar protocol, to 1906 synchronize with UTC. 1908 Preferred format: 1910 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 1911 ; fixed length/zone/capitalization subset of the format 1912 ; see Section 3.3 of [RFC5322] 1914 day-name = %s"Mon" / %s"Tue" / %s"Wed" 1915 / %s"Thu" / %s"Fri" / %s"Sat" / %s"Sun" 1917 date1 = day SP month SP year 1918 ; e.g., 02 Jun 1982 1920 day = 2DIGIT 1921 month = %s"Jan" / %s"Feb" / %s"Mar" / %s"Apr" 1922 / %s"May" / %s"Jun" / %s"Jul" / %s"Aug" 1923 / %s"Sep" / %s"Oct" / %s"Nov" / %s"Dec" 1924 year = 4DIGIT 1926 GMT = %s"GMT" 1928 time-of-day = hour ":" minute ":" second 1929 ; 00:00:00 - 23:59:60 (leap second) 1931 hour = 2DIGIT 1932 minute = 2DIGIT 1933 second = 2DIGIT 1935 Obsolete formats: 1937 obs-date = rfc850-date / asctime-date 1939 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 1940 date2 = day "-" month "-" 2DIGIT 1941 ; e.g., 02-Jun-82 1943 day-name-l = %s"Monday" / %s"Tuesday" / %s"Wednesday" 1944 / %s"Thursday" / %s"Friday" / %s"Saturday" 1945 / %s"Sunday" 1947 asctime-date = day-name SP date3 SP time-of-day SP year 1948 date3 = month SP ( 2DIGIT / ( SP 1DIGIT )) 1949 ; e.g., Jun 2 1951 HTTP-date is case sensitive. Note that Section 4.2 of [CACHING] 1952 relaxes this for cache recipients. 1954 A sender MUST NOT generate additional whitespace in an HTTP-date 1955 beyond that specifically included as SP in the grammar. The 1956 semantics of day-name, day, month, year, and time-of-day are the same 1957 as those defined for the Internet Message Format constructs with the 1958 corresponding name ([RFC5322], Section 3.3). 1960 Recipients of a timestamp value in rfc850-date format, which uses a 1961 two-digit year, MUST interpret a timestamp that appears to be more 1962 than 50 years in the future as representing the most recent year in 1963 the past that had the same last two digits. 1965 Recipients of timestamp values are encouraged to be robust in parsing 1966 timestamps unless otherwise restricted by the field definition. For 1967 example, messages are occasionally forwarded over HTTP from a non- 1968 HTTP source that might generate any of the date and time 1969 specifications defined by the Internet Message Format. 1971 | *Note:* HTTP requirements for the date/time stamp format apply 1972 | only to their usage within the protocol stream. 1973 | Implementations are not required to use these formats for user 1974 | presentation, request logging, etc. 1976 6. Message Abstraction 1978 Each major version of HTTP defines its own syntax for communicating 1979 messages. This section defines an abstract data type for HTTP 1980 messages based on a generalization of those message characteristics, 1981 common structure, and capacity for conveying semantics. This 1982 abstraction is used to define requirements on senders and recipients 1983 that are independent of the HTTP version, such that a message in one 1984 version can be relayed through other versions without changing its 1985 meaning. 1987 A _message_ consists of control data to describe and route the 1988 message, a headers lookup table of key/value pairs for extending that 1989 control data and conveying additional information about the sender, 1990 message, content, or context, a potentially unbounded stream of 1991 content, and a trailers lookup table of key/value pairs for 1992 communicating information obtained while sending the content. 1994 Framing and control data is sent first, followed by a header section 1995 containing fields for the headers table. When a message includes 1996 content, the content is sent after the header section, potentially 1997 followed by a trailer section that might contain fields for the 1998 trailers table. 2000 Messages are expected to be processed as a stream, wherein the 2001 purpose of that stream and its continued processing is revealed while 2002 being read. Hence, control data describes what the recipient needs 2003 to know immediately, header fields describe what needs to be known 2004 before receiving content, the content (when present) presumably 2005 contains what the recipient wants or needs to fulfill the message 2006 semantics, and trailer fields provide optional metadata that was 2007 unknown prior to sending the content. 2009 Messages are intended to be _self-descriptive_: everything a 2010 recipient needs to know about the message can be determined by 2011 looking at the message itself, after decoding or reconstituting parts 2012 that have been compressed or elided in transit, without requiring an 2013 understanding of the sender's current application state (established 2014 via prior messages). However, a client MUST retain knowledge of the 2015 request when parsing, interpreting, or caching a corresponding 2016 response. For example, responses to the HEAD method look just like 2017 the beginning of a response to GET, but cannot be parsed in the same 2018 manner. 2020 Note that this message abstraction is a generalization across many 2021 versions of HTTP, including features that might not be found in some 2022 versions. For example, trailers were introduced within the HTTP/1.1 2023 chunked transfer coding as a trailer section after the content. An 2024 equivalent feature is present in HTTP/2 and HTTP/3 within the header 2025 block that terminates each stream. 2027 6.1. Framing and Completeness 2029 Message framing indicates how each message begins and ends, such that 2030 each message can be distinguished from other messages or noise on the 2031 same connection. Each major version of HTTP defines its own framing 2032 mechanism. 2034 HTTP/0.9 and early deployments of HTTP/1.0 used closure of the 2035 underlying connection to end a response. For backwards 2036 compatibility, this implicit framing is also allowed in HTTP/1.1. 2037 However, implicit framing can fail to distinguish an incomplete 2038 response if the connection closes early. For that reason, almost all 2039 modern implementations use explicit framing in the form of length- 2040 delimited sequences of message data. 2042 A message is considered _complete_ when all of the octets indicated 2043 by its framing are available. Note that, when no explicit framing is 2044 used, a response message that is ended by the underlying connection's 2045 close is considered complete even though it might be 2046 indistinguishable from an incomplete response, unless a transport- 2047 level error indicates that it is not complete. 2049 6.2. Control Data 2051 Messages start with control data that describe its primary purpose. 2052 Request message control data includes a request method (Section 9), 2053 request target (Section 7.1), and protocol version (Section 2.5). 2054 Response message control data includes a status code (Section 15), 2055 optional reason phrase, and protocol version. 2057 In HTTP/1.1 ([HTTP/1.1]) and earlier, control data is sent as the 2058 first line of a message. In HTTP/2 ([HTTP/2]) and HTTP/3 ([HTTP/3]), 2059 control data is sent as pseudo-header fields with a reserved name 2060 prefix (e.g., ":authority"). 2062 Every HTTP message has a protocol version. Depending on the version 2063 in use, it might be identified within the message explicitly or 2064 inferred by the connection over which the message is received. 2065 Recipients use that version information to determine limitations or 2066 potential for later communication with that sender. 2068 When a message is forwarded by an intermediary, the protocol version 2069 is updated to reflect the version used by that intermediary. The Via 2070 header field (Section 7.6.3) is used to communicate upstream protocol 2071 information within a forwarded message. 2073 A client SHOULD send a request version equal to the highest version 2074 to which the client is conformant and whose major version is no 2075 higher than the highest version supported by the server, if this is 2076 known. A client MUST NOT send a version to which it is not 2077 conformant. 2079 A client MAY send a lower request version if it is known that the 2080 server incorrectly implements the HTTP specification, but only after 2081 the client has attempted at least one normal request and determined 2082 from the response status code or header fields (e.g., Server) that 2083 the server improperly handles higher request versions. 2085 A server SHOULD send a response version equal to the highest version 2086 to which the server is conformant that has a major version less than 2087 or equal to the one received in the request. A server MUST NOT send 2088 a version to which it is not conformant. A server can send a 505 2089 (HTTP Version Not Supported) response if it wishes, for any reason, 2090 to refuse service of the client's major protocol version. 2092 A recipient that receives a message with a major version number that 2093 it implements and a minor version number higher than what it 2094 implements SHOULD process the message as if it were in the highest 2095 minor version within that major version to which the recipient is 2096 conformant. A recipient can assume that a message with a higher 2097 minor version, when sent to a recipient that has not yet indicated 2098 support for that higher version, is sufficiently backwards-compatible 2099 to be safely processed by any implementation of the same major 2100 version. 2102 6.3. Header Fields 2104 Fields (Section 5) that are sent/received before the content are 2105 referred to as "header fields" (or just "headers", colloquially). 2107 The _header section_ of a message consists of a sequence of header 2108 field lines. Each header field might modify or extend message 2109 semantics, describe the sender, define the content, or provide 2110 additional context. 2112 | *Note:* We refer to named fields specifically as a "header 2113 | field" when they are only allowed to be sent in the header 2114 | section. 2116 6.4. Content 2118 HTTP messages often transfer a complete or partial representation as 2119 the message _content_: a stream of octets sent after the header 2120 section, as delineated by the message framing. 2122 This abstract definition of content reflects the data after it has 2123 been extracted from the message framing. For example, an HTTP/1.1 2124 message body (Section 6 of [HTTP/1.1]) might consist of a stream of 2125 data encoded with the chunked transfer coding - a sequence of data 2126 chunks, one zero-length chunk, and a trailer section - whereas the 2127 content of that same message includes only the data stream after the 2128 transfer coding has been decoded; it does not include the chunk 2129 lengths, chunked framing syntax, nor the trailer fields 2130 (Section 6.5). 2132 | *Note:* Some field names have a "Content-" prefix. This is an 2133 | informal convention; while some of these fields refer to the 2134 | content of the message, as defined above, others are scoped to 2135 | the selected representation (Section 3.2). See the individual 2136 | field's definition to disambiguate. 2138 6.4.1. Content Semantics 2140 The purpose of content in a request is defined by the method 2141 semantics (Section 9). 2143 For example, a representation in the content of a PUT request 2144 (Section 9.3.4) represents the desired state of the target resource 2145 after the request is successfully applied, whereas a representation 2146 in the content of a POST request (Section 9.3.3) represents 2147 information to be processed by the target resource. 2149 In a response, the content's purpose is defined by the request 2150 method, response status code (Section 15), and response fields 2151 describing that content. For example, the content of a 200 (OK) 2152 response to GET (Section 9.3.1) represents the current state of the 2153 target resource, as observed at the time of the message origination 2154 date (Section 6.6.1), whereas the content of the same status code in 2155 a response to POST might represent either the processing result or 2156 the new state of the target resource after applying the processing. 2158 The content of a 206 (Partial Content) response to GET contains 2159 either a single part of the selected representation or a multipart 2160 message body containing multiple parts of that representation, as 2161 described in Section 15.3.7. 2163 Response messages with an error status code usually contain content 2164 that represents the error condition, such that the content describes 2165 the error state and what steps are suggested for resolving it. 2167 Responses to the HEAD request method (Section 9.3.2) never include 2168 content; the associated response header fields indicate only what 2169 their values would have been if the request method had been GET 2170 (Section 9.3.1). 2172 2xx (Successful) responses to a CONNECT request method 2173 (Section 9.3.6) switch the connection to tunnel mode instead of 2174 having content. 2176 All 1xx (Informational), 204 (No Content), and 304 (Not Modified) 2177 responses do not include content. 2179 All other responses do include content, although that content might 2180 be of zero length. 2182 6.4.2. Identifying Content 2184 When a complete or partial representation is transferred as message 2185 content, it is often desirable for the sender to supply, or the 2186 recipient to determine, an identifier for a resource corresponding to 2187 that specific representation. For example, a client making a GET 2188 request on a resource for "the current weather report" might want an 2189 identifier specific to the content returned (e.g., "weather report 2190 for Laguna Beach at 20210720T1711"). This can be useful for sharing 2191 or bookmarking content from resources that are expected to have 2192 changing representations over time. 2194 For a request message: 2196 * If the request has a Content-Location header field, then the 2197 sender asserts that the content is a representation of the 2198 resource identified by the Content-Location field value. However, 2199 such an assertion cannot be trusted unless it can be verified by 2200 other means (not defined by this specification). The information 2201 might still be useful for revision history links. 2203 * Otherwise, the content is unidentified by HTTP, but a more 2204 specific identifier might be supplied within the content itself. 2206 For a response message, the following rules are applied in order 2207 until a match is found: 2209 1. If the request method is HEAD or the response status code is 204 2210 (No Content) or 304 (Not Modified), there is no content in the 2211 response. 2213 2. If the request method is GET and the response status code is 200 2214 (OK), the content is a representation of the target resource 2215 (Section 7.1). 2217 3. If the request method is GET and the response status code is 203 2218 (Non-Authoritative Information), the content is a potentially 2219 modified or enhanced representation of the target resource as 2220 provided by an intermediary. 2222 4. If the request method is GET and the response status code is 206 2223 (Partial Content), the content is one or more parts of a 2224 representation of the target resource. 2226 5. If the response has a Content-Location header field and its field 2227 value is a reference to the same URI as the target URI, the 2228 content is a representation of the target resource. 2230 6. If the response has a Content-Location header field and its field 2231 value is a reference to a URI different from the target URI, then 2232 the sender asserts that the content is a representation of the 2233 resource identified by the Content-Location field value. 2234 However, such an assertion cannot be trusted unless it can be 2235 verified by other means (not defined by this specification). 2237 7. Otherwise, the content is unidentified by HTTP, but a more 2238 specific identifier might be supplied within the content itself. 2240 6.5. Trailer Fields 2242 Fields (Section 5) that are located within a _trailer section_ are 2243 referred to as "trailer fields" (or just "trailers", colloquially). 2244 Trailer fields can be useful for supplying message integrity checks, 2245 digital signatures, delivery metrics, or post-processing status 2246 information. 2248 Trailer fields ought to be processed and stored separately from the 2249 fields in the header section to avoid contradicting message semantics 2250 known at the time the header section was complete. The presence or 2251 absence of certain header fields might impact choices made for the 2252 routing or processing of the message as a whole before the trailers 2253 are received; those choices cannot be unmade by the later discovery 2254 of trailer fields. 2256 6.5.1. Limitations on use of Trailers 2258 A trailer section is only possible when supported by the version of 2259 HTTP in use and enabled by an explicit framing mechanism. For 2260 example, the chunked coding in HTTP/1.1 allows a trailer section to 2261 be sent after the content (Section 7.1.2 of [HTTP/1.1]). 2263 Many fields cannot be processed outside the header section because 2264 their evaluation is necessary prior to receiving the content, such as 2265 those that describe message framing, routing, authentication, request 2266 modifiers, response controls, or content format. A sender MUST NOT 2267 generate a trailer field unless the sender knows the corresponding 2268 header field name's definition permits the field to be sent in 2269 trailers. 2271 Trailer fields can be difficult to process by intermediaries that 2272 forward messages from one protocol version to another. If the entire 2273 message can be buffered in transit, some intermediaries could merge 2274 trailer fields into the header section (as appropriate) before it is 2275 forwarded. However, in most cases, the trailers are simply 2276 discarded. A recipient MUST NOT merge a trailer field into a header 2277 section unless the recipient understands the corresponding header 2278 field definition and that definition explicitly permits and defines 2279 how trailer field values can be safely merged. 2281 The presence of the keyword "trailers" in the TE header field 2282 (Section 10.1.4) of a request indicates that the client is willing to 2283 accept trailer fields, on behalf of itself and any downstream 2284 clients. For requests from an intermediary, this implies that all 2285 downstream clients are willing to accept trailer fields in the 2286 forwarded response. Note that the presence of "trailers" does not 2287 mean that the client(s) will process any particular trailer field in 2288 the response; only that the trailer section(s) will not be dropped by 2289 any of the clients. 2291 Because of the potential for trailer fields to be discarded in 2292 transit, a server SHOULD NOT generate trailer fields that it believes 2293 are necessary for the user agent to receive. 2295 6.5.2. Processing Trailer Fields 2297 The "Trailer" header field (Section 6.6.2) can be sent to indicate 2298 fields likely to be sent in the trailer section, which allows 2299 recipients to prepare for their receipt before processing the 2300 content. For example, this could be useful if a field name indicates 2301 that a dynamic checksum should be calculated as the content is 2302 received and then immediately checked upon receipt of the trailer 2303 field value. 2305 Like header fields, trailer fields with the same name are processed 2306 in the order received; multiple trailer field lines with the same 2307 name have the equivalent semantics as appending the multiple values 2308 as a list of members. Trailer fields that might be generated more 2309 than once during a message MUST be defined as a list-based field even 2310 if each member value is only processed once per field line received. 2312 At the end of a message, a recipient MAY treat the set of received 2313 trailer fields as a data structure of key/value pairs, similar to 2314 (but separate from) the header fields. Additional processing 2315 expectations, if any, can be defined within the field specification 2316 for a field intended for use in trailers. 2318 6.6. Message Metadata 2320 Fields that describe the message itself, such as when and how the 2321 message has been generated, can appear in both requests and 2322 responses. 2324 6.6.1. Date 2326 The "Date" header field represents the date and time at which the 2327 message was originated, having the same semantics as the Origination 2328 Date Field (orig-date) defined in Section 3.6.1 of [RFC5322]. The 2329 field value is an HTTP-date, as defined in Section 5.6.7. 2331 Date = HTTP-date 2333 An example is 2335 Date: Tue, 15 Nov 1994 08:12:31 GMT 2337 A sender that generates a Date header field SHOULD generate its field 2338 value as the best available approximation of the date and time of 2339 message generation. In theory, the date ought to represent the 2340 moment just before generating the message content. In practice, a 2341 sender can generate the date value at any time during message 2342 origination. 2344 An origin server with a clock (as defined in Section 5.6.7) MUST 2345 generate a Date header field in all 2xx (Successful), 3xx 2346 (Redirection), and 4xx (Client Error) responses, and MAY generate a 2347 Date header field in 1xx (Informational) and 5xx (Server Error) 2348 responses. 2350 An origin server without a clock MUST NOT generate a Date header 2351 field. 2353 A recipient with a clock that receives a response message without a 2354 Date header field MUST record the time it was received and append a 2355 corresponding Date header field to the message's header section if it 2356 is cached or forwarded downstream. 2358 A recipient with a clock that receives a response with an invalid 2359 Date header field value MAY replace that value with the time that 2360 response was received. 2362 A user agent MAY send a Date header field in a request, though 2363 generally will not do so unless it is believed to convey useful 2364 information to the server. For example, custom applications of HTTP 2365 might convey a Date if the server is expected to adjust its 2366 interpretation of the user's request based on differences between the 2367 user agent and server clocks. 2369 6.6.2. Trailer 2371 The "Trailer" header field provides a list of field names that the 2372 sender anticipates sending as trailer fields within that message. 2373 This allows a recipient to prepare for receipt of the indicated 2374 metadata before it starts processing the content. 2376 Trailer = #field-name 2378 For example, a sender might indicate that a signature will be 2379 computed as the content is being streamed and provide the final 2380 signature as a trailer field. This allows a recipient to perform the 2381 same check on the fly as it receives the content. 2383 A sender that intends to generate one or more trailer fields in a 2384 message SHOULD generate a Trailer header field in the header section 2385 of that message to indicate which fields might be present in the 2386 trailers. 2388 If an intermediary discards the trailer section in transit, the 2389 Trailer field could provide a hint of what metadata was lost, though 2390 there is no guarantee that a sender of Trailer will always follow 2391 through by sending the named fields. 2393 7. Routing HTTP Messages 2395 HTTP request message routing is determined by each client based on 2396 the target resource, the client's proxy configuration, and 2397 establishment or reuse of an inbound connection. The corresponding 2398 response routing follows the same connection chain back to the 2399 client. 2401 7.1. Determining the Target Resource 2403 Although HTTP is used in a wide variety of applications, most clients 2404 rely on the same resource identification mechanism and configuration 2405 techniques as general-purpose Web browsers. Even when communication 2406 options are hard-coded in a client's configuration, we can think of 2407 their combined effect as a URI reference (Section 4.1). 2409 A URI reference is resolved to its absolute form in order to obtain 2410 the _target URI_. The target URI excludes the reference's fragment 2411 component, if any, since fragment identifiers are reserved for 2412 client-side processing ([URI], Section 3.5). 2414 To perform an action on a _target resource_, the client sends a 2415 request message containing enough components of its parsed target URI 2416 to enable recipients to identify that same resource. For historical 2417 reasons, the parsed target URI components, collectively referred to 2418 as the _request target_, are sent within the message control data and 2419 the Host header field (Section 7.2). 2421 There are two unusual cases for which the request target components 2422 are in a method-specific form: 2424 * For CONNECT (Section 9.3.6), the request target is the host name 2425 and port number of the tunnel destination, separated by a colon. 2427 * For OPTIONS (Section 9.3.7), the request target can be a single 2428 asterisk ("*"). 2430 See the respective method definitions for details. These forms MUST 2431 NOT be used with other methods. 2433 Upon receipt of a client's request, a server reconstructs the target 2434 URI from the received components in accordance with their local 2435 configuration and incoming connection context. This reconstruction 2436 is specific to each major protocol version. For example, Section 3.3 2437 of [HTTP/1.1] defines how a server determines the target URI of an 2438 HTTP/1.1 request. 2440 | *Note:* Previous specifications defined the recomposed target 2441 | URI as a distinct concept, the _effective request URI_. 2443 7.2. Host and :authority 2445 The "Host" header field in a request provides the host and port 2446 information from the target URI, enabling the origin server to 2447 distinguish among resources while servicing requests for multiple 2448 host names. 2450 In HTTP/2 [HTTP/2] and HTTP/3 [HTTP/3], the Host header field is, in 2451 some cases, supplanted by the ":authority" pseudo-header field of a 2452 request's control data. 2454 Host = uri-host [ ":" port ] ; Section 4 2456 The target URI's authority information is critical for handling a 2457 request. A user agent MUST generate a Host header field in a request 2458 unless it sends that information as an ":authority" pseudo-header 2459 field. A user agent that sends Host SHOULD send it as the first 2460 field in the header section of a request. 2462 For example, a GET request to the origin server for 2463 would begin with: 2465 GET /pub/WWW/ HTTP/1.1 2466 Host: www.example.org 2468 Since the host and port information acts as an application-level 2469 routing mechanism, it is a frequent target for malware seeking to 2470 poison a shared cache or redirect a request to an unintended server. 2471 An interception proxy is particularly vulnerable if it relies on the 2472 host and port information for redirecting requests to internal 2473 servers, or for use as a cache key in a shared cache, without first 2474 verifying that the intercepted connection is targeting a valid IP 2475 address for that host. 2477 7.3. Routing Inbound Requests 2479 Once the target URI and its origin are determined, a client decides 2480 whether a network request is necessary to accomplish the desired 2481 semantics and, if so, where that request is to be directed. 2483 7.3.1. To a Cache 2485 If the client has a cache [CACHING] and the request can be satisfied 2486 by it, then the request is usually directed there first. 2488 7.3.2. To a Proxy 2490 If the request is not satisfied by a cache, then a typical client 2491 will check its configuration to determine whether a proxy is to be 2492 used to satisfy the request. Proxy configuration is implementation- 2493 dependent, but is often based on URI prefix matching, selective 2494 authority matching, or both, and the proxy itself is usually 2495 identified by an "http" or "https" URI. 2497 If an "http" or "https" proxy is applicable, the client connects 2498 inbound by establishing (or reusing) a connection to that proxy and 2499 then sending it an HTTP request message containing a request target 2500 that matches the client's target URI. 2502 7.3.3. To the Origin 2504 If no proxy is applicable, a typical client will invoke a handler 2505 routine (specific to the target URI's scheme) to obtain access to the 2506 identified resource. How that is accomplished is dependent on the 2507 target URI scheme and defined by its associated specification. 2509 Section 4.3.2 defines how to obtain access to an "http" resource by 2510 establishing (or reusing) an inbound connection to the identified 2511 origin server and then sending it an HTTP request message containing 2512 a request target that matches the client's target URI. 2514 Section 4.3.3 defines how to obtain access to an "https" resource by 2515 establishing (or reusing) an inbound secured connection to an origin 2516 server that is authoritative for the identified origin and then 2517 sending it an HTTP request message containing a request target that 2518 matches the client's target URI. 2520 7.4. Rejecting Misdirected Requests 2522 Once a request is received by a server and parsed sufficiently to 2523 determine its target URI, the server decides whether to process the 2524 request itself, forward the request to another server, redirect the 2525 client to a different resource, respond with an error, or drop the 2526 connection. This decision can be influenced by anything about the 2527 request or connection context, but is specifically directed at 2528 whether the server has been configured to process requests for that 2529 target URI and whether the connection context is appropriate for that 2530 request. 2532 For example, a request might have been misdirected, deliberately or 2533 accidentally, such that the information within a received Host header 2534 field differs from the connection's host or port. If the connection 2535 is from a trusted gateway, such inconsistency might be expected; 2536 otherwise, it might indicate an attempt to bypass security filters, 2537 trick the server into delivering non-public content, or poison a 2538 cache. See Section 17 for security considerations regarding message 2539 routing. 2541 Unless the connection is from a trusted gateway, an origin server 2542 MUST reject a request if any scheme-specific requirements for the 2543 target URI are not met. In particular, a request for an "https" 2544 resource MUST be rejected unless it has been received over a 2545 connection that has been secured via a certificate valid for that 2546 target URI's origin, as defined by Section 4.2.2. 2548 The 421 (Misdirected Request) status code in a response indicates 2549 that the origin server has rejected the request because it appears to 2550 have been misdirected (Section 15.5.20). 2552 7.5. Response Correlation 2554 A connection might be used for multiple request/response exchanges. 2555 The mechanism used to correlate between request and response messages 2556 is version dependent; some versions of HTTP use implicit ordering of 2557 messages, while others use an explicit identifier. 2559 All responses, regardless of the status code (including interim 2560 responses) can be sent at any time after a request is received, even 2561 if the request is not yet complete. A response can complete before 2562 its corresponding request is complete (Section 6.1). Likewise, 2563 clients are not expected to wait any specific amount of time for a 2564 response. Clients (including intermediaries) might abandon a request 2565 if the response is not forthcoming within a reasonable period of 2566 time. 2568 A client that receives a response while it is still sending the 2569 associated request SHOULD continue sending that request, unless it 2570 receives an explicit indication to the contrary (see, e.g., 2571 Section 9.5 of [HTTP/1.1] and Section 6.4 of [HTTP/2]). 2573 7.6. Message Forwarding 2575 As described in Section 3.7, intermediaries can serve a variety of 2576 roles in the processing of HTTP requests and responses. Some 2577 intermediaries are used to improve performance or availability. 2578 Others are used for access control or to filter content. Since an 2579 HTTP stream has characteristics similar to a pipe-and-filter 2580 architecture, there are no inherent limits to the extent an 2581 intermediary can enhance (or interfere) with either direction of the 2582 stream. 2584 Intermediaries are expected to forward messages even when protocol 2585 elements are not recognized (e.g., new methods, status codes, or 2586 field names), since that preserves extensibility for downstream 2587 recipients. 2589 An intermediary not acting as a tunnel MUST implement the Connection 2590 header field, as specified in Section 7.6.1, and exclude fields from 2591 being forwarded that are only intended for the incoming connection. 2593 An intermediary MUST NOT forward a message to itself unless it is 2594 protected from an infinite request loop. In general, an intermediary 2595 ought to recognize its own server names, including any aliases, local 2596 variations, or literal IP addresses, and respond to such requests 2597 directly. 2599 An HTTP message can be parsed as a stream for incremental processing 2600 or forwarding downstream. However, senders and recipients cannot 2601 rely on incremental delivery of partial messages, since some 2602 implementations will buffer or delay message forwarding for the sake 2603 of network efficiency, security checks, or content transformations. 2605 7.6.1. Connection 2607 The "Connection" header field allows the sender to list desired 2608 control options for the current connection. 2610 When a field aside from Connection is used to supply control 2611 information for or about the current connection, the sender MUST list 2612 the corresponding field name within the Connection header field. 2613 Note that some versions of HTTP prohibit the use of fields for such 2614 information, and therefore do not allow the Connection field. 2616 Intermediaries MUST parse a received Connection header field before a 2617 message is forwarded and, for each connection-option in this field, 2618 remove any header or trailer field(s) from the message with the same 2619 name as the connection-option, and then remove the Connection header 2620 field itself (or replace it with the intermediary's own connection 2621 options for the forwarded message). 2623 Hence, the Connection header field provides a declarative way of 2624 distinguishing fields that are only intended for the immediate 2625 recipient ("hop-by-hop") from those fields that are intended for all 2626 recipients on the chain ("end-to-end"), enabling the message to be 2627 self-descriptive and allowing future connection-specific extensions 2628 to be deployed without fear that they will be blindly forwarded by 2629 older intermediaries. 2631 Furthermore, intermediaries SHOULD remove or replace field(s) whose 2632 semantics are known to require removal before forwarding, whether or 2633 not they appear as a Connection option, after applying those fields' 2634 semantics. This includes but is not limited to: 2636 * Proxy-Connection (Appendix C.2.2 of [HTTP/1.1]) 2638 * Keep-Alive (Section 19.7.1 of [RFC2068]) 2640 * TE (Section 10.1.4) 2642 * Transfer-Encoding (Section 6.1 of [HTTP/1.1]) 2644 * Upgrade (Section 7.8) 2646 The Connection header field's value has the following grammar: 2648 Connection = #connection-option 2649 connection-option = token 2651 Connection options are case-insensitive. 2653 A sender MUST NOT send a connection option corresponding to a field 2654 that is intended for all recipients of the content. For example, 2655 Cache-Control is never appropriate as a connection option 2656 (Section 5.2 of [CACHING]). 2658 Connection options do not always correspond to a field present in the 2659 message, since a connection-specific field might not be needed if 2660 there are no parameters associated with a connection option. In 2661 contrast, a connection-specific field received without a 2662 corresponding connection option usually indicates that the field has 2663 been improperly forwarded by an intermediary and ought to be ignored 2664 by the recipient. 2666 When defining a new connection option that does not correspond to a 2667 field, specification authors ought to reserve the corresponding field 2668 name anyway in order to avoid later collisions. Such reserved field 2669 names are registered in the Hypertext Transfer Protocol (HTTP) Field 2670 Name Registry (Section 16.3.1). 2672 7.6.2. Max-Forwards 2674 The "Max-Forwards" header field provides a mechanism with the TRACE 2675 (Section 9.3.8) and OPTIONS (Section 9.3.7) request methods to limit 2676 the number of times that the request is forwarded by proxies. This 2677 can be useful when the client is attempting to trace a request that 2678 appears to be failing or looping mid-chain. 2680 Max-Forwards = 1*DIGIT 2682 The Max-Forwards value is a decimal integer indicating the remaining 2683 number of times this request message can be forwarded. 2685 Each intermediary that receives a TRACE or OPTIONS request containing 2686 a Max-Forwards header field MUST check and update its value prior to 2687 forwarding the request. If the received value is zero (0), the 2688 intermediary MUST NOT forward the request; instead, the intermediary 2689 MUST respond as the final recipient. If the received Max-Forwards 2690 value is greater than zero, the intermediary MUST generate an updated 2691 Max-Forwards field in the forwarded message with a field value that 2692 is the lesser of a) the received value decremented by one (1) or b) 2693 the recipient's maximum supported value for Max-Forwards. 2695 A recipient MAY ignore a Max-Forwards header field received with any 2696 other request methods. 2698 7.6.3. Via 2700 The "Via" header field indicates the presence of intermediate 2701 protocols and recipients between the user agent and the server (on 2702 requests) or between the origin server and the client (on responses), 2703 similar to the "Received" header field in email (Section 3.6.7 of 2704 [RFC5322]). Via can be used for tracking message forwards, avoiding 2705 request loops, and identifying the protocol capabilities of senders 2706 along the request/response chain. 2708 Via = #( received-protocol RWS received-by [ RWS comment ] ) 2710 received-protocol = [ protocol-name "/" ] protocol-version 2711 ; see Section 7.8 2712 received-by = pseudonym [ ":" port ] 2713 pseudonym = token 2715 Each member of the Via field value represents a proxy or gateway that 2716 has forwarded the message. Each intermediary appends its own 2717 information about how the message was received, such that the end 2718 result is ordered according to the sequence of forwarding recipients. 2720 A proxy MUST send an appropriate Via header field, as described 2721 below, in each message that it forwards. An HTTP-to-HTTP gateway 2722 MUST send an appropriate Via header field in each inbound request 2723 message and MAY send a Via header field in forwarded response 2724 messages. 2726 For each intermediary, the received-protocol indicates the protocol 2727 and protocol version used by the upstream sender of the message. 2728 Hence, the Via field value records the advertised protocol 2729 capabilities of the request/response chain such that they remain 2730 visible to downstream recipients; this can be useful for determining 2731 what backwards-incompatible features might be safe to use in 2732 response, or within a later request, as described in Section 2.5. 2733 For brevity, the protocol-name is omitted when the received protocol 2734 is HTTP. 2736 The received-by portion is normally the host and optional port number 2737 of a recipient server or client that subsequently forwarded the 2738 message. However, if the real host is considered to be sensitive 2739 information, a sender MAY replace it with a pseudonym. If a port is 2740 not provided, a recipient MAY interpret that as meaning it was 2741 received on the default port, if any, for the received-protocol. 2743 A sender MAY generate comments to identify the software of each 2744 recipient, analogous to the User-Agent and Server header fields. 2745 However, comments in Via are optional, and a recipient MAY remove 2746 them prior to forwarding the message. 2748 For example, a request message could be sent from an HTTP/1.0 user 2749 agent to an internal proxy code-named "fred", which uses HTTP/1.1 to 2750 forward the request to a public proxy at p.example.net, which 2751 completes the request by forwarding it to the origin server at 2752 www.example.com. The request received by www.example.com would then 2753 have the following Via header field: 2755 Via: 1.0 fred, 1.1 p.example.net 2757 An intermediary used as a portal through a network firewall SHOULD 2758 NOT forward the names and ports of hosts within the firewall region 2759 unless it is explicitly enabled to do so. If not enabled, such an 2760 intermediary SHOULD replace each received-by host of any host behind 2761 the firewall by an appropriate pseudonym for that host. 2763 An intermediary MAY combine an ordered subsequence of Via header 2764 field list members into a single member if the entries have identical 2765 received-protocol values. For example, 2767 Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy 2769 could be collapsed to 2771 Via: 1.0 ricky, 1.1 mertz, 1.0 lucy 2773 A sender SHOULD NOT combine multiple list members unless they are all 2774 under the same organizational control and the hosts have already been 2775 replaced by pseudonyms. A sender MUST NOT combine members that have 2776 different received-protocol values. 2778 7.7. Message Transformations 2780 Some intermediaries include features for transforming messages and 2781 their content. A proxy might, for example, convert between image 2782 formats in order to save cache space or to reduce the amount of 2783 traffic on a slow link. However, operational problems might occur 2784 when these transformations are applied to content intended for 2785 critical applications, such as medical imaging or scientific data 2786 analysis, particularly when integrity checks or digital signatures 2787 are used to ensure that the content received is identical to the 2788 original. 2790 An HTTP-to-HTTP proxy is called a _transforming proxy_ if it is 2791 designed or configured to modify messages in a semantically 2792 meaningful way (i.e., modifications, beyond those required by normal 2793 HTTP processing, that change the message in a way that would be 2794 significant to the original sender or potentially significant to 2795 downstream recipients). For example, a transforming proxy might be 2796 acting as a shared annotation server (modifying responses to include 2797 references to a local annotation database), a malware filter, a 2798 format transcoder, or a privacy filter. Such transformations are 2799 presumed to be desired by whichever client (or client organization) 2800 chose the proxy. 2802 If a proxy receives a target URI with a host name that is not a fully 2803 qualified domain name, it MAY add its own domain to the host name it 2804 received when forwarding the request. A proxy MUST NOT change the 2805 host name if the target URI contains a fully qualified domain name. 2807 A proxy MUST NOT modify the "absolute-path" and "query" parts of the 2808 received target URI when forwarding it to the next inbound server 2809 except as required by that forwarding protocol. For example, a proxy 2810 forwarding a request to an origin server via HTTP/1.1 will replace an 2811 empty path with "/" (Section 3.2.1 of [HTTP/1.1]) or "*" 2812 (Section 3.2.4 of [HTTP/1.1]), depending on the request method. 2814 A proxy MUST NOT transform the content (Section 6.4) of a message 2815 that contains a no-transform cache-control response directive 2816 (Section 5.2 of [CACHING]). Note that this does not include changes 2817 to the message body that do not affect the content, such as transfer 2818 codings (Section 7 of [HTTP/1.1]). 2820 A proxy MAY transform the content of a message that does not contain 2821 a no-transform cache-control directive. A proxy that transforms the 2822 content of a 200 (OK) response can inform downstream recipients that 2823 a transformation has been applied by changing the response status 2824 code to 203 (Non-Authoritative Information) (Section 15.3.4). 2826 A proxy SHOULD NOT modify header fields that provide information 2827 about the endpoints of the communication chain, the resource state, 2828 or the selected representation (other than the content) unless the 2829 field's definition specifically allows such modification or the 2830 modification is deemed necessary for privacy or security. 2832 7.8. Upgrade 2834 The "Upgrade" header field is intended to provide a simple mechanism 2835 for transitioning from HTTP/1.1 to some other protocol on the same 2836 connection. 2838 A client MAY send a list of protocol names in the Upgrade header 2839 field of a request to invite the server to switch to one or more of 2840 the named protocols, in order of descending preference, before 2841 sending the final response. A server MAY ignore a received Upgrade 2842 header field if it wishes to continue using the current protocol on 2843 that connection. Upgrade cannot be used to insist on a protocol 2844 change. 2846 Upgrade = #protocol 2848 protocol = protocol-name ["/" protocol-version] 2849 protocol-name = token 2850 protocol-version = token 2852 Although protocol names are registered with a preferred case, 2853 recipients SHOULD use case-insensitive comparison when matching each 2854 protocol-name to supported protocols. 2856 A server that sends a 101 (Switching Protocols) response MUST send an 2857 Upgrade header field to indicate the new protocol(s) to which the 2858 connection is being switched; if multiple protocol layers are being 2859 switched, the sender MUST list the protocols in layer-ascending 2860 order. A server MUST NOT switch to a protocol that was not indicated 2861 by the client in the corresponding request's Upgrade header field. A 2862 server MAY choose to ignore the order of preference indicated by the 2863 client and select the new protocol(s) based on other factors, such as 2864 the nature of the request or the current load on the server. 2866 A server that sends a 426 (Upgrade Required) response MUST send an 2867 Upgrade header field to indicate the acceptable protocols, in order 2868 of descending preference. 2870 A server MAY send an Upgrade header field in any other response to 2871 advertise that it implements support for upgrading to the listed 2872 protocols, in order of descending preference, when appropriate for a 2873 future request. 2875 The following is a hypothetical example sent by a client: 2877 GET /hello HTTP/1.1 2878 Host: www.example.com 2879 Connection: upgrade 2880 Upgrade: websocket, IRC/6.9, RTA/x11 2882 The capabilities and nature of the application-level communication 2883 after the protocol change is entirely dependent upon the new 2884 protocol(s) chosen. However, immediately after sending the 101 2885 (Switching Protocols) response, the server is expected to continue 2886 responding to the original request as if it had received its 2887 equivalent within the new protocol (i.e., the server still has an 2888 outstanding request to satisfy after the protocol has been changed, 2889 and is expected to do so without requiring the request to be 2890 repeated). 2892 For example, if the Upgrade header field is received in a GET request 2893 and the server decides to switch protocols, it first responds with a 2894 101 (Switching Protocols) message in HTTP/1.1 and then immediately 2895 follows that with the new protocol's equivalent of a response to a 2896 GET on the target resource. This allows a connection to be upgraded 2897 to protocols with the same semantics as HTTP without the latency cost 2898 of an additional round trip. A server MUST NOT switch protocols 2899 unless the received message semantics can be honored by the new 2900 protocol; an OPTIONS request can be honored by any protocol. 2902 The following is an example response to the above hypothetical 2903 request: 2905 HTTP/1.1 101 Switching Protocols 2906 Connection: upgrade 2907 Upgrade: websocket 2909 [... data stream switches to websocket with an appropriate response 2910 (as defined by new protocol) to the "GET /hello" request ...] 2912 A sender of Upgrade MUST also send an "Upgrade" connection option in 2913 the Connection header field (Section 7.6.1) to inform intermediaries 2914 not to forward this field. A server that receives an Upgrade header 2915 field in an HTTP/1.0 request MUST ignore that Upgrade field. 2917 A client cannot begin using an upgraded protocol on the connection 2918 until it has completely sent the request message (i.e., the client 2919 can't change the protocol it is sending in the middle of a message). 2920 If a server receives both an Upgrade and an Expect header field with 2921 the "100-continue" expectation (Section 10.1.1), the server MUST send 2922 a 100 (Continue) response before sending a 101 (Switching Protocols) 2923 response. 2925 The Upgrade header field only applies to switching protocols on top 2926 of the existing connection; it cannot be used to switch the 2927 underlying connection (transport) protocol, nor to switch the 2928 existing communication to a different connection. For those 2929 purposes, it is more appropriate to use a 3xx (Redirection) response 2930 (Section 15.4). 2932 This specification only defines the protocol name "HTTP" for use by 2933 the family of Hypertext Transfer Protocols, as defined by the HTTP 2934 version rules of Section 2.5 and future updates to this 2935 specification. Additional protocol names ought to be registered 2936 using the registration procedure defined in Section 16.7. 2938 8. Representation Data and Metadata 2940 8.1. Representation Data 2942 The representation data associated with an HTTP message is either 2943 provided as the content of the message or referred to by the message 2944 semantics and the target URI. The representation data is in a format 2945 and encoding defined by the representation metadata header fields. 2947 The data type of the representation data is determined via the header 2948 fields Content-Type and Content-Encoding. These define a two-layer, 2949 ordered encoding model: 2951 representation-data := Content-Encoding( Content-Type( data ) ) 2953 8.2. Representation Metadata 2955 Representation header fields provide metadata about the 2956 representation. When a message includes content, the representation 2957 header fields describe how to interpret that data. In a response to 2958 a HEAD request, the representation header fields describe the 2959 representation data that would have been enclosed in the content if 2960 the same request had been a GET. 2962 8.3. Content-Type 2964 The "Content-Type" header field indicates the media type of the 2965 associated representation: either the representation enclosed in the 2966 message content or the selected representation, as determined by the 2967 message semantics. The indicated media type defines both the data 2968 format and how that data is intended to be processed by a recipient, 2969 within the scope of the received message semantics, after any content 2970 codings indicated by Content-Encoding are decoded. 2972 Content-Type = media-type 2974 Media types are defined in Section 8.3.1. An example of the field is 2976 Content-Type: text/html; charset=ISO-8859-4 2977 A sender that generates a message containing content SHOULD generate 2978 a Content-Type header field in that message unless the intended media 2979 type of the enclosed representation is unknown to the sender. If a 2980 Content-Type header field is not present, the recipient MAY either 2981 assume a media type of "application/octet-stream" ([RFC2046], 2982 Section 4.5.1) or examine the data to determine its type. 2984 In practice, resource owners do not always properly configure their 2985 origin server to provide the correct Content-Type for a given 2986 representation. Some user agents examine the content and, in certain 2987 cases, override the received type (for example, see [Sniffing]). 2988 This "MIME sniffing" risks drawing incorrect conclusions about the 2989 data, which might expose the user to additional security risks (e.g., 2990 "privilege escalation"). Furthermore, distinct media types often 2991 share a common data format, differing only in how the data is 2992 intended to be processed, which is impossible to distinguish by 2993 inspecting the data alone. When sniffing is implemented, 2994 implementers are encouraged to provide a means for the user to 2995 disable it. 2997 Although Content-Type is defined as a singleton field, it is 2998 sometimes incorrectly generated multiple times, resulting in a 2999 combined field value that appears to be a list. Recipients often 3000 attempt to handle this error by using the last syntactically valid 3001 member of the list, leading to potential interoperability and 3002 security issues if different implementations have different error 3003 handling behaviors. 3005 8.3.1. Media Type 3007 HTTP uses media types [RFC2046] in the Content-Type (Section 8.3) and 3008 Accept (Section 12.5.1) header fields in order to provide open and 3009 extensible data typing and type negotiation. Media types define both 3010 a data format and various processing models: how to process that data 3011 in accordance with the message context. 3013 media-type = type "/" subtype parameters 3014 type = token 3015 subtype = token 3017 The type and subtype tokens are case-insensitive. 3019 The type/subtype MAY be followed by semicolon-delimited parameters 3020 (Section 5.6.6) in the form of name=value pairs. The presence or 3021 absence of a parameter might be significant to the processing of a 3022 media type, depending on its definition within the media type 3023 registry. Parameter values might or might not be case-sensitive, 3024 depending on the semantics of the parameter name. 3026 For example, the following media types are equivalent in describing 3027 HTML text data encoded in the UTF-8 character encoding scheme, but 3028 the first is preferred for consistency (the "charset" parameter value 3029 is defined as being case-insensitive in [RFC2046], Section 4.1.2): 3031 text/html;charset=utf-8 3032 Text/HTML;Charset="utf-8" 3033 text/html; charset="utf-8" 3034 text/html;charset=UTF-8 3036 Media types ought to be registered with IANA according to the 3037 procedures defined in [BCP13]. 3039 8.3.2. Charset 3041 HTTP uses _charset_ names to indicate or negotiate the character 3042 encoding scheme ([RFC6365], Section 1.3) of a textual representation. 3043 In the fields defined by this document, charset names appear either 3044 in parameters (Content-Type), or, for Accept-Encoding, in the form of 3045 a plain token. In both cases, charset names are matched case- 3046 insensitively. 3048 Charset names ought to be registered in the IANA "Character Sets" 3049 registry () 3050 according to the procedures defined in Section 2 of [RFC2978]. 3052 | *Note:* In theory, charset names are defined by the "mime- 3053 | charset" ABNF rule defined in Section 2.3 of [RFC2978] (as 3054 | corrected in [Err1912]). That rule allows two characters that 3055 | are not included in "token" ("{" and "}"), but no charset name 3056 | registered at the time of this writing includes braces (see 3057 | [Err5433]). 3059 8.3.3. Multipart Types 3061 MIME provides for a number of "multipart" types - encapsulations of 3062 one or more representations within a single message body. All 3063 multipart types share a common syntax, as defined in Section 5.1.1 of 3064 [RFC2046], and include a boundary parameter as part of the media type 3065 value. The message body is itself a protocol element; a sender MUST 3066 generate only CRLF to represent line breaks between body parts. 3068 HTTP message framing does not use the multipart boundary as an 3069 indicator of message body length, though it might be used by 3070 implementations that generate or process the content. For example, 3071 the "multipart/form-data" type is often used for carrying form data 3072 in a request, as described in [RFC7578], and the "multipart/ 3073 byteranges" type is defined by this specification for use in some 206 3074 (Partial Content) responses (see Section 15.3.7). 3076 8.4. Content-Encoding 3078 The "Content-Encoding" header field indicates what content codings 3079 have been applied to the representation, beyond those inherent in the 3080 media type, and thus what decoding mechanisms have to be applied in 3081 order to obtain data in the media type referenced by the Content-Type 3082 header field. Content-Encoding is primarily used to allow a 3083 representation's data to be compressed without losing the identity of 3084 its underlying media type. 3086 Content-Encoding = #content-coding 3088 An example of its use is 3090 Content-Encoding: gzip 3092 If one or more encodings have been applied to a representation, the 3093 sender that applied the encodings MUST generate a Content-Encoding 3094 header field that lists the content codings in the order in which 3095 they were applied. Note that the coding named "identity" is reserved 3096 for its special role in Accept-Encoding, and thus SHOULD NOT be 3097 included. 3099 Additional information about the encoding parameters can be provided 3100 by other header fields not defined by this specification. 3102 Unlike Transfer-Encoding (Section 6.1 of [HTTP/1.1]), the codings 3103 listed in Content-Encoding are a characteristic of the 3104 representation; the representation is defined in terms of the coded 3105 form, and all other metadata about the representation is about the 3106 coded form unless otherwise noted in the metadata definition. 3107 Typically, the representation is only decoded just prior to rendering 3108 or analogous usage. 3110 If the media type includes an inherent encoding, such as a data 3111 format that is always compressed, then that encoding would not be 3112 restated in Content-Encoding even if it happens to be the same 3113 algorithm as one of the content codings. Such a content coding would 3114 only be listed if, for some bizarre reason, it is applied a second 3115 time to form the representation. Likewise, an origin server might 3116 choose to publish the same data as multiple representations that 3117 differ only in whether the coding is defined as part of Content-Type 3118 or Content-Encoding, since some user agents will behave differently 3119 in their handling of each response (e.g., open a "Save as ..." dialog 3120 instead of automatic decompression and rendering of content). 3122 An origin server MAY respond with a status code of 415 (Unsupported 3123 Media Type) if a representation in the request message has a content 3124 coding that is not acceptable. 3126 8.4.1. Content Codings 3128 Content coding values indicate an encoding transformation that has 3129 been or can be applied to a representation. Content codings are 3130 primarily used to allow a representation to be compressed or 3131 otherwise usefully transformed without losing the identity of its 3132 underlying media type and without loss of information. Frequently, 3133 the representation is stored in coded form, transmitted directly, and 3134 only decoded by the final recipient. 3136 content-coding = token 3138 All content codings are case-insensitive and ought to be registered 3139 within the "HTTP Content Coding Registry", as described in 3140 Section 16.6 3142 Content-coding values are used in the Accept-Encoding 3143 (Section 12.5.3) and Content-Encoding (Section 8.4) header fields. 3145 8.4.1.1. Compress Coding 3147 The "compress" coding is an adaptive Lempel-Ziv-Welch (LZW) coding 3148 [Welch] that is commonly produced by the UNIX file compression 3149 program "compress". A recipient SHOULD consider "x-compress" to be 3150 equivalent to "compress". 3152 8.4.1.2. Deflate Coding 3154 The "deflate" coding is a "zlib" data format [RFC1950] containing a 3155 "deflate" compressed data stream [RFC1951] that uses a combination of 3156 the Lempel-Ziv (LZ77) compression algorithm and Huffman coding. 3158 | *Note:* Some non-conformant implementations send the "deflate" 3159 | compressed data without the zlib wrapper. 3161 8.4.1.3. Gzip Coding 3163 The "gzip" coding is an LZ77 coding with a 32-bit Cyclic Redundancy 3164 Check (CRC) that is commonly produced by the gzip file compression 3165 program [RFC1952]. A recipient SHOULD consider "x-gzip" to be 3166 equivalent to "gzip". 3168 8.5. Content-Language 3170 The "Content-Language" header field describes the natural language(s) 3171 of the intended audience for the representation. Note that this 3172 might not be equivalent to all the languages used within the 3173 representation. 3175 Content-Language = #language-tag 3177 Language tags are defined in Section 8.5.1. The primary purpose of 3178 Content-Language is to allow a user to identify and differentiate 3179 representations according to the users' own preferred language. 3180 Thus, if the content is intended only for a Danish-literate audience, 3181 the appropriate field is 3183 Content-Language: da 3185 If no Content-Language is specified, the default is that the content 3186 is intended for all language audiences. This might mean that the 3187 sender does not consider it to be specific to any natural language, 3188 or that the sender does not know for which language it is intended. 3190 Multiple languages MAY be listed for content that is intended for 3191 multiple audiences. For example, a rendition of the "Treaty of 3192 Waitangi", presented simultaneously in the original Maori and English 3193 versions, would call for 3195 Content-Language: mi, en 3197 However, just because multiple languages are present within a 3198 representation does not mean that it is intended for multiple 3199 linguistic audiences. An example would be a beginner's language 3200 primer, such as "A First Lesson in Latin", which is clearly intended 3201 to be used by an English-literate audience. In this case, the 3202 Content-Language would properly only include "en". 3204 Content-Language MAY be applied to any media type - it is not limited 3205 to textual documents. 3207 8.5.1. Language Tags 3209 A language tag, as defined in [RFC5646], identifies a natural 3210 language spoken, written, or otherwise conveyed by human beings for 3211 communication of information to other human beings. Computer 3212 languages are explicitly excluded. 3214 HTTP uses language tags within the Accept-Language and 3215 Content-Language header fields. Accept-Language uses the broader 3216 language-range production defined in Section 12.5.4, whereas 3217 Content-Language uses the language-tag production defined below. 3219 language-tag = 3221 A language tag is a sequence of one or more case-insensitive subtags, 3222 each separated by a hyphen character ("-", %x2D). In most cases, a 3223 language tag consists of a primary language subtag that identifies a 3224 broad family of related languages (e.g., "en" = English), which is 3225 optionally followed by a series of subtags that refine or narrow that 3226 language's range (e.g., "en-CA" = the variety of English as 3227 communicated in Canada). Whitespace is not allowed within a language 3228 tag. Example tags include: 3230 fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN 3232 See [RFC5646] for further information. 3234 8.6. Content-Length 3236 The "Content-Length" header field indicates the associated 3237 representation's data length as a decimal non-negative integer number 3238 of octets. When transferring a representation as content, Content- 3239 Length refers specifically to the amount of data enclosed so that it 3240 can be used to delimit framing (e.g., Section 6.2 of [HTTP/1.1]). In 3241 other cases, Content-Length indicates the selected representation's 3242 current length, which can be used by recipients to estimate transfer 3243 time or compare to previously stored representations. 3245 Content-Length = 1*DIGIT 3247 An example is 3249 Content-Length: 3495 3251 A user agent SHOULD send Content-Length in a request when the method 3252 defines a meaning for enclosed content and it is not sending 3253 Transfer-Encoding. For example, a user agent normally sends Content- 3254 Length in a POST request even when the value is 0 (indicating empty 3255 content). A user agent SHOULD NOT send a Content-Length header field 3256 when the request message does not contain content and the method 3257 semantics do not anticipate such data. 3259 A server MAY send a Content-Length header field in a response to a 3260 HEAD request (Section 9.3.2); a server MUST NOT send Content-Length 3261 in such a response unless its field value equals the decimal number 3262 of octets that would have been sent in the content of a response if 3263 the same request had used the GET method. 3265 A server MAY send a Content-Length header field in a 304 (Not 3266 Modified) response to a conditional GET request (Section 15.4.5); a 3267 server MUST NOT send Content-Length in such a response unless its 3268 field value equals the decimal number of octets that would have been 3269 sent in the content of a 200 (OK) response to the same request. 3271 A server MUST NOT send a Content-Length header field in any response 3272 with a status code of 1xx (Informational) or 204 (No Content). A 3273 server MUST NOT send a Content-Length header field in any 2xx 3274 (Successful) response to a CONNECT request (Section 9.3.6). 3276 Aside from the cases defined above, in the absence of Transfer- 3277 Encoding, an origin server SHOULD send a Content-Length header field 3278 when the content size is known prior to sending the complete header 3279 section. This will allow downstream recipients to measure transfer 3280 progress, know when a received message is complete, and potentially 3281 reuse the connection for additional requests. 3283 Any Content-Length field value greater than or equal to zero is 3284 valid. Since there is no predefined limit to the length of content, 3285 a recipient MUST anticipate potentially large decimal numerals and 3286 prevent parsing errors due to integer conversion overflows or 3287 precision loss due to integer conversion (Section 17.5). 3289 Because Content-Length is used for message delimitation in HTTP/1.1, 3290 its field value can impact how the message is parsed by downstream 3291 recipients even when the immediate connection is not using HTTP/1.1. 3292 If the message is forwarded by a downstream intermediary, a Content- 3293 Length field value that is inconsistent with the received message 3294 framing might cause a security failure due to request smuggling or 3295 response splitting. 3297 As a result, a sender MUST NOT forward a message with a Content- 3298 Length header field value that is known to be incorrect. 3300 Likewise, a sender MUST NOT forward a message with a Content-Length 3301 header field value that does not match the ABNF above, with one 3302 exception: A recipient of a Content-Length header field value 3303 consisting of the same decimal value repeated as a comma-separated 3304 list (e.g, "Content-Length: 42, 42"), MAY either reject the message 3305 as invalid or replace that invalid field value with a single instance 3306 of the decimal value, since this likely indicates that a duplicate 3307 was generated or combined by an upstream message processor. 3309 8.7. Content-Location 3311 The "Content-Location" header field references a URI that can be used 3312 as an identifier for a specific resource corresponding to the 3313 representation in this message's content. In other words, if one 3314 were to perform a GET request on this URI at the time of this 3315 message's generation, then a 200 (OK) response would contain the same 3316 representation that is enclosed as content in this message. 3318 Content-Location = absolute-URI / partial-URI 3320 The field value is either an absolute-URI or a partial-URI. In the 3321 latter case (Section 4), the referenced URI is relative to the target 3322 URI ([URI], Section 5). 3324 The Content-Location value is not a replacement for the target URI 3325 (Section 7.1). It is representation metadata. It has the same 3326 syntax and semantics as the header field of the same name defined for 3327 MIME body parts in Section 4 of [RFC2557]. However, its appearance 3328 in an HTTP message has some special implications for HTTP recipients. 3330 If Content-Location is included in a 2xx (Successful) response 3331 message and its value refers (after conversion to absolute form) to a 3332 URI that is the same as the target URI, then the recipient MAY 3333 consider the content to be a current representation of that resource 3334 at the time indicated by the message origination date. For a GET 3335 (Section 9.3.1) or HEAD (Section 9.3.2) request, this is the same as 3336 the default semantics when no Content-Location is provided by the 3337 server. For a state-changing request like PUT (Section 9.3.4) or 3338 POST (Section 9.3.3), it implies that the server's response contains 3339 the new representation of that resource, thereby distinguishing it 3340 from representations that might only report about the action (e.g., 3341 "It worked!"). This allows authoring applications to update their 3342 local copies without the need for a subsequent GET request. 3344 If Content-Location is included in a 2xx (Successful) response 3345 message and its field value refers to a URI that differs from the 3346 target URI, then the origin server claims that the URI is an 3347 identifier for a different resource corresponding to the enclosed 3348 representation. Such a claim can only be trusted if both identifiers 3349 share the same resource owner, which cannot be programmatically 3350 determined via HTTP. 3352 * For a response to a GET or HEAD request, this is an indication 3353 that the target URI refers to a resource that is subject to 3354 content negotiation and the Content-Location field value is a more 3355 specific identifier for the selected representation. 3357 * For a 201 (Created) response to a state-changing method, a 3358 Content-Location field value that is identical to the Location 3359 field value indicates that this content is a current 3360 representation of the newly created resource. 3362 * Otherwise, such a Content-Location indicates that this content is 3363 a representation reporting on the requested action's status and 3364 that the same report is available (for future access with GET) at 3365 the given URI. For example, a purchase transaction made via a 3366 POST request might include a receipt document as the content of 3367 the 200 (OK) response; the Content-Location field value provides 3368 an identifier for retrieving a copy of that same receipt in the 3369 future. 3371 A user agent that sends Content-Location in a request message is 3372 stating that its value refers to where the user agent originally 3373 obtained the content of the enclosed representation (prior to any 3374 modifications made by that user agent). In other words, the user 3375 agent is providing a back link to the source of the original 3376 representation. 3378 An origin server that receives a Content-Location field in a request 3379 message MUST treat the information as transitory request context 3380 rather than as metadata to be saved verbatim as part of the 3381 representation. An origin server MAY use that context to guide in 3382 processing the request or to save it for other uses, such as within 3383 source links or versioning metadata. However, an origin server MUST 3384 NOT use such context information to alter the request semantics. 3386 For example, if a client makes a PUT request on a negotiated resource 3387 and the origin server accepts that PUT (without redirection), then 3388 the new state of that resource is expected to be consistent with the 3389 one representation supplied in that PUT; the Content-Location cannot 3390 be used as a form of reverse content selection identifier to update 3391 only one of the negotiated representations. If the user agent had 3392 wanted the latter semantics, it would have applied the PUT directly 3393 to the Content-Location URI. 3395 8.8. Validator Fields 3397 Resource metadata is referred to as a _validator_ if it can be used 3398 within a precondition (Section 13.1) to make a conditional request 3399 (Section 13). Validator fields convey a current validator for the 3400 selected representation (Section 3.2). 3402 In responses to safe requests, validator fields describe the selected 3403 representation chosen by the origin server while handling the 3404 response. Note that, depending on the method and status code 3405 semantics, the selected representation for a given response is not 3406 necessarily the same as the representation enclosed as response 3407 content. 3409 In a successful response to a state-changing request, validator 3410 fields describe the new representation that has replaced the prior 3411 selected representation as a result of processing the request. 3413 For example, an ETag field in a 201 (Created) response communicates 3414 the entity-tag of the newly created resource's representation, so 3415 that the entity-tag can be used as a validator in later conditional 3416 requests to prevent the "lost update" problem. 3418 This specification defines two forms of metadata that are commonly 3419 used to observe resource state and test for preconditions: 3420 modification dates (Section 8.8.2) and opaque entity tags 3421 (Section 8.8.3). Additional metadata that reflects resource state 3422 has been defined by various extensions of HTTP, such as Web 3423 Distributed Authoring and Versioning [WEBDAV], that are beyond the 3424 scope of this specification. 3426 8.8.1. Weak versus Strong 3428 Validators come in two flavors: strong or weak. Weak validators are 3429 easy to generate but are far less useful for comparisons. Strong 3430 validators are ideal for comparisons but can be very difficult (and 3431 occasionally impossible) to generate efficiently. Rather than impose 3432 that all forms of resource adhere to the same strength of validator, 3433 HTTP exposes the type of validator in use and imposes restrictions on 3434 when weak validators can be used as preconditions. 3436 A _strong validator_ is representation metadata that changes value 3437 whenever a change occurs to the representation data that would be 3438 observable in the content of a 200 (OK) response to GET. 3440 A strong validator might change for reasons other than a change to 3441 the representation data, such as when a semantically significant part 3442 of the representation metadata is changed (e.g., Content-Type), but 3443 it is in the best interests of the origin server to only change the 3444 value when it is necessary to invalidate the stored responses held by 3445 remote caches and authoring tools. 3447 Cache entries might persist for arbitrarily long periods, regardless 3448 of expiration times. Thus, a cache might attempt to validate an 3449 entry using a validator that it obtained in the distant past. A 3450 strong validator is unique across all versions of all representations 3451 associated with a particular resource over time. However, there is 3452 no implication of uniqueness across representations of different 3453 resources (i.e., the same strong validator might be in use for 3454 representations of multiple resources at the same time and does not 3455 imply that those representations are equivalent). 3457 There are a variety of strong validators used in practice. The best 3458 are based on strict revision control, wherein each change to a 3459 representation always results in a unique node name and revision 3460 identifier being assigned before the representation is made 3461 accessible to GET. A collision-resistant hash function applied to 3462 the representation data is also sufficient if the data is available 3463 prior to the response header fields being sent and the digest does 3464 not need to be recalculated every time a validation request is 3465 received. However, if a resource has distinct representations that 3466 differ only in their metadata, such as might occur with content 3467 negotiation over media types that happen to share the same data 3468 format, then the origin server needs to incorporate additional 3469 information in the validator to distinguish those representations. 3471 In contrast, a _weak validator_ is representation metadata that might 3472 not change for every change to the representation data. This 3473 weakness might be due to limitations in how the value is calculated 3474 (e.g., clock resolution), an inability to ensure uniqueness for all 3475 possible representations of the resource, or a desire of the resource 3476 owner to group representations by some self-determined set of 3477 equivalency rather than unique sequences of data. 3479 An origin server SHOULD change a weak entity-tag whenever it 3480 considers prior representations to be unacceptable as a substitute 3481 for the current representation. In other words, a weak entity-tag 3482 ought to change whenever the origin server wants caches to invalidate 3483 old responses. 3485 For example, the representation of a weather report that changes in 3486 content every second, based on dynamic measurements, might be grouped 3487 into sets of equivalent representations (from the origin server's 3488 perspective) with the same weak validator in order to allow cached 3489 representations to be valid for a reasonable period of time (perhaps 3490 adjusted dynamically based on server load or weather quality). 3492 Likewise, a representation's modification time, if defined with only 3493 one-second resolution, might be a weak validator if it is possible 3494 for the representation to be modified twice during a single second 3495 and retrieved between those modifications. 3497 Likewise, a validator is weak if it is shared by two or more 3498 representations of a given resource at the same time, unless those 3499 representations have identical representation data. For example, if 3500 the origin server sends the same validator for a representation with 3501 a gzip content coding applied as it does for a representation with no 3502 content coding, then that validator is weak. However, two 3503 simultaneous representations might share the same strong validator if 3504 they differ only in the representation metadata, such as when two 3505 different media types are available for the same representation data. 3507 Strong validators are usable for all conditional requests, including 3508 cache validation, partial content ranges, and "lost update" 3509 avoidance. Weak validators are only usable when the client does not 3510 require exact equality with previously obtained representation data, 3511 such as when validating a cache entry or limiting a web traversal to 3512 recent changes. 3514 8.8.2. Last-Modified 3516 The "Last-Modified" header field in a response provides a timestamp 3517 indicating the date and time at which the origin server believes the 3518 selected representation was last modified, as determined at the 3519 conclusion of handling the request. 3521 Last-Modified = HTTP-date 3523 An example of its use is 3525 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 3527 8.8.2.1. Generation 3529 An origin server SHOULD send Last-Modified for any selected 3530 representation for which a last modification date can be reasonably 3531 and consistently determined, since its use in conditional requests 3532 and evaluating cache freshness ([CACHING]) can substantially reduce 3533 unnecessary transfers and significantly improve service availability 3534 and scalability. 3536 A representation is typically the sum of many parts behind the 3537 resource interface. The last-modified time would usually be the most 3538 recent time that any of those parts were changed. How that value is 3539 determined for any given resource is an implementation detail beyond 3540 the scope of this specification. 3542 An origin server SHOULD obtain the Last-Modified value of the 3543 representation as close as possible to the time that it generates the 3544 Date field value for its response. This allows a recipient to make 3545 an accurate assessment of the representation's modification time, 3546 especially if the representation changes near the time that the 3547 response is generated. 3549 An origin server with a clock (as defined in Section 5.6.7) MUST NOT 3550 generate a Last-Modified date that is later than the server's time of 3551 message origination (Date, Section 6.6.1). If the last modification 3552 time is derived from implementation-specific metadata that evaluates 3553 to some time in the future, according to the origin server's clock, 3554 then the origin server MUST replace that value with the message 3555 origination date. This prevents a future modification date from 3556 having an adverse impact on cache validation. 3558 An origin server without a clock MUST NOT generate a Last-Modified 3559 date for a response unless that date value was assigned to the 3560 resource by some other system (presumably one with a clock). 3562 8.8.2.2. Comparison 3564 A Last-Modified time, when used as a validator in a request, is 3565 implicitly weak unless it is possible to deduce that it is strong, 3566 using the following rules: 3568 * The validator is being compared by an origin server to the actual 3569 current validator for the representation and, 3571 * That origin server reliably knows that the associated 3572 representation did not change twice during the second covered by 3573 the presented validator; 3575 or 3577 * The validator is about to be used by a client in an 3578 If-Modified-Since, If-Unmodified-Since, or If-Range header field, 3579 because the client has a cache entry for the associated 3580 representation, and 3582 * That cache entry includes a Date value which is at least one 3583 second after the Last-Modified value and the client has reason to 3584 believe that they were generated by the same clock or that there 3585 is enough difference between the Last-Modified and Date values to 3586 make clock synchronization issues unlikely; 3588 or 3590 * The validator is being compared by an intermediate cache to the 3591 validator stored in its cache entry for the representation, and 3593 * That cache entry includes a Date value which is at least one 3594 second after the Last-Modified value and the cache has reason to 3595 believe that they were generated by the same clock or that there 3596 is enough difference between the Last-Modified and Date values to 3597 make clock synchronization issues unlikely. 3599 This method relies on the fact that if two different responses were 3600 sent by the origin server during the same second, but both had the 3601 same Last-Modified time, then at least one of those responses would 3602 have a Date value equal to its Last-Modified time. 3604 8.8.3. ETag 3606 The "ETag" field in a response provides the current entity-tag for 3607 the selected representation, as determined at the conclusion of 3608 handling the request. An entity-tag is an opaque validator for 3609 differentiating between multiple representations of the same 3610 resource, regardless of whether those multiple representations are 3611 due to resource state changes over time, content negotiation 3612 resulting in multiple representations being valid at the same time, 3613 or both. An entity-tag consists of an opaque quoted string, possibly 3614 prefixed by a weakness indicator. 3616 ETag = entity-tag 3618 entity-tag = [ weak ] opaque-tag 3619 weak = %s"W/" 3620 opaque-tag = DQUOTE *etagc DQUOTE 3621 etagc = %x21 / %x23-7E / obs-text 3622 ; VCHAR except double quotes, plus obs-text 3624 | *Note:* Previously, opaque-tag was defined to be a quoted- 3625 | string ([RFC2616], Section 3.11); thus, some recipients might 3626 | perform backslash unescaping. Servers therefore ought to avoid 3627 | backslash characters in entity tags. 3629 An entity-tag can be more reliable for validation than a modification 3630 date in situations where it is inconvenient to store modification 3631 dates, where the one-second resolution of HTTP date values is not 3632 sufficient, or where modification dates are not consistently 3633 maintained. 3635 Examples: 3637 ETag: "xyzzy" 3638 ETag: W/"xyzzy" 3639 ETag: "" 3641 An entity-tag can be either a weak or strong validator, with strong 3642 being the default. If an origin server provides an entity-tag for a 3643 representation and the generation of that entity-tag does not satisfy 3644 all of the characteristics of a strong validator (Section 8.8.1), 3645 then the origin server MUST mark the entity-tag as weak by prefixing 3646 its opaque value with "W/" (case-sensitive). 3648 A sender MAY send the Etag field in a trailer section (see 3649 Section 6.5). However, since trailers are often ignored, it is 3650 preferable to send Etag as a header field unless the entity-tag is 3651 generated while sending the content. 3653 8.8.3.1. Generation 3655 The principle behind entity-tags is that only the service author 3656 knows the implementation of a resource well enough to select the most 3657 accurate and efficient validation mechanism for that resource, and 3658 that any such mechanism can be mapped to a simple sequence of octets 3659 for easy comparison. Since the value is opaque, there is no need for 3660 the client to be aware of how each entity-tag is constructed. 3662 For example, a resource that has implementation-specific versioning 3663 applied to all changes might use an internal revision number, perhaps 3664 combined with a variance identifier for content negotiation, to 3665 accurately differentiate between representations. Other 3666 implementations might use a collision-resistant hash of 3667 representation content, a combination of various file attributes, or 3668 a modification timestamp that has sub-second resolution. 3670 An origin server SHOULD send an ETag for any selected representation 3671 for which detection of changes can be reasonably and consistently 3672 determined, since the entity-tag's use in conditional requests and 3673 evaluating cache freshness ([CACHING]) can substantially reduce 3674 unnecessary transfers and significantly improve service availability, 3675 scalability, and reliability. 3677 8.8.3.2. Comparison 3679 There are two entity-tag comparison functions, depending on whether 3680 or not the comparison context allows the use of weak validators: 3682 _Strong comparison_: two entity-tags are equivalent if both are not 3683 weak and their opaque-tags match character-by-character. 3685 _Weak comparison_: two entity-tags are equivalent if their opaque- 3686 tags match character-by-character, regardless of either or both 3687 being tagged as "weak". 3689 The example below shows the results for a set of entity-tag pairs and 3690 both the weak and strong comparison function results: 3692 +========+========+===================+=================+ 3693 | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | 3694 +========+========+===================+=================+ 3695 | W/"1" | W/"1" | no match | match | 3696 +--------+--------+-------------------+-----------------+ 3697 | W/"1" | W/"2" | no match | no match | 3698 +--------+--------+-------------------+-----------------+ 3699 | W/"1" | "1" | no match | match | 3700 +--------+--------+-------------------+-----------------+ 3701 | "1" | "1" | match | match | 3702 +--------+--------+-------------------+-----------------+ 3704 Table 3 3706 8.8.3.3. Example: Entity-Tags Varying on Content-Negotiated Resources 3708 Consider a resource that is subject to content negotiation 3709 (Section 12), and where the representations sent in response to a GET 3710 request vary based on the Accept-Encoding request header field 3711 (Section 12.5.3): 3713 >> Request: 3715 GET /index HTTP/1.1 3716 Host: www.example.com 3717 Accept-Encoding: gzip 3719 In this case, the response might or might not use the gzip content 3720 coding. If it does not, the response might look like: 3722 >> Response: 3724 HTTP/1.1 200 OK 3725 Date: Fri, 26 Mar 2010 00:05:00 GMT 3726 ETag: "123-a" 3727 Content-Length: 70 3728 Vary: Accept-Encoding 3729 Content-Type: text/plain 3731 Hello World! 3732 Hello World! 3733 Hello World! 3734 Hello World! 3735 Hello World! 3737 An alternative representation that does use gzip content coding would 3738 be: 3740 >> Response: 3742 HTTP/1.1 200 OK 3743 Date: Fri, 26 Mar 2010 00:05:00 GMT 3744 ETag: "123-b" 3745 Content-Length: 43 3746 Vary: Accept-Encoding 3747 Content-Type: text/plain 3748 Content-Encoding: gzip 3750 ...binary data... 3752 | *Note:* Content codings are a property of the representation 3753 | data, so a strong entity-tag for a content-encoded 3754 | representation has to be distinct from the entity tag of an 3755 | unencoded representation to prevent potential conflicts during 3756 | cache updates and range requests. In contrast, transfer 3757 | codings (Section 7 of [HTTP/1.1]) apply only during message 3758 | transfer and do not result in distinct entity-tags. 3760 9. Methods 3762 9.1. Overview 3764 The request method token is the primary source of request semantics; 3765 it indicates the purpose for which the client has made this request 3766 and what is expected by the client as a successful result. 3768 The request method's semantics might be further specialized by the 3769 semantics of some header fields when present in a request if those 3770 additional semantics do not conflict with the method. For example, a 3771 client can send conditional request header fields (Section 13.1) to 3772 make the requested action conditional on the current state of the 3773 target resource. 3775 HTTP is designed to be usable as an interface to distributed object 3776 systems. The request method invokes an action to be applied to a 3777 target resource in much the same way that a remote method invocation 3778 can be sent to an identified object. 3780 method = token 3782 The method token is case-sensitive because it might be used as a 3783 gateway to object-based systems with case-sensitive method names. By 3784 convention, standardized methods are defined in all-uppercase US- 3785 ASCII letters. 3787 Unlike distributed objects, the standardized request methods in HTTP 3788 are not resource-specific, since uniform interfaces provide for 3789 better visibility and reuse in network-based systems [REST]. Once 3790 defined, a standardized method ought to have the same semantics when 3791 applied to any resource, though each resource determines for itself 3792 whether those semantics are implemented or allowed. 3794 This specification defines a number of standardized methods that are 3795 commonly used in HTTP, as outlined by the following table. 3797 +=========+============================================+=======+ 3798 | Method | Description | Ref. | 3799 +=========+============================================+=======+ 3800 | GET | Transfer a current representation of the | 9.3.1 | 3801 | | target resource. | | 3802 +---------+--------------------------------------------+-------+ 3803 | HEAD | Same as GET, but do not transfer the | 9.3.2 | 3804 | | response content. | | 3805 +---------+--------------------------------------------+-------+ 3806 | POST | Perform resource-specific processing on | 9.3.3 | 3807 | | the request content. | | 3808 +---------+--------------------------------------------+-------+ 3809 | PUT | Replace all current representations of the | 9.3.4 | 3810 | | target resource with the request content. | | 3811 +---------+--------------------------------------------+-------+ 3812 | DELETE | Remove all current representations of the | 9.3.5 | 3813 | | target resource. | | 3814 +---------+--------------------------------------------+-------+ 3815 | CONNECT | Establish a tunnel to the server | 9.3.6 | 3816 | | identified by the target resource. | | 3817 +---------+--------------------------------------------+-------+ 3818 | OPTIONS | Describe the communication options for the | 9.3.7 | 3819 | | target resource. | | 3820 +---------+--------------------------------------------+-------+ 3821 | TRACE | Perform a message loop-back test along the | 9.3.8 | 3822 | | path to the target resource. | | 3823 +---------+--------------------------------------------+-------+ 3825 Table 4 3827 All general-purpose servers MUST support the methods GET and HEAD. 3828 All other methods are OPTIONAL. 3830 The set of methods allowed by a target resource can be listed in an 3831 Allow header field (Section 10.2.1). However, the set of allowed 3832 methods can change dynamically. An origin server that receives a 3833 request method that is unrecognized or not implemented SHOULD respond 3834 with the 501 (Not Implemented) status code. An origin server that 3835 receives a request method that is recognized and implemented, but not 3836 allowed for the target resource, SHOULD respond with the 405 (Method 3837 Not Allowed) status code. 3839 Additional methods, outside the scope of this specification, have 3840 been specified for use in HTTP. All such methods ought to be 3841 registered within the "Hypertext Transfer Protocol (HTTP) Method 3842 Registry", as described in Section 16.1. 3844 9.2. Common Method Properties 3846 9.2.1. Safe Methods 3848 Request methods are considered _safe_ if their defined semantics are 3849 essentially read-only; i.e., the client does not request, and does 3850 not expect, any state change on the origin server as a result of 3851 applying a safe method to a target resource. Likewise, reasonable 3852 use of a safe method is not expected to cause any harm, loss of 3853 property, or unusual burden on the origin server. 3855 This definition of safe methods does not prevent an implementation 3856 from including behavior that is potentially harmful, that is not 3857 entirely read-only, or that causes side effects while invoking a safe 3858 method. What is important, however, is that the client did not 3859 request that additional behavior and cannot be held accountable for 3860 it. For example, most servers append request information to access 3861 log files at the completion of every response, regardless of the 3862 method, and that is considered safe even though the log storage might 3863 become full and cause the server to fail. Likewise, a safe request 3864 initiated by selecting an advertisement on the Web will often have 3865 the side effect of charging an advertising account. 3867 Of the request methods defined by this specification, the GET, HEAD, 3868 OPTIONS, and TRACE methods are defined to be safe. 3870 The purpose of distinguishing between safe and unsafe methods is to 3871 allow automated retrieval processes (spiders) and cache performance 3872 optimization (pre-fetching) to work without fear of causing harm. In 3873 addition, it allows a user agent to apply appropriate constraints on 3874 the automated use of unsafe methods when processing potentially 3875 untrusted content. 3877 A user agent SHOULD distinguish between safe and unsafe methods when 3878 presenting potential actions to a user, such that the user can be 3879 made aware of an unsafe action before it is requested. 3881 When a resource is constructed such that parameters within the target 3882 URI have the effect of selecting an action, it is the resource 3883 owner's responsibility to ensure that the action is consistent with 3884 the request method semantics. For example, it is common for Web- 3885 based content editing software to use actions within query 3886 parameters, such as "page?do=delete". If the purpose of such a 3887 resource is to perform an unsafe action, then the resource owner MUST 3888 disable or disallow that action when it is accessed using a safe 3889 request method. Failure to do so will result in unfortunate side 3890 effects when automated processes perform a GET on every URI reference 3891 for the sake of link maintenance, pre-fetching, building a search 3892 index, etc. 3894 9.2.2. Idempotent Methods 3896 A request method is considered _idempotent_ if the intended effect on 3897 the server of multiple identical requests with that method is the 3898 same as the effect for a single such request. Of the request methods 3899 defined by this specification, PUT, DELETE, and safe request methods 3900 are idempotent. 3902 Like the definition of safe, the idempotent property only applies to 3903 what has been requested by the user; a server is free to log each 3904 request separately, retain a revision control history, or implement 3905 other non-idempotent side effects for each idempotent request. 3907 Idempotent methods are distinguished because the request can be 3908 repeated automatically if a communication failure occurs before the 3909 client is able to read the server's response. For example, if a 3910 client sends a PUT request and the underlying connection is closed 3911 before any response is received, then the client can establish a new 3912 connection and retry the idempotent request. It knows that repeating 3913 the request will have the same intended effect, even if the original 3914 request succeeded, though the response might differ. 3916 A client SHOULD NOT automatically retry a request with a non- 3917 idempotent method unless it has some means to know that the request 3918 semantics are actually idempotent, regardless of the method, or some 3919 means to detect that the original request was never applied. 3921 For example, a user agent can repeat a POST request automatically if 3922 it knows (through design or configuration) that the request is safe 3923 for that resource. Likewise, a user agent designed specifically to 3924 operate on a version control repository might be able to recover from 3925 partial failure conditions by checking the target resource 3926 revision(s) after a failed connection, reverting or fixing any 3927 changes that were partially applied, and then automatically retrying 3928 the requests that failed. 3930 Some clients take a riskier approach and attempt to guess when an 3931 automatic retry is possible. For example, a client might 3932 automatically retry a POST request if the underlying transport 3933 connection closed before any part of a response is received, 3934 particularly if an idle persistent connection was used. 3936 A proxy MUST NOT automatically retry non-idempotent requests. A 3937 client SHOULD NOT automatically retry a failed automatic retry. 3939 9.2.3. Methods and Caching 3941 For a cache to store and use a response, the associated method needs 3942 to explicitly allow caching, and detail under what conditions a 3943 response can be used to satisfy subsequent requests; a method 3944 definition which does not do so cannot be cached. For additional 3945 requirements see [CACHING]. 3947 This specification defines caching semantics for GET, HEAD, and POST, 3948 although the overwhelming majority of cache implementations only 3949 support GET and HEAD. 3951 9.3. Method Definitions 3953 9.3.1. GET 3955 The GET method requests transfer of a current selected representation 3956 for the target resource. A successful response reflects the quality 3957 of "sameness" identified by the target URI (Section 1.2.2 of [URI]). 3958 Hence, retrieving identifiable information via HTTP is usually 3959 performed by making a GET request on an identifier associated with 3960 the potential for providing that information in a 200 (OK) response. 3962 GET is the primary mechanism of information retrieval and the focus 3963 of almost all performance optimizations. Applications that produce a 3964 URI for each important resource can benefit from those optimizations 3965 while enabling their reuse by other applications, creating a network 3966 effect that promotes further expansion of the Web. 3968 It is tempting to think of resource identifiers as remote file system 3969 pathnames and of representations as being a copy of the contents of 3970 such files. In fact, that is how many resources are implemented (see 3971 Section 17.3 for related security considerations). However, there 3972 are no such limitations in practice. 3974 The HTTP interface for a resource is just as likely to be implemented 3975 as a tree of content objects, a programmatic view on various database 3976 records, or a gateway to other information systems. Even when the 3977 URI mapping mechanism is tied to a file system, an origin server 3978 might be configured to execute the files with the request as input 3979 and send the output as the representation rather than transfer the 3980 files directly. Regardless, only the origin server needs to know how 3981 each resource identifier corresponds to an implementation and how 3982 that implementation manages to select and send a current 3983 representation of the target resource. 3985 A client can alter the semantics of GET to be a "range request", 3986 requesting transfer of only some part(s) of the selected 3987 representation, by sending a Range header field in the request 3988 (Section 14.2). 3990 Although request message framing is independent of the method used, 3991 content received in a GET request has no generally defined semantics, 3992 cannot alter the meaning or target of the request, and might lead 3993 some implementations to reject the request and close the connection 3994 because of its potential as a request smuggling attack (Section 11.2 3995 of [HTTP/1.1]). A client SHOULD NOT generate content in a GET 3996 request unless it is made directly to an origin server that has 3997 previously indicated, in or out of band, that such a request has a 3998 purpose and will be adequately supported. An origin server SHOULD 3999 NOT rely on private agreements to receive content, since participants 4000 in HTTP communication are often unaware of intermediaries along the 4001 request chain. 4003 The response to a GET request is cacheable; a cache MAY use it to 4004 satisfy subsequent GET and HEAD requests unless otherwise indicated 4005 by the Cache-Control header field (Section 5.2 of [CACHING]). 4007 When information retrieval is performed with a mechanism that 4008 constructs a target URI from user-provided information, such as the 4009 query fields of a form using GET, potentially sensitive data might be 4010 provided that would not be appropriate for disclosure within a URI 4011 (see Section 17.9). In some cases, the data can be filtered or 4012 transformed such that it would not reveal such information. In 4013 others, particularly when there is no benefit from caching a 4014 response, using the POST method (Section 9.3.3) instead of GET can 4015 transmit such information in the request content rather than within 4016 the target URI. 4018 9.3.2. HEAD 4020 The HEAD method is identical to GET except that the server MUST NOT 4021 send content in the response. HEAD is used to obtain metadata about 4022 the selected representation without transferring its representation 4023 data, often for the sake of testing hypertext links or finding recent 4024 modifications. 4026 The server SHOULD send the same header fields in response to a HEAD 4027 request as it would have sent if the request method had been GET. 4028 However, a server MAY omit header fields for which a value is 4029 determined only while generating the content. For example, some 4030 servers buffer a dynamic response to GET until a minimum amount of 4031 data is generated so that they can more efficiently delimit small 4032 responses or make late decisions with regard to content selection. 4033 Such a response to GET might contain Content-Length and Vary fields, 4034 for example, that are not generated within a HEAD response. These 4035 minor inconsistencies are considered preferable to generating and 4036 discarding the content for a HEAD request, since HEAD is usually 4037 requested for the sake of efficiency. 4039 Although request message framing is independent of the method used, 4040 content received in a HEAD request has no generally defined 4041 semantics, cannot alter the meaning or target of the request, and 4042 might lead some implementations to reject the request and close the 4043 connection because of its potential as a request smuggling attack 4044 (Section 11.2 of [HTTP/1.1]). A client SHOULD NOT generate content 4045 in a HEAD request unless it is made directly to an origin server that 4046 has previously indicated, in or out of band, that such a request has 4047 a purpose and will be adequately supported. An origin server SHOULD 4048 NOT rely on private agreements to receive content, since participants 4049 in HTTP communication are often unaware of intermediaries along the 4050 request chain. 4052 The response to a HEAD request is cacheable; a cache MAY use it to 4053 satisfy subsequent HEAD requests unless otherwise indicated by the 4054 Cache-Control header field (Section 5.2 of [CACHING]). A HEAD 4055 response might also affect previously cached responses to GET; see 4056 Section 4.3.5 of [CACHING]. 4058 9.3.3. POST 4060 The POST method requests that the target resource process the 4061 representation enclosed in the request according to the resource's 4062 own specific semantics. For example, POST is used for the following 4063 functions (among others): 4065 * Providing a block of data, such as the fields entered into an HTML 4066 form, to a data-handling process; 4068 * Posting a message to a bulletin board, newsgroup, mailing list, 4069 blog, or similar group of articles; 4071 * Creating a new resource that has yet to be identified by the 4072 origin server; and 4074 * Appending data to a resource's existing representation(s). 4076 An origin server indicates response semantics by choosing an 4077 appropriate status code depending on the result of processing the 4078 POST request; almost all of the status codes defined by this 4079 specification could be received in a response to POST (the exceptions 4080 being 206 (Partial Content), 304 (Not Modified), and 416 (Range Not 4081 Satisfiable)). 4083 If one or more resources has been created on the origin server as a 4084 result of successfully processing a POST request, the origin server 4085 SHOULD send a 201 (Created) response containing a Location header 4086 field that provides an identifier for the primary resource created 4087 (Section 10.2.2) and a representation that describes the status of 4088 the request while referring to the new resource(s). 4090 Responses to POST requests are only cacheable when they include 4091 explicit freshness information (see Section 4.2.1 of [CACHING]) and a 4092 Content-Location header field that has the same value as the POST's 4093 target URI (Section 8.7). A cached POST response can be reused to 4094 satisfy a later GET or HEAD request, but not a POST request, since 4095 POST is required to be written through to the origin server, because 4096 it is unsafe; see Section 4 of [CACHING]. 4098 If the result of processing a POST would be equivalent to a 4099 representation of an existing resource, an origin server MAY redirect 4100 the user agent to that resource by sending a 303 (See Other) response 4101 with the existing resource's identifier in the Location field. This 4102 has the benefits of providing the user agent a resource identifier 4103 and transferring the representation via a method more amenable to 4104 shared caching, though at the cost of an extra request if the user 4105 agent does not already have the representation cached. 4107 9.3.4. PUT 4109 The PUT method requests that the state of the target resource be 4110 created or replaced with the state defined by the representation 4111 enclosed in the request message content. A successful PUT of a given 4112 representation would suggest that a subsequent GET on that same 4113 target resource will result in an equivalent representation being 4114 sent in a 200 (OK) response. However, there is no guarantee that 4115 such a state change will be observable, since the target resource 4116 might be acted upon by other user agents in parallel, or might be 4117 subject to dynamic processing by the origin server, before any 4118 subsequent GET is received. A successful response only implies that 4119 the user agent's intent was achieved at the time of its processing by 4120 the origin server. 4122 If the target resource does not have a current representation and the 4123 PUT successfully creates one, then the origin server MUST inform the 4124 user agent by sending a 201 (Created) response. If the target 4125 resource does have a current representation and that representation 4126 is successfully modified in accordance with the state of the enclosed 4127 representation, then the origin server MUST send either a 200 (OK) or 4128 a 204 (No Content) response to indicate successful completion of the 4129 request. 4131 An origin server SHOULD verify that the PUT representation is 4132 consistent with its configured constraints for the target resource. 4133 For example, if an origin server determines a resource's 4134 representation metadata based on the URI, then the origin server 4135 needs to ensure that the content received in a successful PUT request 4136 is consistent with that metadata. When a PUT representation is 4137 inconsistent with the target resource, the origin server SHOULD 4138 either make them consistent, by transforming the representation or 4139 changing the resource configuration, or respond with an appropriate 4140 error message containing sufficient information to explain why the 4141 representation is unsuitable. The 409 (Conflict) or 415 (Unsupported 4142 Media Type) status codes are suggested, with the latter being 4143 specific to constraints on Content-Type values. 4145 For example, if the target resource is configured to always have a 4146 Content-Type of "text/html" and the representation being PUT has a 4147 Content-Type of "image/jpeg", the origin server ought to do one of: 4149 a. reconfigure the target resource to reflect the new media type; 4151 b. transform the PUT representation to a format consistent with that 4152 of the resource before saving it as the new resource state; or, 4154 c. reject the request with a 415 (Unsupported Media Type) response 4155 indicating that the target resource is limited to "text/html", 4156 perhaps including a link to a different resource that would be a 4157 suitable target for the new representation. 4159 HTTP does not define exactly how a PUT method affects the state of an 4160 origin server beyond what can be expressed by the intent of the user 4161 agent request and the semantics of the origin server response. It 4162 does not define what a resource might be, in any sense of that word, 4163 beyond the interface provided via HTTP. It does not define how 4164 resource state is "stored", nor how such storage might change as a 4165 result of a change in resource state, nor how the origin server 4166 translates resource state into representations. Generally speaking, 4167 all implementation details behind the resource interface are 4168 intentionally hidden by the server. 4170 This extends to how header and trailer fields are stored; while 4171 common header fields like Content-Type will typically be stored and 4172 returned upon subsequent GET requests, header and trailer field 4173 handling is specific to the resource that received the request. As a 4174 result, an origin server SHOULD ignore unrecognized header and 4175 trailer fields received in a PUT request (i.e., not save them as part 4176 of the resource state). 4178 An origin server MUST NOT send a validator field (Section 8.8), such 4179 as an ETag or Last-Modified field, in a successful response to PUT 4180 unless the request's representation data was saved without any 4181 transformation applied to the content (i.e., the resource's new 4182 representation data is identical to the content received in the PUT 4183 request) and the validator field value reflects the new 4184 representation. This requirement allows a user agent to know when 4185 the representation it sent (and retains in memory) is the result of 4186 the PUT, and thus doesn't need to be retrieved again from the origin 4187 server. The new validator(s) received in the response can be used 4188 for future conditional requests in order to prevent accidental 4189 overwrites (Section 13.1). 4191 The fundamental difference between the POST and PUT methods is 4192 highlighted by the different intent for the enclosed representation. 4193 The target resource in a POST request is intended to handle the 4194 enclosed representation according to the resource's own semantics, 4195 whereas the enclosed representation in a PUT request is defined as 4196 replacing the state of the target resource. Hence, the intent of PUT 4197 is idempotent and visible to intermediaries, even though the exact 4198 effect is only known by the origin server. 4200 Proper interpretation of a PUT request presumes that the user agent 4201 knows which target resource is desired. A service that selects a 4202 proper URI on behalf of the client, after receiving a state-changing 4203 request, SHOULD be implemented using the POST method rather than PUT. 4204 If the origin server will not make the requested PUT state change to 4205 the target resource and instead wishes to have it applied to a 4206 different resource, such as when the resource has been moved to a 4207 different URI, then the origin server MUST send an appropriate 3xx 4208 (Redirection) response; the user agent MAY then make its own decision 4209 regarding whether or not to redirect the request. 4211 A PUT request applied to the target resource can have side effects on 4212 other resources. For example, an article might have a URI for 4213 identifying "the current version" (a resource) that is separate from 4214 the URIs identifying each particular version (different resources 4215 that at one point shared the same state as the current version 4216 resource). A successful PUT request on "the current version" URI 4217 might therefore create a new version resource in addition to changing 4218 the state of the target resource, and might also cause links to be 4219 added between the related resources. 4221 Some origin servers support use of the Content-Range header field 4222 (Section 14.4) as a request modifier to perform a partial PUT, as 4223 described in Section 14.5. 4225 Responses to the PUT method are not cacheable. If a successful PUT 4226 request passes through a cache that has one or more stored responses 4227 for the target URI, those stored responses will be invalidated (see 4228 Section 4.4 of [CACHING]). 4230 9.3.5. DELETE 4232 The DELETE method requests that the origin server remove the 4233 association between the target resource and its current 4234 functionality. In effect, this method is similar to the "rm" command 4235 in UNIX: it expresses a deletion operation on the URI mapping of the 4236 origin server rather than an expectation that the previously 4237 associated information be deleted. 4239 If the target resource has one or more current representations, they 4240 might or might not be destroyed by the origin server, and the 4241 associated storage might or might not be reclaimed, depending 4242 entirely on the nature of the resource and its implementation by the 4243 origin server (which are beyond the scope of this specification). 4244 Likewise, other implementation aspects of a resource might need to be 4245 deactivated or archived as a result of a DELETE, such as database or 4246 gateway connections. In general, it is assumed that the origin 4247 server will only allow DELETE on resources for which it has a 4248 prescribed mechanism for accomplishing the deletion. 4250 Relatively few resources allow the DELETE method - its primary use is 4251 for remote authoring environments, where the user has some direction 4252 regarding its effect. For example, a resource that was previously 4253 created using a PUT request, or identified via the Location header 4254 field after a 201 (Created) response to a POST request, might allow a 4255 corresponding DELETE request to undo those actions. Similarly, 4256 custom user agent implementations that implement an authoring 4257 function, such as revision control clients using HTTP for remote 4258 operations, might use DELETE based on an assumption that the server's 4259 URI space has been crafted to correspond to a version repository. 4261 If a DELETE method is successfully applied, the origin server SHOULD 4262 send 4264 * a 202 (Accepted) status code if the action will likely succeed but 4265 has not yet been enacted, 4267 * a 204 (No Content) status code if the action has been enacted and 4268 no further information is to be supplied, or 4270 * a 200 (OK) status code if the action has been enacted and the 4271 response message includes a representation describing the status. 4273 Although request message framing is independent of the method used, 4274 content received in a DELETE request has no generally defined 4275 semantics, cannot alter the meaning or target of the request, and 4276 might lead some implementations to reject the request and close the 4277 connection because of its potential as a request smuggling attack 4278 (Section 11.2 of [HTTP/1.1]). A client SHOULD NOT generate content 4279 in a DELETE request unless it is made directly to an origin server 4280 that has previously indicated, in or out of band, that such a request 4281 has a purpose and will be adequately supported. An origin server 4282 SHOULD NOT rely on private agreements to receive content, since 4283 participants in HTTP communication are often unaware of 4284 intermediaries along the request chain. 4286 Responses to the DELETE method are not cacheable. If a successful 4287 DELETE request passes through a cache that has one or more stored 4288 responses for the target URI, those stored responses will be 4289 invalidated (see Section 4.4 of [CACHING]). 4291 9.3.6. CONNECT 4293 The CONNECT method requests that the recipient establish a tunnel to 4294 the destination origin server identified by the request target and, 4295 if successful, thereafter restrict its behavior to blind forwarding 4296 of data, in both directions, until the tunnel is closed. Tunnels are 4297 commonly used to create an end-to-end virtual connection, through one 4298 or more proxies, which can then be secured using TLS (Transport Layer 4299 Security, [TLS13]). 4301 CONNECT uses a special form of request target, unique to this method, 4302 consisting of only the host and port number of the tunnel 4303 destination, separated by a colon. There is no default port; a 4304 client MUST send the port number even if the CONNECT request is based 4305 on a URI reference that contains an authority component with an 4306 elided port (Section 4.1). For example, 4308 CONNECT server.example.com:80 HTTP/1.1 4309 Host: server.example.com 4311 A server MUST reject a CONNECT request that targets an empty or 4312 invalid port number, typically by responding with a 400 (Bad Request) 4313 status code. 4315 Because CONNECT changes the request/response nature of an HTTP 4316 connection, specific HTTP versions might have different ways of 4317 mapping its semantics into the protocol's wire format. 4319 CONNECT is intended for use in requests to a proxy. The recipient 4320 can establish a tunnel either by directly connecting to the server 4321 identified by the request target or, if configured to use another 4322 proxy, by forwarding the CONNECT request to the next inbound proxy. 4323 An origin server MAY accept a CONNECT request, but most origin 4324 servers do not implement CONNECT. 4326 Any 2xx (Successful) response indicates that the sender (and all 4327 inbound proxies) will switch to tunnel mode immediately after the 4328 response header section; data received after that header section is 4329 from the server identified by the request target. Any response other 4330 than a successful response indicates that the tunnel has not yet been 4331 formed. 4333 A tunnel is closed when a tunnel intermediary detects that either 4334 side has closed its connection: the intermediary MUST attempt to send 4335 any outstanding data that came from the closed side to the other 4336 side, close both connections, and then discard any remaining data 4337 left undelivered. 4339 Proxy authentication might be used to establish the authority to 4340 create a tunnel. For example, 4342 CONNECT server.example.com:443 HTTP/1.1 4343 Host: server.example.com:443 4344 Proxy-Authorization: basic aGVsbG86d29ybGQ= 4346 There are significant risks in establishing a tunnel to arbitrary 4347 servers, particularly when the destination is a well-known or 4348 reserved TCP port that is not intended for Web traffic. For example, 4349 a CONNECT to "example.com:25" would suggest that the proxy connect to 4350 the reserved port for SMTP traffic; if allowed, that could trick the 4351 proxy into relaying spam email. Proxies that support CONNECT SHOULD 4352 restrict its use to a limited set of known ports or a configurable 4353 list of safe request targets. 4355 A server MUST NOT send any Transfer-Encoding or Content-Length header 4356 fields in a 2xx (Successful) response to CONNECT. A client MUST 4357 ignore any Content-Length or Transfer-Encoding header fields received 4358 in a successful response to CONNECT. 4360 A CONNECT request message does not have content. The interpretation 4361 of data sent after the header section of the CONNECT request message 4362 is specific to the version of HTTP in use. 4364 Responses to the CONNECT method are not cacheable. 4366 9.3.7. OPTIONS 4368 The OPTIONS method requests information about the communication 4369 options available for the target resource, at either the origin 4370 server or an intervening intermediary. This method allows a client 4371 to determine the options and/or requirements associated with a 4372 resource, or the capabilities of a server, without implying a 4373 resource action. 4375 An OPTIONS request with an asterisk ("*") as the request target 4376 (Section 7.1) applies to the server in general rather than to a 4377 specific resource. Since a server's communication options typically 4378 depend on the resource, the "*" request is only useful as a "ping" or 4379 "no-op" type of method; it does nothing beyond allowing the client to 4380 test the capabilities of the server. For example, this can be used 4381 to test a proxy for HTTP/1.1 conformance (or lack thereof). 4383 If the request target is not an asterisk, the OPTIONS request applies 4384 to the options that are available when communicating with the target 4385 resource. 4387 A server generating a successful response to OPTIONS SHOULD send any 4388 header that might indicate optional features implemented by the 4389 server and applicable to the target resource (e.g., Allow), including 4390 potential extensions not defined by this specification. The response 4391 content, if any, might also describe the communication options in a 4392 machine or human-readable representation. A standard format for such 4393 a representation is not defined by this specification, but might be 4394 defined by future extensions to HTTP. 4396 A client MAY send a Max-Forwards header field in an OPTIONS request 4397 to target a specific recipient in the request chain (see 4398 Section 7.6.2). A proxy MUST NOT generate a Max-Forwards header 4399 field while forwarding a request unless that request was received 4400 with a Max-Forwards field. 4402 A client that generates an OPTIONS request containing content MUST 4403 send a valid Content-Type header field describing the representation 4404 media type. Note that this specification does not define any use for 4405 such content. 4407 Responses to the OPTIONS method are not cacheable. 4409 9.3.8. TRACE 4411 The TRACE method requests a remote, application-level loop-back of 4412 the request message. The final recipient of the request SHOULD 4413 reflect the message received, excluding some fields described below, 4414 back to the client as the content of a 200 (OK) response. The 4415 "message/http" (Section 10.1 of [HTTP/1.1]) format is one way to do 4416 so. The final recipient is either the origin server or the first 4417 server to receive a Max-Forwards value of zero (0) in the request 4418 (Section 7.6.2). 4420 A client MUST NOT generate fields in a TRACE request containing 4421 sensitive data that might be disclosed by the response. For example, 4422 it would be foolish for a user agent to send stored user credentials 4423 (Section 11) or cookies [COOKIE] in a TRACE request. The final 4424 recipient of the request SHOULD exclude any request fields that are 4425 likely to contain sensitive data when that recipient generates the 4426 response content. 4428 TRACE allows the client to see what is being received at the other 4429 end of the request chain and use that data for testing or diagnostic 4430 information. The value of the Via header field (Section 7.6.3) is of 4431 particular interest, since it acts as a trace of the request chain. 4432 Use of the Max-Forwards header field allows the client to limit the 4433 length of the request chain, which is useful for testing a chain of 4434 proxies forwarding messages in an infinite loop. 4436 A client MUST NOT send content in a TRACE request. 4438 Responses to the TRACE method are not cacheable. 4440 10. Message Context 4442 10.1. Request Context Fields 4444 The request header fields below provide additional information about 4445 the request context, including information about the user, user 4446 agent, and resource behind the request. 4448 10.1.1. Expect 4450 The "Expect" header field in a request indicates a certain set of 4451 behaviors (expectations) that need to be supported by the server in 4452 order to properly handle this request. 4454 Expect = #expectation 4455 expectation = token [ "=" ( token / quoted-string ) parameters ] 4457 The Expect field value is case-insensitive. 4459 The only expectation defined by this specification is "100-continue" 4460 (with no defined parameters). 4462 A server that receives an Expect field value containing a member 4463 other than 100-continue MAY respond with a 417 (Expectation Failed) 4464 status code to indicate that the unexpected expectation cannot be 4465 met. 4467 A _100-continue_ expectation informs recipients that the client is 4468 about to send (presumably large) content in this request and wishes 4469 to receive a 100 (Continue) interim response if the method, target 4470 URI, and header fields are not sufficient to cause an immediate 4471 success, redirect, or error response. This allows the client to wait 4472 for an indication that it is worthwhile to send the content before 4473 actually doing so, which can improve efficiency when the data is huge 4474 or when the client anticipates that an error is likely (e.g., when 4475 sending a state-changing method, for the first time, without 4476 previously verified authentication credentials). 4478 For example, a request that begins with 4479 PUT /somewhere/fun HTTP/1.1 4480 Host: origin.example.com 4481 Content-Type: video/h264 4482 Content-Length: 1234567890987 4483 Expect: 100-continue 4485 allows the origin server to immediately respond with an error 4486 message, such as 401 (Unauthorized) or 405 (Method Not Allowed), 4487 before the client starts filling the pipes with an unnecessary data 4488 transfer. 4490 Requirements for clients: 4492 * A client MUST NOT generate a 100-continue expectation in a request 4493 that does not include content. 4495 * A client that will wait for a 100 (Continue) response before 4496 sending the request content MUST send an Expect header field 4497 containing a 100-continue expectation. 4499 * A client that sends a 100-continue expectation is not required to 4500 wait for any specific length of time; such a client MAY proceed to 4501 send the content even if it has not yet received a response. 4502 Furthermore, since 100 (Continue) responses cannot be sent through 4503 an HTTP/1.0 intermediary, such a client SHOULD NOT wait for an 4504 indefinite period before sending the content. 4506 * A client that receives a 417 (Expectation Failed) status code in 4507 response to a request containing a 100-continue expectation SHOULD 4508 repeat that request without a 100-continue expectation, since the 4509 417 response merely indicates that the response chain does not 4510 support expectations (e.g., it passes through an HTTP/1.0 server). 4512 Requirements for servers: 4514 * A server that receives a 100-continue expectation in an HTTP/1.0 4515 request MUST ignore that expectation. 4517 * A server MAY omit sending a 100 (Continue) response if it has 4518 already received some or all of the content for the corresponding 4519 request, or if the framing indicates that there is no content. 4521 * A server that sends a 100 (Continue) response MUST ultimately send 4522 a final status code, once it receives and processes the request 4523 content, unless the connection is closed prematurely. 4525 * A server that responds with a final status code before reading the 4526 entire request content SHOULD indicate whether it intends to close 4527 the connection (e.g., see Section 9.6 of [HTTP/1.1]) or continue 4528 reading the request content. 4530 An origin server MUST, upon receiving an HTTP/1.1 (or later) request 4531 that has a method, target URI, and complete header section that 4532 contains a 100-continue expectation and an indication that request 4533 content will follow, either send an immediate response with a final 4534 status code, if that status can be determined by examining just the 4535 method, target URI, and header fields, or send an immediate 100 4536 (Continue) response to encourage the client to send the request 4537 content. The origin server MUST NOT wait for the content before 4538 sending the 100 (Continue) response. 4540 A proxy MUST, upon receiving an HTTP/1.1 (or later) request that has 4541 a method, target URI, and complete header section that contains a 4542 100-continue expectation and indicates a request content will follow, 4543 either send an immediate response with a final status code, if that 4544 status can be determined by examining just the method, target URI, 4545 and header fields, or begin forwarding the request toward the origin 4546 server by sending a corresponding request-line and header section to 4547 the next inbound server. If the proxy believes (from configuration 4548 or past interaction) that the next inbound server only supports 4549 HTTP/1.0, the proxy MAY generate an immediate 100 (Continue) response 4550 to encourage the client to begin sending the content. 4552 10.1.2. From 4554 The "From" header field contains an Internet email address for a 4555 human user who controls the requesting user agent. The address ought 4556 to be machine-usable, as defined by "mailbox" in Section 3.4 of 4557 [RFC5322]: 4559 From = mailbox 4561 mailbox = 4563 An example is: 4565 From: webmaster@example.org 4567 The From header field is rarely sent by non-robotic user agents. A 4568 user agent SHOULD NOT send a From header field without explicit 4569 configuration by the user, since that might conflict with the user's 4570 privacy interests or their site's security policy. 4572 A robotic user agent SHOULD send a valid From header field so that 4573 the person responsible for running the robot can be contacted if 4574 problems occur on servers, such as if the robot is sending excessive, 4575 unwanted, or invalid requests. 4577 A server SHOULD NOT use the From header field for access control or 4578 authentication, since its value is expected to be visible to anyone 4579 receiving or observing the request and is often recorded within 4580 logfiles and error reports without any expectation of privacy. 4582 10.1.3. Referer 4584 The "Referer" [sic] header field allows the user agent to specify a 4585 URI reference for the resource from which the target URI was obtained 4586 (i.e., the "referrer", though the field name is misspelled). A user 4587 agent MUST NOT include the fragment and userinfo components of the 4588 URI reference [URI], if any, when generating the Referer field value. 4590 Referer = absolute-URI / partial-URI 4592 The field value is either an absolute-URI or a partial-URI. In the 4593 latter case (Section 4), the referenced URI is relative to the target 4594 URI ([URI], Section 5). 4596 The Referer header field allows servers to generate back-links to 4597 other resources for simple analytics, logging, optimized caching, 4598 etc. It also allows obsolete or mistyped links to be found for 4599 maintenance. Some servers use the Referer header field as a means of 4600 denying links from other sites (so-called "deep linking") or 4601 restricting cross-site request forgery (CSRF), but not all requests 4602 contain it. 4604 Example: 4606 Referer: http://www.example.org/hypertext/Overview.html 4608 If the target URI was obtained from a source that does not have its 4609 own URI (e.g., input from the user keyboard, or an entry within the 4610 user's bookmarks/favorites), the user agent MUST either exclude the 4611 Referer header field or send it with a value of "about:blank". 4613 The Referer header field value need not convey the full URI of the 4614 referring resource; a user agent MAY truncate parts other than the 4615 referring origin. 4617 The Referer header field has the potential to reveal information 4618 about the request context or browsing history of the user, which is a 4619 privacy concern if the referring resource's identifier reveals 4620 personal information (such as an account name) or a resource that is 4621 supposed to be confidential (such as behind a firewall or internal to 4622 a secured service). Most general-purpose user agents do not send the 4623 Referer header field when the referring resource is a local "file" or 4624 "data" URI. A user agent SHOULD NOT send a Referer header field if 4625 the referring resource was accessed with a secure protocol and the 4626 request target has an origin differing from that of the referring 4627 resource, unless the referring resource explicitly allows Referer to 4628 be sent. A user agent MUST NOT send a Referer header field in an 4629 unsecured HTTP request if the referring resource was accessed with a 4630 secure protocol. See Section 17.9 for additional security 4631 considerations. 4633 Some intermediaries have been known to indiscriminately remove 4634 Referer header fields from outgoing requests. This has the 4635 unfortunate side effect of interfering with protection against CSRF 4636 attacks, which can be far more harmful to their users. 4637 Intermediaries and user agent extensions that wish to limit 4638 information disclosure in Referer ought to restrict their changes to 4639 specific edits, such as replacing internal domain names with 4640 pseudonyms or truncating the query and/or path components. An 4641 intermediary SHOULD NOT modify or delete the Referer header field 4642 when the field value shares the same scheme and host as the target 4643 URI. 4645 10.1.4. TE 4647 The "TE" header field describes capabilities of the client with 4648 regard to transfer encodings and trailer sections. 4650 A TE field with a "trailers" member sent in a request indicates that 4651 the client will not discard trailer fields, as described in 4652 Section 6.5. 4654 TE is also used within HTTP/1.1 to advise servers about what transfer 4655 codings the client is able to accept in a response. As of 4656 publication, only HTTP/1.1 uses transfer codings (see Section 7 of 4657 [HTTP/1.1]). 4659 The TE field value is a list of members, with each member (aside from 4660 "trailers") consisting of a transfer coding name token with an 4661 optional weight indicating the client's relative preference for that 4662 transfer coding (Section 12.4.2) and optional parameters for that 4663 transfer coding. 4665 TE = #t-codings 4666 t-codings = "trailers" / ( transfer-coding [ weight ] ) 4667 transfer-coding = token *( OWS ";" OWS transfer-parameter ) 4668 transfer-parameter = token BWS "=" BWS ( token / quoted-string ) 4670 A sender of TE MUST also send a "TE" connection option within the 4671 Connection header field (Section 7.6.1) to inform intermediaries not 4672 to forward this field. 4674 10.1.5. User-Agent 4676 The "User-Agent" header field contains information about the user 4677 agent originating the request, which is often used by servers to help 4678 identify the scope of reported interoperability problems, to work 4679 around or tailor responses to avoid particular user agent 4680 limitations, and for analytics regarding browser or operating system 4681 use. A user agent SHOULD send a User-Agent header field in each 4682 request unless specifically configured not to do so. 4684 User-Agent = product *( RWS ( product / comment ) ) 4686 The User-Agent field value consists of one or more product 4687 identifiers, each followed by zero or more comments (Section 5.6.5), 4688 which together identify the user agent software and its significant 4689 subproducts. By convention, the product identifiers are listed in 4690 decreasing order of their significance for identifying the user agent 4691 software. Each product identifier consists of a name and optional 4692 version. 4694 product = token ["/" product-version] 4695 product-version = token 4697 A sender SHOULD limit generated product identifiers to what is 4698 necessary to identify the product; a sender MUST NOT generate 4699 advertising or other nonessential information within the product 4700 identifier. A sender SHOULD NOT generate information in 4701 product-version that is not a version identifier (i.e., successive 4702 versions of the same product name ought to differ only in the 4703 product-version portion of the product identifier). 4705 Example: 4707 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 4708 A user agent SHOULD NOT generate a User-Agent header field containing 4709 needlessly fine-grained detail and SHOULD limit the addition of 4710 subproducts by third parties. Overly long and detailed User-Agent 4711 field values increase request latency and the risk of a user being 4712 identified against their wishes ("fingerprinting"). 4714 Likewise, implementations are encouraged not to use the product 4715 tokens of other implementations in order to declare compatibility 4716 with them, as this circumvents the purpose of the field. If a user 4717 agent masquerades as a different user agent, recipients can assume 4718 that the user intentionally desires to see responses tailored for 4719 that identified user agent, even if they might not work as well for 4720 the actual user agent being used. 4722 10.2. Response Context Fields 4724 The response header fields below provide additional information about 4725 the response, beyond what is implied by the status code, including 4726 information about the server, about the target resource, or about 4727 related resources. 4729 10.2.1. Allow 4731 The "Allow" header field lists the set of methods advertised as 4732 supported by the target resource. The purpose of this field is 4733 strictly to inform the recipient of valid request methods associated 4734 with the resource. 4736 Allow = #method 4738 Example of use: 4740 Allow: GET, HEAD, PUT 4742 The actual set of allowed methods is defined by the origin server at 4743 the time of each request. An origin server MUST generate an Allow 4744 header field in a 405 (Method Not Allowed) response and MAY do so in 4745 any other response. An empty Allow field value indicates that the 4746 resource allows no methods, which might occur in a 405 response if 4747 the resource has been temporarily disabled by configuration. 4749 A proxy MUST NOT modify the Allow header field - it does not need to 4750 understand all of the indicated methods in order to handle them 4751 according to the generic message handling rules. 4753 10.2.2. Location 4755 The "Location" header field is used in some responses to refer to a 4756 specific resource in relation to the response. The type of 4757 relationship is defined by the combination of request method and 4758 status code semantics. 4760 Location = URI-reference 4762 The field value consists of a single URI-reference. When it has the 4763 form of a relative reference ([URI], Section 4.2), the final value is 4764 computed by resolving it against the target URI ([URI], Section 5). 4766 For 201 (Created) responses, the Location value refers to the primary 4767 resource created by the request. For 3xx (Redirection) responses, 4768 the Location value refers to the preferred target resource for 4769 automatically redirecting the request. 4771 If the Location value provided in a 3xx (Redirection) response does 4772 not have a fragment component, a user agent MUST process the 4773 redirection as if the value inherits the fragment component of the 4774 URI reference used to generate the target URI (i.e., the redirection 4775 inherits the original reference's fragment, if any). 4777 For example, a GET request generated for the URI reference 4778 "http://www.example.org/~tim" might result in a 303 (See Other) 4779 response containing the header field: 4781 Location: /People.html#tim 4783 which suggests that the user agent redirect to 4784 "http://www.example.org/People.html#tim" 4786 Likewise, a GET request generated for the URI reference 4787 "http://www.example.org/index.html#larry" might result in a 301 4788 (Moved Permanently) response containing the header field: 4790 Location: http://www.example.net/index.html 4792 which suggests that the user agent redirect to 4793 "http://www.example.net/index.html#larry", preserving the original 4794 fragment identifier. 4796 There are circumstances in which a fragment identifier in a Location 4797 value would not be appropriate. For example, the Location header 4798 field in a 201 (Created) response is supposed to provide a URI that 4799 is specific to the created resource. 4801 | *Note:* Some recipients attempt to recover from Location header 4802 | fields that are not valid URI references. This specification 4803 | does not mandate or define such processing, but does allow it 4804 | for the sake of robustness. A Location field value cannot 4805 | allow a list of members because the comma list separator is a 4806 | valid data character within a URI-reference. If an invalid 4807 | message is sent with multiple Location field lines, a recipient 4808 | along the path might combine those field lines into one value. 4809 | Recovery of a valid Location field value from that situation is 4810 | difficult and not interoperable across implementations. 4812 | *Note:* The Content-Location header field (Section 8.7) differs 4813 | from Location in that the Content-Location refers to the most 4814 | specific resource corresponding to the enclosed representation. 4815 | It is therefore possible for a response to contain both the 4816 | Location and Content-Location header fields. 4818 10.2.3. Retry-After 4820 Servers send the "Retry-After" header field to indicate how long the 4821 user agent ought to wait before making a follow-up request. When 4822 sent with a 503 (Service Unavailable) response, Retry-After indicates 4823 how long the service is expected to be unavailable to the client. 4824 When sent with any 3xx (Redirection) response, Retry-After indicates 4825 the minimum time that the user agent is asked to wait before issuing 4826 the redirected request. 4828 The Retry-After field value can be either an HTTP-date or a number of 4829 seconds to delay after receiving the response. 4831 Retry-After = HTTP-date / delay-seconds 4833 A delay-seconds value is a non-negative decimal integer, representing 4834 time in seconds. 4836 delay-seconds = 1*DIGIT 4838 Two examples of its use are 4840 Retry-After: Fri, 31 Dec 1999 23:59:59 GMT 4841 Retry-After: 120 4843 In the latter example, the delay is 2 minutes. 4845 10.2.4. Server 4847 The "Server" header field contains information about the software 4848 used by the origin server to handle the request, which is often used 4849 by clients to help identify the scope of reported interoperability 4850 problems, to work around or tailor requests to avoid particular 4851 server limitations, and for analytics regarding server or operating 4852 system use. An origin server MAY generate a Server header field in 4853 its responses. 4855 Server = product *( RWS ( product / comment ) ) 4857 The Server header field value consists of one or more product 4858 identifiers, each followed by zero or more comments (Section 5.6.5), 4859 which together identify the origin server software and its 4860 significant subproducts. By convention, the product identifiers are 4861 listed in decreasing order of their significance for identifying the 4862 origin server software. Each product identifier consists of a name 4863 and optional version, as defined in Section 10.1.5. 4865 Example: 4867 Server: CERN/3.0 libwww/2.17 4869 An origin server SHOULD NOT generate a Server header field containing 4870 needlessly fine-grained detail and SHOULD limit the addition of 4871 subproducts by third parties. Overly long and detailed Server field 4872 values increase response latency and potentially reveal internal 4873 implementation details that might make it (slightly) easier for 4874 attackers to find and exploit known security holes. 4876 11. HTTP Authentication 4878 11.1. Authentication Scheme 4880 HTTP provides a general framework for access control and 4881 authentication, via an extensible set of challenge-response 4882 authentication schemes, which can be used by a server to challenge a 4883 client request and by a client to provide authentication information. 4884 It uses a case-insensitive token to identify the authentication 4885 scheme 4887 auth-scheme = token 4889 Aside from the general framework, this document does not specify any 4890 authentication schemes. New and existing authentication schemes are 4891 specified independently and ought to be registered within the 4892 "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry". 4893 For example, the "basic" and "digest" authentication schemes are 4894 defined by RFC 7617 and RFC 7616, respectively. 4896 11.2. Authentication Parameters 4898 The authentication scheme is followed by additional information 4899 necessary for achieving authentication via that scheme as either a 4900 comma-separated list of parameters or a single sequence of characters 4901 capable of holding base64-encoded information. 4903 token68 = 1*( ALPHA / DIGIT / 4904 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 4906 The token68 syntax allows the 66 unreserved URI characters ([URI]), 4907 plus a few others, so that it can hold a base64, base64url (URL and 4908 filename safe alphabet), base32, or base16 (hex) encoding, with or 4909 without padding, but excluding whitespace ([RFC4648]). 4911 Authentication parameters are name=value pairs, where the name token 4912 is matched case-insensitively and each parameter name MUST only occur 4913 once per challenge. 4915 auth-param = token BWS "=" BWS ( token / quoted-string ) 4917 Parameter values can be expressed either as "token" or as "quoted- 4918 string" (Section 5.6). Authentication scheme definitions need to 4919 accept both notations, both for senders and recipients, to allow 4920 recipients to use generic parsing components regardless of the 4921 authentication scheme. 4923 For backwards compatibility, authentication scheme definitions can 4924 restrict the format for senders to one of the two variants. This can 4925 be important when it is known that deployed implementations will fail 4926 when encountering one of the two formats. 4928 11.3. Challenge and Response 4930 A 401 (Unauthorized) response message is used by an origin server to 4931 challenge the authorization of a user agent, including a 4932 WWW-Authenticate header field containing at least one challenge 4933 applicable to the requested resource. 4935 A 407 (Proxy Authentication Required) response message is used by a 4936 proxy to challenge the authorization of a client, including a 4937 Proxy-Authenticate header field containing at least one challenge 4938 applicable to the proxy for the requested resource. 4940 challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 4942 | *Note:* Many clients fail to parse a challenge that contains an 4943 | unknown scheme. A workaround for this problem is to list well- 4944 | supported schemes (such as "basic") first. 4946 A user agent that wishes to authenticate itself with an origin server 4947 - usually, but not necessarily, after receiving a 401 (Unauthorized) 4948 - can do so by including an Authorization header field with the 4949 request. 4951 A client that wishes to authenticate itself with a proxy - usually, 4952 but not necessarily, after receiving a 407 (Proxy Authentication 4953 Required) - can do so by including a Proxy-Authorization header field 4954 with the request. 4956 11.4. Credentials 4958 Both the Authorization field value and the Proxy-Authorization field 4959 value contain the client's credentials for the realm of the resource 4960 being requested, based upon a challenge received in a response 4961 (possibly at some point in the past). When creating their values, 4962 the user agent ought to do so by selecting the challenge with what it 4963 considers to be the most secure auth-scheme that it understands, 4964 obtaining credentials from the user as appropriate. Transmission of 4965 credentials within header field values implies significant security 4966 considerations regarding the confidentiality of the underlying 4967 connection, as described in Section 17.16.1. 4969 credentials = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 4971 Upon receipt of a request for a protected resource that omits 4972 credentials, contains invalid credentials (e.g., a bad password) or 4973 partial credentials (e.g., when the authentication scheme requires 4974 more than one round trip), an origin server SHOULD send a 401 4975 (Unauthorized) response that contains a WWW-Authenticate header field 4976 with at least one (possibly new) challenge applicable to the 4977 requested resource. 4979 Likewise, upon receipt of a request that omits proxy credentials or 4980 contains invalid or partial proxy credentials, a proxy that requires 4981 authentication SHOULD generate a 407 (Proxy Authentication Required) 4982 response that contains a Proxy-Authenticate header field with at 4983 least one (possibly new) challenge applicable to the proxy. 4985 A server that receives valid credentials that are not adequate to 4986 gain access ought to respond with the 403 (Forbidden) status code 4987 (Section 15.5.4). 4989 HTTP does not restrict applications to this simple challenge-response 4990 framework for access authentication. Additional mechanisms can be 4991 used, such as authentication at the transport level or via message 4992 encapsulation, and with additional header fields specifying 4993 authentication information. However, such additional mechanisms are 4994 not defined by this specification. 4996 Note that various custom mechanisms for user authentication use the 4997 Set-Cookie and Cookie header fields, defined in [COOKIE], for passing 4998 tokens related to authentication. 5000 11.5. Establishing a Protection Space (Realm) 5002 The _realm_ authentication parameter is reserved for use by 5003 authentication schemes that wish to indicate a scope of protection. 5005 A _protection space_ is defined by the origin (see Section 4.3.1) of 5006 the server being accessed, in combination with the realm value if 5007 present. These realms allow the protected resources on a server to 5008 be partitioned into a set of protection spaces, each with its own 5009 authentication scheme and/or authorization database. The realm value 5010 is a string, generally assigned by the origin server, that can have 5011 additional semantics specific to the authentication scheme. Note 5012 that a response can have multiple challenges with the same auth- 5013 scheme but with different realms. 5015 The protection space determines the domain over which credentials can 5016 be automatically applied. If a prior request has been authorized, 5017 the user agent MAY reuse the same credentials for all other requests 5018 within that protection space for a period of time determined by the 5019 authentication scheme, parameters, and/or user preferences (such as a 5020 configurable inactivity timeout). 5022 The extent of a protection space, and therefore the requests to which 5023 credentials might be automatically applied, is not necessarily known 5024 to clients without additional information. An authentication scheme 5025 might define parameters that describe the extent of a protection 5026 space. Unless specifically allowed by the authentication scheme, a 5027 single protection space cannot extend outside the scope of its 5028 server. 5030 For historical reasons, a sender MUST only generate the quoted-string 5031 syntax. Recipients might have to support both token and quoted- 5032 string syntax for maximum interoperability with existing clients that 5033 have been accepting both notations for a long time. 5035 11.6. Authenticating Users to Origin Servers 5037 11.6.1. WWW-Authenticate 5039 The "WWW-Authenticate" response header field indicates the 5040 authentication scheme(s) and parameters applicable to the target 5041 resource. 5043 WWW-Authenticate = #challenge 5045 A server generating a 401 (Unauthorized) response MUST send a WWW- 5046 Authenticate header field containing at least one challenge. A 5047 server MAY generate a WWW-Authenticate header field in other response 5048 messages to indicate that supplying credentials (or different 5049 credentials) might affect the response. 5051 A proxy forwarding a response MUST NOT modify any WWW-Authenticate 5052 header fields in that response. 5054 User agents are advised to take special care in parsing the field 5055 value, as it might contain more than one challenge, and each 5056 challenge can contain a comma-separated list of authentication 5057 parameters. Furthermore, the header field itself can occur multiple 5058 times. 5060 For instance: 5062 WWW-Authenticate: Basic realm="simple", Newauth realm="apps", 5063 type=1, title="Login to \"apps\"" 5065 This header field contains two challenges; one for the "Basic" scheme 5066 with a realm value of "simple", and another for the "Newauth" scheme 5067 with a realm value of "apps", and two additional parameters "type" 5068 and "title". 5070 Some user agents do not recognise this form, however. As a result, 5071 sending a WWW-Authenticate field value with more than one member on 5072 the same field line might not be interoperable. 5074 | *Note:* The challenge grammar production uses the list syntax 5075 | as well. Therefore, a sequence of comma, whitespace, and comma 5076 | can be considered either as applying to the preceding 5077 | challenge, or to be an empty entry in the list of challenges. 5078 | In practice, this ambiguity does not affect the semantics of 5079 | the header field value and thus is harmless. 5081 11.6.2. Authorization 5083 The "Authorization" header field allows a user agent to authenticate 5084 itself with an origin server - usually, but not necessarily, after 5085 receiving a 401 (Unauthorized) response. Its value consists of 5086 credentials containing the authentication information of the user 5087 agent for the realm of the resource being requested. 5089 Authorization = credentials 5091 If a request is authenticated and a realm specified, the same 5092 credentials are presumed to be valid for all other requests within 5093 this realm (assuming that the authentication scheme itself does not 5094 require otherwise, such as credentials that vary according to a 5095 challenge value or using synchronized clocks). 5097 A proxy forwarding a request MUST NOT modify any Authorization header 5098 fields in that request. See Section 3.5 of [CACHING] for details of 5099 and requirements pertaining to handling of the Authorization header 5100 field by HTTP caches. 5102 11.6.3. Authentication-Info 5104 HTTP authentication schemes can use the Authentication-Info response 5105 field to communicate information after the client's authentication 5106 credentials have been accepted. This information can include a 5107 finalization message from the server (e.g., it can contain the server 5108 authentication). 5110 The field value is a list of parameters (name/value pairs), using the 5111 "auth-param" syntax defined in Section 11.3. This specification only 5112 describes the generic format; authentication schemes using 5113 Authentication-Info will define the individual parameters. The 5114 "Digest" Authentication Scheme, for instance, defines multiple 5115 parameters in Section 3.5 of [RFC7616]. 5117 Authentication-Info = #auth-param 5119 The Authentication-Info field can be used in any HTTP response, 5120 independently of request method and status code. Its semantics are 5121 defined by the authentication scheme indicated by the Authorization 5122 header field (Section 11.6.2) of the corresponding request. 5124 A proxy forwarding a response is not allowed to modify the field 5125 value in any way. 5127 Authentication-Info can be sent as a trailer field (Section 6.5) when 5128 the authentication scheme explicitly allows this. 5130 11.7. Authenticating Clients to Proxies 5132 11.7.1. Proxy-Authenticate 5134 The "Proxy-Authenticate" header field consists of at least one 5135 challenge that indicates the authentication scheme(s) and parameters 5136 applicable to the proxy for this request. A proxy MUST send at least 5137 one Proxy-Authenticate header field in each 407 (Proxy Authentication 5138 Required) response that it generates. 5140 Proxy-Authenticate = #challenge 5142 Unlike WWW-Authenticate, the Proxy-Authenticate header field applies 5143 only to the next outbound client on the response chain. This is 5144 because only the client that chose a given proxy is likely to have 5145 the credentials necessary for authentication. However, when multiple 5146 proxies are used within the same administrative domain, such as 5147 office and regional caching proxies within a large corporate network, 5148 it is common for credentials to be generated by the user agent and 5149 passed through the hierarchy until consumed. Hence, in such a 5150 configuration, it will appear as if Proxy-Authenticate is being 5151 forwarded because each proxy will send the same challenge set. 5153 Note that the parsing considerations for WWW-Authenticate apply to 5154 this header field as well; see Section 11.6.1 for details. 5156 11.7.2. Proxy-Authorization 5158 The "Proxy-Authorization" header field allows the client to identify 5159 itself (or its user) to a proxy that requires authentication. Its 5160 value consists of credentials containing the authentication 5161 information of the client for the proxy and/or realm of the resource 5162 being requested. 5164 Proxy-Authorization = credentials 5166 Unlike Authorization, the Proxy-Authorization header field applies 5167 only to the next inbound proxy that demanded authentication using the 5168 Proxy-Authenticate header field. When multiple proxies are used in a 5169 chain, the Proxy-Authorization header field is consumed by the first 5170 inbound proxy that was expecting to receive credentials. A proxy MAY 5171 relay the credentials from the client request to the next proxy if 5172 that is the mechanism by which the proxies cooperatively authenticate 5173 a given request. 5175 11.7.3. Proxy-Authentication-Info 5177 The Proxy-Authentication-Info response header field is equivalent to 5178 Authentication-Info, except that it applies to proxy authentication 5179 (Section 11.3) and its semantics are defined by the authentication 5180 scheme indicated by the Proxy-Authorization header field 5181 (Section 11.7.2) of the corresponding request: 5183 Proxy-Authentication-Info = #auth-param 5185 However, unlike Authentication-Info, the Proxy-Authentication-Info 5186 header field applies only to the next outbound client on the response 5187 chain. This is because only the client that chose a given proxy is 5188 likely to have the credentials necessary for authentication. 5189 However, when multiple proxies are used within the same 5190 administrative domain, such as office and regional caching proxies 5191 within a large corporate network, it is common for credentials to be 5192 generated by the user agent and passed through the hierarchy until 5193 consumed. Hence, in such a configuration, it will appear as if 5194 Proxy-Authentication-Info is being forwarded because each proxy will 5195 send the same field value. 5197 Proxy-Authentication-Info can be sent as a trailer field 5198 (Section 6.5) when the authentication scheme explicitly allows this. 5200 12. Content Negotiation 5202 When responses convey content, whether indicating a success or an 5203 error, the origin server often has different ways of representing 5204 that information; for example, in different formats, languages, or 5205 encodings. Likewise, different users or user agents might have 5206 differing capabilities, characteristics, or preferences that could 5207 influence which representation, among those available, would be best 5208 to deliver. For this reason, HTTP provides mechanisms for content 5209 negotiation. 5211 This specification defines three patterns of content negotiation that 5212 can be made visible within the protocol: "proactive" negotiation, 5213 where the server selects the representation based upon the user 5214 agent's stated preferences, "reactive" negotiation, where the server 5215 provides a list of representations for the user agent to choose from, 5216 and "request content" negotiation, where the user agent selects the 5217 representation for a future request based upon the server's stated 5218 preferences in past responses. 5220 Other patterns of content negotiation include "conditional content", 5221 where the representation consists of multiple parts that are 5222 selectively rendered based on user agent parameters, "active 5223 content", where the representation contains a script that makes 5224 additional (more specific) requests based on the user agent 5225 characteristics, and "Transparent Content Negotiation" ([RFC2295]), 5226 where content selection is performed by an intermediary. These 5227 patterns are not mutually exclusive, and each has trade-offs in 5228 applicability and practicality. 5230 Note that, in all cases, HTTP is not aware of the resource semantics. 5231 The consistency with which an origin server responds to requests, 5232 over time and over the varying dimensions of content negotiation, and 5233 thus the "sameness" of a resource's observed representations over 5234 time, is determined entirely by whatever entity or algorithm selects 5235 or generates those responses. 5237 12.1. Proactive Negotiation 5239 When content negotiation preferences are sent by the user agent in a 5240 request to encourage an algorithm located at the server to select the 5241 preferred representation, it is called _proactive negotiation_ 5242 (a.k.a., _server-driven negotiation_). Selection is based on the 5243 available representations for a response (the dimensions over which 5244 it might vary, such as language, content coding, etc.) compared to 5245 various information supplied in the request, including both the 5246 explicit negotiation header fields below and implicit 5247 characteristics, such as the client's network address or parts of the 5248 User-Agent field. 5250 Proactive negotiation is advantageous when the algorithm for 5251 selecting from among the available representations is difficult to 5252 describe to a user agent, or when the server desires to send its 5253 "best guess" to the user agent along with the first response (when 5254 that "best guess" is good enough for the user, this avoids the round 5255 trip delay of a subsequent request). In order to improve the 5256 server's guess, a user agent MAY send request header fields that 5257 describe its preferences. 5259 Proactive negotiation has serious disadvantages: 5261 * It is impossible for the server to accurately determine what might 5262 be "best" for any given user, since that would require complete 5263 knowledge of both the capabilities of the user agent and the 5264 intended use for the response (e.g., does the user want to view it 5265 on screen or print it on paper?); 5267 * Having the user agent describe its capabilities in every request 5268 can be both very inefficient (given that only a small percentage 5269 of responses have multiple representations) and a potential risk 5270 to the user's privacy; 5272 * It complicates the implementation of an origin server and the 5273 algorithms for generating responses to a request; and, 5275 * It limits the reusability of responses for shared caching. 5277 A user agent cannot rely on proactive negotiation preferences being 5278 consistently honored, since the origin server might not implement 5279 proactive negotiation for the requested resource or might decide that 5280 sending a response that doesn't conform to the user agent's 5281 preferences is better than sending a 406 (Not Acceptable) response. 5283 A Vary header field (Section 12.5.5) is often sent in a response 5284 subject to proactive negotiation to indicate what parts of the 5285 request information were used in the selection algorithm. 5287 The request header fields Accept, Accept-Charset, Accept-Encoding, 5288 and Accept-Language are defined below for a user agent to engage in 5289 proactive negotiation of the response content. The preferences sent 5290 in these fields apply to any content in the response, including 5291 representations of the target resource, representations of error or 5292 processing status, and potentially even the miscellaneous text 5293 strings that might appear within the protocol. 5295 12.2. Reactive Negotiation 5297 With _reactive negotiation_ (a.k.a., _agent-driven negotiation_), 5298 selection of content (regardless of the status code) is performed by 5299 the user agent after receiving an initial response. The mechanism 5300 for reactive negotiation might be as simple as a list of references 5301 to alternative representations. 5303 If the user agent is not satisfied by the initial response content, 5304 it can perform a GET request on one or more of the alternative 5305 resources to obtain a different representation. Selection of such 5306 alternatives might be performed automatically (by the user agent) or 5307 manually (e.g., by the user selecting from a hypertext menu). 5309 A server might choose not to send an initial representation, other 5310 than the list of alternatives, and thereby indicate that reactive 5311 negotiation by the user agent is preferred. For example, the 5312 alternatives listed in responses with the 300 (Multiple Choices) and 5313 406 (Not Acceptable) status codes include information about available 5314 representations so that the user or user agent can react by making a 5315 selection. 5317 Reactive negotiation is advantageous when the response would vary 5318 over commonly used dimensions (such as type, language, or encoding), 5319 when the origin server is unable to determine a user agent's 5320 capabilities from examining the request, and generally when public 5321 caches are used to distribute server load and reduce network usage. 5323 Reactive negotiation suffers from the disadvantages of transmitting a 5324 list of alternatives to the user agent, which degrades user-perceived 5325 latency if transmitted in the header section, and needing a second 5326 request to obtain an alternate representation. Furthermore, this 5327 specification does not define a mechanism for supporting automatic 5328 selection, though it does not prevent such a mechanism from being 5329 developed. 5331 12.3. Request Content Negotiation 5333 When content negotiation preferences are sent in a server's response, 5334 the listed preferences are called _request content negotiation_ 5335 because they intend to influence selection of an appropriate content 5336 for subsequent requests to that resource. For example, the Accept 5337 (Section 12.5.1) and Accept-Encoding (Section 12.5.3) header fields 5338 can be sent in a response to indicate preferred media types and 5339 content codings for subsequent requests to that resource. 5341 Similarly, Section 3.1 of [RFC5789] defines the "Accept-Patch" 5342 response header field which allows discovery of which content types 5343 are accepted in PATCH requests. 5345 12.4. Content Negotiation Field Features 5347 12.4.1. Absence 5349 For each of the content negotiation fields, a request that does not 5350 contain the field implies that the sender has no preference on that 5351 dimension of negotiation. 5353 If a content negotiation header field is present in a request and 5354 none of the available representations for the response can be 5355 considered acceptable according to it, the origin server can either 5356 honor the header field by sending a 406 (Not Acceptable) response or 5357 disregard the header field by treating the response as if it is not 5358 subject to content negotiation for that request header field. This 5359 does not imply, however, that the client will be able to use the 5360 representation. 5362 | *Note:* A user agent sending these header fields makes it 5363 | easier for a server to identify an individual by virtue of the 5364 | user agent's request characteristics (Section 17.13). 5366 12.4.2. Quality Values 5368 The content negotiation fields defined by this specification use a 5369 common parameter, named "q" (case-insensitive), to assign a relative 5370 "weight" to the preference for that associated kind of content. This 5371 weight is referred to as a "quality value" (or "qvalue") because the 5372 same parameter name is often used within server configurations to 5373 assign a weight to the relative quality of the various 5374 representations that can be selected for a resource. 5376 The weight is normalized to a real number in the range 0 through 1, 5377 where 0.001 is the least preferred and 1 is the most preferred; a 5378 value of 0 means "not acceptable". If no "q" parameter is present, 5379 the default weight is 1. 5381 weight = OWS ";" OWS "q=" qvalue 5382 qvalue = ( "0" [ "." 0*3DIGIT ] ) 5383 / ( "1" [ "." 0*3("0") ] ) 5385 A sender of qvalue MUST NOT generate more than three digits after the 5386 decimal point. User configuration of these values ought to be 5387 limited in the same fashion. 5389 12.4.3. Wildcard Values 5391 Most of these header fields, where indicated, define a wildcard value 5392 ("*") to select unspecified values. If no wildcard is present, 5393 values that are not explicitly mentioned in the field are considered 5394 unacceptable. Within Vary, the wildcard value means that the 5395 variance is unlimited. 5397 | *Note:* In practice, using wildcards in content negotiation has 5398 | limited practical value, because it is seldom useful to say, 5399 | for example, "I prefer image/* more or less than (some other 5400 | specific value)". Clients can explicitly request a 406 (Not 5401 | Acceptable) response if a more preferred format is not 5402 | available by sending Accept: */*;q=0, but they still need to be 5403 | able to handle a different response, since the server is 5404 | allowed to ignore their preference. 5406 12.5. Content Negotiation Fields 5408 12.5.1. Accept 5410 The "Accept" header field can be used by user agents to specify their 5411 preferences regarding response media types. For example, Accept 5412 header fields can be used to indicate that the request is 5413 specifically limited to a small set of desired types, as in the case 5414 of a request for an in-line image. 5416 When sent by a server in a response, Accept provides information 5417 about what content types are preferred in the content of a subsequent 5418 request to the same resource. 5420 Accept = #( media-range [ weight ] ) 5422 media-range = ( "*/*" 5423 / ( type "/" "*" ) 5424 / ( type "/" subtype ) 5425 ) parameters 5427 The asterisk "*" character is used to group media types into ranges, 5428 with "*/*" indicating all media types and "type/*" indicating all 5429 subtypes of that type. The media-range can include media type 5430 parameters that are applicable to that range. 5432 Each media-range might be followed by optional applicable media type 5433 parameters (e.g., charset), followed by an optional "q" parameter for 5434 indicating a relative weight (Section 12.4.2). 5436 Previous specifications allowed additional extension parameters to 5437 appear after the weight parameter. The accept extension grammar 5438 (accept-params, accept-ext) has been removed because it had a 5439 complicated definition, was not being used in practice, and is more 5440 easily deployed through new header fields. Senders using weights 5441 SHOULD send "q" last (after all media-range parameters). Recipients 5442 SHOULD process any parameter named "q" as weight, regardless of 5443 parameter ordering. 5445 | *Note:* Use of the "q" parameter name to control content 5446 | negotiation would interfere with any media type parameter 5447 | having the same name. Hence, the media type registry disallows 5448 | parameters named "q". 5450 The example 5452 Accept: audio/*; q=0.2, audio/basic 5453 is interpreted as "I prefer audio/basic, but send me any audio type 5454 if it is the best available after an 80% markdown in quality". 5456 A more elaborate example is 5458 Accept: text/plain; q=0.5, text/html, 5459 text/x-dvi; q=0.8, text/x-c 5461 Verbally, this would be interpreted as "text/html and text/x-c are 5462 the equally preferred media types, but if they do not exist, then 5463 send the text/x-dvi representation, and if that does not exist, send 5464 the text/plain representation". 5466 Media ranges can be overridden by more specific media ranges or 5467 specific media types. If more than one media range applies to a 5468 given type, the most specific reference has precedence. For example, 5470 Accept: text/*, text/plain, text/plain;format=flowed, */* 5472 have the following precedence: 5474 1. text/plain;format=flowed 5476 2. text/plain 5478 3. text/* 5480 4. */* 5482 The media type quality factor associated with a given type is 5483 determined by finding the media range with the highest precedence 5484 that matches the type. For example, 5486 Accept: text/*;q=0.3, text/plain;q=0.7, text/plain;format=flowed, 5487 text/plain;format=fixed;q=0.4, */*;q=0.5 5489 would cause the following values to be associated: 5491 +==========================+===============+ 5492 | Media Type | Quality Value | 5493 +==========================+===============+ 5494 | text/plain;format=flowed | 1 | 5495 +--------------------------+---------------+ 5496 | text/plain | 0.7 | 5497 +--------------------------+---------------+ 5498 | text/html | 0.3 | 5499 +--------------------------+---------------+ 5500 | image/jpeg | 0.5 | 5501 +--------------------------+---------------+ 5502 | text/plain;format=fixed | 0.4 | 5503 +--------------------------+---------------+ 5504 | text/html;level=3 | 0.7 | 5505 +--------------------------+---------------+ 5507 Table 5 5509 | *Note:* A user agent might be provided with a default set of 5510 | quality values for certain media ranges. However, unless the 5511 | user agent is a closed system that cannot interact with other 5512 | rendering agents, this default set ought to be configurable by 5513 | the user. 5515 12.5.2. Accept-Charset 5517 The "Accept-Charset" header field can be sent by a user agent to 5518 indicate its preferences for charsets in textual response content. 5519 For example, this field allows user agents capable of understanding 5520 more comprehensive or special-purpose charsets to signal that 5521 capability to an origin server that is capable of representing 5522 information in those charsets. 5524 Accept-Charset = #( ( token / "*" ) [ weight ] ) 5526 Charset names are defined in Section 8.3.2. A user agent MAY 5527 associate a quality value with each charset to indicate the user's 5528 relative preference for that charset, as defined in Section 12.4.2. 5529 An example is 5531 Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 5533 The special value "*", if present in the Accept-Charset header field, 5534 matches every charset that is not mentioned elsewhere in the field. 5536 | *Note:* Accept-Charset is deprecated because UTF-8 has become 5537 | nearly ubiquitous and sending a detailed list of user-preferred 5538 | charsets wastes bandwidth, increases latency, and makes passive 5539 | fingerprinting far too easy (Section 17.13). Most general- 5540 | purpose user agents do not send Accept-Charset, unless 5541 | specifically configured to do so. 5543 12.5.3. Accept-Encoding 5545 The "Accept-Encoding" header field can be used to indicate 5546 preferences regarding the use of content codings (Section 8.4.1). 5548 When sent by a user agent in a request, Accept-Encoding indicates the 5549 content codings acceptable in a response. 5551 When sent by a server in a response, Accept-Encoding provides 5552 information about what content codings are preferred in the content 5553 of a subsequent request to the same resource. 5555 An "identity" token is used as a synonym for "no encoding" in order 5556 to communicate when no encoding is preferred. 5558 Accept-Encoding = #( codings [ weight ] ) 5559 codings = content-coding / "identity" / "*" 5561 Each codings value MAY be given an associated quality value (weight) 5562 representing the preference for that encoding, as defined in 5563 Section 12.4.2. The asterisk "*" symbol in an Accept-Encoding field 5564 matches any available content coding not explicitly listed in the 5565 field. 5567 Examples: 5569 Accept-Encoding: compress, gzip 5570 Accept-Encoding: 5571 Accept-Encoding: * 5572 Accept-Encoding: compress;q=0.5, gzip;q=1.0 5573 Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 5575 A server tests whether a content coding for a given representation is 5576 acceptable using these rules: 5578 1. If no Accept-Encoding header field is in the request, any content 5579 coding is considered acceptable by the user agent. 5581 2. If the representation has no content coding, then it is 5582 acceptable by default unless specifically excluded by the Accept- 5583 Encoding header field stating either "identity;q=0" or "*;q=0" 5584 without a more specific entry for "identity". 5586 3. If the representation's content coding is one of the content 5587 codings listed in the Accept-Encoding field value, then it is 5588 acceptable unless it is accompanied by a qvalue of 0. (As 5589 defined in Section 12.4.2, a qvalue of 0 means "not acceptable".) 5591 A representation could be encoded with multiple content codings. 5592 However, most content codings are alternative ways to accomplish the 5593 same purpose (e.g., data compression). When selecting between 5594 multiple content codings that have the same purpose, the acceptable 5595 content coding with the highest non-zero qvalue is preferred. 5597 An Accept-Encoding header field with a field value that is empty 5598 implies that the user agent does not want any content coding in 5599 response. If an Accept-Encoding header field is present in a request 5600 and none of the available representations for the response have a 5601 content coding that is listed as acceptable, the origin server SHOULD 5602 send a response without any content coding. 5604 When the Accept-Encoding header field is present in a response, it 5605 indicates what content codings the resource was willing to accept in 5606 the associated request. The field value is evaluated the same way as 5607 in a request. 5609 Note that this information is specific to the associated request; the 5610 set of supported encodings might be different for other resources on 5611 the same server and could change over time or depend on other aspects 5612 of the request (such as the request method). 5614 Servers that fail a request due to an unsupported content coding 5615 ought to respond with a 415 (Unsupported Media Type) status and 5616 include an Accept-Encoding header field in that response, allowing 5617 clients to distinguish between issues related to content codings and 5618 media types. In order to avoid confusion with issues related to 5619 media types, servers that fail a request with a 415 status for 5620 reasons unrelated to content codings MUST NOT include the Accept- 5621 Encoding header field. 5623 The most common use of Accept-Encoding is in responses with a 415 5624 (Unsupported Media Type) status code, in response to optimistic use 5625 of a content coding by clients. However, the header field can also 5626 be used to indicate to clients that content codings are supported, to 5627 optimize future interactions. For example, a resource might include 5628 it in a 2xx (Successful) response when the request content was big 5629 enough to justify use of a compression coding but the client failed 5630 do so. 5632 12.5.4. Accept-Language 5634 The "Accept-Language" header field can be used by user agents to 5635 indicate the set of natural languages that are preferred in the 5636 response. Language tags are defined in Section 8.5.1. 5638 Accept-Language = #( language-range [ weight ] ) 5639 language-range = 5640 5642 Each language-range can be given an associated quality value 5643 representing an estimate of the user's preference for the languages 5644 specified by that range, as defined in Section 12.4.2. For example, 5646 Accept-Language: da, en-gb;q=0.8, en;q=0.7 5648 would mean: "I prefer Danish, but will accept British English and 5649 other types of English". 5651 Note that some recipients treat the order in which language tags are 5652 listed as an indication of descending priority, particularly for tags 5653 that are assigned equal quality values (no value is the same as q=1). 5654 However, this behavior cannot be relied upon. For consistency and to 5655 maximize interoperability, many user agents assign each language tag 5656 a unique quality value while also listing them in order of decreasing 5657 quality. Additional discussion of language priority lists can be 5658 found in Section 2.3 of [RFC4647]. 5660 For matching, Section 3 of [RFC4647] defines several matching 5661 schemes. Implementations can offer the most appropriate matching 5662 scheme for their requirements. The "Basic Filtering" scheme 5663 ([RFC4647], Section 3.3.1) is identical to the matching scheme that 5664 was previously defined for HTTP in Section 14.4 of [RFC2616]. 5666 It might be contrary to the privacy expectations of the user to send 5667 an Accept-Language header field with the complete linguistic 5668 preferences of the user in every request (Section 17.13). 5670 Since intelligibility is highly dependent on the individual user, 5671 user agents need to allow user control over the linguistic preference 5672 (either through configuration of the user agent itself or by 5673 defaulting to a user controllable system setting). A user agent that 5674 does not provide such control to the user MUST NOT send an Accept- 5675 Language header field. 5677 | *Note:* User agents ought to provide guidance to users when 5678 | setting a preference, since users are rarely familiar with the 5679 | details of language matching as described above. For example, 5680 | users might assume that on selecting "en-gb", they will be 5681 | served any kind of English document if British English is not 5682 | available. A user agent might suggest, in such a case, to add 5683 | "en" to the list for better matching behavior. 5685 12.5.5. Vary 5687 The "Vary" header field in a response describes what parts of a 5688 request message, aside from the method and target URI, might have 5689 influenced the origin server's process for selecting the content of 5690 this response. 5692 Vary = #( "*" / field-name ) 5694 A Vary field value is either the wildcard member "*" or a list of 5695 request field names, known as the selecting header fields, that might 5696 have had a role in selecting the representation for this response. 5697 Potential selecting header fields are not limited to fields defined 5698 by this specification. 5700 A list containing the member "*" signals that other aspects of the 5701 request might have played a role in selecting the response 5702 representation, possibly including aspects outside the message syntax 5703 (e.g., the client's network address). A recipient will not be able 5704 to determine whether this response is appropriate for a later request 5705 without forwarding the request to the origin server. A proxy MUST 5706 NOT generate "*" in a Vary field value. 5708 For example, a response that contains 5710 Vary: accept-encoding, accept-language 5712 indicates that the origin server might have used the request's 5713 Accept-Encoding and Accept-Language header fields (or lack thereof) 5714 as determining factors while choosing the content for this response. 5716 A Vary field containing a list of field names has two purposes: 5718 1. To inform cache recipients that they MUST NOT use this response 5719 to satisfy a later request unless the later request has the same 5720 values for the listed header fields as the original request 5721 (Section 4.1 of [CACHING]) or reuse of the response has been 5722 validated by the origin server. In other words, Vary expands the 5723 cache key required to match a new request to the stored cache 5724 entry. 5726 2. To inform user agent recipients that this response was subject to 5727 content negotiation (Section 12) and a different representation 5728 might be sent in a subsequent request if other values are 5729 provided in the listed header fields (proactive negotiation). 5731 An origin server SHOULD generate a Vary header field on a cacheable 5732 response when it wishes that response to be selectively reused for 5733 subsequent requests. Generally, that is the case when the response 5734 content has been tailored to better fit the preferences expressed by 5735 those selecting header fields, such as when an origin server has 5736 selected the response's language based on the request's 5737 Accept-Language header field. 5739 Vary might be elided when an origin server considers variance in 5740 content selection to be less significant than Vary's performance 5741 impact on caching, particularly when reuse is already limited by 5742 Cache-Control response directives (Section 5.2 of [CACHING]). 5744 There is no need to send the Authorization field name in Vary because 5745 reuse of that response for a different user is prohibited by the 5746 field definition (Section 11.6.2). Likewise, if the response content 5747 has been selected or influenced by network region but the origin 5748 server wants the cached response to be reused even if recipients move 5749 from one region to another, then there is no need for the origin 5750 server to indicate such variance in Vary. 5752 13. Conditional Requests 5754 A conditional request is an HTTP request with one or more request 5755 header fields that indicate a precondition to be tested before 5756 applying the request method to the target resource. Section 13.2 5757 defines when to evaluate preconditions and their order of precedence 5758 when more than one precondition is present. 5760 Conditional GET requests are the most efficient mechanism for HTTP 5761 cache updates [CACHING]. Conditionals can also be applied to state- 5762 changing methods, such as PUT and DELETE, to prevent the "lost 5763 update" problem: one client accidentally overwriting the work of 5764 another client that has been acting in parallel. 5766 13.1. Preconditions 5768 Preconditions are usually defined with respect to a state of the 5769 target resource as a whole (its current value set) or the state as 5770 observed in a previously obtained representation (one value in that 5771 set). If a resource has multiple current representations, each with 5772 its own observable state, a precondition will assume that the mapping 5773 of each request to a selected representation (Section 3.2) is 5774 consistent over time. Regardless, if the mapping is inconsistent or 5775 the server is unable to select an appropriate representation, then no 5776 harm will result when the precondition evaluates to false. 5778 Each precondition defined below consists of a comparison between a 5779 set of validators obtained from prior representations of the target 5780 resource to the current state of validators for the selected 5781 representation (Section 8.8). Hence, these preconditions evaluate 5782 whether the state of the target resource has changed since a given 5783 state known by the client. The effect of such an evaluation depends 5784 on the method semantics and choice of conditional, as defined in 5785 Section 13.2. 5787 Other preconditions, defined by other specifications as extension 5788 fields, might place conditions on all recipients, on the state of the 5789 target resource in general, or on a group of resources. For 5790 instance, the "If" header field in WebDAV can make a request 5791 conditional on various aspects of multiple resources, such as locks, 5792 if the recipient understands and implements that field ([WEBDAV], 5793 Section 10.4). 5795 Extensibility of preconditions is only possible when the precondition 5796 can be safely ignored if unknown (like If-Modified-Since), when 5797 deployment can be assumed for a given use case, or when 5798 implementation is signaled by some other property of the target 5799 resource. This encourages a focus on mutually agreed deployment of 5800 common standards. 5802 13.1.1. If-Match 5804 The "If-Match" header field makes the request method conditional on 5805 the recipient origin server either having at least one current 5806 representation of the target resource, when the field value is "*", 5807 or having a current representation of the target resource that has an 5808 entity-tag matching a member of the list of entity-tags provided in 5809 the field value. 5811 An origin server MUST use the strong comparison function when 5812 comparing entity-tags for If-Match (Section 8.8.3.2), since the 5813 client intends this precondition to prevent the method from being 5814 applied if there have been any changes to the representation data. 5816 If-Match = "*" / #entity-tag 5818 Examples: 5820 If-Match: "xyzzy" 5821 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 5822 If-Match: * 5824 If-Match is most often used with state-changing methods (e.g., POST, 5825 PUT, DELETE) to prevent accidental overwrites when multiple user 5826 agents might be acting in parallel on the same resource (i.e., to 5827 prevent the "lost update" problem). In general, it can be used with 5828 any method that involves the selection or modification of a 5829 representation to abort the request if the selected representation's 5830 current entity-tag is not a member within the If-Match field value. 5832 When an origin server receives a request that selects a 5833 representation and that request includes an If-Match header field, 5834 the origin server MUST evaluate the If-Match condition as per 5835 Section 13.2 prior to performing the method. 5837 To evaluate a received If-Match header field: 5839 1. If the field value is "*", the condition is true if the origin 5840 server has a current representation for the target resource. 5842 2. If the field value is a list of entity-tags, the condition is 5843 true if any of the listed tags match the entity-tag of the 5844 selected representation. 5846 3. Otherwise, the condition is false. 5848 An origin server that evaluates an If-Match condition MUST NOT 5849 perform the requested method if the condition evaluates to false. 5850 Instead, the origin server MAY indicate that the conditional request 5851 failed by responding with a 412 (Precondition Failed) status code. 5852 Alternatively, if the request is a state-changing operation that 5853 appears to have already been applied to the selected representation, 5854 the origin server MAY respond with a 2xx (Successful) status code 5855 (i.e., the change requested by the user agent has already succeeded, 5856 but the user agent might not be aware of it, perhaps because the 5857 prior response was lost or an equivalent change was made by some 5858 other user agent). 5860 Allowing an origin server to send a success response when a change 5861 request appears to have already been applied is more efficient for 5862 many authoring use cases, but comes with some risk if multiple user 5863 agents are making change requests that are very similar but not 5864 cooperative. For example, multiple user agents writing to a common 5865 resource as a semaphore (e.g., a non-atomic increment) are likely to 5866 collide and potentially lose important state transitions. For those 5867 kinds of resources, an origin server is better off being stringent in 5868 sending 412 for every failed precondition on an unsafe method. In 5869 other cases, excluding the ETag field from a success response might 5870 encourage the user agent to perform a GET as its next request to 5871 eliminate confusion about the resource's current state. 5873 A client MAY send an If-Match header field in a GET request to 5874 indicate that it would prefer a 412 (Precondition Failed) response if 5875 the selected representation does not match. However, this is only 5876 useful in range requests (Section 14), for completing a previously 5877 received partial representation, when there is no desire for a new 5878 representation. If-Range (Section 13.1.5) is better suited for range 5879 requests when the client prefers to receive a new representation. 5881 A cache or intermediary MAY ignore If-Match because its 5882 interoperability features are only necessary for an origin server. 5884 Note that an If-Match header field with a list value containing "*" 5885 and other values (including other instances of "*") is syntactically 5886 invalid (therefore not allowed to be generated) and furthermore is 5887 unlikely to be interoperable. 5889 13.1.2. If-None-Match 5891 The "If-None-Match" header field makes the request method conditional 5892 on a recipient cache or origin server either not having any current 5893 representation of the target resource, when the field value is "*", 5894 or having a selected representation with an entity-tag that does not 5895 match any of those listed in the field value. 5897 A recipient MUST use the weak comparison function when comparing 5898 entity-tags for If-None-Match (Section 8.8.3.2), since weak entity- 5899 tags can be used for cache validation even if there have been changes 5900 to the representation data. 5902 If-None-Match = "*" / #entity-tag 5904 Examples: 5906 If-None-Match: "xyzzy" 5907 If-None-Match: W/"xyzzy" 5908 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 5909 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 5910 If-None-Match: * 5912 If-None-Match is primarily used in conditional GET requests to enable 5913 efficient updates of cached information with a minimum amount of 5914 transaction overhead. When a client desires to update one or more 5915 stored responses that have entity-tags, the client SHOULD generate an 5916 If-None-Match header field containing a list of those entity-tags 5917 when making a GET request; this allows recipient servers to send a 5918 304 (Not Modified) response to indicate when one of those stored 5919 responses matches the selected representation. 5921 If-None-Match can also be used with a value of "*" to prevent an 5922 unsafe request method (e.g., PUT) from inadvertently modifying an 5923 existing representation of the target resource when the client 5924 believes that the resource does not have a current representation 5925 (Section 9.2.1). This is a variation on the "lost update" problem 5926 that might arise if more than one client attempts to create an 5927 initial representation for the target resource. 5929 When an origin server receives a request that selects a 5930 representation and that request includes an If-None-Match header 5931 field, the origin server MUST evaluate the If-None-Match condition as 5932 per Section 13.2 prior to performing the method. 5934 To evaluate a received If-None-Match header field: 5936 1. If the field value is "*", the condition is false if the origin 5937 server has a current representation for the target resource. 5939 2. If the field value is a list of entity-tags, the condition is 5940 false if one of the listed tags matches the entity-tag of the 5941 selected representation. 5943 3. Otherwise, the condition is true. 5945 An origin server that evaluates an If-None-Match condition MUST NOT 5946 perform the requested method if the condition evaluates to false; 5947 instead, the origin server MUST respond with either a) the 304 (Not 5948 Modified) status code if the request method is GET or HEAD or b) the 5949 412 (Precondition Failed) status code for all other request methods. 5951 Requirements on cache handling of a received If-None-Match header 5952 field are defined in Section 4.3.2 of [CACHING]. 5954 Note that an If-None-Match header field with a list value containing 5955 "*" and other values (including other instances of "*") is 5956 syntactically invalid (therefore not allowed to be generated) and 5957 furthermore is unlikely to be interoperable. 5959 13.1.3. If-Modified-Since 5961 The "If-Modified-Since" header field makes a GET or HEAD request 5962 method conditional on the selected representation's modification date 5963 being more recent than the date provided in the field value. 5964 Transfer of the selected representation's data is avoided if that 5965 data has not changed. 5967 If-Modified-Since = HTTP-date 5969 An example of the field is: 5971 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 5973 A recipient MUST ignore If-Modified-Since if the request contains an 5974 If-None-Match header field; the condition in If-None-Match is 5975 considered to be a more accurate replacement for the condition in If- 5976 Modified-Since, and the two are only combined for the sake of 5977 interoperating with older intermediaries that might not implement 5978 If-None-Match. 5980 A recipient MUST ignore the If-Modified-Since header field if the 5981 received field value is not a valid HTTP-date, the field value has 5982 more than one member, or if the request method is neither GET nor 5983 HEAD. 5985 A recipient MUST ignore the If-Modified-Since header field if the 5986 resource does not have a modification date available. 5988 A recipient MUST interpret an If-Modified-Since field value's 5989 timestamp in terms of the origin server's clock. 5991 If-Modified-Since is typically used for two distinct purposes: 1) to 5992 allow efficient updates of a cached representation that does not have 5993 an entity-tag and 2) to limit the scope of a web traversal to 5994 resources that have recently changed. 5996 When used for cache updates, a cache will typically use the value of 5997 the cached message's Last-Modified header field to generate the field 5998 value of If-Modified-Since. This behavior is most interoperable for 5999 cases where clocks are poorly synchronized or when the server has 6000 chosen to only honor exact timestamp matches (due to a problem with 6001 Last-Modified dates that appear to go "back in time" when the origin 6002 server's clock is corrected or a representation is restored from an 6003 archived backup). However, caches occasionally generate the field 6004 value based on other data, such as the Date header field of the 6005 cached message or the clock time at which the message was received, 6006 particularly when the cached message does not contain a Last-Modified 6007 header field. 6009 When used for limiting the scope of retrieval to a recent time 6010 window, a user agent will generate an If-Modified-Since field value 6011 based on either its own clock or a Date header field received from 6012 the server in a prior response. Origin servers that choose an exact 6013 timestamp match based on the selected representation's Last-Modified 6014 header field will not be able to help the user agent limit its data 6015 transfers to only those changed during the specified window. 6017 When an origin server receives a request that selects a 6018 representation and that request includes an If-Modified-Since header 6019 field without an If-None-Match header field, the origin server SHOULD 6020 evaluate the If-Modified-Since condition as per Section 13.2 prior to 6021 performing the method. 6023 To evaluate a received If-Modified-Since header field: 6025 1. If the selected representation's last modification date is 6026 earlier or equal to the date provided in the field value, the 6027 condition is false. 6029 2. Otherwise, the condition is true. 6031 An origin server that evaluates an If-Modified-Since condition SHOULD 6032 NOT perform the requested method if the condition evaluates to false; 6033 instead, the origin server SHOULD generate a 304 (Not Modified) 6034 response, including only those metadata that are useful for 6035 identifying or updating a previously cached response. 6037 Requirements on cache handling of a received If-Modified-Since header 6038 field are defined in Section 4.3.2 of [CACHING]. 6040 13.1.4. If-Unmodified-Since 6042 The "If-Unmodified-Since" header field makes the request method 6043 conditional on the selected representation's last modification date 6044 being earlier than or equal to the date provided in the field value. 6045 This field accomplishes the same purpose as If-Match for cases where 6046 the user agent does not have an entity-tag for the representation. 6048 If-Unmodified-Since = HTTP-date 6050 An example of the field is: 6052 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 6054 A recipient MUST ignore If-Unmodified-Since if the request contains 6055 an If-Match header field; the condition in If-Match is considered to 6056 be a more accurate replacement for the condition in If-Unmodified- 6057 Since, and the two are only combined for the sake of interoperating 6058 with older intermediaries that might not implement If-Match. 6060 A recipient MUST ignore the If-Unmodified-Since header field if the 6061 received field value is not a valid HTTP-date (including when the 6062 field value appears to be a list of dates). 6064 A recipient MUST ignore the If-Unmodified-Since header field if the 6065 resource does not have a modification date available. 6067 A recipient MUST interpret an If-Unmodified-Since field value's 6068 timestamp in terms of the origin server's clock. 6070 If-Unmodified-Since is most often used with state-changing methods 6071 (e.g., POST, PUT, DELETE) to prevent accidental overwrites when 6072 multiple user agents might be acting in parallel on a resource that 6073 does not supply entity-tags with its representations (i.e., to 6074 prevent the "lost update" problem). In general, it can be used with 6075 any method that involves the selection or modification of a 6076 representation to abort the request if the selected representation's 6077 last modification date has changed since the date provided in the If- 6078 Unmodified-Since field value. 6080 When an origin server receives a request that selects a 6081 representation and that request includes an If-Unmodified-Since 6082 header field without an If-Match header field, the origin server MUST 6083 evaluate the If-Unmodified-Since condition as per Section 13.2 prior 6084 to performing the method. 6086 To evaluate a received If-Unmodified-Since header field: 6088 1. If the selected representation's last modification date is 6089 earlier than or equal to the date provided in the field value, 6090 the condition is true. 6092 2. Otherwise, the condition is false. 6094 An origin server that evaluates an If-Unmodified-Since condition MUST 6095 NOT perform the requested method if the condition evaluates to false. 6096 Instead, the origin server MAY indicate that the conditional request 6097 failed by responding with a 412 (Precondition Failed) status code. 6098 Alternatively, if the request is a state-changing operation that 6099 appears to have already been applied to the selected representation, 6100 the origin server MAY respond with a 2xx (Successful) status code 6101 (i.e., the change requested by the user agent has already succeeded, 6102 but the user agent might not be aware of it, perhaps because the 6103 prior response was lost or an equivalent change was made by some 6104 other user agent). 6106 Allowing an origin server to send a success response when a change 6107 request appears to have already been applied is more efficient for 6108 many authoring use cases, but comes with some risk if multiple user 6109 agents are making change requests that are very similar but not 6110 cooperative. In those cases, an origin server is better off being 6111 stringent in sending 412 for every failed precondition on an unsafe 6112 method. 6114 A client MAY send an If-Unmodified-Since header field in a GET 6115 request to indicate that it would prefer a 412 (Precondition Failed) 6116 response if the selected representation has been modified. However, 6117 this is only useful in range requests (Section 14), for completing a 6118 previously received partial representation, when there is no desire 6119 for a new representation. If-Range (Section 13.1.5) is better suited 6120 for range requests when the client prefers to receive a new 6121 representation. 6123 A cache or intermediary MAY ignore If-Unmodified-Since because its 6124 interoperability features are only necessary for an origin server. 6126 13.1.5. If-Range 6128 The "If-Range" header field provides a special conditional request 6129 mechanism that is similar to the If-Match and If-Unmodified-Since 6130 header fields but that instructs the recipient to ignore the Range 6131 header field if the validator doesn't match, resulting in transfer of 6132 the new selected representation instead of a 412 (Precondition 6133 Failed) response. 6135 If a client has a partial copy of a representation and wishes to have 6136 an up-to-date copy of the entire representation, it could use the 6137 Range header field with a conditional GET (using either or both of 6138 If-Unmodified-Since and If-Match.) However, if the precondition 6139 fails because the representation has been modified, the client would 6140 then have to make a second request to obtain the entire current 6141 representation. 6143 The "If-Range" header field allows a client to "short-circuit" the 6144 second request. Informally, its meaning is as follows: if the 6145 representation is unchanged, send me the part(s) that I am requesting 6146 in Range; otherwise, send me the entire representation. 6148 If-Range = entity-tag / HTTP-date 6150 A valid entity-tag can be distinguished from a valid HTTP-date by 6151 examining the first three characters for a DQUOTE. 6153 A client MUST NOT generate an If-Range header field in a request that 6154 does not contain a Range header field. A server MUST ignore an If- 6155 Range header field received in a request that does not contain a 6156 Range header field. An origin server MUST ignore an If-Range header 6157 field received in a request for a target resource that does not 6158 support Range requests. 6160 A client MUST NOT generate an If-Range header field containing an 6161 entity-tag that is marked as weak. A client MUST NOT generate an If- 6162 Range header field containing an HTTP-date unless the client has no 6163 entity-tag for the corresponding representation and the date is a 6164 strong validator in the sense defined by Section 8.8.2.2. 6166 A server that receives an If-Range header field on a Range request 6167 MUST evaluate the condition as per Section 13.2 prior to performing 6168 the method. 6170 To evaluate a received If-Range header field containing an HTTP-date: 6172 1. If the HTTP-date validator provided is not a strong validator in 6173 the sense defined by Section 8.8.2.2, the condition is false. 6175 2. If the HTTP-date validator provided exactly matches the 6176 Last-Modified field value for the selected representation, the 6177 condition is true. 6179 3. Otherwise, the condition is false. 6181 To evaluate a received If-Range header field containing an 6182 entity-tag: 6184 1. If the entity-tag validator provided exactly matches the ETag 6185 field value for the selected representation using the strong 6186 comparison function (Section 8.8.3.2), the condition is true. 6188 2. Otherwise, the condition is false. 6190 A recipient of an If-Range header field MUST ignore the Range header 6191 field if the If-Range condition evaluates to false. Otherwise, the 6192 recipient SHOULD process the Range header field as requested. 6194 Note that the If-Range comparison is by exact match, including when 6195 the validator is an HTTP-date, and so differs from the "earlier than 6196 or equal to" comparison used when evaluating an If-Unmodified-Since 6197 conditional. 6199 13.2. Evaluation of Preconditions 6201 13.2.1. When to Evaluate 6203 Except when excluded below, a recipient cache or origin server MUST 6204 evaluate received request preconditions after it has successfully 6205 performed its normal request checks and just before it would process 6206 the request content (if any) or perform the action associated with 6207 the request method. A server MUST ignore all received preconditions 6208 if its response to the same request without those conditions, prior 6209 to processing the request content, would have been a status code 6210 other than a 2xx (Successful) or 412 (Precondition Failed). In other 6211 words, redirects and failures that can be detected before significant 6212 processing occurs take precedence over the evaluation of 6213 preconditions. 6215 A server that is not the origin server for the target resource and 6216 cannot act as a cache for requests on the target resource MUST NOT 6217 evaluate the conditional request header fields defined by this 6218 specification, and it MUST forward them if the request is forwarded, 6219 since the generating client intends that they be evaluated by a 6220 server that can provide a current representation. Likewise, a server 6221 MUST ignore the conditional request header fields defined by this 6222 specification when received with a request method that does not 6223 involve the selection or modification of a selected representation, 6224 such as CONNECT, OPTIONS, or TRACE. 6226 Note that protocol extensions can modify the conditions under which 6227 preconditions are evaluated or the consequences of their evaluation. 6228 For example, the "immutable" cache directive (defined by [RFC8246]) 6229 instructs caches to forgo forwarding conditional requests when they 6230 hold a fresh response. 6232 Although conditional request header fields are defined as being 6233 usable with the HEAD method (to keep HEAD's semantics consistent with 6234 those of GET), there is no point in sending a conditional HEAD 6235 because a successful response is around the same size as a 304 (Not 6236 Modified) response and more useful than a 412 (Precondition Failed) 6237 response. 6239 13.2.2. Precedence of Preconditions 6241 When more than one conditional request header field is present in a 6242 request, the order in which the fields are evaluated becomes 6243 important. In practice, the fields defined in this document are 6244 consistently implemented in a single, logical order, since "lost 6245 update" preconditions have more strict requirements than cache 6246 validation, a validated cache is more efficient than a partial 6247 response, and entity tags are presumed to be more accurate than date 6248 validators. 6250 A recipient cache or origin server MUST evaluate the request 6251 preconditions defined by this specification in the following order: 6253 1. When recipient is the origin server and If-Match is present, 6254 evaluate the If-Match precondition: 6256 * if true, continue to step 3 6258 * if false, respond 412 (Precondition Failed) unless it can be 6259 determined that the state-changing request has already 6260 succeeded (see Section 13.1.1) 6262 2. When recipient is the origin server, If-Match is not present, and 6263 If-Unmodified-Since is present, evaluate the If-Unmodified-Since 6264 precondition: 6266 * if true, continue to step 3 6268 * if false, respond 412 (Precondition Failed) unless it can be 6269 determined that the state-changing request has already 6270 succeeded (see Section 13.1.4) 6272 3. When If-None-Match is present, evaluate the If-None-Match 6273 precondition: 6275 * if true, continue to step 5 6277 * if false for GET/HEAD, respond 304 (Not Modified) 6279 * if false for other methods, respond 412 (Precondition Failed) 6281 4. When the method is GET or HEAD, If-None-Match is not present, and 6282 If-Modified-Since is present, evaluate the If-Modified-Since 6283 precondition: 6285 * if true, continue to step 5 6287 * if false, respond 304 (Not Modified) 6289 5. When the method is GET and both Range and If-Range are present, 6290 evaluate the If-Range precondition: 6292 * if true and the Range is applicable to the selected 6293 representation, respond 206 (Partial Content) 6295 * otherwise, ignore the Range header field and respond 200 (OK) 6297 6. Otherwise, 6299 * perform the requested method and respond according to its 6300 success or failure. 6302 Any extension to HTTP that defines additional conditional request 6303 header fields ought to define the order for evaluating such fields in 6304 relation to those defined in this document and other conditionals 6305 that might be found in practice. 6307 14. Range Requests 6309 Clients often encounter interrupted data transfers as a result of 6310 canceled requests or dropped connections. When a client has stored a 6311 partial representation, it is desirable to request the remainder of 6312 that representation in a subsequent request rather than transfer the 6313 entire representation. Likewise, devices with limited local storage 6314 might benefit from being able to request only a subset of a larger 6315 representation, such as a single page of a very large document, or 6316 the dimensions of an embedded image. 6318 Range requests are an OPTIONAL feature of HTTP, designed so that 6319 recipients not implementing this feature (or not supporting it for 6320 the target resource) can respond as if it is a normal GET request 6321 without impacting interoperability. Partial responses are indicated 6322 by a distinct status code to not be mistaken for full responses by 6323 caches that might not implement the feature. 6325 14.1. Range Units 6327 Representation data can be partitioned into subranges when there are 6328 addressable structural units inherent to that data's content coding 6329 or media type. For example, octet (a.k.a., byte) boundaries are a 6330 structural unit common to all representation data, allowing 6331 partitions of the data to be identified as a range of bytes at some 6332 offset from the start or end of that data. 6334 This general notion of a _range unit_ is used in the Accept-Ranges 6335 (Section 14.3) response header field to advertise support for range 6336 requests, the Range (Section 14.2) request header field to delineate 6337 the parts of a representation that are requested, and the 6338 Content-Range (Section 14.4) header field to describe which part of a 6339 representation is being transferred. 6341 range-unit = token 6343 All range unit names are case-insensitive and ought to be registered 6344 within the "HTTP Range Unit Registry", as defined in Section 16.5.1. 6346 Range units are intended to be extensible, as described in 6347 Section 16.5. 6349 14.1.1. Range Specifiers 6351 Ranges are expressed in terms of a range unit paired with a set of 6352 range specifiers. The range unit name determines what kinds of 6353 range-spec are applicable to its own specifiers. Hence, the 6354 following grammar is generic: each range unit is expected to specify 6355 requirements on when int-range, suffix-range, and other-range are 6356 allowed. 6358 A range request can specify a single range or a set of ranges within 6359 a single representation. 6361 ranges-specifier = range-unit "=" range-set 6362 range-set = 1#range-spec 6363 range-spec = int-range 6364 / suffix-range 6365 / other-range 6367 An int-range is a range expressed as two non-negative integers or as 6368 one non-negative integer through to the end of the representation 6369 data. The range unit specifies what the integers mean (e.g., they 6370 might indicate unit offsets from the beginning, inclusive numbered 6371 parts, etc.). 6373 int-range = first-pos "-" [ last-pos ] 6374 first-pos = 1*DIGIT 6375 last-pos = 1*DIGIT 6377 An int-range is invalid if the last-pos value is present and less 6378 than the first-pos. 6380 A suffix-range is a range expressed as a suffix of the representation 6381 data with the provided non-negative integer maximum length (in range 6382 units). In other words, the last N units of the representation data. 6384 suffix-range = "-" suffix-length 6385 suffix-length = 1*DIGIT 6387 To provide for extensibility, the other-range rule is a mostly 6388 unconstrained grammar that allows application-specific or future 6389 range units to define additional range specifiers. 6391 other-range = 1*( %x21-2B / %x2D-7E ) 6392 ; 1*(VCHAR excluding comma) 6394 14.1.2. Byte Ranges 6396 The "bytes" range unit is used to express subranges of a 6397 representation data's octet sequence. Each byte range is expressed 6398 as an integer range at some offset, relative to either the beginning 6399 (int-range) or end (suffix-range) of the representation data. Byte 6400 ranges do not use the other-range specifier. 6402 The first-pos value in a bytes int-range gives the offset of the 6403 first byte in a range. The last-pos value gives the offset of the 6404 last byte in the range; that is, the byte positions specified are 6405 inclusive. Byte offsets start at zero. 6407 If the representation data has a content coding applied, each byte 6408 range is calculated with respect to the encoded sequence of bytes, 6409 not the sequence of underlying bytes that would be obtained after 6410 decoding. 6412 Examples of bytes range specifiers: 6414 * The first 500 bytes (byte offsets 0-499, inclusive): 6416 bytes=0-499 6418 * The second 500 bytes (byte offsets 500-999, inclusive): 6420 bytes=500-999 6422 A client can limit the number of bytes requested without knowing the 6423 size of the selected representation. If the last-pos value is 6424 absent, or if the value is greater than or equal to the current 6425 length of the representation data, the byte range is interpreted as 6426 the remainder of the representation (i.e., the server replaces the 6427 value of last-pos with a value that is one less than the current 6428 length of the selected representation). 6430 A client can request the last N bytes (N > 0) of the selected 6431 representation using a suffix-range. If the selected representation 6432 is shorter than the specified suffix-length, the entire 6433 representation is used. 6435 Additional examples, assuming a representation of length 10000: 6437 * The final 500 bytes (byte offsets 9500-9999, inclusive): 6439 bytes=-500 6441 Or: 6443 bytes=9500- 6445 * The first and last bytes only (bytes 0 and 9999): 6447 bytes=0-0,-1 6449 * The first, middle, and last 1000 bytes: 6451 bytes= 0-999, 4500-5499, -1000 6453 * Other valid (but not canonical) specifications of the second 500 6454 bytes (byte offsets 500-999, inclusive): 6456 bytes=500-600,601-999 6457 bytes=500-700,601-999 6459 If a valid bytes range-set includes at least one range-spec with a 6460 first-pos that is less than the current length of the representation, 6461 or at least one suffix-range with a non-zero suffix-length, then the 6462 bytes range-set is satisfiable. Otherwise, the bytes range-set is 6463 unsatisfiable. 6465 If the selected representation has zero length, the only satisfiable 6466 form of range-spec is a suffix-range with a non-zero suffix-length. 6468 In the byte-range syntax, first-pos, last-pos, and suffix-length are 6469 expressed as decimal number of octets. Since there is no predefined 6470 limit to the length of content, recipients MUST anticipate 6471 potentially large decimal numerals and prevent parsing errors due to 6472 integer conversion overflows. 6474 14.2. Range 6476 The "Range" header field on a GET request modifies the method 6477 semantics to request transfer of only one or more subranges of the 6478 selected representation data (Section 8.1), rather than the entire 6479 selected representation. 6481 Range = ranges-specifier 6483 A server MAY ignore the Range header field. However, origin servers 6484 and intermediate caches ought to support byte ranges when possible, 6485 since they support efficient recovery from partially failed transfers 6486 and partial retrieval of large representations. 6488 A server MUST ignore a Range header field received with a request 6489 method which is unrecognized or for which range handling is not 6490 defined. For this specification, GET is the only method for which 6491 range handling is defined. 6493 An origin server MUST ignore a Range header field that contains a 6494 range unit it does not understand. A proxy MAY discard a Range 6495 header field that contains a range unit it does not understand. 6497 A server that supports range requests MAY ignore or reject a Range 6498 header field that consists of more than two overlapping ranges, or a 6499 set of many small ranges that are not listed in ascending order, 6500 since both are indications of either a broken client or a deliberate 6501 denial-of-service attack (Section 17.15). A client SHOULD NOT 6502 request multiple ranges that are inherently less efficient to process 6503 and transfer than a single range that encompasses the same data. 6505 A server that supports range requests MAY ignore a Range header field 6506 when the selected representation has no content (i.e., the selected 6507 representation's data is of zero length). 6509 A client that is requesting multiple ranges SHOULD list those ranges 6510 in ascending order (the order in which they would typically be 6511 received in a complete representation) unless there is a specific 6512 need to request a later part earlier. For example, a user agent 6513 processing a large representation with an internal catalog of parts 6514 might need to request later parts first, particularly if the 6515 representation consists of pages stored in reverse order and the user 6516 agent wishes to transfer one page at a time. 6518 The Range header field is evaluated after evaluating the precondition 6519 header fields defined in Section 13.1, and only if the result in 6520 absence of the Range header field would be a 200 (OK) response. In 6521 other words, Range is ignored when a conditional GET would result in 6522 a 304 (Not Modified) response. 6524 The If-Range header field (Section 13.1.5) can be used as a 6525 precondition to applying the Range header field. 6527 If all of the preconditions are true, the server supports the Range 6528 header field for the target resource, and the specified range(s) are 6529 valid and satisfiable (as defined in Section 14.1.2), the server 6530 SHOULD send a 206 (Partial Content) response with a content 6531 containing one or more partial representations that correspond to the 6532 satisfiable ranges requested. 6534 The above does not imply that a server will send all requested 6535 ranges. In some cases, it may only be possible (or efficient) to 6536 send a portion of the requested ranges first, while expecting the 6537 client to re-request the remaining portions later if they are still 6538 desired (see Section 15.3.7). 6540 If all of the preconditions are true, the server supports the Range 6541 header field for the target resource, and the specified range(s) are 6542 invalid or unsatisfiable, the server SHOULD send a 416 (Range Not 6543 Satisfiable) response. 6545 14.3. Accept-Ranges 6547 The "Accept-Ranges" field in a response indicates whether an upstream 6548 server supports range requests for the target resource. 6550 Accept-Ranges = acceptable-ranges 6551 acceptable-ranges = 1#range-unit 6553 For example, a server that supports byte-range requests 6554 (Section 14.1.2) can send the field 6556 Accept-Ranges: bytes 6557 to indicate that it supports byte range requests for that target 6558 resource, thereby encouraging its use by the client for future 6559 partial requests on the same request path. Range units are defined 6560 in Section 14.1. 6562 A client MAY generate range requests regardless of having received an 6563 Accept-Ranges field. The information only provides advice for the 6564 sake of improving performance and reducing unnecessary network 6565 transfers. 6567 Conversely, a client MUST NOT assume that receiving an Accept-Ranges 6568 field means that future range requests will return partial responses. 6569 The content might change, the server might only support range 6570 requests at certain times or under certain conditions, or a different 6571 intermediary might process the next request. 6573 A server that does not support any kind of range request for the 6574 target resource MAY send 6576 Accept-Ranges: none 6578 to advise the client not to attempt a range request on the same 6579 request path. The range unit "none" is reserved for this purpose. 6581 The Accept-Ranges field MAY be sent in a trailer section, but is 6582 preferred to be sent as a header field because the information is 6583 particularly useful for restarting large information transfers that 6584 have failed in mid-content (before the trailer section is received). 6586 14.4. Content-Range 6588 The "Content-Range" header field is sent in a single part 206 6589 (Partial Content) response to indicate the partial range of the 6590 selected representation enclosed as the message content, sent in each 6591 part of a multipart 206 response to indicate the range enclosed 6592 within each body part, and sent in 416 (Range Not Satisfiable) 6593 responses to provide information about the selected representation. 6595 Content-Range = range-unit SP 6596 ( range-resp / unsatisfied-range ) 6598 range-resp = incl-range "/" ( complete-length / "*" ) 6599 incl-range = first-pos "-" last-pos 6600 unsatisfied-range = "*/" complete-length 6602 complete-length = 1*DIGIT 6604 If a 206 (Partial Content) response contains a Content-Range header 6605 field with a range unit (Section 14.1) that the recipient does not 6606 understand, the recipient MUST NOT attempt to recombine it with a 6607 stored representation. A proxy that receives such a message SHOULD 6608 forward it downstream. 6610 Content-Range might also be sent as a request modifier to request a 6611 partial PUT, as described in Section 14.5, based on private 6612 agreements between client and origin server. A server MUST ignore a 6613 Content-Range header field received in a request with a method for 6614 which Content-Range support is not defined. 6616 For byte ranges, a sender SHOULD indicate the complete length of the 6617 representation from which the range has been extracted, unless the 6618 complete length is unknown or difficult to determine. An asterisk 6619 character ("*") in place of the complete-length indicates that the 6620 representation length was unknown when the header field was 6621 generated. 6623 The following example illustrates when the complete length of the 6624 selected representation is known by the sender to be 1234 bytes: 6626 Content-Range: bytes 42-1233/1234 6628 and this second example illustrates when the complete length is 6629 unknown: 6631 Content-Range: bytes 42-1233/* 6633 A Content-Range field value is invalid if it contains a range-resp 6634 that has a last-pos value less than its first-pos value, or a 6635 complete-length value less than or equal to its last-pos value. The 6636 recipient of an invalid Content-Range MUST NOT attempt to recombine 6637 the received content with a stored representation. 6639 A server generating a 416 (Range Not Satisfiable) response to a byte- 6640 range request SHOULD send a Content-Range header field with an 6641 unsatisfied-range value, as in the following example: 6643 Content-Range: bytes */1234 6645 The complete-length in a 416 response indicates the current length of 6646 the selected representation. 6648 The Content-Range header field has no meaning for status codes that 6649 do not explicitly describe its semantic. For this specification, 6650 only the 206 (Partial Content) and 416 (Range Not Satisfiable) status 6651 codes describe a meaning for Content-Range. 6653 The following are examples of Content-Range values in which the 6654 selected representation contains a total of 1234 bytes: 6656 * The first 500 bytes: 6658 Content-Range: bytes 0-499/1234 6660 * The second 500 bytes: 6662 Content-Range: bytes 500-999/1234 6664 * All except for the first 500 bytes: 6666 Content-Range: bytes 500-1233/1234 6668 * The last 500 bytes: 6670 Content-Range: bytes 734-1233/1234 6672 14.5. Partial PUT 6674 Some origin servers support PUT of a partial representation when the 6675 user agent sends a Content-Range header field (Section 14.4) in the 6676 request, though such support is inconsistent and depends on private 6677 agreements with user agents. In general, it requests that the state 6678 of the target resource be partly replaced with the enclosed content 6679 at an offset and length indicated by the Content-Range value, where 6680 the offset is relative to the current selected representation. 6682 An origin server SHOULD respond with a 400 (Bad Request) status code 6683 if it receives Content-Range on a PUT for a target resource that does 6684 not support partial PUT requests. 6686 Partial PUT is not backwards compatible with the original definition 6687 of PUT. It may result in the content being written as a complete 6688 replacement for the current representation. 6690 Partial resource updates are also possible by targeting a separately 6691 identified resource with state that overlaps or extends a portion of 6692 the larger resource, or by using a different method that has been 6693 specifically defined for partial updates (for example, the PATCH 6694 method defined in [RFC5789]). 6696 14.6. Media Type multipart/byteranges 6698 When a 206 (Partial Content) response message includes the content of 6699 multiple ranges, they are transmitted as body parts in a multipart 6700 message body ([RFC2046], Section 5.1) with the media type of 6701 "multipart/byteranges". 6703 The multipart/byteranges media type includes one or more body parts, 6704 each with its own Content-Type and Content-Range fields. The 6705 required boundary parameter specifies the boundary string used to 6706 separate each body part. 6708 Implementation Notes: 6710 1. Additional CRLFs might precede the first boundary string in the 6711 body. 6713 2. Although [RFC2046] permits the boundary string to be quoted, some 6714 existing implementations handle a quoted boundary string 6715 incorrectly. 6717 3. A number of clients and servers were coded to an early draft of 6718 the byteranges specification that used a media type of multipart/ 6719 x-byteranges , which is almost (but not quite) compatible with 6720 this type. 6722 Despite the name, the "multipart/byteranges" media type is not 6723 limited to byte ranges. The following example uses an "exampleunit" 6724 range unit: 6726 HTTP/1.1 206 Partial Content 6727 Date: Tue, 14 Nov 1995 06:25:24 GMT 6728 Last-Modified: Tue, 14 July 04:58:08 GMT 6729 Content-Length: 2331785 6730 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 6732 --THIS_STRING_SEPARATES 6733 Content-Type: video/example 6734 Content-Range: exampleunit 1.2-4.3/25 6736 ...the first range... 6737 --THIS_STRING_SEPARATES 6738 Content-Type: video/example 6739 Content-Range: exampleunit 11.2-14.3/25 6741 ...the second range 6742 --THIS_STRING_SEPARATES-- 6743 The following information serves as the registration form for the 6744 multipart/byteranges media type. 6746 Type name: multipart 6748 Subtype name: byteranges 6750 Required parameters: boundary 6752 Optional parameters: N/A 6754 Encoding considerations: only "7bit", "8bit", or "binary" are 6755 permitted 6757 Security considerations: see Section 17 6759 Interoperability considerations: N/A 6761 Published specification: This specification (see Section 14.6). 6763 Applications that use this media type: HTTP components supporting 6764 multiple ranges in a single request. 6766 Fragment identifier considerations: N/A 6768 Additional information: Deprecated alias names for this type: N/A 6770 Magic number(s): N/A 6772 File extension(s): N/A 6774 Macintosh file type code(s): N/A 6776 Person and email address to contact for further information: See Aut 6777 hors' Addresses section. 6779 Intended usage: COMMON 6781 Restrictions on usage: N/A 6783 Author: See Authors' Addresses section. 6785 Change controller: IESG 6787 15. Status Codes 6789 The status code of a response is a three-digit integer code that 6790 describes the result of the request and the semantics of the 6791 response, including whether the request was successful and what 6792 content is enclosed (if any). All valid status codes are within the 6793 range of 100 to 599, inclusive. 6795 The first digit of the status code defines the class of response. 6796 The last two digits do not have any categorization role. There are 6797 five values for the first digit: 6799 * 1xx (Informational): The request was received, continuing process 6801 * 2xx (Successful): The request was successfully received, 6802 understood, and accepted 6804 * 3xx (Redirection): Further action needs to be taken in order to 6805 complete the request 6807 * 4xx (Client Error): The request contains bad syntax or cannot be 6808 fulfilled 6810 * 5xx (Server Error): The server failed to fulfill an apparently 6811 valid request 6813 HTTP status codes are extensible. A client is not required to 6814 understand the meaning of all registered status codes, though such 6815 understanding is obviously desirable. However, a client MUST 6816 understand the class of any status code, as indicated by the first 6817 digit, and treat an unrecognized status code as being equivalent to 6818 the x00 status code of that class. 6820 For example, if a client receives an unrecognized status code of 471, 6821 it can see from the first digit that there was something wrong with 6822 its request and treat the response as if it had received a 400 (Bad 6823 Request) status code. The response message will usually contain a 6824 representation that explains the status. 6826 Values outside the range 100..599 are invalid. Implementations often 6827 use three-digit integer values outside of that range (i.e., 600..999) 6828 for internal communication of non-HTTP status (e.g., library errors). 6829 A client that receives a response with an invalid status code SHOULD 6830 process the response as if it had a 5xx (Server Error) status code. 6832 A single request can have multiple associated responses: zero or more 6833 _interim_ (non-final) responses with status codes in the 6834 "informational" (1xx) range, followed by exactly one _final_ response 6835 with a status code in one of the other ranges. 6837 15.1. Overview of Status Codes 6839 The status codes listed below are defined in this specification. The 6840 reason phrases listed here are only recommendations - they can be 6841 replaced by local equivalents or left out altogether without 6842 affecting the protocol. 6844 Responses with status codes that are defined as heuristically 6845 cacheable (e.g., 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 6846 414, and 501 in this specification) can be reused by a cache with 6847 heuristic expiration unless otherwise indicated by the method 6848 definition or explicit cache controls [CACHING]; all other status 6849 codes are not heuristically cacheable. 6851 Additional status codes, outside the scope of this specification, 6852 have been specified for use in HTTP. All such status codes ought to 6853 be registered within the "Hypertext Transfer Protocol (HTTP) Status 6854 Code Registry", as described in Section 16.2. 6856 15.2. Informational 1xx 6858 The _1xx (Informational)_ class of status code indicates an interim 6859 response for communicating connection status or request progress 6860 prior to completing the requested action and sending a final 6861 response. Since HTTP/1.0 did not define any 1xx status codes, a 6862 server MUST NOT send a 1xx response to an HTTP/1.0 client. 6864 A 1xx response is terminated by the end of the header section; it 6865 cannot contain content or trailers. 6867 A client MUST be able to parse one or more 1xx responses received 6868 prior to a final response, even if the client does not expect one. A 6869 user agent MAY ignore unexpected 1xx responses. 6871 A proxy MUST forward 1xx responses unless the proxy itself requested 6872 the generation of the 1xx response. For example, if a proxy adds an 6873 "Expect: 100-continue" header field when it forwards a request, then 6874 it need not forward the corresponding 100 (Continue) response(s). 6876 15.2.1. 100 Continue 6878 The _100 (Continue)_ status code indicates that the initial part of a 6879 request has been received and has not yet been rejected by the 6880 server. The server intends to send a final response after the 6881 request has been fully received and acted upon. 6883 When the request contains an Expect header field that includes a 6884 100-continue expectation, the 100 response indicates that the server 6885 wishes to receive the request content, as described in 6886 Section 10.1.1. The client ought to continue sending the request and 6887 discard the 100 response. 6889 If the request did not contain an Expect header field containing the 6890 100-continue expectation, the client can simply discard this interim 6891 response. 6893 15.2.2. 101 Switching Protocols 6895 The _101 (Switching Protocols)_ status code indicates that the server 6896 understands and is willing to comply with the client's request, via 6897 the Upgrade header field (Section 7.8), for a change in the 6898 application protocol being used on this connection. The server MUST 6899 generate an Upgrade header field in the response that indicates which 6900 protocol(s) will be in effect after this response. 6902 It is assumed that the server will only agree to switch protocols 6903 when it is advantageous to do so. For example, switching to a newer 6904 version of HTTP might be advantageous over older versions, and 6905 switching to a real-time, synchronous protocol might be advantageous 6906 when delivering resources that use such features. 6908 15.3. Successful 2xx 6910 The _2xx (Successful)_ class of status code indicates that the 6911 client's request was successfully received, understood, and accepted. 6913 15.3.1. 200 OK 6915 The _200 (OK)_ status code indicates that the request has succeeded. 6916 The content sent in a 200 response depends on the request method. 6917 For the methods defined by this specification, the intended meaning 6918 of the content can be summarized as: 6920 +================+============================================+ 6921 | request method | response content is a representation of | 6922 +================+============================================+ 6923 | GET | the target resource | 6924 +----------------+--------------------------------------------+ 6925 | HEAD | the target resource, like GET, but without | 6926 | | transferring the representation data | 6927 +----------------+--------------------------------------------+ 6928 | POST | the status of, or results obtained from, | 6929 | | the action | 6930 +----------------+--------------------------------------------+ 6931 | PUT, DELETE | the status of the action | 6932 +----------------+--------------------------------------------+ 6933 | OPTIONS | communication options for the target | 6934 | | resource | 6935 +----------------+--------------------------------------------+ 6936 | TRACE | the request message as received by the | 6937 | | server returning the trace | 6938 +----------------+--------------------------------------------+ 6940 Table 6 6942 Aside from responses to CONNECT, a 200 response is expected to 6943 contain message content unless the message framing explicitly 6944 indicates that the content has zero length. If some aspect of the 6945 request indicates a preference for no content upon success, the 6946 origin server ought to send a _204 (No Content)_ response instead. 6947 For CONNECT, there is no content because the successful result is a 6948 tunnel, which begins immediately after the 200 response header 6949 section. 6951 A 200 response is heuristically cacheable; i.e., unless otherwise 6952 indicated by the method definition or explicit cache controls (see 6953 Section 4.2.2 of [CACHING]). 6955 In 200 responses to GET or HEAD, an origin server SHOULD send any 6956 available validator fields (Section 8.8) for the selected 6957 representation, with both a strong entity-tag and a Last-Modified 6958 date being preferred. 6960 In 200 responses to state-changing methods, any validator fields 6961 (Section 8.8) sent in the response convey the current validators for 6962 the new representation formed as a result of successfully applying 6963 the request semantics. Note that the PUT method (Section 9.3.4) has 6964 additional requirements that might preclude sending such validators. 6966 15.3.2. 201 Created 6968 The _201 (Created)_ status code indicates that the request has been 6969 fulfilled and has resulted in one or more new resources being 6970 created. The primary resource created by the request is identified 6971 by either a Location header field in the response or, if no Location 6972 header field is received, by the target URI. 6974 The 201 response content typically describes and links to the 6975 resource(s) created. Any validator fields (Section 8.8) sent in the 6976 response convey the current validators for a new representation 6977 created by the request. Note that the PUT method (Section 9.3.4) has 6978 additional requirements that might preclude sending such validators. 6980 15.3.3. 202 Accepted 6982 The _202 (Accepted)_ status code indicates that the request has been 6983 accepted for processing, but the processing has not been completed. 6984 The request might or might not eventually be acted upon, as it might 6985 be disallowed when processing actually takes place. There is no 6986 facility in HTTP for re-sending a status code from an asynchronous 6987 operation. 6989 The 202 response is intentionally noncommittal. Its purpose is to 6990 allow a server to accept a request for some other process (perhaps a 6991 batch-oriented process that is only run once per day) without 6992 requiring that the user agent's connection to the server persist 6993 until the process is completed. The representation sent with this 6994 response ought to describe the request's current status and point to 6995 (or embed) a status monitor that can provide the user with an 6996 estimate of when the request will be fulfilled. 6998 15.3.4. 203 Non-Authoritative Information 7000 The _203 (Non-Authoritative Information)_ status code indicates that 7001 the request was successful but the enclosed content has been modified 7002 from that of the origin server's 200 (OK) response by a transforming 7003 proxy (Section 7.7). This status code allows the proxy to notify 7004 recipients when a transformation has been applied, since that 7005 knowledge might impact later decisions regarding the content. For 7006 example, future cache validation requests for the content might only 7007 be applicable along the same request path (through the same proxies). 7009 A 203 response is heuristically cacheable; i.e., unless otherwise 7010 indicated by the method definition or explicit cache controls (see 7011 Section 4.2.2 of [CACHING]). 7013 15.3.5. 204 No Content 7015 The _204 (No Content)_ status code indicates that the server has 7016 successfully fulfilled the request and that there is no additional 7017 content to send in the response content. Metadata in the response 7018 header fields refer to the target resource and its selected 7019 representation after the requested action was applied. 7021 For example, if a 204 status code is received in response to a PUT 7022 request and the response contains an ETag field, then the PUT was 7023 successful and the ETag field value contains the entity-tag for the 7024 new representation of that target resource. 7026 The 204 response allows a server to indicate that the action has been 7027 successfully applied to the target resource, while implying that the 7028 user agent does not need to traverse away from its current "document 7029 view" (if any). The server assumes that the user agent will provide 7030 some indication of the success to its user, in accord with its own 7031 interface, and apply any new or updated metadata in the response to 7032 its active representation. 7034 For example, a 204 status code is commonly used with document editing 7035 interfaces corresponding to a "save" action, such that the document 7036 being saved remains available to the user for editing. It is also 7037 frequently used with interfaces that expect automated data transfers 7038 to be prevalent, such as within distributed version control systems. 7040 A 204 response is terminated by the end of the header section; it 7041 cannot contain content or trailers. 7043 A 204 response is heuristically cacheable; i.e., unless otherwise 7044 indicated by the method definition or explicit cache controls (see 7045 Section 4.2.2 of [CACHING]). 7047 15.3.6. 205 Reset Content 7049 The _205 (Reset Content)_ status code indicates that the server has 7050 fulfilled the request and desires that the user agent reset the 7051 "document view", which caused the request to be sent, to its original 7052 state as received from the origin server. 7054 This response is intended to support a common data entry use case 7055 where the user receives content that supports data entry (a form, 7056 notepad, canvas, etc.), enters or manipulates data in that space, 7057 causes the entered data to be submitted in a request, and then the 7058 data entry mechanism is reset for the next entry so that the user can 7059 easily initiate another input action. 7061 Since the 205 status code implies that no additional content will be 7062 provided, a server MUST NOT generate content in a 205 response. 7064 15.3.7. 206 Partial Content 7066 The _206 (Partial Content)_ status code indicates that the server is 7067 successfully fulfilling a range request for the target resource by 7068 transferring one or more parts of the selected representation. 7070 A server that supports range requests (Section 14) will usually 7071 attempt to satisfy all of the requested ranges, since sending less 7072 data will likely result in another client request for the remainder. 7073 However, a server might want to send only a subset of the data 7074 requested for reasons of its own, such as temporary unavailability, 7075 cache efficiency, load balancing, etc. Since a 206 response is self- 7076 descriptive, the client can still understand a response that only 7077 partially satisfies its range request. 7079 A client MUST inspect a 206 response's Content-Type and Content-Range 7080 field(s) to determine what parts are enclosed and whether additional 7081 requests are needed. 7083 A server that generates a 206 response MUST generate the following 7084 header fields, in addition to those required in the subsections 7085 below, if the field would have been sent in a 200 (OK) response to 7086 the same request: Date, Cache-Control, ETag, Expires, 7087 Content-Location, and Vary. 7089 A Content-Length header field present in a 206 response indicates the 7090 number of octets in the content of this message, which is usually not 7091 the complete length of the selected representation. Each 7092 Content-Range header field includes information about the selected 7093 representation's complete length. 7095 A sender that generates a 206 response to a request with an If-Range 7096 header field SHOULD NOT generate other representation header fields 7097 beyond those required, because the client already has a prior 7098 response containing those header fields. Otherwise, a sender MUST 7099 generate all of the representation header fields that would have been 7100 sent in a 200 (OK) response to the same request. 7102 A 206 response is heuristically cacheable; i.e., unless otherwise 7103 indicated by explicit cache controls (see Section 4.2.2 of 7104 [CACHING]). 7106 15.3.7.1. Single Part 7108 If a single part is being transferred, the server generating the 206 7109 response MUST generate a Content-Range header field, describing what 7110 range of the selected representation is enclosed, and a content 7111 consisting of the range. For example: 7113 HTTP/1.1 206 Partial Content 7114 Date: Wed, 15 Nov 1995 06:25:24 GMT 7115 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 7116 Content-Range: bytes 21010-47021/47022 7117 Content-Length: 26012 7118 Content-Type: image/gif 7120 ... 26012 bytes of partial image data ... 7122 15.3.7.2. Multiple Parts 7124 If multiple parts are being transferred, the server generating the 7125 206 response MUST generate "multipart/byteranges" content, as defined 7126 in Section 14.6, and a Content-Type header field containing the 7127 multipart/byteranges media type and its required boundary parameter. 7128 To avoid confusion with single-part responses, a server MUST NOT 7129 generate a Content-Range header field in the HTTP header section of a 7130 multiple part response (this field will be sent in each part 7131 instead). 7133 Within the header area of each body part in the multipart content, 7134 the server MUST generate a Content-Range header field corresponding 7135 to the range being enclosed in that body part. If the selected 7136 representation would have had a Content-Type header field in a 200 7137 (OK) response, the server SHOULD generate that same Content-Type 7138 header field in the header area of each body part. For example: 7140 HTTP/1.1 206 Partial Content 7141 Date: Wed, 15 Nov 1995 06:25:24 GMT 7142 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 7143 Content-Length: 1741 7144 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 7146 --THIS_STRING_SEPARATES 7147 Content-Type: application/pdf 7148 Content-Range: bytes 500-999/8000 7150 ...the first range... 7151 --THIS_STRING_SEPARATES 7152 Content-Type: application/pdf 7153 Content-Range: bytes 7000-7999/8000 7155 ...the second range 7156 --THIS_STRING_SEPARATES-- 7158 When multiple ranges are requested, a server MAY coalesce any of the 7159 ranges that overlap, or that are separated by a gap that is smaller 7160 than the overhead of sending multiple parts, regardless of the order 7161 in which the corresponding range-spec appeared in the received Range 7162 header field. Since the typical overhead between each part of a 7163 multipart/byteranges is around 80 bytes, depending on the selected 7164 representation's media type and the chosen boundary parameter length, 7165 it can be less efficient to transfer many small disjoint parts than 7166 it is to transfer the entire selected representation. 7168 A server MUST NOT generate a multipart response to a request for a 7169 single range, since a client that does not request multiple parts 7170 might not support multipart responses. However, a server MAY 7171 generate a multipart/byteranges response with only a single body part 7172 if multiple ranges were requested and only one range was found to be 7173 satisfiable or only one range remained after coalescing. A client 7174 that cannot process a multipart/byteranges response MUST NOT generate 7175 a request that asks for multiple ranges. 7177 A server that generates a multipart response SHOULD send the parts in 7178 the same order that the corresponding range-spec appeared in the 7179 received Range header field, excluding those ranges that were deemed 7180 unsatisfiable or that were coalesced into other ranges. A client 7181 that receives a multipart response MUST inspect the Content-Range 7182 header field present in each body part in order to determine which 7183 range is contained in that body part; a client cannot rely on 7184 receiving the same ranges that it requested, nor the same order that 7185 it requested. 7187 15.3.7.3. Combining Parts 7189 A response might transfer only a subrange of a representation if the 7190 connection closed prematurely or if the request used one or more 7191 Range specifications. After several such transfers, a client might 7192 have received several ranges of the same representation. These 7193 ranges can only be safely combined if they all have in common the 7194 same strong validator (Section 8.8.1). 7196 A client that has received multiple partial responses to GET requests 7197 on a target resource MAY combine those responses into a larger 7198 continuous range if they share the same strong validator. 7200 If the most recent response is an incomplete 200 (OK) response, then 7201 the header fields of that response are used for any combined response 7202 and replace those of the matching stored responses. 7204 If the most recent response is a 206 (Partial Content) response and 7205 at least one of the matching stored responses is a 200 (OK), then the 7206 combined response header fields consist of the most recent 200 7207 response's header fields. If all of the matching stored responses 7208 are 206 responses, then the stored response with the most recent 7209 header fields is used as the source of header fields for the combined 7210 response, except that the client MUST use other header fields 7211 provided in the new response, aside from Content-Range, to replace 7212 all instances of the corresponding header fields in the stored 7213 response. 7215 The combined response content consists of the union of partial 7216 content ranges within the new response and all of the matching stored 7217 responses. If the union consists of the entire range of the 7218 representation, then the client MUST process the combined response as 7219 if it were a complete 200 (OK) response, including a Content-Length 7220 header field that reflects the complete length. Otherwise, the 7221 client MUST process the set of continuous ranges as one of the 7222 following: an incomplete 200 (OK) response if the combined response 7223 is a prefix of the representation, a single 206 (Partial Content) 7224 response containing multipart/byteranges content, or multiple 206 7225 (Partial Content) responses, each with one continuous range that is 7226 indicated by a Content-Range header field. 7228 15.4. Redirection 3xx 7230 The _3xx (Redirection)_ class of status code indicates that further 7231 action needs to be taken by the user agent in order to fulfill the 7232 request. There are several types of redirects: 7234 1. Redirects that indicate this resource might be available at a 7235 different URI, as provided by the Location header field, as in 7236 the status codes 301 (Moved Permanently), 302 (Found), 307 7237 (Temporary Redirect), and 308 (Permanent Redirect). 7239 2. Redirection that offers a choice among matching resources capable 7240 of representing this resource, as in the 300 (Multiple Choices) 7241 status code. 7243 3. Redirection to a different resource, identified by the Location 7244 header field, that can represent an indirect response to the 7245 request, as in the 303 (See Other) status code. 7247 4. Redirection to a previously stored result, as in the 304 (Not 7248 Modified) status code. 7250 | *Note:* In HTTP/1.0, the status codes 301 (Moved Permanently) 7251 | and 302 (Found) were originally defined as method-preserving 7252 | ([HTTP/1.0], Section 9.3) to match their implementation at 7253 | CERN; 303 (See Other) was defined for a redirection that 7254 | changed its method to GET. However, early user agents split on 7255 | whether to redirect POST requests as POST (according to then- 7256 | current specification) or as GET (the safer alternative when 7257 | redirected to a different site). Prevailing practice 7258 | eventually converged on changing the method to GET. 307 7259 | (Temporary Redirect) and 308 (Permanent Redirect) [RFC7538] 7260 | were later added to unambiguously indicate method-preserving 7261 | redirects, and 301/302 have been adjusted to allow a POST 7262 | request to be redirected as GET. 7264 If a Location header field (Section 10.2.2) is provided, the user 7265 agent MAY automatically redirect its request to the URI referenced by 7266 the Location field value, even if the specific status code is not 7267 understood. Automatic redirection needs to be done with care for 7268 methods not known to be safe, as defined in Section 9.2.1, since the 7269 user might not wish to redirect an unsafe request. 7271 When automatically following a redirected request, the user agent 7272 SHOULD resend the original request message with the following 7273 modifications: 7275 1. Replace the target URI with the URI referenced by the redirection 7276 response's Location header field value after resolving it 7277 relative to the original request's target URI. 7279 2. Remove header fields that were automatically generated by the 7280 implementation, replacing them with updated values as appropriate 7281 to the new request. This includes: 7283 1. Connection-specific header fields (see Section 7.6.1), 7285 2. Header fields specific to the client's proxy configuration, 7286 including (but not limited to) Proxy-Authorization, 7288 3. Origin-specific header fields (if any), including (but not 7289 limited to) Host, 7291 4. Validating header fields that were added by the 7292 implementation's cache (e.g., If-None-Match, 7293 If-Modified-Since), 7295 5. Resource-specific header fields, including (but not limited 7296 to) Referer, Origin, Authorization, and Cookie. 7298 3. Consider removing header fields that were not automatically 7299 generated by the implementation (i.e., those present in the 7300 request because they were added by the calling context) where 7301 there are security implications; this includes but is not limited 7302 to Authorization and Cookie. 7304 4. Change the request method according to the redirecting status 7305 code's semantics, if applicable. 7307 5. If the request method has been changed to GET or HEAD, remove 7308 content-specific header fields, including (but not limited to) 7309 Content-Encoding, Content-Language, Content-Location, 7310 Content-Type, Content-Length, Digest, Last-Modified. 7312 A client SHOULD detect and intervene in cyclical redirections (i.e., 7313 "infinite" redirection loops). 7315 | *Note:* An earlier version of this specification recommended a 7316 | maximum of five redirections ([RFC2068], Section 10.3). 7317 | Content developers need to be aware that some clients might 7318 | implement such a fixed limitation. 7320 15.4.1. 300 Multiple Choices 7322 The _300 (Multiple Choices)_ status code indicates that the target 7323 resource has more than one representation, each with its own more 7324 specific identifier, and information about the alternatives is being 7325 provided so that the user (or user agent) can select a preferred 7326 representation by redirecting its request to one or more of those 7327 identifiers. In other words, the server desires that the user agent 7328 engage in reactive negotiation to select the most appropriate 7329 representation(s) for its needs (Section 12). 7331 If the server has a preferred choice, the server SHOULD generate a 7332 Location header field containing a preferred choice's URI reference. 7333 The user agent MAY use the Location field value for automatic 7334 redirection. 7336 For request methods other than HEAD, the server SHOULD generate 7337 content in the 300 response containing a list of representation 7338 metadata and URI reference(s) from which the user or user agent can 7339 choose the one most preferred. The user agent MAY make a selection 7340 from that list automatically if it understands the provided media 7341 type. A specific format for automatic selection is not defined by 7342 this specification because HTTP tries to remain orthogonal to the 7343 definition of its content. In practice, the representation is 7344 provided in some easily parsed format believed to be acceptable to 7345 the user agent, as determined by shared design or content 7346 negotiation, or in some commonly accepted hypertext format. 7348 A 300 response is heuristically cacheable; i.e., unless otherwise 7349 indicated by the method definition or explicit cache controls (see 7350 Section 4.2.2 of [CACHING]). 7352 | *Note:* The original proposal for the 300 status code defined 7353 | the URI header field as providing a list of alternative 7354 | representations, such that it would be usable for 200, 300, and 7355 | 406 responses and be transferred in responses to the HEAD 7356 | method. However, lack of deployment and disagreement over 7357 | syntax led to both URI and Alternates (a subsequent proposal) 7358 | being dropped from this specification. It is possible to 7359 | communicate the list as a Link header field value [RFC8288] 7360 | whose members have a relationship of "alternate", though 7361 | deployment is a chicken-and-egg problem. 7363 15.4.2. 301 Moved Permanently 7365 The _301 (Moved Permanently)_ status code indicates that the target 7366 resource has been assigned a new permanent URI and any future 7367 references to this resource ought to use one of the enclosed URIs. 7368 The server is suggesting that a user agent with link-editing 7369 capability can permanently replace references to the target URI with 7370 one of the new references sent by the server. However, this 7371 suggestion is usually ignored unless the user agent is actively 7372 editing references (e.g., engaged in authoring content), the 7373 connection is secured, and the origin server is a trusted authority 7374 for the content being edited. 7376 The server SHOULD generate a Location header field in the response 7377 containing a preferred URI reference for the new permanent URI. The 7378 user agent MAY use the Location field value for automatic 7379 redirection. The server's response content usually contains a short 7380 hypertext note with a hyperlink to the new URI(s). 7382 | *Note:* For historical reasons, a user agent MAY change the 7383 | request method from POST to GET for the subsequent request. If 7384 | this behavior is undesired, the 308 (Permanent Redirect) status 7385 | code can be used instead. 7387 A 301 response is heuristically cacheable; i.e., unless otherwise 7388 indicated by the method definition or explicit cache controls (see 7389 Section 4.2.2 of [CACHING]). 7391 15.4.3. 302 Found 7393 The _302 (Found)_ status code indicates that the target resource 7394 resides temporarily under a different URI. Since the redirection 7395 might be altered on occasion, the client ought to continue to use the 7396 target URI for future requests. 7398 The server SHOULD generate a Location header field in the response 7399 containing a URI reference for the different URI. The user agent MAY 7400 use the Location field value for automatic redirection. The server's 7401 response content usually contains a short hypertext note with a 7402 hyperlink to the different URI(s). 7404 | *Note:* For historical reasons, a user agent MAY change the 7405 | request method from POST to GET for the subsequent request. If 7406 | this behavior is undesired, the 307 (Temporary Redirect) status 7407 | code can be used instead. 7409 15.4.4. 303 See Other 7411 The _303 (See Other)_ status code indicates that the server is 7412 redirecting the user agent to a different resource, as indicated by a 7413 URI in the Location header field, which is intended to provide an 7414 indirect response to the original request. A user agent can perform 7415 a retrieval request targeting that URI (a GET or HEAD request if 7416 using HTTP), which might also be redirected, and present the eventual 7417 result as an answer to the original request. Note that the new URI 7418 in the Location header field is not considered equivalent to the 7419 target URI. 7421 This status code is applicable to any HTTP method. It is primarily 7422 used to allow the output of a POST action to redirect the user agent 7423 to a different resource, since doing so provides the information 7424 corresponding to the POST response as a resource that can be 7425 separately identified, bookmarked, and cached. 7427 A 303 response to a GET request indicates that the origin server does 7428 not have a representation of the target resource that can be 7429 transferred by the server over HTTP. However, the Location field 7430 value refers to a resource that is descriptive of the target 7431 resource, such that making a retrieval request on that other resource 7432 might result in a representation that is useful to recipients without 7433 implying that it represents the original target resource. Note that 7434 answers to the questions of what can be represented, what 7435 representations are adequate, and what might be a useful description 7436 are outside the scope of HTTP. 7438 Except for responses to a HEAD request, the representation of a 303 7439 response ought to contain a short hypertext note with a hyperlink to 7440 the same URI reference provided in the Location header field. 7442 15.4.5. 304 Not Modified 7444 The _304 (Not Modified)_ status code indicates that a conditional GET 7445 or HEAD request has been received and would have resulted in a 200 7446 (OK) response if it were not for the fact that the condition 7447 evaluated to false. In other words, there is no need for the server 7448 to transfer a representation of the target resource because the 7449 request indicates that the client, which made the request 7450 conditional, already has a valid representation; the server is 7451 therefore redirecting the client to make use of that stored 7452 representation as if it were the content of a 200 (OK) response. 7454 The server generating a 304 response MUST generate any of the 7455 following header fields that would have been sent in a 200 (OK) 7456 response to the same request: Cache-Control, Content-Location, Date, 7457 ETag, Expires, and Vary. 7459 Since the goal of a 304 response is to minimize information transfer 7460 when the recipient already has one or more cached representations, a 7461 sender SHOULD NOT generate representation metadata other than the 7462 above listed fields unless said metadata exists for the purpose of 7463 guiding cache updates (e.g., Last-Modified might be useful if the 7464 response does not have an ETag field). 7466 Requirements on a cache that receives a 304 response are defined in 7467 Section 4.3.4 of [CACHING]. If the conditional request originated 7468 with an outbound client, such as a user agent with its own cache 7469 sending a conditional GET to a shared proxy, then the proxy SHOULD 7470 forward the 304 response to that client. 7472 A 304 response is terminated by the end of the header section; it 7473 cannot contain content or trailers. 7475 15.4.6. 305 Use Proxy 7477 The _305 (Use Proxy)_ status code was defined in a previous version 7478 of this specification and is now deprecated (Appendix B of 7479 [RFC7231]). 7481 15.4.7. 306 (Unused) 7483 The 306 status code was defined in a previous version of this 7484 specification, is no longer used, and the code is reserved. 7486 15.4.8. 307 Temporary Redirect 7488 The _307 (Temporary Redirect)_ status code indicates that the target 7489 resource resides temporarily under a different URI and the user agent 7490 MUST NOT change the request method if it performs an automatic 7491 redirection to that URI. Since the redirection can change over time, 7492 the client ought to continue using the original target URI for future 7493 requests. 7495 The server SHOULD generate a Location header field in the response 7496 containing a URI reference for the different URI. The user agent MAY 7497 use the Location field value for automatic redirection. The server's 7498 response content usually contains a short hypertext note with a 7499 hyperlink to the different URI(s). 7501 15.4.9. 308 Permanent Redirect 7503 The _308 (Permanent Redirect)_ status code indicates that the target 7504 resource has been assigned a new permanent URI and any future 7505 references to this resource ought to use one of the enclosed URIs. 7506 The server is suggesting that a user agent with link-editing 7507 capability can permanently replace references to the target URI with 7508 one of the new references sent by the server. However, this 7509 suggestion is usually ignored unless the user agent is actively 7510 editing references (e.g., engaged in authoring content), the 7511 connection is secured, and the origin server is a trusted authority 7512 for the content being edited. 7514 The server SHOULD generate a Location header field in the response 7515 containing a preferred URI reference for the new permanent URI. The 7516 user agent MAY use the Location field value for automatic 7517 redirection. The server's response content usually contains a short 7518 hypertext note with a hyperlink to the new URI(s). 7520 A 308 response is heuristically cacheable; i.e., unless otherwise 7521 indicated by the method definition or explicit cache controls (see 7522 Section 4.2.2 of [CACHING]). 7524 | *Note:* This status code is much younger (June 2014) than its 7525 | sibling codes, and thus might not be recognized everywhere. 7526 | See Section 4 of [RFC7538] for deployment considerations. 7528 15.5. Client Error 4xx 7530 The _4xx (Client Error)_ class of status code indicates that the 7531 client seems to have erred. Except when responding to a HEAD 7532 request, the server SHOULD send a representation containing an 7533 explanation of the error situation, and whether it is a temporary or 7534 permanent condition. These status codes are applicable to any 7535 request method. User agents SHOULD display any included 7536 representation to the user. 7538 15.5.1. 400 Bad Request 7540 The _400 (Bad Request)_ status code indicates that the server cannot 7541 or will not process the request due to something that is perceived to 7542 be a client error (e.g., malformed request syntax, invalid request 7543 message framing, or deceptive request routing). 7545 15.5.2. 401 Unauthorized 7547 The _401 (Unauthorized)_ status code indicates that the request has 7548 not been applied because it lacks valid authentication credentials 7549 for the target resource. The server generating a 401 response MUST 7550 send a WWW-Authenticate header field (Section 11.6.1) containing at 7551 least one challenge applicable to the target resource. 7553 If the request included authentication credentials, then the 401 7554 response indicates that authorization has been refused for those 7555 credentials. The user agent MAY repeat the request with a new or 7556 replaced Authorization header field (Section 11.6.2). If the 401 7557 response contains the same challenge as the prior response, and the 7558 user agent has already attempted authentication at least once, then 7559 the user agent SHOULD present the enclosed representation to the 7560 user, since it usually contains relevant diagnostic information. 7562 15.5.3. 402 Payment Required 7564 The _402 (Payment Required)_ status code is reserved for future use. 7566 15.5.4. 403 Forbidden 7568 The _403 (Forbidden)_ status code indicates that the server 7569 understood the request but refuses to fulfill it. A server that 7570 wishes to make public why the request has been forbidden can describe 7571 that reason in the response content (if any). 7573 If authentication credentials were provided in the request, the 7574 server considers them insufficient to grant access. The client 7575 SHOULD NOT automatically repeat the request with the same 7576 credentials. The client MAY repeat the request with new or different 7577 credentials. However, a request might be forbidden for reasons 7578 unrelated to the credentials. 7580 An origin server that wishes to "hide" the current existence of a 7581 forbidden target resource MAY instead respond with a status code of 7582 404 (Not Found). 7584 15.5.5. 404 Not Found 7586 The _404 (Not Found)_ status code indicates that the origin server 7587 did not find a current representation for the target resource or is 7588 not willing to disclose that one exists. A 404 status code does not 7589 indicate whether this lack of representation is temporary or 7590 permanent; the 410 (Gone) status code is preferred over 404 if the 7591 origin server knows, presumably through some configurable means, that 7592 the condition is likely to be permanent. 7594 A 404 response is heuristically cacheable; i.e., unless otherwise 7595 indicated by the method definition or explicit cache controls (see 7596 Section 4.2.2 of [CACHING]). 7598 15.5.6. 405 Method Not Allowed 7600 The _405 (Method Not Allowed)_ status code indicates that the method 7601 received in the request-line is known by the origin server but not 7602 supported by the target resource. The origin server MUST generate an 7603 Allow header field in a 405 response containing a list of the target 7604 resource's currently supported methods. 7606 A 405 response is heuristically cacheable; i.e., unless otherwise 7607 indicated by the method definition or explicit cache controls (see 7608 Section 4.2.2 of [CACHING]). 7610 15.5.7. 406 Not Acceptable 7612 The _406 (Not Acceptable)_ status code indicates that the target 7613 resource does not have a current representation that would be 7614 acceptable to the user agent, according to the proactive negotiation 7615 header fields received in the request (Section 12.1), and the server 7616 is unwilling to supply a default representation. 7618 The server SHOULD generate content containing a list of available 7619 representation characteristics and corresponding resource identifiers 7620 from which the user or user agent can choose the one most 7621 appropriate. A user agent MAY automatically select the most 7622 appropriate choice from that list. However, this specification does 7623 not define any standard for such automatic selection, as described in 7624 Section 15.4.1. 7626 15.5.8. 407 Proxy Authentication Required 7628 The _407 (Proxy Authentication Required)_ status code is similar to 7629 401 (Unauthorized), but it indicates that the client needs to 7630 authenticate itself in order to use a proxy for this request. The 7631 proxy MUST send a Proxy-Authenticate header field (Section 11.7.1) 7632 containing a challenge applicable to that proxy for the request. The 7633 client MAY repeat the request with a new or replaced 7634 Proxy-Authorization header field (Section 11.7.2). 7636 15.5.9. 408 Request Timeout 7638 The _408 (Request Timeout)_ status code indicates that the server did 7639 not receive a complete request message within the time that it was 7640 prepared to wait. 7642 If the client has an outstanding request in transit, it MAY repeat 7643 that request. If the current connection is not usable (e.g., as it 7644 would be in HTTP/1.1, because request delimitation is lost), a new 7645 connection will be used. 7647 15.5.10. 409 Conflict 7649 The _409 (Conflict)_ status code indicates that the request could not 7650 be completed due to a conflict with the current state of the target 7651 resource. This code is used in situations where the user might be 7652 able to resolve the conflict and resubmit the request. The server 7653 SHOULD generate content that includes enough information for a user 7654 to recognize the source of the conflict. 7656 Conflicts are most likely to occur in response to a PUT request. For 7657 example, if versioning were being used and the representation being 7658 PUT included changes to a resource that conflict with those made by 7659 an earlier (third-party) request, the origin server might use a 409 7660 response to indicate that it can't complete the request. In this 7661 case, the response representation would likely contain information 7662 useful for merging the differences based on the revision history. 7664 15.5.11. 410 Gone 7666 The _410 (Gone)_ status code indicates that access to the target 7667 resource is no longer available at the origin server and that this 7668 condition is likely to be permanent. If the origin server does not 7669 know, or has no facility to determine, whether or not the condition 7670 is permanent, the status code 404 (Not Found) ought to be used 7671 instead. 7673 The 410 response is primarily intended to assist the task of web 7674 maintenance by notifying the recipient that the resource is 7675 intentionally unavailable and that the server owners desire that 7676 remote links to that resource be removed. Such an event is common 7677 for limited-time, promotional services and for resources belonging to 7678 individuals no longer associated with the origin server's site. It 7679 is not necessary to mark all permanently unavailable resources as 7680 "gone" or to keep the mark for any length of time - that is left to 7681 the discretion of the server owner. 7683 A 410 response is heuristically cacheable; i.e., unless otherwise 7684 indicated by the method definition or explicit cache controls (see 7685 Section 4.2.2 of [CACHING]). 7687 15.5.12. 411 Length Required 7689 The _411 (Length Required)_ status code indicates that the server 7690 refuses to accept the request without a defined Content-Length 7691 (Section 8.6). The client MAY repeat the request if it adds a valid 7692 Content-Length header field containing the length of the request 7693 content. 7695 15.5.13. 412 Precondition Failed 7697 The _412 (Precondition Failed)_ status code indicates that one or 7698 more conditions given in the request header fields evaluated to false 7699 when tested on the server (Section 13). This response status code 7700 allows the client to place preconditions on the current resource 7701 state (its current representations and metadata) and, thus, prevent 7702 the request method from being applied if the target resource is in an 7703 unexpected state. 7705 15.5.14. 413 Content Too Large 7707 The _413 (Content Too Large)_ status code indicates that the server 7708 is refusing to process a request because the request content is 7709 larger than the server is willing or able to process. The server MAY 7710 terminate the request, if the protocol version in use allows it; 7711 otherwise, the server MAY close the connection. 7713 If the condition is temporary, the server SHOULD generate a 7714 Retry-After header field to indicate that it is temporary and after 7715 what time the client MAY try again. 7717 15.5.15. 414 URI Too Long 7719 The _414 (URI Too Long)_ status code indicates that the server is 7720 refusing to service the request because the target URI is longer than 7721 the server is willing to interpret. This rare condition is only 7722 likely to occur when a client has improperly converted a POST request 7723 to a GET request with long query information, when the client has 7724 descended into a "black hole" of redirection (e.g., a redirected URI 7725 prefix that points to a suffix of itself) or when the server is under 7726 attack by a client attempting to exploit potential security holes. 7728 A 414 response is heuristically cacheable; i.e., unless otherwise 7729 indicated by the method definition or explicit cache controls (see 7730 Section 4.2.2 of [CACHING]). 7732 15.5.16. 415 Unsupported Media Type 7734 The _415 (Unsupported Media Type)_ status code indicates that the 7735 origin server is refusing to service the request because the content 7736 is in a format not supported by this method on the target resource. 7738 The format problem might be due to the request's indicated 7739 Content-Type or Content-Encoding, or as a result of inspecting the 7740 data directly. 7742 If the problem was caused by an unsupported content coding, the 7743 Accept-Encoding response header field (Section 12.5.3) ought to be 7744 used to indicate what (if any) content codings would have been 7745 accepted in the request. 7747 On the other hand, if the cause was an unsupported media type, the 7748 Accept response header field (Section 12.5.1) can be used to indicate 7749 what media types would have been accepted in the request. 7751 15.5.17. 416 Range Not Satisfiable 7753 The _416 (Range Not Satisfiable)_ status code indicates that the set 7754 of ranges in the request's Range header field (Section 14.2) has been 7755 rejected either because none of the requested ranges are satisfiable 7756 or because the client has requested an excessive number of small or 7757 overlapping ranges (a potential denial of service attack). 7759 Each range unit defines what is required for its own range sets to be 7760 satisfiable. For example, Section 14.1.2 defines what makes a bytes 7761 range set satisfiable. 7763 A server that generates a 416 response to a byte-range request SHOULD 7764 generate a Content-Range header field specifying the current length 7765 of the selected representation (Section 14.4). 7767 For example: 7769 HTTP/1.1 416 Range Not Satisfiable 7770 Date: Fri, 20 Jan 2012 15:41:54 GMT 7771 Content-Range: bytes */47022 7773 | *Note:* Because servers are free to ignore Range, many 7774 | implementations will respond with the entire selected 7775 | representation in a 200 (OK) response. That is partly because 7776 | most clients are prepared to receive a 200 (OK) to complete the 7777 | task (albeit less efficiently) and partly because clients might 7778 | not stop making an invalid range request until they have 7779 | received a complete representation. Thus, clients cannot 7780 | depend on receiving a 416 (Range Not Satisfiable) response even 7781 | when it is most appropriate. 7783 15.5.18. 417 Expectation Failed 7785 The _417 (Expectation Failed)_ status code indicates that the 7786 expectation given in the request's Expect header field 7787 (Section 10.1.1) could not be met by at least one of the inbound 7788 servers. 7790 15.5.19. 418 (Unused) 7792 [RFC2324] was an April 1 RFC that lampooned the various ways HTTP was 7793 abused; one such abuse was the definition of an application-specific 7794 418 status code. In the intervening years, this status code has been 7795 widely implemented as an "Easter Egg", and therefore is effectively 7796 consumed by this use. 7798 Therefore, the 418 status code is reserved in the IANA HTTP Status 7799 Code Registry. This indicates that the status code cannot be 7800 assigned to other applications currently. If future circumstances 7801 require its use (e.g., exhaustion of 4NN status codes), it can be re- 7802 assigned to another use. 7804 15.5.20. 421 Misdirected Request 7806 The 421 (Misdirected Request) status code indicates that the request 7807 was directed at a server that is unable or unwilling to produce an 7808 authoritative response for the target URI. An origin server (or 7809 gateway acting on behalf of the origin server) sends 421 to reject a 7810 target URI that does not match an origin for which the server has 7811 been configured (Section 4.3.1) or does not match the connection 7812 context over which the request was received (Section 7.4). 7814 A client that receives a 421 (Misdirected Request) response MAY retry 7815 the request, whether or not the request method is idempotent, over a 7816 different connection, such as a fresh connection specific to the 7817 target resource's origin, or via an alternative service [ALTSVC]. 7819 A proxy MUST NOT generate a 421 response. 7821 15.5.21. 422 Unprocessable Content 7823 The 422 (Unprocessable Content) status code indicates that the server 7824 understands the content type of the request content (hence a 415 7825 (Unsupported Media Type) status code is inappropriate), and the 7826 syntax of the request content is correct, but was unable to process 7827 the contained instructions. For example, this status code can be 7828 sent if an XML request content contains well-formed (i.e., 7829 syntactically correct), but semantically erroneous XML instructions. 7831 15.5.22. 426 Upgrade Required 7833 The _426 (Upgrade Required)_ status code indicates that the server 7834 refuses to perform the request using the current protocol but might 7835 be willing to do so after the client upgrades to a different 7836 protocol. The server MUST send an Upgrade header field in a 426 7837 response to indicate the required protocol(s) (Section 7.8). 7839 Example: 7841 HTTP/1.1 426 Upgrade Required 7842 Upgrade: HTTP/3.0 7843 Connection: Upgrade 7844 Content-Length: 53 7845 Content-Type: text/plain 7847 This service requires use of the HTTP/3.0 protocol. 7849 15.6. Server Error 5xx 7851 The _5xx (Server Error)_ class of status code indicates that the 7852 server is aware that it has erred or is incapable of performing the 7853 requested method. Except when responding to a HEAD request, the 7854 server SHOULD send a representation containing an explanation of the 7855 error situation, and whether it is a temporary or permanent 7856 condition. A user agent SHOULD display any included representation 7857 to the user. These response codes are applicable to any request 7858 method. 7860 15.6.1. 500 Internal Server Error 7862 The _500 (Internal Server Error)_ status code indicates that the 7863 server encountered an unexpected condition that prevented it from 7864 fulfilling the request. 7866 15.6.2. 501 Not Implemented 7868 The _501 (Not Implemented)_ status code indicates that the server 7869 does not support the functionality required to fulfill the request. 7870 This is the appropriate response when the server does not recognize 7871 the request method and is not capable of supporting it for any 7872 resource. 7874 A 501 response is heuristically cacheable; i.e., unless otherwise 7875 indicated by the method definition or explicit cache controls (see 7876 Section 4.2.2 of [CACHING]). 7878 15.6.3. 502 Bad Gateway 7880 The _502 (Bad Gateway)_ status code indicates that the server, while 7881 acting as a gateway or proxy, received an invalid response from an 7882 inbound server it accessed while attempting to fulfill the request. 7884 15.6.4. 503 Service Unavailable 7886 The _503 (Service Unavailable)_ status code indicates that the server 7887 is currently unable to handle the request due to a temporary overload 7888 or scheduled maintenance, which will likely be alleviated after some 7889 delay. The server MAY send a Retry-After header field 7890 (Section 10.2.3) to suggest an appropriate amount of time for the 7891 client to wait before retrying the request. 7893 | *Note:* The existence of the 503 status code does not imply 7894 | that a server has to use it when becoming overloaded. Some 7895 | servers might simply refuse the connection. 7897 15.6.5. 504 Gateway Timeout 7899 The _504 (Gateway Timeout)_ status code indicates that the server, 7900 while acting as a gateway or proxy, did not receive a timely response 7901 from an upstream server it needed to access in order to complete the 7902 request. 7904 15.6.6. 505 HTTP Version Not Supported 7906 The _505 (HTTP Version Not Supported)_ status code indicates that the 7907 server does not support, or refuses to support, the major version of 7908 HTTP that was used in the request message. The server is indicating 7909 that it is unable or unwilling to complete the request using the same 7910 major version as the client, as described in Section 2.5, other than 7911 with this error message. The server SHOULD generate a representation 7912 for the 505 response that describes why that version is not supported 7913 and what other protocols are supported by that server. 7915 16. Extending HTTP 7917 HTTP defines a number of generic extension points that can be used to 7918 introduce capabilities to the protocol without introducing a new 7919 version, including methods, status codes, field names, and further 7920 extensibility points within defined fields, such as authentication 7921 schemes and cache-directives (see Cache-Control extensions in 7922 Section 5.2.3 of [CACHING]). Because the semantics of HTTP are not 7923 versioned, these extension points are persistent; the version of the 7924 protocol in use does not affect their semantics. 7926 Version-independent extensions are discouraged from depending on or 7927 interacting with the specific version of the protocol in use. When 7928 this is unavoidable, careful consideration needs to be given to how 7929 the extension can interoperate across versions. 7931 Additionally, specific versions of HTTP might have their own 7932 extensibility points, such as transfer-codings in HTTP/1.1 7933 (Section 6.1 of [HTTP/1.1]) and HTTP/2 ([HTTP/2]) SETTINGS or frame 7934 types. These extension points are specific to the version of the 7935 protocol they occur within. 7937 Version-specific extensions cannot override or modify the semantics 7938 of a version-independent mechanism or extension point (like a method 7939 or header field) without explicitly being allowed by that protocol 7940 element. For example, the CONNECT method (Section 9.3.6) allows 7941 this. 7943 These guidelines assure that the protocol operates correctly and 7944 predictably, even when parts of the path implement different versions 7945 of HTTP. 7947 16.1. Method Extensibility 7949 16.1.1. Method Registry 7951 The "Hypertext Transfer Protocol (HTTP) Method Registry", maintained 7952 by IANA at , registers 7953 method names. 7955 HTTP method registrations MUST include the following fields: 7957 * Method Name (see Section 9) 7959 * Safe ("yes" or "no", see Section 9.2.1) 7961 * Idempotent ("yes" or "no", see Section 9.2.2) 7963 * Pointer to specification text 7965 Values to be added to this namespace require IETF Review (see 7966 [RFC8126], Section 4.8). 7968 16.1.2. Considerations for New Methods 7970 Standardized methods are generic; that is, they are potentially 7971 applicable to any resource, not just one particular media type, kind 7972 of resource, or application. As such, it is preferred that new 7973 methods be registered in a document that isn't specific to a single 7974 application or data format, since orthogonal technologies deserve 7975 orthogonal specification. 7977 Since message parsing (Section 6) needs to be independent of method 7978 semantics (aside from responses to HEAD), definitions of new methods 7979 cannot change the parsing algorithm or prohibit the presence of 7980 content on either the request or the response message. Definitions 7981 of new methods can specify that only a zero-length content is allowed 7982 by requiring a Content-Length header field with a value of "0". 7984 Likewise, new methods cannot use the special host:port and asterisk 7985 forms of request target that are allowed for CONNECT and OPTIONS, 7986 respectively (Section 7.1). A full URI in absolute form is needed 7987 for the target URI, which means either the request target needs to be 7988 sent in absolute form or the target URI will be reconstructed from 7989 the request context in the same way it is for other methods. 7991 A new method definition needs to indicate whether it is safe 7992 (Section 9.2.1), idempotent (Section 9.2.2), cacheable 7993 (Section 9.2.3), what semantics are to be associated with the request 7994 content (if any), and what refinements the method makes to header 7995 field or status code semantics. If the new method is cacheable, its 7996 definition ought to describe how, and under what conditions, a cache 7997 can store a response and use it to satisfy a subsequent request. The 7998 new method ought to describe whether it can be made conditional 7999 (Section 13.1) and, if so, how a server responds when the condition 8000 is false. Likewise, if the new method might have some use for 8001 partial response semantics (Section 14.2), it ought to document this, 8002 too. 8004 | *Note:* Avoid defining a method name that starts with "M-", 8005 | since that prefix might be misinterpreted as having the 8006 | semantics assigned to it by [RFC2774]. 8008 16.2. Status Code Extensibility 8010 16.2.1. Status Code Registry 8012 The "Hypertext Transfer Protocol (HTTP) Status Code Registry", 8013 maintained by IANA at , registers status code numbers. 8016 A registration MUST include the following fields: 8018 * Status Code (3 digits) 8020 * Short Description 8022 * Pointer to specification text 8023 Values to be added to the HTTP status code namespace require IETF 8024 Review (see [RFC8126], Section 4.8). 8026 16.2.2. Considerations for New Status Codes 8028 When it is necessary to express semantics for a response that are not 8029 defined by current status codes, a new status code can be registered. 8030 Status codes are generic; they are potentially applicable to any 8031 resource, not just one particular media type, kind of resource, or 8032 application of HTTP. As such, it is preferred that new status codes 8033 be registered in a document that isn't specific to a single 8034 application. 8036 New status codes are required to fall under one of the categories 8037 defined in Section 15. To allow existing parsers to process the 8038 response message, new status codes cannot disallow content, although 8039 they can mandate a zero-length content. 8041 Proposals for new status codes that are not yet widely deployed ought 8042 to avoid allocating a specific number for the code until there is 8043 clear consensus that it will be registered; instead, early drafts can 8044 use a notation such as "4NN", or "3N0" .. "3N9", to indicate the 8045 class of the proposed status code(s) without consuming a number 8046 prematurely. 8048 The definition of a new status code ought to explain the request 8049 conditions that would cause a response containing that status code 8050 (e.g., combinations of request header fields and/or method(s)) along 8051 with any dependencies on response header fields (e.g., what fields 8052 are required, what fields can modify the semantics, and what field 8053 semantics are further refined when used with the new status code). 8055 By default, a status code applies only to the request corresponding 8056 to the response it occurs within. If a status code applies to a 8057 larger scope of applicability - for example, all requests to the 8058 resource in question, or all requests to a server - this must be 8059 explicitly specified. When doing so, it should be noted that not all 8060 clients can be expected to consistently apply a larger scope, because 8061 they might not understand the new status code. 8063 The definition of a new final status code ought to specify whether or 8064 not it is heuristically cacheable. Note that all final status codes 8065 can be cached if the response they occur in has explicit freshness 8066 information; however, those status codes that are defined as being 8067 heuristically cacheable are allowed to be cached without explicit 8068 freshness information. Likewise, the definition of a status code can 8069 place constraints upon cache behavior, if the 'must-understand' cache 8070 directive is used. See [CACHING] for more information. 8072 Finally, the definition of a new status code ought to indicate 8073 whether the content has any implied association with an identified 8074 resource (Section 6.4.2). 8076 16.3. Field Extensibility 8078 HTTP's most widely used extensibility point is the definition of new 8079 header and trailer fields. 8081 New fields can be defined such that, when they are understood by a 8082 recipient, they override or enhance the interpretation of previously 8083 defined fields, define preconditions on request evaluation, or refine 8084 the meaning of responses. 8086 However, defining a field doesn't guarantee its deployment or 8087 recognition by recipients. Most fields are designed with the 8088 expectation that a recipient can safely ignore (but forward 8089 downstream) any field not recognized. In other cases, the sender's 8090 ability to understand a given field might be indicated by its prior 8091 communication, perhaps in the protocol version or fields that it sent 8092 in prior messages, or its use of a specific media type. Likewise, 8093 direct inspection of support might be possible through an OPTIONS 8094 request or by interacting with a defined well-known URI [RFC8615] if 8095 such inspection is defined along with the field being introduced. 8097 16.3.1. Field Name Registry 8099 The "Hypertext Transfer Protocol (HTTP) Field Name Registry" defines 8100 the namespace for HTTP field names. 8102 Any party can request registration of an HTTP field. See 8103 Section 16.3.2 for considerations to take into account when creating 8104 a new HTTP field. 8106 The "Hypertext Transfer Protocol (HTTP) Field Name Registry" is 8107 located at . 8108 Registration requests can be made by following the instructions 8109 located there or by sending an email to the "ietf-http-wg@w3.org" 8110 mailing list. 8112 Field names are registered on the advice of a Designated Expert 8113 (appointed by the IESG or their delegate). Fields with the status 8114 'permanent' are Specification Required ([RFC8126], Section 4.6). 8116 Registration requests consist of the following information: 8118 Field name: 8119 The requested field name. It MUST conform to the field-name 8120 syntax defined in Section 5.1, and SHOULD be restricted to just 8121 letters, digits, and hyphen ('-') characters, with the first 8122 character being a letter. 8124 Status: 8125 "permanent" or "provisional". 8127 Specification document(s): 8128 Reference to the document that specifies the field, preferably 8129 including a URI that can be used to retrieve a copy of the 8130 document. Optional but encouraged for provisional registrations. 8131 An indication of the relevant section(s) can also be included, but 8132 is not required. 8134 And, optionally: 8136 Comments: Additional information, such as about reserved entries. 8138 The Expert(s) can define additional fields to be collected in the 8139 registry, in consultation with the community. 8141 Standards-defined names have a status of "permanent". Other names 8142 can also be registered as permanent, if the Expert(s) find that they 8143 are in use, in consultation with the community. Other names should 8144 be registered as "provisional". 8146 Provisional entries can be removed by the Expert(s) if - in 8147 consultation with the community - the Expert(s) find that they are 8148 not in use. The Experts can change a provisional entry's status to 8149 permanent at any time. 8151 Note that names can be registered by third parties (including the 8152 Expert(s)), if the Expert(s) determines that an unregistered name is 8153 widely deployed and not likely to be registered in a timely manner 8154 otherwise. 8156 16.3.2. Considerations for New Fields 8158 HTTP header and trailer fields are a widely-used extension point for 8159 the protocol. While they can be used in an ad hoc fashion, fields 8160 that are intended for wider use need to be carefully documented to 8161 ensure interoperability. 8163 In particular, authors of specifications defining new fields are 8164 advised to consider and, where appropriate, document the following 8165 aspects: 8167 * Under what conditions the field can be used; e.g., only in 8168 responses or requests, in all messages, only on responses to a 8169 particular request method, etc. 8171 * Whether the field semantics are further refined by their context, 8172 such as their use with certain request methods or status codes. 8174 * The scope of applicability for the information conveyed. By 8175 default, fields apply only to the message they are associated 8176 with, but some response fields are designed to apply to all 8177 representations of a resource, the resource itself, or an even 8178 broader scope. Specifications that expand the scope of a response 8179 field will need to carefully consider issues such as content 8180 negotiation, the time period of applicability, and (in some cases) 8181 multi-tenant server deployments. 8183 * Under what conditions intermediaries are allowed to insert, 8184 delete, or modify the field's value. 8186 * If the field is allowable in trailers; by default, it will not be 8187 (see Section 6.5.1). 8189 * Whether it is appropriate or even required to list the field name 8190 in the Connection header field (i.e., if the field is to be hop- 8191 by-hop; see Section 7.6.1). 8193 * Whether the field introduces any additional security 8194 considerations, such as disclosure of privacy-related data. 8196 Request header fields have additional considerations that need to be 8197 documented if the default behaviour is not appropriate: 8199 * If it is appropriate to list the field name in a Vary response 8200 header field (e.g., when the request header field is used by an 8201 origin server's content selection algorithm; see Section 12.5.5). 8203 * If the field is intended to be stored when received in a PUT 8204 request (see Section 9.3.4). 8206 * If the field ought to be removed when automatically redirecting a 8207 request, due to security concerns (see Section 15.4). 8209 16.3.2.1. Considerations for New Field Names 8211 Authors of specifications defining new fields are advised to choose a 8212 short but descriptive field name. Short names avoid needless data 8213 transmission; descriptive names avoid confusion and "squatting" on 8214 names that might have broader uses. 8216 To that end, limited-use fields (such as a header confined to a 8217 single application or use case) are encouraged to use a name that 8218 includes that use (or an abbreviation) as a prefix; for example, if 8219 the Foo Application needs a Description field, it might use "Foo- 8220 Desc"; "Description" is too generic, and "Foo-Description" is 8221 needlessly long. 8223 While the field-name syntax is defined to allow any token character, 8224 in practice some implementations place limits on the characters they 8225 accept in field-names. To be interoperable, new field names SHOULD 8226 constrain themselves to alphanumeric characters, "-", and ".", and 8227 SHOULD begin with a letter. For example, the underscore ("_") 8228 character can be problematic when passed through non-HTTP gateway 8229 interfaces (see Section 17.10). 8231 Field names ought not be prefixed with "X-"; see [BCP178] for further 8232 information. 8234 Other prefixes are sometimes used in HTTP field names; for example, 8235 "Accept-" is used in many content negotiation headers, and "Content-" 8236 is used as explained in Section 6.4. These prefixes are only an aid 8237 to recognizing the purpose of a field, and do not trigger automatic 8238 processing. 8240 16.3.2.2. Considerations for New Field Values 8242 A major task in the definition of a new HTTP field is the 8243 specification of the field value syntax: what senders should 8244 generate, and how recipients should infer semantics from what is 8245 received. 8247 Authors are encouraged (but not required) to use either the ABNF 8248 rules in this specification or those in [RFC8941] to define the 8249 syntax of new field values. 8251 Authors are advised to carefully consider how the combination of 8252 multiple field lines will impact them (see Section 5.3). Because 8253 senders might erroneously send multiple values, and both 8254 intermediaries and HTTP libraries can perform combination 8255 automatically, this applies to all field values - even when only a 8256 single value is anticipated. 8258 Therefore, authors are advised to delimit or encode values that 8259 contain commas (e.g., with the quoted-string rule of Section 5.6.4, 8260 the String data type of [RFC8941], or a field-specific encoding). 8261 This ensures that commas within field data are not confused with the 8262 commas that delimit a list value. 8264 For example, the Content-Type field value only allows commas inside 8265 quoted strings, which can be reliably parsed even when multiple 8266 values are present. The Location field value provides a counter- 8267 example that should not be emulated: because URIs can include commas, 8268 it is not possible to reliably distinguish between a single value 8269 that includes a comma from two values. 8271 Authors of fields with a singleton value (see Section 5.5) are 8272 additionally advised to document how to treat messages where the 8273 multiple members are present (a sensible default would be to ignore 8274 the field, but this might not always be the right choice). 8276 16.4. Authentication Scheme Extensibility 8278 16.4.1. Authentication Scheme Registry 8280 The "Hypertext Transfer Protocol (HTTP) Authentication Scheme 8281 Registry" defines the namespace for the authentication schemes in 8282 challenges and credentials. It is maintained at 8283 . 8285 Registrations MUST include the following fields: 8287 * Authentication Scheme Name 8289 * Pointer to specification text 8291 * Notes (optional) 8293 Values to be added to this namespace require IETF Review (see 8294 [RFC8126], Section 4.8). 8296 16.4.2. Considerations for New Authentication Schemes 8298 There are certain aspects of the HTTP Authentication framework that 8299 put constraints on how new authentication schemes can work: 8301 * HTTP authentication is presumed to be stateless: all of the 8302 information necessary to authenticate a request MUST be provided 8303 in the request, rather than be dependent on the server remembering 8304 prior requests. Authentication based on, or bound to, the 8305 underlying connection is outside the scope of this specification 8306 and inherently flawed unless steps are taken to ensure that the 8307 connection cannot be used by any party other than the 8308 authenticated user (see Section 3.3). 8310 * The authentication parameter "realm" is reserved for defining 8311 protection spaces as described in Section 11.5. New schemes MUST 8312 NOT use it in a way incompatible with that definition. 8314 * The "token68" notation was introduced for compatibility with 8315 existing authentication schemes and can only be used once per 8316 challenge or credential. Thus, new schemes ought to use the auth- 8317 param syntax instead, because otherwise future extensions will be 8318 impossible. 8320 * The parsing of challenges and credentials is defined by this 8321 specification and cannot be modified by new authentication 8322 schemes. When the auth-param syntax is used, all parameters ought 8323 to support both token and quoted-string syntax, and syntactical 8324 constraints ought to be defined on the field value after parsing 8325 (i.e., quoted-string processing). This is necessary so that 8326 recipients can use a generic parser that applies to all 8327 authentication schemes. 8329 *Note:* The fact that the value syntax for the "realm" parameter 8330 is restricted to quoted-string was a bad design choice not to be 8331 repeated for new parameters. 8333 * Definitions of new schemes ought to define the treatment of 8334 unknown extension parameters. In general, a "must-ignore" rule is 8335 preferable to a "must-understand" rule, because otherwise it will 8336 be hard to introduce new parameters in the presence of legacy 8337 recipients. Furthermore, it's good to describe the policy for 8338 defining new parameters (such as "update the specification" or 8339 "use this registry"). 8341 * Authentication schemes need to document whether they are usable in 8342 origin-server authentication (i.e., using WWW-Authenticate), and/ 8343 or proxy authentication (i.e., using Proxy-Authenticate). 8345 * The credentials carried in an Authorization header field are 8346 specific to the user agent and, therefore, have the same effect on 8347 HTTP caches as the "private" Cache-Control response directive 8348 (Section 5.2.2.7 of [CACHING]), within the scope of the request in 8349 which they appear. 8351 Therefore, new authentication schemes that choose not to carry 8352 credentials in the Authorization header field (e.g., using a newly 8353 defined header field) will need to explicitly disallow caching, by 8354 mandating the use of Cache-Control response directives (e.g., 8355 "private"). 8357 * Schemes using Authentication-Info, Proxy-Authentication-Info, or 8358 any other authentication related response header field need to 8359 consider and document the related security considerations (see 8360 Section 17.16.4). 8362 16.5. Range Unit Extensibility 8364 16.5.1. Range Unit Registry 8366 The "HTTP Range Unit Registry" defines the namespace for the range 8367 unit names and refers to their corresponding specifications. It is 8368 maintained at . 8370 Registration of an HTTP Range Unit MUST include the following fields: 8372 * Name 8374 * Description 8376 * Pointer to specification text 8378 Values to be added to this namespace require IETF Review (see 8379 [RFC8126], Section 4.8). 8381 16.5.2. Considerations for New Range Units 8383 Other range units, such as format-specific boundaries like pages, 8384 sections, records, rows, or time, are potentially usable in HTTP for 8385 application-specific purposes, but are not commonly used in practice. 8386 Implementors of alternative range units ought to consider how they 8387 would work with content codings and general-purpose intermediaries. 8389 16.6. Content Coding Extensibility 8391 16.6.1. Content Coding Registry 8393 The "HTTP Content Coding Registry", maintained by IANA at 8394 , registers 8395 content-coding names. 8397 Content coding registrations MUST include the following fields: 8399 * Name 8401 * Description 8403 * Pointer to specification text 8404 Names of content codings MUST NOT overlap with names of transfer 8405 codings (as per the "HTTP Transfer Coding registry", located at 8406 ), unless the 8407 encoding transformation is identical (as is the case for the 8408 compression codings defined in Section 8.4.1). 8410 Values to be added to this namespace require IETF Review (see 8411 Section 4.8 of [RFC8126]) and MUST conform to the purpose of content 8412 coding defined in Section 8.4.1. 8414 16.6.2. Considerations for New Content Codings 8416 New content codings ought to be self-descriptive whenever possible, 8417 with optional parameters discoverable within the coding format 8418 itself, rather than rely on external metadata that might be lost 8419 during transit. 8421 16.7. Upgrade Token Registry 8423 The "Hypertext Transfer Protocol (HTTP) Upgrade Token Registry" 8424 defines the namespace for protocol-name tokens used to identify 8425 protocols in the Upgrade header field. The registry is maintained at 8426 . 8428 Each registered protocol name is associated with contact information 8429 and an optional set of specifications that details how the connection 8430 will be processed after it has been upgraded. 8432 Registrations happen on a "First Come First Served" basis (see 8433 Section 4.4 of [RFC8126]) and are subject to the following rules: 8435 1. A protocol-name token, once registered, stays registered forever. 8437 2. A protocol-name token is case-insensitive and registered with the 8438 preferred case to be generated by senders. 8440 3. The registration MUST name a responsible party for the 8441 registration. 8443 4. The registration MUST name a point of contact. 8445 5. The registration MAY name a set of specifications associated with 8446 that token. Such specifications need not be publicly available. 8448 6. The registration SHOULD name a set of expected "protocol-version" 8449 tokens associated with that token at the time of registration. 8451 7. The responsible party MAY change the registration at any time. 8452 The IANA will keep a record of all such changes, and make them 8453 available upon request. 8455 8. The IESG MAY reassign responsibility for a protocol token. This 8456 will normally only be used in the case when a responsible party 8457 cannot be contacted. 8459 17. Security Considerations 8461 This section is meant to inform developers, information providers, 8462 and users of known security concerns relevant to HTTP semantics and 8463 its use for transferring information over the Internet. 8464 Considerations related to caching are discussed in Section 7 of 8465 [CACHING] and considerations related to HTTP/1.1 message syntax and 8466 parsing are discussed in Section 11 of [HTTP/1.1]. 8468 The list of considerations below is not exhaustive. Most security 8469 concerns related to HTTP semantics are about securing server-side 8470 applications (code behind the HTTP interface), securing user agent 8471 processing of content received via HTTP, or secure use of the 8472 Internet in general, rather than security of the protocol. The 8473 security considerations for URIs, which are fundamental to HTTP 8474 operation, are discussed in Section 7 of [URI]. Various 8475 organizations maintain topical information and links to current 8476 research on Web application security (e.g., [OWASP]). 8478 17.1. Establishing Authority 8480 HTTP relies on the notion of an _authoritative response_: a response 8481 that has been determined by (or at the direction of) the origin 8482 server identified within the target URI to be the most appropriate 8483 response for that request given the state of the target resource at 8484 the time of response message origination. 8486 When a registered name is used in the authority component, the "http" 8487 URI scheme (Section 4.2.1) relies on the user's local name resolution 8488 service to determine where it can find authoritative responses. This 8489 means that any attack on a user's network host table, cached names, 8490 or name resolution libraries becomes an avenue for attack on 8491 establishing authority for "http" URIs. Likewise, the user's choice 8492 of server for Domain Name Service (DNS), and the hierarchy of servers 8493 from which it obtains resolution results, could impact the 8494 authenticity of address mappings; DNS Security Extensions (DNSSEC, 8495 [RFC4033]) are one way to improve authenticity, as are the various 8496 mechanisms for making DNS requests over more secure transfer 8497 protocols. 8499 Furthermore, after an IP address is obtained, establishing authority 8500 for an "http" URI is vulnerable to attacks on Internet Protocol 8501 routing. 8503 The "https" scheme (Section 4.2.2) is intended to prevent (or at 8504 least reveal) many of these potential attacks on establishing 8505 authority, provided that the negotiated connection is secured and the 8506 client properly verifies that the communicating server's identity 8507 matches the target URI's authority component (Section 4.3.4). 8508 Correctly implementing such verification can be difficult (see 8509 [Georgiev]). 8511 Authority for a given origin server can be delegated through protocol 8512 extensions; for example, [ALTSVC]. Likewise, the set of servers for 8513 which a connection is considered authoritative can be changed with a 8514 protocol extension like [RFC8336]. 8516 Providing a response from a non-authoritative source, such as a 8517 shared proxy cache, is often useful to improve performance and 8518 availability, but only to the extent that the source can be trusted 8519 or the distrusted response can be safely used. 8521 Unfortunately, communicating authority to users can be difficult. 8522 For example, _phishing_ is an attack on the user's perception of 8523 authority, where that perception can be misled by presenting similar 8524 branding in hypertext, possibly aided by userinfo obfuscating the 8525 authority component (see Section 4.2.1). User agents can reduce the 8526 impact of phishing attacks by enabling users to easily inspect a 8527 target URI prior to making an action, by prominently distinguishing 8528 (or rejecting) userinfo when present, and by not sending stored 8529 credentials and cookies when the referring document is from an 8530 unknown or untrusted source. 8532 17.2. Risks of Intermediaries 8534 HTTP intermediaries are inherently situated for on-path attacks. 8535 Compromise of the systems on which the intermediaries run can result 8536 in serious security and privacy problems. Intermediaries might have 8537 access to security-related information, personal information about 8538 individual users and organizations, and proprietary information 8539 belonging to users and content providers. A compromised 8540 intermediary, or an intermediary implemented or configured without 8541 regard to security and privacy considerations, might be used in the 8542 commission of a wide range of potential attacks. 8544 Intermediaries that contain a shared cache are especially vulnerable 8545 to cache poisoning attacks, as described in Section 7 of [CACHING]. 8547 Implementers need to consider the privacy and security implications 8548 of their design and coding decisions, and of the configuration 8549 options they provide to operators (especially the default 8550 configuration). 8552 Intermediaries are no more trustworthy than the people and policies 8553 under which they operate; HTTP cannot solve this problem. 8555 17.3. Attacks Based on File and Path Names 8557 Origin servers frequently make use of their local file system to 8558 manage the mapping from target URI to resource representations. Most 8559 file systems are not designed to protect against malicious file or 8560 path names. Therefore, an origin server needs to avoid accessing 8561 names that have a special significance to the system when mapping the 8562 target resource to files, folders, or directories. 8564 For example, UNIX, Microsoft Windows, and other operating systems use 8565 ".." as a path component to indicate a directory level above the 8566 current one, and they use specially named paths or file names to send 8567 data to system devices. Similar naming conventions might exist 8568 within other types of storage systems. Likewise, local storage 8569 systems have an annoying tendency to prefer user-friendliness over 8570 security when handling invalid or unexpected characters, 8571 recomposition of decomposed characters, and case-normalization of 8572 case-insensitive names. 8574 Attacks based on such special names tend to focus on either denial- 8575 of-service (e.g., telling the server to read from a COM port) or 8576 disclosure of configuration and source files that are not meant to be 8577 served. 8579 17.4. Attacks Based on Command, Code, or Query Injection 8581 Origin servers often use parameters within the URI as a means of 8582 identifying system services, selecting database entries, or choosing 8583 a data source. However, data received in a request cannot be 8584 trusted. An attacker could construct any of the request data 8585 elements (method, target URI, header fields, or content) to contain 8586 data that might be misinterpreted as a command, code, or query when 8587 passed through a command invocation, language interpreter, or 8588 database interface. 8590 For example, SQL injection is a common attack wherein additional 8591 query language is inserted within some part of the target URI or 8592 header fields (e.g., Host, Referer, etc.). If the received data is 8593 used directly within a SELECT statement, the query language might be 8594 interpreted as a database command instead of a simple string value. 8595 This type of implementation vulnerability is extremely common, in 8596 spite of being easy to prevent. 8598 In general, resource implementations ought to avoid use of request 8599 data in contexts that are processed or interpreted as instructions. 8600 Parameters ought to be compared to fixed strings and acted upon as a 8601 result of that comparison, rather than passed through an interface 8602 that is not prepared for untrusted data. Received data that isn't 8603 based on fixed parameters ought to be carefully filtered or encoded 8604 to avoid being misinterpreted. 8606 Similar considerations apply to request data when it is stored and 8607 later processed, such as within log files, monitoring tools, or when 8608 included within a data format that allows embedded scripts. 8610 17.5. Attacks via Protocol Element Length 8612 Because HTTP uses mostly textual, character-delimited fields, parsers 8613 are often vulnerable to attacks based on sending very long (or very 8614 slow) streams of data, particularly where an implementation is 8615 expecting a protocol element with no predefined length (Section 2.3). 8617 To promote interoperability, specific recommendations are made for 8618 minimum size limits on fields (Section 5.4). These are minimum 8619 recommendations, chosen to be supportable even by implementations 8620 with limited resources; it is expected that most implementations will 8621 choose substantially higher limits. 8623 A server can reject a message that has a target URI that is too long 8624 (Section 15.5.15) or request content that is too large 8625 (Section 15.5.14). Additional status codes related to capacity 8626 limits have been defined by extensions to HTTP [RFC6585]. 8628 Recipients ought to carefully limit the extent to which they process 8629 other protocol elements, including (but not limited to) request 8630 methods, response status phrases, field names, numeric values, and 8631 chunk lengths. Failure to limit such processing can result in 8632 arbitrary code execution due to buffer or arithmetic overflows, and 8633 increased vulnerability to denial-of-service attacks. 8635 17.6. Attacks using Shared-dictionary Compression 8637 Some attacks on encrypted protocols use the differences in size 8638 created by dynamic compression to reveal confidential information; 8639 for example, [BREACH]. These attacks rely on creating a redundancy 8640 between attacker-controlled content and the confidential information, 8641 such that a dynamic compression algorithm using the same dictionary 8642 for both content will compress more efficiently when the attacker- 8643 controlled content matches parts of the confidential content. 8645 HTTP messages can be compressed in a number of ways, including using 8646 TLS compression, content codings, transfer codings, and other 8647 extension or version-specific mechanisms. 8649 The most effective mitigation for this risk is to disable compression 8650 on sensitive data, or to strictly separate sensitive data from 8651 attacker-controlled data so that they cannot share the same 8652 compression dictionary. With careful design, a compression scheme 8653 can be designed in a way that is not considered exploitable in 8654 limited use cases, such as HPACK ([HPACK]). 8656 17.7. Disclosure of Personal Information 8658 Clients are often privy to large amounts of personal information, 8659 including both information provided by the user to interact with 8660 resources (e.g., the user's name, location, mail address, passwords, 8661 encryption keys, etc.) and information about the user's browsing 8662 activity over time (e.g., history, bookmarks, etc.). Implementations 8663 need to prevent unintentional disclosure of personal information. 8665 17.8. Privacy of Server Log Information 8667 A server is in the position to save personal data about a user's 8668 requests over time, which might identify their reading patterns or 8669 subjects of interest. In particular, log information gathered at an 8670 intermediary often contains a history of user agent interaction, 8671 across a multitude of sites, that can be traced to individual users. 8673 HTTP log information is confidential in nature; its handling is often 8674 constrained by laws and regulations. Log information needs to be 8675 securely stored and appropriate guidelines followed for its analysis. 8676 Anonymization of personal information within individual entries 8677 helps, but it is generally not sufficient to prevent real log traces 8678 from being re-identified based on correlation with other access 8679 characteristics. As such, access traces that are keyed to a specific 8680 client are unsafe to publish even if the key is pseudonymous. 8682 To minimize the risk of theft or accidental publication, log 8683 information ought to be purged of personally identifiable 8684 information, including user identifiers, IP addresses, and user- 8685 provided query parameters, as soon as that information is no longer 8686 necessary to support operational needs for security, auditing, or 8687 fraud control. 8689 17.9. Disclosure of Sensitive Information in URIs 8691 URIs are intended to be shared, not secured, even when they identify 8692 secure resources. URIs are often shown on displays, added to 8693 templates when a page is printed, and stored in a variety of 8694 unprotected bookmark lists. Many servers, proxies, and user agents 8695 log or display the target URI in places where it might be visible to 8696 third parties. It is therefore unwise to include information within 8697 a URI that is sensitive, personally identifiable, or a risk to 8698 disclose. 8700 When an application uses client-side mechanisms to construct a target 8701 URI out of user-provided information, such as the query fields of a 8702 form using GET, potentially sensitive data might be provided that 8703 would not be appropriate for disclosure within a URI. POST is often 8704 preferred in such cases because it usually doesn't construct a URI; 8705 instead, POST of a form transmits the potentially sensitive data in 8706 the request content. However, this hinders caching and uses an 8707 unsafe method for what would otherwise be a safe request. 8708 Alternative workarounds include transforming the user-provided data 8709 prior to constructing the URI, or filtering the data to only include 8710 common values that are not sensitive. Likewise, redirecting the 8711 result of a query to a different (server-generated) URI can remove 8712 potentially sensitive data from later links and provide a cacheable 8713 response for later reuse. 8715 Since the Referer header field tells a target site about the context 8716 that resulted in a request, it has the potential to reveal 8717 information about the user's immediate browsing history and any 8718 personal information that might be found in the referring resource's 8719 URI. Limitations on the Referer header field are described in 8720 Section 10.1.3 to address some of its security considerations. 8722 17.10. Application Handling of Field Names 8724 Servers often use non-HTTP gateway interfaces and frameworks to 8725 process a received request and produce content for the response. For 8726 historical reasons, such interfaces often pass received field names 8727 as external variable names, using a name mapping suitable for 8728 environment variables. 8730 For example, the Common Gateway Interface (CGI) mapping of protocol- 8731 specific meta-variables, defined by Section 4.1.18 of [RFC3875], is 8732 applied to received header fields that do not correspond to one of 8733 CGI's standard variables; the mapping consists of prepending "HTTP_" 8734 to each name and changing all instances of hyphen ("-") to underscore 8735 ("_"). This same mapping has been inherited by many other 8736 application frameworks in order to simplify moving applications from 8737 one platform to the next. 8739 In CGI, a received Content-Length field would be passed as the meta- 8740 variable "CONTENT_LENGTH" with a string value matching the received 8741 field's value. In contrast, a received "Content_Length" header field 8742 would be passed as the protocol-specific meta-variable 8743 "HTTP_CONTENT_LENGTH", which might lead to some confusion if an 8744 application mistakenly reads the protocol-specific meta-variable 8745 instead of the default one. (This historical practice is why 8746 Section 16.3.2.1 discourages the creation of new field names that 8747 contain an underscore.) 8749 Unfortunately, mapping field names to different interface names can 8750 lead to security vulnerabilities if the mapping is incomplete or 8751 ambiguous. For example, if an attacker were to send a field named 8752 "Transfer_Encoding", a naive interface might map that to the same 8753 variable name as the "Transfer-Encoding" field, resulting in a 8754 potential request smuggling vulnerability (Section 11.2 of 8755 [HTTP/1.1]). 8757 To mitigate the associated risks, implementations that perform such 8758 mappings are advised to make the mapping unambiguous and complete for 8759 the full range of potential octets received as a name (including 8760 those that are discouraged or forbidden by the HTTP grammar). For 8761 example, a field with an unusual name character might result in the 8762 request being blocked, the specific field being removed, or the name 8763 being passed with a different prefix to distinguish it from other 8764 fields. 8766 17.11. Disclosure of Fragment after Redirects 8768 Although fragment identifiers used within URI references are not sent 8769 in requests, implementers ought to be aware that they will be visible 8770 to the user agent and any extensions or scripts running as a result 8771 of the response. In particular, when a redirect occurs and the 8772 original request's fragment identifier is inherited by the new 8773 reference in Location (Section 10.2.2), this might have the effect of 8774 disclosing one site's fragment to another site. If the first site 8775 uses personal information in fragments, it ought to ensure that 8776 redirects to other sites include a (possibly empty) fragment 8777 component in order to block that inheritance. 8779 17.12. Disclosure of Product Information 8781 The User-Agent (Section 10.1.5), Via (Section 7.6.3), and Server 8782 (Section 10.2.4) header fields often reveal information about the 8783 respective sender's software systems. In theory, this can make it 8784 easier for an attacker to exploit known security holes; in practice, 8785 attackers tend to try all potential holes regardless of the apparent 8786 software versions being used. 8788 Proxies that serve as a portal through a network firewall ought to 8789 take special precautions regarding the transfer of header information 8790 that might identify hosts behind the firewall. The Via header field 8791 allows intermediaries to replace sensitive machine names with 8792 pseudonyms. 8794 17.13. Browser Fingerprinting 8796 Browser fingerprinting is a set of techniques for identifying a 8797 specific user agent over time through its unique set of 8798 characteristics. These characteristics might include information 8799 related to how it uses the underlying transport protocol, feature 8800 capabilities, and scripting environment, though of particular 8801 interest here is the set of unique characteristics that might be 8802 communicated via HTTP. Fingerprinting is considered a privacy 8803 concern because it enables tracking of a user agent's behavior over 8804 time ([Bujlow]) without the corresponding controls that the user 8805 might have over other forms of data collection (e.g., cookies). Many 8806 general-purpose user agents (i.e., Web browsers) have taken steps to 8807 reduce their fingerprints. 8809 There are a number of request header fields that might reveal 8810 information to servers that is sufficiently unique to enable 8811 fingerprinting. The From header field is the most obvious, though it 8812 is expected that From will only be sent when self-identification is 8813 desired by the user. Likewise, Cookie header fields are deliberately 8814 designed to enable re-identification, so fingerprinting concerns only 8815 apply to situations where cookies are disabled or restricted by the 8816 user agent's configuration. 8818 The User-Agent header field might contain enough information to 8819 uniquely identify a specific device, usually when combined with other 8820 characteristics, particularly if the user agent sends excessive 8821 details about the user's system or extensions. However, the source 8822 of unique information that is least expected by users is proactive 8823 negotiation (Section 12.1), including the Accept, Accept-Charset, 8824 Accept-Encoding, and Accept-Language header fields. 8826 In addition to the fingerprinting concern, detailed use of the 8827 Accept-Language header field can reveal information the user might 8828 consider to be of a private nature. For example, understanding a 8829 given language set might be strongly correlated to membership in a 8830 particular ethnic group. An approach that limits such loss of 8831 privacy would be for a user agent to omit the sending of Accept- 8832 Language except for sites that have been explicitly permitted, 8833 perhaps via interaction after detecting a Vary header field that 8834 indicates language negotiation might be useful. 8836 In environments where proxies are used to enhance privacy, user 8837 agents ought to be conservative in sending proactive negotiation 8838 header fields. General-purpose user agents that provide a high 8839 degree of header field configurability ought to inform users about 8840 the loss of privacy that might result if too much detail is provided. 8841 As an extreme privacy measure, proxies could filter the proactive 8842 negotiation header fields in relayed requests. 8844 17.14. Validator Retention 8846 The validators defined by this specification are not intended to 8847 ensure the validity of a representation, guard against malicious 8848 changes, or detect on-path attacks. At best, they enable more 8849 efficient cache updates and optimistic concurrent writes when all 8850 participants are behaving nicely. At worst, the conditions will fail 8851 and the client will receive a response that is no more harmful than 8852 an HTTP exchange without conditional requests. 8854 An entity-tag can be abused in ways that create privacy risks. For 8855 example, a site might deliberately construct a semantically invalid 8856 entity-tag that is unique to the user or user agent, send it in a 8857 cacheable response with a long freshness time, and then read that 8858 entity-tag in later conditional requests as a means of re-identifying 8859 that user or user agent. Such an identifying tag would become a 8860 persistent identifier for as long as the user agent retained the 8861 original cache entry. User agents that cache representations ought 8862 to ensure that the cache is cleared or replaced whenever the user 8863 performs privacy-maintaining actions, such as clearing stored cookies 8864 or changing to a private browsing mode. 8866 17.15. Denial-of-Service Attacks Using Range 8868 Unconstrained multiple range requests are susceptible to denial-of- 8869 service attacks because the effort required to request many 8870 overlapping ranges of the same data is tiny compared to the time, 8871 memory, and bandwidth consumed by attempting to serve the requested 8872 data in many parts. Servers ought to ignore, coalesce, or reject 8873 egregious range requests, such as requests for more than two 8874 overlapping ranges or for many small ranges in a single set, 8875 particularly when the ranges are requested out of order for no 8876 apparent reason. Multipart range requests are not designed to 8877 support random access. 8879 17.16. Authentication Considerations 8881 Everything about the topic of HTTP authentication is a security 8882 consideration, so the list of considerations below is not exhaustive. 8883 Furthermore, it is limited to security considerations regarding the 8884 authentication framework, in general, rather than discussing all of 8885 the potential considerations for specific authentication schemes 8886 (which ought to be documented in the specifications that define those 8887 schemes). Various organizations maintain topical information and 8888 links to current research on Web application security (e.g., 8889 [OWASP]), including common pitfalls for implementing and using the 8890 authentication schemes found in practice. 8892 17.16.1. Confidentiality of Credentials 8894 The HTTP authentication framework does not define a single mechanism 8895 for maintaining the confidentiality of credentials; instead, each 8896 authentication scheme defines how the credentials are encoded prior 8897 to transmission. While this provides flexibility for the development 8898 of future authentication schemes, it is inadequate for the protection 8899 of existing schemes that provide no confidentiality on their own, or 8900 that do not sufficiently protect against replay attacks. 8901 Furthermore, if the server expects credentials that are specific to 8902 each individual user, the exchange of those credentials will have the 8903 effect of identifying that user even if the content within 8904 credentials remains confidential. 8906 HTTP depends on the security properties of the underlying transport- 8907 or session-level connection to provide confidential transmission of 8908 fields. Services that depend on individual user authentication 8909 require a secured connection prior to exchanging credentials 8910 (Section 4.2.2). 8912 17.16.2. Credentials and Idle Clients 8914 Existing HTTP clients and user agents typically retain authentication 8915 information indefinitely. HTTP does not provide a mechanism for the 8916 origin server to direct clients to discard these cached credentials, 8917 since the protocol has no awareness of how credentials are obtained 8918 or managed by the user agent. The mechanisms for expiring or 8919 revoking credentials can be specified as part of an authentication 8920 scheme definition. 8922 Circumstances under which credential caching can interfere with the 8923 application's security model include but are not limited to: 8925 * Clients that have been idle for an extended period, following 8926 which the server might wish to cause the client to re-prompt the 8927 user for credentials. 8929 * Applications that include a session termination indication (such 8930 as a "logout" or "commit" button on a page) after which the server 8931 side of the application "knows" that there is no further reason 8932 for the client to retain the credentials. 8934 User agents that cache credentials are encouraged to provide a 8935 readily accessible mechanism for discarding cached credentials under 8936 user control. 8938 17.16.3. Protection Spaces 8940 Authentication schemes that solely rely on the "realm" mechanism for 8941 establishing a protection space will expose credentials to all 8942 resources on an origin server. Clients that have successfully made 8943 authenticated requests with a resource can use the same 8944 authentication credentials for other resources on the same origin 8945 server. This makes it possible for a different resource to harvest 8946 authentication credentials for other resources. 8948 This is of particular concern when an origin server hosts resources 8949 for multiple parties under the same origin (Section 11.5). Possible 8950 mitigation strategies include restricting direct access to 8951 authentication credentials (i.e., not making the content of the 8952 Authorization request header field available), and separating 8953 protection spaces by using a different host name (or port number) for 8954 each party. 8956 17.16.4. Additional Response Fields 8958 Adding information to responses that are sent over an unencrypted 8959 channel can affect security and privacy. The presence of the 8960 Authentication-Info and Proxy-Authentication-Info header fields alone 8961 indicates that HTTP authentication is in use. Additional information 8962 could be exposed by the contents of the authentication-scheme 8963 specific parameters; this will have to be considered in the 8964 definitions of these schemes. 8966 18. IANA Considerations 8968 The change controller for the following registrations is: "IETF 8969 (iesg@ietf.org) - Internet Engineering Task Force". 8971 18.1. URI Scheme Registration 8973 Please update the registry of URI Schemes [BCP35] at 8974 with the permanent 8975 schemes listed in the table in Section 4.2. 8977 18.2. Method Registration 8979 Please update the "Hypertext Transfer Protocol (HTTP) Method 8980 Registry" at with the 8981 registration procedure of Section 16.1.1 and the method names 8982 summarized in the following table. 8984 +=========+======+============+=======+ 8985 | Method | Safe | Idempotent | Ref. | 8986 +=========+======+============+=======+ 8987 | CONNECT | no | no | 9.3.6 | 8988 +---------+------+------------+-------+ 8989 | DELETE | no | yes | 9.3.5 | 8990 +---------+------+------------+-------+ 8991 | GET | yes | yes | 9.3.1 | 8992 +---------+------+------------+-------+ 8993 | HEAD | yes | yes | 9.3.2 | 8994 +---------+------+------------+-------+ 8995 | OPTIONS | yes | yes | 9.3.7 | 8996 +---------+------+------------+-------+ 8997 | POST | no | no | 9.3.3 | 8998 +---------+------+------------+-------+ 8999 | PUT | no | yes | 9.3.4 | 9000 +---------+------+------------+-------+ 9001 | TRACE | yes | yes | 9.3.8 | 9002 +---------+------+------------+-------+ 9003 | * | no | no | 18.2 | 9004 +---------+------+------------+-------+ 9006 Table 7 9008 The method name "*" is reserved, since using "*" as a method name 9009 would conflict with its usage as a wildcard in some fields (e.g., 9010 "Access-Control-Request-Method"). 9012 18.3. Status Code Registration 9014 Please update the "Hypertext Transfer Protocol (HTTP) Status Code 9015 Registry" at 9016 with the registration procedure of Section 16.2.1 and the status code 9017 values summarized in the following table. 9019 +=======+===============================+=========+ 9020 | Value | Description | Ref. | 9021 +=======+===============================+=========+ 9022 | 100 | Continue | 15.2.1 | 9023 +-------+-------------------------------+---------+ 9024 | 101 | Switching Protocols | 15.2.2 | 9025 +-------+-------------------------------+---------+ 9026 | 200 | OK | 15.3.1 | 9027 +-------+-------------------------------+---------+ 9028 | 201 | Created | 15.3.2 | 9029 +-------+-------------------------------+---------+ 9030 | 202 | Accepted | 15.3.3 | 9031 +-------+-------------------------------+---------+ 9032 | 203 | Non-Authoritative Information | 15.3.4 | 9033 +-------+-------------------------------+---------+ 9034 | 204 | No Content | 15.3.5 | 9035 +-------+-------------------------------+---------+ 9036 | 205 | Reset Content | 15.3.6 | 9037 +-------+-------------------------------+---------+ 9038 | 206 | Partial Content | 15.3.7 | 9039 +-------+-------------------------------+---------+ 9040 | 300 | Multiple Choices | 15.4.1 | 9041 +-------+-------------------------------+---------+ 9042 | 301 | Moved Permanently | 15.4.2 | 9043 +-------+-------------------------------+---------+ 9044 | 302 | Found | 15.4.3 | 9045 +-------+-------------------------------+---------+ 9046 | 303 | See Other | 15.4.4 | 9047 +-------+-------------------------------+---------+ 9048 | 304 | Not Modified | 15.4.5 | 9049 +-------+-------------------------------+---------+ 9050 | 305 | Use Proxy | 15.4.6 | 9051 +-------+-------------------------------+---------+ 9052 | 306 | (Unused) | 15.4.7 | 9053 +-------+-------------------------------+---------+ 9054 | 307 | Temporary Redirect | 15.4.8 | 9055 +-------+-------------------------------+---------+ 9056 | 308 | Permanent Redirect | 15.4.9 | 9057 +-------+-------------------------------+---------+ 9058 | 400 | Bad Request | 15.5.1 | 9059 +-------+-------------------------------+---------+ 9060 | 401 | Unauthorized | 15.5.2 | 9061 +-------+-------------------------------+---------+ 9062 | 402 | Payment Required | 15.5.3 | 9063 +-------+-------------------------------+---------+ 9064 | 403 | Forbidden | 15.5.4 | 9065 +-------+-------------------------------+---------+ 9066 | 404 | Not Found | 15.5.5 | 9067 +-------+-------------------------------+---------+ 9068 | 405 | Method Not Allowed | 15.5.6 | 9069 +-------+-------------------------------+---------+ 9070 | 406 | Not Acceptable | 15.5.7 | 9071 +-------+-------------------------------+---------+ 9072 | 407 | Proxy Authentication Required | 15.5.8 | 9073 +-------+-------------------------------+---------+ 9074 | 408 | Request Timeout | 15.5.9 | 9075 +-------+-------------------------------+---------+ 9076 | 409 | Conflict | 15.5.10 | 9077 +-------+-------------------------------+---------+ 9078 | 410 | Gone | 15.5.11 | 9079 +-------+-------------------------------+---------+ 9080 | 411 | Length Required | 15.5.12 | 9081 +-------+-------------------------------+---------+ 9082 | 412 | Precondition Failed | 15.5.13 | 9083 +-------+-------------------------------+---------+ 9084 | 413 | Content Too Large | 15.5.14 | 9085 +-------+-------------------------------+---------+ 9086 | 414 | URI Too Long | 15.5.15 | 9087 +-------+-------------------------------+---------+ 9088 | 415 | Unsupported Media Type | 15.5.16 | 9089 +-------+-------------------------------+---------+ 9090 | 416 | Range Not Satisfiable | 15.5.17 | 9091 +-------+-------------------------------+---------+ 9092 | 417 | Expectation Failed | 15.5.18 | 9093 +-------+-------------------------------+---------+ 9094 | 418 | (Unused) | 15.5.19 | 9095 +-------+-------------------------------+---------+ 9096 | 421 | Misdirected Request | 15.5.20 | 9097 +-------+-------------------------------+---------+ 9098 | 422 | Unprocessable Content | 15.5.21 | 9099 +-------+-------------------------------+---------+ 9100 | 426 | Upgrade Required | 15.5.22 | 9101 +-------+-------------------------------+---------+ 9102 | 500 | Internal Server Error | 15.6.1 | 9103 +-------+-------------------------------+---------+ 9104 | 501 | Not Implemented | 15.6.2 | 9105 +-------+-------------------------------+---------+ 9106 | 502 | Bad Gateway | 15.6.3 | 9107 +-------+-------------------------------+---------+ 9108 | 503 | Service Unavailable | 15.6.4 | 9109 +-------+-------------------------------+---------+ 9110 | 504 | Gateway Timeout | 15.6.5 | 9111 +-------+-------------------------------+---------+ 9112 | 505 | HTTP Version Not Supported | 15.6.6 | 9113 +-------+-------------------------------+---------+ 9114 Table 8 9116 18.4. Field Name Registration 9118 This specification updates the HTTP related aspects of the existing 9119 registration procedures for message header fields defined in 9120 [RFC3864]. It replaces the old procedures as they relate to HTTP, by 9121 defining a new registration procedure and moving HTTP field 9122 definitions into a separate registry. 9124 Please create a new registry as outlined in Section 16.3.1. 9126 After creating the registry, all entries in the Permanent and 9127 Provisional Message Header Registries with the protocol 'http' are to 9128 be moved to it, with the following changes applied: 9130 1. The 'Applicable Protocol' field is to be omitted. 9132 2. Entries with a status of 'standard', 'experimental', 'reserved', 9133 or 'informational' are to have a status of 'permanent'. 9135 3. Provisional entries without a status are to have a status of 9136 'provisional'. 9138 4. Permanent entries without a status (after confirmation that the 9139 registration document did not define one) will have a status of 9140 'provisional'. The Expert(s) can choose to update their status 9141 if there is evidence that another is more appropriate. 9143 Please annotate the Permanent and Provisional Message Header 9144 registries to indicate that HTTP field name registrations have moved, 9145 with an appropriate link. 9147 After that is complete, please update the new registry with the field 9148 names listed in the following table. 9150 +===========================+============+========+============+ 9151 | Field Name | Status | Ref. | Comments | 9152 +===========================+============+========+============+ 9153 | Accept | standard | 12.5.1 | | 9154 +---------------------------+------------+--------+------------+ 9155 | Accept-Charset | deprecated | 12.5.2 | | 9156 +---------------------------+------------+--------+------------+ 9157 | Accept-Encoding | standard | 12.5.3 | | 9158 +---------------------------+------------+--------+------------+ 9159 | Accept-Language | standard | 12.5.4 | | 9160 +---------------------------+------------+--------+------------+ 9161 | Accept-Ranges | standard | 14.3 | | 9162 +---------------------------+------------+--------+------------+ 9163 | Allow | standard | 10.2.1 | | 9164 +---------------------------+------------+--------+------------+ 9165 | Authentication-Info | standard | 11.6.3 | | 9166 +---------------------------+------------+--------+------------+ 9167 | Authorization | standard | 11.6.2 | | 9168 +---------------------------+------------+--------+------------+ 9169 | Connection | standard | 7.6.1 | | 9170 +---------------------------+------------+--------+------------+ 9171 | Content-Encoding | standard | 8.4 | | 9172 +---------------------------+------------+--------+------------+ 9173 | Content-Language | standard | 8.5 | | 9174 +---------------------------+------------+--------+------------+ 9175 | Content-Length | standard | 8.6 | | 9176 +---------------------------+------------+--------+------------+ 9177 | Content-Location | standard | 8.7 | | 9178 +---------------------------+------------+--------+------------+ 9179 | Content-Range | standard | 14.4 | | 9180 +---------------------------+------------+--------+------------+ 9181 | Content-Type | standard | 8.3 | | 9182 +---------------------------+------------+--------+------------+ 9183 | Date | standard | 6.6.1 | | 9184 +---------------------------+------------+--------+------------+ 9185 | ETag | standard | 8.8.3 | | 9186 +---------------------------+------------+--------+------------+ 9187 | Expect | standard | 10.1.1 | | 9188 +---------------------------+------------+--------+------------+ 9189 | From | standard | 10.1.2 | | 9190 +---------------------------+------------+--------+------------+ 9191 | Host | standard | 7.2 | | 9192 +---------------------------+------------+--------+------------+ 9193 | If-Match | standard | 13.1.1 | | 9194 +---------------------------+------------+--------+------------+ 9195 | If-Modified-Since | standard | 13.1.3 | | 9196 +---------------------------+------------+--------+------------+ 9197 | If-None-Match | standard | 13.1.2 | | 9198 +---------------------------+------------+--------+------------+ 9199 | If-Range | standard | 13.1.5 | | 9200 +---------------------------+------------+--------+------------+ 9201 | If-Unmodified-Since | standard | 13.1.4 | | 9202 +---------------------------+------------+--------+------------+ 9203 | Last-Modified | standard | 8.8.2 | | 9204 +---------------------------+------------+--------+------------+ 9205 | Location | standard | 10.2.2 | | 9206 +---------------------------+------------+--------+------------+ 9207 | Max-Forwards | standard | 7.6.2 | | 9208 +---------------------------+------------+--------+------------+ 9209 | Proxy-Authenticate | standard | 11.7.1 | | 9210 +---------------------------+------------+--------+------------+ 9211 | Proxy-Authentication-Info | standard | 11.7.3 | | 9212 +---------------------------+------------+--------+------------+ 9213 | Proxy-Authorization | standard | 11.7.2 | | 9214 +---------------------------+------------+--------+------------+ 9215 | Range | standard | 14.2 | | 9216 +---------------------------+------------+--------+------------+ 9217 | Referer | standard | 10.1.3 | | 9218 +---------------------------+------------+--------+------------+ 9219 | Retry-After | standard | 10.2.3 | | 9220 +---------------------------+------------+--------+------------+ 9221 | Server | standard | 10.2.4 | | 9222 +---------------------------+------------+--------+------------+ 9223 | TE | standard | 10.1.4 | | 9224 +---------------------------+------------+--------+------------+ 9225 | Trailer | standard | 6.6.2 | | 9226 +---------------------------+------------+--------+------------+ 9227 | Upgrade | standard | 7.8 | | 9228 +---------------------------+------------+--------+------------+ 9229 | User-Agent | standard | 10.1.5 | | 9230 +---------------------------+------------+--------+------------+ 9231 | Vary | standard | 12.5.5 | | 9232 +---------------------------+------------+--------+------------+ 9233 | Via | standard | 7.6.3 | | 9234 +---------------------------+------------+--------+------------+ 9235 | WWW-Authenticate | standard | 11.6.1 | | 9236 +---------------------------+------------+--------+------------+ 9237 | * | standard | 12.5.5 | (reserved) | 9238 +---------------------------+------------+--------+------------+ 9240 Table 9 9242 The field name "*" is reserved, since using that name as an HTTP 9243 header field might conflict with its special semantics in the Vary 9244 header field (Section 12.5.5). 9246 Finally, please update the "Content-MD5" entry in the new registry to 9247 have a status of 'obsoleted' with references to Section 14.15 of 9248 [RFC2616] (for the definition of the header field) and Appendix B of 9249 [RFC7231] (which removed the field definition from the updated 9250 specification). 9252 18.5. Authentication Scheme Registration 9254 Please update the "Hypertext Transfer Protocol (HTTP) Authentication 9255 Scheme Registry" at with the registration procedure of Section 16.4.1. No 9257 authentication schemes are defined in this document. 9259 18.6. Content Coding Registration 9261 Please update the "HTTP Content Coding Registry" at 9262 with the 9263 registration procedure of Section 16.6.1 and the content coding names 9264 summarized in the table below. 9266 +============+===========================================+=========+ 9267 | Name | Description | Ref. | 9268 +============+===========================================+=========+ 9269 | compress | UNIX "compress" data format [Welch] | 8.4.1.1 | 9270 +------------+-------------------------------------------+---------+ 9271 | deflate | "deflate" compressed data ([RFC1951]) | 8.4.1.2 | 9272 | | inside the "zlib" data format ([RFC1950]) | | 9273 +------------+-------------------------------------------+---------+ 9274 | gzip | GZIP file format [RFC1952] | 8.4.1.3 | 9275 +------------+-------------------------------------------+---------+ 9276 | identity | Reserved | 12.5.3 | 9277 +------------+-------------------------------------------+---------+ 9278 | x-compress | Deprecated (alias for compress) | 8.4.1.1 | 9279 +------------+-------------------------------------------+---------+ 9280 | x-gzip | Deprecated (alias for gzip) | 8.4.1.3 | 9281 +------------+-------------------------------------------+---------+ 9283 Table 10 9285 18.7. Range Unit Registration 9287 Please update the "HTTP Range Unit Registry" at 9288 with the 9289 registration procedure of Section 16.5.1 and the range unit names 9290 summarized in the table below. 9292 +=================+==================================+========+ 9293 | Range Unit Name | Description | Ref. | 9294 +=================+==================================+========+ 9295 | bytes | a range of octets | 14.1.2 | 9296 +-----------------+----------------------------------+--------+ 9297 | none | reserved as keyword to indicate | 14.3 | 9298 | | range requests are not supported | | 9299 +-----------------+----------------------------------+--------+ 9301 Table 11 9303 18.8. Media Type Registration 9305 Please update the "Media Types" registry at 9306 with the registration 9307 information in Section 14.6 for the media type "multipart/ 9308 byteranges". 9310 Furthermore please update the registry note about "q" parameters with 9311 a link to Section 12.5.1 of this document. 9313 18.9. Port Registration 9315 Please update the "Service Name and Transport Protocol Port Number" 9316 registry at for the services on ports 80 and 443 that use UDP or TCP 9318 to: 9320 1. use this document as "Reference", and 9322 2. when currently unspecified, set "Assignee" to "IESG" and 9323 "Contact" to "IETF_Chair". 9325 18.10. Upgrade Token Registration 9327 Please update the "Hypertext Transfer Protocol (HTTP) Upgrade Token 9328 Registry" at 9329 with the registration procedure of Section 16.7 and the upgrade token 9330 names summarized in the following table. 9332 +======+===================+=========================+======+ 9333 | Name | Description | Expected Version Tokens | Ref. | 9334 +======+===================+=========================+======+ 9335 | HTTP | Hypertext | any DIGIT.DIGIT (e.g, | 2.5 | 9336 | | Transfer Protocol | "2.0") | | 9337 +------+-------------------+-------------------------+------+ 9339 Table 12 9341 19. References 9343 19.1. Normative References 9345 [CACHING] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 9346 Ed., "HTTP Caching", Work in Progress, Internet-Draft, 9347 draft-ietf-httpbis-cache-19, 10 September 2021, 9348 . 9351 [RFC1950] Deutsch, L.P. and J-L. Gailly, "ZLIB Compressed Data 9352 Format Specification version 3.3", RFC 1950, 9353 DOI 10.17487/RFC1950, May 1996, 9354 . 9356 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 9357 version 1.3", RFC 1951, DOI 10.17487/RFC1951, May 1996, 9358 . 9360 [RFC1952] Deutsch, P., Gailly, J-L., Adler, M., Deutsch, L.P., and 9361 G. Randers-Pehrson, "GZIP file format specification 9362 version 4.3", RFC 1952, DOI 10.17487/RFC1952, May 1996, 9363 . 9365 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 9366 Extensions (MIME) Part Two: Media Types", RFC 2046, 9367 DOI 10.17487/RFC2046, November 1996, 9368 . 9370 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 9371 Requirement Levels", BCP 14, RFC 2119, 9372 DOI 10.17487/RFC2119, March 1997, 9373 . 9375 [RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of Language 9376 Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 9377 2006, . 9379 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 9380 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 9381 . 9383 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 9384 Specifications: ABNF", STD 68, RFC 5234, 9385 DOI 10.17487/RFC5234, January 2008, 9386 . 9388 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 9389 Housley, R., and W. Polk, "Internet X.509 Public Key 9390 Infrastructure Certificate and Certificate Revocation List 9391 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 9392 . 9394 [RFC5322] Resnick, P., "Internet Message Format", RFC 5322, 9395 DOI 10.17487/RFC5322, October 2008, 9396 . 9398 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 9399 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 9400 September 2009, . 9402 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 9403 Verification of Domain-Based Application Service Identity 9404 within Internet Public Key Infrastructure Using X.509 9405 (PKIX) Certificates in the Context of Transport Layer 9406 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 9407 2011, . 9409 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in 9410 Internationalization in the IETF", BCP 166, RFC 6365, 9411 DOI 10.17487/RFC6365, September 2011, 9412 . 9414 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 9415 RFC 7405, DOI 10.17487/RFC7405, December 2014, 9416 . 9418 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 9419 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 9420 May 2017, . 9422 [TCP] Postel, J., "Transmission Control Protocol", STD 7, 9423 RFC 793, DOI 10.17487/RFC0793, September 1981, 9424 . 9426 [TLS13] Rescorla, E., "The Transport Layer Security (TLS) Protocol 9427 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 9428 . 9430 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 9431 Resource Identifier (URI): Generic Syntax", STD 66, 9432 RFC 3986, DOI 10.17487/RFC3986, January 2005, 9433 . 9435 [USASCII] American National Standards Institute, "Coded Character 9436 Set -- 7-bit American Standard Code for Information 9437 Interchange", ANSI X3.4, 1986. 9439 [Welch] Welch, T. A., "A Technique for High-Performance Data 9440 Compression", IEEE Computer 17(6), 9441 DOI 10.1109/MC.1984.1659158, June 1984, 9442 . 9444 19.2. Informative References 9446 [ALTSVC] Nottingham, M., McManus, P., and J. Reschke, "HTTP 9447 Alternative Services", RFC 7838, DOI 10.17487/RFC7838, 9448 April 2016, . 9450 [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type 9451 Specifications and Registration Procedures", BCP 13, 9452 RFC 6838, January 2013, 9453 . 9455 [BCP178] Saint-Andre, P., Crocker, D., and M. Nottingham, 9456 "Deprecating the "X-" Prefix and Similar Constructs in 9457 Application Protocols", BCP 178, RFC 6648, June 2012, 9458 . 9460 [BCP35] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 9461 and Registration Procedures for URI Schemes", BCP 35, 9462 RFC 7595, June 2015, 9463 . 9465 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the 9466 CRIME Attack", July 2013, 9467 . 9470 [Bujlow] Bujlow, T., Carela-Espanol, V., Sole-Pareta, J., and P. 9471 Barlet-Ros, "A Survey on Web Tracking: Mechanisms, 9472 Implications, and Defenses", 9473 DOI 10.1109/JPROC.2016.2637878, Proceedings of the 9474 IEEE 105(8), August 2017, 9475 . 9477 [COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265, 9478 DOI 10.17487/RFC6265, April 2011, 9479 . 9481 [Err1912] RFC Errata, Erratum ID 1912, RFC 2978, 9482 . 9484 [Err5433] RFC Errata, Erratum ID 5433, RFC 2978, 9485 . 9487 [Georgiev] Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh, 9488 D., and V. Shmatikov, "The Most Dangerous Code in the 9489 World: Validating SSL Certificates in Non-browser 9490 Software", In Proceedings of the 2012 ACM Conference on 9491 Computer and Communications Security (CCS '12), pp. 38-49, 9492 DOI 10.1145/2382196.2382204, October 2012, 9493 . 9495 [HPACK] Peon, R. and H. Ruellan, "HPACK: Header Compression for 9496 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 9497 . 9499 [HTTP/1.0] Berners-Lee, T., Fielding, R.T., and H.F. Nielsen, 9500 "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945, 9501 DOI 10.17487/RFC1945, May 1996, 9502 . 9504 [HTTP/1.1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 9505 Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft- 9506 ietf-httpbis-messaging-19, 10 September 2021, 9507 . 9510 [HTTP/2] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 9511 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 9512 DOI 10.17487/RFC7540, May 2015, 9513 . 9515 [HTTP/3] Bishop, M., "Hypertext Transfer Protocol Version 3 9516 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 9517 quic-http-34, 2 February 2021, 9518 . 9521 [ISO-8859-1] 9522 International Organization for Standardization, 9523 "Information technology -- 8-bit single-byte coded graphic 9524 character sets -- Part 1: Latin alphabet No. 1", ISO/ 9525 IEC 8859-1:1998, 1998. 9527 [Kri2001] Kristol, D., "HTTP Cookies: Standards, Privacy, and 9528 Politics", ACM Transactions on Internet Technology 1(2), 9529 November 2001, . 9531 [OWASP] van der Stock, A., Ed., "A Guide to Building Secure Web 9532 Applications and Web Services", The Open Web Application 9533 Security Project (OWASP) 2.0.1, 27 July 2005, 9534 . 9536 [REST] Fielding, R.T., "Architectural Styles and the Design of 9537 Network-based Software Architectures", Doctoral 9538 Dissertation, University of California, Irvine, September 9539 2000, . 9541 [RFC1919] Chatel, M., "Classical versus Transparent IP Proxies", 9542 RFC 1919, DOI 10.17487/RFC1919, March 1996, 9543 . 9545 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 9546 Part Three: Message Header Extensions for Non-ASCII Text", 9547 RFC 2047, DOI 10.17487/RFC2047, November 1996, 9548 . 9550 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T. 9551 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 9552 RFC 2068, DOI 10.17487/RFC2068, January 1997, 9553 . 9555 [RFC2145] Mogul, J.C., Fielding, R.T., Gettys, J., and H.F. Nielsen, 9556 "Use and Interpretation of HTTP Version Numbers", 9557 RFC 2145, DOI 10.17487/RFC2145, May 1997, 9558 . 9560 [RFC2295] Holtman, K. and A.H. Mutz, "Transparent Content 9561 Negotiation in HTTP", RFC 2295, DOI 10.17487/RFC2295, 9562 March 1998, . 9564 [RFC2324] Masinter, L., "Hyper Text Coffee Pot Control Protocol 9565 (HTCPCP/1.0)", RFC 2324, DOI 10.17487/RFC2324, 1 April 9566 1998, . 9568 [RFC2557] Palme, F., Hopmann, A., Shelness, N., and E. Stefferud, 9569 "MIME Encapsulation of Aggregate Documents, such as HTML 9570 (MHTML)", RFC 2557, DOI 10.17487/RFC2557, March 1999, 9571 . 9573 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 9574 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 9575 Transfer Protocol -- HTTP/1.1", RFC 2616, 9576 DOI 10.17487/RFC2616, June 1999, 9577 . 9579 [RFC2617] Franks, J., Hallam-Baker, P.M., Hostetler, J.L., Lawrence, 9580 S.D., Leach, P.J., Luotonen, A., and L. Stewart, "HTTP 9581 Authentication: Basic and Digest Access Authentication", 9582 RFC 2617, DOI 10.17487/RFC2617, June 1999, 9583 . 9585 [RFC2774] Frystyk, H., Leach, P., and S. Lawrence, "An HTTP 9586 Extension Framework", RFC 2774, DOI 10.17487/RFC2774, 9587 February 2000, . 9589 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 9590 DOI 10.17487/RFC2818, May 2000, 9591 . 9593 [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration 9594 Procedures", BCP 19, RFC 2978, DOI 10.17487/RFC2978, 9595 October 2000, . 9597 [RFC3040] Cooper, I., Melve, I., and G. Tomlinson, "Internet Web 9598 Replication and Caching Taxonomy", RFC 3040, 9599 DOI 10.17487/RFC3040, January 2001, 9600 . 9602 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 9603 Procedures for Message Header Fields", BCP 90, RFC 3864, 9604 DOI 10.17487/RFC3864, September 2004, 9605 . 9607 [RFC3875] Robinson, D. and K. Coar, "The Common Gateway Interface 9608 (CGI) Version 1.1", RFC 3875, DOI 10.17487/RFC3875, 9609 October 2004, . 9611 [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S. 9612 Rose, "DNS Security Introduction and Requirements", 9613 RFC 4033, DOI 10.17487/RFC4033, March 2005, 9614 . 9616 [RFC4559] Jaganathan, K., Zhu, L., and J. Brezak, "SPNEGO-based 9617 Kerberos and NTLM HTTP Authentication in Microsoft 9618 Windows", RFC 4559, DOI 10.17487/RFC4559, June 2006, 9619 . 9621 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 9622 RFC 5789, DOI 10.17487/RFC5789, March 2010, 9623 . 9625 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 9626 "Network Time Protocol Version 4: Protocol and Algorithms 9627 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 9628 . 9630 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 9631 DOI 10.17487/RFC6454, December 2011, 9632 . 9634 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 9635 Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, 9636 . 9638 [RFC7230] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9639 Transfer Protocol (HTTP/1.1): Message Syntax and Routing", 9640 RFC 7230, DOI 10.17487/RFC7230, June 2014, 9641 . 9643 [RFC7231] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9644 Transfer Protocol (HTTP/1.1): Semantics and Content", 9645 RFC 7231, DOI 10.17487/RFC7231, June 2014, 9646 . 9648 [RFC7232] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9649 Transfer Protocol (HTTP/1.1): Conditional Requests", 9650 RFC 7232, DOI 10.17487/RFC7232, June 2014, 9651 . 9653 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. F. Reschke, Ed., 9654 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 9655 RFC 7233, DOI 10.17487/RFC7233, June 2014, 9656 . 9658 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. F. Reschke, 9659 Ed., "Hypertext Transfer Protocol (HTTP): Caching", 9660 RFC 7234, DOI 10.17487/RFC7234, June 2014, 9661 . 9663 [RFC7235] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9664 Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, 9665 DOI 10.17487/RFC7235, June 2014, 9666 . 9668 [RFC7538] Reschke, J. F., "The Hypertext Transfer Protocol Status 9669 Code 308 (Permanent Redirect)", RFC 7538, 9670 DOI 10.17487/RFC7538, April 2015, 9671 . 9673 [RFC7578] Masinter, L., "Returning Values from Forms: multipart/ 9674 form-data", RFC 7578, DOI 10.17487/RFC7578, July 2015, 9675 . 9677 [RFC7615] Reschke, J. F., "HTTP Authentication-Info and Proxy- 9678 Authentication-Info Response Header Fields", RFC 7615, 9679 DOI 10.17487/RFC7615, September 2015, 9680 . 9682 [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP 9683 Digest Access Authentication", RFC 7616, 9684 DOI 10.17487/RFC7616, September 2015, 9685 . 9687 [RFC7617] Reschke, J. F., "The 'Basic' HTTP Authentication Scheme", 9688 RFC 7617, DOI 10.17487/RFC7617, September 2015, 9689 . 9691 [RFC7694] Reschke, J. F., "Hypertext Transfer Protocol (HTTP) 9692 Client-Initiated Content-Encoding", RFC 7694, 9693 DOI 10.17487/RFC7694, November 2015, 9694 . 9696 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 9697 Writing an IANA Considerations Section in RFCs", BCP 26, 9698 RFC 8126, DOI 10.17487/RFC8126, June 2017, 9699 . 9701 [RFC8187] Reschke, J. F., "Indicating Character Encoding and 9702 Language for HTTP Header Field Parameters", RFC 8187, 9703 DOI 10.17487/RFC8187, September 2017, 9704 . 9706 [RFC8246] McManus, P., "HTTP Immutable Responses", RFC 8246, 9707 DOI 10.17487/RFC8246, September 2017, 9708 . 9710 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 9711 DOI 10.17487/RFC8288, October 2017, 9712 . 9714 [RFC8336] Nottingham, M. and E. Nygren, "The ORIGIN HTTP/2 Frame", 9715 RFC 8336, DOI 10.17487/RFC8336, March 2018, 9716 . 9718 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 9719 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 9720 . 9722 [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for 9723 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 9724 . 9726 [Sniffing] WHATWG, "MIME Sniffing", 9727 . 9729 [WEBDAV] Dusseault, L.M., Ed., "HTTP Extensions for Web Distributed 9730 Authoring and Versioning (WebDAV)", RFC 4918, 9731 DOI 10.17487/RFC4918, June 2007, 9732 . 9734 Appendix A. Collected ABNF 9736 In the collected ABNF below, list rules are expanded as per 9737 Section 5.6.1. 9739 Accept = [ ( media-range [ weight ] ) *( OWS "," OWS ( media-range [ 9740 weight ] ) ) ] 9741 Accept-Charset = [ ( ( token / "*" ) [ weight ] ) *( OWS "," OWS ( ( 9742 token / "*" ) [ weight ] ) ) ] 9743 Accept-Encoding = [ ( codings [ weight ] ) *( OWS "," OWS ( codings [ 9744 weight ] ) ) ] 9745 Accept-Language = [ ( language-range [ weight ] ) *( OWS "," OWS ( 9746 language-range [ weight ] ) ) ] 9747 Accept-Ranges = acceptable-ranges 9748 Allow = [ method *( OWS "," OWS method ) ] 9749 Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) ] 9750 Authorization = credentials 9752 BWS = OWS 9754 Connection = [ connection-option *( OWS "," OWS connection-option ) 9755 ] 9756 Content-Encoding = [ content-coding *( OWS "," OWS content-coding ) 9757 ] 9758 Content-Language = [ language-tag *( OWS "," OWS language-tag ) ] 9759 Content-Length = 1*DIGIT 9760 Content-Location = absolute-URI / partial-URI 9761 Content-Range = range-unit SP ( range-resp / unsatisfied-range ) 9762 Content-Type = media-type 9764 Date = HTTP-date 9766 ETag = entity-tag 9767 Expect = [ expectation *( OWS "," OWS expectation ) ] 9769 From = mailbox 9771 GMT = %x47.4D.54 ; GMT 9773 HTTP-date = IMF-fixdate / obs-date 9774 Host = uri-host [ ":" port ] 9776 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 9777 If-Match = "*" / [ entity-tag *( OWS "," OWS entity-tag ) ] 9778 If-Modified-Since = HTTP-date 9779 If-None-Match = "*" / [ entity-tag *( OWS "," OWS entity-tag ) ] 9780 If-Range = entity-tag / HTTP-date 9781 If-Unmodified-Since = HTTP-date 9782 Last-Modified = HTTP-date 9783 Location = URI-reference 9785 Max-Forwards = 1*DIGIT 9787 OWS = *( SP / HTAB ) 9789 Proxy-Authenticate = [ challenge *( OWS "," OWS challenge ) ] 9790 Proxy-Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) 9791 ] 9792 Proxy-Authorization = credentials 9794 RWS = 1*( SP / HTAB ) 9795 Range = ranges-specifier 9796 Referer = absolute-URI / partial-URI 9797 Retry-After = HTTP-date / delay-seconds 9799 Server = product *( RWS ( product / comment ) ) 9801 TE = [ t-codings *( OWS "," OWS t-codings ) ] 9802 Trailer = [ field-name *( OWS "," OWS field-name ) ] 9804 URI-reference = 9805 Upgrade = [ protocol *( OWS "," OWS protocol ) ] 9806 User-Agent = product *( RWS ( product / comment ) ) 9808 Vary = [ ( "*" / field-name ) *( OWS "," OWS ( "*" / field-name ) ) 9809 ] 9810 Via = [ ( received-protocol RWS received-by [ RWS comment ] ) *( OWS 9811 "," OWS ( received-protocol RWS received-by [ RWS comment ] ) ) ] 9813 WWW-Authenticate = [ challenge *( OWS "," OWS challenge ) ] 9815 absolute-URI = 9816 absolute-path = 1*( "/" segment ) 9817 acceptable-ranges = range-unit *( OWS "," OWS range-unit ) 9818 asctime-date = day-name SP date3 SP time-of-day SP year 9819 auth-param = token BWS "=" BWS ( token / quoted-string ) 9820 auth-scheme = token 9821 authority = 9823 challenge = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS "," 9824 OWS auth-param ) ] ) ] 9825 codings = content-coding / "identity" / "*" 9826 comment = "(" *( ctext / quoted-pair / comment ) ")" 9827 complete-length = 1*DIGIT 9828 connection-option = token 9829 content-coding = token 9830 credentials = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS "," 9831 OWS auth-param ) ] ) ] 9832 ctext = HTAB / SP / %x21-27 ; '!'-''' 9833 / %x2A-5B ; '*'-'[' 9834 / %x5D-7E ; ']'-'~' 9835 / obs-text 9837 date1 = day SP month SP year 9838 date2 = day "-" month "-" 2DIGIT 9839 date3 = month SP ( 2DIGIT / ( SP DIGIT ) ) 9840 day = 2DIGIT 9841 day-name = %x4D.6F.6E ; Mon 9842 / %x54.75.65 ; Tue 9843 / %x57.65.64 ; Wed 9844 / %x54.68.75 ; Thu 9845 / %x46.72.69 ; Fri 9846 / %x53.61.74 ; Sat 9847 / %x53.75.6E ; Sun 9848 day-name-l = %x4D.6F.6E.64.61.79 ; Monday 9849 / %x54.75.65.73.64.61.79 ; Tuesday 9850 / %x57.65.64.6E.65.73.64.61.79 ; Wednesday 9851 / %x54.68.75.72.73.64.61.79 ; Thursday 9852 / %x46.72.69.64.61.79 ; Friday 9853 / %x53.61.74.75.72.64.61.79 ; Saturday 9854 / %x53.75.6E.64.61.79 ; Sunday 9855 delay-seconds = 1*DIGIT 9857 entity-tag = [ weak ] opaque-tag 9858 etagc = "!" / %x23-7E ; '#'-'~' 9859 / obs-text 9860 expectation = token [ "=" ( token / quoted-string ) parameters ] 9862 field-content = field-vchar [ 1*( SP / HTAB / field-vchar ) 9863 field-vchar ] 9864 field-name = token 9865 field-value = *field-content 9866 field-vchar = VCHAR / obs-text 9867 first-pos = 1*DIGIT 9869 hour = 2DIGIT 9870 http-URI = "http://" authority path-abempty [ "?" query ] 9871 https-URI = "https://" authority path-abempty [ "?" query ] 9873 incl-range = first-pos "-" last-pos 9874 int-range = first-pos "-" [ last-pos ] 9876 language-range = 9877 language-tag = 9878 last-pos = 1*DIGIT 9880 mailbox = 9881 media-range = ( "*/*" / ( type "/*" ) / ( type "/" subtype ) ) 9882 parameters 9883 media-type = type "/" subtype parameters 9884 method = token 9885 minute = 2DIGIT 9886 month = %x4A.61.6E ; Jan 9887 / %x46.65.62 ; Feb 9888 / %x4D.61.72 ; Mar 9889 / %x41.70.72 ; Apr 9890 / %x4D.61.79 ; May 9891 / %x4A.75.6E ; Jun 9892 / %x4A.75.6C ; Jul 9893 / %x41.75.67 ; Aug 9894 / %x53.65.70 ; Sep 9895 / %x4F.63.74 ; Oct 9896 / %x4E.6F.76 ; Nov 9897 / %x44.65.63 ; Dec 9899 obs-date = rfc850-date / asctime-date 9900 obs-text = %x80-FF 9901 opaque-tag = DQUOTE *etagc DQUOTE 9902 other-range = 1*( %x21-2B ; '!'-'+' 9903 / %x2D-7E ; '-'-'~' 9904 ) 9906 parameter = parameter-name "=" parameter-value 9907 parameter-name = token 9908 parameter-value = ( token / quoted-string ) 9909 parameters = *( OWS ";" OWS [ parameter ] ) 9910 partial-URI = relative-part [ "?" query ] 9911 path-abempty = 9912 port = 9913 product = token [ "/" product-version ] 9914 product-version = token 9915 protocol = protocol-name [ "/" protocol-version ] 9916 protocol-name = token 9917 protocol-version = token 9918 pseudonym = token 9920 qdtext = HTAB / SP / "!" / %x23-5B ; '#'-'[' 9921 / %x5D-7E ; ']'-'~' 9922 / obs-text 9923 query = 9924 quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) 9925 quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE 9926 qvalue = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] ) 9928 range-resp = incl-range "/" ( complete-length / "*" ) 9929 range-set = range-spec *( OWS "," OWS range-spec ) 9930 range-spec = int-range / suffix-range / other-range 9931 range-unit = token 9932 ranges-specifier = range-unit "=" range-set 9933 received-by = pseudonym [ ":" port ] 9934 received-protocol = [ protocol-name "/" ] protocol-version 9935 relative-part = 9936 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 9938 second = 2DIGIT 9939 segment = 9940 subtype = token 9941 suffix-length = 1*DIGIT 9942 suffix-range = "-" suffix-length 9944 t-codings = "trailers" / ( transfer-coding [ weight ] ) 9945 tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / 9946 "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA 9947 time-of-day = hour ":" minute ":" second 9948 token = 1*tchar 9949 token68 = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) 9950 *"=" 9951 transfer-coding = token *( OWS ";" OWS transfer-parameter ) 9952 transfer-parameter = token BWS "=" BWS ( token / quoted-string ) 9953 type = token 9955 unsatisfied-range = "*/" complete-length 9956 uri-host = 9958 weak = %x57.2F ; W/ 9959 weight = OWS ";" OWS "q=" qvalue 9961 year = 4DIGIT 9963 Appendix B. Changes from previous RFCs 9965 B.1. Changes from RFC 2818 9967 None. 9969 B.2. Changes from RFC 7230 9971 The sections introducing HTTP's design goals, history, architecture, 9972 conformance criteria, protocol versioning, URIs, message routing, and 9973 header fields have been moved here. 9975 The requirement on semantic conformance has been replaced with 9976 permission to ignore/workaround implementation-specific failures. 9977 (Section 2.2) 9979 The description of an origin and authoritative access to origin 9980 servers has been extended for both "http" and "https" URIs to account 9981 for alternative services and secured connections that are not 9982 necessarily based on TCP. (Section 4.2.1, Section 4.2.2, 9983 Section 4.3.1, Section 7.3.3) 9985 Explicit requirements have been added to check the target URI 9986 scheme's semantics and reject requests that don't meet any associated 9987 requirements. (Section 7.4) 9989 Parameters in media type, media range, and expectation can be empty 9990 via one or more trailing semicolons. (Section 5.6.6) 9992 "Field value" now refers to the value after multiple field lines are 9993 combined with commas - by far the most common use. To refer to a 9994 single header line's value, use "field line value". (Section 6.3) 9996 Trailer field semantics now transcend the specifics of chunked 9997 encoding. Use of trailer fields has been further limited to only 9998 allow generation as a trailer field when the sender knows the field 9999 defines that usage and to only allow merging into the header section 10000 if the recipient knows the corresponding field definition permits and 10001 defines how to merge. In all other cases, implementations are 10002 encouraged to either store the trailer fields separately or discard 10003 them instead of merging. (Section 6.5.1) 10005 Made the priority of the absolute form of the request URI over the 10006 Host header by origin servers explicit, to align with proxy handling. 10007 (Section 7.2) 10009 The grammar definition for the Via field's "received-by" was expanded 10010 in 7230 due to changes in the URI grammar for host [URI] that are not 10011 desirable for Via. For simplicity, we have removed uri-host from the 10012 received-by production because it can be encompassed by the existing 10013 grammar for pseudonym. In particular, this change removed comma from 10014 the allowed set of charaters for a host name in received-by. 10015 (Section 7.6.3) 10017 B.3. Changes from RFC 7231 10019 Minimum URI lengths to be supported by implementations are now 10020 recommended. (Section 3.1) 10021 Clarified that CR and NUL in field values are to be rejected or 10022 mapped to SP and that leading and trailing whitespace need to be 10023 stripped from field values before they are consumed. (Section 5.5) 10025 Parameters in media type, media range, and expectation can be empty 10026 via one or more trailing semicolons. (Section 5.6.6) 10028 An abstract data type for HTTP messages has been introduced to define 10029 the components of a message and their semantics as an abstraction 10030 across multiple HTTP versions, rather than in terms of the specific 10031 syntax form of HTTP/1.1 in [HTTP/1.1], and reflect the contents after 10032 the message is parsed. This makes it easier to distinguish between 10033 requirements on the content (what is conveyed) versus requirements on 10034 the messaging syntax (how it is conveyed) and avoids baking 10035 limitations of early protocol versions into the future of HTTP. 10036 (Section 6) 10038 The terms "payload" and "payload body" have been replaced with 10039 "content", to better align with its usage elsewhere (e.g., in field 10040 names) and to avoid confusion with frame payloads in HTTP/2 and 10041 HTTP/3. (Section 6.4) 10043 The term "effective request URI" has been replaced with "target URI". 10044 (Section 7.1) 10046 Restrictions on client retries have been loosened, to reflect 10047 implementation behavior. (Section 9.2.2) 10049 Clarified that request bodies on GET, HEAD, and DELETE are not 10050 interoperable. (Section 9.3.1, Section 9.3.2, Section 9.3.5) 10052 Allowed use of the Content-Range header field (Section 14.4) as a 10053 request modifier on PUT. (Section 9.3.4) 10055 Removed a superfluous requirement about setting Content-Length from 10056 the description of the OPTIONS method. (Section 9.3.7) 10058 Removed normative requirement to use the "message/http" media type in 10059 TRACE responses. (Section 9.3.8) 10061 Restore list-based grammar for Expect for compatibility with RFC 10062 2616. (Section 10.1.1) 10064 Allow Accept and Accept-Encoding in response messages; the latter was 10065 introduced by [RFC7694]. (Section 12.3) 10066 "Accept Parameters" (accept-params and accept-ext ABNF production) 10067 have been removed from the definition of the Accept field. 10068 (Section 12.5.1) 10070 The "Accept-Charset" field now is deprecated. (Section 12.5.2) 10072 The semantics of "*" in the Vary header field when other values are 10073 present was clarified. (Section 12.5.5) 10075 Range units are compared in a case insensitive fashion. 10076 (Section 14.1) 10078 Use of "Accept-Ranges" is not restricted to origin servers. 10079 (Section 14.3) 10081 The process of creating a redirected request has been clarified. 10082 (Section 15.4) 10084 Added status code 308 (previously defined in [RFC7538]) so that it's 10085 defined closer to status codes 301, 302, and 307. (Section 15.4.9) 10087 Added status code 421 (previously defined in Section 9.1.2 of 10088 [HTTP/2]) because of its general applicability. 421 is no longer 10089 defined as heuristically cacheable, since the response is specific to 10090 the connection (not the target resource). (Section 15.5.20) 10092 Added status code 422 (previously defined in Section 11.2 of 10093 [WEBDAV]) because of its general applicability. (Section 15.5.21) 10095 B.4. Changes from RFC 7232 10097 Previous revisions of HTTP imposed an arbitrary 60-second limit on 10098 the determination of whether Last-Modified was a strong validator to 10099 guard against the possibility that the Date and Last-Modified values 10100 are generated from different clocks or at somewhat different times 10101 during the preparation of the response. This specification has 10102 relaxed that to allow reasonable discretion. (Section 8.8.2.2) 10104 Removed edge case requirement on If-Match and If-Unmodified-Since 10105 that a validator not be sent in a 2xx response when validation fails 10106 and the server decides that the same change request has already been 10107 applied. (Section 13.1.1 and Section 13.1.4) 10109 Clarified that If-Unmodified-Since doesn't apply to a resource 10110 without a concept of modification time. (Section 13.1.4) 10111 Preconditions can now be evaluated before the request content is 10112 processed rather than waiting until the response would otherwise be 10113 successful. (Section 13.2) 10115 B.5. Changes from RFC 7233 10117 Refactored the range-unit and ranges-specifier grammars to simplify 10118 and reduce artificial distinctions between bytes and other 10119 (extension) range units, removing the overlapping grammar of other- 10120 range-unit by defining range units generically as a token and placing 10121 extensions within the scope of a range-spec (other-range). This 10122 disambiguates the role of list syntax (commas) in all range sets, 10123 including extension range units, for indicating a range-set of more 10124 than one range. Moving the extension grammar into range specifiers 10125 also allows protocol specific to byte ranges to be specified 10126 separately. 10128 It is now possible to define Range handling on extension methods. 10129 (Section 14.2) 10131 Described use of the Content-Range header field (Section 14.4) as a 10132 request modifier to perform a partial PUT. (Section 14.5) 10134 B.6. Changes from RFC 7235 10136 None. 10138 B.7. Changes from RFC 7538 10140 None. 10142 B.8. Changes from RFC 7615 10144 None. 10146 B.9. Changes from RFC 7694 10148 This specification includes the extension defined in [RFC7694], but 10149 leaves out examples and deployment considerations. 10151 Appendix C. Change Log 10153 This section is to be removed before publishing as an RFC. 10155 C.1. Between RFC723x and draft 00 10157 The changes were purely editorial: 10159 * Change boilerplate and abstract to indicate the "draft" status, 10160 and update references to ancestor specifications. 10162 * Remove version "1.1" from document title, indicating that this 10163 specification applies to all HTTP versions. 10165 * Adjust historical notes. 10167 * Update links to sibling specifications. 10169 * Replace sections listing changes from RFC 2616 by new empty 10170 sections referring to RFC 723x. 10172 * Remove acknowledgements specific to RFC 723x. 10174 * Move "Acknowledgements" to the very end and make them unnumbered. 10176 C.2. Since draft-ietf-httpbis-semantics-00 10178 The changes in this draft are editorial, with respect to HTTP as a 10179 whole, to merge core HTTP semantics into this document: 10181 * Merged introduction, architecture, conformance, and ABNF 10182 extensions from RFC 7230 (Messaging). 10184 * Rearranged architecture to extract conformance, http(s) schemes, 10185 and protocol versioning into a separate major section. 10187 * Moved discussion of MIME differences to [HTTP/1.1] since that is 10188 primarily concerned with transforming 1.1 messages. 10190 * Merged entire content of RFC 7232 (Conditional Requests). 10192 * Merged entire content of RFC 7233 (Range Requests). 10194 * Merged entire content of RFC 7235 (Auth Framework). 10196 * Moved all extensibility tips, registration procedures, and 10197 registry tables from the IANA considerations to normative 10198 sections, reducing the IANA considerations to just instructions 10199 that will be removed prior to publication as an RFC. 10201 C.3. Since draft-ietf-httpbis-semantics-01 10203 * Improve [Welch] citation () 10206 * Remove HTTP/1.1-ism about Range Requests 10207 () 10209 * Cite RFC 8126 instead of RFC 5226 () 10212 * Cite RFC 7538 instead of RFC 7238 () 10215 * Cite RFC 8288 instead of RFC 5988 () 10218 * Cite RFC 8187 instead of RFC 5987 () 10221 * Cite RFC 7578 instead of RFC 2388 () 10224 * Cite RFC 7595 instead of RFC 4395 () 10227 * improve ABNF readability for qdtext (, ) 10230 * Clarify "resource" vs "representation" in definition of status 10231 code 416 (, 10232 ) 10234 * Resolved erratum 4072, no change needed here 10235 (, 10236 ) 10238 * Clarify DELETE status code suggestions 10239 (, 10240 ) 10242 * In Section 14.4, fix ABNF for "other-range-resp" to use VCHAR 10243 instead of CHAR (, 10244 ) 10246 * Resolved erratum 5162, no change needed here 10247 (, 10248 ) 10250 * Replace "response code" with "response status code" and "status- 10251 code" (the ABNF production name from the HTTP/1.1 message format) 10252 by "status code" (, 10253 ) 10255 * Added a missing word in Section 15.4 (, ) 10258 * In Section 5.6.1, fixed an example that had trailing whitespace 10259 where it shouldn't (, ) 10262 * In Section 15.3.7, remove words that were potentially misleading 10263 with respect to the relation to the requested ranges 10264 (, 10265 ) 10267 C.4. Since draft-ietf-httpbis-semantics-02 10269 * Included (Proxy-)Auth-Info header field definition from RFC 7615 10270 () 10272 * In Section 9.3.3, clarify POST caching 10273 () 10275 * Add Section 15.5.19 to reserve the 418 status code 10276 () 10278 * In Section 3.4 and Section 10.1.1, clarified when a response can 10279 be sent () 10281 * In Section 8.3.2, explain the difference between the "token" 10282 production, the RFC 2978 ABNF for charset names, and the actual 10283 registration practice (, ) 10286 * In Section 3.1, removed the fragment component in the URI scheme 10287 definitions as per Section 4.3 of [URI], furthermore moved 10288 fragment discussion into a separate section 10289 (, 10290 , ) 10293 * In Section 2.5, add language about minor HTTP version number 10294 defaulting () 10296 * Added Section 15.5.21 for status code 422, previously defined in 10297 Section 11.2 of [WEBDAV] () 10300 * In Section 15.5.17, fixed prose about byte range comparison 10301 (, 10302 ) 10304 * In Section 3.4, explain that request/response correlation is 10305 version specific () 10308 C.5. Since draft-ietf-httpbis-semantics-03 10310 * In Section 15.4.9, include status code 308 from RFC 7538 10311 () 10313 * In Section 8.3.1, clarify that the charset parameter value is 10314 case-insensitive due to the definition in RFC 2046 10315 () 10317 * Define a separate registry for HTTP header field names 10318 () 10320 * In Section 12.1, refactor and clarify description of wildcard 10321 ("*") handling () 10323 * Deprecate Accept-Charset () 10326 * In Section 13.2, mention Cache-Control: immutable 10327 () 10329 * In Section 5.3, clarify when header field combination is allowed 10330 () 10332 * In Section 18.4, instruct IANA to mark Content-MD5 as obsolete 10333 () 10335 * Use RFC 7405 ABNF notation for case-sensitive string constants 10336 () 10338 * Rework Section 3.4 to be more version-independent 10339 () 10341 * In Section 9.3.5, clarify that DELETE needs to be successful to 10342 invalidate cache (, ) 10345 C.6. Since draft-ietf-httpbis-semantics-04 10347 * In Section 5.5, fix field-content ABNF 10348 (, 10349 ) 10351 * Move Section 5.6.6 into its own section 10352 () 10354 * In Section 8.3, reference MIME Sniffing 10355 () 10357 * In Section 5.6.1, simplify the #rule mapping for recipients 10358 (, 10359 ) 10361 * In Section 9.3.7, remove misleading text about "extension" of HTTP 10362 is needed to define method content () 10365 * Fix editorial issue in Section 3.2 () 10368 * In Section 15.5.21, rephrase language not to use "entity" anymore, 10369 and also avoid lowercase "may" () 10372 * Move discussion of retries from [HTTP/1.1] into Section 9.2.2 10373 () 10375 C.7. Since draft-ietf-httpbis-semantics-05 10377 * Moved transport-independent part of the description of trailers 10378 into Section 6.5 () 10380 * Loosen requirements on retries based upon implementation behavior 10381 () 10383 * In Section 18.9, update IANA port registry for TCP/UDP on ports 80 10384 and 443 () 10386 * In Section 16.3.2.2, revise guidelines for new header field names 10387 () 10389 * In Section 9.2.3, remove concept of "cacheable methods" in favor 10390 of prose (, 10391 ) 10393 * In Section 17.1, mention that the concept of authority can be 10394 modified by protocol extensions () 10397 * Create new subsection on content in Section 6.4, taken from 10398 portions of message body () 10401 * Moved definition of "Whitespace" into new container "Generic 10402 Syntax" () 10404 * In Section 3.1, recommend minimum URI size support for 10405 implementations () 10407 * In Section 14.1, refactored the range-unit and ranges-specifier 10408 grammars (, 10409 ) 10411 * In Section 9.3.1, caution against a request content more strongly 10412 () 10414 * Reorganized text in Section 16.3.2.2 () 10417 * In Section 15.5.4, replace "authorize" with "fulfill" 10418 () 10420 * In Section 9.3.7, removed a misleading statement about Content- 10421 Length (, 10422 ) 10424 * In Section 17.1, add text from RFC 2818 10425 () 10427 * Changed "cacheable by default" to "heuristically cacheable" 10428 throughout () 10430 C.8. Since draft-ietf-httpbis-semantics-06 10432 * In Section 7.6.3, simplify received-by grammar (and disallow comma 10433 character) () 10435 * In Section 5.1, give guidance on interoperable field names 10436 () 10438 * In Section 5.6.3, define the semantics and possible replacement of 10439 whitespace when it is known to occur (, ) 10442 * In Section 6.3, introduce field terminology and distinguish 10443 between field line values and field values; use terminology 10444 consistently throughout () 10447 * Moved #rule definition into Section 5.5 and whitespace into 10448 Section 2.1 () 10450 * In Section 14.1, explicitly call out range unit names as case- 10451 insensitive, and encourage registration 10452 () 10454 * In Section 8.4.1, explicitly call out content codings as case- 10455 insensitive, and encourage registration 10456 () 10458 * In Section 5.1, explicitly call out field names as case- 10459 insensitive () 10461 * In Section 17.13, cite [Bujlow] () 10464 * In Section 15, formally define "final" and "interim" status codes 10465 () 10467 * In Section 9.3.5, caution against a request content more strongly 10468 () 10470 * In Section 8.8.3, note that Etag can be used in trailers 10471 () 10473 * In Section 18.4, consider reserved fields as well 10474 () 10476 * In Section 4.2.4, be more correct about what was deprecated by RFC 10477 3986 (, 10478 ) 10480 * In Section 5.3, recommend comma SP when combining field lines 10481 () 10483 * In Section 7.2, make explicit requirements on origin server to use 10484 authority from absolute-form when available 10485 () 10487 * In Section 4.2.1, Section 4.2.2, Section 4.3.1, and Section 7.3.3, 10488 refactored schemes to define origin and authoritative access to an 10489 origin server for both "http" and "https" URIs to account for 10490 alternative services and secured connections that are not 10491 necessarily based on TCP () 10494 * In Section 2.2, reference RFC 8174 as well 10495 () 10497 C.9. Since draft-ietf-httpbis-semantics-07 10499 * In Section 14.2, explicitly reference the definition of 10500 representation data as including any content codings 10501 () 10503 * Move TE: trailers from [HTTP/1.1] into Section 6.5.1 10504 () 10506 * In Section 8.6, adjust requirements for handling multiple content- 10507 length values () 10509 * In Section 13.1.1 and Section 13.1.2, clarified condition 10510 evaluation () 10512 * In Section 5.5, remove concept of obs-fold, as that is 10513 HTTP/1-specific () 10515 * In Section 12, introduce the concept of request content 10516 negotiation (Section 12.3) and define for Accept-Encoding 10517 () 10519 * In Section 15.3.6, Section 15.5.9, and Section 15.5.14, remove 10520 HTTP/1-specific, connection-related requirements 10521 () 10523 * In Section 9.3.6, correct language about what is forwarded 10524 () 10526 * Throughout, replace "effective request URI", "request-target" and 10527 similar with "target URI" () 10530 * In Section 16.3.2.2 and Section 16.2.2, describe how extensions 10531 should consider scope of applicability 10532 () 10534 * In Section 3.4, don't rely on the HTTP/1.1 Messaging specification 10535 to define "message" () 10538 * In Section 8.7 and Section 10.1.3, note that URL resolution is 10539 necessary () 10541 * In Section 3.2, explicitly reference 206 as one of the status 10542 codes that provide representation data 10543 () 10545 * In Section 13.1.4, refine requirements so that they don't apply to 10546 resources without a concept of modification time 10547 () 10549 * In Section 11.7.1, specify the scope as a request, not a target 10550 resource () 10552 * In Section 3.4, introduce concept of "complete" messages 10553 () 10555 * In Section 7.1, Section 9.3.6, and Section 9.3.7, refine use of 10556 "request target" () 10559 * Throughout, remove "status-line" and "request-line", as these are 10560 HTTP/1.1-specific () 10563 C.10. Since draft-ietf-httpbis-semantics-08 10565 * In Section 15.5.17, remove duplicate definition of what makes a 10566 range satisfiable and refer instead to each range unit's 10567 definition () 10569 * In Section 14.1.2 and Section 14.2, clarify that a selected 10570 representation of zero length can only be satisfiable as a suffix 10571 range and that a server can still ignore Range for that case 10572 () 10574 * In Section 12.5.1 and Section 15.5.16, allow "Accept" as response 10575 field () 10577 * Appendix A now uses the sender variant of the "#" list expansion 10578 () 10580 * In Section 12.5.5, make the field list-based even when "*" is 10581 present () 10583 * In Section 16.3.1, add optional "Comments" entry 10584 () 10586 * In Section 18.4, reserve "*" as field name 10587 () 10589 * In Section 18.2, reserve "*" as method name 10590 () 10592 * In Section 13.1.1 and Section 13.1.2, state that multiple "*" is 10593 unlikely to be interoperable () 10596 * In Section 12.5.1, avoid use of obsolete media type parameter on 10597 text/html (, 10598 ) 10600 * Rephrase prose in Section 3.4 to become version-agnostic 10601 () 10603 * In Section 5.5, instruct recipients how to deal with control 10604 characters in field values () 10607 * In Section 5.5, update note about field ABNF 10608 () 10610 * Add Section 16 about Extending and Versioning HTTP 10611 () 10613 * In Section 15.1, include status 308 in list of heuristically 10614 cacheable status codes () 10617 * In Section 8.4, make it clearer that "identity" is not to be 10618 included () 10620 C.11. Since draft-ietf-httpbis-semantics-09 10622 * Switch to xml2rfc v3 mode for draft generation 10623 () 10625 C.12. Since draft-ietf-httpbis-semantics-10 10627 * In Section 17.6, mention compression attacks 10628 () 10630 * In Section 16.6.1, advise to make new content codings self- 10631 descriptive () 10633 * In Section 5.6.6, introduced the "parameters" ABNF rule, allowing 10634 empty parameters and trailing semicolons within media type, media 10635 range, and expectation () 10638 * In Section 15.4, explain how to create a redirected request 10639 () 10641 * In Section 8.3, defined error handling for multiple members 10642 () 10644 * In Section 1, revise the introduction and introduce HTTP/2 and 10645 HTTP/3 () 10647 * In Section 8.6, added a definition for Content-Length that 10648 encompasses its various roles in describing message content or 10649 selected representation length; in Section 15.3.7, noted that 10650 Content-Length counts only the message content (not the selected 10651 representation) and that the representation length is in each 10652 Content-Range () 10654 * Noted that "WWW-Authenticate" with more than one value on a line 10655 is sometimes not interoperable [HTTP/1.1] 10656 () 10658 * In Section 13.1.1 and Section 13.1.4, removed requirement that a 10659 validator not be sent in a 2xx response when validation fails and 10660 the server decides that the same change request has already been 10661 applied () 10663 * Moved requirements specific to HTTP/1.1 from Section 7.2 to 10664 [HTTP/1.1] () 10666 * In Section 5.5, introduce the terms "singleton field" and "list- 10667 based field" (also - in various places - discuss what to do when a 10668 singleton field is received as a list) 10669 () 10671 * In Section 10.1.1, change the ABNF back to be a list of 10672 expectations, as defined in RFC 2616 () 10675 * In Section 6.6.2 (Trailer), Section 7.6.3 (Via), Section 7.8 10676 (Upgrade), Section 7.6.1 (Connection), Section 8.4 10677 (Content-Encoding), Section 8.5 (Content-Language), Section 10.1.1 10678 (Expect), Section 13.1.1 (If-Match), Section 13.1.2 10679 (If-None-Match), Section 12.5.2 (Accept-Charset), Section 12.5.4 10680 (Accept-Language), Section 12.5.5 (Vary), Section 11.6.1 10681 (WWW-Authenticate), and Section 11.7.1 (Proxy-Authenticate), 10682 adjust ABNF to allow empty lists () 10685 * In Section 9.3.1 and Section 17.9, provide a more nuanced 10686 explanation of sensitive data in GET-based forms and describe 10687 workarounds () 10689 * In Section 13.2, allow preconditions to be evaluated before the 10690 request content (if any) is processed () 10693 * In Section 6.3 and Section 6.5.2, allow for trailer fields in 10694 multiple trailer sections, depending on the HTTP version and 10695 framing in use, with processing being iterative as each section is 10696 received () 10698 * Moved definitions of "TE" and "Upgrade" from [HTTP/1.1] 10699 () 10701 * Moved 1.1-specific discussion of TLS to Messaging and rewrote 10702 Section 4.3.4 to refer to RFC6125 () 10705 * Moved definition of "Connection" from [HTTP/1.1] 10706 () 10708 C.13. Since draft-ietf-httpbis-semantics-11 10710 * The entire document has been reorganized, with no changes to 10711 content except editorial for the reorganization 10712 () 10714 * Move IANA Upgrade Token Registry instructions from [HTTP/1.1] 10715 () 10717 C.14. Since draft-ietf-httpbis-semantics-12 10719 * In Appendix "Acknowledgements" (Appendix "Acknowledgements"), 10720 added acks for the work since 2014 () 10723 * In Section 15.3.7, specifically require that a client check the 10724 206 response header fields to determine what ranges are enclosed, 10725 since it cannot assume they exactly match those requested 10726 () 10728 * In Section 16.3, explain why new fields need to be backwards- 10729 compatible () 10731 * In Section 5.3, constrain field combination to be within a section 10732 () 10734 * In Section 5.6.7, mention that caching relaxes date sensitivity 10735 () 10737 * In Section 18.4, moved "*" field registration into main table 10738 () 10740 * In Section 1.2, reference HTTP/0.9 () 10743 * In Section 9.3.4, clarify handling of unrecognized fields 10744 () 10746 * In Section 15.2, align language about bodies and trailers with 204 10747 and 304 () 10749 * Moved table of content codings into Section 18.6, moved table of 10750 range units into Section 18.7 () 10753 * In Section 6, add an abstract data type for message to help define 10754 semantics without being dependent on the specific structure of 10755 HTTP/1.1 () 10757 * In Section 8.8.2.2, relax arbitrary 60-second comparison limit 10758 () 10760 * In Section 7.2, add ":authority" pseudo-header to Host discussion 10761 and make section applicable to both () 10764 * In Section 18.4, note that this document updates [RFC3864] 10765 () 10767 * Moved transfer-coding ABNF from [HTTP/1.1] to Section 10.1.4 and 10768 replaced "t-ranking" ABNF by equivalent "weight" 10769 () 10771 * In Section 11.5, replace "canonical root URI" by "origin" 10772 () 10774 * In Section 10.1.1, remove obsolete note about a change in RFC 723x 10775 () 10777 * Changed to using "payload" when defining requirements about the 10778 data being conveyed within a message, instead of the terms 10779 "payload body" or "response body" or "representation body", since 10780 they often get confused with the HTTP/1.1 message body (which 10781 includes transfer coding) () 10784 * Rewrite definition of HEAD method () 10787 * In Section 13.1.5, fix an off-by-one bug about how many chars to 10788 consider when checking for etags () 10791 * In Section 15.1, clarify that "no reason phrase" is fine as well 10792 () 10794 * In Section 15.3.4, remove an obsolete reference to the Warning 10795 response header field () 10798 * In Section 15.5.9, rephrase prose about connection re-use 10799 () 10801 * In Section 14.2, potentially allow Range handling on methods other 10802 than GET () 10804 * In Section 18.3, remove redundant text about status code 418 10805 () 10807 * In Section 17.16.1, rewrite requirement to refer to "secured 10808 connection" () 10810 * Make reference to [TLS13] normative () 10813 C.15. Since draft-ietf-httpbis-semantics-13 10815 * In Section 12.5.1, remove the unused "accept parameters" 10816 () 10818 * In Section 1.2, mention that RFC 1945 describes HTTP/0.9 as well 10819 () 10821 * In Section 14.5, describe non-standard use of the Content-Range 10822 header field (Section 14.4) as a request modifier to perform a 10823 partial PUT () 10825 * In Section 15.5.20, import the 421 (Misdirected Request) status 10826 code from [HTTP/2] () 10829 * In Section 2.3, rephrase the actual recipient parsing requirements 10830 () 10832 * In Section 16.1.2, mention request target forms in considerations 10833 for new methods () 10835 * Changed to using "content" instead of "payload" or "payload data" 10836 to avoid confusion with the payload of version-specific messaging 10837 frames () 10839 * In Section 13.1.3, Section 13.1.4, and Section 13.1.5, specify 10840 evaluation in a way similar to other conditional header fields 10841 () 10843 * In Section 6.6.1, specify that recipients can replace an invalid 10844 Date header field value with the time received 10845 () 10847 C.16. Since draft-ietf-httpbis-semantics-14 10849 * In Section 5.5, relax prohibition of characters in field values to 10850 CR and NUL () 10852 * In Section 15, clarify that status code values outside the range 10853 100..599 are invalid, and recommend error handling 10854 () 10856 * In Section 2.2, replaced requirement on semantic conformance with 10857 permission to ignore/workaround implementation-specific failures 10858 () 10860 * Avoid the term "whitelist" () 10863 * In Section 9.3.8, remove the normative requirement to use the 10864 message/http media type () 10867 * In Section 7.6, discuss extensibility () 10870 * In Section 5.5, tighten the recommendation for characters in newly 10871 defined fields, making it consistent with obs-text 10872 () 10874 * In Section 5.5, leading/trailing whitespace removal is at time of 10875 use, not parsing () 10878 * In Section 6, clarify that HTTP self-descriptive messages have an 10879 exception in that the request must be understood in order to parse 10880 and interpret the response () 10883 * Remove "Canonicalization and Text Defaults" 10884 () 10886 * In Section 10.1.3, refine what can be sent in Referer, and when 10887 () 10889 * In Section 11.5, explain that the protection space is not defined 10890 without additional information () 10893 * Simplify description of reactive content negotiation in 10894 Section 12.2 () 10896 * In Section 8.3.2, remove the "charset" ABNF production, and 10897 clarify where charsets appear () 10900 * In Section 12.5.3, clarify that selection _between_ multiple 10901 acceptable codings is only relevant when they have the same 10902 purpose () 10904 * In Section 13, rewrite introduction, mentioning extensibility 10905 () 10907 * Throughout, be consistent about 'content coding' vs 'content- 10908 coding' () 10910 * In Section 9.3.6, clarify that the port is mandatory in a CONNECT 10911 request target () 10912 and that the tunnel begins after the header section 10913 () 10915 * In Section 6.5, remove mid-stream trailers 10916 () 10918 * In Section 3.3, clarify duplexing semantics 10919 () 10921 * In Section 3.3, explain the implications of statelessness more 10922 clearly () 10924 * In Section 8.6, be more explicit about invalid and incorrect 10925 values ( and 10926 ) 10928 * Move discussion of statelessness from Section 3.7 to Section 3.3 10929 () 10931 * In Section 15.2.2, clarify that the upgraded protocol is in effect 10932 after the 101 response () 10935 * In Section 9.3.6, state that data received after the headers of a 10936 CONNECT message is version-specific () 10939 * In Section 4.2.3, clarify how normalization works, and align with 10940 RF3986 () 10942 * In Section 6.6.2, note that the Trailer field can be used to 10943 discover deleted trailers () 10946 * Throughout, remove unneeded normative references to [HTTP/1.1] 10947 () 10949 * In Section 10.1.4, explicitly require listing in Connection 10950 () 10952 C.17. Since draft-ietf-httpbis-semantics-15 10954 * For [HTTP/3], add an RFC Editor note to rename to "RFCnnn" before 10955 publication () 10957 * In Section 9.3.2, align prose about content in HEAD requests with 10958 description of GET () 10961 * In Section 5.3, remove the restriction to non-empty field line 10962 values () 10964 * Add forward references to definition of OWS 10965 () 10967 * In Section 17.10, add a security consideration regarding 10968 application handling of field names () 10971 C.18. Since draft-ietf-httpbis-semantics-16 10973 This draft addresses mostly editorial issues raised during or past 10974 IETF Last Call; see for a summary. 10977 Furthermore: 10979 * In Section 15.3.7, reinstate 'to a request' 10980 () 10982 * Align Section 16.3.1 with Section 16.3.2.1 10983 () 10985 * In Section 14.3, clarify that Accept-Ranges can be sent by any 10986 server, remove "none" from the ABNF because it is now a reserved 10987 range unit, and allow the field to be sent in a trailer section 10988 while noting why that is much less useful than as a header field 10989 () 10991 * In Section 7.6.3, don't specify TCP () 10994 * In Section 6.4, explain the "Content-" prefix 10995 () 10997 * In Section 7.4, check all target URIs for scheme semantic 10998 mismatches () 11000 * In Section 9.3.1, Section 9.3.2, and Section 9.3.5, clarify 11001 (again) that sending content in a request for a method that does 11002 not define such content will not interoperate without prior 11003 agreement, even if it is parsed correctly, and cannot be relied 11004 upon by an origin server unless they control the entire request 11005 chain () 11007 C.19. Since draft-ietf-httpbis-semantics-17 11009 * Move ABNF for obs-text into Section 5.5 11010 () 11012 * In Section 6.4.1, note that response metadata can be relevant as 11013 well () 11015 * In Section 6.6.2, use the term "signature" througout and lower 11016 expectations on what Trailer indicates without a trailer section 11017 () 11019 * In Section 8.3, cleanup mime sniffing discussion 11020 () 11022 * In Section 10.1.4, add a forward reference to "weight" 11023 () 11025 * In Section 12.5.3, clarify that the examples contains multiple 11026 values; also remove obsolete HTTP/1.0 note about qvalues 11027 () 11029 * In Section 15.4, remove incorrect mention of Etag as request field 11030 () 11032 * Move text about obs-fold in message/http to [HTTP/1.1]; also note 11033 that LF is forbidden in field values just as CR and NUL 11034 () 11036 * In Section 7.7, properly refer to text that has moved to 11037 [HTTP/1.1] () 11039 * Rewrite description of validators and move cache-related aspects 11040 into [CACHING] () 11042 * In Section 12.5.5, rephrase description to be more explanatory 11043 () 11045 * In Section 13.2.2, clarify that a false If-Range means ignore the 11046 Range () 11048 * In Section 13.1.3 and Section 13.1.4, restore text about missing 11049 modification date () 11052 * In Section 5.6.1.1, avoid duplicate normative requirement 11053 () 11055 * In Section 8.8.2.1, reference 'Date' more visibly 11056 () 11058 * In Section 11.7.3, state that Proxy-Authentication-Info can be 11059 used as trailer () 11061 * In Section 15.4, slightly clarify history of redirect status codes 11062 () 11064 * In Section 16.3.1, fix requirements for provisional registrations 11065 () 11067 * In Section 4.3, explicitly refer to how this spec defines access 11068 to http or https resources () 11071 * In Section 6.6.1, make clock a defined term and use that 11072 definition throughout the spec () 11075 * In Section 13.1, make preconditions consistent on when they are 11076 required to be evaluated () 11079 * Throughout, disambiguate "selected representation" and "selected 11080 response" (now "chosen response") () 11083 C.20. Since draft-ietf-httpbis-semantics-18 11085 * In Section 12.5.1, align text about "q" parameter with recent 11086 changes to IANA media types registry, and instruct IANA to 11087 reference this document with respect to the "q" special case 11088 () 11090 * In Section 18.4, rephrase text about the relation with [RFC3864] 11091 () 11093 * In Section 3.7, avoid bare "for the sake of security" 11094 () 11096 * In Section 12.2, wordsmith future guidance on reactive negotiation 11097 () 11099 * In Section 15.4.2 and Section 15.4.9, improve text about automatic 11100 link-editing () 11102 * In Section 17, reference [URI] security considerations 11103 () 11105 Acknowledgements 11107 Aside from the current editors, the following individuals deserve 11108 special recognition for their contributions to early aspects of HTTP 11109 and its core specifications: Marc Andreessen, Tim Berners-Lee, Robert 11110 Cailliau, Daniel W. Connolly, Bob Denny, John Franks, Jim Gettys, 11111 Jean-François Groff, Phillip M. Hallam-Baker, Koen Holtman, Jeffery 11112 L. Hostetler, Shel Kaphan, Dave Kristol, Yves Lafon, Scott 11113 D. Lawrence, Paul J. Leach, Håkon W. Lie, Ari Luotonen, Larry 11114 Masinter, Rob McCool, Jeffrey C. Mogul, Lou Montulli, David Morris, 11115 Henrik Frystyk Nielsen, Dave Raggett, Eric Rescorla, Tony Sanders, 11116 Lawrence C. Stewart, Marc VanHeyningen, and Steve Zilles. 11118 This edition builds on the many contributions that went into past 11119 specifications of HTTP, including RFC 1945, RFC 2068, RFC 2145, RFC 11120 2616, RFC 2617, RFC 2818, RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 11121 7234, and RFC 7235. The acknowledgements within those documents 11122 still apply. 11124 Since 2014, the following contributors have helped improve this 11125 specification by reporting bugs, asking smart questions, drafting or 11126 reviewing text, and evaluating open issues: 11128 Alan Egerton, Alex Rousskov, Amichai Rothman, Amos Jeffries, Anders 11129 Kaseorg, Andreas Gebhardt, Anne van Kesteren, Armin Abfalterer, Aron 11130 Duby, Asanka Herath, Asbjørn Ulsberg, Asta Olofsson, Attila Gulyas, 11131 Austin Wright, Barry Pollard, Ben Burkert, Benjamin Kaduk, Björn 11132 Höhrmann, Brad Fitzpatrick, Chris Pacejo, Colin Bendell, Cory 11133 Benfield, Cory Nelson, Daisuke Miyakawa, Dale Worley, Daniel 11134 Stenberg, Danil Suits, David Benjamin, David Matson, David Schinazi, 11135 Дилян Палаузов (Dilyan Palauzov), Eric Anderson, Eric Rescorla, Éric 11136 Vyncke, Erik Kline, Erwin Pe, Etan Kissling, Evert Pot, Evgeny 11137 Vrublevsky, Florian Best, Francesca Palombini, Igor Lubashev, James 11138 Callahan, James Peach, Jeffrey Yasskin, Kalin Gyokov, Kannan Goundan, 11139 奥 一穂 (Kazuho Oku), Ken Murchison, Krzysztof Maczyński, Lars Eggert, 11140 Lucas Pardue, Martin Duke, Martin Dürst, Martin Thomson, Martynas 11141 Jusevičius, Matt Menke, Matthias Pigulla, Mattias Grenfeldt, Michael 11142 Osipov, Mike Bishop, Mike Pennisi, Mike Taylor, Mike West, Mohit 11143 Sethi, Murray Kucherawy, Nathaniel J. Smith, Nicholas Hurley, Nikita 11144 Prokhorov, Patrick McManus, Piotr Sikora, Poul-Henning Kamp, Rick van 11145 Rein, Robert Wilton, Roberto Polli, Roman Danyliw, Samuel Williams, 11146 Semyon Kholodnov, Simon Pieters, Simon Schüppel, Stefan Eissing, 11147 Taylor Hunt, Todd Greer, Tommy Pauly, Vasiliy Faronov, Vladimir 11148 Lashchev, Wenbo Zhu, William A. Rowe Jr., Willy Tarreau, Xingwei Liu, 11149 Yishuai Li, and Zaheduzzaman Sarker. 11151 Index 11153 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 11155 1 11157 100 Continue (status code) Section 15.2.1 11158 100-continue (expect value) Section 10.1.1 11159 101 Switching Protocols (status code) Section 15.2.2 11160 1xx Informational (status code class) Section 15.2 11162 2 11164 200 OK (status code) Section 15.3.1 11165 201 Created (status code) Section 15.3.2 11166 202 Accepted (status code) Section 15.3.3 11167 203 Non-Authoritative Information (status code) Section 15.3.4 11168 204 No Content (status code) Section 15.3.5 11169 205 Reset Content (status code) Section 15.3.6 11170 206 Partial Content (status code) Section 15.3.7 11171 2xx Successful (status code class) Section 15.3 11173 3 11175 300 Multiple Choices (status code) Section 15.4.1 11176 301 Moved Permanently (status code) Section 15.4.2 11177 302 Found (status code) Section 15.4.3 11178 303 See Other (status code) Section 15.4.4 11179 304 Not Modified (status code) Section 15.4.5 11180 305 Use Proxy (status code) Section 15.4.6 11181 306 (Unused) (status code) Section 15.4.7 11182 307 Temporary Redirect (status code) Section 15.4.8 11183 308 Permanent Redirect (status code) Section 15.4.9 11184 3xx Redirection (status code class) Section 15.4 11186 4 11188 400 Bad Request (status code) Section 15.5.1 11189 401 Unauthorized (status code) Section 15.5.2 11190 402 Payment Required (status code) Section 15.5.3 11191 403 Forbidden (status code) Section 15.5.4 11192 404 Not Found (status code) Section 15.5.5 11193 405 Method Not Allowed (status code) Section 15.5.6 11194 406 Not Acceptable (status code) Section 15.5.7 11195 407 Proxy Authentication Required (status code) Section 15.5.8 11196 408 Request Timeout (status code) Section 15.5.9 11197 409 Conflict (status code) Section 15.5.10 11198 410 Gone (status code) Section 15.5.11 11199 411 Length Required (status code) Section 15.5.12 11200 412 Precondition Failed (status code) Section 15.5.13 11201 413 Content Too Large (status code) Section 15.5.14 11202 414 URI Too Long (status code) Section 15.5.15 11203 415 Unsupported Media Type (status code) Section 15.5.16 11204 416 Range Not Satisfiable (status code) Section 15.5.17 11205 417 Expectation Failed (status code) Section 15.5.18 11206 418 (Unused) (status code) Section 15.5.19 11207 421 Misdirected Request (status code) Section 15.5.20 11208 422 Unprocessable Content (status code) Section 15.5.21 11209 426 Upgrade Required (status code) Section 15.5.22 11210 4xx Client Error (status code class) Section 15.5 11212 5 11214 500 Internal Server Error (status code) Section 15.6.1 11215 501 Not Implemented (status code) Section 15.6.2 11216 502 Bad Gateway (status code) Section 15.6.3 11217 503 Service Unavailable (status code) Section 15.6.4 11218 504 Gateway Timeout (status code) Section 15.6.5 11219 505 HTTP Version Not Supported (status code) Section 15.6.6 11220 5xx Server Error (status code class) Section 15.6 11222 A 11224 Accept header field Section 12.5.1 11225 Accept-Charset header field Section 12.5.2 11226 Accept-Encoding header field Section 12.5.3 11227 Accept-Language header field Section 12.5.4 11228 Accept-Ranges header field Section 14.3 11229 Allow header field Section 10.2.1 11230 Authentication-Info header field Section 11.6.3 11231 Authorization header field Section 11.6.2 11232 accelerator Section 3.7, Paragraph 6 11233 authoritative response Section 17.1 11235 B 11237 browser Section 3.5 11239 C 11241 CONNECT method Section 9.3.6 11242 Connection header field Section 7.6.1 11243 Content-Encoding header field Section 8.4 11244 Content-Language header field Section 8.5 11245 Content-Length header field Section 8.6 11246 Content-Location header field Section 8.7 11247 Content-MD5 header field Section 18.4, Paragraph 9 11248 Content-Range header field Section 14.4; Section 14.5 11249 Content-Type header field Section 8.3 11250 cache Section 3.8 11251 cacheable Section 3.8, Paragraph 4 11252 client Section 3.3 11253 clock Section 5.6.7 11254 complete Section 6.1 11255 compress (Coding Format) Section 8.4.1.1 11256 compress (content coding) Section 8.4.1 11257 conditional request Section 13 11258 connection Section 3.3 11259 content Section 6.4 11260 content coding Section 8.4.1 11261 content negotiation Section 1.3, Paragraph 4 11262 control data Section 6.2 11264 D 11266 DELETE method Section 9.3.5 11267 Date header field Section 6.6.1 11268 Delimiters Section 5.6.2, Paragraph 3 11269 deflate (Coding Format) Section 8.4.1.2 11270 deflate (content coding) Section 8.4.1 11271 downstream Section 3.7, Paragraph 4 11273 E 11275 ETag field Section 8.8.3 11276 Expect header field Section 10.1.1 11277 effective request URI Section 7.1, Paragraph 8.1 11279 F 11281 Fields 11282 * Section 18.4, Paragraph 8 11283 Accept Section 12.5.1 11284 Accept-Charset Section 12.5.2 11285 Accept-Encoding Section 12.5.3 11286 Accept-Language Section 12.5.4 11287 Accept-Ranges Section 14.3 11288 Allow Section 10.2.1 11289 Authentication-Info Section 11.6.3 11290 Authorization Section 11.6.2 11291 Connection Section 7.6.1 11292 Content-Encoding Section 8.4 11293 Content-Language Section 8.5 11294 Content-Length Section 8.6 11295 Content-Location Section 8.7 11296 Content-MD5 Section 18.4, Paragraph 9 11297 Content-Range Section 14.4; Section 14.5 11298 Content-Type Section 8.3 11299 Date Section 6.6.1 11300 ETag Section 8.8.3 11301 Expect Section 10.1.1 11302 From Section 10.1.2 11303 Host Section 7.2 11304 If-Match Section 13.1.1 11305 If-Modified-Since Section 13.1.3 11306 If-None-Match Section 13.1.2 11307 If-Range Section 13.1.5 11308 If-Unmodified-Since Section 13.1.4 11309 Last-Modified Section 8.8.2 11310 Location Section 10.2.2 11311 Max-Forwards Section 7.6.2 11312 Proxy-Authenticate Section 11.7.1 11313 Proxy-Authentication-Info Section 11.7.3 11314 Proxy-Authorization Section 11.7.2 11315 Range Section 14.2 11316 Referer Section 10.1.3 11317 Retry-After Section 10.2.3 11318 Server Section 10.2.4 11319 TE Section 10.1.4 11320 Trailer Section 6.6.2 11321 Upgrade Section 7.8 11322 User-Agent Section 10.1.5 11323 Vary Section 12.5.5 11324 Via Section 7.6.3 11325 WWW-Authenticate Section 11.6.1 11326 Fragment Identifiers Section 4.2.5 11327 From header field Section 10.1.2 11328 field Section 5; Section 6.3 11329 field line Section 5.2, Paragraph 1 11330 field line value Section 5.2, Paragraph 1 11331 field name Section 5.2, Paragraph 1 11332 field value Section 5.2, Paragraph 2 11334 G 11336 GET method Section 9.3.1 11337 Grammar 11338 ALPHA Section 2.1 11339 Accept Section 12.5.1 11340 Accept-Charset Section 12.5.2 11341 Accept-Encoding Section 12.5.3 11342 Accept-Language Section 12.5.4 11343 Accept-Ranges Section 14.3 11344 Allow Section 10.2.1 11345 Authentication-Info Section 11.6.3 11346 Authorization Section 11.6.2 11347 BWS Section 5.6.3 11348 CR Section 2.1 11349 CRLF Section 2.1 11350 CTL Section 2.1 11351 Connection Section 7.6.1 11352 Content-Encoding Section 8.4 11353 Content-Language Section 8.5 11354 Content-Length Section 8.6 11355 Content-Location Section 8.7 11356 Content-Range Section 14.4 11357 Content-Type Section 8.3 11358 DIGIT Section 2.1 11359 DQUOTE Section 2.1 11360 Date Section 6.6.1 11361 ETag Section 8.8.3 11362 Expect Section 10.1.1 11363 From Section 10.1.2 11364 GMT Section 5.6.7 11365 HEXDIG Section 2.1 11366 HTAB Section 2.1 11367 HTTP-date Section 5.6.7 11368 Host Section 7.2 11369 IMF-fixdate Section 5.6.7 11370 If-Match Section 13.1.1 11371 If-Modified-Since Section 13.1.3 11372 If-None-Match Section 13.1.2 11373 If-Range Section 13.1.5 11374 If-Unmodified-Since Section 13.1.4 11375 LF Section 2.1 11376 Last-Modified Section 8.8.2 11377 Location Section 10.2.2 11378 Max-Forwards Section 7.6.2 11379 OCTET Section 2.1 11380 OWS Section 5.6.3 11381 Proxy-Authenticate Section 11.7.1 11382 Proxy-Authentication-Info Section 11.7.3 11383 Proxy-Authorization Section 11.7.2 11384 RWS Section 5.6.3 11385 Range Section 14.2 11386 Referer Section 10.1.3 11387 Retry-After Section 10.2.3 11388 SP Section 2.1 11389 Server Section 10.2.4 11390 TE Section 10.1.4 11391 Trailer Section 6.6.2 11392 URI-reference Section 4.1 11393 Upgrade Section 7.8 11394 User-Agent Section 10.1.5 11395 VCHAR Section 2.1 11396 Vary Section 12.5.5 11397 Via Section 7.6.3 11398 WWW-Authenticate Section 11.6.1 11399 absolute-URI Section 4.1 11400 absolute-path Section 4.1 11401 acceptable-ranges Section 14.3 11402 asctime-date Section 5.6.7 11403 auth-param Section 11.2 11404 auth-scheme Section 11.1 11405 authority Section 4.1 11406 challenge Section 11.3 11407 codings Section 12.5.3 11408 comment Section 5.6.5 11409 complete-length Section 14.4 11410 connection-option Section 7.6.1 11411 content-coding Section 8.4.1 11412 credentials Section 11.4 11413 ctext Section 5.6.5 11414 date1 Section 5.6.7 11415 day Section 5.6.7 11416 day-name Section 5.6.7 11417 day-name-l Section 5.6.7 11418 delay-seconds Section 10.2.3 11419 entity-tag Section 8.8.3 11420 etagc Section 8.8.3 11421 field-content Section 5.5 11422 field-name Section 5.1; Section 6.6.2 11423 field-value Section 5.5 11424 field-vchar Section 5.5 11425 first-pos Section 14.1.1; Section 14.4 11426 hour Section 5.6.7 11427 http-URI Section 4.2.1 11428 https-URI Section 4.2.2 11429 incl-range Section 14.4 11430 int-range Section 14.1.1 11431 language-range Section 12.5.4 11432 language-tag Section 8.5.1 11433 last-pos Section 14.1.1; Section 14.4 11434 media-range Section 12.5.1 11435 media-type Section 8.3.1 11436 method Section 9.1 11437 minute Section 5.6.7 11438 month Section 5.6.7 11439 obs-date Section 5.6.7 11440 obs-text Section 5.5 11441 opaque-tag Section 8.8.3 11442 other-range Section 14.1.1 11443 parameter Section 5.6.6 11444 parameter-name Section 5.6.6 11445 parameter-value Section 5.6.6 11446 parameters Section 5.6.6 11447 partial-URI Section 4.1 11448 port Section 4.1 11449 product Section 10.1.5 11450 product-version Section 10.1.5 11451 protocol-name Section 7.6.3 11452 protocol-version Section 7.6.3 11453 pseudonym Section 7.6.3 11454 qdtext Section 5.6.4 11455 query Section 4.1 11456 quoted-pair Section 5.6.4 11457 quoted-string Section 5.6.4 11458 qvalue Section 12.4.2 11459 range-resp Section 14.4 11460 range-set Section 14.1.1 11461 range-spec Section 14.1.1 11462 range-unit Section 14.1 11463 ranges-specifier Section 14.1.1 11464 received-by Section 7.6.3 11465 received-protocol Section 7.6.3 11466 rfc850-date Section 5.6.7 11467 second Section 5.6.7 11468 segment Section 4.1 11469 subtype Section 8.3.1 11470 suffix-length Section 14.1.1 11471 suffix-range Section 14.1.1 11472 t-codings Section 10.1.4 11473 tchar Section 5.6.2 11474 time-of-day Section 5.6.7 11475 token Section 5.6.2 11476 token68 Section 11.2 11477 transfer-coding Section 10.1.4 11478 transfer-parameter Section 10.1.4 11479 type Section 8.3.1 11480 unsatisfied-range Section 14.4 11481 uri-host Section 4.1 11482 weak Section 8.8.3 11483 weight Section 12.4.2 11484 year Section 5.6.7 11485 gateway Section 3.7, Paragraph 6 11486 gzip (Coding Format) Section 8.4.1.3 11487 gzip (content coding) Section 8.4.1 11489 H 11491 HEAD method Section 9.3.2 11492 Header Fields 11493 Accept Section 12.5.1 11494 Accept-Charset Section 12.5.2 11495 Accept-Encoding Section 12.5.3 11496 Accept-Language Section 12.5.4 11497 Accept-Ranges Section 14.3 11498 Allow Section 10.2.1 11499 Authentication-Info Section 11.6.3 11500 Authorization Section 11.6.2 11501 Connection Section 7.6.1 11502 Content-Encoding Section 8.4 11503 Content-Language Section 8.5 11504 Content-Length Section 8.6 11505 Content-Location Section 8.7 11506 Content-MD5 Section 18.4, Paragraph 9 11507 Content-Range Section 14.4; Section 14.5 11508 Content-Type Section 8.3 11509 Date Section 6.6.1 11510 ETag Section 8.8.3 11511 Expect Section 10.1.1 11512 From Section 10.1.2 11513 Host Section 7.2 11514 If-Match Section 13.1.1 11515 If-Modified-Since Section 13.1.3 11516 If-None-Match Section 13.1.2 11517 If-Range Section 13.1.5 11518 If-Unmodified-Since Section 13.1.4 11519 Last-Modified Section 8.8.2 11520 Location Section 10.2.2 11521 Max-Forwards Section 7.6.2 11522 Proxy-Authenticate Section 11.7.1 11523 Proxy-Authentication-Info Section 11.7.3 11524 Proxy-Authorization Section 11.7.2 11525 Range Section 14.2 11526 Referer Section 10.1.3 11527 Retry-After Section 10.2.3 11528 Server Section 10.2.4 11529 TE Section 10.1.4 11530 Trailer Section 6.6.2 11531 Upgrade Section 7.8 11532 User-Agent Section 10.1.5 11533 Vary Section 12.5.5 11534 Via Section 7.6.3 11535 WWW-Authenticate Section 11.6.1 11536 Host header field Section 7.2 11537 header section Section 6.3 11538 http URI scheme Section 4.2.1 11539 https URI scheme Section 4.2.2 11541 I 11543 If-Match header field Section 13.1.1 11544 If-Modified-Since header field Section 13.1.3 11545 If-None-Match header field Section 13.1.2 11546 If-Range header field Section 13.1.5 11547 If-Unmodified-Since header field Section 13.1.4 11548 idempotent Section 9.2.2 11549 inbound Section 3.7, Paragraph 4 11550 incomplete Section 6.1 11551 interception proxy Section 3.7, Paragraph 10 11552 intermediary Section 3.7 11554 L 11556 Last-Modified header field Section 8.8.2 11557 Location header field Section 10.2.2 11558 list-based field Section 5.5, Paragraph 7 11560 M 11562 Max-Forwards header field Section 7.6.2 11563 Media Type 11564 multipart/byteranges Section 14.6 11565 multipart/x-byteranges Section 14.6, Paragraph 4, Item 3 11566 Method 11567 * Section 18.2, Paragraph 3 11568 CONNECT Section 9.3.6 11569 DELETE Section 9.3.5 11570 GET Section 9.3.1 11571 HEAD Section 9.3.2 11572 OPTIONS Section 9.3.7 11573 POST Section 9.3.3 11574 PUT Section 9.3.4 11575 TRACE Section 9.3.8 11576 message Section 3.4; Section 6 11577 message abstraction Section 6 11578 messages Section 3.4 11579 metadata Section 8.8 11580 multipart/byteranges Media Type Section 14.6 11581 multipart/x-byteranges Media Type Section 14.6, Paragraph 4, 11582 Item 3 11584 N 11586 non-transforming proxy Section 7.7 11588 O 11590 OPTIONS method Section 9.3.7 11591 Origin Section 11.5 11592 origin Section 4.3.1 11593 origin server Section 3.6 11594 outbound Section 3.7, Paragraph 4 11596 P 11598 POST method Section 9.3.3 11599 PUT method Section 9.3.4 11600 Protection Space Section 11.5 11601 Proxy-Authenticate header field Section 11.7.1 11602 Proxy-Authentication-Info header field Section 11.7.3 11603 Proxy-Authorization header field Section 11.7.2 11604 phishing Section 17.1 11605 proxy Section 3.7, Paragraph 5 11607 R 11609 Range header field Section 14.2 11610 Realm Section 11.5 11611 Referer header field Section 10.1.3 11612 Retry-After header field Section 10.2.3 11613 recipient Section 3.4 11614 representation Section 3.2 11615 request Section 3.4 11616 request target Section 7.1 11617 resource Section 3.1; Section 4 11618 response Section 3.4 11619 reverse proxy Section 3.7, Paragraph 6 11621 S 11623 Server header field Section 10.2.4 11624 Status Code Section 15 11625 Status Codes 11626 Final Section 15, Paragraph 7 11627 Informational Section 15, Paragraph 7 11628 Interim Section 15, Paragraph 7 11629 Status Codes Classes 11630 1xx Informational Section 15.2 11631 2xx Successful Section 15.3 11632 3xx Redirection Section 15.4 11633 4xx Client Error Section 15.5 11634 5xx Server Error Section 15.6 11635 safe Section 9.2.1 11636 secured Section 4.2.2 11637 selected representation Section 3.2, Paragraph 4; Section 8.8; 11638 Section 13.1 11639 self-descriptive Section 6 11640 sender Section 3.4 11641 server Section 3.3 11642 singleton field Section 5.5, Paragraph 6 11643 spider Section 3.5 11645 T 11647 TE header field Section 10.1.4 11648 TRACE method Section 9.3.8 11649 Trailer Fields 11650 ETag Section 8.8.3 11651 Trailer header field Section 6.6.2 11652 target URI Section 7.1 11653 target resource Section 7.1 11654 trailer fields Section 6.5 11655 trailer section Section 6.5 11656 trailers Section 6.5 11657 transforming proxy Section 7.7 11658 transparent proxy Section 3.7, Paragraph 10 11659 tunnel Section 3.7, Paragraph 8 11661 U 11663 URI Section 4 11664 origin Section 4.3.1 11665 URI reference Section 4.1 11666 URI scheme 11667 http Section 4.2.1 11668 https Section 4.2.2 11669 Upgrade header field Section 7.8 11670 User-Agent header field Section 10.1.5 11671 upstream Section 3.7, Paragraph 4 11672 user agent Section 3.5 11674 V 11676 Vary header field Section 12.5.5 11677 Via header field Section 7.6.3 11678 validator Section 8.8 11679 strong Section 8.8.1 11680 weak Section 8.8.1 11682 W 11684 WWW-Authenticate header field Section 11.6.1 11686 X 11688 x-compress (content coding) Section 8.4.1 11689 x-gzip (content coding) Section 8.4.1 11691 Authors' Addresses 11693 Roy T. Fielding (editor) 11694 Adobe 11695 345 Park Ave 11696 San Jose, CA 95110 11697 United States of America 11699 Email: fielding@gbiv.com 11700 URI: https://roy.gbiv.com/ 11702 Mark Nottingham (editor) 11703 Fastly 11704 Prahran VIC 11705 Australia 11707 Email: mnot@mnot.net 11708 URI: https://www.mnot.net/ 11710 Julian Reschke (editor) 11711 greenbytes GmbH 11712 Hafenweg 16 11713 48155 Münster 11714 Germany 11716 Email: julian.reschke@greenbytes.de 11717 URI: https://greenbytes.de/tech/webdav/