idnits 2.17.1 draft-ietf-httpbis-semantics-14.txt: -(10435): 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 9 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 5 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. -- The draft header indicates that this document obsoletes RFC7230, but the abstract doesn't seem to directly say this. It does mention RFC7230 though, so this could be OK. -- The abstract seems to indicate that this document obsoletes RFC7615, but the header doesn't have an 'Obsoletes:' line to match this. -- The abstract seems to indicate that this document obsoletes RFC7538, but the header doesn't have an 'Obsoletes:' line to match this. -- The abstract seems to indicate that this document obsoletes RFC7694, but the header doesn't have an 'Obsoletes:' line to match this. -- The draft header indicates that this document updates RFC3864, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 6685 has weird spacing: '... method resp...' == Line 8678 has weird spacing: '... yes yes...' == Line 8679 has weird spacing: '... yes yes...' == Line 8680 has weird spacing: '...S yes yes...' == Line 8683 has weird spacing: '... yes yes...' == (1 more instance...) (Using the creation date from RFC3864, updated by this document, for RFC5378 checks: 2001-09-27) -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 13, 2021) is 1198 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 9117, but no explicit reference was found in the text == Unused Reference: 'RFC7617' is defined on line 9262, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-cache-14 -- Possible downref: Normative reference to a draft: ref. 'Caching' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-messaging-14 -- Possible downref: Normative reference to a draft: ref. 'Messaging' ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Downref: Normative reference to an Informational RFC: RFC 1950 ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Downref: Normative reference to an Informational RFC: RFC 1952 ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' -- Possible downref: Non-RFC (?) normative reference: ref. 'Welch' -- Duplicate reference: RFC2978, mentioned in 'Err5433', was also mentioned in 'Err1912'. == Outdated reference: A later version (-34) exists of draft-ietf-quic-http-33 -- Obsolete informational reference (is this intentional?): RFC 2068 (Obsoleted by RFC 2616) -- Obsolete informational reference (is this intentional?): RFC 2145 (Obsoleted by RFC 7230) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Duplicate reference: RFC2978, mentioned in 'RFC2978', was also mentioned in 'Err5433'. -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7232 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7233 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7235 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7538 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) -- Obsolete informational reference (is this intentional?): RFC 7615 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7694 (Obsoleted by RFC 9110) Summary: 5 errors (**), 0 flaws (~~), 14 warnings (==), 28 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP Working Group R. Fielding, Ed. 3 Internet-Draft Adobe 4 Obsoletes: 2818, 7230, 7231, 7232, 7233, 7235, M. Nottingham, Ed. 5 7538, 7615, 7694 (if approved) Fastly 6 Updates: 3864 (if approved) J. Reschke, Ed. 7 Intended status: Standards Track greenbytes 8 Expires: July 17, 2021 January 13, 2021 10 HTTP Semantics 11 draft-ietf-httpbis-semantics-14 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 obsoletes RFC 2818, RFC 7231, RFC 7232, RFC 7233, RFC 24 7235, RFC 7538, RFC 7615, RFC 7694, and portions of RFC 7230. 26 Editorial Note 28 This note is to be removed before publishing as an RFC. 30 Discussion of this draft takes place on the HTTP working group 31 mailing list (ietf-http-wg@w3.org), which is archived at 32 . 34 Working Group information can be found at ; 35 source code and issues list for this draft can be found at 36 . 38 The changes in this draft are summarized in Appendix C.15. 40 Status of This Memo 42 This Internet-Draft is submitted in full conformance with the 43 provisions of BCP 78 and BCP 79. 45 Internet-Drafts are working documents of the Internet Engineering 46 Task Force (IETF). Note that other groups may also distribute 47 working documents as Internet-Drafts. The list of current Internet- 48 Drafts is at https://datatracker.ietf.org/drafts/current/. 50 Internet-Drafts are draft documents valid for a maximum of six months 51 and may be updated, replaced, or obsoleted by other documents at any 52 time. It is inappropriate to use Internet-Drafts as reference 53 material or to cite them other than as "work in progress." 55 This Internet-Draft will expire on July 17, 2021. 57 Copyright Notice 59 Copyright (c) 2021 IETF Trust and the persons identified as the 60 document authors. All rights reserved. 62 This document is subject to BCP 78 and the IETF Trust's Legal 63 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 64 license-info) in effect on the date of publication of this document. 65 Please review these documents carefully, as they describe your rights 66 and restrictions with respect to this document. Code Components 67 extracted from this document must include Simplified BSD License text 68 as described in Section 4.e of the Trust Legal Provisions and are 69 provided without warranty as described in the Simplified BSD License. 71 This document may contain material from IETF Documents or IETF 72 Contributions published or made publicly available before November 73 10, 2008. The person(s) controlling the copyright in some of this 74 material may not have granted the IETF Trust the right to allow 75 modifications of such material outside the IETF Standards Process. 76 Without obtaining an adequate license from the person(s) controlling 77 the copyright in such materials, this document may not be modified 78 outside the IETF Standards Process, and derivative works of it may 79 not be created outside the IETF Standards Process, except to format 80 it for publication as an RFC or to translate it into languages other 81 than English. 83 Table of Contents 85 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 9 86 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 9 87 1.2. History and Evolution . . . . . . . . . . . . . . . . . . 10 88 1.3. Core Semantics . . . . . . . . . . . . . . . . . . . . . 10 89 1.4. Specifications Obsoleted by this Document . . . . . . . . 11 90 2. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 12 91 2.1. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 12 92 2.2. Requirements Notation . . . . . . . . . . . . . . . . . . 12 93 2.3. Length Requirements . . . . . . . . . . . . . . . . . . . 13 94 2.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 14 95 2.5. Protocol Version . . . . . . . . . . . . . . . . . . . . 14 96 3. Terminology and Core Concepts . . . . . . . . . . . . . . . . 15 97 3.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 15 98 3.2. Representations . . . . . . . . . . . . . . . . . . . . . 16 99 3.3. Connections, Clients and Servers . . . . . . . . . . . . 16 100 3.4. Messages . . . . . . . . . . . . . . . . . . . . . . . . 17 101 3.5. User Agents . . . . . . . . . . . . . . . . . . . . . . . 17 102 3.6. Origin Server . . . . . . . . . . . . . . . . . . . . . . 18 103 3.7. Intermediaries . . . . . . . . . . . . . . . . . . . . . 18 104 3.8. Caches . . . . . . . . . . . . . . . . . . . . . . . . . 20 105 3.9. Example Message Exchange . . . . . . . . . . . . . . . . 21 106 4. Identifiers in HTTP . . . . . . . . . . . . . . . . . . . . . 22 107 4.1. URI References . . . . . . . . . . . . . . . . . . . . . 22 108 4.2. HTTP-Related URI Schemes . . . . . . . . . . . . . . . . 23 109 4.2.1. http URI Scheme . . . . . . . . . . . . . . . . . . . 23 110 4.2.2. https URI Scheme . . . . . . . . . . . . . . . . . . 24 111 4.2.3. http(s) Normalization and Comparison . . . . . . . . 25 112 4.2.4. Deprecation of userinfo in http(s) URIs . . . . . . . 25 113 4.2.5. http(s) References with Fragment Identifiers . . . . 26 114 4.3. Authoritative Access . . . . . . . . . . . . . . . . . . 26 115 4.3.1. URI Origin . . . . . . . . . . . . . . . . . . . . . 26 116 4.3.2. http origins . . . . . . . . . . . . . . . . . . . . 27 117 4.3.3. https origins . . . . . . . . . . . . . . . . . . . . 28 118 4.3.4. https certificate verification . . . . . . . . . . . 29 119 5. Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 120 5.1. Field Names . . . . . . . . . . . . . . . . . . . . . . . 30 121 5.2. Field Lines and Combined Field Value . . . . . . . . . . 31 122 5.3. Field Order . . . . . . . . . . . . . . . . . . . . . . . 31 123 5.4. Field Limits . . . . . . . . . . . . . . . . . . . . . . 32 124 5.5. Field Values . . . . . . . . . . . . . . . . . . . . . . 33 125 5.6. Common Rules for Defining Field Values . . . . . . . . . 35 126 5.6.1. Lists (#rule ABNF Extension) . . . . . . . . . . . . 35 127 5.6.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 36 128 5.6.3. Whitespace . . . . . . . . . . . . . . . . . . . . . 36 129 5.6.4. Quoted Strings . . . . . . . . . . . . . . . . . . . 37 130 5.6.5. Comments . . . . . . . . . . . . . . . . . . . . . . 38 131 5.6.6. Parameters . . . . . . . . . . . . . . . . . . . . . 38 132 5.6.7. Date/Time Formats . . . . . . . . . . . . . . . . . . 38 133 6. Message Abstraction . . . . . . . . . . . . . . . . . . . . . 40 134 6.1. Framing and Completeness . . . . . . . . . . . . . . . . 41 135 6.2. Control Data . . . . . . . . . . . . . . . . . . . . . . 42 136 6.3. Header Fields . . . . . . . . . . . . . . . . . . . . . . 43 137 6.4. Content . . . . . . . . . . . . . . . . . . . . . . . . . 43 138 6.4.1. Content Semantics . . . . . . . . . . . . . . . . . . 44 139 6.4.2. Identifying Content . . . . . . . . . . . . . . . . . 45 140 6.5. Trailer Fields . . . . . . . . . . . . . . . . . . . . . 46 141 6.5.1. Limitations on use of Trailers . . . . . . . . . . . 46 142 6.5.2. Processing Trailer Fields . . . . . . . . . . . . . . 47 143 7. Routing HTTP Messages . . . . . . . . . . . . . . . . . . . . 48 144 7.1. Determining the Target Resource . . . . . . . . . . . . . 48 145 7.2. Host and :authority . . . . . . . . . . . . . . . . . . . 49 146 7.3. Routing Inbound Requests . . . . . . . . . . . . . . . . 50 147 7.3.1. To a Cache . . . . . . . . . . . . . . . . . . . . . 50 148 7.3.2. To a Proxy . . . . . . . . . . . . . . . . . . . . . 50 149 7.3.3. To the Origin . . . . . . . . . . . . . . . . . . . . 50 150 7.4. Rejecting Misdirected Requests . . . . . . . . . . . . . 50 151 7.5. Response Correlation . . . . . . . . . . . . . . . . . . 51 152 7.6. Message Forwarding . . . . . . . . . . . . . . . . . . . 51 153 7.6.1. Connection . . . . . . . . . . . . . . . . . . . . . 51 154 7.6.2. Max-Forwards . . . . . . . . . . . . . . . . . . . . 53 155 7.6.3. Via . . . . . . . . . . . . . . . . . . . . . . . . . 54 156 7.7. Message Transformations . . . . . . . . . . . . . . . . . 55 157 7.8. Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . 56 158 8. Representation Data and Metadata . . . . . . . . . . . . . . 59 159 8.1. Representation Data . . . . . . . . . . . . . . . . . . . 59 160 8.2. Representation Metadata . . . . . . . . . . . . . . . . . 59 161 8.3. Content-Type . . . . . . . . . . . . . . . . . . . . . . 59 162 8.3.1. Media Type . . . . . . . . . . . . . . . . . . . . . 60 163 8.3.2. Charset . . . . . . . . . . . . . . . . . . . . . . . 61 164 8.3.3. Canonicalization and Text Defaults . . . . . . . . . 61 165 8.3.4. Multipart Types . . . . . . . . . . . . . . . . . . . 62 166 8.4. Content-Encoding . . . . . . . . . . . . . . . . . . . . 62 167 8.4.1. Content Codings . . . . . . . . . . . . . . . . . . . 63 168 8.5. Content-Language . . . . . . . . . . . . . . . . . . . . 64 169 8.5.1. Language Tags . . . . . . . . . . . . . . . . . . . . 65 170 8.6. Content-Length . . . . . . . . . . . . . . . . . . . . . 66 171 8.7. Content-Location . . . . . . . . . . . . . . . . . . . . 67 172 8.8. Validator Fields . . . . . . . . . . . . . . . . . . . . 69 173 8.8.1. Weak versus Strong . . . . . . . . . . . . . . . . . 70 174 8.8.2. Last-Modified . . . . . . . . . . . . . . . . . . . . 71 175 8.8.3. ETag . . . . . . . . . . . . . . . . . . . . . . . . 73 176 8.8.4. When to Use Entity-Tags and Last-Modified Dates . . . 77 177 9. Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 178 9.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 77 179 9.2. Common Method Properties . . . . . . . . . . . . . . . . 79 180 9.2.1. Safe Methods . . . . . . . . . . . . . . . . . . . . 80 181 9.2.2. Idempotent Methods . . . . . . . . . . . . . . . . . 81 182 9.2.3. Methods and Caching . . . . . . . . . . . . . . . . . 82 183 9.3. Method Definitions . . . . . . . . . . . . . . . . . . . 82 184 9.3.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 82 185 9.3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 83 186 9.3.3. POST . . . . . . . . . . . . . . . . . . . . . . . . 84 187 9.3.4. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 85 188 9.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 88 189 9.3.6. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 89 190 9.3.7. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 90 191 9.3.8. TRACE . . . . . . . . . . . . . . . . . . . . . . . . 91 192 10. Message Context . . . . . . . . . . . . . . . . . . . . . . . 92 193 10.1. Request Context Fields . . . . . . . . . . . . . . . . . 92 194 10.1.1. Expect . . . . . . . . . . . . . . . . . . . . . . . 92 195 10.1.2. From . . . . . . . . . . . . . . . . . . . . . . . . 94 196 10.1.3. Referer . . . . . . . . . . . . . . . . . . . . . . 95 197 10.1.4. TE . . . . . . . . . . . . . . . . . . . . . . . . . 96 198 10.1.5. Trailer . . . . . . . . . . . . . . . . . . . . . . 97 199 10.1.6. User-Agent . . . . . . . . . . . . . . . . . . . . . 97 200 10.2. Response Context Fields . . . . . . . . . . . . . . . . 98 201 10.2.1. Allow . . . . . . . . . . . . . . . . . . . . . . . 99 202 10.2.2. Date . . . . . . . . . . . . . . . . . . . . . . . . 99 203 10.2.3. Location . . . . . . . . . . . . . . . . . . . . . . 100 204 10.2.4. Retry-After . . . . . . . . . . . . . . . . . . . . 102 205 10.2.5. Server . . . . . . . . . . . . . . . . . . . . . . . 102 206 11. HTTP Authentication . . . . . . . . . . . . . . . . . . . . . 103 207 11.1. Authentication Scheme . . . . . . . . . . . . . . . . . 103 208 11.2. Authentication Parameters . . . . . . . . . . . . . . . 103 209 11.3. Challenge and Response . . . . . . . . . . . . . . . . . 104 210 11.4. Credentials . . . . . . . . . . . . . . . . . . . . . . 105 211 11.5. Establishing a Protection Space (Realm) . . . . . . . . 105 212 11.6. Authenticating Users to Origin Servers . . . . . . . . . 106 213 11.6.1. WWW-Authenticate . . . . . . . . . . . . . . . . . . 106 214 11.6.2. Authorization . . . . . . . . . . . . . . . . . . . 107 215 11.6.3. Authentication-Info . . . . . . . . . . . . . . . . 108 216 11.7. Authenticating Clients to Proxies . . . . . . . . . . . 108 217 11.7.1. Proxy-Authenticate . . . . . . . . . . . . . . . . . 108 218 11.7.2. Proxy-Authorization . . . . . . . . . . . . . . . . 109 219 11.7.3. Proxy-Authentication-Info . . . . . . . . . . . . . 109 220 12. Content Negotiation . . . . . . . . . . . . . . . . . . . . . 110 221 12.1. Proactive Negotiation . . . . . . . . . . . . . . . . . 111 222 12.2. Reactive Negotiation . . . . . . . . . . . . . . . . . . 112 223 12.3. Request Content Negotiation . . . . . . . . . . . . . . 113 224 12.4. Content Negotiation Field Features . . . . . . . . . . . 113 225 12.4.1. Absence . . . . . . . . . . . . . . . . . . . . . . 113 226 12.4.2. Quality Values . . . . . . . . . . . . . . . . . . . 114 227 12.4.3. Wildcard Values . . . . . . . . . . . . . . . . . . 114 228 12.5. Content Negotiation Fields . . . . . . . . . . . . . . . 114 229 12.5.1. Accept . . . . . . . . . . . . . . . . . . . . . . . 115 230 12.5.2. Accept-Charset . . . . . . . . . . . . . . . . . . . 117 231 12.5.3. Accept-Encoding . . . . . . . . . . . . . . . . . . 118 232 12.5.4. Accept-Language . . . . . . . . . . . . . . . . . . 119 233 12.5.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . 121 234 13. Conditional Requests . . . . . . . . . . . . . . . . . . . . 122 235 13.1. Preconditions . . . . . . . . . . . . . . . . . . . . . 122 236 13.1.1. If-Match . . . . . . . . . . . . . . . . . . . . . . 123 237 13.1.2. If-None-Match . . . . . . . . . . . . . . . . . . . 124 238 13.1.3. If-Modified-Since . . . . . . . . . . . . . . . . . 126 239 13.1.4. If-Unmodified-Since . . . . . . . . . . . . . . . . 128 240 13.1.5. If-Range . . . . . . . . . . . . . . . . . . . . . . 129 241 13.2. Evaluation of Preconditions . . . . . . . . . . . . . . 130 242 13.2.1. When to Evaluate . . . . . . . . . . . . . . . . . . 131 243 13.2.2. Precedence of Preconditions . . . . . . . . . . . . 132 244 14. Range Requests . . . . . . . . . . . . . . . . . . . . . . . 133 245 14.1. Range Units . . . . . . . . . . . . . . . . . . . . . . 133 246 14.1.1. Range Specifiers . . . . . . . . . . . . . . . . . . 134 247 14.1.2. Byte Ranges . . . . . . . . . . . . . . . . . . . . 135 248 14.2. Range . . . . . . . . . . . . . . . . . . . . . . . . . 137 249 14.3. Accept-Ranges . . . . . . . . . . . . . . . . . . . . . 138 250 14.4. Content-Range . . . . . . . . . . . . . . . . . . . . . 139 251 14.5. Partial PUT . . . . . . . . . . . . . . . . . . . . . . 141 252 14.6. Media Type multipart/byteranges . . . . . . . . . . . . 141 253 15. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . 143 254 15.1. Overview of Status Codes . . . . . . . . . . . . . . . . 144 255 15.2. Informational 1xx . . . . . . . . . . . . . . . . . . . 144 256 15.2.1. 100 Continue . . . . . . . . . . . . . . . . . . . . 145 257 15.2.2. 101 Switching Protocols . . . . . . . . . . . . . . 145 258 15.3. Successful 2xx . . . . . . . . . . . . . . . . . . . . . 145 259 15.3.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . 146 260 15.3.2. 201 Created . . . . . . . . . . . . . . . . . . . . 146 261 15.3.3. 202 Accepted . . . . . . . . . . . . . . . . . . . . 147 262 15.3.4. 203 Non-Authoritative Information . . . . . . . . . 147 263 15.3.5. 204 No Content . . . . . . . . . . . . . . . . . . . 147 264 15.3.6. 205 Reset Content . . . . . . . . . . . . . . . . . 148 265 15.3.7. 206 Partial Content . . . . . . . . . . . . . . . . 148 266 15.4. Redirection 3xx . . . . . . . . . . . . . . . . . . . . 152 267 15.4.1. 300 Multiple Choices . . . . . . . . . . . . . . . . 154 268 15.4.2. 301 Moved Permanently . . . . . . . . . . . . . . . 155 269 15.4.3. 302 Found . . . . . . . . . . . . . . . . . . . . . 155 270 15.4.4. 303 See Other . . . . . . . . . . . . . . . . . . . 156 271 15.4.5. 304 Not Modified . . . . . . . . . . . . . . . . . . 156 272 15.4.6. 305 Use Proxy . . . . . . . . . . . . . . . . . . . 157 273 15.4.7. 306 (Unused) . . . . . . . . . . . . . . . . . . . . 157 274 15.4.8. 307 Temporary Redirect . . . . . . . . . . . . . . . 157 275 15.4.9. 308 Permanent Redirect . . . . . . . . . . . . . . . 158 276 15.5. Client Error 4xx . . . . . . . . . . . . . . . . . . . . 158 277 15.5.1. 400 Bad Request . . . . . . . . . . . . . . . . . . 158 278 15.5.2. 401 Unauthorized . . . . . . . . . . . . . . . . . . 159 279 15.5.3. 402 Payment Required . . . . . . . . . . . . . . . . 159 280 15.5.4. 403 Forbidden . . . . . . . . . . . . . . . . . . . 159 281 15.5.5. 404 Not Found . . . . . . . . . . . . . . . . . . . 159 282 15.5.6. 405 Method Not Allowed . . . . . . . . . . . . . . . 160 283 15.5.7. 406 Not Acceptable . . . . . . . . . . . . . . . . . 160 284 15.5.8. 407 Proxy Authentication Required . . . . . . . . . 160 285 15.5.9. 408 Request Timeout . . . . . . . . . . . . . . . . 160 286 15.5.10. 409 Conflict . . . . . . . . . . . . . . . . . . . . 161 287 15.5.11. 410 Gone . . . . . . . . . . . . . . . . . . . . . . 161 288 15.5.12. 411 Length Required . . . . . . . . . . . . . . . . 162 289 15.5.13. 412 Precondition Failed . . . . . . . . . . . . . . 162 290 15.5.14. 413 Content Too Large . . . . . . . . . . . . . . . 162 291 15.5.15. 414 URI Too Long . . . . . . . . . . . . . . . . . . 162 292 15.5.16. 415 Unsupported Media Type . . . . . . . . . . . . . 163 293 15.5.17. 416 Range Not Satisfiable . . . . . . . . . . . . . 163 294 15.5.18. 417 Expectation Failed . . . . . . . . . . . . . . . 164 295 15.5.19. 418 (Unused) . . . . . . . . . . . . . . . . . . . . 164 296 15.5.20. 421 Misdirected Request . . . . . . . . . . . . . . 164 297 15.5.21. 422 Unprocessable Content . . . . . . . . . . . . . 165 298 15.5.22. 426 Upgrade Required . . . . . . . . . . . . . . . . 165 299 15.6. Server Error 5xx . . . . . . . . . . . . . . . . . . . . 165 300 15.6.1. 500 Internal Server Error . . . . . . . . . . . . . 165 301 15.6.2. 501 Not Implemented . . . . . . . . . . . . . . . . 166 302 15.6.3. 502 Bad Gateway . . . . . . . . . . . . . . . . . . 166 303 15.6.4. 503 Service Unavailable . . . . . . . . . . . . . . 166 304 15.6.5. 504 Gateway Timeout . . . . . . . . . . . . . . . . 166 305 15.6.6. 505 HTTP Version Not Supported . . . . . . . . . . . 166 306 16. Extending HTTP . . . . . . . . . . . . . . . . . . . . . . . 167 307 16.1. Method Extensibility . . . . . . . . . . . . . . . . . . 167 308 16.1.1. Method Registry . . . . . . . . . . . . . . . . . . 167 309 16.1.2. Considerations for New Methods . . . . . . . . . . . 168 310 16.2. Status Code Extensibility . . . . . . . . . . . . . . . 168 311 16.2.1. Status Code Registry . . . . . . . . . . . . . . . . 169 312 16.2.2. Considerations for New Status Codes . . . . . . . . 169 313 16.3. Field Extensibility . . . . . . . . . . . . . . . . . . 170 314 16.3.1. Field Name Registry . . . . . . . . . . . . . . . . 170 315 16.3.2. Considerations for New Fields . . . . . . . . . . . 172 316 16.4. Authentication Scheme Extensibility . . . . . . . . . . 174 317 16.4.1. Authentication Scheme Registry . . . . . . . . . . . 174 318 16.4.2. Considerations for New Authentication Schemes . . . 175 319 16.5. Range Unit Extensibility . . . . . . . . . . . . . . . . 176 320 16.5.1. Range Unit Registry . . . . . . . . . . . . . . . . 176 321 16.5.2. Considerations for New Range Units . . . . . . . . . 176 322 16.6. Content Coding Extensibility . . . . . . . . . . . . . . 176 323 16.6.1. Content Coding Registry . . . . . . . . . . . . . . 177 324 16.6.2. Considerations for New Content Codings . . . . . . . 177 325 16.7. Upgrade Token Registry . . . . . . . . . . . . . . . . . 177 326 17. Security Considerations . . . . . . . . . . . . . . . . . . . 178 327 17.1. Establishing Authority . . . . . . . . . . . . . . . . . 178 328 17.2. Risks of Intermediaries . . . . . . . . . . . . . . . . 179 329 17.3. Attacks Based on File and Path Names . . . . . . . . . . 180 330 17.4. Attacks Based on Command, Code, or Query Injection . . . 181 331 17.5. Attacks via Protocol Element Length . . . . . . . . . . 181 332 17.6. Attacks using Shared-dictionary Compression . . . . . . 182 333 17.7. Disclosure of Personal Information . . . . . . . . . . . 182 334 17.8. Privacy of Server Log Information . . . . . . . . . . . 182 335 17.9. Disclosure of Sensitive Information in URIs . . . . . . 183 336 17.10. Disclosure of Fragment after Redirects . . . . . . . . . 184 337 17.11. Disclosure of Product Information . . . . . . . . . . . 184 338 17.12. Browser Fingerprinting . . . . . . . . . . . . . . . . . 184 339 17.13. Validator Retention . . . . . . . . . . . . . . . . . . 185 340 17.14. Denial-of-Service Attacks Using Range . . . . . . . . . 186 341 17.15. Authentication Considerations . . . . . . . . . . . . . 186 342 17.15.1. Confidentiality of Credentials . . . . . . . . . . 186 343 17.15.2. Credentials and Idle Clients . . . . . . . . . . . 187 344 17.15.3. Protection Spaces . . . . . . . . . . . . . . . . . 187 345 17.15.4. Additional Response Fields . . . . . . . . . . . . 188 346 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 188 347 18.1. URI Scheme Registration . . . . . . . . . . . . . . . . 188 348 18.2. Method Registration . . . . . . . . . . . . . . . . . . 188 349 18.3. Status Code Registration . . . . . . . . . . . . . . . . 189 350 18.4. Field Name Registration . . . . . . . . . . . . . . . . 190 351 18.5. Authentication Scheme Registration . . . . . . . . . . . 192 352 18.6. Content Coding Registration . . . . . . . . . . . . . . 192 353 18.7. Range Unit Registration . . . . . . . . . . . . . . . . 193 354 18.8. Media Type Registration . . . . . . . . . . . . . . . . 193 355 18.9. Port Registration . . . . . . . . . . . . . . . . . . . 193 356 18.10. Upgrade Token Registration . . . . . . . . . . . . . . . 194 357 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 194 358 19.1. Normative References . . . . . . . . . . . . . . . . . . 194 359 19.2. Informative References . . . . . . . . . . . . . . . . . 196 360 Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 202 361 Appendix B. Changes from previous RFCs . . . . . . . . . . . . . 207 362 B.1. Changes from RFC 2818 . . . . . . . . . . . . . . . . . . 207 363 B.2. Changes from RFC 7230 . . . . . . . . . . . . . . . . . . 207 364 B.3. Changes from RFC 7231 . . . . . . . . . . . . . . . . . . 208 365 B.4. Changes from RFC 7232 . . . . . . . . . . . . . . . . . . 210 366 B.5. Changes from RFC 7233 . . . . . . . . . . . . . . . . . . 210 367 B.6. Changes from RFC 7235 . . . . . . . . . . . . . . . . . . 210 368 B.7. Changes from RFC 7538 . . . . . . . . . . . . . . . . . . 210 369 B.8. Changes from RFC 7615 . . . . . . . . . . . . . . . . . . 211 370 B.9. Changes from RFC 7694 . . . . . . . . . . . . . . . . . . 211 371 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 211 372 C.1. Between RFC723x and draft 00 . . . . . . . . . . . . . . 211 373 C.2. Since draft-ietf-httpbis-semantics-00 . . . . . . . . . . 211 374 C.3. Since draft-ietf-httpbis-semantics-01 . . . . . . . . . . 212 375 C.4. Since draft-ietf-httpbis-semantics-02 . . . . . . . . . . 213 376 C.5. Since draft-ietf-httpbis-semantics-03 . . . . . . . . . . 214 377 C.6. Since draft-ietf-httpbis-semantics-04 . . . . . . . . . . 215 378 C.7. Since draft-ietf-httpbis-semantics-05 . . . . . . . . . . 215 379 C.8. Since draft-ietf-httpbis-semantics-06 . . . . . . . . . . 217 380 C.9. Since draft-ietf-httpbis-semantics-07 . . . . . . . . . . 218 381 C.10. Since draft-ietf-httpbis-semantics-08 . . . . . . . . . . 219 382 C.11. Since draft-ietf-httpbis-semantics-09 . . . . . . . . . . 221 383 C.12. Since draft-ietf-httpbis-semantics-10 . . . . . . . . . . 221 384 C.13. Since draft-ietf-httpbis-semantics-11 . . . . . . . . . . 222 385 C.14. Since draft-ietf-httpbis-semantics-12 . . . . . . . . . . 223 386 C.15. Since draft-ietf-httpbis-semantics-13 . . . . . . . . . . 225 387 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 225 388 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 226 390 1. Introduction 392 1.1. Purpose 394 The Hypertext Transfer Protocol (HTTP) is a family of stateless, 395 application-level, request/response protocols that share a generic 396 interface, extensible semantics, and self-descriptive messages to 397 enable flexible interaction with network-based hypertext information 398 systems. 400 HTTP hides the details of how a service is implemented by presenting 401 a uniform interface to clients that is independent of the types of 402 resources provided. Likewise, servers do not need to be aware of 403 each client's purpose: a request can be considered in isolation 404 rather than being associated with a specific type of client or a 405 predetermined sequence of application steps. This allows general- 406 purpose implementations to be used effectively in many different 407 contexts, reduces interaction complexity, and enables independent 408 evolution over time. 410 HTTP is also designed for use as an intermediation protocol, wherein 411 proxies and gateways can translate non-HTTP information systems into 412 a more generic interface. 414 One consequence of this flexibility is that the protocol cannot be 415 defined in terms of what occurs behind the interface. Instead, we 416 are limited to defining the syntax of communication, the intent of 417 received communication, and the expected behavior of recipients. If 418 the communication is considered in isolation, then successful actions 419 ought to be reflected in corresponding changes to the observable 420 interface provided by servers. However, since multiple clients might 421 act in parallel and perhaps at cross-purposes, we cannot require that 422 such changes be observable beyond the scope of a single response. 424 1.2. History and Evolution 426 HTTP has been the primary information transfer protocol for the World 427 Wide Web since its introduction in 1990. It began as a trivial 428 mechanism for low-latency requests, with a single method (GET) to 429 request transfer of a presumed hypertext document identified by a 430 given pathname. As the Web grew, HTTP was extended to enclose 431 requests and responses within messages, transfer arbitrary data 432 formats using MIME-like media types, and route requests through 433 intermediaries. These protocols were eventually defined as HTTP/0.9 434 and HTTP/1.0 (see [RFC1945]). 436 HTTP/1.1 was designed to refine the protocol's features while 437 retaining compatibility with the existing text-based messaging 438 syntax, improving its interoperability, scalability, and robustness 439 across the Internet. This included length-based data delimiters for 440 both fixed and dynamic (chunked) content, a consistent framework for 441 content negotiation, opaque validators for conditional requests, 442 cache controls for better cache consistency, range requests for 443 partial updates, and default persistent connections. HTTP/1.1 was 444 introduced in 1995 and published on the standards track in 1997 445 [RFC2068], revised in 1999 [RFC2616], and revised again in 2014 446 ([RFC7230] - [RFC7235]). 448 HTTP/2 ([RFC7540]) introduced a multiplexed session layer on top of 449 the existing TLS and TCP protocols for exchanging concurrent HTTP 450 messages with efficient field compression and server push. HTTP/3 451 ([HTTP3]) provides greater independence for concurrent messages by 452 using QUIC as a secure multiplexed transport over UDP instead of TCP. 454 All three major versions of HTTP rely on the semantics defined by 455 this document. They have not obsoleted each other because each one 456 has specific benefits and limitations depending on the context of 457 use. Implementations are expected to choose the most appropriate 458 transport and messaging syntax for their particular context. 460 This revision of HTTP separates the definition of semantics (this 461 document) and caching ([Caching]) from the current HTTP/1.1 messaging 462 syntax ([Messaging]) to allow each major protocol version to progress 463 independently while referring to the same core semantics. 465 1.3. Core Semantics 467 HTTP provides a uniform interface for interacting with a resource 468 (Section 3.1) - regardless of its type, nature, or implementation - 469 by sending messages that manipulate or transfer representations 470 (Section 3.2). 472 Each message is either a request or a response. A client constructs 473 request messages that communicate its intentions and routes those 474 messages toward an identified origin server. A server listens for 475 requests, parses each message received, interprets the message 476 semantics in relation to the identified target resource, and responds 477 to that request with one or more response messages. The client 478 examines received responses to see if its intentions were carried 479 out, determining what to do next based on the status codes and 480 content received. 482 HTTP semantics include the intentions defined by each request method 483 (Section 9), extensions to those semantics that might be described in 484 request header fields, status codes that describe the response 485 (Section 15), and other control data and resource metadata that might 486 be given in response fields. 488 Semantics also include representation metadata that describe how 489 content is intended to be interpreted by a recipient, request header 490 fields that might influence content selection, and the various 491 selection algorithms that are collectively referred to as _content 492 negotiation_ (Section 12). 494 1.4. Specifications Obsoleted by this Document 496 This document obsoletes the following specifications: 498 -------------------------------------------- ----------- --------- 499 Title Reference Changes 500 -------------------------------------------- ----------- --------- 501 HTTP Over TLS [RFC2818] B.1 502 HTTP/1.1 Message Syntax and Routing [*] [RFC7230] B.2 503 HTTP/1.1 Semantics and Content [RFC7231] B.3 504 HTTP/1.1 Conditional Requests [RFC7232] B.4 505 HTTP/1.1 Range Requests [RFC7233] B.5 506 HTTP/1.1 Authentication [RFC7235] B.6 507 HTTP Status Code 308 (Permanent Redirect) [RFC7538] B.7 508 HTTP Authentication-Info and Proxy- [RFC7615] B.8 509 Authentication-Info Response Header Fields 510 HTTP Client-Initiated Content-Encoding [RFC7694] B.9 511 -------------------------------------------- ----------- --------- 513 Table 1 515 [*] This document only obsoletes the portions of RFC 7230 that are 516 independent of the HTTP/1.1 messaging syntax and connection 517 management; the remaining bits of RFC 7230 are obsoleted by 518 "HTTP/1.1" [Messaging]. 520 2. Conformance 522 2.1. Syntax Notation 524 This specification uses the Augmented Backus-Naur Form (ABNF) 525 notation of [RFC5234], extended with the notation for case- 526 sensitivity in strings defined in [RFC7405]. 528 It also uses a list extension, defined in Section 5.6.1, that allows 529 for compact definition of comma-separated lists using a "#" operator 530 (similar to how the "*" operator indicates repetition). Appendix A 531 shows the collected grammar with all list operators expanded to 532 standard ABNF notation. 534 As a convention, ABNF rule names prefixed with "obs-" denote 535 "obsolete" grammar rules that appear for historical reasons. 537 The following core rules are included by reference, as defined in 538 Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), 539 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 540 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF 541 (line feed), OCTET (any 8-bit sequence of data), SP (space), and 542 VCHAR (any visible US-ASCII character). 544 Section 5.6 defines some generic syntactic components for field 545 values. 547 This specification uses the terms "character", "character encoding 548 scheme", "charset", and "protocol element" as they are defined in 549 [RFC6365]. 551 2.2. Requirements Notation 553 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 554 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 555 "OPTIONAL" in this document are to be interpreted as described in BCP 556 14 [RFC2119] [RFC8174] when, and only when, they appear in all 557 capitals, as shown here. 559 This specification targets conformance criteria according to the role 560 of a participant in HTTP communication. Hence, requirements are 561 placed on senders, recipients, clients, servers, user agents, 562 intermediaries, origin servers, proxies, gateways, or caches, 563 depending on what behavior is being constrained by the requirement. 564 Additional (social) requirements are placed on implementations, 565 resource owners, and protocol element registrations when they apply 566 beyond the scope of a single communication. 568 The verb "generate" is used instead of "send" where a requirement 569 applies only to implementations that create the protocol element, 570 rather than an implementation that forwards a received element 571 downstream. 573 An implementation is considered conformant if it complies with all of 574 the requirements associated with the roles it partakes in HTTP. 576 Conformance includes both the syntax and semantics of protocol 577 elements. A sender MUST NOT generate protocol elements that convey a 578 meaning that is known by that sender to be false. A sender MUST NOT 579 generate protocol elements that do not match the grammar defined by 580 the corresponding ABNF rules. Within a given message, a sender MUST 581 NOT generate protocol elements or syntax alternatives that are only 582 allowed to be generated by participants in other roles (i.e., a role 583 that the sender does not have for that message). 585 2.3. Length Requirements 587 A recipient SHOULD parse a received protocol element defensively, 588 with only marginal expectations that the element will conform to its 589 ABNF grammar and fit within a reasonable buffer size. 591 HTTP does not have specific length limitations for many of its 592 protocol elements because the lengths that might be appropriate will 593 vary widely, depending on the deployment context and purpose of the 594 implementation. Hence, interoperability between senders and 595 recipients depends on shared expectations regarding what is a 596 reasonable length for each protocol element. Furthermore, what is 597 commonly understood to be a reasonable length for some protocol 598 elements has changed over the course of the past two decades of HTTP 599 use and is expected to continue changing in the future. 601 At a minimum, a recipient MUST be able to parse and process protocol 602 element lengths that are at least as long as the values that it 603 generates for those same protocol elements in other messages. For 604 example, an origin server that publishes very long URI references to 605 its own resources needs to be able to parse and process those same 606 references when received as a target URI. 608 Many received protocol elements are only parsed to the extent 609 necessary to identify and forward that element downstream. For 610 example, an intermediary might parse a received field into its field 611 name and field value components, but then forward the field without 612 further parsing inside the field value. 614 2.4. Error Handling 616 A recipient MUST interpret a received protocol element according to 617 the semantics defined for it by this specification, including 618 extensions to this specification, unless the recipient has determined 619 (through experience or configuration) that the sender incorrectly 620 implements what is implied by those semantics. For example, an 621 origin server might disregard the contents of a received 622 Accept-Encoding header field if inspection of the User-Agent header 623 field indicates a specific implementation version that is known to 624 fail on receipt of certain content codings. 626 Unless noted otherwise, a recipient MAY attempt to recover a usable 627 protocol element from an invalid construct. HTTP does not define 628 specific error handling mechanisms except when they have a direct 629 impact on security, since different applications of the protocol 630 require different error handling strategies. For example, a Web 631 browser might wish to transparently recover from a response where the 632 Location header field doesn't parse according to the ABNF, whereas a 633 systems control client might consider any form of error recovery to 634 be dangerous. 636 Some requests can be automatically retried by a client in the event 637 of an underlying connection failure, as described in Section 9.2.2. 639 2.5. Protocol Version 641 HTTP's version number consists of two decimal digits separated by a 642 "." (period or decimal point). The first digit ("major version") 643 indicates the messaging syntax, whereas the second digit ("minor 644 version") indicates the highest minor version within that major 645 version to which the sender is conformant (able to understand for 646 future communication). 648 While HTTP's core semantics don't change between protocol versions, 649 the expression of them "on the wire" can change, and so the HTTP 650 version number changes when incompatible changes are made to the wire 651 format. Additionally, HTTP allows incremental, backwards-compatible 652 changes to be made to the protocol without changing its version 653 through the use of defined extension points (Section 16). 655 The protocol version as a whole indicates the sender's conformance 656 with the set of requirements laid out in that version's corresponding 657 specification of HTTP. For example, the version "HTTP/1.1" is 658 defined by the combined specifications of this document, "HTTP 659 Caching" [Caching], and "HTTP/1.1" [Messaging]. 661 HTTP's major version number is incremented when an incompatible 662 message syntax is introduced. The minor number is incremented when 663 changes made to the protocol have the effect of adding to the message 664 semantics or implying additional capabilities of the sender. 666 The minor version advertises the sender's communication capabilities 667 even when the sender is only using a backwards-compatible subset of 668 the protocol, thereby letting the recipient know that more advanced 669 features can be used in response (by servers) or in future requests 670 (by clients). 672 When a major version of HTTP does not define any minor versions, the 673 minor version "0" is implied and is used when referring to that 674 protocol within a protocol element that requires sending a minor 675 version. 677 3. Terminology and Core Concepts 679 HTTP was created for the World Wide Web (WWW) architecture and has 680 evolved over time to support the scalability needs of a worldwide 681 hypertext system. Much of that architecture is reflected in the 682 terminology and syntax productions used to define HTTP. 684 3.1. Resources 686 The target of an HTTP request is called a _resource_. HTTP does not 687 limit the nature of a resource; it merely defines an interface that 688 might be used to interact with resources. Most resources are 689 identified by a Uniform Resource Identifier (URI), as described in 690 Section 4. 692 One design goal of HTTP is to separate resource identification from 693 request semantics, which is made possible by vesting the request 694 semantics in the request method (Section 9) and a few request- 695 modifying header fields. If there is a conflict between the method 696 semantics and any semantic implied by the URI itself, as described in 697 Section 9.2.1, the method semantics take precedence. 699 HTTP relies upon the Uniform Resource Identifier (URI) standard 700 [RFC3986] to indicate the target resource (Section 7.1) and 701 relationships between resources. 703 3.2. Representations 705 A _representation_ is information that is intended to reflect a past, 706 current, or desired state of a given resource, in a format that can 707 be readily communicated via the protocol. A representation consists 708 of a set of representation metadata and a potentially unbounded 709 stream of representation data (Section 8). 711 HTTP allows "information hiding" behind its uniform interface by 712 defining communication with respect to a transferable representation 713 of the resource state, rather than transferring the resource itself. 714 This allows the resource identified by a URI to be anything, 715 including temporal functions like "the current weather in Laguna 716 Beach", while potentially providing information that represents that 717 resource at the time a message is generated [REST]. 719 The uniform interface is similar to a window through which one can 720 observe and act upon a thing only through the communication of 721 messages to an independent actor on the other side. A shared 722 abstraction is needed to represent ("take the place of") the current 723 or desired state of that thing in our communications. When a 724 representation is hypertext, it can provide both a representation of 725 the resource state and processing instructions that help guide the 726 recipient's future interactions. 728 A target resource might be provided with, or be capable of 729 generating, multiple representations that are each intended to 730 reflect the resource's current state. An algorithm, usually based on 731 content negotiation (Section 12), would be used to select one of 732 those representations as being most applicable to a given request. 733 This _selected representation_ provides the data and metadata for 734 evaluating conditional requests (Section 13) and constructing the 735 content for 200 (OK), 206 (Partial Content), and 304 (Not Modified) 736 responses to GET (Section 9.3.1). 738 3.3. Connections, Clients and Servers 740 HTTP is a client/server protocol that operates over a reliable 741 transport- or session-layer _connection_. 743 An HTTP _client_ is a program that establishes a connection to a 744 server for the purpose of sending one or more HTTP requests. An HTTP 745 _server_ is a program that accepts connections in order to service 746 HTTP requests by sending HTTP responses. 748 The terms "client" and "server" refer only to the roles that these 749 programs perform for a particular connection. The same program might 750 act as a client on some connections and a server on others. 752 3.4. Messages 754 HTTP is a stateless request/response protocol for exchanging 755 _messages_ across a connection. The terms _sender_ and _recipient_ 756 refer to any implementation that sends or receives a given message, 757 respectively. 759 A client sends requests to a server in the form of a _request_ 760 message with a method (Section 9) and request target (Section 7.1). 761 The request might also contain header fields (Section 6.3) for 762 request modifiers, client information, and representation metadata, 763 content (Section 6.4) intended for processing in accordance with the 764 method, and trailer fields (Section 6.5) to communicate information 765 collected while sending the content. 767 A server responds to a client's request by sending one or more 768 _response_ messages, each including a status code (Section 15). The 769 response might also contain header fields for server information, 770 resource metadata, and representation metadata, content to be 771 interpreted in accordance with the status code, and trailer fields to 772 communicate information collected while sending the content. 774 3.5. User Agents 776 The term _user agent_ refers to any of the various client programs 777 that initiate a request. 779 The most familiar form of user agent is the general-purpose Web 780 browser, but that's only a small percentage of implementations. 781 Other common user agents include spiders (web-traversing robots), 782 command-line tools, billboard screens, household appliances, scales, 783 light bulbs, firmware update scripts, mobile apps, and communication 784 devices in a multitude of shapes and sizes. 786 Being a user agent does not imply that there is a human user directly 787 interacting with the software agent at the time of a request. In 788 many cases, a user agent is installed or configured to run in the 789 background and save its results for later inspection (or save only a 790 subset of those results that might be interesting or erroneous). 791 Spiders, for example, are typically given a start URI and configured 792 to follow certain behavior while crawling the Web as a hypertext 793 graph. 795 Many user agents cannot, or choose not to, make interactive 796 suggestions to their user or provide adequate warning for security or 797 privacy concerns. In the few cases where this specification requires 798 reporting of errors to the user, it is acceptable for such reporting 799 to only be observable in an error console or log file. Likewise, 800 requirements that an automated action be confirmed by the user before 801 proceeding might be met via advance configuration choices, run-time 802 options, or simple avoidance of the unsafe action; confirmation does 803 not imply any specific user interface or interruption of normal 804 processing if the user has already made that choice. 806 3.6. Origin Server 808 The term _origin server_ refers to a program that can originate 809 authoritative responses for a given target resource. 811 The most familiar form of origin server are large public websites. 812 However, like user agents being equated with browsers, it is easy to 813 be misled into thinking that all origin servers are alike. Common 814 origin servers also include home automation units, configurable 815 networking components, office machines, autonomous robots, news 816 feeds, traffic cameras, real-time ad selectors, and video-on-demand 817 platforms. 819 Most HTTP communication consists of a retrieval request (GET) for a 820 representation of some resource identified by a URI. In the simplest 821 case, this might be accomplished via a single bidirectional 822 connection (===) between the user agent (UA) and the origin server 823 (O). 825 request > 826 UA ======================================= O 827 < response 829 Figure 1 831 3.7. Intermediaries 833 HTTP enables the use of intermediaries to satisfy requests through a 834 chain of connections. There are three common forms of HTTP 835 _intermediary_: proxy, gateway, and tunnel. In some cases, a single 836 intermediary might act as an origin server, proxy, gateway, or 837 tunnel, switching behavior based on the nature of each request. 839 > > > > 840 UA =========== A =========== B =========== C =========== O 841 < < < < 843 Figure 2 845 The figure above shows three intermediaries (A, B, and C) between the 846 user agent and origin server. A request or response message that 847 travels the whole chain will pass through four separate connections. 849 Some HTTP communication options might apply only to the connection 850 with the nearest, non-tunnel neighbor, only to the endpoints of the 851 chain, or to all connections along the chain. Although the diagram 852 is linear, each participant might be engaged in multiple, 853 simultaneous communications. For example, B might be receiving 854 requests from many clients other than A, and/or forwarding requests 855 to servers other than C, at the same time that it is handling A's 856 request. Likewise, later requests might be sent through a different 857 path of connections, often based on dynamic configuration for load 858 balancing. 860 The terms _upstream_ and _downstream_ are used to describe 861 directional requirements in relation to the message flow: all 862 messages flow from upstream to downstream. The terms "inbound" and 863 "outbound" are used to describe directional requirements in relation 864 to the request route: _inbound_ means toward the origin server and 865 _outbound_ means toward the user agent. 867 A _proxy_ is a message-forwarding agent that is chosen by the client, 868 usually via local configuration rules, to receive requests for some 869 type(s) of absolute URI and attempt to satisfy those requests via 870 translation through the HTTP interface. Some translations are 871 minimal, such as for proxy requests for "http" URIs, whereas other 872 requests might require translation to and from entirely different 873 application-level protocols. Proxies are often used to group an 874 organization's HTTP requests through a common intermediary for the 875 sake of security, annotation services, or shared caching. Some 876 proxies are designed to apply transformations to selected messages or 877 content while they are being forwarded, as described in Section 7.7. 879 A _gateway_ (a.k.a. _reverse proxy_) is an intermediary that acts as 880 an origin server for the outbound connection but translates received 881 requests and forwards them inbound to another server or servers. 882 Gateways are often used to encapsulate legacy or untrusted 883 information services, to improve server performance through 884 _accelerator_ caching, and to enable partitioning or load balancing 885 of HTTP services across multiple machines. 887 All HTTP requirements applicable to an origin server also apply to 888 the outbound communication of a gateway. A gateway communicates with 889 inbound servers using any protocol that it desires, including private 890 extensions to HTTP that are outside the scope of this specification. 891 However, an HTTP-to-HTTP gateway that wishes to interoperate with 892 third-party HTTP servers ought to conform to user agent requirements 893 on the gateway's inbound connection. 895 A _tunnel_ acts as a blind relay between two connections without 896 changing the messages. Once active, a tunnel is not considered a 897 party to the HTTP communication, though the tunnel might have been 898 initiated by an HTTP request. A tunnel ceases to exist when both 899 ends of the relayed connection are closed. Tunnels are used to 900 extend a virtual connection through an intermediary, such as when 901 Transport Layer Security (TLS, [RFC8446]) is used to establish 902 confidential communication through a shared firewall proxy. 904 The above categories for intermediary only consider those acting as 905 participants in the HTTP communication. There are also 906 intermediaries that can act on lower layers of the network protocol 907 stack, filtering or redirecting HTTP traffic without the knowledge or 908 permission of message senders. Network intermediaries are 909 indistinguishable (at a protocol level) from an on-path attacker, 910 often introducing security flaws or interoperability problems due to 911 mistakenly violating HTTP semantics. 913 For example, an _interception proxy_ [RFC3040] (also commonly known 914 as a _transparent proxy_ [RFC1919]) differs from an HTTP proxy 915 because it is not chosen by the client. Instead, an interception 916 proxy filters or redirects outgoing TCP port 80 packets (and 917 occasionally other common port traffic). Interception proxies are 918 commonly found on public network access points, as a means of 919 enforcing account subscription prior to allowing use of non-local 920 Internet services, and within corporate firewalls to enforce network 921 usage policies. 923 HTTP is defined as a stateless protocol, meaning that each request 924 message can be understood in isolation. Many implementations depend 925 on HTTP's stateless design in order to reuse proxied connections or 926 dynamically load balance requests across multiple servers. Hence, a 927 server MUST NOT assume that two requests on the same connection are 928 from the same user agent unless the connection is secured and 929 specific to that agent. Some non-standard HTTP extensions (e.g., 930 [RFC4559]) have been known to violate this requirement, resulting in 931 security and interoperability problems. 933 3.8. Caches 935 A _cache_ is a local store of previous response messages and the 936 subsystem that controls its message storage, retrieval, and deletion. 937 A cache stores cacheable responses in order to reduce the response 938 time and network bandwidth consumption on future, equivalent 939 requests. Any client or server MAY employ a cache, though a cache 940 cannot be used while acting as a tunnel. 942 The effect of a cache is that the request/response chain is shortened 943 if one of the participants along the chain has a cached response 944 applicable to that request. The following illustrates the resulting 945 chain if B has a cached copy of an earlier response from O (via C) 946 for a request that has not been cached by UA or A. 948 > > 949 UA =========== A =========== B - - - - - - C - - - - - - O 950 < < 952 Figure 3 954 A response is _cacheable_ if a cache is allowed to store a copy of 955 the response message for use in answering subsequent requests. Even 956 when a response is cacheable, there might be additional constraints 957 placed by the client or by the origin server on when that cached 958 response can be used for a particular request. HTTP requirements for 959 cache behavior and cacheable responses are defined in Section 2 of 960 [Caching]. 962 There is a wide variety of architectures and configurations of caches 963 deployed across the World Wide Web and inside large organizations. 964 These include national hierarchies of proxy caches to save bandwidth 965 and reduce latency, Content Delivery Networks that use gateway 966 caching to optimise regional and global distribution of popular 967 sites, collaborative systems that broadcast or multicast cache 968 entries, archives of pre-fetched cache entries for use in off-line or 969 high-latency environments, and so on. 971 3.9. Example Message Exchange 973 The following example illustrates a typical HTTP/1.1 message exchange 974 for a GET request (Section 9.3.1) on the URI "http://www.example.com/ 975 hello.txt": 977 Client request: 979 GET /hello.txt HTTP/1.1 980 User-Agent: curl/7.16.3 libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3 981 Host: www.example.com 982 Accept-Language: en, mi 984 Server response: 986 HTTP/1.1 200 OK 987 Date: Mon, 27 Jul 2009 12:28:53 GMT 988 Server: Apache 989 Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT 990 ETag: "34aa387-d-1568eb00" 991 Accept-Ranges: bytes 992 Content-Length: 51 993 Vary: Accept-Encoding 994 Content-Type: text/plain 996 Hello World! My content includes a trailing CRLF. 998 4. Identifiers in HTTP 1000 Uniform Resource Identifiers (URIs) [RFC3986] are used throughout 1001 HTTP as the means for identifying resources (Section 3.1). 1003 4.1. URI References 1005 URI references are used to target requests, indicate redirects, and 1006 define relationships. 1008 The definitions of "URI-reference", "absolute-URI", "relative-part", 1009 "authority", "port", "host", "path-abempty", "segment", and "query" 1010 are adopted from the URI generic syntax. An "absolute-path" rule is 1011 defined for protocol elements that can contain a non-empty path 1012 component. (This rule differs slightly from the path-abempty rule of 1013 RFC 3986, which allows for an empty path to be used in references, 1014 and path-absolute rule, which does not allow paths that begin with 1015 "//".) A "partial-URI" rule is defined for protocol elements that 1016 can contain a relative URI but not a fragment component. 1018 URI-reference = 1019 absolute-URI = 1020 relative-part = 1021 authority = 1022 uri-host = 1023 port = 1024 path-abempty = 1025 segment = 1026 query = 1028 absolute-path = 1*( "/" segment ) 1029 partial-URI = relative-part [ "?" query ] 1031 Each protocol element in HTTP that allows a URI reference will 1032 indicate in its ABNF production whether the element allows any form 1033 of reference (URI-reference), only a URI in absolute form (absolute- 1034 URI), only the path and optional query components, or some 1035 combination of the above. Unless otherwise indicated, URI references 1036 are parsed relative to the target URI (Section 7.1). 1038 It is RECOMMENDED that all senders and recipients support, at a 1039 minimum, URIs with lengths of 8000 octets in protocol elements. Note 1040 that this implies some structures and on-wire representations (for 1041 example, the request line in HTTP/1.1) will necessarily be larger in 1042 some cases. 1044 4.2. HTTP-Related URI Schemes 1046 IANA maintains the registry of URI Schemes [BCP35] at 1047 . Although requests 1048 might target any URI scheme, the following schemes are inherent to 1049 HTTP servers: 1051 ------------ ------------------------------------ ------- 1052 URI Scheme Description Ref. 1053 ------------ ------------------------------------ ------- 1054 http Hypertext Transfer Protocol 4.2.1 1055 https Hypertext Transfer Protocol Secure 4.2.2 1056 ------------ ------------------------------------ ------- 1058 Table 2 1060 Note that the presence of an "http" or "https" URI does not imply 1061 that there is always an HTTP server at the identified origin 1062 listening for connections. Anyone can mint a URI, whether or not a 1063 server exists and whether or not that server currently maps that 1064 identifier to a resource. The delegated nature of registered names 1065 and IP addresses creates a federated namespace whether or not an HTTP 1066 server is present. 1068 4.2.1. http URI Scheme 1070 The "http" URI scheme is hereby defined for minting identifiers 1071 within the hierarchical namespace governed by a potential HTTP origin 1072 server listening for TCP ([RFC0793]) connections on a given port. 1074 http-URI = "http" "://" authority path-abempty [ "?" query ] 1076 The origin server for an "http" URI is identified by the authority 1077 component, which includes a host identifier and optional port number 1078 ([RFC3986], Section 3.2.2). If the port subcomponent is empty or not 1079 given, TCP port 80 (the reserved port for WWW services) is the 1080 default. The origin determines who has the right to respond 1081 authoritatively to requests that target the identified resource, as 1082 defined in Section 4.3.2. 1084 A sender MUST NOT generate an "http" URI with an empty host 1085 identifier. A recipient that processes such a URI reference MUST 1086 reject it as invalid. 1088 The hierarchical path component and optional query component identify 1089 the target resource within that origin server's name space. 1091 4.2.2. https URI Scheme 1093 The "https" URI scheme is hereby defined for minting identifiers 1094 within the hierarchical namespace governed by a potential origin 1095 server listening for TCP connections on a given port and capable of 1096 establishing a TLS ([RFC8446]) connection that has been secured for 1097 HTTP communication. In this context, _secured_ specifically means 1098 that the server has been authenticated as acting on behalf of the 1099 identified authority and all HTTP communication with that server has 1100 been protected for confidentiality and integrity through the use of 1101 strong encryption. 1103 https-URI = "https" "://" authority path-abempty [ "?" query ] 1105 The origin server for an "https" URI is identified by the authority 1106 component, which includes a host identifier and optional port number 1107 ([RFC3986], Section 3.2.2). If the port subcomponent is empty or not 1108 given, TCP port 443 (the reserved port for HTTP over TLS) is the 1109 default. The origin determines who has the right to respond 1110 authoritatively to requests that target the identified resource, as 1111 defined in Section 4.3.3. 1113 A sender MUST NOT generate an "https" URI with an empty host 1114 identifier. A recipient that processes such a URI reference MUST 1115 reject it as invalid. 1117 The hierarchical path component and optional query component identify 1118 the target resource within that origin server's name space. 1120 A client MUST ensure that its HTTP requests for an "https" resource 1121 are secured, prior to being communicated, and that it only accepts 1122 secured responses to those requests. 1124 Resources made available via the "https" scheme have no shared 1125 identity with the "http" scheme. They are distinct origins with 1126 separate namespaces. However, an extension to HTTP that is defined 1127 to apply to all origins with the same host, such as the Cookie 1128 protocol [RFC6265], can allow information set by one service to 1129 impact communication with other services within a matching group of 1130 host domains. 1132 4.2.3. http(s) Normalization and Comparison 1134 Since the "http" and "https" schemes conform to the URI generic 1135 syntax, such URIs are normalized and compared according to the 1136 algorithm defined in Section 6 of [RFC3986], using the defaults 1137 described above for each scheme. 1139 If the port is equal to the default port for a scheme, the normal 1140 form is to omit the port subcomponent. When not being used as the 1141 target of an OPTIONS request, an empty path component is equivalent 1142 to an absolute path of "/", so the normal form is to provide a path 1143 of "/" instead. The scheme and host are case-insensitive and 1144 normally provided in lowercase; all other components are compared in 1145 a case-sensitive manner. Characters other than those in the 1146 "reserved" set are equivalent to their percent-encoded octets: the 1147 normal form is to not encode them (see Sections 2.1 and 2.2 of 1148 [RFC3986]). 1150 For example, the following three URIs are equivalent: 1152 http://example.com:80/~smith/home.html 1153 http://EXAMPLE.com/%7Esmith/home.html 1154 http://EXAMPLE.com:/%7esmith/home.html 1156 4.2.4. Deprecation of userinfo in http(s) URIs 1158 The URI generic syntax for authority also includes a userinfo 1159 subcomponent ([RFC3986], Section 3.2.1) for including user 1160 authentication information in the URI. In that subcomponent, the use 1161 of the format "user:password" is deprecated. 1163 Some implementations make use of the userinfo component for internal 1164 configuration of authentication information, such as within command 1165 invocation options, configuration files, or bookmark lists, even 1166 though such usage might expose a user identifier or password. 1168 A sender MUST NOT generate the userinfo subcomponent (and its "@" 1169 delimiter) when an "http" or "https" URI reference is generated 1170 within a message as a target URI or field value. 1172 Before making use of an "http" or "https" URI reference received from 1173 an untrusted source, a recipient SHOULD parse for userinfo and treat 1174 its presence as an error; it is likely being used to obscure the 1175 authority for the sake of phishing attacks. 1177 4.2.5. http(s) References with Fragment Identifiers 1179 Fragment identifiers allow for indirect identification of a secondary 1180 resource, independent of the URI scheme, as defined in Section 3.5 of 1181 [RFC3986]. Some protocol elements that refer to a URI allow 1182 inclusion of a fragment, while others do not. They are distinguished 1183 by use of the ABNF rule for elements where fragment is allowed; 1184 otherwise, a specific rule that excludes fragments is used. 1186 | *Note:* The fragment identifier component is not part of the 1187 | scheme definition for a URI scheme (see Section 4.3 of 1188 | [RFC3986]), thus does not appear in the ABNF definitions for 1189 | the "http" and "https" URI schemes above. 1191 4.3. Authoritative Access 1193 Authoritative access refers to dereferencing a given identifier, for 1194 the sake of access to the identified resource, in a way that the 1195 client believes is authoritative (controlled by the resource owner). 1196 The process for determining that access is defined by the URI scheme 1197 and often uses data within the URI components, such as the authority 1198 component when the generic syntax is used. However, authoritative 1199 access is not limited to the identified mechanism. 1201 Section 4.3.1 defines the concept of an origin as an aid to such 1202 uses, and the subsequent subsections explain how to establish a 1203 peer's association with an authority to represent an origin. 1205 See Section 17.1 for security considerations related to establishing 1206 authority. 1208 4.3.1. URI Origin 1210 The _origin_ for a given URI is the triple of scheme, host, and port 1211 after normalizing the scheme and host to lowercase and normalizing 1212 the port to remove any leading zeros. If port is elided from the 1213 URI, the default port for that scheme is used. For example, the URI 1215 https://Example.Com/happy.js 1217 would have the origin 1219 { "https", "example.com", "443" } 1221 which can also be described as the normalized URI prefix with port 1222 always present: 1224 https://example.com:443 1226 Each origin defines its own namespace and controls how identifiers 1227 within that namespace are mapped to resources. In turn, how the 1228 origin responds to valid requests, consistently over time, determines 1229 the semantics that users will associate with a URI, and the 1230 usefulness of those semantics is what ultimately transforms these 1231 mechanisms into a "resource" for users to reference and access in the 1232 future. 1234 Two origins are distinct if they differ in scheme, host, or port. 1235 Even when it can be verified that the same entity controls two 1236 distinct origins, the two namespaces under those origins are distinct 1237 unless explicitly aliased by a server authoritative for that origin. 1239 Origin is also used within HTML and related Web protocols, beyond the 1240 scope of this document, as described in [RFC6454]. 1242 4.3.2. http origins 1244 Although HTTP is independent of the transport protocol, the "http" 1245 scheme (Section 4.2.1) is specific to associating authority with 1246 whomever controls the origin server listening for TCP connections on 1247 the indicated port of whatever host is identified within the 1248 authority component. This is a very weak sense of authority because 1249 it depends on both client-specific name resolution mechanisms and 1250 communication that might not be secured from an on-path attacker. 1251 Nevertheless, it is a sufficient minimum for binding "http" 1252 identifiers to an origin server for consistent resolution within a 1253 trusted environment. 1255 If the host identifier is provided as an IP address, the origin 1256 server is the listener (if any) on the indicated TCP port at that IP 1257 address. If host is a registered name, the registered name is an 1258 indirect identifier for use with a name resolution service, such as 1259 DNS, to find an address for an appropriate origin server. 1261 When an "http" URI is used within a context that calls for access to 1262 the indicated resource, a client MAY attempt access by resolving the 1263 host identifier to an IP address, establishing a TCP connection to 1264 that address on the indicated port, and sending an HTTP request 1265 message to the server containing the URI's identifying data. 1267 If the server responds to such a request with a non-interim HTTP 1268 response message, as described in Section 15, then that response is 1269 considered an authoritative answer to the client's request. 1271 Note, however, that the above is not the only means for obtaining an 1272 authoritative response, nor does it imply that an authoritative 1273 response is always necessary (see [Caching]). For example, the Alt- 1274 Svc header field [RFC7838] allows an origin server to identify other 1275 services that are also authoritative for that origin. Access to 1276 "http" identified resources might also be provided by protocols 1277 outside the scope of this document. 1279 4.3.3. https origins 1281 The "https" scheme (Section 4.2.2) associates authority based on the 1282 ability of a server to use the private key corresponding to a 1283 certificate that the client considers to be trustworthy for the 1284 identified origin server. The client usually relies upon a chain of 1285 trust, conveyed from some prearranged or configured trust anchor, to 1286 deem a certificate trustworthy (Section 4.3.4). 1288 In HTTP/1.1 and earlier, a client will only attribute authority to a 1289 server when they are communicating over a successfully established 1290 and secured connection specifically to that URI origin's host. The 1291 connection establishment and certificate verification are used as 1292 proof of authority. 1294 In HTTP/2 and HTTP/3, a client will attribute authority to a server 1295 when they are communicating over a successfully established and 1296 secured connection if the URI origin's host matches any of the hosts 1297 present in the server's certificate and the client believes that it 1298 could open a connection to that host for that URI. In practice, a 1299 client will make a DNS query to check that the origin's host contains 1300 the same server IP address as the established connection. This 1301 restriction can be removed by the origin server sending an equivalent 1302 ORIGIN frame [RFC8336]. 1304 The request target's host and port value are passed within each HTTP 1305 request, identifying the origin and distinguishing it from other 1306 namespaces that might be controlled by the same server (Section 7.2). 1307 It is the origin's responsibility to ensure that any services 1308 provided with control over its certificate's private key are equally 1309 responsible for managing the corresponding "https" namespaces, or at 1310 least prepared to reject requests that appear to have been 1311 misdirected. A server might be unwilling to serve as the origin for 1312 some hosts even when they have the authority to do so. 1314 For example, if a network attacker causes connections for port N to 1315 be received at port Q, checking the target URI is necessary to ensure 1316 that the attacker can't cause "https://example.com:N/foo" to be 1317 replaced by "https://example.com:Q/foo" without consent. 1319 Note that the "https" scheme does not rely on TCP and the connected 1320 port number for associating authority, since both are outside the 1321 secured communication and thus cannot be trusted as definitive. 1322 Hence, the HTTP communication might take place over any channel that 1323 has been secured, as defined in Section 4.2.2, including protocols 1324 that don't use TCP. 1326 When an "https" URI is used within a context that calls for access to 1327 the indicated resource, a client MAY attempt access by resolving the 1328 host identifier to an IP address, establishing a TCP connection to 1329 that address on the indicated port, securing the connection end-to- 1330 end by successfully initiating TLS over TCP with confidentiality and 1331 integrity protection, and sending an HTTP request message over that 1332 connection containing the URI's identifying data. 1334 If the server responds to such a request with a non-interim HTTP 1335 response message, as described in Section 15, then that response is 1336 considered an authoritative answer to the client's request. 1338 Note, however, that the above is not the only means for obtaining an 1339 authoritative response, nor does it imply that an authoritative 1340 response is always necessary (see [Caching]). 1342 4.3.4. https certificate verification 1344 To establish a secured connection to dereference a URI, a client MUST 1345 verify that the service's identity is an acceptable match for the 1346 URI's origin server. Certificate verification is used to prevent 1347 server impersonation by an on-path attacker or by an attacker that 1348 controls name resolution. This process requires that a client be 1349 configured with a set of trust anchors. 1351 In general, a client MUST verify the service identity using the 1352 verification process defined in Section 6 of [RFC6125] (for a 1353 reference identifier of type URI-ID) unless the client has been 1354 specifically configured to accept some other form of verification. 1355 For example, a client might be connecting to a server whose address 1356 and hostname are dynamic, with an expectation that the service will 1357 present a specific certificate (or a certificate matching some 1358 externally defined reference identity) rather than one matching the 1359 dynamic URI's origin server identifier. 1361 In special cases, it might be appropriate for a client to simply 1362 ignore the server's identity, but it must be understood that this 1363 leaves a connection open to active attack. 1365 If the certificate is not valid for the URI's origin server, a user 1366 agent MUST either notify the user (user agents MAY give the user an 1367 option to continue with the connection in any case) or terminate the 1368 connection with a bad certificate error. Automated clients MUST log 1369 the error to an appropriate audit log (if available) and SHOULD 1370 terminate the connection (with a bad certificate error). Automated 1371 clients MAY provide a configuration setting that disables this check, 1372 but MUST provide a setting which enables it. 1374 5. Fields 1376 HTTP uses _fields_ to provide data in the form of extensible key/ 1377 value pairs with a registered key namespace. Fields are sent and 1378 received within the header and trailer sections of messages 1379 (Section 6). 1381 5.1. Field Names 1383 A field name labels the corresponding field value as having the 1384 semantics defined by that name. For example, the Date header field 1385 is defined in Section 10.2.2 as containing the origination timestamp 1386 for the message in which it appears. 1388 field-name = token 1390 Field names are case-insensitive and ought to be registered within 1391 the "Hypertext Transfer Protocol (HTTP) Field Name Registry"; see 1392 Section 16.3.1. 1394 The interpretation of a field does not change between minor versions 1395 of the same major HTTP version, though the default behavior of a 1396 recipient in the absence of such a field can change. Unless 1397 specified otherwise, fields are defined for all versions of HTTP. In 1398 particular, the Host and Connection fields ought to be recognized by 1399 all HTTP implementations whether or not they advertise conformance 1400 with HTTP/1.1. 1402 New fields can be introduced without changing the protocol version if 1403 their defined semantics allow them to be safely ignored by recipients 1404 that do not recognize them; see Section 16.3. 1406 A proxy MUST forward unrecognized header fields unless the field name 1407 is listed in the Connection header field (Section 7.6.1) or the proxy 1408 is specifically configured to block, or otherwise transform, such 1409 fields. Other recipients SHOULD ignore unrecognized header and 1410 trailer fields. Adhering to these requirements allows HTTP's 1411 functionality to be extended without updating or removing deployed 1412 intermediaries. 1414 5.2. Field Lines and Combined Field Value 1416 Field sections are composed of any number of _field lines_, each with 1417 a _field name_ (see Section 5.1) identifying the field, and a _field 1418 line value_ that conveys data for that instance of the field. 1420 When a field name is only present once in a section, the combined 1421 _field value_ for that field consists of the corresponding field line 1422 value. When a field name is repeated within a section, its combined 1423 field value consists of the list of corresponding field line values 1424 within that section, concatenated in order, with each non-empty field 1425 line value separated by a comma. 1427 For example, this section: 1429 Example-Field: Foo, Bar 1430 Example-Field: Baz 1432 contains two field lines, both with the field name "Example-Field". 1433 The first field line has a field line value of "Foo, Bar", while the 1434 second field line value is "Baz". The field value for "Example- 1435 Field" is a list with three members: "Foo", "Bar", and "Baz". 1437 5.3. Field Order 1439 A recipient MAY combine multiple field lines within a field section 1440 that have the same field name into one field line, without changing 1441 the semantics of the message, by appending each subsequent field line 1442 value to the initial field line value in order, separated by a comma 1443 and OWS (optional whitespace). For consistency, use comma SP. 1445 The order in which field lines with the same name are received is 1446 therefore significant to the interpretation of the field value; a 1447 proxy MUST NOT change the order of these field line values when 1448 forwarding a message. 1450 This means that, aside from the well-known exception noted below, a 1451 sender MUST NOT generate multiple field lines with the same name in a 1452 message (whether in the headers or trailers), or append a field line 1453 when a field line of the same name already exists in the message, 1454 unless that field's definition allows multiple field line values to 1455 be recombined as a comma-separated list [i.e., at least one 1456 alternative of the field's definition allows a comma-separated list, 1457 such as an ABNF rule of #(values) defined in Section 5.6.1]. 1459 | *Note:* In practice, the "Set-Cookie" header field ([RFC6265]) 1460 | often appears in a response message across multiple field lines 1461 | and does not use the list syntax, violating the above 1462 | requirements on multiple field lines with the same field name. 1463 | Since it cannot be combined into a single field value, 1464 | recipients ought to handle "Set-Cookie" as a special case while 1465 | processing fields. (See Appendix A.2.3 of [Kri2001] for 1466 | details.) 1468 The order in which field lines with differing field names are 1469 received in a section is not significant. However, it is good 1470 practice to send header fields that contain additional control data 1471 first, such as Host on requests and Date on responses, so that 1472 implementations can decide when not to handle a message as early as 1473 possible. 1475 A server MUST NOT apply a request to the target resource until the 1476 entire request header section is received, since later header field 1477 lines might include conditionals, authentication credentials, or 1478 deliberately misleading duplicate header fields that would impact 1479 request processing. 1481 5.4. Field Limits 1483 HTTP does not place a predefined limit on the length of each field 1484 line, field value, or on the length of a header or trailer section as 1485 a whole, as described in Section 2. Various ad hoc limitations on 1486 individual lengths are found in practice, often depending on the 1487 specific field's semantics. 1489 A server that receives a request header field line, field value, or 1490 set of fields larger than it wishes to process MUST respond with an 1491 appropriate 4xx (Client Error) status code. Ignoring such header 1492 fields would increase the server's vulnerability to request smuggling 1493 attacks (Section 11.2 of [Messaging]). 1495 A client MAY discard or truncate received field lines that are larger 1496 than the client wishes to process if the field semantics are such 1497 that the dropped value(s) can be safely ignored without changing the 1498 message framing or response semantics. 1500 5.5. Field Values 1502 HTTP field values typically have their syntax defined using ABNF 1503 ([RFC5234]), using the extension defined in Section 5.6.1 as 1504 necessary, and are usually constrained to the range of US-ASCII 1505 characters. Fields needing a greater range of characters can use an 1506 encoding such as the one defined in [RFC8187]. 1508 field-value = *field-content 1509 field-content = field-vchar 1510 [ 1*( SP / HTAB / field-vchar ) field-vchar ] 1511 field-vchar = VCHAR / obs-text 1513 Historically, HTTP allowed field content with text in the ISO-8859-1 1514 charset [ISO-8859-1], supporting other charsets only through use of 1515 [RFC2047] encoding. In practice, most HTTP field values use only a 1516 subset of the US-ASCII charset [USASCII]. Newly defined fields 1517 SHOULD limit their values to US-ASCII octets. A recipient SHOULD 1518 treat other octets in field content (obs-text) as opaque data. 1520 Field values containing control (CTL) characters such as CR or LF are 1521 invalid; recipients MUST either reject a field value containing 1522 control characters, or convert them to SP before processing or 1523 forwarding the message. 1525 Leading and trailing whitespace in raw field values is removed upon 1526 field parsing (e.g., Section 5.1 of [Messaging]). Field definitions 1527 where leading or trailing whitespace in values is significant will 1528 have to use a container syntax such as quoted-string (Section 5.6.4). 1530 Commas (",") often are used to separate members in field values. 1531 Fields that allow multiple members are referred to as _list-based 1532 fields_. Fields that only anticipate a single member are referred to 1533 as _singleton fields_. 1535 Because commas are used as a generic delimiter between members, they 1536 need to be treated with care if they are allowed as data within a 1537 member. This is true for both list-based and singleton fields, since 1538 a singleton field might be sent with multiple members erroneously; 1539 being able to detect this condition improves interoperability. 1540 Fields that expect to contain a comma within a member, such as an 1541 HTTP-date or URI-reference element, ought to be defined with 1542 delimiters around that element to distinguish any comma within that 1543 data from potential list separators. 1545 For example, a textual date and a URI (either of which might contain 1546 a comma) could be safely carried in list-based field values like 1547 these: 1549 Example-URI-Field: "http://example.com/a.html,foo", 1550 "http://without-a-comma.example.com/" 1551 Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005" 1553 Note that double-quote delimiters almost always are used with the 1554 quoted-string production; using a different syntax inside double- 1555 quotes will likely cause unnecessary confusion. 1557 Many fields (such as Content-Type, defined in Section 8.3) use a 1558 common syntax for parameters that allows both unquoted (token) and 1559 quoted (quoted-string) syntax for a parameter value (Section 5.6.6). 1560 Use of common syntax allows recipients to reuse existing parser 1561 components. When allowing both forms, the meaning of a parameter 1562 value ought to be the same whether it was received as a token or a 1563 quoted string. 1565 Historically, HTTP field values could be extended over multiple lines 1566 by preceding each extra line with at least one space or horizontal 1567 tab (obs-fold). This document assumes that any such obsolete line 1568 folding has been replaced with one or more SP octets prior to 1569 interpreting the field value, as described in Section 5.2 of 1570 [Messaging]. 1572 | *Note:* This specification does not use ABNF rules to define 1573 | each "Field Name: Field Value" pair, as was done in earlier 1574 | editions (published before [RFC7230]). Instead, ABNF rules are 1575 | named according to each registered field name, wherein the rule 1576 | defines the valid grammar for that field's corresponding field 1577 | values (i.e., after the field value has been extracted by a 1578 | generic field parser). 1580 5.6. Common Rules for Defining Field Values 1582 5.6.1. Lists (#rule ABNF Extension) 1584 A #rule extension to the ABNF rules of [RFC5234] is used to improve 1585 readability in the definitions of some list-based field values. 1587 A construct "#" is defined, similar to "*", for defining comma- 1588 delimited lists of elements. The full form is "#element" 1589 indicating at least and at most elements, each separated by a 1590 single comma (",") and optional whitespace (OWS). 1592 5.6.1.1. Sender Requirements 1594 In any production that uses the list construct, a sender MUST NOT 1595 generate empty list elements. In other words, a sender MUST generate 1596 lists that satisfy the following syntax: 1598 1#element => element *( OWS "," OWS element ) 1600 and: 1602 #element => [ 1#element ] 1604 and for n >= 1 and m > 1: 1606 #element => element *( OWS "," OWS element ) 1608 Appendix A shows the collected ABNF for senders after the list 1609 constructs have been expanded. 1611 5.6.1.2. Recipient Requirements 1613 Empty elements do not contribute to the count of elements present. A 1614 recipient MUST parse and ignore a reasonable number of empty list 1615 elements: enough to handle common mistakes by senders that merge 1616 values, but not so much that they could be used as a denial-of- 1617 service mechanism. In other words, a recipient MUST accept lists 1618 that satisfy the following syntax: 1620 #element => [ element ] *( OWS "," OWS [ element ] ) 1622 Note that because of the potential presence of empty list elements, 1623 the RFC 5234 ABNF cannot enforce the cardinality of list elements, 1624 and consequently all cases are mapped as if there was no cardinality 1625 specified. 1627 For example, given these ABNF productions: 1629 example-list = 1#example-list-elmt 1630 example-list-elmt = token ; see Section 5.6.2 1632 Then the following are valid values for example-list (not including 1633 the double quotes, which are present for delimitation only): 1635 "foo,bar" 1636 "foo ,bar," 1637 "foo , ,bar,charlie" 1639 In contrast, the following values would be invalid, since at least 1640 one non-empty element is required by the example-list production: 1642 "" 1643 "," 1644 ", ," 1646 5.6.2. Tokens 1648 Many HTTP field values are defined using common syntax components, 1649 separated by whitespace or specific delimiting characters. 1650 Delimiters are chosen from the set of US-ASCII visual characters not 1651 allowed in a token (DQUOTE and "(),/:;<=>?@[\]{}"). 1653 Tokens are short textual identifiers that do not include whitespace 1654 or delimiters. 1656 token = 1*tchar 1658 tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" 1659 / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" 1660 / DIGIT / ALPHA 1661 ; any VCHAR, except delimiters 1663 5.6.3. Whitespace 1665 This specification uses three rules to denote the use of linear 1666 whitespace: OWS (optional whitespace), RWS (required whitespace), and 1667 BWS ("bad" whitespace). 1669 The OWS rule is used where zero or more linear whitespace octets 1670 might appear. For protocol elements where optional whitespace is 1671 preferred to improve readability, a sender SHOULD generate the 1672 optional whitespace as a single SP; otherwise, a sender SHOULD NOT 1673 generate optional whitespace except as needed to white out invalid or 1674 unwanted protocol elements during in-place message filtering. 1676 The RWS rule is used when at least one linear whitespace octet is 1677 required to separate field tokens. A sender SHOULD generate RWS as a 1678 single SP. 1680 OWS and RWS have the same semantics as a single SP. Any content 1681 known to be defined as OWS or RWS MAY be replaced with a single SP 1682 before interpreting it or forwarding the message downstream. 1684 The BWS rule is used where the grammar allows optional whitespace 1685 only for historical reasons. A sender MUST NOT generate BWS in 1686 messages. A recipient MUST parse for such bad whitespace and remove 1687 it before interpreting the protocol element. 1689 BWS has no semantics. Any content known to be defined as BWS MAY be 1690 removed before interpreting it or forwarding the message downstream. 1692 OWS = *( SP / HTAB ) 1693 ; optional whitespace 1694 RWS = 1*( SP / HTAB ) 1695 ; required whitespace 1696 BWS = OWS 1697 ; "bad" whitespace 1699 5.6.4. Quoted Strings 1701 A string of text is parsed as a single value if it is quoted using 1702 double-quote marks. 1704 quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE 1705 qdtext = HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text 1706 obs-text = %x80-FF 1708 The backslash octet ("\") can be used as a single-octet quoting 1709 mechanism within quoted-string and comment constructs. Recipients 1710 that process the value of a quoted-string MUST handle a quoted-pair 1711 as if it were replaced by the octet following the backslash. 1713 quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) 1715 A sender SHOULD NOT generate a quoted-pair in a quoted-string except 1716 where necessary to quote DQUOTE and backslash octets occurring within 1717 that string. A sender SHOULD NOT generate a quoted-pair in a comment 1718 except where necessary to quote parentheses ["(" and ")"] and 1719 backslash octets occurring within that comment. 1721 5.6.5. Comments 1723 Comments can be included in some HTTP fields by surrounding the 1724 comment text with parentheses. Comments are only allowed in fields 1725 containing "comment" as part of their field value definition. 1727 comment = "(" *( ctext / quoted-pair / comment ) ")" 1728 ctext = HTAB / SP / %x21-27 / %x2A-5B / %x5D-7E / obs-text 1730 5.6.6. Parameters 1732 Parameters are instances of name=value pairs; they are often used in 1733 field values as a common syntax for appending auxiliary information 1734 to an item. Each parameter is usually delimited by an immediately 1735 preceding semicolon. 1737 parameters = *( OWS ";" OWS [ parameter ] ) 1738 parameter = parameter-name "=" parameter-value 1739 parameter-name = token 1740 parameter-value = ( token / quoted-string ) 1742 Parameter names are case-insensitive. Parameter values might or 1743 might not be case-sensitive, depending on the semantics of the 1744 parameter name. Examples of parameters and some equivalent forms can 1745 be seen in media types (Section 8.3.1) and the Accept header field 1746 (Section 12.5.1). 1748 A parameter value that matches the token production can be 1749 transmitted either as a token or within a quoted-string. The quoted 1750 and unquoted values are equivalent. 1752 | *Note:* Parameters do not allow whitespace (not even "bad" 1753 | whitespace) around the "=" character. 1755 5.6.7. Date/Time Formats 1757 Prior to 1995, there were three different formats commonly used by 1758 servers to communicate timestamps. For compatibility with old 1759 implementations, all three are defined here. The preferred format is 1760 a fixed-length and single-zone subset of the date and time 1761 specification used by the Internet Message Format [RFC5322]. 1763 HTTP-date = IMF-fixdate / obs-date 1765 An example of the preferred format is 1767 Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate 1769 Examples of the two obsolete formats are 1771 Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format 1772 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format 1774 A recipient that parses a timestamp value in an HTTP field MUST 1775 accept all three HTTP-date formats. When a sender generates a field 1776 that contains one or more timestamps defined as HTTP-date, the sender 1777 MUST generate those timestamps in the IMF-fixdate format. 1779 An HTTP-date value represents time as an instance of Coordinated 1780 Universal Time (UTC). The first two formats indicate UTC by the 1781 three-letter abbreviation for Greenwich Mean Time, "GMT", a 1782 predecessor of the UTC name; values in the asctime format are assumed 1783 to be in UTC. A sender that generates HTTP-date values from a local 1784 clock ought to use NTP ([RFC5905]) or some similar protocol to 1785 synchronize its clock to UTC. 1787 Preferred format: 1789 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 1790 ; fixed length/zone/capitalization subset of the format 1791 ; see Section 3.3 of [RFC5322] 1793 day-name = %s"Mon" / %s"Tue" / %s"Wed" 1794 / %s"Thu" / %s"Fri" / %s"Sat" / %s"Sun" 1796 date1 = day SP month SP year 1797 ; e.g., 02 Jun 1982 1799 day = 2DIGIT 1800 month = %s"Jan" / %s"Feb" / %s"Mar" / %s"Apr" 1801 / %s"May" / %s"Jun" / %s"Jul" / %s"Aug" 1802 / %s"Sep" / %s"Oct" / %s"Nov" / %s"Dec" 1803 year = 4DIGIT 1805 GMT = %s"GMT" 1807 time-of-day = hour ":" minute ":" second 1808 ; 00:00:00 - 23:59:60 (leap second) 1810 hour = 2DIGIT 1811 minute = 2DIGIT 1812 second = 2DIGIT 1814 Obsolete formats: 1816 obs-date = rfc850-date / asctime-date 1817 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 1818 date2 = day "-" month "-" 2DIGIT 1819 ; e.g., 02-Jun-82 1821 day-name-l = %s"Monday" / %s"Tuesday" / %s"Wednesday" 1822 / %s"Thursday" / %s"Friday" / %s"Saturday" 1823 / %s"Sunday" 1825 asctime-date = day-name SP date3 SP time-of-day SP year 1826 date3 = month SP ( 2DIGIT / ( SP 1DIGIT )) 1827 ; e.g., Jun 2 1829 HTTP-date is case sensitive. Note that Section 4.2 of [Caching] 1830 relaxes this for cache recipients. 1832 A sender MUST NOT generate additional whitespace in an HTTP-date 1833 beyond that specifically included as SP in the grammar. The 1834 semantics of day-name, day, month, year, and time-of-day are the same 1835 as those defined for the Internet Message Format constructs with the 1836 corresponding name ([RFC5322], Section 3.3). 1838 Recipients of a timestamp value in rfc850-date format, which uses a 1839 two-digit year, MUST interpret a timestamp that appears to be more 1840 than 50 years in the future as representing the most recent year in 1841 the past that had the same last two digits. 1843 Recipients of timestamp values are encouraged to be robust in parsing 1844 timestamps unless otherwise restricted by the field definition. For 1845 example, messages are occasionally forwarded over HTTP from a non- 1846 HTTP source that might generate any of the date and time 1847 specifications defined by the Internet Message Format. 1849 | *Note:* HTTP requirements for the date/time stamp format apply 1850 | only to their usage within the protocol stream. 1851 | Implementations are not required to use these formats for user 1852 | presentation, request logging, etc. 1854 6. Message Abstraction 1856 Each major version of HTTP defines its own syntax for communicating 1857 messages. This section defines an abstract data type for HTTP 1858 messages based on a generalization of those message characteristics, 1859 common structure, and capacity for conveying semantics. This 1860 abstraction is used to define requirements on senders and recipients 1861 that are independent of the HTTP version, such that a message in one 1862 version can be relayed through other versions without changing its 1863 meaning. 1865 A _message_ consists of control data to describe and route the 1866 message, a headers lookup table of key/value pairs for extending that 1867 control data and conveying additional information about the sender, 1868 message, content, or context, a potentially unbounded stream of 1869 content, and a trailers lookup table of key/value pairs for 1870 communicating information obtained while sending the content. 1872 Framing and control data is sent first, followed by a header section 1873 containing fields for the headers table. When a message includes 1874 content, the content is sent after the header section and potentially 1875 interleaved with zero or more trailer sections containing fields for 1876 the trailers table. 1878 Messages are expected to be processed as a stream, wherein the 1879 purpose of that stream and its continued processing is revealed while 1880 being read. Hence, control data describes what the recipient needs 1881 to know immediately, header fields describe what needs to be known 1882 before receiving content, the content (when present) presumably 1883 contains what the recipient wants or needs to fulfill the message 1884 semantics, and trailer fields provide additional metadata that can be 1885 dropped (safely ignored) when not desired. 1887 Messages are intended to be _self-descriptive_: everything a 1888 recipient needs to know about the message can be determined by 1889 looking at the message itself, after decoding or reconstituting parts 1890 that have been compressed or elided in transit, without requiring an 1891 understanding of the sender's current application state (established 1892 via prior messages). 1894 Note that this message abstraction is a generalization across many 1895 versions of HTTP, including features that might not be found in some 1896 versions. For example, trailers were introduced within the HTTP/1.1 1897 chunked transfer coding as a single trailer section after the 1898 content. An equivalent feature is present in HTTP/2 and HTTP/3 1899 within the header block that terminates each stream. However, 1900 multiple trailer sections interleaved with content have only been 1901 deployed as frame extensions. 1903 6.1. Framing and Completeness 1905 Message framing indicates how each message begins and ends, such that 1906 each message can be distinguished from other messages or noise on the 1907 same connection. Each major version of HTTP defines its own framing 1908 mechanism. 1910 HTTP/0.9 and early deployments of HTTP/1.0 used closure of the 1911 underlying connection to end a response. For backwards 1912 compatibility, this implicit framing is also allowed in HTTP/1.1. 1914 However, implicit framing can fail to distinguish an incomplete 1915 response if the connection closes early. For that reason, almost all 1916 modern implementations use explicit framing in the form of length- 1917 delimited sequences of message data. 1919 A message is considered _complete_ when all of the octets indicated 1920 by its framing are available. Note that, when no explicit framing is 1921 used, a response message that is ended by the underlying connection's 1922 close is considered complete even though it might be 1923 indistinguishable from an incomplete response, unless a transport- 1924 level error indicates that it is not complete. 1926 6.2. Control Data 1928 Messages start with control data that describe its primary purpose. 1929 Request message control data includes a request method (Section 9), 1930 request target (Section 7.1), and protocol version (Section 2.5). 1931 Response message control data includes a status code (Section 15), 1932 optional reason phrase, and protocol version. 1934 In HTTP/1.1 [Messaging] and earlier, control data is sent as the 1935 first line of a message. In HTTP/2 ([RFC7540]) and HTTP/3 ([HTTP3]), 1936 control data is sent as pseudo-header fields with a reserved name 1937 prefix (e.g., ":authority"). 1939 Every HTTP message has a protocol version. Depending on the version 1940 in use, it might be identified within the message explicitly or 1941 inferred by the connection over which the message is received. 1942 Recipients use that version information to determine limitations or 1943 potential for later communication with that sender. 1945 When a message is forwarded by an intermediary, the protocol version 1946 is updated to reflect the version used by that intermediary. The Via 1947 header field (Section 7.6.3) is used to communicate upstream protocol 1948 information within a forwarded message. 1950 A client SHOULD send a request version equal to the highest version 1951 to which the client is conformant and whose major version is no 1952 higher than the highest version supported by the server, if this is 1953 known. A client MUST NOT send a version to which it is not 1954 conformant. 1956 A client MAY send a lower request version if it is known that the 1957 server incorrectly implements the HTTP specification, but only after 1958 the client has attempted at least one normal request and determined 1959 from the response status code or header fields (e.g., Server) that 1960 the server improperly handles higher request versions. 1962 A server SHOULD send a response version equal to the highest version 1963 to which the server is conformant that has a major version less than 1964 or equal to the one received in the request. A server MUST NOT send 1965 a version to which it is not conformant. A server can send a 505 1966 (HTTP Version Not Supported) response if it wishes, for any reason, 1967 to refuse service of the client's major protocol version. 1969 When an HTTP message is received with a major version number that the 1970 recipient implements, but a higher minor version number than what the 1971 recipient implements, the recipient SHOULD process the message as if 1972 it were in the highest minor version within that major version to 1973 which the recipient is conformant. A recipient can assume that a 1974 message with a higher minor version, when sent to a recipient that 1975 has not yet indicated support for that higher version, is 1976 sufficiently backwards-compatible to be safely processed by any 1977 implementation of the same major version. 1979 6.3. Header Fields 1981 Fields (Section 5) that are sent/received before the content are 1982 referred to as "header fields" (or just "headers", colloquially). 1984 The _header section_ of a message consists of a sequence of of header 1985 field lines. Each header field might modify or extend message 1986 semantics, describe the sender, define the content, or provide 1987 additional context. 1989 | *Note:* We refer to named fields specifically as a "header 1990 | field" when they are only allowed to be sent in the header 1991 | section. 1993 6.4. Content 1995 HTTP messages often transfer a complete or partial representation as 1996 the message _content_: a stream of octets sent after the header 1997 section, as delineated by the message framing. 1999 This abstract definition of content reflects the data after it has 2000 been extracted from the message framing. For example, an HTTP/1.1 2001 message body (Section 6 of [Messaging]) might consist of a stream of 2002 data encoded with the chunked transfer coding - a sequence of data 2003 chunks, one zero-length chunk, and a trailer section - whereas the 2004 content of that same message includes only the data stream after the 2005 transfer coding has been decoded; it does not include the chunk 2006 lengths, chunked framing syntax, nor the trailer fields 2007 (Section 6.5). 2009 6.4.1. Content Semantics 2011 The purpose of content in a request is defined by the method 2012 semantics (Section 9). 2014 For example, a representation in the content of a PUT request 2015 (Section 9.3.4) represents the desired state of the target resource 2016 after the request is successfully applied, whereas a representation 2017 in the content of a POST request (Section 9.3.3) represents 2018 information to be processed by the target resource. 2020 In a response, the content's purpose is defined by both the request 2021 method and the response status code (Section 15). For example, the 2022 content of a 200 (OK) response to GET (Section 9.3.1) represents the 2023 current state of the target resource, as observed at the time of the 2024 message origination date (Section 10.2.2), whereas the content of the 2025 same status code in a response to POST might represent either the 2026 processing result or the new state of the target resource after 2027 applying the processing. 2029 The content of a 206 (Partial Content) response to GET contains 2030 either a single part of the selected representation or a multipart 2031 message body containing multiple parts of that representation, as 2032 described in Section 15.3.7. 2034 Response messages with an error status code usually contain content 2035 that represents the error condition, such that the content describes 2036 the error state and what steps are suggested for resolving it. 2038 Responses to the HEAD request method (Section 9.3.2) never include 2039 content; the associated response header fields indicate only what 2040 their values would have been if the request method had been GET 2041 (Section 9.3.1). 2043 2xx (Successful) responses to a CONNECT request method 2044 (Section 9.3.6) switch the connection to tunnel mode instead of 2045 having content. 2047 All 1xx (Informational), 204 (No Content), and 304 (Not Modified) 2048 responses do not include content. 2050 All other responses do include content, although that content might 2051 be of zero length. 2053 6.4.2. Identifying Content 2055 When a complete or partial representation is transferred as message 2056 content, it is often desirable for the sender to supply, or the 2057 recipient to determine, an identifier for a resource corresponding to 2058 that representation. 2060 For a request message: 2062 o If the request has a Content-Location header field, then the 2063 sender asserts that the content is a representation of the 2064 resource identified by the Content-Location field value. However, 2065 such an assertion cannot be trusted unless it can be verified by 2066 other means (not defined by this specification). The information 2067 might still be useful for revision history links. 2069 o Otherwise, the content is unidentified. 2071 For a response message, the following rules are applied in order 2072 until a match is found: 2074 1. If the request method is HEAD or the response status code is 204 2075 (No Content) or 304 (Not Modified), there is no content in the 2076 response. 2078 2. If the request method is GET and the response status code is 200 2079 (OK), the content is a representation of the resource identified 2080 by the target URI (Section 7.1). 2082 3. If the request method is GET and the response status code is 203 2083 (Non-Authoritative Information), the content is a potentially 2084 modified or enhanced representation of the target resource as 2085 provided by an intermediary. 2087 4. If the request method is GET and the response status code is 206 2088 (Partial Content), the content is one or more parts of a 2089 representation of the resource identified by the target URI 2090 (Section 7.1). 2092 5. If the response has a Content-Location header field and its field 2093 value is a reference to the same URI as the target URI, the 2094 content is a representation of the target resource. 2096 6. If the response has a Content-Location header field and its field 2097 value is a reference to a URI different from the target URI, then 2098 the sender asserts that the content is a representation of the 2099 resource identified by the Content-Location field value. 2100 However, such an assertion cannot be trusted unless it can be 2101 verified by other means (not defined by this specification). 2103 7. Otherwise, the content is unidentified. 2105 6.5. Trailer Fields 2107 Fields (Section 5) that are sent/received after the header section 2108 has ended (usually after the content begins to stream) are referred 2109 to as "trailer fields" (or just "trailers", colloquially) and located 2110 within a _trailer section_. Trailer fields can be useful for 2111 supplying message integrity checks, digital signatures, delivery 2112 metrics, or post-processing status information. 2114 Trailer fields ought to be processed and stored separately from the 2115 fields in the header section to avoid contradicting message semantics 2116 known at the time the header section was complete. The presence or 2117 absence of certain header fields might impact choices made for the 2118 routing or processing of the message as a whole before the trailers 2119 are received; those choices cannot be unmade by the later discovery 2120 of trailer fields. 2122 6.5.1. Limitations on use of Trailers 2124 Trailer sections are only possible when supported by the version of 2125 HTTP in use and enabled by an explicit framing mechanism. For 2126 example, the chunked coding in HTTP/1.1 allows a trailer section to 2127 be sent after the content (Section 7.1.2 of [Messaging]). 2129 Many fields cannot be processed outside the header section because 2130 their evaluation is necessary prior to receiving the content, such as 2131 those that describe message framing, routing, authentication, request 2132 modifiers, response controls, or content format. A sender MUST NOT 2133 generate a trailer field unless the sender knows the corresponding 2134 header field name's definition permits the field to be sent in 2135 trailers. 2137 Trailer fields can be difficult to process by intermediaries that 2138 forward messages from one protocol version to another. If the entire 2139 message can be buffered in transit, some intermediaries could merge 2140 trailer fields into the header section (as appropriate) before it is 2141 forwarded. However, in most cases, the trailers are simply 2142 discarded. A recipient MUST NOT merge a trailer field into a header 2143 section unless the recipient understands the corresponding header 2144 field definition and that definition explicitly permits and defines 2145 how trailer field values can be safely merged. 2147 The presence of the keyword "trailers" in the TE header field 2148 (Section 10.1.4) indicates that the client is willing to accept 2149 trailer fields, on behalf of itself and any downstream clients. For 2150 requests from an intermediary, this implies that all downstream 2151 clients are willing to accept trailer fields in the forwarded 2152 response. Note that the presence of "trailers" does not mean that 2153 the client(s) will process any particular trailer field in the 2154 response; only that the trailer section(s) will not be dropped by any 2155 of the clients. 2157 Because of the potential for trailer fields to be discarded in 2158 transit, a server SHOULD NOT generate trailer fields that it believes 2159 are necessary for the user agent to receive. 2161 6.5.2. Processing Trailer Fields 2163 Like header fields, trailer fields with the same name are processed 2164 in the order received; multiple trailer field lines with the same 2165 name have the equivalent semantics as appending the multiple values 2166 as a list of members, even when the field lines are received in 2167 separate trailer sections. Trailer fields that might be generated 2168 more than once during a message MUST be defined as a list-based field 2169 even if each member value is only processed once per field line 2170 received. 2172 Trailer fields are expected (but not required) to be processed one 2173 trailer section at a time. That is, for each trailer section 2174 received, a recipient that is looking for trailer fields will parse 2175 the received section into fields, invoke any associated processing 2176 for those fields at that point in the message processing, and then 2177 append those fields to the set of trailer fields received for the 2178 overall message. 2180 This behavior allows for iterative processing of trailer fields that 2181 contain incremental signatures or mid-stream status information, and 2182 fields that might refer to each other's values within the same 2183 section. However, there is no guarantee that trailer sections won't 2184 shift in relation to the content stream, or won't be recombined (or 2185 dropped) in transit. Trailer fields that refer to data outside the 2186 present trailer section need to use self-descriptive references 2187 (i.e., refer to the data by name, ordinal position, or an octet 2188 range) rather than assume it is the data most recently received. 2190 Likewise, at the end of a message, a recipient MAY treat the entire 2191 set of received trailer fields as one data structure to be considered 2192 as the message concludes. Additional processing expectations, if 2193 any, can be defined within the field specification for a field 2194 intended for use in trailers. 2196 7. Routing HTTP Messages 2198 HTTP request message routing is determined by each client based on 2199 the target resource, the client's proxy configuration, and 2200 establishment or reuse of an inbound connection. The corresponding 2201 response routing follows the same connection chain back to the 2202 client. 2204 7.1. Determining the Target Resource 2206 Although HTTP is used in a wide variety of applications, most clients 2207 rely on the same resource identification mechanism and configuration 2208 techniques as general-purpose Web browsers. Even when communication 2209 options are hard-coded in a client's configuration, we can think of 2210 their combined effect as a URI reference (Section 4.1). 2212 A URI reference is resolved to its absolute form in order to obtain 2213 the _target URI_. The target URI excludes the reference's fragment 2214 component, if any, since fragment identifiers are reserved for 2215 client-side processing ([RFC3986], Section 3.5). 2217 To perform an action on a _target resource_, the client sends a 2218 request message containing enough components of its parsed target URI 2219 to enable recipients to identify that same resource. For historical 2220 reasons, the parsed target URI components, collectively referred to 2221 as the _request target_, are sent within the message control data and 2222 the Host header field (Section 7.2). 2224 There are two unusual cases for which the request target components 2225 are in a method-specific form: 2227 o For CONNECT (Section 9.3.6), the request target is the host name 2228 and port number of the tunnel destination, separated by a colon. 2230 o For OPTIONS (Section 9.3.7), the request target can be a single 2231 asterisk ("*"). 2233 See the respective method definitions for details. These forms MUST 2234 NOT be used with other methods. 2236 Upon receipt of a client's request, a server reconstructs the target 2237 URI from the received components in accordance with their local 2238 configuration and incoming connection context. This reconstruction 2239 is specific to each major protocol version. For example, Appendix of 2240 [Messaging] defines how a server determines the target URI of an 2241 HTTP/1.1 request. 2243 | *Note:* Previous specifications defined the recomposed target 2244 | URI as a distinct concept, the _effective request URI_. 2246 7.2. Host and :authority 2248 The "Host" header field in a request provides the host and port 2249 information from the target URI, enabling the origin server to 2250 distinguish among resources while servicing requests for multiple 2251 host names. 2253 In HTTP/2 [RFC7540] and HTTP/3 [HTTP3], the Host header field is, in 2254 some cases, supplanted by the ":authority" pseudo-header field of a 2255 request's control data. 2257 Host = uri-host [ ":" port ] ; Section 4 2259 The target URI's authority information is critical for handling a 2260 request. A user agent SHOULD generate Host as the first field in the 2261 header section of a request unless it has already generated that 2262 information as an ":authority" pseudo-header field. 2264 For example, a GET request to the origin server for 2265 would begin with: 2267 GET /pub/WWW/ HTTP/1.1 2268 Host: www.example.org 2270 Since the host and port information acts as an application-level 2271 routing mechanism, it is a frequent target for malware seeking to 2272 poison a shared cache or redirect a request to an unintended server. 2273 An interception proxy is particularly vulnerable if it relies on the 2274 host and port information for redirecting requests to internal 2275 servers, or for use as a cache key in a shared cache, without first 2276 verifying that the intercepted connection is targeting a valid IP 2277 address for that host. 2279 7.3. Routing Inbound Requests 2281 Once the target URI and its origin are determined, a client decides 2282 whether a network request is necessary to accomplish the desired 2283 semantics and, if so, where that request is to be directed. 2285 7.3.1. To a Cache 2287 If the client has a cache [Caching] and the request can be satisfied 2288 by it, then the request is usually directed there first. 2290 7.3.2. To a Proxy 2292 If the request is not satisfied by a cache, then a typical client 2293 will check its configuration to determine whether a proxy is to be 2294 used to satisfy the request. Proxy configuration is implementation- 2295 dependent, but is often based on URI prefix matching, selective 2296 authority matching, or both, and the proxy itself is usually 2297 identified by an "http" or "https" URI. If a proxy is applicable, 2298 the client connects inbound by establishing (or reusing) a connection 2299 to that proxy. 2301 7.3.3. To the Origin 2303 If no proxy is applicable, a typical client will invoke a handler 2304 routine, usually specific to the target URI's scheme, to connect 2305 directly to an origin for the target resource. How that is 2306 accomplished is dependent on the target URI scheme and defined by its 2307 associated specification. 2309 7.4. Rejecting Misdirected Requests 2311 Before performing a request, a server decides whether or not to 2312 provide service for the target URI via the connection in which the 2313 request is received. For example, a request might have been 2314 misdirected, deliberately or accidentally, such that the information 2315 within a received Host header field differs from the connection's 2316 host or port. 2318 If the connection is from a trusted gateway, such inconsistency might 2319 be expected; otherwise, it might indicate an attempt to bypass 2320 security filters, trick the server into delivering non-public 2321 content, or poison a cache. See Section 17 for security 2322 considerations regarding message routing. 2324 The 421 (Misdirected Request) status code in a response indicates 2325 that the origin server has rejected the request because it appears to 2326 have been misdirected (Section 15.5.20). 2328 7.5. Response Correlation 2330 A connection might be used for multiple request/response exchanges. 2331 The mechanism used to correlate between request and response messages 2332 is version dependent; some versions of HTTP use implicit ordering of 2333 messages, while others use an explicit identifier. 2335 Responses (both final and interim) can be sent at any time after a 2336 request is received, even if it is not yet complete. However, 2337 clients (including intermediaries) might abandon a request if the 2338 response is not forthcoming within a reasonable period of time. 2340 7.6. Message Forwarding 2342 As described in Section 3.7, intermediaries can serve a variety of 2343 roles in the processing of HTTP requests and responses. Some 2344 intermediaries are used to improve performance or availability. 2345 Others are used for access control or to filter content. Since an 2346 HTTP stream has characteristics similar to a pipe-and-filter 2347 architecture, there are no inherent limits to the extent an 2348 intermediary can enhance (or interfere) with either direction of the 2349 stream. 2351 An intermediary not acting as a tunnel MUST implement the Connection 2352 header field, as specified in Section 7.6.1, and exclude fields from 2353 being forwarded that are only intended for the incoming connection. 2355 An intermediary MUST NOT forward a message to itself unless it is 2356 protected from an infinite request loop. In general, an intermediary 2357 ought to recognize its own server names, including any aliases, local 2358 variations, or literal IP addresses, and respond to such requests 2359 directly. 2361 An HTTP message can be parsed as a stream for incremental processing 2362 or forwarding downstream. However, recipients cannot rely on 2363 incremental delivery of partial messages, since some implementations 2364 will buffer or delay message forwarding for the sake of network 2365 efficiency, security checks, or content transformations. 2367 7.6.1. Connection 2369 The "Connection" header field allows the sender to list desired 2370 control options for the current connection. 2372 When a field aside from Connection is used to supply control 2373 information for or about the current connection, the sender MUST list 2374 the corresponding field name within the Connection header field. 2375 Note that some versions of HTTP prohibit the use of fields for such 2376 information, and therefore do not allow the Connection field. 2378 Intermediaries MUST parse a received Connection header field before a 2379 message is forwarded and, for each connection-option in this field, 2380 remove any header or trailer field(s) from the message with the same 2381 name as the connection-option, and then remove the Connection header 2382 field itself (or replace it with the intermediary's own connection 2383 options for the forwarded message). 2385 Hence, the Connection header field provides a declarative way of 2386 distinguishing fields that are only intended for the immediate 2387 recipient ("hop-by-hop") from those fields that are intended for all 2388 recipients on the chain ("end-to-end"), enabling the message to be 2389 self-descriptive and allowing future connection-specific extensions 2390 to be deployed without fear that they will be blindly forwarded by 2391 older intermediaries. 2393 Furthermore, intermediaries SHOULD remove or replace field(s) whose 2394 semantics are known to require removal before forwarding, whether or 2395 not they appear as a Connection option, after applying those fields' 2396 semantics. This includes but is not limited to: 2398 o Proxy-Connection (Appendix C.2.2 of [Messaging]) 2400 o Keep-Alive (Section 19.7.1 of [RFC2068]) 2402 o TE (Section 10.1.4) 2404 o Trailer (Section 10.1.5) 2406 o Transfer-Encoding (Section 6.1 of [Messaging]) 2408 o Upgrade (Section 7.8) 2410 The Connection header field's value has the following grammar: 2412 Connection = #connection-option 2413 connection-option = token 2415 Connection options are case-insensitive. 2417 A sender MUST NOT send a connection option corresponding to a field 2418 that is intended for all recipients of the content. For example, 2419 Cache-Control is never appropriate as a connection option 2420 (Section 5.2 of [Caching]). 2422 The connection options do not always correspond to a field present in 2423 the message, since a connection-specific field might not be needed if 2424 there are no parameters associated with a connection option. In 2425 contrast, a connection-specific field that is received without a 2426 corresponding connection option usually indicates that the field has 2427 been improperly forwarded by an intermediary and ought to be ignored 2428 by the recipient. 2430 When defining new connection options, specification authors ought to 2431 document it as reserved field name and register that definition in 2432 the Hypertext Transfer Protocol (HTTP) Field Name Registry 2433 (Section 16.3.1), to avoid collisions. 2435 7.6.2. Max-Forwards 2437 The "Max-Forwards" header field provides a mechanism with the TRACE 2438 (Section 9.3.8) and OPTIONS (Section 9.3.7) request methods to limit 2439 the number of times that the request is forwarded by proxies. This 2440 can be useful when the client is attempting to trace a request that 2441 appears to be failing or looping mid-chain. 2443 Max-Forwards = 1*DIGIT 2445 The Max-Forwards value is a decimal integer indicating the remaining 2446 number of times this request message can be forwarded. 2448 Each intermediary that receives a TRACE or OPTIONS request containing 2449 a Max-Forwards header field MUST check and update its value prior to 2450 forwarding the request. If the received value is zero (0), the 2451 intermediary MUST NOT forward the request; instead, the intermediary 2452 MUST respond as the final recipient. If the received Max-Forwards 2453 value is greater than zero, the intermediary MUST generate an updated 2454 Max-Forwards field in the forwarded message with a field value that 2455 is the lesser of a) the received value decremented by one (1) or b) 2456 the recipient's maximum supported value for Max-Forwards. 2458 A recipient MAY ignore a Max-Forwards header field received with any 2459 other request methods. 2461 7.6.3. Via 2463 The "Via" header field indicates the presence of intermediate 2464 protocols and recipients between the user agent and the server (on 2465 requests) or between the origin server and the client (on responses), 2466 similar to the "Received" header field in email (Section 3.6.7 of 2467 [RFC5322]). Via can be used for tracking message forwards, avoiding 2468 request loops, and identifying the protocol capabilities of senders 2469 along the request/response chain. 2471 Via = #( received-protocol RWS received-by [ RWS comment ] ) 2473 received-protocol = [ protocol-name "/" ] protocol-version 2474 ; see Section 7.8 2475 received-by = pseudonym [ ":" port ] 2476 pseudonym = token 2478 Each member of the Via field value represents a proxy or gateway that 2479 has forwarded the message. Each intermediary appends its own 2480 information about how the message was received, such that the end 2481 result is ordered according to the sequence of forwarding recipients. 2483 A proxy MUST send an appropriate Via header field, as described 2484 below, in each message that it forwards. An HTTP-to-HTTP gateway 2485 MUST send an appropriate Via header field in each inbound request 2486 message and MAY send a Via header field in forwarded response 2487 messages. 2489 For each intermediary, the received-protocol indicates the protocol 2490 and protocol version used by the upstream sender of the message. 2491 Hence, the Via field value records the advertised protocol 2492 capabilities of the request/response chain such that they remain 2493 visible to downstream recipients; this can be useful for determining 2494 what backwards-incompatible features might be safe to use in 2495 response, or within a later request, as described in Section 2.5. 2496 For brevity, the protocol-name is omitted when the received protocol 2497 is HTTP. 2499 The received-by portion is normally the host and optional port number 2500 of a recipient server or client that subsequently forwarded the 2501 message. However, if the real host is considered to be sensitive 2502 information, a sender MAY replace it with a pseudonym. If a port is 2503 not provided, a recipient MAY interpret that as meaning it was 2504 received on the default TCP port, if any, for the received-protocol. 2506 A sender MAY generate comments to identify the software of each 2507 recipient, analogous to the User-Agent and Server header fields. 2508 However, comments in Via are optional, and a recipient MAY remove 2509 them prior to forwarding the message. 2511 For example, a request message could be sent from an HTTP/1.0 user 2512 agent to an internal proxy code-named "fred", which uses HTTP/1.1 to 2513 forward the request to a public proxy at p.example.net, which 2514 completes the request by forwarding it to the origin server at 2515 www.example.com. The request received by www.example.com would then 2516 have the following Via header field: 2518 Via: 1.0 fred, 1.1 p.example.net 2520 An intermediary used as a portal through a network firewall SHOULD 2521 NOT forward the names and ports of hosts within the firewall region 2522 unless it is explicitly enabled to do so. If not enabled, such an 2523 intermediary SHOULD replace each received-by host of any host behind 2524 the firewall by an appropriate pseudonym for that host. 2526 An intermediary MAY combine an ordered subsequence of Via header 2527 field list members into a single member if the entries have identical 2528 received-protocol values. For example, 2530 Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy 2532 could be collapsed to 2534 Via: 1.0 ricky, 1.1 mertz, 1.0 lucy 2536 A sender SHOULD NOT combine multiple list members unless they are all 2537 under the same organizational control and the hosts have already been 2538 replaced by pseudonyms. A sender MUST NOT combine members that have 2539 different received-protocol values. 2541 7.7. Message Transformations 2543 Some intermediaries include features for transforming messages and 2544 their content. A proxy might, for example, convert between image 2545 formats in order to save cache space or to reduce the amount of 2546 traffic on a slow link. However, operational problems might occur 2547 when these transformations are applied to content intended for 2548 critical applications, such as medical imaging or scientific data 2549 analysis, particularly when integrity checks or digital signatures 2550 are used to ensure that the content received is identical to the 2551 original. 2553 An HTTP-to-HTTP proxy is called a _transforming proxy_ if it is 2554 designed or configured to modify messages in a semantically 2555 meaningful way (i.e., modifications, beyond those required by normal 2556 HTTP processing, that change the message in a way that would be 2557 significant to the original sender or potentially significant to 2558 downstream recipients). For example, a transforming proxy might be 2559 acting as a shared annotation server (modifying responses to include 2560 references to a local annotation database), a malware filter, a 2561 format transcoder, or a privacy filter. Such transformations are 2562 presumed to be desired by whichever client (or client organization) 2563 chose the proxy. 2565 If a proxy receives a target URI with a host name that is not a fully 2566 qualified domain name, it MAY add its own domain to the host name it 2567 received when forwarding the request. A proxy MUST NOT change the 2568 host name if the target URI contains a fully qualified domain name. 2570 A proxy MUST NOT modify the "absolute-path" and "query" parts of the 2571 received target URI when forwarding it to the next inbound server, 2572 except as noted above to replace an empty path with "/" or "*". 2574 A proxy MUST NOT transform the content (Section 6.4) of a message 2575 that contains a no-transform cache-control response directive 2576 (Section 5.2 of [Caching]). Note that this does not include changes 2577 to the message body that do not affect the content, such as transfer 2578 codings (Section 7 of [Messaging]). 2580 A proxy MAY transform the content of a message that does not contain 2581 a no-transform cache-control directive. A proxy that transforms the 2582 content of a 200 (OK) response can inform downstream recipients that 2583 a transformation has been applied by changing the response status 2584 code to 203 (Non-Authoritative Information) (Section 15.3.4). 2586 A proxy SHOULD NOT modify header fields that provide information 2587 about the endpoints of the communication chain, the resource state, 2588 or the selected representation (other than the content) unless the 2589 field's definition specifically allows such modification or the 2590 modification is deemed necessary for privacy or security. 2592 7.8. Upgrade 2594 The "Upgrade" header field is intended to provide a simple mechanism 2595 for transitioning from HTTP/1.1 to some other protocol on the same 2596 connection. 2598 A client MAY send a list of protocol names in the Upgrade header 2599 field of a request to invite the server to switch to one or more of 2600 the named protocols, in order of descending preference, before 2601 sending the final response. A server MAY ignore a received Upgrade 2602 header field if it wishes to continue using the current protocol on 2603 that connection. Upgrade cannot be used to insist on a protocol 2604 change. 2606 Upgrade = #protocol 2608 protocol = protocol-name ["/" protocol-version] 2609 protocol-name = token 2610 protocol-version = token 2612 Although protocol names are registered with a preferred case, 2613 recipients SHOULD use case-insensitive comparison when matching each 2614 protocol-name to supported protocols. 2616 A server that sends a 101 (Switching Protocols) response MUST send an 2617 Upgrade header field to indicate the new protocol(s) to which the 2618 connection is being switched; if multiple protocol layers are being 2619 switched, the sender MUST list the protocols in layer-ascending 2620 order. A server MUST NOT switch to a protocol that was not indicated 2621 by the client in the corresponding request's Upgrade header field. A 2622 server MAY choose to ignore the order of preference indicated by the 2623 client and select the new protocol(s) based on other factors, such as 2624 the nature of the request or the current load on the server. 2626 A server that sends a 426 (Upgrade Required) response MUST send an 2627 Upgrade header field to indicate the acceptable protocols, in order 2628 of descending preference. 2630 A server MAY send an Upgrade header field in any other response to 2631 advertise that it implements support for upgrading to the listed 2632 protocols, in order of descending preference, when appropriate for a 2633 future request. 2635 The following is a hypothetical example sent by a client: 2637 GET /hello HTTP/1.1 2638 Host: www.example.com 2639 Connection: upgrade 2640 Upgrade: websocket, IRC/6.9, RTA/x11 2642 The capabilities and nature of the application-level communication 2643 after the protocol change is entirely dependent upon the new 2644 protocol(s) chosen. However, immediately after sending the 101 2645 (Switching Protocols) response, the server is expected to continue 2646 responding to the original request as if it had received its 2647 equivalent within the new protocol (i.e., the server still has an 2648 outstanding request to satisfy after the protocol has been changed, 2649 and is expected to do so without requiring the request to be 2650 repeated). 2652 For example, if the Upgrade header field is received in a GET request 2653 and the server decides to switch protocols, it first responds with a 2654 101 (Switching Protocols) message in HTTP/1.1 and then immediately 2655 follows that with the new protocol's equivalent of a response to a 2656 GET on the target resource. This allows a connection to be upgraded 2657 to protocols with the same semantics as HTTP without the latency cost 2658 of an additional round trip. A server MUST NOT switch protocols 2659 unless the received message semantics can be honored by the new 2660 protocol; an OPTIONS request can be honored by any protocol. 2662 The following is an example response to the above hypothetical 2663 request: 2665 HTTP/1.1 101 Switching Protocols 2666 Connection: upgrade 2667 Upgrade: websocket 2669 [... data stream switches to websocket with an appropriate response 2670 (as defined by new protocol) to the "GET /hello" request ...] 2672 When Upgrade is sent, the sender MUST also send a Connection header 2673 field (Section 7.6.1) that contains an "upgrade" connection option, 2674 in order to prevent Upgrade from being accidentally forwarded by 2675 intermediaries that might not implement the listed protocols. A 2676 server MUST ignore an Upgrade header field that is received in an 2677 HTTP/1.0 request. 2679 A client cannot begin using an upgraded protocol on the connection 2680 until it has completely sent the request message (i.e., the client 2681 can't change the protocol it is sending in the middle of a message). 2682 If a server receives both an Upgrade and an Expect header field with 2683 the "100-continue" expectation (Section 10.1.1), the server MUST send 2684 a 100 (Continue) response before sending a 101 (Switching Protocols) 2685 response. 2687 The Upgrade header field only applies to switching protocols on top 2688 of the existing connection; it cannot be used to switch the 2689 underlying connection (transport) protocol, nor to switch the 2690 existing communication to a different connection. For those 2691 purposes, it is more appropriate to use a 3xx (Redirection) response 2692 (Section 15.4). 2694 This specification only defines the protocol name "HTTP" for use by 2695 the family of Hypertext Transfer Protocols, as defined by the HTTP 2696 version rules of Section 2.5 and future updates to this 2697 specification. Additional protocol names ought to be registered 2698 using the registration procedure defined in Section 16.7. 2700 8. Representation Data and Metadata 2702 8.1. Representation Data 2704 The representation data associated with an HTTP message is either 2705 provided as the content of the message or referred to by the message 2706 semantics and the target URI. The representation data is in a format 2707 and encoding defined by the representation metadata header fields. 2709 The data type of the representation data is determined via the header 2710 fields Content-Type and Content-Encoding. These define a two-layer, 2711 ordered encoding model: 2713 representation-data := Content-Encoding( Content-Type( bits ) ) 2715 8.2. Representation Metadata 2717 Representation header fields provide metadata about the 2718 representation. When a message includes content, the representation 2719 header fields describe how to interpret that data. In a response to 2720 a HEAD request, the representation header fields describe the 2721 representation data that would have been enclosed in the content if 2722 the same request had been a GET. 2724 8.3. Content-Type 2726 The "Content-Type" header field indicates the media type of the 2727 associated representation: either the representation enclosed in the 2728 message content or the selected representation, as determined by the 2729 message semantics. The indicated media type defines both the data 2730 format and how that data is intended to be processed by a recipient, 2731 within the scope of the received message semantics, after any content 2732 codings indicated by Content-Encoding are decoded. 2734 Content-Type = media-type 2736 Media types are defined in Section 8.3.1. An example of the field is 2738 Content-Type: text/html; charset=ISO-8859-4 2740 A sender that generates a message containing content SHOULD generate 2741 a Content-Type header field in that message unless the intended media 2742 type of the enclosed representation is unknown to the sender. If a 2743 Content-Type header field is not present, the recipient MAY either 2744 assume a media type of "application/octet-stream" ([RFC2046], 2745 Section 4.5.1) or examine the data to determine its type. 2747 In practice, resource owners do not always properly configure their 2748 origin server to provide the correct Content-Type for a given 2749 representation. Some user agents examine the content and, in certain 2750 cases, override the received type (for example, see [Sniffing]). 2751 This "MIME sniffing" risks drawing incorrect conclusions about the 2752 data, which might expose the user to additional security risks (e.g., 2753 "privilege escalation"). Furthermore, it is impossible to determine 2754 the sender's intended processing model by examining the data format: 2755 many data formats match multiple media types that differ only in 2756 processing semantics. Implementers are encouraged to provide a means 2757 to disable such sniffing. 2759 Furthermore, although Content-Type is defined as a singleton field, 2760 it is sometimes incorrectly generated multiple times, resulting in a 2761 combined field value that appears to be a list. Recipients often 2762 attempt to handle this error by using the last syntactically valid 2763 member of the list, but note that some implementations might have 2764 different error handling behaviors, leading to interoperability and/ 2765 or security issues. 2767 8.3.1. Media Type 2769 HTTP uses media types [RFC2046] in the Content-Type (Section 8.3) and 2770 Accept (Section 12.5.1) header fields in order to provide open and 2771 extensible data typing and type negotiation. Media types define both 2772 a data format and various processing models: how to process that data 2773 in accordance with each context in which it is received. 2775 media-type = type "/" subtype parameters 2776 type = token 2777 subtype = token 2779 The type and subtype tokens are case-insensitive. 2781 The type/subtype MAY be followed by semicolon-delimited parameters 2782 (Section 5.6.6) in the form of name=value pairs. The presence or 2783 absence of a parameter might be significant to the processing of a 2784 media type, depending on its definition within the media type 2785 registry. Parameter values might or might not be case-sensitive, 2786 depending on the semantics of the parameter name. 2788 For example, the following media types are equivalent in describing 2789 HTML text data encoded in the UTF-8 character encoding scheme, but 2790 the first is preferred for consistency (the "charset" parameter value 2791 is defined as being case-insensitive in [RFC2046], Section 4.1.2): 2793 text/html;charset=utf-8 2794 Text/HTML;Charset="utf-8" 2795 text/html; charset="utf-8" 2796 text/html;charset=UTF-8 2798 Media types ought to be registered with IANA according to the 2799 procedures defined in [BCP13]. 2801 8.3.2. Charset 2803 HTTP uses _charset_ names to indicate or negotiate the character 2804 encoding scheme of a textual representation [RFC6365]. A charset is 2805 identified by a case-insensitive token. 2807 charset = token 2809 Charset names ought to be registered in the IANA "Character Sets" 2810 registry () 2811 according to the procedures defined in Section 2 of [RFC2978]. 2813 | *Note:* In theory, charset names are defined by the "mime- 2814 | charset" ABNF rule defined in Section 2.3 of [RFC2978] (as 2815 | corrected in [Err1912]). That rule allows two characters that 2816 | are not included in "token" ("{" and "}"), but no charset name 2817 | registered at the time of this writing includes braces (see 2818 | [Err5433]). 2820 8.3.3. Canonicalization and Text Defaults 2822 Media types are registered with a canonical form in order to be 2823 interoperable among systems with varying native encoding formats. 2824 Representations selected or transferred via HTTP ought to be in 2825 canonical form, for many of the same reasons described by the 2826 Multipurpose Internet Mail Extensions (MIME) [RFC2045]. However, the 2827 performance characteristics of email deployments (i.e., store and 2828 forward messages to peers) are significantly different from those 2829 common to HTTP and the Web (server-based information services). 2830 Furthermore, MIME's constraints for the sake of compatibility with 2831 older mail transfer protocols do not apply to HTTP (see Appendix B of 2832 [Messaging]). 2834 MIME's canonical form requires that media subtypes of the "text" type 2835 use CRLF as the text line break. HTTP allows the transfer of text 2836 media with plain CR or LF alone representing a line break, when such 2837 line breaks are consistent for an entire representation. An HTTP 2838 sender MAY generate, and a recipient MUST be able to parse, line 2839 breaks in text media that consist of CRLF, bare CR, or bare LF. In 2840 addition, text media in HTTP is not limited to charsets that use 2841 octets 13 and 10 for CR and LF, respectively. This flexibility 2842 regarding line breaks applies only to text within a representation 2843 that has been assigned a "text" media type; it does not apply to 2844 "multipart" types or HTTP elements outside the content (e.g., header 2845 fields). 2847 If a representation is encoded with a content-coding, the underlying 2848 data ought to be in a form defined above prior to being encoded. 2850 8.3.4. Multipart Types 2852 MIME provides for a number of "multipart" types - encapsulations of 2853 one or more representations within a single message body. All 2854 multipart types share a common syntax, as defined in Section 5.1.1 of 2855 [RFC2046], and include a boundary parameter as part of the media type 2856 value. The message body is itself a protocol element; a sender MUST 2857 generate only CRLF to represent line breaks between body parts. 2859 HTTP message framing does not use the multipart boundary as an 2860 indicator of message body length, though it might be used by 2861 implementations that generate or process the content. For example, 2862 the "multipart/form-data" type is often used for carrying form data 2863 in a request, as described in [RFC7578], and the "multipart/ 2864 byteranges" type is defined by this specification for use in some 206 2865 (Partial Content) responses (see Section 15.3.7). 2867 8.4. Content-Encoding 2869 The "Content-Encoding" header field indicates what content codings 2870 have been applied to the representation, beyond those inherent in the 2871 media type, and thus what decoding mechanisms have to be applied in 2872 order to obtain data in the media type referenced by the Content-Type 2873 header field. Content-Encoding is primarily used to allow a 2874 representation's data to be compressed without losing the identity of 2875 its underlying media type. 2877 Content-Encoding = #content-coding 2879 An example of its use is 2881 Content-Encoding: gzip 2883 If one or more encodings have been applied to a representation, the 2884 sender that applied the encodings MUST generate a Content-Encoding 2885 header field that lists the content codings in the order in which 2886 they were applied. Note that the coding named "identity" is reserved 2887 for its special role in Accept-Encoding, and thus SHOULD NOT be 2888 included. 2890 Additional information about the encoding parameters can be provided 2891 by other header fields not defined by this specification. 2893 Unlike Transfer-Encoding (Section 6.1 of [Messaging]), the codings 2894 listed in Content-Encoding are a characteristic of the 2895 representation; the representation is defined in terms of the coded 2896 form, and all other metadata about the representation is about the 2897 coded form unless otherwise noted in the metadata definition. 2898 Typically, the representation is only decoded just prior to rendering 2899 or analogous usage. 2901 If the media type includes an inherent encoding, such as a data 2902 format that is always compressed, then that encoding would not be 2903 restated in Content-Encoding even if it happens to be the same 2904 algorithm as one of the content codings. Such a content coding would 2905 only be listed if, for some bizarre reason, it is applied a second 2906 time to form the representation. Likewise, an origin server might 2907 choose to publish the same data as multiple representations that 2908 differ only in whether the coding is defined as part of Content-Type 2909 or Content-Encoding, since some user agents will behave differently 2910 in their handling of each response (e.g., open a "Save as ..." dialog 2911 instead of automatic decompression and rendering of content). 2913 An origin server MAY respond with a status code of 415 (Unsupported 2914 Media Type) if a representation in the request message has a content 2915 coding that is not acceptable. 2917 8.4.1. Content Codings 2919 Content coding values indicate an encoding transformation that has 2920 been or can be applied to a representation. Content codings are 2921 primarily used to allow a representation to be compressed or 2922 otherwise usefully transformed without losing the identity of its 2923 underlying media type and without loss of information. Frequently, 2924 the representation is stored in coded form, transmitted directly, and 2925 only decoded by the final recipient. 2927 content-coding = token 2929 All content codings are case-insensitive and ought to be registered 2930 within the "HTTP Content Coding Registry", as described in 2931 Section 16.6 2933 Content-coding values are used in the Accept-Encoding 2934 (Section 12.5.3) and Content-Encoding (Section 8.4) header fields. 2936 8.4.1.1. Compress Coding 2938 The "compress" coding is an adaptive Lempel-Ziv-Welch (LZW) coding 2939 [Welch] that is commonly produced by the UNIX file compression 2940 program "compress". A recipient SHOULD consider "x-compress" to be 2941 equivalent to "compress". 2943 8.4.1.2. Deflate Coding 2945 The "deflate" coding is a "zlib" data format [RFC1950] containing a 2946 "deflate" compressed data stream [RFC1951] that uses a combination of 2947 the Lempel-Ziv (LZ77) compression algorithm and Huffman coding. 2949 | *Note:* Some non-conformant implementations send the "deflate" 2950 | compressed data without the zlib wrapper. 2952 8.4.1.3. Gzip Coding 2954 The "gzip" coding is an LZ77 coding with a 32-bit Cyclic Redundancy 2955 Check (CRC) that is commonly produced by the gzip file compression 2956 program [RFC1952]. A recipient SHOULD consider "x-gzip" to be 2957 equivalent to "gzip". 2959 8.5. Content-Language 2961 The "Content-Language" header field describes the natural language(s) 2962 of the intended audience for the representation. Note that this 2963 might not be equivalent to all the languages used within the 2964 representation. 2966 Content-Language = #language-tag 2968 Language tags are defined in Section 8.5.1. The primary purpose of 2969 Content-Language is to allow a user to identify and differentiate 2970 representations according to the users' own preferred language. 2971 Thus, if the content is intended only for a Danish-literate audience, 2972 the appropriate field is 2974 Content-Language: da 2976 If no Content-Language is specified, the default is that the content 2977 is intended for all language audiences. This might mean that the 2978 sender does not consider it to be specific to any natural language, 2979 or that the sender does not know for which language it is intended. 2981 Multiple languages MAY be listed for content that is intended for 2982 multiple audiences. For example, a rendition of the "Treaty of 2983 Waitangi", presented simultaneously in the original Maori and English 2984 versions, would call for 2986 Content-Language: mi, en 2988 However, just because multiple languages are present within a 2989 representation does not mean that it is intended for multiple 2990 linguistic audiences. An example would be a beginner's language 2991 primer, such as "A First Lesson in Latin", which is clearly intended 2992 to be used by an English-literate audience. In this case, the 2993 Content-Language would properly only include "en". 2995 Content-Language MAY be applied to any media type - it is not limited 2996 to textual documents. 2998 8.5.1. Language Tags 3000 A language tag, as defined in [RFC5646], identifies a natural 3001 language spoken, written, or otherwise conveyed by human beings for 3002 communication of information to other human beings. Computer 3003 languages are explicitly excluded. 3005 HTTP uses language tags within the Accept-Language and 3006 Content-Language header fields. Accept-Language uses the broader 3007 language-range production defined in Section 12.5.4, whereas 3008 Content-Language uses the language-tag production defined below. 3010 language-tag = 3012 A language tag is a sequence of one or more case-insensitive subtags, 3013 each separated by a hyphen character ("-", %x2D). In most cases, a 3014 language tag consists of a primary language subtag that identifies a 3015 broad family of related languages (e.g., "en" = English), which is 3016 optionally followed by a series of subtags that refine or narrow that 3017 language's range (e.g., "en-CA" = the variety of English as 3018 communicated in Canada). Whitespace is not allowed within a language 3019 tag. Example tags include: 3021 fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN 3023 See [RFC5646] for further information. 3025 8.6. Content-Length 3027 The "Content-Length" header field indicates the associated 3028 representation's data length as a decimal non-negative integer number 3029 of octets. When transferring a representation as content, Content- 3030 Length refers specifically to the amount of data enclosed so that it 3031 can be used to delimit framing (e.g., Section 6.2 of [Messaging]). 3032 In other cases, Content-Length indicates the selected 3033 representation's current length, which can be used by recipients to 3034 estimate transfer time or compare to previously stored 3035 representations. 3037 Content-Length = 1*DIGIT 3039 An example is 3041 Content-Length: 3495 3043 A sender MUST NOT send a Content-Length header field in any message 3044 that contains a Transfer-Encoding header field. 3046 A user agent SHOULD send a Content-Length in a request message when 3047 no Transfer-Encoding is sent and the request method defines a meaning 3048 for enclosed content. For example, a Content-Length header field is 3049 normally sent in a POST request even when the value is 0 (indicating 3050 empty content). A user agent SHOULD NOT send a Content-Length header 3051 field when the request message does not contain content and the 3052 method semantics do not anticipate such data. 3054 A server MAY send a Content-Length header field in a response to a 3055 HEAD request (Section 9.3.2); a server MUST NOT send Content-Length 3056 in such a response unless its field value equals the decimal number 3057 of octets that would have been sent in the content of a response if 3058 the same request had used the GET method. 3060 A server MAY send a Content-Length header field in a 304 (Not 3061 Modified) response to a conditional GET request (Section 15.4.5); a 3062 server MUST NOT send Content-Length in such a response unless its 3063 field value equals the decimal number of octets that would have been 3064 sent in the content of a 200 (OK) response to the same request. 3066 A server MUST NOT send a Content-Length header field in any response 3067 with a status code of 1xx (Informational) or 204 (No Content). A 3068 server MUST NOT send a Content-Length header field in any 2xx 3069 (Successful) response to a CONNECT request (Section 9.3.6). 3071 Aside from the cases defined above, in the absence of Transfer- 3072 Encoding, an origin server SHOULD send a Content-Length header field 3073 when the content size is known prior to sending the complete header 3074 section. This will allow downstream recipients to measure transfer 3075 progress, know when a received message is complete, and potentially 3076 reuse the connection for additional requests. 3078 Any Content-Length field value greater than or equal to zero is 3079 valid. Since there is no predefined limit to the length of content, 3080 a recipient MUST anticipate potentially large decimal numerals and 3081 prevent parsing errors due to integer conversion overflows 3082 (Section 17.5). 3084 If a message is received that has a Content-Length header field value 3085 consisting of the same decimal value as a comma-separated list 3086 (Section 5.6.1) - for example, "Content-Length: 42, 42" - indicating 3087 that duplicate Content-Length header fields have been generated or 3088 combined by an upstream message processor, then the recipient MUST 3089 either reject the message as invalid or replace the duplicated field 3090 values with a single valid Content-Length field containing that 3091 decimal value. 3093 8.7. Content-Location 3095 The "Content-Location" header field references a URI that can be used 3096 as an identifier for a specific resource corresponding to the 3097 representation in this message's content. In other words, if one 3098 were to perform a GET request on this URI at the time of this 3099 message's generation, then a 200 (OK) response would contain the same 3100 representation that is enclosed as content in this message. 3102 Content-Location = absolute-URI / partial-URI 3104 The field value is either an absolute-URI or a partial-URI. In the 3105 latter case (Section 4), the referenced URI is relative to the target 3106 URI ([RFC3986], Section 5). 3108 The Content-Location value is not a replacement for the target URI 3109 (Section 7.1). It is representation metadata. It has the same 3110 syntax and semantics as the header field of the same name defined for 3111 MIME body parts in Section 4 of [RFC2557]. However, its appearance 3112 in an HTTP message has some special implications for HTTP recipients. 3114 If Content-Location is included in a 2xx (Successful) response 3115 message and its value refers (after conversion to absolute form) to a 3116 URI that is the same as the target URI, then the recipient MAY 3117 consider the content to be a current representation of that resource 3118 at the time indicated by the message origination date. For a GET 3119 (Section 9.3.1) or HEAD (Section 9.3.2) request, this is the same as 3120 the default semantics when no Content-Location is provided by the 3121 server. For a state-changing request like PUT (Section 9.3.4) or 3122 POST (Section 9.3.3), it implies that the server's response contains 3123 the new representation of that resource, thereby distinguishing it 3124 from representations that might only report about the action (e.g., 3125 "It worked!"). This allows authoring applications to update their 3126 local copies without the need for a subsequent GET request. 3128 If Content-Location is included in a 2xx (Successful) response 3129 message and its field value refers to a URI that differs from the 3130 target URI, then the origin server claims that the URI is an 3131 identifier for a different resource corresponding to the enclosed 3132 representation. Such a claim can only be trusted if both identifiers 3133 share the same resource owner, which cannot be programmatically 3134 determined via HTTP. 3136 o For a response to a GET or HEAD request, this is an indication 3137 that the target URI refers to a resource that is subject to 3138 content negotiation and the Content-Location field value is a more 3139 specific identifier for the selected representation. 3141 o For a 201 (Created) response to a state-changing method, a 3142 Content-Location field value that is identical to the Location 3143 field value indicates that this content is a current 3144 representation of the newly created resource. 3146 o Otherwise, such a Content-Location indicates that this content is 3147 a representation reporting on the requested action's status and 3148 that the same report is available (for future access with GET) at 3149 the given URI. For example, a purchase transaction made via a 3150 POST request might include a receipt document as the content of 3151 the 200 (OK) response; the Content-Location field value provides 3152 an identifier for retrieving a copy of that same receipt in the 3153 future. 3155 A user agent that sends Content-Location in a request message is 3156 stating that its value refers to where the user agent originally 3157 obtained the content of the enclosed representation (prior to any 3158 modifications made by that user agent). In other words, the user 3159 agent is providing a back link to the source of the original 3160 representation. 3162 An origin server that receives a Content-Location field in a request 3163 message MUST treat the information as transitory request context 3164 rather than as metadata to be saved verbatim as part of the 3165 representation. An origin server MAY use that context to guide in 3166 processing the request or to save it for other uses, such as within 3167 source links or versioning metadata. However, an origin server MUST 3168 NOT use such context information to alter the request semantics. 3170 For example, if a client makes a PUT request on a negotiated resource 3171 and the origin server accepts that PUT (without redirection), then 3172 the new state of that resource is expected to be consistent with the 3173 one representation supplied in that PUT; the Content-Location cannot 3174 be used as a form of reverse content selection identifier to update 3175 only one of the negotiated representations. If the user agent had 3176 wanted the latter semantics, it would have applied the PUT directly 3177 to the Content-Location URI. 3179 8.8. Validator Fields 3181 Validator fields convey metadata about the selected representation 3182 (Section 3.2). In responses to safe requests, validator fields 3183 describe the selected representation chosen by the origin server 3184 while handling the response. Note that, depending on the status code 3185 semantics, the selected representation for a given response is not 3186 necessarily the same as the representation enclosed as response 3187 content. 3189 In a successful response to a state-changing request, validator 3190 fields describe the new representation that has replaced the prior 3191 selected representation as a result of processing the request. 3193 For example, an ETag field in a 201 (Created) response communicates 3194 the entity-tag of the newly created resource's representation, so 3195 that it can be used in later conditional requests to prevent the 3196 "lost update" problem Section 13.1. 3198 This specification defines two forms of metadata that are commonly 3199 used to observe resource state and test for preconditions: 3200 modification dates (Section 8.8.2) and opaque entity tags 3201 (Section 8.8.3). Additional metadata that reflects resource state 3202 has been defined by various extensions of HTTP, such as Web 3203 Distributed Authoring and Versioning (WebDAV, [RFC4918]), that are 3204 beyond the scope of this specification. A resource metadata value is 3205 referred to as a _validator_ when it is used within a precondition. 3207 8.8.1. Weak versus Strong 3209 Validators come in two flavors: strong or weak. Weak validators are 3210 easy to generate but are far less useful for comparisons. Strong 3211 validators are ideal for comparisons but can be very difficult (and 3212 occasionally impossible) to generate efficiently. Rather than impose 3213 that all forms of resource adhere to the same strength of validator, 3214 HTTP exposes the type of validator in use and imposes restrictions on 3215 when weak validators can be used as preconditions. 3217 A _strong validator_ is representation metadata that changes value 3218 whenever a change occurs to the representation data that would be 3219 observable in the content of a 200 (OK) response to GET. 3221 A strong validator might change for reasons other than a change to 3222 the representation data, such as when a semantically significant part 3223 of the representation metadata is changed (e.g., Content-Type), but 3224 it is in the best interests of the origin server to only change the 3225 value when it is necessary to invalidate the stored responses held by 3226 remote caches and authoring tools. 3228 Cache entries might persist for arbitrarily long periods, regardless 3229 of expiration times. Thus, a cache might attempt to validate an 3230 entry using a validator that it obtained in the distant past. A 3231 strong validator is unique across all versions of all representations 3232 associated with a particular resource over time. However, there is 3233 no implication of uniqueness across representations of different 3234 resources (i.e., the same strong validator might be in use for 3235 representations of multiple resources at the same time and does not 3236 imply that those representations are equivalent). 3238 There are a variety of strong validators used in practice. The best 3239 are based on strict revision control, wherein each change to a 3240 representation always results in a unique node name and revision 3241 identifier being assigned before the representation is made 3242 accessible to GET. A collision-resistant hash function applied to 3243 the representation data is also sufficient if the data is available 3244 prior to the response header fields being sent and the digest does 3245 not need to be recalculated every time a validation request is 3246 received. However, if a resource has distinct representations that 3247 differ only in their metadata, such as might occur with content 3248 negotiation over media types that happen to share the same data 3249 format, then the origin server needs to incorporate additional 3250 information in the validator to distinguish those representations. 3252 In contrast, a _weak validator_ is representation metadata that might 3253 not change for every change to the representation data. This 3254 weakness might be due to limitations in how the value is calculated, 3255 such as clock resolution, an inability to ensure uniqueness for all 3256 possible representations of the resource, or a desire of the resource 3257 owner to group representations by some self-determined set of 3258 equivalency rather than unique sequences of data. An origin server 3259 SHOULD change a weak entity-tag whenever it considers prior 3260 representations to be unacceptable as a substitute for the current 3261 representation. In other words, a weak entity-tag ought to change 3262 whenever the origin server wants caches to invalidate old responses. 3264 For example, the representation of a weather report that changes in 3265 content every second, based on dynamic measurements, might be grouped 3266 into sets of equivalent representations (from the origin server's 3267 perspective) with the same weak validator in order to allow cached 3268 representations to be valid for a reasonable period of time (perhaps 3269 adjusted dynamically based on server load or weather quality). 3270 Likewise, a representation's modification time, if defined with only 3271 one-second resolution, might be a weak validator if it is possible 3272 for the representation to be modified twice during a single second 3273 and retrieved between those modifications. 3275 Likewise, a validator is weak if it is shared by two or more 3276 representations of a given resource at the same time, unless those 3277 representations have identical representation data. For example, if 3278 the origin server sends the same validator for a representation with 3279 a gzip content coding applied as it does for a representation with no 3280 content coding, then that validator is weak. However, two 3281 simultaneous representations might share the same strong validator if 3282 they differ only in the representation metadata, such as when two 3283 different media types are available for the same representation data. 3285 Strong validators are usable for all conditional requests, including 3286 cache validation, partial content ranges, and "lost update" 3287 avoidance. Weak validators are only usable when the client does not 3288 require exact equality with previously obtained representation data, 3289 such as when validating a cache entry or limiting a web traversal to 3290 recent changes. 3292 8.8.2. Last-Modified 3294 The "Last-Modified" header field in a response provides a timestamp 3295 indicating the date and time at which the origin server believes the 3296 selected representation was last modified, as determined at the 3297 conclusion of handling the request. 3299 Last-Modified = HTTP-date 3301 An example of its use is 3302 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 3304 8.8.2.1. Generation 3306 An origin server SHOULD send Last-Modified for any selected 3307 representation for which a last modification date can be reasonably 3308 and consistently determined, since its use in conditional requests 3309 and evaluating cache freshness ([Caching]) results in a substantial 3310 reduction of HTTP traffic on the Internet and can be a significant 3311 factor in improving service scalability and reliability. 3313 A representation is typically the sum of many parts behind the 3314 resource interface. The last-modified time would usually be the most 3315 recent time that any of those parts were changed. How that value is 3316 determined for any given resource is an implementation detail beyond 3317 the scope of this specification. What matters to HTTP is how 3318 recipients of the Last-Modified header field can use its value to 3319 make conditional requests and test the validity of locally cached 3320 responses. 3322 An origin server SHOULD obtain the Last-Modified value of the 3323 representation as close as possible to the time that it generates the 3324 Date field value for its response. This allows a recipient to make 3325 an accurate assessment of the representation's modification time, 3326 especially if the representation changes near the time that the 3327 response is generated. 3329 An origin server with a clock MUST NOT send a Last-Modified date that 3330 is later than the server's time of message origination (Date). If 3331 the last modification time is derived from implementation-specific 3332 metadata that evaluates to some time in the future, according to the 3333 origin server's clock, then the origin server MUST replace that value 3334 with the message origination date. This prevents a future 3335 modification date from having an adverse impact on cache validation. 3337 An origin server without a clock MUST NOT assign Last-Modified values 3338 to a response unless these values were associated with the resource 3339 by some other system or user with a reliable clock. 3341 8.8.2.2. Comparison 3343 A Last-Modified time, when used as a validator in a request, is 3344 implicitly weak unless it is possible to deduce that it is strong, 3345 using the following rules: 3347 o The validator is being compared by an origin server to the actual 3348 current validator for the representation and, 3350 o That origin server reliably knows that the associated 3351 representation did not change twice during the second covered by 3352 the presented validator; 3354 or 3356 o The validator is about to be used by a client in an 3357 If-Modified-Since, If-Unmodified-Since, or If-Range header field, 3358 because the client has a cache entry for the associated 3359 representation, and 3361 o That cache entry includes a Date value which is at least one 3362 second after the Last-Modified value and the client has reason to 3363 believe that they were generated by the same clock or that there 3364 is enough difference between the Last-Modified and Date values to 3365 make clock synchronization issues unlikely; 3367 or 3369 o The validator is being compared by an intermediate cache to the 3370 validator stored in its cache entry for the representation, and 3372 o That cache entry includes a Date value which is at least one 3373 second after the Last-Modified value and the cache has reason to 3374 believe that they were generated by the same clock or that there 3375 is enough difference between the Last-Modified and Date values to 3376 make clock synchronization issues unlikely. 3378 This method relies on the fact that if two different responses were 3379 sent by the origin server during the same second, but both had the 3380 same Last-Modified time, then at least one of those responses would 3381 have a Date value equal to its Last-Modified time. 3383 8.8.3. ETag 3385 The "ETag" field in a response provides the current entity-tag for 3386 the selected representation, as determined at the conclusion of 3387 handling the request. An entity-tag is an opaque validator for 3388 differentiating between multiple representations of the same 3389 resource, regardless of whether those multiple representations are 3390 due to resource state changes over time, content negotiation 3391 resulting in multiple representations being valid at the same time, 3392 or both. An entity-tag consists of an opaque quoted string, possibly 3393 prefixed by a weakness indicator. 3395 ETag = entity-tag 3397 entity-tag = [ weak ] opaque-tag 3398 weak = %s"W/" 3399 opaque-tag = DQUOTE *etagc DQUOTE 3400 etagc = %x21 / %x23-7E / obs-text 3401 ; VCHAR except double quotes, plus obs-text 3403 | *Note:* Previously, opaque-tag was defined to be a quoted- 3404 | string ([RFC2616], Section 3.11); thus, some recipients might 3405 | perform backslash unescaping. Servers therefore ought to avoid 3406 | backslash characters in entity tags. 3408 An entity-tag can be more reliable for validation than a modification 3409 date in situations where it is inconvenient to store modification 3410 dates, where the one-second resolution of HTTP date values is not 3411 sufficient, or where modification dates are not consistently 3412 maintained. 3414 Examples: 3416 ETag: "xyzzy" 3417 ETag: W/"xyzzy" 3418 ETag: "" 3420 An entity-tag can be either a weak or strong validator, with strong 3421 being the default. If an origin server provides an entity-tag for a 3422 representation and the generation of that entity-tag does not satisfy 3423 all of the characteristics of a strong validator (Section 8.8.1), 3424 then the origin server MUST mark the entity-tag as weak by prefixing 3425 its opaque value with "W/" (case-sensitive). 3427 A sender MAY send the Etag field in a trailer section (see 3428 Section 6.5). However, since trailers are often ignored, it is 3429 preferable to send Etag as a header field unless the entity-tag is 3430 generated while sending the content. 3432 8.8.3.1. Generation 3434 The principle behind entity-tags is that only the service author 3435 knows the implementation of a resource well enough to select the most 3436 accurate and efficient validation mechanism for that resource, and 3437 that any such mechanism can be mapped to a simple sequence of octets 3438 for easy comparison. Since the value is opaque, there is no need for 3439 the client to be aware of how each entity-tag is constructed. 3441 For example, a resource that has implementation-specific versioning 3442 applied to all changes might use an internal revision number, perhaps 3443 combined with a variance identifier for content negotiation, to 3444 accurately differentiate between representations. Other 3445 implementations might use a collision-resistant hash of 3446 representation content, a combination of various file attributes, or 3447 a modification timestamp that has sub-second resolution. 3449 An origin server SHOULD send an ETag for any selected representation 3450 for which detection of changes can be reasonably and consistently 3451 determined, since the entity-tag's use in conditional requests and 3452 evaluating cache freshness ([Caching]) can result in a substantial 3453 reduction of HTTP network traffic and can be a significant factor in 3454 improving service scalability and reliability. 3456 8.8.3.2. Comparison 3458 There are two entity-tag comparison functions, depending on whether 3459 or not the comparison context allows the use of weak validators: 3461 _Strong comparison_: two entity-tags are equivalent if both are not 3462 weak and their opaque-tags match character-by-character. 3464 _Weak comparison_: two entity-tags are equivalent if their opaque- 3465 tags match character-by-character, regardless of either or both 3466 being tagged as "weak". 3468 The example below shows the results for a set of entity-tag pairs and 3469 both the weak and strong comparison function results: 3471 -------- -------- ------------------- ----------------- 3472 ETag 1 ETag 2 Strong Comparison Weak Comparison 3473 -------- -------- ------------------- ----------------- 3474 W/"1" W/"1" no match match 3475 W/"1" W/"2" no match no match 3476 W/"1" "1" no match match 3477 "1" "1" match match 3478 -------- -------- ------------------- ----------------- 3480 Table 3 3482 8.8.3.3. Example: Entity-Tags Varying on Content-Negotiated Resources 3484 Consider a resource that is subject to content negotiation 3485 (Section 12), and where the representations sent in response to a GET 3486 request vary based on the Accept-Encoding request header field 3487 (Section 12.5.3): 3489 >> Request: 3491 GET /index HTTP/1.1 3492 Host: www.example.com 3493 Accept-Encoding: gzip 3495 In this case, the response might or might not use the gzip content 3496 coding. If it does not, the response might look like: 3498 >> Response: 3500 HTTP/1.1 200 OK 3501 Date: Fri, 26 Mar 2010 00:05:00 GMT 3502 ETag: "123-a" 3503 Content-Length: 70 3504 Vary: Accept-Encoding 3505 Content-Type: text/plain 3507 Hello World! 3508 Hello World! 3509 Hello World! 3510 Hello World! 3511 Hello World! 3513 An alternative representation that does use gzip content coding would 3514 be: 3516 >> Response: 3518 HTTP/1.1 200 OK 3519 Date: Fri, 26 Mar 2010 00:05:00 GMT 3520 ETag: "123-b" 3521 Content-Length: 43 3522 Vary: Accept-Encoding 3523 Content-Type: text/plain 3524 Content-Encoding: gzip 3526 ...binary data... 3528 | *Note:* Content codings are a property of the representation 3529 | data, so a strong entity-tag for a content-encoded 3530 | representation has to be distinct from the entity tag of an 3531 | unencoded representation to prevent potential conflicts during 3532 | cache updates and range requests. In contrast, transfer 3533 | codings (Section 7 of [Messaging]) apply only during message 3534 | transfer and do not result in distinct entity-tags. 3536 8.8.4. When to Use Entity-Tags and Last-Modified Dates 3538 In 200 (OK) responses to GET or HEAD, an origin server: 3540 o SHOULD send an entity-tag validator unless it is not feasible to 3541 generate one. 3543 o MAY send a weak entity-tag instead of a strong entity-tag, if 3544 performance considerations support the use of weak entity-tags, or 3545 if it is unfeasible to send a strong entity-tag. 3547 o SHOULD send a Last-Modified value if it is feasible to send one. 3549 In other words, the preferred behavior for an origin server is to 3550 send both a strong entity-tag and a Last-Modified value in successful 3551 responses to a retrieval request. 3553 A client: 3555 o MUST send that entity-tag in any cache validation request (using 3556 If-Match or If-None-Match) if an entity-tag has been provided by 3557 the origin server. 3559 o SHOULD send the Last-Modified value in non-subrange cache 3560 validation requests (using If-Modified-Since) if only a Last- 3561 Modified value has been provided by the origin server. 3563 o MAY send the Last-Modified value in subrange cache validation 3564 requests (using If-Unmodified-Since) if only a Last-Modified value 3565 has been provided by an HTTP/1.0 origin server. The user agent 3566 SHOULD provide a way to disable this, in case of difficulty. 3568 o SHOULD send both validators in cache validation requests if both 3569 an entity-tag and a Last-Modified value have been provided by the 3570 origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to 3571 respond appropriately. 3573 9. Methods 3575 9.1. Overview 3577 The request method token is the primary source of request semantics; 3578 it indicates the purpose for which the client has made this request 3579 and what is expected by the client as a successful result. 3581 The request method's semantics might be further specialized by the 3582 semantics of some header fields when present in a request if those 3583 additional semantics do not conflict with the method. For example, a 3584 client can send conditional request header fields (Section 13.1) to 3585 make the requested action conditional on the current state of the 3586 target resource. 3588 HTTP was originally designed to be usable as an interface to 3589 distributed object systems. The request method was envisioned as 3590 applying semantics to a target resource in much the same way as 3591 invoking a defined method on an identified object would apply 3592 semantics. 3594 method = token 3596 The method token is case-sensitive because it might be used as a 3597 gateway to object-based systems with case-sensitive method names. By 3598 convention, standardized methods are defined in all-uppercase US- 3599 ASCII letters. 3601 Unlike distributed objects, the standardized request methods in HTTP 3602 are not resource-specific, since uniform interfaces provide for 3603 better visibility and reuse in network-based systems [REST]. Once 3604 defined, a standardized method ought to have the same semantics when 3605 applied to any resource, though each resource determines for itself 3606 whether those semantics are implemented or allowed. 3608 This specification defines a number of standardized methods that are 3609 commonly used in HTTP, as outlined by the following table. 3611 --------- -------------------------------------------- ------- 3612 Method Description Ref. 3613 --------- -------------------------------------------- ------- 3614 GET Transfer a current representation of the 9.3.1 3615 target resource. 3616 HEAD Same as GET, but do not transfer the 9.3.2 3617 response content. 3618 POST Perform resource-specific processing on 9.3.3 3619 the request content. 3620 PUT Replace all current representations of the 9.3.4 3621 target resource with the request content. 3622 DELETE Remove all current representations of the 9.3.5 3623 target resource. 3624 CONNECT Establish a tunnel to the server 9.3.6 3625 identified by the target resource. 3626 OPTIONS Describe the communication options for the 9.3.7 3627 target resource. 3628 TRACE Perform a message loop-back test along the 9.3.8 3629 path to the target resource. 3630 --------- -------------------------------------------- ------- 3632 Table 4 3634 All general-purpose servers MUST support the methods GET and HEAD. 3635 All other methods are OPTIONAL. 3637 The set of methods allowed by a target resource can be listed in an 3638 Allow header field (Section 10.2.1). However, the set of allowed 3639 methods can change dynamically. When a request method is received 3640 that is unrecognized or not implemented by an origin server, the 3641 origin server SHOULD respond with the 501 (Not Implemented) status 3642 code. When a request method is received that is known by an origin 3643 server but not allowed for the target resource, the origin server 3644 SHOULD respond with the 405 (Method Not Allowed) status code. 3646 Additional methods, outside the scope of this specification, have 3647 been specified for use in HTTP. All such methods ought to be 3648 registered within the "Hypertext Transfer Protocol (HTTP) Method 3649 Registry", as described in Section 16.1. 3651 9.2. Common Method Properties 3652 9.2.1. Safe Methods 3654 Request methods are considered _safe_ if their defined semantics are 3655 essentially read-only; i.e., the client does not request, and does 3656 not expect, any state change on the origin server as a result of 3657 applying a safe method to a target resource. Likewise, reasonable 3658 use of a safe method is not expected to cause any harm, loss of 3659 property, or unusual burden on the origin server. 3661 This definition of safe methods does not prevent an implementation 3662 from including behavior that is potentially harmful, that is not 3663 entirely read-only, or that causes side effects while invoking a safe 3664 method. What is important, however, is that the client did not 3665 request that additional behavior and cannot be held accountable for 3666 it. For example, most servers append request information to access 3667 log files at the completion of every response, regardless of the 3668 method, and that is considered safe even though the log storage might 3669 become full and crash the server. Likewise, a safe request initiated 3670 by selecting an advertisement on the Web will often have the side 3671 effect of charging an advertising account. 3673 Of the request methods defined by this specification, the GET, HEAD, 3674 OPTIONS, and TRACE methods are defined to be safe. 3676 The purpose of distinguishing between safe and unsafe methods is to 3677 allow automated retrieval processes (spiders) and cache performance 3678 optimization (pre-fetching) to work without fear of causing harm. In 3679 addition, it allows a user agent to apply appropriate constraints on 3680 the automated use of unsafe methods when processing potentially 3681 untrusted content. 3683 A user agent SHOULD distinguish between safe and unsafe methods when 3684 presenting potential actions to a user, such that the user can be 3685 made aware of an unsafe action before it is requested. 3687 When a resource is constructed such that parameters within the target 3688 URI have the effect of selecting an action, it is the resource 3689 owner's responsibility to ensure that the action is consistent with 3690 the request method semantics. For example, it is common for Web- 3691 based content editing software to use actions within query 3692 parameters, such as "page?do=delete". If the purpose of such a 3693 resource is to perform an unsafe action, then the resource owner MUST 3694 disable or disallow that action when it is accessed using a safe 3695 request method. Failure to do so will result in unfortunate side 3696 effects when automated processes perform a GET on every URI reference 3697 for the sake of link maintenance, pre-fetching, building a search 3698 index, etc. 3700 9.2.2. Idempotent Methods 3702 A request method is considered _idempotent_ if the intended effect on 3703 the server of multiple identical requests with that method is the 3704 same as the effect for a single such request. Of the request methods 3705 defined by this specification, PUT, DELETE, and safe request methods 3706 are idempotent. 3708 Like the definition of safe, the idempotent property only applies to 3709 what has been requested by the user; a server is free to log each 3710 request separately, retain a revision control history, or implement 3711 other non-idempotent side effects for each idempotent request. 3713 Idempotent methods are distinguished because the request can be 3714 repeated automatically if a communication failure occurs before the 3715 client is able to read the server's response. For example, if a 3716 client sends a PUT request and the underlying connection is closed 3717 before any response is received, then the client can establish a new 3718 connection and retry the idempotent request. It knows that repeating 3719 the request will have the same intended effect, even if the original 3720 request succeeded, though the response might differ. 3722 A client SHOULD NOT automatically retry a request with a non- 3723 idempotent method unless it has some means to know that the request 3724 semantics are actually idempotent, regardless of the method, or some 3725 means to detect that the original request was never applied. 3727 For example, a user agent that knows (through design or 3728 configuration) that a POST request to a given resource is safe can 3729 repeat that request automatically. Likewise, a user agent designed 3730 specifically to operate on a version control repository might be able 3731 to recover from partial failure conditions by checking the target 3732 resource revision(s) after a failed connection, reverting or fixing 3733 any changes that were partially applied, and then automatically 3734 retrying the requests that failed. 3736 Some clients use weaker signals to initiate automatic retries. For 3737 example, when a POST request is sent, but the underlying transport 3738 connection is closed before any part of the response is received. 3739 Although this is commonly implemented, it is not recommended. 3741 A proxy MUST NOT automatically retry non-idempotent requests. A 3742 client SHOULD NOT automatically retry a failed automatic retry. 3744 9.2.3. Methods and Caching 3746 For a cache to store and use a response, the associated method needs 3747 to explicitly allow caching, and detail under what conditions a 3748 response can be used to satisfy subsequent requests; a method 3749 definition which does not do so cannot be cached. For additional 3750 requirements see [Caching]. 3752 This specification defines caching semantics for GET, HEAD, and POST, 3753 although the overwhelming majority of cache implementations only 3754 support GET and HEAD. 3756 9.3. Method Definitions 3758 9.3.1. GET 3760 The GET method requests transfer of a current selected representation 3761 for the target resource. 3763 GET is the primary mechanism of information retrieval and the focus 3764 of almost all performance optimizations. Hence, when people speak of 3765 retrieving some identifiable information via HTTP, they are generally 3766 referring to making a GET request. A successful response reflects 3767 the quality of "sameness" identified by the target URI. In turn, 3768 constructing applications such that they produce a URI for each 3769 important resource results in more resources being available for 3770 other applications, producing a network effect that promotes further 3771 expansion of the Web. 3773 It is tempting to think of resource identifiers as remote file system 3774 pathnames and of representations as being a copy of the contents of 3775 such files. In fact, that is how many resources are implemented (see 3776 Section 17.3 for related security considerations). However, there 3777 are no such limitations in practice. 3779 The HTTP interface for a resource is just as likely to be implemented 3780 as a tree of content objects, a programmatic view on various database 3781 records, or a gateway to other information systems. Even when the 3782 URI mapping mechanism is tied to a file system, an origin server 3783 might be configured to execute the files with the request as input 3784 and send the output as the representation rather than transfer the 3785 files directly. Regardless, only the origin server needs to know how 3786 each of its resource identifiers corresponds to an implementation and 3787 how each implementation manages to select and send a current 3788 representation of the target resource in a response to GET. 3790 A client can alter the semantics of GET to be a "range request", 3791 requesting transfer of only some part(s) of the selected 3792 representation, by sending a Range header field in the request 3793 (Section 14.2). 3795 A client SHOULD NOT generate content in a GET request. Content 3796 received in a GET request has no defined semantics, cannot alter the 3797 meaning or target of the request, and might lead some implementations 3798 to reject the request and close the connection because of its 3799 potential as a request smuggling attack (Section 11.2 of 3800 [Messaging]). 3802 The response to a GET request is cacheable; a cache MAY use it to 3803 satisfy subsequent GET and HEAD requests unless otherwise indicated 3804 by the Cache-Control header field (Section 5.2 of [Caching]). 3806 When information retrieval is performed with a mechanism that 3807 constructs a target URI from user-provided information, such as the 3808 query fields of a form using GET, potentially sensitive data might be 3809 provided that would not be appropriate for disclosure within a URI 3810 (see Section 17.9). In some cases, the data can be filtered or 3811 transformed such that it would not reveal such information. In 3812 others, particularly when there is no benefit from caching a 3813 response, using the POST method (Section 9.3.3) instead of GET can 3814 transmit such information in the request content rather than within 3815 the target URI. 3817 9.3.2. HEAD 3819 The HEAD method is identical to GET except that the server MUST NOT 3820 send content in the response and the response always terminates at 3821 the end of the header section. HEAD is used to obtain metadata about 3822 the selected representation without transferring its representation 3823 data, often for the sake of testing hypertext links or finding recent 3824 modifications. 3826 The server SHOULD send the same header fields in response to a HEAD 3827 request as it would have sent if the request method had been GET. 3828 However, a server MAY omit header fields for which a value is 3829 determined only while generating the content. For example, some 3830 servers buffer a dynamic response to GET until a minimum amount of 3831 data is generated so that they can more efficiently delimit small 3832 responses or make late decisions with regard to content selection. 3833 Such a response to GET might contain Content-Length and Vary fields, 3834 for example, that are not generated within a HEAD response. These 3835 minor inconsistencies are considered preferable to generating and 3836 discarding the content for a HEAD request, since HEAD is usually 3837 requested for the sake of efficiency. 3839 A content within a HEAD request message has no defined semantics; 3840 sending content in a HEAD request might cause some existing 3841 implementations to reject the request. 3843 The response to a HEAD request is cacheable; a cache MAY use it to 3844 satisfy subsequent HEAD requests unless otherwise indicated by the 3845 Cache-Control header field (Section 5.2 of [Caching]). A HEAD 3846 response might also affect previously cached responses to GET; see 3847 Section 4.3.5 of [Caching]. 3849 9.3.3. POST 3851 The POST method requests that the target resource process the 3852 representation enclosed in the request according to the resource's 3853 own specific semantics. For example, POST is used for the following 3854 functions (among others): 3856 o Providing a block of data, such as the fields entered into an HTML 3857 form, to a data-handling process; 3859 o Posting a message to a bulletin board, newsgroup, mailing list, 3860 blog, or similar group of articles; 3862 o Creating a new resource that has yet to be identified by the 3863 origin server; and 3865 o Appending data to a resource's existing representation(s). 3867 An origin server indicates response semantics by choosing an 3868 appropriate status code depending on the result of processing the 3869 POST request; almost all of the status codes defined by this 3870 specification could be received in a response to POST (the exceptions 3871 being 206 (Partial Content), 304 (Not Modified), and 416 (Range Not 3872 Satisfiable)). 3874 If one or more resources has been created on the origin server as a 3875 result of successfully processing a POST request, the origin server 3876 SHOULD send a 201 (Created) response containing a Location header 3877 field that provides an identifier for the primary resource created 3878 (Section 10.2.3) and a representation that describes the status of 3879 the request while referring to the new resource(s). 3881 Responses to POST requests are only cacheable when they include 3882 explicit freshness information (see Section 4.2.1 of [Caching]) and a 3883 Content-Location header field that has the same value as the POST's 3884 target URI (Section 8.7). A cached POST response can be reused to 3885 satisfy a later GET or HEAD request, but not a POST request, since 3886 POST is required to be written through to the origin server, because 3887 it is unsafe; see Section 4 of [Caching]. 3889 If the result of processing a POST would be equivalent to a 3890 representation of an existing resource, an origin server MAY redirect 3891 the user agent to that resource by sending a 303 (See Other) response 3892 with the existing resource's identifier in the Location field. This 3893 has the benefits of providing the user agent a resource identifier 3894 and transferring the representation via a method more amenable to 3895 shared caching, though at the cost of an extra request if the user 3896 agent does not already have the representation cached. 3898 9.3.4. PUT 3900 The PUT method requests that the state of the target resource be 3901 created or replaced with the state defined by the representation 3902 enclosed in the request message content. A successful PUT of a given 3903 representation would suggest that a subsequent GET on that same 3904 target resource will result in an equivalent representation being 3905 sent in a 200 (OK) response. However, there is no guarantee that 3906 such a state change will be observable, since the target resource 3907 might be acted upon by other user agents in parallel, or might be 3908 subject to dynamic processing by the origin server, before any 3909 subsequent GET is received. A successful response only implies that 3910 the user agent's intent was achieved at the time of its processing by 3911 the origin server. 3913 If the target resource does not have a current representation and the 3914 PUT successfully creates one, then the origin server MUST inform the 3915 user agent by sending a 201 (Created) response. If the target 3916 resource does have a current representation and that representation 3917 is successfully modified in accordance with the state of the enclosed 3918 representation, then the origin server MUST send either a 200 (OK) or 3919 a 204 (No Content) response to indicate successful completion of the 3920 request. 3922 An origin server SHOULD verify that the PUT representation is 3923 consistent with any constraints the server has for the target 3924 resource that cannot or will not be changed by the PUT. This is 3925 particularly important when the origin server uses internal 3926 configuration information related to the URI in order to set the 3927 values for representation metadata on GET responses. When a PUT 3928 representation is inconsistent with the target resource, the origin 3929 server SHOULD either make them consistent, by transforming the 3930 representation or changing the resource configuration, or respond 3931 with an appropriate error message containing sufficient information 3932 to explain why the representation is unsuitable. The 409 (Conflict) 3933 or 415 (Unsupported Media Type) status codes are suggested, with the 3934 latter being specific to constraints on Content-Type values. 3936 For example, if the target resource is configured to always have a 3937 Content-Type of "text/html" and the representation being PUT has a 3938 Content-Type of "image/jpeg", the origin server ought to do one of: 3940 a. reconfigure the target resource to reflect the new media type; 3942 b. transform the PUT representation to a format consistent with that 3943 of the resource before saving it as the new resource state; or, 3945 c. reject the request with a 415 (Unsupported Media Type) response 3946 indicating that the target resource is limited to "text/html", 3947 perhaps including a link to a different resource that would be a 3948 suitable target for the new representation. 3950 HTTP does not define exactly how a PUT method affects the state of an 3951 origin server beyond what can be expressed by the intent of the user 3952 agent request and the semantics of the origin server response. It 3953 does not define what a resource might be, in any sense of that word, 3954 beyond the interface provided via HTTP. It does not define how 3955 resource state is "stored", nor how such storage might change as a 3956 result of a change in resource state, nor how the origin server 3957 translates resource state into representations. Generally speaking, 3958 all implementation details behind the resource interface are 3959 intentionally hidden by the server. 3961 This extends to how header and trailer fields are stored; while 3962 common header fields like Content-Type will typically be stored and 3963 returned upon subsequent GET requests, header and trailer field 3964 handling is specific to the resource that received the request. As a 3965 result, an origin server SHOULD ignore unrecognized header and 3966 trailer fields received in a PUT request (i.e., do not save them as 3967 part of the resource state). 3969 An origin server MUST NOT send a validator field (Section 8.8), such 3970 as an ETag or Last-Modified field, in a successful response to PUT 3971 unless the request's representation data was saved without any 3972 transformation applied to the content (i.e., the resource's new 3973 representation data is identical to the content received in the PUT 3974 request) and the validator field value reflects the new 3975 representation. This requirement allows a user agent to know when 3976 the representation it has in memory remains current as a result of 3977 the PUT, thus not in need of being retrieved again from the origin 3978 server, and that the new validator(s) received in the response can be 3979 used for future conditional requests in order to prevent accidental 3980 overwrites (Section 13.1). 3982 The fundamental difference between the POST and PUT methods is 3983 highlighted by the different intent for the enclosed representation. 3984 The target resource in a POST request is intended to handle the 3985 enclosed representation according to the resource's own semantics, 3986 whereas the enclosed representation in a PUT request is defined as 3987 replacing the state of the target resource. Hence, the intent of PUT 3988 is idempotent and visible to intermediaries, even though the exact 3989 effect is only known by the origin server. 3991 Proper interpretation of a PUT request presumes that the user agent 3992 knows which target resource is desired. A service that selects a 3993 proper URI on behalf of the client, after receiving a state-changing 3994 request, SHOULD be implemented using the POST method rather than PUT. 3995 If the origin server will not make the requested PUT state change to 3996 the target resource and instead wishes to have it applied to a 3997 different resource, such as when the resource has been moved to a 3998 different URI, then the origin server MUST send an appropriate 3xx 3999 (Redirection) response; the user agent MAY then make its own decision 4000 regarding whether or not to redirect the request. 4002 A PUT request applied to the target resource can have side effects on 4003 other resources. For example, an article might have a URI for 4004 identifying "the current version" (a resource) that is separate from 4005 the URIs identifying each particular version (different resources 4006 that at one point shared the same state as the current version 4007 resource). A successful PUT request on "the current version" URI 4008 might therefore create a new version resource in addition to changing 4009 the state of the target resource, and might also cause links to be 4010 added between the related resources. 4012 Some origin servers support use of the Content-Range header field 4013 (Section 14.4) as a request modifier to perform a partial PUT, as 4014 described in Section 14.5. 4016 Responses to the PUT method are not cacheable. If a successful PUT 4017 request passes through a cache that has one or more stored responses 4018 for the target URI, those stored responses will be invalidated (see 4019 Section 4.4 of [Caching]). 4021 9.3.5. DELETE 4023 The DELETE method requests that the origin server remove the 4024 association between the target resource and its current 4025 functionality. In effect, this method is similar to the "rm" command 4026 in UNIX: it expresses a deletion operation on the URI mapping of the 4027 origin server rather than an expectation that the previously 4028 associated information be deleted. 4030 If the target resource has one or more current representations, they 4031 might or might not be destroyed by the origin server, and the 4032 associated storage might or might not be reclaimed, depending 4033 entirely on the nature of the resource and its implementation by the 4034 origin server (which are beyond the scope of this specification). 4035 Likewise, other implementation aspects of a resource might need to be 4036 deactivated or archived as a result of a DELETE, such as database or 4037 gateway connections. In general, it is assumed that the origin 4038 server will only allow DELETE on resources for which it has a 4039 prescribed mechanism for accomplishing the deletion. 4041 Relatively few resources allow the DELETE method - its primary use is 4042 for remote authoring environments, where the user has some direction 4043 regarding its effect. For example, a resource that was previously 4044 created using a PUT request, or identified via the Location header 4045 field after a 201 (Created) response to a POST request, might allow a 4046 corresponding DELETE request to undo those actions. Similarly, 4047 custom user agent implementations that implement an authoring 4048 function, such as revision control clients using HTTP for remote 4049 operations, might use DELETE based on an assumption that the server's 4050 URI space has been crafted to correspond to a version repository. 4052 If a DELETE method is successfully applied, the origin server SHOULD 4053 send 4055 o a 202 (Accepted) status code if the action will likely succeed but 4056 has not yet been enacted, 4058 o a 204 (No Content) status code if the action has been enacted and 4059 no further information is to be supplied, or 4061 o a 200 (OK) status code if the action has been enacted and the 4062 response message includes a representation describing the status. 4064 A client SHOULD NOT generate content in a DELETE request. Content 4065 received in a DELETE request has no defined semantics, cannot alter 4066 the meaning or target of the request, and might lead some 4067 implementations to reject the request. 4069 Responses to the DELETE method are not cacheable. If a successful 4070 DELETE request passes through a cache that has one or more stored 4071 responses for the target URI, those stored responses will be 4072 invalidated (see Section 4.4 of [Caching]). 4074 9.3.6. CONNECT 4076 The CONNECT method requests that the recipient establish a tunnel to 4077 the destination origin server identified by the request target and, 4078 if successful, thereafter restrict its behavior to blind forwarding 4079 of data, in both directions, until the tunnel is closed. Tunnels are 4080 commonly used to create an end-to-end virtual connection, through one 4081 or more proxies, which can then be secured using TLS (Transport Layer 4082 Security, [RFC8446]). 4084 Because CONNECT changes the request/response nature of an HTTP 4085 connection, specific HTTP versions might have different ways of 4086 mapping its semantics into the protocol's wire format. 4088 CONNECT is intended only for use in requests to a proxy. An origin 4089 server that receives a CONNECT request for itself MAY respond with a 4090 2xx (Successful) status code to indicate that a connection is 4091 established. However, most origin servers do not implement CONNECT. 4093 A client sending a CONNECT request MUST send the authority component 4094 (described in Section 3.2 of [RFC3986]) as the request target; i.e., 4095 the request target consists of only the host name and port number of 4096 the tunnel destination, separated by a colon. For example, 4098 CONNECT server.example.com:80 HTTP/1.1 4099 Host: server.example.com:80 4101 The recipient proxy can establish a tunnel either by directly 4102 connecting to the request target or, if configured to use another 4103 proxy, by forwarding the CONNECT request to the next inbound proxy. 4104 Any 2xx (Successful) response indicates that the sender (and all 4105 inbound proxies) will switch to tunnel mode immediately after the 4106 blank line that concludes the successful response's header section; 4107 data received after that blank line is from the server identified by 4108 the request target. Any response other than a successful response 4109 indicates that the tunnel has not yet been formed and that the 4110 connection remains governed by HTTP. 4112 A tunnel is closed when a tunnel intermediary detects that either 4113 side has closed its connection: the intermediary MUST attempt to send 4114 any outstanding data that came from the closed side to the other 4115 side, close both connections, and then discard any remaining data 4116 left undelivered. 4118 Proxy authentication might be used to establish the authority to 4119 create a tunnel. For example, 4121 CONNECT server.example.com:80 HTTP/1.1 4122 Host: server.example.com:80 4123 Proxy-Authorization: basic aGVsbG86d29ybGQ= 4125 There are significant risks in establishing a tunnel to arbitrary 4126 servers, particularly when the destination is a well-known or 4127 reserved TCP port that is not intended for Web traffic. For example, 4128 a CONNECT to "example.com:25" would suggest that the proxy connect to 4129 the reserved port for SMTP traffic; if allowed, that could trick the 4130 proxy into relaying spam email. Proxies that support CONNECT SHOULD 4131 restrict its use to a limited set of known ports or a configurable 4132 whitelist of safe request targets. 4134 A server MUST NOT send any Transfer-Encoding or Content-Length header 4135 fields in a 2xx (Successful) response to CONNECT. A client MUST 4136 ignore any Content-Length or Transfer-Encoding header fields received 4137 in a successful response to CONNECT. 4139 Content within a CONNECT request message has no defined semantics; 4140 sending content in a CONNECT request might cause some existing 4141 implementations to reject the request. 4143 Responses to the CONNECT method are not cacheable. 4145 9.3.7. OPTIONS 4147 The OPTIONS method requests information about the communication 4148 options available for the target resource, at either the origin 4149 server or an intervening intermediary. This method allows a client 4150 to determine the options and/or requirements associated with a 4151 resource, or the capabilities of a server, without implying a 4152 resource action. 4154 An OPTIONS request with an asterisk ("*") as the request target 4155 (Section 7.1) applies to the server in general rather than to a 4156 specific resource. Since a server's communication options typically 4157 depend on the resource, the "*" request is only useful as a "ping" or 4158 "no-op" type of method; it does nothing beyond allowing the client to 4159 test the capabilities of the server. For example, this can be used 4160 to test a proxy for HTTP/1.1 conformance (or lack thereof). 4162 If the request target is not an asterisk, the OPTIONS request applies 4163 to the options that are available when communicating with the target 4164 resource. 4166 A server generating a successful response to OPTIONS SHOULD send any 4167 header that might indicate optional features implemented by the 4168 server and applicable to the target resource (e.g., Allow), including 4169 potential extensions not defined by this specification. The response 4170 content, if any, might also describe the communication options in a 4171 machine or human-readable representation. A standard format for such 4172 a representation is not defined by this specification, but might be 4173 defined by future extensions to HTTP. 4175 A client MAY send a Max-Forwards header field in an OPTIONS request 4176 to target a specific recipient in the request chain (see 4177 Section 7.6.2). A proxy MUST NOT generate a Max-Forwards header 4178 field while forwarding a request unless that request was received 4179 with a Max-Forwards field. 4181 A client that generates an OPTIONS request containing content MUST 4182 send a valid Content-Type header field describing the representation 4183 media type. Note that this specification does not define any use for 4184 such content. 4186 Responses to the OPTIONS method are not cacheable. 4188 9.3.8. TRACE 4190 The TRACE method requests a remote, application-level loop-back of 4191 the request message. The final recipient of the request SHOULD 4192 reflect the message received, excluding some fields described below, 4193 back to the client as the content of a 200 (OK) response with a 4194 Content-Type of "message/http" (Section 10.1 of [Messaging]). The 4195 final recipient is either the origin server or the first server to 4196 receive a Max-Forwards value of zero (0) in the request 4197 (Section 7.6.2). 4199 A client MUST NOT generate fields in a TRACE request containing 4200 sensitive data that might be disclosed by the response. For example, 4201 it would be foolish for a user agent to send stored user credentials 4202 (Section 11) or cookies [RFC6265] in a TRACE request. The final 4203 recipient of the request SHOULD exclude any request fields that are 4204 likely to contain sensitive data when that recipient generates the 4205 response content. 4207 TRACE allows the client to see what is being received at the other 4208 end of the request chain and use that data for testing or diagnostic 4209 information. The value of the Via header field (Section 7.6.3) is of 4210 particular interest, since it acts as a trace of the request chain. 4211 Use of the Max-Forwards header field allows the client to limit the 4212 length of the request chain, which is useful for testing a chain of 4213 proxies forwarding messages in an infinite loop. 4215 A client MUST NOT send content in a TRACE request. 4217 Responses to the TRACE method are not cacheable. 4219 10. Message Context 4221 10.1. Request Context Fields 4223 The request header fields below provide additional information about 4224 the request context, including information about the user, user 4225 agent, and resource behind the request. 4227 10.1.1. Expect 4229 The "Expect" header field in a request indicates a certain set of 4230 behaviors (expectations) that need to be supported by the server in 4231 order to properly handle this request. 4233 Expect = #expectation 4234 expectation = token [ "=" ( token / quoted-string ) parameters ] 4236 The Expect field value is case-insensitive. 4238 The only expectation defined by this specification is "100-continue" 4239 (with no defined parameters). 4241 A server that receives an Expect field value containing a member 4242 other than 100-continue MAY respond with a 417 (Expectation Failed) 4243 status code to indicate that the unexpected expectation cannot be 4244 met. 4246 A _100-continue_ expectation informs recipients that the client is 4247 about to send (presumably large) content in this request and wishes 4248 to receive a 100 (Continue) interim response if the method, target 4249 URI, and header fields are not sufficient to cause an immediate 4250 success, redirect, or error response. This allows the client to wait 4251 for an indication that it is worthwhile to send the content before 4252 actually doing so, which can improve efficiency when the data is huge 4253 or when the client anticipates that an error is likely (e.g., when 4254 sending a state-changing method, for the first time, without 4255 previously verified authentication credentials). 4257 For example, a request that begins with 4259 PUT /somewhere/fun HTTP/1.1 4260 Host: origin.example.com 4261 Content-Type: video/h264 4262 Content-Length: 1234567890987 4263 Expect: 100-continue 4265 allows the origin server to immediately respond with an error 4266 message, such as 401 (Unauthorized) or 405 (Method Not Allowed), 4267 before the client starts filling the pipes with an unnecessary data 4268 transfer. 4270 Requirements for clients: 4272 o A client MUST NOT generate a 100-continue expectation in a request 4273 that does not include content. 4275 o A client that will wait for a 100 (Continue) response before 4276 sending the request content MUST send an Expect header field 4277 containing a 100-continue expectation. 4279 o A client that sends a 100-continue expectation is not required to 4280 wait for any specific length of time; such a client MAY proceed to 4281 send the content even if it has not yet received a response. 4282 Furthermore, since 100 (Continue) responses cannot be sent through 4283 an HTTP/1.0 intermediary, such a client SHOULD NOT wait for an 4284 indefinite period before sending the content. 4286 o A client that receives a 417 (Expectation Failed) status code in 4287 response to a request containing a 100-continue expectation SHOULD 4288 repeat that request without a 100-continue expectation, since the 4289 417 response merely indicates that the response chain does not 4290 support expectations (e.g., it passes through an HTTP/1.0 server). 4292 Requirements for servers: 4294 o A server that receives a 100-continue expectation in an HTTP/1.0 4295 request MUST ignore that expectation. 4297 o A server MAY omit sending a 100 (Continue) response if it has 4298 already received some or all of the content for the corresponding 4299 request, or if the framing indicates that there is no content. 4301 o A server that sends a 100 (Continue) response MUST ultimately send 4302 a final status code, once the request content is received and 4303 processed, unless the connection is closed prematurely. 4305 o A server that responds with a final status code before reading the 4306 entire request content SHOULD indicate whether it intends to close 4307 the connection (e.g., see Section 9.6 of [Messaging]) or continue 4308 reading the request content. 4310 An origin server MUST, upon receiving an HTTP/1.1 (or later) request 4311 that has a method, target URI, and complete header section that 4312 contains a 100-continue expectation and an indication that request 4313 content will follow, either send an immediate response with a final 4314 status code, if that status can be determined by examining just the 4315 method, target URI, and header fields, or send an immediate 100 4316 (Continue) response to encourage the client to send the request 4317 content. The origin server MUST NOT wait for the content before 4318 sending the 100 (Continue) response. 4320 A proxy MUST, upon receiving an HTTP/1.1 (or later) request that has 4321 a method, target URI, and complete header section that contains a 4322 100-continue expectation and indicates a request content will follow, 4323 either send an immediate response with a final status code, if that 4324 status can be determined by examining just the method, target URI, 4325 and header fields, or begin forwarding the request toward the origin 4326 server by sending a corresponding request-line and header section to 4327 the next inbound server. If the proxy believes (from configuration 4328 or past interaction) that the next inbound server only supports 4329 HTTP/1.0, the proxy MAY generate an immediate 100 (Continue) response 4330 to encourage the client to begin sending the content. 4332 10.1.2. From 4334 The "From" header field contains an Internet email address for a 4335 human user who controls the requesting user agent. The address ought 4336 to be machine-usable, as defined by "mailbox" in Section 3.4 of 4337 [RFC5322]: 4339 From = mailbox 4341 mailbox = 4343 An example is: 4345 From: webmaster@example.org 4347 The From header field is rarely sent by non-robotic user agents. A 4348 user agent SHOULD NOT send a From header field without explicit 4349 configuration by the user, since that might conflict with the user's 4350 privacy interests or their site's security policy. 4352 A robotic user agent SHOULD send a valid From header field so that 4353 the person responsible for running the robot can be contacted if 4354 problems occur on servers, such as if the robot is sending excessive, 4355 unwanted, or invalid requests. 4357 A server SHOULD NOT use the From header field for access control or 4358 authentication, since most recipients will assume that the field 4359 value is public information. 4361 10.1.3. Referer 4363 The "Referer" [sic] header field allows the user agent to specify a 4364 URI reference for the resource from which the target URI was obtained 4365 (i.e., the "referrer", though the field name is misspelled). A user 4366 agent MUST NOT include the fragment and userinfo components of the 4367 URI reference [RFC3986], if any, when generating the Referer field 4368 value. 4370 Referer = absolute-URI / partial-URI 4372 The field value is either an absolute-URI or a partial-URI. In the 4373 latter case (Section 4), the referenced URI is relative to the target 4374 URI ([RFC3986], Section 5). 4376 The Referer header field allows servers to generate back-links to 4377 other resources for simple analytics, logging, optimized caching, 4378 etc. It also allows obsolete or mistyped links to be found for 4379 maintenance. Some servers use the Referer header field as a means of 4380 denying links from other sites (so-called "deep linking") or 4381 restricting cross-site request forgery (CSRF), but not all requests 4382 contain it. 4384 Example: 4386 Referer: http://www.example.org/hypertext/Overview.html 4388 If the target URI was obtained from a source that does not have its 4389 own URI (e.g., input from the user keyboard, or an entry within the 4390 user's bookmarks/favorites), the user agent MUST either exclude the 4391 Referer header field or send it with a value of "about:blank". 4393 The Referer header field has the potential to reveal information 4394 about the request context or browsing history of the user, which is a 4395 privacy concern if the referring resource's identifier reveals 4396 personal information (such as an account name) or a resource that is 4397 supposed to be confidential (such as behind a firewall or internal to 4398 a secured service). Most general-purpose user agents do not send the 4399 Referer header field when the referring resource is a local "file" or 4400 "data" URI. A user agent MUST NOT send a Referer header field in an 4401 unsecured HTTP request if the referring page was received with a 4402 secure protocol. See Section 17.9 for additional security 4403 considerations. 4405 Some intermediaries have been known to indiscriminately remove 4406 Referer header fields from outgoing requests. This has the 4407 unfortunate side effect of interfering with protection against CSRF 4408 attacks, which can be far more harmful to their users. 4409 Intermediaries and user agent extensions that wish to limit 4410 information disclosure in Referer ought to restrict their changes to 4411 specific edits, such as replacing internal domain names with 4412 pseudonyms or truncating the query and/or path components. An 4413 intermediary SHOULD NOT modify or delete the Referer header field 4414 when the field value shares the same scheme and host as the target 4415 URI. 4417 10.1.4. TE 4419 The "TE" header field in a request can be used to indicate that the 4420 sender will not discard trailer fields when it contains a "trailers" 4421 member, as described in Section 6.5. 4423 Additionally, specific HTTP versions can use it to indicate the 4424 transfer codings the client is willing to accept in the response. As 4425 of publication, only HTTP/1.1 uses transfer codings (see Section 7 of 4426 [Messaging]). 4428 The TE field value consists of a list of tokens, each allowing for 4429 optional parameters (except for the special case "trailers"). 4431 TE = #t-codings 4432 t-codings = "trailers" / ( transfer-coding [ weight ] ) 4433 transfer-coding = token *( OWS ";" OWS transfer-parameter ) 4434 transfer-parameter = token BWS "=" BWS ( token / quoted-string ) 4436 10.1.5. Trailer 4438 The "Trailer" header field provides a list of field names that the 4439 sender anticipates sending as trailer fields within that message. 4440 This allows a recipient to prepare for receipt of the indicated 4441 metadata before it starts processing the content. 4443 Trailer = #field-name 4445 For example, a sender might indicate that a message integrity check 4446 will be computed as the content is being streamed and provide the 4447 final signature as a trailer field. This allows a recipient to 4448 perform the same check on the fly as the content is received. 4450 A sender that intends to generate one or more trailer fields in a 4451 message SHOULD generate a Trailer header field in the header section 4452 of that message to indicate which fields might be present in the 4453 trailers. 4455 10.1.6. User-Agent 4457 The "User-Agent" header field contains information about the user 4458 agent originating the request, which is often used by servers to help 4459 identify the scope of reported interoperability problems, to work 4460 around or tailor responses to avoid particular user agent 4461 limitations, and for analytics regarding browser or operating system 4462 use. A user agent SHOULD send a User-Agent header field in each 4463 request unless specifically configured not to do so. 4465 User-Agent = product *( RWS ( product / comment ) ) 4467 The User-Agent field value consists of one or more product 4468 identifiers, each followed by zero or more comments (Section 5.6.5), 4469 which together identify the user agent software and its significant 4470 subproducts. By convention, the product identifiers are listed in 4471 decreasing order of their significance for identifying the user agent 4472 software. Each product identifier consists of a name and optional 4473 version. 4475 product = token ["/" product-version] 4476 product-version = token 4478 A sender SHOULD limit generated product identifiers to what is 4479 necessary to identify the product; a sender MUST NOT generate 4480 advertising or other nonessential information within the product 4481 identifier. A sender SHOULD NOT generate information in 4482 product-version that is not a version identifier (i.e., successive 4483 versions of the same product name ought to differ only in the 4484 product-version portion of the product identifier). 4486 Example: 4488 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 4490 A user agent SHOULD NOT generate a User-Agent header field containing 4491 needlessly fine-grained detail and SHOULD limit the addition of 4492 subproducts by third parties. Overly long and detailed User-Agent 4493 field values increase request latency and the risk of a user being 4494 identified against their wishes ("fingerprinting"). 4496 Likewise, implementations are encouraged not to use the product 4497 tokens of other implementations in order to declare compatibility 4498 with them, as this circumvents the purpose of the field. If a user 4499 agent masquerades as a different user agent, recipients can assume 4500 that the user intentionally desires to see responses tailored for 4501 that identified user agent, even if they might not work as well for 4502 the actual user agent being used. 4504 10.2. Response Context Fields 4506 Response header fields can supply control data that supplements the 4507 status code, directs caching, or instructs the client where to go 4508 next. 4510 The response header fields allow the server to pass additional 4511 information about the response beyond the status code. These header 4512 fields give information about the server, about further access to the 4513 target resource, or about related resources. 4515 Although each response header field has a defined meaning, in 4516 general, the precise semantics might be further refined by the 4517 semantics of the request method and/or response status code. 4519 The remaining response header fields provide more information about 4520 the target resource for potential use in later requests. 4522 10.2.1. Allow 4524 The "Allow" header field lists the set of methods advertised as 4525 supported by the target resource. The purpose of this field is 4526 strictly to inform the recipient of valid request methods associated 4527 with the resource. 4529 Allow = #method 4531 Example of use: 4533 Allow: GET, HEAD, PUT 4535 The actual set of allowed methods is defined by the origin server at 4536 the time of each request. An origin server MUST generate an Allow 4537 header field in a 405 (Method Not Allowed) response and MAY do so in 4538 any other response. An empty Allow field value indicates that the 4539 resource allows no methods, which might occur in a 405 response if 4540 the resource has been temporarily disabled by configuration. 4542 A proxy MUST NOT modify the Allow header field - it does not need to 4543 understand all of the indicated methods in order to handle them 4544 according to the generic message handling rules. 4546 10.2.2. Date 4548 The "Date" header field represents the date and time at which the 4549 message was originated, having the same semantics as the Origination 4550 Date Field (orig-date) defined in Section 3.6.1 of [RFC5322]. The 4551 field value is an HTTP-date, as defined in Section 5.6.7. 4553 Date = HTTP-date 4555 An example is 4557 Date: Tue, 15 Nov 1994 08:12:31 GMT 4559 When a Date header field is generated, the sender SHOULD generate its 4560 field value as the best available approximation of the date and time 4561 of message generation. In theory, the date ought to represent the 4562 moment just before the content is generated. In practice, the date 4563 can be generated at any time during message origination. 4565 An origin server MUST NOT send a Date header field if it does not 4566 have a clock capable of providing a reasonable approximation of the 4567 current instance in Coordinated Universal Time. An origin server MAY 4568 send a Date header field if the response is in the 1xx 4569 (Informational) or 5xx (Server Error) class of status codes. An 4570 origin server MUST send a Date header field in all other cases. 4572 A recipient with a clock that receives a response message without a 4573 Date header field MUST record the time it was received and append a 4574 corresponding Date header field to the message's header section if it 4575 is cached or forwarded downstream. 4577 A recipient with a clock that receives a response with an invalid 4578 Date header field value MAY replace that value with the time that 4579 response was received. 4581 A user agent MAY send a Date header field in a request, though 4582 generally will not do so unless it is believed to convey useful 4583 information to the server. For example, custom applications of HTTP 4584 might convey a Date if the server is expected to adjust its 4585 interpretation of the user's request based on differences between the 4586 user agent and server clocks. 4588 10.2.3. Location 4590 The "Location" header field is used in some responses to refer to a 4591 specific resource in relation to the response. The type of 4592 relationship is defined by the combination of request method and 4593 status code semantics. 4595 Location = URI-reference 4597 The field value consists of a single URI-reference. When it has the 4598 form of a relative reference ([RFC3986], Section 4.2), the final 4599 value is computed by resolving it against the target URI ([RFC3986], 4600 Section 5). 4602 For 201 (Created) responses, the Location value refers to the primary 4603 resource created by the request. For 3xx (Redirection) responses, 4604 the Location value refers to the preferred target resource for 4605 automatically redirecting the request. 4607 If the Location value provided in a 3xx (Redirection) response does 4608 not have a fragment component, a user agent MUST process the 4609 redirection as if the value inherits the fragment component of the 4610 URI reference used to generate the target URI (i.e., the redirection 4611 inherits the original reference's fragment, if any). 4613 For example, a GET request generated for the URI reference 4614 "http://www.example.org/~tim" might result in a 303 (See Other) 4615 response containing the header field: 4617 Location: /People.html#tim 4619 which suggests that the user agent redirect to 4620 "http://www.example.org/People.html#tim" 4622 Likewise, a GET request generated for the URI reference 4623 "http://www.example.org/index.html#larry" might result in a 301 4624 (Moved Permanently) response containing the header field: 4626 Location: http://www.example.net/index.html 4628 which suggests that the user agent redirect to 4629 "http://www.example.net/index.html#larry", preserving the original 4630 fragment identifier. 4632 There are circumstances in which a fragment identifier in a Location 4633 value would not be appropriate. For example, the Location header 4634 field in a 201 (Created) response is supposed to provide a URI that 4635 is specific to the created resource. 4637 | *Note:* Some recipients attempt to recover from Location header 4638 | fields that are not valid URI references. This specification 4639 | does not mandate or define such processing, but does allow it 4640 | for the sake of robustness. A Location field value cannot 4641 | allow a list of members because the comma list separator is a 4642 | valid data character within a URI-reference. If an invalid 4643 | message is sent with multiple Location field lines, a recipient 4644 | along the path might combine those field lines into one value. 4645 | Recovery of a valid Location field value from that situation is 4646 | difficult and not interoperable across implementations. 4648 | *Note:* The Content-Location header field (Section 8.7) differs 4649 | from Location in that the Content-Location refers to the most 4650 | specific resource corresponding to the enclosed representation. 4651 | It is therefore possible for a response to contain both the 4652 | Location and Content-Location header fields. 4654 10.2.4. Retry-After 4656 Servers send the "Retry-After" header field to indicate how long the 4657 user agent ought to wait before making a follow-up request. When 4658 sent with a 503 (Service Unavailable) response, Retry-After indicates 4659 how long the service is expected to be unavailable to the client. 4660 When sent with any 3xx (Redirection) response, Retry-After indicates 4661 the minimum time that the user agent is asked to wait before issuing 4662 the redirected request. 4664 The Retry-After field value can be either an HTTP-date or a number of 4665 seconds to delay after the response is received. 4667 Retry-After = HTTP-date / delay-seconds 4669 A delay-seconds value is a non-negative decimal integer, representing 4670 time in seconds. 4672 delay-seconds = 1*DIGIT 4674 Two examples of its use are 4676 Retry-After: Fri, 31 Dec 1999 23:59:59 GMT 4677 Retry-After: 120 4679 In the latter example, the delay is 2 minutes. 4681 10.2.5. Server 4683 The "Server" header field contains information about the software 4684 used by the origin server to handle the request, which is often used 4685 by clients to help identify the scope of reported interoperability 4686 problems, to work around or tailor requests to avoid particular 4687 server limitations, and for analytics regarding server or operating 4688 system use. An origin server MAY generate a Server header field in 4689 its responses. 4691 Server = product *( RWS ( product / comment ) ) 4693 The Server header field value consists of one or more product 4694 identifiers, each followed by zero or more comments (Section 5.6.5), 4695 which together identify the origin server software and its 4696 significant subproducts. By convention, the product identifiers are 4697 listed in decreasing order of their significance for identifying the 4698 origin server software. Each product identifier consists of a name 4699 and optional version, as defined in Section 10.1.6. 4701 Example: 4703 Server: CERN/3.0 libwww/2.17 4705 An origin server SHOULD NOT generate a Server header field containing 4706 needlessly fine-grained detail and SHOULD limit the addition of 4707 subproducts by third parties. Overly long and detailed Server field 4708 values increase response latency and potentially reveal internal 4709 implementation details that might make it (slightly) easier for 4710 attackers to find and exploit known security holes. 4712 11. HTTP Authentication 4714 11.1. Authentication Scheme 4716 HTTP provides a general framework for access control and 4717 authentication, via an extensible set of challenge-response 4718 authentication schemes, which can be used by a server to challenge a 4719 client request and by a client to provide authentication information. 4720 It uses a case-insensitive token to identify the authentication 4721 scheme 4723 auth-scheme = token 4725 Aside from the general framework, this document does not specify any 4726 authentication schemes. New and existing authentication schemes are 4727 specified independently and ought to be registered within the 4728 "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry". 4729 For example, the "basic" and "digest" authentication schemes are 4730 defined by RFC 7617 and RFC 7616, respectively. 4732 11.2. Authentication Parameters 4734 The authentication scheme is followed by additional information 4735 necessary for achieving authentication via that scheme as either a 4736 comma-separated list of parameters or a single sequence of characters 4737 capable of holding base64-encoded information. 4739 token68 = 1*( ALPHA / DIGIT / 4740 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 4742 The token68 syntax allows the 66 unreserved URI characters 4743 ([RFC3986]), plus a few others, so that it can hold a base64, 4744 base64url (URL and filename safe alphabet), base32, or base16 (hex) 4745 encoding, with or without padding, but excluding whitespace 4746 ([RFC4648]). 4748 Authentication parameters are name=value pairs, where the name token 4749 is matched case-insensitively and each parameter name MUST only occur 4750 once per challenge. 4752 auth-param = token BWS "=" BWS ( token / quoted-string ) 4754 Parameter values can be expressed either as "token" or as "quoted- 4755 string" (Section 5.6). Authentication scheme definitions need to 4756 accept both notations, both for senders and recipients, to allow 4757 recipients to use generic parsing components regardless of the 4758 authentication scheme. 4760 For backwards compatibility, authentication scheme definitions can 4761 restrict the format for senders to one of the two variants. This can 4762 be important when it is known that deployed implementations will fail 4763 when encountering one of the two formats. 4765 11.3. Challenge and Response 4767 A 401 (Unauthorized) response message is used by an origin server to 4768 challenge the authorization of a user agent, including a 4769 WWW-Authenticate header field containing at least one challenge 4770 applicable to the requested resource. 4772 A 407 (Proxy Authentication Required) response message is used by a 4773 proxy to challenge the authorization of a client, including a 4774 Proxy-Authenticate header field containing at least one challenge 4775 applicable to the proxy for the requested resource. 4777 challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 4779 | *Note:* Many clients fail to parse a challenge that contains an 4780 | unknown scheme. A workaround for this problem is to list well- 4781 | supported schemes (such as "basic") first. 4783 A user agent that wishes to authenticate itself with an origin server 4784 - usually, but not necessarily, after receiving a 401 (Unauthorized) 4785 - can do so by including an Authorization header field with the 4786 request. 4788 A client that wishes to authenticate itself with a proxy - usually, 4789 but not necessarily, after receiving a 407 (Proxy Authentication 4790 Required) - can do so by including a Proxy-Authorization header field 4791 with the request. 4793 11.4. Credentials 4795 Both the Authorization field value and the Proxy-Authorization field 4796 value contain the client's credentials for the realm of the resource 4797 being requested, based upon a challenge received in a response 4798 (possibly at some point in the past). When creating their values, 4799 the user agent ought to do so by selecting the challenge with what it 4800 considers to be the most secure auth-scheme that it understands, 4801 obtaining credentials from the user as appropriate. Transmission of 4802 credentials within header field values implies significant security 4803 considerations regarding the confidentiality of the underlying 4804 connection, as described in Section 17.15.1. 4806 credentials = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 4808 Upon receipt of a request for a protected resource that omits 4809 credentials, contains invalid credentials (e.g., a bad password) or 4810 partial credentials (e.g., when the authentication scheme requires 4811 more than one round trip), an origin server SHOULD send a 401 4812 (Unauthorized) response that contains a WWW-Authenticate header field 4813 with at least one (possibly new) challenge applicable to the 4814 requested resource. 4816 Likewise, upon receipt of a request that omits proxy credentials or 4817 contains invalid or partial proxy credentials, a proxy that requires 4818 authentication SHOULD generate a 407 (Proxy Authentication Required) 4819 response that contains a Proxy-Authenticate header field with at 4820 least one (possibly new) challenge applicable to the proxy. 4822 A server that receives valid credentials that are not adequate to 4823 gain access ought to respond with the 403 (Forbidden) status code 4824 (Section 15.5.4). 4826 HTTP does not restrict applications to this simple challenge-response 4827 framework for access authentication. Additional mechanisms can be 4828 used, such as authentication at the transport level or via message 4829 encapsulation, and with additional header fields specifying 4830 authentication information. However, such additional mechanisms are 4831 not defined by this specification. 4833 Note that various custom mechanisms for user authentication use the 4834 Set-Cookie and Cookie header fields, defined in [RFC6265], for 4835 passing tokens related to authentication. 4837 11.5. Establishing a Protection Space (Realm) 4839 The _realm_ authentication parameter is reserved for use by 4840 authentication schemes that wish to indicate a scope of protection. 4842 A _protection space_ is defined by the origin (see Section 4.3.1) of 4843 the server being accessed, in combination with the realm value if 4844 present. These realms allow the protected resources on a server to 4845 be partitioned into a set of protection spaces, each with its own 4846 authentication scheme and/or authorization database. The realm value 4847 is a string, generally assigned by the origin server, that can have 4848 additional semantics specific to the authentication scheme. Note 4849 that a response can have multiple challenges with the same auth- 4850 scheme but with different realms. 4852 The protection space determines the domain over which credentials can 4853 be automatically applied. If a prior request has been authorized, 4854 the user agent MAY reuse the same credentials for all other requests 4855 within that protection space for a period of time determined by the 4856 authentication scheme, parameters, and/or user preferences (such as a 4857 configurable inactivity timeout). Unless specifically allowed by the 4858 authentication scheme, a single protection space cannot extend 4859 outside the scope of its server. 4861 For historical reasons, a sender MUST only generate the quoted-string 4862 syntax. Recipients might have to support both token and quoted- 4863 string syntax for maximum interoperability with existing clients that 4864 have been accepting both notations for a long time. 4866 11.6. Authenticating Users to Origin Servers 4868 11.6.1. WWW-Authenticate 4870 The "WWW-Authenticate" header field indicates the authentication 4871 scheme(s) and parameters applicable to the target resource. 4873 WWW-Authenticate = #challenge 4875 A server generating a 401 (Unauthorized) response MUST send a WWW- 4876 Authenticate header field containing at least one challenge. A 4877 server MAY generate a WWW-Authenticate header field in other response 4878 messages to indicate that supplying credentials (or different 4879 credentials) might affect the response. 4881 A proxy forwarding a response MUST NOT modify any WWW-Authenticate 4882 header fields in that response. 4884 User agents are advised to take special care in parsing the field 4885 value, as it might contain more than one challenge, and each 4886 challenge can contain a comma-separated list of authentication 4887 parameters. Furthermore, the header field itself can occur multiple 4888 times. 4890 For instance: 4892 WWW-Authenticate: Newauth realm="apps", type=1, 4893 title="Login to \"apps\"", Basic realm="simple" 4895 This header field contains two challenges; one for the "Newauth" 4896 scheme with a realm value of "apps", and two additional parameters 4897 "type" and "title", and another one for the "Basic" scheme with a 4898 realm value of "simple". 4900 Some user agents do not recognise this form, however. As a result, 4901 sending a WWW-Authenticate field value with more than one member on 4902 the same field line might not be interoperable. 4904 | *Note:* The challenge grammar production uses the list syntax 4905 | as well. Therefore, a sequence of comma, whitespace, and comma 4906 | can be considered either as applying to the preceding 4907 | challenge, or to be an empty entry in the list of challenges. 4908 | In practice, this ambiguity does not affect the semantics of 4909 | the header field value and thus is harmless. 4911 11.6.2. Authorization 4913 The "Authorization" header field allows a user agent to authenticate 4914 itself with an origin server - usually, but not necessarily, after 4915 receiving a 401 (Unauthorized) response. Its value consists of 4916 credentials containing the authentication information of the user 4917 agent for the realm of the resource being requested. 4919 Authorization = credentials 4921 If a request is authenticated and a realm specified, the same 4922 credentials are presumed to be valid for all other requests within 4923 this realm (assuming that the authentication scheme itself does not 4924 require otherwise, such as credentials that vary according to a 4925 challenge value or using synchronized clocks). 4927 A proxy forwarding a request MUST NOT modify any Authorization header 4928 fields in that request. See Section 3.5 of [Caching] for details of 4929 and requirements pertaining to handling of the Authorization header 4930 field by HTTP caches. 4932 11.6.3. Authentication-Info 4934 HTTP authentication schemes can use the Authentication-Info response 4935 field to communicate information after the client's authentication 4936 credentials have been accepted. This information can include a 4937 finalization message from the server (e.g., it can contain the server 4938 authentication). 4940 The field value is a list of parameters (name/value pairs), using the 4941 "auth-param" syntax defined in Section 11.3. This specification only 4942 describes the generic format; authentication schemes using 4943 Authentication-Info will define the individual parameters. The 4944 "Digest" Authentication Scheme, for instance, defines multiple 4945 parameters in Section 3.5 of [RFC7616]. 4947 Authentication-Info = #auth-param 4949 The Authentication-Info field can be used in any HTTP response, 4950 independently of request method and status code. Its semantics are 4951 defined by the authentication scheme indicated by the Authorization 4952 header field (Section 11.6.2) of the corresponding request. 4954 A proxy forwarding a response is not allowed to modify the field 4955 value in any way. 4957 Authentication-Info can be sent as a trailer field (Section 6.5) when 4958 the authentication scheme explicitly allows this. 4960 11.7. Authenticating Clients to Proxies 4962 11.7.1. Proxy-Authenticate 4964 The "Proxy-Authenticate" header field consists of at least one 4965 challenge that indicates the authentication scheme(s) and parameters 4966 applicable to the proxy for this request. A proxy MUST send at least 4967 one Proxy-Authenticate header field in each 407 (Proxy Authentication 4968 Required) response that it generates. 4970 Proxy-Authenticate = #challenge 4972 Unlike WWW-Authenticate, the Proxy-Authenticate header field applies 4973 only to the next outbound client on the response chain. This is 4974 because only the client that chose a given proxy is likely to have 4975 the credentials necessary for authentication. However, when multiple 4976 proxies are used within the same administrative domain, such as 4977 office and regional caching proxies within a large corporate network, 4978 it is common for credentials to be generated by the user agent and 4979 passed through the hierarchy until consumed. Hence, in such a 4980 configuration, it will appear as if Proxy-Authenticate is being 4981 forwarded because each proxy will send the same challenge set. 4983 Note that the parsing considerations for WWW-Authenticate apply to 4984 this header field as well; see Section 11.6.1 for details. 4986 11.7.2. Proxy-Authorization 4988 The "Proxy-Authorization" header field allows the client to identify 4989 itself (or its user) to a proxy that requires authentication. Its 4990 value consists of credentials containing the authentication 4991 information of the client for the proxy and/or realm of the resource 4992 being requested. 4994 Proxy-Authorization = credentials 4996 Unlike Authorization, the Proxy-Authorization header field applies 4997 only to the next inbound proxy that demanded authentication using the 4998 Proxy-Authenticate header field. When multiple proxies are used in a 4999 chain, the Proxy-Authorization header field is consumed by the first 5000 inbound proxy that was expecting to receive credentials. A proxy MAY 5001 relay the credentials from the client request to the next proxy if 5002 that is the mechanism by which the proxies cooperatively authenticate 5003 a given request. 5005 11.7.3. Proxy-Authentication-Info 5007 The Proxy-Authentication-Info response header field is equivalent to 5008 Authentication-Info, except that it applies to proxy authentication 5009 (Section 11.3) and its semantics are defined by the authentication 5010 scheme indicated by the Proxy-Authorization header field 5011 (Section 11.7.2) of the corresponding request: 5013 Proxy-Authentication-Info = #auth-param 5015 However, unlike Authentication-Info, the Proxy-Authentication-Info 5016 header field applies only to the next outbound client on the response 5017 chain. This is because only the client that chose a given proxy is 5018 likely to have the credentials necessary for authentication. 5019 However, when multiple proxies are used within the same 5020 administrative domain, such as office and regional caching proxies 5021 within a large corporate network, it is common for credentials to be 5022 generated by the user agent and passed through the hierarchy until 5023 consumed. Hence, in such a configuration, it will appear as if 5024 Proxy-Authentication-Info is being forwarded because each proxy will 5025 send the same field value. 5027 12. Content Negotiation 5029 When responses convey content, whether indicating a success or an 5030 error, the origin server often has different ways of representing 5031 that information; for example, in different formats, languages, or 5032 encodings. Likewise, different users or user agents might have 5033 differing capabilities, characteristics, or preferences that could 5034 influence which representation, among those available, would be best 5035 to deliver. For this reason, HTTP provides mechanisms for content 5036 negotiation. 5038 This specification defines three patterns of content negotiation that 5039 can be made visible within the protocol: "proactive" negotiation, 5040 where the server selects the representation based upon the user 5041 agent's stated preferences, "reactive" negotiation, where the server 5042 provides a list of representations for the user agent to choose from, 5043 and "request content" negotiation, where the user agent selects the 5044 representation for a future request based upon the server's stated 5045 preferences in past responses. 5047 Other patterns of content negotiation include "conditional content", 5048 where the representation consists of multiple parts that are 5049 selectively rendered based on user agent parameters, "active 5050 content", where the representation contains a script that makes 5051 additional (more specific) requests based on the user agent 5052 characteristics, and "Transparent Content Negotiation" ([RFC2295]), 5053 where content selection is performed by an intermediary. These 5054 patterns are not mutually exclusive, and each has trade-offs in 5055 applicability and practicality. 5057 Note that, in all cases, HTTP is not aware of the resource semantics. 5058 The consistency with which an origin server responds to requests, 5059 over time and over the varying dimensions of content negotiation, and 5060 thus the "sameness" of a resource's observed representations over 5061 time, is determined entirely by whatever entity or algorithm selects 5062 or generates those responses. 5064 12.1. Proactive Negotiation 5066 When content negotiation preferences are sent by the user agent in a 5067 request to encourage an algorithm located at the server to select the 5068 preferred representation, it is called _proactive negotiation_ 5069 (a.k.a., _server-driven negotiation_). Selection is based on the 5070 available representations for a response (the dimensions over which 5071 it might vary, such as language, content-coding, etc.) compared to 5072 various information supplied in the request, including both the 5073 explicit negotiation header fields below and implicit 5074 characteristics, such as the client's network address or parts of the 5075 User-Agent field. 5077 Proactive negotiation is advantageous when the algorithm for 5078 selecting from among the available representations is difficult to 5079 describe to a user agent, or when the server desires to send its 5080 "best guess" to the user agent along with the first response (hoping 5081 to avoid the round trip delay of a subsequent request if the "best 5082 guess" is good enough for the user). In order to improve the 5083 server's guess, a user agent MAY send request header fields that 5084 describe its preferences. 5086 Proactive negotiation has serious disadvantages: 5088 o It is impossible for the server to accurately determine what might 5089 be "best" for any given user, since that would require complete 5090 knowledge of both the capabilities of the user agent and the 5091 intended use for the response (e.g., does the user want to view it 5092 on screen or print it on paper?); 5094 o Having the user agent describe its capabilities in every request 5095 can be both very inefficient (given that only a small percentage 5096 of responses have multiple representations) and a potential risk 5097 to the user's privacy; 5099 o It complicates the implementation of an origin server and the 5100 algorithms for generating responses to a request; and, 5102 o It limits the reusability of responses for shared caching. 5104 A user agent cannot rely on proactive negotiation preferences being 5105 consistently honored, since the origin server might not implement 5106 proactive negotiation for the requested resource or might decide that 5107 sending a response that doesn't conform to the user agent's 5108 preferences is better than sending a 406 (Not Acceptable) response. 5110 A Vary header field (Section 12.5.5) is often sent in a response 5111 subject to proactive negotiation to indicate what parts of the 5112 request information were used in the selection algorithm. 5114 The request header fields Accept, Accept-Charset, Accept-Encoding, 5115 and Accept-Language are defined below for a user agent to engage in 5116 proactive negotiation of the response content. The preferences sent 5117 in these fields apply to any content in the response, including 5118 representations of the target resource, representations of error or 5119 processing status, and potentially even the miscellaneous text 5120 strings that might appear within the protocol. 5122 12.2. Reactive Negotiation 5124 With _reactive negotiation_ (a.k.a., _agent-driven negotiation_), 5125 selection of the best response representation (regardless of the 5126 status code) is performed by the user agent after receiving an 5127 initial response from the origin server that contains a list of 5128 resources for alternative representations. 5130 If the user agent is not satisfied by the initial response 5131 representation, it can perform a GET request on one or more of the 5132 alternative resources, selected based on metadata included in the 5133 list, to obtain a different form of representation for that response. 5134 Selection of alternatives might be performed automatically by the 5135 user agent or manually by the user selecting from a generated 5136 (possibly hypertext) menu. 5138 Note that the above refers to representations of the response, in 5139 general, not representations of the resource. The alternative 5140 representations are only considered representations of the target 5141 resource if the response in which those alternatives are provided has 5142 the semantics of being a representation of the target resource (e.g., 5143 a 200 (OK) response to a GET request) or has the semantics of 5144 providing links to alternative representations for the target 5145 resource (e.g., a 300 (Multiple Choices) response to a GET request). 5147 A server might choose not to send an initial representation, other 5148 than the list of alternatives, and thereby indicate that reactive 5149 negotiation by the user agent is preferred. For example, the 5150 alternatives listed in responses with the 300 (Multiple Choices) and 5151 406 (Not Acceptable) status codes include information about the 5152 available representations so that the user or user agent can react by 5153 making a selection. 5155 Reactive negotiation is advantageous when the response would vary 5156 over commonly used dimensions (such as type, language, or encoding), 5157 when the origin server is unable to determine a user agent's 5158 capabilities from examining the request, and generally when public 5159 caches are used to distribute server load and reduce network usage. 5161 Reactive negotiation suffers from the disadvantages of transmitting a 5162 list of alternatives to the user agent, which degrades user-perceived 5163 latency if transmitted in the header section, and needing a second 5164 request to obtain an alternate representation. Furthermore, this 5165 specification does not define a mechanism for supporting automatic 5166 selection, though it does not prevent such a mechanism from being 5167 developed as an extension. 5169 12.3. Request Content Negotiation 5171 When content negotiation preferences are sent in a server's response, 5172 the listed preferences are called _request content negotiation_ 5173 because they intend to influence selection of an appropriate content 5174 for subsequent requests to that resource. For example, the Accept 5175 (Section 12.5.1) and Accept-Encoding (Section 12.5.3) header fields 5176 can be sent in a response to indicate preferred media types and 5177 content codings for subsequent requests to that resource. 5179 Similarly, Section 3.1 of [RFC5789] defines the "Accept-Patch" 5180 response header field which allows discovery of which content types 5181 are accepted in PATCH requests. 5183 12.4. Content Negotiation Field Features 5185 12.4.1. Absence 5187 For each of the content negotiation fields, a request that does not 5188 contain the field implies that the sender has no preference on that 5189 axis of negotiation. 5191 If a content negotiation header field is present in a request and 5192 none of the available representations for the response can be 5193 considered acceptable according to it, the origin server can either 5194 honor the header field by sending a 406 (Not Acceptable) response or 5195 disregard the header field by treating the response as if it is not 5196 subject to content negotiation for that request header field. This 5197 does not imply, however, that the client will be able to use the 5198 representation. 5200 | *Note:* Sending these header fields makes it easier for a 5201 | server to identify an individual by virtue of the user agent's 5202 | request characteristics (Section 17.12). 5204 12.4.2. Quality Values 5206 The content negotiation fields defined by this specification use a 5207 common parameter, named "q" (case-insensitive), to assign a relative 5208 "weight" to the preference for that associated kind of content. This 5209 weight is referred to as a "quality value" (or "qvalue") because the 5210 same parameter name is often used within server configurations to 5211 assign a weight to the relative quality of the various 5212 representations that can be selected for a resource. 5214 The weight is normalized to a real number in the range 0 through 1, 5215 where 0.001 is the least preferred and 1 is the most preferred; a 5216 value of 0 means "not acceptable". If no "q" parameter is present, 5217 the default weight is 1. 5219 weight = OWS ";" OWS "q=" qvalue 5220 qvalue = ( "0" [ "." 0*3DIGIT ] ) 5221 / ( "1" [ "." 0*3("0") ] ) 5223 A sender of qvalue MUST NOT generate more than three digits after the 5224 decimal point. User configuration of these values ought to be 5225 limited in the same fashion. 5227 12.4.3. Wildcard Values 5229 Most of these header fields, where indicated, define a wildcard value 5230 ("*") to select unspecified values. If no wildcard is present, 5231 values that are not explicitly mentioned in the field are considered 5232 unacceptable, except for within Vary where it means the variance is 5233 unlimited. 5235 | *Note:* In practice, using wildcards in content negotiation has 5236 | limited practical value, because it is seldom useful to say, 5237 | for example, "I prefer image/* more or less than (some other 5238 | specific value)". Clients can explicitly request a 406 (Not 5239 | Acceptable) response if a more preferred format is not 5240 | available by sending Accept: */*;q=0, but they still need to be 5241 | able to handle a different response, since the server is 5242 | allowed to ignore their preference. 5244 12.5. Content Negotiation Fields 5245 12.5.1. Accept 5247 The "Accept" header field can be used by user agents to specify their 5248 preferences regarding response media types. For example, Accept 5249 header fields can be used to indicate that the request is 5250 specifically limited to a small set of desired types, as in the case 5251 of a request for an in-line image. 5253 When sent by a server in a response, Accept provides information 5254 about what content types are preferred in the content of a subsequent 5255 request to the same resource. 5257 Accept = #( media-range [ weight ] ) 5259 media-range = ( "*/*" 5260 / ( type "/" "*" ) 5261 / ( type "/" subtype ) 5262 ) parameters 5264 The asterisk "*" character is used to group media types into ranges, 5265 with "*/*" indicating all media types and "type/*" indicating all 5266 subtypes of that type. The media-range can include media type 5267 parameters that are applicable to that range. 5269 Each media-range might be followed by optional applicable media type 5270 parameters (e.g., charset), followed by an optional "q" parameter for 5271 indicating a relative weight (Section 12.4.2). 5273 Previous specifications allowed additional extension parameters to 5274 appear after the weight parameter. The accept extension grammar 5275 (accept-ext) has been removed because it had a complicated 5276 definition, was not being used in practice, and is more easily 5277 deployed through new header fields. Senders using weights SHOULD 5278 send "q" last (after all media-range parameters). Recipients SHOULD 5279 process any parameter named "q" as weight, regardless of parameter 5280 ordering. 5282 | *Note:* Use of the "q" parameter name to control content 5283 | negotiation is due to historical practice. Although this 5284 | prevents any media type parameter named "q" from being used 5285 | with a media range, such an event is believed to be unlikely 5286 | given the lack of any "q" parameters in the IANA media type 5287 | registry and the rare usage of any media type parameters in 5288 | Accept. Future media types are discouraged from registering 5289 | any parameter named "q". 5291 The example 5292 Accept: audio/*; q=0.2, audio/basic 5294 is interpreted as "I prefer audio/basic, but send me any audio type 5295 if it is the best available after an 80% markdown in quality". 5297 A more elaborate example is 5299 Accept: text/plain; q=0.5, text/html, 5300 text/x-dvi; q=0.8, text/x-c 5302 Verbally, this would be interpreted as "text/html and text/x-c are 5303 the equally preferred media types, but if they do not exist, then 5304 send the text/x-dvi representation, and if that does not exist, send 5305 the text/plain representation". 5307 Media ranges can be overridden by more specific media ranges or 5308 specific media types. If more than one media range applies to a 5309 given type, the most specific reference has precedence. For example, 5311 Accept: text/*, text/plain, text/plain;format=flowed, */* 5313 have the following precedence: 5315 1. text/plain;format=flowed 5317 2. text/plain 5319 3. text/* 5321 4. */* 5323 The media type quality factor associated with a given type is 5324 determined by finding the media range with the highest precedence 5325 that matches the type. For example, 5327 Accept: text/*;q=0.3, text/plain;q=0.7, text/plain;format=flowed, 5328 text/plain;format=fixed;q=0.4, */*;q=0.5 5330 would cause the following values to be associated: 5332 -------------------------- --------------- 5333 Media Type Quality Value 5334 -------------------------- --------------- 5335 text/plain;format=flowed 1 5336 text/plain 0.7 5337 text/html 0.3 5338 image/jpeg 0.5 5339 text/plain;format=fixed 0.4 5340 text/html;level=3 0.7 5341 -------------------------- --------------- 5343 Table 5 5345 | *Note:* A user agent might be provided with a default set of 5346 | quality values for certain media ranges. However, unless the 5347 | user agent is a closed system that cannot interact with other 5348 | rendering agents, this default set ought to be configurable by 5349 | the user. 5351 12.5.2. Accept-Charset 5353 The "Accept-Charset" header field can be sent by a user agent to 5354 indicate its preferences for charsets in textual response content. 5355 For example, this field allows user agents capable of understanding 5356 more comprehensive or special-purpose charsets to signal that 5357 capability to an origin server that is capable of representing 5358 information in those charsets. 5360 Accept-Charset = #( ( charset / "*" ) [ weight ] ) 5362 Charset names are defined in Section 8.3.2. A user agent MAY 5363 associate a quality value with each charset to indicate the user's 5364 relative preference for that charset, as defined in Section 12.4.2. 5365 An example is 5367 Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 5369 The special value "*", if present in the Accept-Charset header field, 5370 matches every charset that is not mentioned elsewhere in the field. 5372 | *Note:* Accept-Charset is deprecated because UTF-8 has become 5373 | nearly ubiquitous and sending a detailed list of user-preferred 5374 | charsets wastes bandwidth, increases latency, and makes passive 5375 | fingerprinting far too easy (Section 17.12). Most general- 5376 | purpose user agents do not send Accept-Charset, unless 5377 | specifically configured to do so. 5379 12.5.3. Accept-Encoding 5381 The "Accept-Encoding" header field can be used to indicate 5382 preferences regarding the use of content codings (Section 8.4.1). 5384 When sent by a user agent in a request, Accept-Encoding indicates the 5385 content codings acceptable in a response. 5387 When sent by a server in a response, Accept-Encoding provides 5388 information about what content codings are preferred in the content 5389 of a subsequent request to the same resource. 5391 An "identity" token is used as a synonym for "no encoding" in order 5392 to communicate when no encoding is preferred. 5394 Accept-Encoding = #( codings [ weight ] ) 5395 codings = content-coding / "identity" / "*" 5397 Each codings value MAY be given an associated quality value 5398 representing the preference for that encoding, as defined in 5399 Section 12.4.2. The asterisk "*" symbol in an Accept-Encoding field 5400 matches any available content-coding not explicitly listed in the 5401 field. 5403 For example, 5405 Accept-Encoding: compress, gzip 5406 Accept-Encoding: 5407 Accept-Encoding: * 5408 Accept-Encoding: compress;q=0.5, gzip;q=1.0 5409 Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 5411 A server tests whether a content-coding for a given representation is 5412 acceptable using these rules: 5414 1. If no Accept-Encoding header field is in the request, any 5415 content-coding is considered acceptable by the user agent. 5417 2. If the representation has no content-coding, then it is 5418 acceptable by default unless specifically excluded by the Accept- 5419 Encoding header field stating either "identity;q=0" or "*;q=0" 5420 without a more specific entry for "identity". 5422 3. If the representation's content-coding is one of the content- 5423 codings listed in the Accept-Encoding field value, then it is 5424 acceptable unless it is accompanied by a qvalue of 0. (As 5425 defined in Section 12.4.2, a qvalue of 0 means "not acceptable".) 5427 4. If multiple content-codings are acceptable, then the acceptable 5428 content-coding with the highest non-zero qvalue is preferred. 5430 An Accept-Encoding header field with a field value that is empty 5431 implies that the user agent does not want any content-coding in 5432 response. If an Accept-Encoding header field is present in a request 5433 and none of the available representations for the response have a 5434 content-coding that is listed as acceptable, the origin server SHOULD 5435 send a response without any content-coding. 5437 When the Accept-Encoding header field is present in a response, it 5438 indicates what content codings the resource was willing to accept in 5439 the associated request. The field value is evaluated the same way as 5440 in a request. 5442 Note that this information is specific to the associated request; the 5443 set of supported encodings might be different for other resources on 5444 the same server and could change over time or depend on other aspects 5445 of the request (such as the request method). 5447 Servers that fail a request due to an unsupported content coding 5448 ought to respond with a 415 (Unsupported Media Type) status and 5449 include an Accept-Encoding header field in that response, allowing 5450 clients to distinguish between issues related to content codings and 5451 media types. In order to avoid confusion with issues related to 5452 media types, servers that fail a request with a 415 status for 5453 reasons unrelated to content codings MUST NOT include the Accept- 5454 Encoding header field. 5456 The most common use of Accept-Encoding is in responses with a 415 5457 (Unsupported Media Type) status code, in response to optimistic use 5458 of a content coding by clients. However, the header field can also 5459 be used to indicate to clients that content codings are supported, to 5460 optimize future interactions. For example, a resource might include 5461 it in a 2xx (Successful) response when the request content was big 5462 enough to justify use of a compression coding but the client failed 5463 do so. 5465 | *Note:* Most HTTP/1.0 applications do not recognize or obey 5466 | qvalues associated with content-codings. This means that 5467 | qvalues might not work and are not permitted with x-gzip or 5468 | x-compress. 5470 12.5.4. Accept-Language 5472 The "Accept-Language" header field can be used by user agents to 5473 indicate the set of natural languages that are preferred in the 5474 response. Language tags are defined in Section 8.5.1. 5476 Accept-Language = #( language-range [ weight ] ) 5477 language-range = 5478 5480 Each language-range can be given an associated quality value 5481 representing an estimate of the user's preference for the languages 5482 specified by that range, as defined in Section 12.4.2. For example, 5484 Accept-Language: da, en-gb;q=0.8, en;q=0.7 5486 would mean: "I prefer Danish, but will accept British English and 5487 other types of English". 5489 Note that some recipients treat the order in which language tags are 5490 listed as an indication of descending priority, particularly for tags 5491 that are assigned equal quality values (no value is the same as q=1). 5492 However, this behavior cannot be relied upon. For consistency and to 5493 maximize interoperability, many user agents assign each language tag 5494 a unique quality value while also listing them in order of decreasing 5495 quality. Additional discussion of language priority lists can be 5496 found in Section 2.3 of [RFC4647]. 5498 For matching, Section 3 of [RFC4647] defines several matching 5499 schemes. Implementations can offer the most appropriate matching 5500 scheme for their requirements. The "Basic Filtering" scheme 5501 ([RFC4647], Section 3.3.1) is identical to the matching scheme that 5502 was previously defined for HTTP in Section 14.4 of [RFC2616]. 5504 It might be contrary to the privacy expectations of the user to send 5505 an Accept-Language header field with the complete linguistic 5506 preferences of the user in every request (Section 17.12). 5508 Since intelligibility is highly dependent on the individual user, 5509 user agents need to allow user control over the linguistic preference 5510 (either through configuration of the user agent itself or by 5511 defaulting to a user controllable system setting). A user agent that 5512 does not provide such control to the user MUST NOT send an Accept- 5513 Language header field. 5515 | *Note:* User agents ought to provide guidance to users when 5516 | setting a preference, since users are rarely familiar with the 5517 | details of language matching as described above. For example, 5518 | users might assume that on selecting "en-gb", they will be 5519 | served any kind of English document if British English is not 5520 | available. A user agent might suggest, in such a case, to add 5521 | "en" to the list for better matching behavior. 5523 12.5.5. Vary 5525 The "Vary" header field in a response describes what parts of a 5526 request message, aside from the method and target URI, might 5527 influence the origin server's process for selecting and representing 5528 this response. 5530 Vary = #( "*" / field-name ) 5532 A Vary field value is a list of request field names, known as the 5533 selecting header fields, that might have a role in selecting the 5534 representation for this response. Potential selecting header fields 5535 are not limited to those defined by this specification. 5537 If the list contains "*", it signals that other aspects of the 5538 request might play a role in selecting the response representation, 5539 possibly including elements outside the message syntax (e.g., the 5540 client's network address). A recipient will not be able to determine 5541 whether this response is appropriate for a later request without 5542 forwarding the request to the origin server. A proxy MUST NOT 5543 generate "*" in a Vary field value. 5545 For example, a response that contains 5547 Vary: accept-encoding, accept-language 5549 indicates that the origin server might have used the request's 5550 Accept-Encoding and Accept-Language header fields (or lack thereof) 5551 as determining factors while choosing the content for this response. 5553 An origin server might send Vary with a list of header fields for two 5554 purposes: 5556 1. To inform cache recipients that they MUST NOT use this response 5557 to satisfy a later request unless the later request has the same 5558 values for the listed header fields as the original request 5559 (Section 4.1 of [Caching]). In other words, Vary expands the 5560 cache key required to match a new request to the stored cache 5561 entry. 5563 2. To inform user agent recipients that this response is subject to 5564 content negotiation (Section 12) and that a different 5565 representation might be sent in a subsequent request if 5566 additional parameters are provided in the listed header fields 5567 (proactive negotiation). 5569 An origin server SHOULD send a Vary header field when its algorithm 5570 for selecting a representation varies based on aspects of the request 5571 message other than the method and target URI, unless the variance 5572 cannot be crossed or the origin server has been deliberately 5573 configured to prevent cache transparency. For example, there is no 5574 need to send the Authorization field name in Vary because reuse 5575 across users is constrained by the field definition (Section 11.6.2). 5576 Likewise, an origin server might use Cache-Control response 5577 directives (Section 5.2 of [Caching]) to supplant Vary if it 5578 considers the variance less significant than the performance cost of 5579 Vary's impact on caching. 5581 13. Conditional Requests 5583 A conditional request is an HTTP request with one or more request 5584 header fields that indicate a precondition to be tested before 5585 applying the request method to the target resource. Section 13.2 5586 defines when to evaluate preconditions and their order of precedence 5587 when more than one precondition is present. 5589 Conditional GET requests are the most efficient mechanism for HTTP 5590 cache updates [Caching]. Conditionals can also be applied to state- 5591 changing methods, such as PUT and DELETE, to prevent the "lost 5592 update" problem: one client accidentally overwriting the work of 5593 another client that has been acting in parallel. 5595 Conditional request preconditions are based on the state of the 5596 target resource as a whole (its current value set) or the state as 5597 observed in a previously obtained representation (one value in that 5598 set). A resource might have multiple current representations, each 5599 with its own observable state. The conditional request mechanisms 5600 assume that the mapping of requests to a selected representation 5601 (Section 3.2) will be consistent over time if the server intends to 5602 take advantage of conditionals. Regardless, if the mapping is 5603 inconsistent and the server is unable to select the appropriate 5604 representation, then no harm will result when the precondition 5605 evaluates to false. 5607 13.1. Preconditions 5609 The request header fields below allow a client to place a 5610 precondition on the state of the target resource, so that the action 5611 corresponding to the method semantics will not be applied if the 5612 precondition evaluates to false. Each precondition defined by this 5613 specification consists of a comparison between a set of validators 5614 obtained from prior representations of the target resource to the 5615 current state of validators for the selected representation 5616 (Section 8.8). Hence, these preconditions evaluate whether the state 5617 of the target resource has changed since a given state known by the 5618 client. The effect of such an evaluation depends on the method 5619 semantics and choice of conditional, as defined in Section 13.2. 5621 13.1.1. If-Match 5623 The "If-Match" header field makes the request method conditional on 5624 the recipient origin server either having at least one current 5625 representation of the target resource, when the field value is "*", 5626 or having a current representation of the target resource that has an 5627 entity-tag matching a member of the list of entity-tags provided in 5628 the field value. 5630 An origin server MUST use the strong comparison function when 5631 comparing entity-tags for If-Match (Section 8.8.3.2), since the 5632 client intends this precondition to prevent the method from being 5633 applied if there have been any changes to the representation data. 5635 If-Match = "*" / #entity-tag 5637 Examples: 5639 If-Match: "xyzzy" 5640 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 5641 If-Match: * 5643 If-Match is most often used with state-changing methods (e.g., POST, 5644 PUT, DELETE) to prevent accidental overwrites when multiple user 5645 agents might be acting in parallel on the same resource (i.e., to 5646 prevent the "lost update" problem). It can also be used with any 5647 method to abort a request if the selected representation does not 5648 match one that the client has already stored (or partially stored) 5649 from a prior request. 5651 An origin server that receives an If-Match header field MUST evaluate 5652 the condition as per Section 13.2 prior to performing the method. 5654 To evaluate a received If-Match header field: 5656 1. If the field value is "*", the condition is true if the origin 5657 server has a current representation for the target resource. 5659 2. If the field value is a list of entity-tags, the condition is 5660 true if any of the listed tags match the entity-tag of the 5661 selected representation. 5663 3. Otherwise, the condition is false. 5665 An origin server MUST NOT perform the requested method if a received 5666 If-Match condition evaluates to false. Instead, the origin server 5667 MAY indicate that the conditional request failed by responding with a 5668 412 (Precondition Failed) status code. Alternatively, if the request 5669 is a state-changing operation that appears to have already been 5670 applied to the selected representation, the origin server MAY respond 5671 with a 2xx (Successful) status code (i.e., the change requested by 5672 the user agent has already succeeded, but the user agent might not be 5673 aware of it, perhaps because the prior response was lost or an 5674 equivalent change was made by some other user agent). 5676 Allowing an origin server to send a success response when a change 5677 request appears to have already been applied is more efficient for 5678 many authoring use cases, but comes with some risk if multiple user 5679 agents are making change requests that are very similar but not 5680 cooperative. For example, multiple user agents writing to a common 5681 resource as a semaphore (e.g., a non-atomic increment) are likely to 5682 collide and potentially lose important state transitions. For those 5683 kinds of resources, an origin server is better off being stringent in 5684 sending 412 for every failed precondition on an unsafe method. In 5685 other cases, excluding the ETag field from a success response might 5686 encourage the user agent to perform a GET as its next request to 5687 eliminate confusion about the resource's current state. 5689 The If-Match header field can be ignored by caches and intermediaries 5690 because it is not applicable to a stored response. 5692 Note that an If-Match header field with a list value containing "*" 5693 and other values (including other instances of "*") is unlikely to be 5694 interoperable. 5696 13.1.2. If-None-Match 5698 The "If-None-Match" header field makes the request method conditional 5699 on a recipient cache or origin server either not having any current 5700 representation of the target resource, when the field value is "*", 5701 or having a selected representation with an entity-tag that does not 5702 match any of those listed in the field value. 5704 A recipient MUST use the weak comparison function when comparing 5705 entity-tags for If-None-Match (Section 8.8.3.2), since weak entity- 5706 tags can be used for cache validation even if there have been changes 5707 to the representation data. 5709 If-None-Match = "*" / #entity-tag 5711 Examples: 5713 If-None-Match: "xyzzy" 5714 If-None-Match: W/"xyzzy" 5715 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 5716 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 5717 If-None-Match: * 5719 If-None-Match is primarily used in conditional GET requests to enable 5720 efficient updates of cached information with a minimum amount of 5721 transaction overhead. When a client desires to update one or more 5722 stored responses that have entity-tags, the client SHOULD generate an 5723 If-None-Match header field containing a list of those entity-tags 5724 when making a GET request; this allows recipient servers to send a 5725 304 (Not Modified) response to indicate when one of those stored 5726 responses matches the selected representation. 5728 If-None-Match can also be used with a value of "*" to prevent an 5729 unsafe request method (e.g., PUT) from inadvertently modifying an 5730 existing representation of the target resource when the client 5731 believes that the resource does not have a current representation 5732 (Section 9.2.1). This is a variation on the "lost update" problem 5733 that might arise if more than one client attempts to create an 5734 initial representation for the target resource. 5736 An origin server that receives an If-None-Match header field MUST 5737 evaluate the condition as per Section 13.2 prior to performing the 5738 method. 5740 To evaluate a received If-None-Match header field: 5742 1. If the field value is "*", the condition is false if the origin 5743 server has a current representation for the target resource. 5745 2. If the field value is a list of entity-tags, the condition is 5746 false if one of the listed tags matches the entity-tag of the 5747 selected representation. 5749 3. Otherwise, the condition is true. 5751 An origin server MUST NOT perform the requested method if a received 5752 If-None-Match condition evaluates to false; instead, the origin 5753 server MUST respond with either a) the 304 (Not Modified) status code 5754 if the request method is GET or HEAD or b) the 412 (Precondition 5755 Failed) status code for all other request methods. 5757 Requirements on cache handling of a received If-None-Match header 5758 field are defined in Section 4.3.2 of [Caching]. 5760 Note that an If-None-Match header field with a list value containing 5761 "*" and other values (including other instances of "*") is unlikely 5762 to be interoperable. 5764 13.1.3. If-Modified-Since 5766 The "If-Modified-Since" header field makes a GET or HEAD request 5767 method conditional on the selected representation's modification date 5768 being more recent than the date provided in the field value. 5769 Transfer of the selected representation's data is avoided if that 5770 data has not changed. 5772 If-Modified-Since = HTTP-date 5774 An example of the field is: 5776 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 5778 A recipient MUST ignore If-Modified-Since if the request contains an 5779 If-None-Match header field; the condition in If-None-Match is 5780 considered to be a more accurate replacement for the condition in If- 5781 Modified-Since, and the two are only combined for the sake of 5782 interoperating with older intermediaries that might not implement 5783 If-None-Match. 5785 A recipient MUST ignore the If-Modified-Since header field if the 5786 received field value is not a valid HTTP-date, the field value has 5787 more than one member, or if the request method is neither GET nor 5788 HEAD. 5790 A recipient MUST interpret an If-Modified-Since field value's 5791 timestamp in terms of the origin server's clock. 5793 If-Modified-Since is typically used for two distinct purposes: 1) to 5794 allow efficient updates of a cached representation that does not have 5795 an entity-tag and 2) to limit the scope of a web traversal to 5796 resources that have recently changed. 5798 When used for cache updates, a cache will typically use the value of 5799 the cached message's Last-Modified header field to generate the field 5800 value of If-Modified-Since. This behavior is most interoperable for 5801 cases where clocks are poorly synchronized or when the server has 5802 chosen to only honor exact timestamp matches (due to a problem with 5803 Last-Modified dates that appear to go "back in time" when the origin 5804 server's clock is corrected or a representation is restored from an 5805 archived backup). However, caches occasionally generate the field 5806 value based on other data, such as the Date header field of the 5807 cached message or the local clock time that the message was received, 5808 particularly when the cached message does not contain a Last-Modified 5809 header field. 5811 When used for limiting the scope of retrieval to a recent time 5812 window, a user agent will generate an If-Modified-Since field value 5813 based on either its own local clock or a Date header field received 5814 from the server in a prior response. Origin servers that choose an 5815 exact timestamp match based on the selected representation's 5816 Last-Modified header field will not be able to help the user agent 5817 limit its data transfers to only those changed during the specified 5818 window. 5820 An origin server that receives an If-Modified-Since header field 5821 SHOULD evaluate the condition as per Section 13.2 prior to performing 5822 the method. 5824 To evaluate a received If-Modified-Since header field: 5826 1. If the selected representation's last modification date is 5827 earlier or equal to the date provided in the field value, the 5828 condition is false. 5830 2. Otherwise, the condition is true. 5832 An origin server SHOULD NOT perform the requested method if a 5833 received If-Modified-Since condition evaluates to false; instead, the 5834 origin server SHOULD generate a 304 (Not Modified) response, 5835 including only those metadata that are useful for identifying or 5836 updating a previously cached response. 5838 Requirements on cache handling of a received If-Modified-Since header 5839 field are defined in Section 4.3.2 of [Caching]. 5841 13.1.4. If-Unmodified-Since 5843 The "If-Unmodified-Since" header field makes the request method 5844 conditional on the selected representation's last modification date 5845 being earlier than or equal to the date provided in the field value. 5846 This field accomplishes the same purpose as If-Match for cases where 5847 the user agent does not have an entity-tag for the representation. 5849 If-Unmodified-Since = HTTP-date 5851 An example of the field is: 5853 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 5855 A recipient MUST ignore If-Unmodified-Since if the request contains 5856 an If-Match header field; the condition in If-Match is considered to 5857 be a more accurate replacement for the condition in If-Unmodified- 5858 Since, and the two are only combined for the sake of interoperating 5859 with older intermediaries that might not implement If-Match. 5861 A recipient MUST ignore the If-Unmodified-Since header field if the 5862 received field value is not a valid HTTP-date (including when the 5863 field value appears to be a list of dates). 5865 A recipient MUST interpret an If-Unmodified-Since field value's 5866 timestamp in terms of the origin server's clock. 5868 If-Unmodified-Since is most often used with state-changing methods 5869 (e.g., POST, PUT, DELETE) to prevent accidental overwrites when 5870 multiple user agents might be acting in parallel on a resource that 5871 does not supply entity-tags with its representations (i.e., to 5872 prevent the "lost update" problem). It can also be used with any 5873 method to abort a request if the selected representation does not 5874 match one that the client already stored (or partially stored) from a 5875 prior request. 5877 An origin server that receives an If-Unmodified-Since header field 5878 without an If-Match header field MUST evaluate the condition as per 5879 Section 13.2 prior to performing the method. 5881 To evaluate a received If-Unmodified-Since header field: 5883 1. If the selected representation's last modification date is 5884 earlier than or equal to the date provided in the field value, 5885 the condition is true. 5887 2. Otherwise, the condition is false. 5889 An origin server MUST NOT perform the requested method if an If- 5890 Unmodified-Since condition evaluates to false. Instead, the origin 5891 server MAY indicate that the conditional request failed by responding 5892 with a 412 (Precondition Failed) status code. Alternatively, if the 5893 request is a state-changing operation that appears to have already 5894 been applied to the selected representation, the origin server MAY 5895 respond with a 2xx (Successful) status code (i.e., the change 5896 requested by the user agent has already succeeded, but the user agent 5897 might not be aware of it, perhaps because the prior response was lost 5898 or an equivalent change was made by some other user agent). 5900 Allowing an origin server to send a success response when a change 5901 request appears to have already been applied is more efficient for 5902 many authoring use cases, but comes with some risk if multiple user 5903 agents are making change requests that are very similar but not 5904 cooperative. In those cases, an origin server is better off being 5905 stringent in sending 412 for every failed precondition on an unsafe 5906 method. 5908 The If-Unmodified-Since header field can be ignored by caches and 5909 intermediaries because it is not applicable to a stored response. 5911 13.1.5. If-Range 5913 The "If-Range" header field provides a special conditional request 5914 mechanism that is similar to the If-Match and If-Unmodified-Since 5915 header fields but that instructs the recipient to ignore the Range 5916 header field if the validator doesn't match, resulting in transfer of 5917 the new selected representation instead of a 412 (Precondition 5918 Failed) response. 5920 If a client has a partial copy of a representation and wishes to have 5921 an up-to-date copy of the entire representation, it could use the 5922 Range header field with a conditional GET (using either or both of 5923 If-Unmodified-Since and If-Match.) However, if the precondition 5924 fails because the representation has been modified, the client would 5925 then have to make a second request to obtain the entire current 5926 representation. 5928 The "If-Range" header field allows a client to "short-circuit" the 5929 second request. Informally, its meaning is as follows: if the 5930 representation is unchanged, send me the part(s) that I am requesting 5931 in Range; otherwise, send me the entire representation. 5933 If-Range = entity-tag / HTTP-date 5935 A valid entity-tag can be distinguished from a valid HTTP-date by 5936 examining the first three characters for a DQUOTE. 5938 A client MUST NOT generate an If-Range header field in a request that 5939 does not contain a Range header field. A server MUST ignore an If- 5940 Range header field received in a request that does not contain a 5941 Range header field. An origin server MUST ignore an If-Range header 5942 field received in a request for a target resource that does not 5943 support Range requests. 5945 A client MUST NOT generate an If-Range header field containing an 5946 entity-tag that is marked as weak. A client MUST NOT generate an If- 5947 Range header field containing an HTTP-date unless the client has no 5948 entity-tag for the corresponding representation and the date is a 5949 strong validator in the sense defined by Section 8.8.2.2. 5951 A server that receives an If-Range header field on a Range request 5952 MUST evaluate the condition as per Section 13.2 prior to performing 5953 the method. 5955 To evaluate a received If-Range header field containing an HTTP-date: 5957 1. If the HTTP-date validator provided is not a strong validator in 5958 the sense defined by Section 8.8.2.2, the condition is false. 5960 2. If the HTTP-date validator provided exactly matches the 5961 Last-Modified field value for the selected representation, the 5962 condition is true. 5964 3. Otherwise, the condition is false. 5966 To evaluate a received If-Range header field containing an 5967 entity-tag: 5969 1. If the entity-tag validator provided exactly matches the ETag 5970 field value for the selected representation using the strong 5971 comparison function (Section 8.8.3.2), the condition is true. 5973 2. Otherwise, the condition is false. 5975 A recipient of an If-Range header field MUST ignore the Range header 5976 field if the If-Range condition evaluates to false. Otherwise, the 5977 recipient SHOULD process the Range header field as requested. 5979 Note that the If-Range comparison by exact match, including when the 5980 validator is an HTTP-date, differs from the "earlier than or equal 5981 to" comparison used when evaluating an If-Unmodified-Since 5982 conditional. 5984 13.2. Evaluation of Preconditions 5985 13.2.1. When to Evaluate 5987 Except when excluded below, a recipient cache or origin server MUST 5988 evaluate received request preconditions after it has successfully 5989 performed its normal request checks and just before it would process 5990 the request content (if any) or perform the action associated with 5991 the request method. A server MUST ignore all received preconditions 5992 if its response to the same request without those conditions, prior 5993 to processing the request content, would have been a status code 5994 other than a 2xx (Successful) or 412 (Precondition Failed). In other 5995 words, redirects and failures that can be detected before significant 5996 processing occurs take precedence over the evaluation of 5997 preconditions. 5999 A server that is not the origin server for the target resource and 6000 cannot act as a cache for requests on the target resource MUST NOT 6001 evaluate the conditional request header fields defined by this 6002 specification, and it MUST forward them if the request is forwarded, 6003 since the generating client intends that they be evaluated by a 6004 server that can provide a current representation. Likewise, a server 6005 MUST ignore the conditional request header fields defined by this 6006 specification when received with a request method that does not 6007 involve the selection or modification of a selected representation, 6008 such as CONNECT, OPTIONS, or TRACE. 6010 Note that protocol extensions can modify the conditions under which 6011 revalidation is triggered. For example, the "immutable" cache 6012 directive (defined by [RFC8246]) instructs caches to forgo 6013 revalidation of fresh responses even when requested by the client. 6015 Conditional request header fields that are defined by extensions to 6016 HTTP might place conditions on all recipients, on the state of the 6017 target resource in general, or on a group of resources. For 6018 instance, the "If" header field in WebDAV can make a request 6019 conditional on various aspects of multiple resources, such as locks, 6020 if the recipient understands and implements that field ([RFC4918], 6021 Section 10.4). 6023 Although conditional request header fields are defined as being 6024 usable with the HEAD method (to keep HEAD's semantics consistent with 6025 those of GET), there is no point in sending a conditional HEAD 6026 because a successful response is around the same size as a 304 (Not 6027 Modified) response and more useful than a 412 (Precondition Failed) 6028 response. 6030 13.2.2. Precedence of Preconditions 6032 When more than one conditional request header field is present in a 6033 request, the order in which the fields are evaluated becomes 6034 important. In practice, the fields defined in this document are 6035 consistently implemented in a single, logical order, since "lost 6036 update" preconditions have more strict requirements than cache 6037 validation, a validated cache is more efficient than a partial 6038 response, and entity tags are presumed to be more accurate than date 6039 validators. 6041 A recipient cache or origin server MUST evaluate the request 6042 preconditions defined by this specification in the following order: 6044 1. When recipient is the origin server and If-Match is present, 6045 evaluate the If-Match precondition: 6047 o if true, continue to step 3 6049 o if false, respond 412 (Precondition Failed) unless it can be 6050 determined that the state-changing request has already 6051 succeeded (see Section 13.1.1) 6053 2. When recipient is the origin server, If-Match is not present, and 6054 If-Unmodified-Since is present, evaluate the If-Unmodified-Since 6055 precondition: 6057 o if true, continue to step 3 6059 o if false, respond 412 (Precondition Failed) unless it can be 6060 determined that the state-changing request has already 6061 succeeded (see Section 13.1.4) 6063 3. When If-None-Match is present, evaluate the If-None-Match 6064 precondition: 6066 o if true, continue to step 5 6068 o if false for GET/HEAD, respond 304 (Not Modified) 6070 o if false for other methods, respond 412 (Precondition Failed) 6072 4. When the method is GET or HEAD, If-None-Match is not present, and 6073 If-Modified-Since is present, evaluate the If-Modified-Since 6074 precondition: 6076 o if true, continue to step 5 6077 o if false, respond 304 (Not Modified) 6079 5. When the method is GET and both Range and If-Range are present, 6080 evaluate the If-Range precondition: 6082 o if the validator matches and the Range specification is 6083 applicable to the selected representation, respond 206 6084 (Partial Content) 6086 6. Otherwise, 6088 o all conditions are met, so perform the requested action and 6089 respond according to its success or failure. 6091 Any extension to HTTP that defines additional conditional request 6092 header fields ought to define its own expectations regarding the 6093 order for evaluating such fields in relation to those defined in this 6094 document and other conditionals that might be found in practice. 6096 14. Range Requests 6098 Clients often encounter interrupted data transfers as a result of 6099 canceled requests or dropped connections. When a client has stored a 6100 partial representation, it is desirable to request the remainder of 6101 that representation in a subsequent request rather than transfer the 6102 entire representation. Likewise, devices with limited local storage 6103 might benefit from being able to request only a subset of a larger 6104 representation, such as a single page of a very large document, or 6105 the dimensions of an embedded image. 6107 Range requests are an OPTIONAL feature of HTTP, designed so that 6108 recipients not implementing this feature (or not supporting it for 6109 the target resource) can respond as if it is a normal GET request 6110 without impacting interoperability. Partial responses are indicated 6111 by a distinct status code to not be mistaken for full responses by 6112 caches that might not implement the feature. 6114 14.1. Range Units 6116 Representation data can be partitioned into subranges when there are 6117 addressable structural units inherent to that data's content coding 6118 or media type. For example, octet (a.k.a., byte) boundaries are a 6119 structural unit common to all representation data, allowing 6120 partitions of the data to be identified as a range of bytes at some 6121 offset from the start or end of that data. 6123 This general notion of a _range unit_ is used in the Accept-Ranges 6124 (Section 14.3) response header field to advertise support for range 6125 requests, the Range (Section 14.2) request header field to delineate 6126 the parts of a representation that are requested, and the 6127 Content-Range (Section 14.4) header field to describe which part of a 6128 representation is being transferred. 6130 range-unit = token 6132 All range unit names are case-insensitive and ought to be registered 6133 within the "HTTP Range Unit Registry", as defined in Section 16.5.1 6135 Range units are intended to be extensible, as described in 6136 Section 16.5. 6138 14.1.1. Range Specifiers 6140 Ranges are expressed in terms of a range unit paired with a set of 6141 range specifiers. The range unit name determines what kinds of 6142 range-spec are applicable to its own specifiers. Hence, the 6143 following gramar is generic: each range unit is expected to specify 6144 requirements on when int-range, suffix-range, and other-range are 6145 allowed. 6147 A range request can specify a single range or a set of ranges within 6148 a single representation. 6150 ranges-specifier = range-unit "=" range-set 6151 range-set = 1#range-spec 6152 range-spec = int-range 6153 / suffix-range 6154 / other-range 6156 An int-range is a range expressed as two non-negative integers or as 6157 one non-negative integer through to the end of the representation 6158 data. The range unit specifies what the integers mean (e.g., they 6159 might indicate unit offsets from the beginning, inclusive numbered 6160 parts, etc.). 6162 int-range = first-pos "-" [ last-pos ] 6163 first-pos = 1*DIGIT 6164 last-pos = 1*DIGIT 6166 An int-range is invalid if the last-pos value is present and less 6167 than the first-pos. 6169 A suffix-range is a range expressed as a suffix of the representation 6170 data with the provided non-negative integer maximum length (in range 6171 units). In other words, the last N units of the representation data. 6173 suffix-range = "-" suffix-length 6174 suffix-length = 1*DIGIT 6176 To provide for extensibility, the other-range rule is a mostly 6177 unconstrained grammar that allows application-specific or future 6178 range units to define additional range specifiers. 6180 other-range = 1*( %x21-2B / %x2D-7E ) 6181 ; 1*(VCHAR excluding comma) 6183 14.1.2. Byte Ranges 6185 The "bytes" range unit is used to express subranges of a 6186 representation data's octet sequence. Each byte range is expressed 6187 as an integer range at some offset, relative to either the beginning 6188 (int-range) or end (suffix-range) of the representation data. Byte 6189 ranges do not use the other-range specifier. 6191 The first-pos value in a bytes int-range gives the offset of the 6192 first byte in a range. The last-pos value gives the offset of the 6193 last byte in the range; that is, the byte positions specified are 6194 inclusive. Byte offsets start at zero. 6196 If the representation data has a content coding applied, each byte 6197 range is calculated with respect to the encoded sequence of bytes, 6198 not the sequence of underlying bytes that would be obtained after 6199 decoding. 6201 Examples of bytes range specifiers: 6203 o The first 500 bytes (byte offsets 0-499, inclusive): 6205 bytes=0-499 6207 o The second 500 bytes (byte offsets 500-999, inclusive): 6209 bytes=500-999 6211 A client can limit the number of bytes requested without knowing the 6212 size of the selected representation. If the last-pos value is 6213 absent, or if the value is greater than or equal to the current 6214 length of the representation data, the byte range is interpreted as 6215 the remainder of the representation (i.e., the server replaces the 6216 value of last-pos with a value that is one less than the current 6217 length of the selected representation). 6219 A client can request the last N bytes (N > 0) of the selected 6220 representation using a suffix-range. If the selected representation 6221 is shorter than the specified suffix-length, the entire 6222 representation is used. 6224 Additional examples, assuming a representation of length 10000: 6226 o The final 500 bytes (byte offsets 9500-9999, inclusive): 6228 bytes=-500 6230 Or: 6232 bytes=9500- 6234 o The first and last bytes only (bytes 0 and 9999): 6236 bytes=0-0,-1 6238 o The first, middle, and last 1000 bytes: 6240 bytes= 0-999, 4500-5499, -1000 6242 o Other valid (but not canonical) specifications of the second 500 6243 bytes (byte offsets 500-999, inclusive): 6245 bytes=500-600,601-999 6246 bytes=500-700,601-999 6248 If a valid bytes range-set includes at least one range-spec with a 6249 first-pos that is less than the current length of the representation, 6250 or at least one suffix-range with a non-zero suffix-length, then the 6251 bytes range-set is satisfiable. Otherwise, the bytes range-set is 6252 unsatisfiable. 6254 If the selected representation has zero length, the only satisfiable 6255 form of range-spec is a suffix-range with a non-zero suffix-length. 6257 In the byte-range syntax, first-pos, last-pos, and suffix-length are 6258 expressed as decimal number of octets. Since there is no predefined 6259 limit to the length of content, recipients MUST anticipate 6260 potentially large decimal numerals and prevent parsing errors due to 6261 integer conversion overflows. 6263 14.2. Range 6265 The "Range" header field on a GET request modifies the method 6266 semantics to request transfer of only one or more subranges of the 6267 selected representation data (Section 8.1), rather than the entire 6268 selected representation. 6270 Range = ranges-specifier 6272 A server MAY ignore the Range header field. However, origin servers 6273 and intermediate caches ought to support byte ranges when possible, 6274 since they support efficient recovery from partially failed transfers 6275 and partial retrieval of large representations. 6277 A server MUST ignore a Range header field received with a request 6278 method which is unrecognized or for which range handling is not 6279 defined. For this specification, GET is the only method for which 6280 range handling is defined. 6282 An origin server MUST ignore a Range header field that contains a 6283 range unit it does not understand. A proxy MAY discard a Range 6284 header field that contains a range unit it does not understand. 6286 A server that supports range requests MAY ignore or reject a Range 6287 header field that consists of more than two overlapping ranges, or a 6288 set of many small ranges that are not listed in ascending order, 6289 since both are indications of either a broken client or a deliberate 6290 denial-of-service attack (Section 17.14). A client SHOULD NOT 6291 request multiple ranges that are inherently less efficient to process 6292 and transfer than a single range that encompasses the same data. 6294 A server that supports range requests MAY ignore a Range header field 6295 when the selected representation has no content (i.e., the selected 6296 representation's data is of zero length). 6298 A client that is requesting multiple ranges SHOULD list those ranges 6299 in ascending order (the order in which they would typically be 6300 received in a complete representation) unless there is a specific 6301 need to request a later part earlier. For example, a user agent 6302 processing a large representation with an internal catalog of parts 6303 might need to request later parts first, particularly if the 6304 representation consists of pages stored in reverse order and the user 6305 agent wishes to transfer one page at a time. 6307 The Range header field is evaluated after evaluating the precondition 6308 header fields defined in Section 13.1, and only if the result in 6309 absence of the Range header field would be a 200 (OK) response. In 6310 other words, Range is ignored when a conditional GET would result in 6311 a 304 (Not Modified) response. 6313 The If-Range header field (Section 13.1.5) can be used as a 6314 precondition to applying the Range header field. 6316 If all of the preconditions are true, the server supports the Range 6317 header field for the target resource, and the specified range(s) are 6318 valid and satisfiable (as defined in Section 14.1.2), the server 6319 SHOULD send a 206 (Partial Content) response with a content 6320 containing one or more partial representations that correspond to the 6321 satisfiable ranges requested. 6323 The above does not imply that a server will send all requested 6324 ranges. In some cases, it may only be possible (or efficient) to 6325 send a portion of the requested ranges first, while expecting the 6326 client to re-request the remaining portions later if they are still 6327 desired (see Section 15.3.7). 6329 If all of the preconditions are true, the server supports the Range 6330 header field for the target resource, and the specified range(s) are 6331 invalid or unsatisfiable, the server SHOULD send a 416 (Range Not 6332 Satisfiable) response. 6334 14.3. Accept-Ranges 6336 The "Accept-Ranges" header field allows a server to indicate that it 6337 supports range requests for the target resource. 6339 Accept-Ranges = acceptable-ranges 6340 acceptable-ranges = 1#range-unit / "none" 6342 An origin server that supports byte-range requests for a given target 6343 resource MAY send 6345 Accept-Ranges: bytes 6347 to indicate what range units are supported. A client MAY generate 6348 range requests without having received this header field for the 6349 resource involved. Range units are defined in Section 14.1. 6351 A server that does not support any kind of range request for the 6352 target resource MAY send 6354 Accept-Ranges: none 6356 to advise the client not to attempt a range request. 6358 14.4. Content-Range 6360 The "Content-Range" header field is sent in a single part 206 6361 (Partial Content) response to indicate the partial range of the 6362 selected representation enclosed as the message content, sent in each 6363 part of a multipart 206 response to indicate the range enclosed 6364 within each body part, and sent in 416 (Range Not Satisfiable) 6365 responses to provide information about the selected representation. 6367 Content-Range = range-unit SP 6368 ( range-resp / unsatisfied-range ) 6370 range-resp = incl-range "/" ( complete-length / "*" ) 6371 incl-range = first-pos "-" last-pos 6372 unsatisfied-range = "*/" complete-length 6374 complete-length = 1*DIGIT 6376 If a 206 (Partial Content) response contains a Content-Range header 6377 field with a range unit (Section 14.1) that the recipient does not 6378 understand, the recipient MUST NOT attempt to recombine it with a 6379 stored representation. A proxy that receives such a message SHOULD 6380 forward it downstream. 6382 Content-Range might also be sent as a request modifier to request a 6383 partial PUT, as described in Section 14.5, based on private 6384 agreements between client and origin server. A server MUST ignore a 6385 Content-Range header field received in a request with a method for 6386 which Content-Range support is not defined. 6388 For byte ranges, a sender SHOULD indicate the complete length of the 6389 representation from which the range has been extracted, unless the 6390 complete length is unknown or difficult to determine. An asterisk 6391 character ("*") in place of the complete-length indicates that the 6392 representation length was unknown when the header field was 6393 generated. 6395 The following example illustrates when the complete length of the 6396 selected representation is known by the sender to be 1234 bytes: 6398 Content-Range: bytes 42-1233/1234 6400 and this second example illustrates when the complete length is 6401 unknown: 6403 Content-Range: bytes 42-1233/* 6405 A Content-Range field value is invalid if it contains a range-resp 6406 that has a last-pos value less than its first-pos value, or a 6407 complete-length value less than or equal to its last-pos value. The 6408 recipient of an invalid Content-Range MUST NOT attempt to recombine 6409 the received content with a stored representation. 6411 A server generating a 416 (Range Not Satisfiable) response to a byte- 6412 range request SHOULD send a Content-Range header field with an 6413 unsatisfied-range value, as in the following example: 6415 Content-Range: bytes */1234 6417 The complete-length in a 416 response indicates the current length of 6418 the selected representation. 6420 The Content-Range header field has no meaning for status codes that 6421 do not explicitly describe its semantic. For this specification, 6422 only the 206 (Partial Content) and 416 (Range Not Satisfiable) status 6423 codes describe a meaning for Content-Range. 6425 The following are examples of Content-Range values in which the 6426 selected representation contains a total of 1234 bytes: 6428 o The first 500 bytes: 6430 Content-Range: bytes 0-499/1234 6432 o The second 500 bytes: 6434 Content-Range: bytes 500-999/1234 6436 o All except for the first 500 bytes: 6438 Content-Range: bytes 500-1233/1234 6440 o The last 500 bytes: 6442 Content-Range: bytes 734-1233/1234 6444 14.5. Partial PUT 6446 Some origin servers support PUT of a partial representation when a 6447 Content-Range header field (Section 14.4) is sent in the request, 6448 though such support is inconsistent and depends on private agreements 6449 with user agents. In general, it requests that the state of the 6450 target resource be partly replaced with the enclosed content at an 6451 offset and length indicated by the Content-Range value, where the 6452 offset is relative to the current selected representation. 6454 An origin server SHOULD respond with a 400 (Bad Request) status code 6455 if it receives Content-Range on a PUT for a target resource that does 6456 not support partial PUT requests. 6458 Partial PUT is not backwards compatible with the original definition 6459 of PUT. It may result in the content being written as a complete 6460 replacement for the current representation. 6462 Partial resource updates are also possible by targeting a separately 6463 identified resource with state that overlaps or extends a portion of 6464 the larger resource, or by using a different method that has been 6465 specifically defined for partial updates (for example, the PATCH 6466 method defined in [RFC5789]). 6468 14.6. Media Type multipart/byteranges 6470 When a 206 (Partial Content) response message includes the content of 6471 multiple ranges, they are transmitted as body parts in a multipart 6472 message body ([RFC2046], Section 5.1) with the media type of 6473 "multipart/byteranges". 6475 The multipart/byteranges media type includes one or more body parts, 6476 each with its own Content-Type and Content-Range fields. The 6477 required boundary parameter specifies the boundary string used to 6478 separate each body part. 6480 Implementation Notes: 6482 1. Additional CRLFs might precede the first boundary string in the 6483 body. 6485 2. Although [RFC2046] permits the boundary string to be quoted, some 6486 existing implementations handle a quoted boundary string 6487 incorrectly. 6489 3. A number of clients and servers were coded to an early draft of 6490 the byteranges specification that used a media type of multipart/ 6491 x-byteranges , which is almost (but not quite) compatible with 6492 this type. 6494 Despite the name, the "multipart/byteranges" media type is not 6495 limited to byte ranges. The following example uses an "exampleunit" 6496 range unit: 6498 HTTP/1.1 206 Partial Content 6499 Date: Tue, 14 Nov 1995 06:25:24 GMT 6500 Last-Modified: Tue, 14 July 04:58:08 GMT 6501 Content-Length: 2331785 6502 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 6504 --THIS_STRING_SEPARATES 6505 Content-Type: video/example 6506 Content-Range: exampleunit 1.2-4.3/25 6508 ...the first range... 6509 --THIS_STRING_SEPARATES 6510 Content-Type: video/example 6511 Content-Range: exampleunit 11.2-14.3/25 6513 ...the second range 6514 --THIS_STRING_SEPARATES-- 6516 The following information serves as the registration form for the 6517 multipart/byteranges media type. 6519 Type name: multipart 6521 Subtype name: byteranges 6523 Required parameters: boundary 6525 Optional parameters: N/A 6527 Encoding considerations: only "7bit", "8bit", or "binary" are 6528 permitted 6530 Security considerations: see Section 17 6532 Interoperability considerations: N/A 6534 Published specification: This specification (see Section 14.6). 6536 Applications that use this media type: HTTP components supporting 6537 multiple ranges in a single request. 6539 Fragment identifier considerations: N/A 6541 Additional information: Deprecated alias names for this type: N/A 6543 Magic number(s): N/A 6545 File extension(s): N/A 6547 Macintosh file type code(s): N/A 6549 Person and email address to contact for further information: See Aut 6550 hors' Addresses section. 6552 Intended usage: COMMON 6554 Restrictions on usage: N/A 6556 Author: See Authors' Addresses section. 6558 Change controller: IESG 6560 15. Status Codes 6562 The (response) status code is a three-digit integer code giving the 6563 result of the attempt to understand and satisfy the request. 6565 HTTP status codes are extensible. HTTP clients are not required to 6566 understand the meaning of all registered status codes, though such 6567 understanding is obviously desirable. However, a client MUST 6568 understand the class of any status code, as indicated by the first 6569 digit, and treat an unrecognized status code as being equivalent to 6570 the x00 status code of that class. 6572 For example, if an unrecognized status code of 471 is received by a 6573 client, the client can assume that there was something wrong with its 6574 request and treat the response as if it had received a 400 (Bad 6575 Request) status code. The response message will usually contain a 6576 representation that explains the status. 6578 The first digit of the status code defines the class of response. 6579 The last two digits do not have any categorization role. There are 6580 five values for the first digit: 6582 o 1xx (Informational): The request was received, continuing process 6583 o 2xx (Successful): The request was successfully received, 6584 understood, and accepted 6586 o 3xx (Redirection): Further action needs to be taken in order to 6587 complete the request 6589 o 4xx (Client Error): The request contains bad syntax or cannot be 6590 fulfilled 6592 o 5xx (Server Error): The server failed to fulfill an apparently 6593 valid request 6595 A single request can have multiple associated responses: zero or more 6596 _interim_ (non-final) responses with status codes in the 6597 "informational" (1xx) range, followed by exactly one _final_ response 6598 with a status code in one of the other ranges. 6600 15.1. Overview of Status Codes 6602 The status codes listed below are defined in this specification. The 6603 reason phrases listed here are only recommendations - they can be 6604 replaced by local equivalents or left out altogether without 6605 affecting the protocol. 6607 Responses with status codes that are defined as heuristically 6608 cacheable (e.g., 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 6609 414, and 501 in this specification) can be reused by a cache with 6610 heuristic expiration unless otherwise indicated by the method 6611 definition or explicit cache controls [Caching]; all other status 6612 codes are not heuristically cacheable. 6614 Additional status codes, outside the scope of this specification, 6615 have been specified for use in HTTP. All such status codes ought to 6616 be registered within the "Hypertext Transfer Protocol (HTTP) Status 6617 Code Registry", as described in Section 16.2. 6619 15.2. Informational 1xx 6621 The _1xx (Informational)_ class of status code indicates an interim 6622 response for communicating connection status or request progress 6623 prior to completing the requested action and sending a final 6624 response. Since HTTP/1.0 did not define any 1xx status codes, a 6625 server MUST NOT send a 1xx response to an HTTP/1.0 client. 6627 A 1xx response is terminated by the end of the header section; it 6628 cannot contain content or trailers. 6630 A client MUST be able to parse one or more 1xx responses received 6631 prior to a final response, even if the client does not expect one. A 6632 user agent MAY ignore unexpected 1xx responses. 6634 A proxy MUST forward 1xx responses unless the proxy itself requested 6635 the generation of the 1xx response. For example, if a proxy adds an 6636 "Expect: 100-continue" header field when it forwards a request, then 6637 it need not forward the corresponding 100 (Continue) response(s). 6639 15.2.1. 100 Continue 6641 The _100 (Continue)_ status code indicates that the initial part of a 6642 request has been received and has not yet been rejected by the 6643 server. The server intends to send a final response after the 6644 request has been fully received and acted upon. 6646 When the request contains an Expect header field that includes a 6647 100-continue expectation, the 100 response indicates that the server 6648 wishes to receive the request content, as described in 6649 Section 10.1.1. The client ought to continue sending the request and 6650 discard the 100 response. 6652 If the request did not contain an Expect header field containing the 6653 100-continue expectation, the client can simply discard this interim 6654 response. 6656 15.2.2. 101 Switching Protocols 6658 The _101 (Switching Protocols)_ status code indicates that the server 6659 understands and is willing to comply with the client's request, via 6660 the Upgrade header field (Section 7.8), for a change in the 6661 application protocol being used on this connection. The server MUST 6662 generate an Upgrade header field in the response that indicates which 6663 protocol(s) will be switched to immediately after the empty line that 6664 terminates the 101 response. 6666 It is assumed that the server will only agree to switch protocols 6667 when it is advantageous to do so. For example, switching to a newer 6668 version of HTTP might be advantageous over older versions, and 6669 switching to a real-time, synchronous protocol might be advantageous 6670 when delivering resources that use such features. 6672 15.3. Successful 2xx 6674 The _2xx (Successful)_ class of status code indicates that the 6675 client's request was successfully received, understood, and accepted. 6677 15.3.1. 200 OK 6679 The _200 (OK)_ status code indicates that the request has succeeded. 6680 The content sent in a 200 response depends on the request method. 6681 For the methods defined by this specification, the intended meaning 6682 of the content can be summarized as: 6684 ---------------- -------------------------------------------- 6685 request method response content is a representation of 6686 ---------------- -------------------------------------------- 6687 GET the target resource 6688 HEAD the target resource, like GET, but without 6689 transferring the representation data 6690 POST the status of, or results obtained from, 6691 the action 6692 PUT, DELETE the status of the action 6693 OPTIONS communication options for the target 6694 resource 6695 TRACE the request message as received by the 6696 server returning the trace 6697 ---------------- -------------------------------------------- 6699 Table 6 6701 Aside from responses to CONNECT, a 200 response always has content, 6702 though an origin server MAY generate content of zero length. If no 6703 content is desired, an origin server ought to send _204 (No Content)_ 6704 instead. For CONNECT, no content is allowed because the successful 6705 result is a tunnel, which begins immediately after the 200 response 6706 header section. 6708 A 200 response is heuristically cacheable; i.e., unless otherwise 6709 indicated by the method definition or explicit cache controls (see 6710 Section 4.2.2 of [Caching]). 6712 15.3.2. 201 Created 6714 The _201 (Created)_ status code indicates that the request has been 6715 fulfilled and has resulted in one or more new resources being 6716 created. The primary resource created by the request is identified 6717 by either a Location header field in the response or, if no Location 6718 header field is received, by the target URI. 6720 The 201 response content typically describes and links to the 6721 resource(s) created. See Section 8.8 for a discussion of the meaning 6722 and purpose of validator fields, such as ETag and Last-Modified, in a 6723 201 response. 6725 15.3.3. 202 Accepted 6727 The _202 (Accepted)_ status code indicates that the request has been 6728 accepted for processing, but the processing has not been completed. 6729 The request might or might not eventually be acted upon, as it might 6730 be disallowed when processing actually takes place. There is no 6731 facility in HTTP for re-sending a status code from an asynchronous 6732 operation. 6734 The 202 response is intentionally noncommittal. Its purpose is to 6735 allow a server to accept a request for some other process (perhaps a 6736 batch-oriented process that is only run once per day) without 6737 requiring that the user agent's connection to the server persist 6738 until the process is completed. The representation sent with this 6739 response ought to describe the request's current status and point to 6740 (or embed) a status monitor that can provide the user with an 6741 estimate of when the request will be fulfilled. 6743 15.3.4. 203 Non-Authoritative Information 6745 The _203 (Non-Authoritative Information)_ status code indicates that 6746 the request was successful but the enclosed content has been modified 6747 from that of the origin server's 200 (OK) response by a transforming 6748 proxy (Section 7.7). This status code allows the proxy to notify 6749 recipients when a transformation has been applied, since that 6750 knowledge might impact later decisions regarding the content. For 6751 example, future cache validation requests for the content might only 6752 be applicable along the same request path (through the same proxies). 6754 A 203 response is heuristically cacheable; i.e., unless otherwise 6755 indicated by the method definition or explicit cache controls (see 6756 Section 4.2.2 of [Caching]). 6758 15.3.5. 204 No Content 6760 The _204 (No Content)_ status code indicates that the server has 6761 successfully fulfilled the request and that there is no additional 6762 content to send in the response content. Metadata in the response 6763 header fields refer to the target resource and its selected 6764 representation after the requested action was applied. 6766 For example, if a 204 status code is received in response to a PUT 6767 request and the response contains an ETag field, then the PUT was 6768 successful and the ETag field value contains the entity-tag for the 6769 new representation of that target resource. 6771 The 204 response allows a server to indicate that the action has been 6772 successfully applied to the target resource, while implying that the 6773 user agent does not need to traverse away from its current "document 6774 view" (if any). The server assumes that the user agent will provide 6775 some indication of the success to its user, in accord with its own 6776 interface, and apply any new or updated metadata in the response to 6777 its active representation. 6779 For example, a 204 status code is commonly used with document editing 6780 interfaces corresponding to a "save" action, such that the document 6781 being saved remains available to the user for editing. It is also 6782 frequently used with interfaces that expect automated data transfers 6783 to be prevalent, such as within distributed version control systems. 6785 A 204 response is terminated by the end of the header section; it 6786 cannot contain content or trailers. 6788 A 204 response is heuristically cacheable; i.e., unless otherwise 6789 indicated by the method definition or explicit cache controls (see 6790 Section 4.2.2 of [Caching]). 6792 15.3.6. 205 Reset Content 6794 The _205 (Reset Content)_ status code indicates that the server has 6795 fulfilled the request and desires that the user agent reset the 6796 "document view", which caused the request to be sent, to its original 6797 state as received from the origin server. 6799 This response is intended to support a common data entry use case 6800 where the user receives content that supports data entry (a form, 6801 notepad, canvas, etc.), enters or manipulates data in that space, 6802 causes the entered data to be submitted in a request, and then the 6803 data entry mechanism is reset for the next entry so that the user can 6804 easily initiate another input action. 6806 Since the 205 status code implies that no additional content will be 6807 provided, a server MUST NOT generate content in a 205 response. 6809 15.3.7. 206 Partial Content 6811 The _206 (Partial Content)_ status code indicates that the server is 6812 successfully fulfilling a range request for the target resource by 6813 transferring one or more parts of the selected representation. 6815 A server that supports range requests (Section 14) will usually 6816 attempt to satisfy all of the requested ranges, since sending less 6817 data will likely result in another client request for the remainder. 6818 However, a server might want to send only a subset of the data 6819 requested for reasons of its own, such as temporary unavailability, 6820 cache efficiency, load balancing, etc. Since a 206 response is self- 6821 descriptive, the client can still understand a response that only 6822 partially satisfies its range request. 6824 A client MUST inspect a 206 response's Content-Type and Content-Range 6825 field(s) to determine what parts are enclosed and whether additional 6826 requests are needed. 6828 When a 206 response is generated, the server MUST generate the 6829 following header fields, in addition to those required in the 6830 subsections below, if the field would have been sent in a 200 (OK) 6831 response to the same request: Date, Cache-Control, ETag, Expires, 6832 Content-Location, and Vary. 6834 A Content-Length header field present in a 206 response indicates the 6835 number of octets in the content of this message, which is usually not 6836 the complete length of the selected representation. Each 6837 Content-Range header field includes information about the selected 6838 representation's complete length. 6840 If a 206 is generated in response to a request with an If-Range 6841 header field, the sender SHOULD NOT generate other representation 6842 header fields beyond those required, because the client is understood 6843 to already have a prior response containing those header fields. 6844 Otherwise, the sender MUST generate all of the representation header 6845 fields that would have been sent in a 200 (OK) response to the same 6846 request. 6848 A 206 response is heuristically cacheable; i.e., unless otherwise 6849 indicated by explicit cache controls (see Section 4.2.2 of 6850 [Caching]). 6852 15.3.7.1. Single Part 6854 If a single part is being transferred, the server generating the 206 6855 response MUST generate a Content-Range header field, describing what 6856 range of the selected representation is enclosed, and a content 6857 consisting of the range. For example: 6859 HTTP/1.1 206 Partial Content 6860 Date: Wed, 15 Nov 1995 06:25:24 GMT 6861 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 6862 Content-Range: bytes 21010-47021/47022 6863 Content-Length: 26012 6864 Content-Type: image/gif 6866 ... 26012 bytes of partial image data ... 6868 15.3.7.2. Multiple Parts 6870 If multiple parts are being transferred, the server generating the 6871 206 response MUST generate "multipart/byteranges" content, as defined 6872 in Section 14.6, and a Content-Type header field containing the 6873 multipart/byteranges media type and its required boundary parameter. 6874 To avoid confusion with single-part responses, a server MUST NOT 6875 generate a Content-Range header field in the HTTP header section of a 6876 multiple part response (this field will be sent in each part 6877 instead). 6879 Within the header area of each body part in the multipart content, 6880 the server MUST generate a Content-Range header field corresponding 6881 to the range being enclosed in that body part. If the selected 6882 representation would have had a Content-Type header field in a 200 6883 (OK) response, the server SHOULD generate that same Content-Type 6884 header field in the header area of each body part. For example: 6886 HTTP/1.1 206 Partial Content 6887 Date: Wed, 15 Nov 1995 06:25:24 GMT 6888 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 6889 Content-Length: 1741 6890 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 6892 --THIS_STRING_SEPARATES 6893 Content-Type: application/pdf 6894 Content-Range: bytes 500-999/8000 6896 ...the first range... 6897 --THIS_STRING_SEPARATES 6898 Content-Type: application/pdf 6899 Content-Range: bytes 7000-7999/8000 6901 ...the second range 6902 --THIS_STRING_SEPARATES-- 6904 When multiple ranges are requested, a server MAY coalesce any of the 6905 ranges that overlap, or that are separated by a gap that is smaller 6906 than the overhead of sending multiple parts, regardless of the order 6907 in which the corresponding range-spec appeared in the received Range 6908 header field. Since the typical overhead between each part of a 6909 multipart/byteranges is around 80 bytes, depending on the selected 6910 representation's media type and the chosen boundary parameter length, 6911 it can be less efficient to transfer many small disjoint parts than 6912 it is to transfer the entire selected representation. 6914 A server MUST NOT generate a multipart response to a request for a 6915 single range, since a client that does not request multiple parts 6916 might not support multipart responses. However, a server MAY 6917 generate a multipart/byteranges response with only a single body part 6918 if multiple ranges were requested and only one range was found to be 6919 satisfiable or only one range remained after coalescing. A client 6920 that cannot process a multipart/byteranges response MUST NOT generate 6921 a request that asks for multiple ranges. 6923 When a multipart response is generated, the server SHOULD send the 6924 parts in the same order that the corresponding range-spec appeared in 6925 the received Range header field, excluding those ranges that were 6926 deemed unsatisfiable or that were coalesced into other ranges. A 6927 client that receives a multipart response MUST inspect the 6928 Content-Range header field present in each body part in order to 6929 determine which range is contained in that body part; a client cannot 6930 rely on receiving the same ranges that it requested, nor the same 6931 order that it requested. 6933 15.3.7.3. Combining Parts 6935 A response might transfer only a subrange of a representation if the 6936 connection closed prematurely or if the request used one or more 6937 Range specifications. After several such transfers, a client might 6938 have received several ranges of the same representation. These 6939 ranges can only be safely combined if they all have in common the 6940 same strong validator (Section 8.8.1). 6942 A client that has received multiple partial responses to GET requests 6943 on a target resource MAY combine those responses into a larger 6944 continuous range if they share the same strong validator. 6946 If the most recent response is an incomplete 200 (OK) response, then 6947 the header fields of that response are used for any combined response 6948 and replace those of the matching stored responses. 6950 If the most recent response is a 206 (Partial Content) response and 6951 at least one of the matching stored responses is a 200 (OK), then the 6952 combined response header fields consist of the most recent 200 6953 response's header fields. If all of the matching stored responses 6954 are 206 responses, then the stored response with the most recent 6955 header fields is used as the source of header fields for the combined 6956 response, except that the client MUST use other header fields 6957 provided in the new response, aside from Content-Range, to replace 6958 all instances of the corresponding header fields in the stored 6959 response. 6961 The combined response content consists of the union of partial 6962 content ranges in the new response and each of the selected 6963 responses. If the union consists of the entire range of the 6964 representation, then the client MUST process the combined response as 6965 if it were a complete 200 (OK) response, including a Content-Length 6966 header field that reflects the complete length. Otherwise, the 6967 client MUST process the set of continuous ranges as one of the 6968 following: an incomplete 200 (OK) response if the combined response 6969 is a prefix of the representation, a single 206 (Partial Content) 6970 response containing multipart/byteranges content, or multiple 206 6971 (Partial Content) responses, each with one continuous range that is 6972 indicated by a Content-Range header field. 6974 15.4. Redirection 3xx 6976 The _3xx (Redirection)_ class of status code indicates that further 6977 action needs to be taken by the user agent in order to fulfill the 6978 request. There are several types of redirects: 6980 1. Redirects that indicate this resource might be available at a 6981 different URI, as provided by the Location header field, as in 6982 the status codes 301 (Moved Permanently), 302 (Found), 307 6983 (Temporary Redirect), and 308 (Permanent Redirect). 6985 2. Redirection that offers a choice among matching resources capable 6986 of representing this resource, as in the 300 (Multiple Choices) 6987 status code. 6989 3. Redirection to a different resource, identified by the Location 6990 header field, that can represent an indirect response to the 6991 request, as in the 303 (See Other) status code. 6993 4. Redirection to a previously stored result, as in the 304 (Not 6994 Modified) status code. 6996 If a Location header field (Section 10.2.3) is provided, the user 6997 agent MAY automatically redirect its request to the URI referenced by 6998 the Location field value, even if the specific status code is not 6999 understood. Automatic redirection needs to be done with care for 7000 methods not known to be safe, as defined in Section 9.2.1, since the 7001 user might not wish to redirect an unsafe request. 7003 When automatically following a redirected request, the user agent 7004 SHOULD resend the original request message with the following 7005 modifications: 7007 1. Replace the target URI with the URI referenced by the redirection 7008 response's Location header field value after resolving it 7009 relative to the original request's target URI. 7011 2. Remove header fields that were automatically generated by the 7012 implementation, replacing them with updated values as appropriate 7013 to the new request. This includes: 7015 1. Connection-specific header fields (see Section 7.6.1), 7017 2. Header fields specific to the client's proxy configuration, 7018 including (but not limited to) Proxy-Authorization, 7020 3. Origin-specific header fields (if any), including (but not 7021 limited to) Host, 7023 4. Validating header fields that were added by the 7024 implementation's cache (e.g., If-None-Match, 7025 If-Modified-Since), 7027 5. Resource-specific header fields, including (but not limited 7028 to) Referer, Origin, Authorization, and Cookie. 7030 3. Consider removing header fields that were not automatically 7031 generated by the implementation (i.e., those present in the 7032 request because they were added by the calling context) where 7033 there are security implications; this includes but is not limited 7034 to Authorization and Cookie. 7036 4. Change the request method according to the redirecting status 7037 code's semantics, if applicable. 7039 5. If the request method has been changed to GET or HEAD, remove 7040 content-specific header fields, including (but not limited to) 7041 Content-Encoding, Content-Language, Content-Location, 7042 Content-Type, Content-Length, Digest, ETag, Last-Modified. 7044 | *Note:* In HTTP/1.0, the status codes 301 (Moved Permanently) 7045 | and 302 (Found) were defined for the first type of redirect 7046 | ([RFC1945], Section 9.3). Early user agents split on whether 7047 | the method applied to the redirect target would be the same as 7048 | the original request or would be rewritten as GET. Although 7049 | HTTP originally defined the former semantics for 301 and 302 7050 | (to match its original implementation at CERN), and defined 303 7051 | (See Other) to match the latter semantics, prevailing practice 7052 | gradually converged on the latter semantics for 301 and 302 as 7053 | well. The first revision of HTTP/1.1 added 307 (Temporary 7054 | Redirect) to indicate the former semantics of 302 without being 7055 | impacted by divergent practice. For the same reason, 308 7056 | (Permanent Redirect) was later on added in [RFC7538] to match 7057 | 301. Over 10 years later, most user agents still do method 7058 | rewriting for 301 and 302; therefore, [RFC7231] made that 7059 | behavior conformant when the original request is POST. 7061 A client SHOULD detect and intervene in cyclical redirections (i.e., 7062 "infinite" redirection loops). 7064 | *Note:* An earlier version of this specification recommended a 7065 | maximum of five redirections ([RFC2068], Section 10.3). 7066 | Content developers need to be aware that some clients might 7067 | implement such a fixed limitation. 7069 15.4.1. 300 Multiple Choices 7071 The _300 (Multiple Choices)_ status code indicates that the target 7072 resource has more than one representation, each with its own more 7073 specific identifier, and information about the alternatives is being 7074 provided so that the user (or user agent) can select a preferred 7075 representation by redirecting its request to one or more of those 7076 identifiers. In other words, the server desires that the user agent 7077 engage in reactive negotiation to select the most appropriate 7078 representation(s) for its needs (Section 12). 7080 If the server has a preferred choice, the server SHOULD generate a 7081 Location header field containing a preferred choice's URI reference. 7082 The user agent MAY use the Location field value for automatic 7083 redirection. 7085 For request methods other than HEAD, the server SHOULD generate 7086 content in the 300 response containing a list of representation 7087 metadata and URI reference(s) from which the user or user agent can 7088 choose the one most preferred. The user agent MAY make a selection 7089 from that list automatically if it understands the provided media 7090 type. A specific format for automatic selection is not defined by 7091 this specification because HTTP tries to remain orthogonal to the 7092 definition of its content. In practice, the representation is 7093 provided in some easily parsed format believed to be acceptable to 7094 the user agent, as determined by shared design or content 7095 negotiation, or in some commonly accepted hypertext format. 7097 A 300 response is heuristically cacheable; i.e., unless otherwise 7098 indicated by the method definition or explicit cache controls (see 7099 Section 4.2.2 of [Caching]). 7101 | *Note:* The original proposal for the 300 status code defined 7102 | the URI header field as providing a list of alternative 7103 | representations, such that it would be usable for 200, 300, and 7104 | 406 responses and be transferred in responses to the HEAD 7105 | method. However, lack of deployment and disagreement over 7106 | syntax led to both URI and Alternates (a subsequent proposal) 7107 | being dropped from this specification. It is possible to 7108 | communicate the list as a Link header field value [RFC8288] 7109 | whose members have a relationship of "alternate", though 7110 | deployment is a chicken-and-egg problem. 7112 15.4.2. 301 Moved Permanently 7114 The _301 (Moved Permanently)_ status code indicates that the target 7115 resource has been assigned a new permanent URI and any future 7116 references to this resource ought to use one of the enclosed URIs. 7117 Clients with link-editing capabilities ought to automatically re-link 7118 references to the target URI to one or more of the new references 7119 sent by the server, where possible. 7121 The server SHOULD generate a Location header field in the response 7122 containing a preferred URI reference for the new permanent URI. The 7123 user agent MAY use the Location field value for automatic 7124 redirection. The server's response content usually contains a short 7125 hypertext note with a hyperlink to the new URI(s). 7127 | *Note:* For historical reasons, a user agent MAY change the 7128 | request method from POST to GET for the subsequent request. If 7129 | this behavior is undesired, the 308 (Permanent Redirect) status 7130 | code can be used instead. 7132 A 301 response is heuristically cacheable; i.e., unless otherwise 7133 indicated by the method definition or explicit cache controls (see 7134 Section 4.2.2 of [Caching]). 7136 15.4.3. 302 Found 7138 The _302 (Found)_ status code indicates that the target resource 7139 resides temporarily under a different URI. Since the redirection 7140 might be altered on occasion, the client ought to continue to use the 7141 target URI for future requests. 7143 The server SHOULD generate a Location header field in the response 7144 containing a URI reference for the different URI. The user agent MAY 7145 use the Location field value for automatic redirection. The server's 7146 response content usually contains a short hypertext note with a 7147 hyperlink to the different URI(s). 7149 | *Note:* For historical reasons, a user agent MAY change the 7150 | request method from POST to GET for the subsequent request. If 7151 | this behavior is undesired, the 307 (Temporary Redirect) status 7152 | code can be used instead. 7154 15.4.4. 303 See Other 7156 The _303 (See Other)_ status code indicates that the server is 7157 redirecting the user agent to a different resource, as indicated by a 7158 URI in the Location header field, which is intended to provide an 7159 indirect response to the original request. A user agent can perform 7160 a retrieval request targeting that URI (a GET or HEAD request if 7161 using HTTP), which might also be redirected, and present the eventual 7162 result as an answer to the original request. Note that the new URI 7163 in the Location header field is not considered equivalent to the 7164 target URI. 7166 This status code is applicable to any HTTP method. It is primarily 7167 used to allow the output of a POST action to redirect the user agent 7168 to a selected resource, since doing so provides the information 7169 corresponding to the POST response in a form that can be separately 7170 identified, bookmarked, and cached, independent of the original 7171 request. 7173 A 303 response to a GET request indicates that the origin server does 7174 not have a representation of the target resource that can be 7175 transferred by the server over HTTP. However, the Location field 7176 value refers to a resource that is descriptive of the target 7177 resource, such that making a retrieval request on that other resource 7178 might result in a representation that is useful to recipients without 7179 implying that it represents the original target resource. Note that 7180 answers to the questions of what can be represented, what 7181 representations are adequate, and what might be a useful description 7182 are outside the scope of HTTP. 7184 Except for responses to a HEAD request, the representation of a 303 7185 response ought to contain a short hypertext note with a hyperlink to 7186 the same URI reference provided in the Location header field. 7188 15.4.5. 304 Not Modified 7190 The _304 (Not Modified)_ status code indicates that a conditional GET 7191 or HEAD request has been received and would have resulted in a 200 7192 (OK) response if it were not for the fact that the condition 7193 evaluated to false. In other words, there is no need for the server 7194 to transfer a representation of the target resource because the 7195 request indicates that the client, which made the request 7196 conditional, already has a valid representation; the server is 7197 therefore redirecting the client to make use of that stored 7198 representation as if it were the content of a 200 (OK) response. 7200 The server generating a 304 response MUST generate any of the 7201 following header fields that would have been sent in a 200 (OK) 7202 response to the same request: Cache-Control, Content-Location, Date, 7203 ETag, Expires, and Vary. 7205 Since the goal of a 304 response is to minimize information transfer 7206 when the recipient already has one or more cached representations, a 7207 sender SHOULD NOT generate representation metadata other than the 7208 above listed fields unless said metadata exists for the purpose of 7209 guiding cache updates (e.g., Last-Modified might be useful if the 7210 response does not have an ETag field). 7212 Requirements on a cache that receives a 304 response are defined in 7213 Section 4.3.4 of [Caching]. If the conditional request originated 7214 with an outbound client, such as a user agent with its own cache 7215 sending a conditional GET to a shared proxy, then the proxy SHOULD 7216 forward the 304 response to that client. 7218 A 304 response is terminated by the end of the header section; it 7219 cannot contain content or trailers. 7221 15.4.6. 305 Use Proxy 7223 The _305 (Use Proxy)_ status code was defined in a previous version 7224 of this specification and is now deprecated (Appendix B of 7225 [RFC7231]). 7227 15.4.7. 306 (Unused) 7229 The 306 status code was defined in a previous version of this 7230 specification, is no longer used, and the code is reserved. 7232 15.4.8. 307 Temporary Redirect 7234 The _307 (Temporary Redirect)_ status code indicates that the target 7235 resource resides temporarily under a different URI and the user agent 7236 MUST NOT change the request method if it performs an automatic 7237 redirection to that URI. Since the redirection can change over time, 7238 the client ought to continue using the original target URI for future 7239 requests. 7241 The server SHOULD generate a Location header field in the response 7242 containing a URI reference for the different URI. The user agent MAY 7243 use the Location field value for automatic redirection. The server's 7244 response content usually contains a short hypertext note with a 7245 hyperlink to the different URI(s). 7247 15.4.9. 308 Permanent Redirect 7249 The _308 (Permanent Redirect)_ status code indicates that the target 7250 resource has been assigned a new permanent URI and any future 7251 references to this resource ought to use one of the enclosed URIs. 7252 Clients with link editing capabilities ought to automatically re-link 7253 references to the target URI to one or more of the new references 7254 sent by the server, where possible. 7256 The server SHOULD generate a Location header field in the response 7257 containing a preferred URI reference for the new permanent URI. The 7258 user agent MAY use the Location field value for automatic 7259 redirection. The server's response content usually contains a short 7260 hypertext note with a hyperlink to the new URI(s). 7262 A 308 response is heuristically cacheable; i.e., unless otherwise 7263 indicated by the method definition or explicit cache controls (see 7264 Section 4.2.2 of [Caching]). 7266 | *Note:* This status code is much younger (June 2014) than its 7267 | sibling codes, and thus might not be recognized everywhere. 7268 | See Section 4 of [RFC7538] for deployment considerations. 7270 15.5. Client Error 4xx 7272 The _4xx (Client Error)_ class of status code indicates that the 7273 client seems to have erred. Except when responding to a HEAD 7274 request, the server SHOULD send a representation containing an 7275 explanation of the error situation, and whether it is a temporary or 7276 permanent condition. These status codes are applicable to any 7277 request method. User agents SHOULD display any included 7278 representation to the user. 7280 15.5.1. 400 Bad Request 7282 The _400 (Bad Request)_ status code indicates that the server cannot 7283 or will not process the request due to something that is perceived to 7284 be a client error (e.g., malformed request syntax, invalid request 7285 message framing, or deceptive request routing). 7287 15.5.2. 401 Unauthorized 7289 The _401 (Unauthorized)_ status code indicates that the request has 7290 not been applied because it lacks valid authentication credentials 7291 for the target resource. The server generating a 401 response MUST 7292 send a WWW-Authenticate header field (Section 11.6.1) containing at 7293 least one challenge applicable to the target resource. 7295 If the request included authentication credentials, then the 401 7296 response indicates that authorization has been refused for those 7297 credentials. The user agent MAY repeat the request with a new or 7298 replaced Authorization header field (Section 11.6.2). If the 401 7299 response contains the same challenge as the prior response, and the 7300 user agent has already attempted authentication at least once, then 7301 the user agent SHOULD present the enclosed representation to the 7302 user, since it usually contains relevant diagnostic information. 7304 15.5.3. 402 Payment Required 7306 The _402 (Payment Required)_ status code is reserved for future use. 7308 15.5.4. 403 Forbidden 7310 The _403 (Forbidden)_ status code indicates that the server 7311 understood the request but refuses to fulfill it. A server that 7312 wishes to make public why the request has been forbidden can describe 7313 that reason in the response content (if any). 7315 If authentication credentials were provided in the request, the 7316 server considers them insufficient to grant access. The client 7317 SHOULD NOT automatically repeat the request with the same 7318 credentials. The client MAY repeat the request with new or different 7319 credentials. However, a request might be forbidden for reasons 7320 unrelated to the credentials. 7322 An origin server that wishes to "hide" the current existence of a 7323 forbidden target resource MAY instead respond with a status code of 7324 404 (Not Found). 7326 15.5.5. 404 Not Found 7328 The _404 (Not Found)_ status code indicates that the origin server 7329 did not find a current representation for the target resource or is 7330 not willing to disclose that one exists. A 404 status code does not 7331 indicate whether this lack of representation is temporary or 7332 permanent; the 410 (Gone) status code is preferred over 404 if the 7333 origin server knows, presumably through some configurable means, that 7334 the condition is likely to be permanent. 7336 A 404 response is heuristically cacheable; i.e., unless otherwise 7337 indicated by the method definition or explicit cache controls (see 7338 Section 4.2.2 of [Caching]). 7340 15.5.6. 405 Method Not Allowed 7342 The _405 (Method Not Allowed)_ status code indicates that the method 7343 received in the request-line is known by the origin server but not 7344 supported by the target resource. The origin server MUST generate an 7345 Allow header field in a 405 response containing a list of the target 7346 resource's currently supported methods. 7348 A 405 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 15.5.7. 406 Not Acceptable 7354 The _406 (Not Acceptable)_ status code indicates that the target 7355 resource does not have a current representation that would be 7356 acceptable to the user agent, according to the proactive negotiation 7357 header fields received in the request (Section 12.1), and the server 7358 is unwilling to supply a default representation. 7360 The server SHOULD generate content containing a list of available 7361 representation characteristics and corresponding resource identifiers 7362 from which the user or user agent can choose the one most 7363 appropriate. A user agent MAY automatically select the most 7364 appropriate choice from that list. However, this specification does 7365 not define any standard for such automatic selection, as described in 7366 Section 15.4.1. 7368 15.5.8. 407 Proxy Authentication Required 7370 The _407 (Proxy Authentication Required)_ status code is similar to 7371 401 (Unauthorized), but it indicates that the client needs to 7372 authenticate itself in order to use a proxy for this request. The 7373 proxy MUST send a Proxy-Authenticate header field (Section 11.7.1) 7374 containing a challenge applicable to that proxy for the request. The 7375 client MAY repeat the request with a new or replaced 7376 Proxy-Authorization header field (Section 11.7.2). 7378 15.5.9. 408 Request Timeout 7380 The _408 (Request Timeout)_ status code indicates that the server did 7381 not receive a complete request message within the time that it was 7382 prepared to wait. 7384 If the client has an outstanding request in transit, it MAY repeat 7385 that request. If the current connection is not usable (e.g., as it 7386 would be in HTTP/1.1, because request delimitation is lost), a new 7387 connection will be used. 7389 15.5.10. 409 Conflict 7391 The _409 (Conflict)_ status code indicates that the request could not 7392 be completed due to a conflict with the current state of the target 7393 resource. This code is used in situations where the user might be 7394 able to resolve the conflict and resubmit the request. The server 7395 SHOULD generate content that includes enough information for a user 7396 to recognize the source of the conflict. 7398 Conflicts are most likely to occur in response to a PUT request. For 7399 example, if versioning were being used and the representation being 7400 PUT included changes to a resource that conflict with those made by 7401 an earlier (third-party) request, the origin server might use a 409 7402 response to indicate that it can't complete the request. In this 7403 case, the response representation would likely contain information 7404 useful for merging the differences based on the revision history. 7406 15.5.11. 410 Gone 7408 The _410 (Gone)_ status code indicates that access to the target 7409 resource is no longer available at the origin server and that this 7410 condition is likely to be permanent. If the origin server does not 7411 know, or has no facility to determine, whether or not the condition 7412 is permanent, the status code 404 (Not Found) ought to be used 7413 instead. 7415 The 410 response is primarily intended to assist the task of web 7416 maintenance by notifying the recipient that the resource is 7417 intentionally unavailable and that the server owners desire that 7418 remote links to that resource be removed. Such an event is common 7419 for limited-time, promotional services and for resources belonging to 7420 individuals no longer associated with the origin server's site. It 7421 is not necessary to mark all permanently unavailable resources as 7422 "gone" or to keep the mark for any length of time - that is left to 7423 the discretion of the server owner. 7425 A 410 response is heuristically cacheable; i.e., unless otherwise 7426 indicated by the method definition or explicit cache controls (see 7427 Section 4.2.2 of [Caching]). 7429 15.5.12. 411 Length Required 7431 The _411 (Length Required)_ status code indicates that the server 7432 refuses to accept the request without a defined Content-Length 7433 (Section 8.6). The client MAY repeat the request if it adds a valid 7434 Content-Length header field containing the length of the request 7435 content. 7437 15.5.13. 412 Precondition Failed 7439 The _412 (Precondition Failed)_ status code indicates that one or 7440 more conditions given in the request header fields evaluated to false 7441 when tested on the server. This response status code allows the 7442 client to place preconditions on the current resource state (its 7443 current representations and metadata) and, thus, prevent the request 7444 method from being applied if the target resource is in an unexpected 7445 state. 7447 15.5.14. 413 Content Too Large 7449 The _413 (Content Too Large)_ status code indicates that the server 7450 is refusing to process a request because the request content is 7451 larger than the server is willing or able to process. The server MAY 7452 terminate the request, if the protocol version in use allows it; 7453 otherwise, the server MAY close the connection. 7455 If the condition is temporary, the server SHOULD generate a 7456 Retry-After header field to indicate that it is temporary and after 7457 what time the client MAY try again. 7459 15.5.15. 414 URI Too Long 7461 The _414 (URI Too Long)_ status code indicates that the server is 7462 refusing to service the request because the target URI is longer than 7463 the server is willing to interpret. This rare condition is only 7464 likely to occur when a client has improperly converted a POST request 7465 to a GET request with long query information, when the client has 7466 descended into a "black hole" of redirection (e.g., a redirected URI 7467 prefix that points to a suffix of itself) or when the server is under 7468 attack by a client attempting to exploit potential security holes. 7470 A 414 response is heuristically cacheable; i.e., unless otherwise 7471 indicated by the method definition or explicit cache controls (see 7472 Section 4.2.2 of [Caching]). 7474 15.5.16. 415 Unsupported Media Type 7476 The _415 (Unsupported Media Type)_ status code indicates that the 7477 origin server is refusing to service the request because the content 7478 is in a format not supported by this method on the target resource. 7480 The format problem might be due to the request's indicated 7481 Content-Type or Content-Encoding, or as a result of inspecting the 7482 data directly. 7484 If the problem was caused by an unsupported content coding, the 7485 Accept-Encoding response header field (Section 12.5.3) ought to be 7486 used to indicate what (if any) content codings would have been 7487 accepted in the request. 7489 On the other hand, if the cause was an unsupported media type, the 7490 Accept response header field (Section 12.5.1) can be used to indicate 7491 what media types would have been accepted in the request. 7493 15.5.17. 416 Range Not Satisfiable 7495 The _416 (Range Not Satisfiable)_ status code indicates that the set 7496 of ranges in the request's Range header field (Section 14.2) has been 7497 rejected either because none of the requested ranges are satisfiable 7498 or because the client has requested an excessive number of small or 7499 overlapping ranges (a potential denial of service attack). 7501 Each range unit defines what is required for its own range sets to be 7502 satisfiable. For example, Section 14.1.2 defines what makes a bytes 7503 range set satisfiable. 7505 When this status code is generated in response to a byte-range 7506 request, the sender SHOULD generate a Content-Range header field 7507 specifying the current length of the selected representation 7508 (Section 14.4). 7510 For example: 7512 HTTP/1.1 416 Range Not Satisfiable 7513 Date: Fri, 20 Jan 2012 15:41:54 GMT 7514 Content-Range: bytes */47022 7516 | *Note:* Because servers are free to ignore Range, many 7517 | implementations will respond with the entire selected 7518 | representation in a 200 (OK) response. That is partly because 7519 | most clients are prepared to receive a 200 (OK) to complete the 7520 | task (albeit less efficiently) and partly because clients might 7521 | not stop making an invalid range request until they have 7522 | received a complete representation. Thus, clients cannot 7523 | depend on receiving a 416 (Range Not Satisfiable) response even 7524 | when it is most appropriate. 7526 15.5.18. 417 Expectation Failed 7528 The _417 (Expectation Failed)_ status code indicates that the 7529 expectation given in the request's Expect header field 7530 (Section 10.1.1) could not be met by at least one of the inbound 7531 servers. 7533 15.5.19. 418 (Unused) 7535 [RFC2324] was an April 1 RFC that lampooned the various ways HTTP was 7536 abused; one such abuse was the definition of an application-specific 7537 418 status code. In the intervening years, this status code has been 7538 widely implemented as an "Easter Egg", and therefore is effectively 7539 consumed by this use. 7541 Therefore, the 418 status code is reserved in the IANA HTTP Status 7542 Code Registry. This indicates that the status code cannot be 7543 assigned to other applications currently. If future circumstances 7544 require its use (e.g., exhaustion of 4NN status codes), it can be re- 7545 assigned to another use. 7547 15.5.20. 421 Misdirected Request 7549 The 421 (Misdirected Request) status code indicates that the request 7550 was directed at a server that is unable or unwilling to produce an 7551 authoritative response for the target URI. A 421 is sent when an 7552 origin server (or gateway acting on behalf of the origin server) 7553 rejects a target URI that does not match an origin for which the 7554 server has been configured (Section 4.3.1) or does not match the 7555 connection context over which the request was received (Section 7.4). 7557 A client that receives a 421 (Misdirected Request) response MAY retry 7558 the request, whether or not the request method is idempotent, over a 7559 different connection, such as a fresh connection specific to the 7560 target resource's origin, or via an alternative service [RFC7838]. 7562 A proxy MUST NOT generate a 421 response. 7564 15.5.21. 422 Unprocessable Content 7566 The 422 (Unprocessable Content) status code indicates that the server 7567 understands the content type of the request content (hence a 415 7568 (Unsupported Media Type) status code is inappropriate), and the 7569 syntax of the request content is correct, but was unable to process 7570 the contained instructions. For example, this status code can be 7571 sent if an XML request content contains well-formed (i.e., 7572 syntactically correct), but semantically erroneous XML instructions. 7574 15.5.22. 426 Upgrade Required 7576 The _426 (Upgrade Required)_ status code indicates that the server 7577 refuses to perform the request using the current protocol but might 7578 be willing to do so after the client upgrades to a different 7579 protocol. The server MUST send an Upgrade header field in a 426 7580 response to indicate the required protocol(s) (Section 7.8). 7582 Example: 7584 HTTP/1.1 426 Upgrade Required 7585 Upgrade: HTTP/3.0 7586 Connection: Upgrade 7587 Content-Length: 53 7588 Content-Type: text/plain 7590 This service requires use of the HTTP/3.0 protocol. 7592 15.6. Server Error 5xx 7594 The _5xx (Server Error)_ class of status code indicates that the 7595 server is aware that it has erred or is incapable of performing the 7596 requested method. Except when responding to a HEAD request, the 7597 server SHOULD send a representation containing an explanation of the 7598 error situation, and whether it is a temporary or permanent 7599 condition. A user agent SHOULD display any included representation 7600 to the user. These response codes are applicable to any request 7601 method. 7603 15.6.1. 500 Internal Server Error 7605 The _500 (Internal Server Error)_ status code indicates that the 7606 server encountered an unexpected condition that prevented it from 7607 fulfilling the request. 7609 15.6.2. 501 Not Implemented 7611 The _501 (Not Implemented)_ status code indicates that the server 7612 does not support the functionality required to fulfill the request. 7613 This is the appropriate response when the server does not recognize 7614 the request method and is not capable of supporting it for any 7615 resource. 7617 A 501 response is heuristically cacheable; i.e., unless otherwise 7618 indicated by the method definition or explicit cache controls (see 7619 Section 4.2.2 of [Caching]). 7621 15.6.3. 502 Bad Gateway 7623 The _502 (Bad Gateway)_ status code indicates that the server, while 7624 acting as a gateway or proxy, received an invalid response from an 7625 inbound server it accessed while attempting to fulfill the request. 7627 15.6.4. 503 Service Unavailable 7629 The _503 (Service Unavailable)_ status code indicates that the server 7630 is currently unable to handle the request due to a temporary overload 7631 or scheduled maintenance, which will likely be alleviated after some 7632 delay. The server MAY send a Retry-After header field 7633 (Section 10.2.4) to suggest an appropriate amount of time for the 7634 client to wait before retrying the request. 7636 | *Note:* The existence of the 503 status code does not imply 7637 | that a server has to use it when becoming overloaded. Some 7638 | servers might simply refuse the connection. 7640 15.6.5. 504 Gateway Timeout 7642 The _504 (Gateway Timeout)_ status code indicates that the server, 7643 while acting as a gateway or proxy, did not receive a timely response 7644 from an upstream server it needed to access in order to complete the 7645 request. 7647 15.6.6. 505 HTTP Version Not Supported 7649 The _505 (HTTP Version Not Supported)_ status code indicates that the 7650 server does not support, or refuses to support, the major version of 7651 HTTP that was used in the request message. The server is indicating 7652 that it is unable or unwilling to complete the request using the same 7653 major version as the client, as described in Section 2.5, other than 7654 with this error message. The server SHOULD generate a representation 7655 for the 505 response that describes why that version is not supported 7656 and what other protocols are supported by that server. 7658 16. Extending HTTP 7660 HTTP defines a number of generic extension points that can be used to 7661 introduce capabilities to the protocol without introducing a new 7662 version, including methods, status codes, field names, and further 7663 extensibility points within defined fields, such as authentication 7664 schemes and cache-directives (see Cache-Control extensions in 7665 Section 5.2.3 of [Caching]). Because the semantics of HTTP are not 7666 versioned, these extension points are persistent; the version of the 7667 protocol in use does not affect their semantics. 7669 Version-independent extensions are discouraged from depending on or 7670 interacting with the specific version of the protocol in use. When 7671 this is unavoidable, careful consideration needs to be given to how 7672 the extension can interoperate across versions. 7674 Additionally, specific versions of HTTP might have their own 7675 extensibility points, such as transfer-codings in HTTP/1.1 7676 (Section 6.1 of [Messaging]) and HTTP/2 ([RFC7540]) SETTINGS or frame 7677 types. These extension points are specific to the version of the 7678 protocol they occur within. 7680 Version-specific extensions cannot override or modify the semantics 7681 of a version-independent mechanism or extension point (like a method 7682 or header field) without explicitly being allowed by that protocol 7683 element. For example, the CONNECT method (Section 9.3.6) allows 7684 this. 7686 These guidelines assure that the protocol operates correctly and 7687 predictably, even when parts of the path implement different versions 7688 of HTTP. 7690 16.1. Method Extensibility 7692 16.1.1. Method Registry 7694 The "Hypertext Transfer Protocol (HTTP) Method Registry", maintained 7695 by IANA at , registers 7696 method names. 7698 HTTP method registrations MUST include the following fields: 7700 o Method Name (see Section 9) 7702 o Safe ("yes" or "no", see Section 9.2.1) 7704 o Idempotent ("yes" or "no", see Section 9.2.2) 7705 o Pointer to specification text 7707 Values to be added to this namespace require IETF Review (see 7708 [RFC8126], Section 4.8). 7710 16.1.2. Considerations for New Methods 7712 Standardized methods are generic; that is, they are potentially 7713 applicable to any resource, not just one particular media type, kind 7714 of resource, or application. As such, it is preferred that new 7715 methods be registered in a document that isn't specific to a single 7716 application or data format, since orthogonal technologies deserve 7717 orthogonal specification. 7719 Since message parsing (Section 6 of [Messaging]) needs to be 7720 independent of method semantics (aside from responses to HEAD), 7721 definitions of new methods cannot change the parsing algorithm or 7722 prohibit the presence of content on either the request or the 7723 response message. Definitions of new methods can specify that only a 7724 zero-length content is allowed by requiring a Content-Length header 7725 field with a value of "0". 7727 Likewise, new methods cannot use the special host:port and asterisk 7728 forms of request target that are allowed for CONNECT and OPTIONS, 7729 respectively (Section 7.1). A full URI in absolute form is needed 7730 for the target URI, which means either the request target needs to be 7731 sent in absolute form or the target URI will be reconstructed from 7732 the request context in the same way it is for other methods. 7734 A new method definition needs to indicate whether it is safe 7735 (Section 9.2.1), idempotent (Section 9.2.2), cacheable 7736 (Section 9.2.3), what semantics are to be associated with the request 7737 content (if any), and what refinements the method makes to header 7738 field or status code semantics. If the new method is cacheable, its 7739 definition ought to describe how, and under what conditions, a cache 7740 can store a response and use it to satisfy a subsequent request. The 7741 new method ought to describe whether it can be made conditional 7742 (Section 13.1) and, if so, how a server responds when the condition 7743 is false. Likewise, if the new method might have some use for 7744 partial response semantics (Section 14.2), it ought to document this, 7745 too. 7747 | *Note:* Avoid defining a method name that starts with "M-", 7748 | since that prefix might be misinterpreted as having the 7749 | semantics assigned to it by [RFC2774]. 7751 16.2. Status Code Extensibility 7752 16.2.1. Status Code Registry 7754 The "Hypertext Transfer Protocol (HTTP) Status Code Registry", 7755 maintained by IANA at , registers status code numbers. 7758 A registration MUST include the following fields: 7760 o Status Code (3 digits) 7762 o Short Description 7764 o Pointer to specification text 7766 Values to be added to the HTTP status code namespace require IETF 7767 Review (see [RFC8126], Section 4.8). 7769 16.2.2. Considerations for New Status Codes 7771 When it is necessary to express semantics for a response that are not 7772 defined by current status codes, a new status code can be registered. 7773 Status codes are generic; they are potentially applicable to any 7774 resource, not just one particular media type, kind of resource, or 7775 application of HTTP. As such, it is preferred that new status codes 7776 be registered in a document that isn't specific to a single 7777 application. 7779 New status codes are required to fall under one of the categories 7780 defined in Section 15. To allow existing parsers to process the 7781 response message, new status codes cannot disallow content, although 7782 they can mandate a zero-length content. 7784 Proposals for new status codes that are not yet widely deployed ought 7785 to avoid allocating a specific number for the code until there is 7786 clear consensus that it will be registered; instead, early drafts can 7787 use a notation such as "4NN", or "3N0" .. "3N9", to indicate the 7788 class of the proposed status code(s) without consuming a number 7789 prematurely. 7791 The definition of a new status code ought to explain the request 7792 conditions that would cause a response containing that status code 7793 (e.g., combinations of request header fields and/or method(s)) along 7794 with any dependencies on response header fields (e.g., what fields 7795 are required, what fields can modify the semantics, and what field 7796 semantics are further refined when used with the new status code). 7798 By default, a status code applies only to the request corresponding 7799 to the response it occurs within. If a status code applies to a 7800 larger scope of applicability - for example, all requests to the 7801 resource in question, or all requests to a server - this must be 7802 explicitly specified. When doing so, it should be noted that not all 7803 clients can be expected to consistently apply a larger scope, because 7804 they might not understand the new status code. 7806 The definition of a new status code ought to specify whether or not 7807 it is cacheable. Note that all status codes can be cached if the 7808 response they occur in has explicit freshness information; however, 7809 status codes that are defined as being cacheable are allowed to be 7810 cached without explicit freshness information. Likewise, the 7811 definition of a status code can place constraints upon cache 7812 behavior. See [Caching] for more information. 7814 Finally, the definition of a new status code ought to indicate 7815 whether the content has any implied association with an identified 7816 resource (Section 6.4.2). 7818 16.3. Field Extensibility 7820 HTTP's most widely used extensibility point is the definition of new 7821 header and trailer fields. 7823 New fields can be defined such that, when they are understood by a 7824 recipient, they override or enhance the interpretation of previously 7825 defined fields, define preconditions on request evaluation, or refine 7826 the meaning of responses. 7828 However, defining a field doesn't guarantee its deployment or 7829 recognition by recipients. Most fields are designed with the 7830 expectation that a recipient can safely ignore (but forward 7831 downstream) any field not recognized. In other cases, the sender's 7832 ability to understand a given field might be indicated by its prior 7833 communication, perhaps in the protocol version or fields that it sent 7834 in prior messages, or its use of a specific media type. Likewise, 7835 direct inspection of support might be possible through an OPTIONS 7836 request or by interacting with a defined well-known URI [RFC8615] if 7837 such inspection is defined along with the field being introduced. 7839 16.3.1. Field Name Registry 7841 The "Hypertext Transfer Protocol (HTTP) Field Name Registry" defines 7842 the namespace for HTTP field names. 7844 Any party can request registration of a HTTP field. See 7845 Section 16.3.2 for considerations to take into account when creating 7846 a new HTTP field. 7848 The "Hypertext Transfer Protocol (HTTP) Field Name Registry" is 7849 located at . 7850 Registration requests can be made by following the instructions 7851 located there or by sending an email to the "ietf-http-wg@ietf.org" 7852 mailing list. 7854 Field names are registered on the advice of a Designated Expert 7855 (appointed by the IESG or their delegate). Fields with the status 7856 'permanent' are Specification Required ([RFC8126], Section 4.6). 7858 Registration requests consist of at least the following information: 7860 Field name: 7861 The requested field name. It MUST conform to the field-name 7862 syntax defined in Section 5.1, and SHOULD be restricted to just 7863 letters, digits, hyphen ('-') and underscore ('_') characters, 7864 with the first character being a letter. 7866 Status: 7867 "permanent" or "provisional". 7869 Specification document(s): 7870 Reference to the document that specifies the field, preferably 7871 including a URI that can be used to retrieve a copy of the 7872 document. An indication of the relevant section(s) can also be 7873 included, but is not required. 7875 And, optionally: 7877 Comments: Additional information, such as about reserved entries. 7879 The Expert(s) can define additional fields to be collected in the 7880 registry, in consultation with the community. 7882 Standards-defined names have a status of "permanent". Other names 7883 can also be registered as permanent, if the Expert(s) find that they 7884 are in use, in consultation with the community. Other names should 7885 be registered as "provisional". 7887 Provisional entries can be removed by the Expert(s) if - in 7888 consultation with the community - the Expert(s) find that they are 7889 not in use. The Experts can change a provisional entry's status to 7890 permanent at any time. 7892 Note that names can be registered by third parties (including the 7893 Expert(s)), if the Expert(s) determines that an unregistered name is 7894 widely deployed and not likely to be registered in a timely manner 7895 otherwise. 7897 16.3.2. Considerations for New Fields 7899 HTTP header and trailer fields are a widely-used extension point for 7900 the protocol. While they can be used in an ad hoc fashion, fields 7901 that are intended for wider use need to be carefully documented to 7902 ensure interoperability. 7904 In particular, authors of specifications defining new fields are 7905 advised to consider and, where appropriate, document the following 7906 aspects: 7908 o Under what conditions the field can be used; e.g., only in 7909 responses or requests, in all messages, only on responses to a 7910 particular request method, etc. 7912 o Whether the field semantics are further refined by their context, 7913 such as their use with certain request methods or status codes. 7915 o The scope of applicability for the information conveyed. By 7916 default, fields apply only to the message they are associated 7917 with, but some response fields are designed to apply to all 7918 representations of a resource, the resource itself, or an even 7919 broader scope. Specifications that expand the scope of a response 7920 field will need to carefully consider issues such as content 7921 negotiation, the time period of applicability, and (in some cases) 7922 multi-tenant server deployments. 7924 o Under what conditions intermediaries are allowed to insert, 7925 delete, or modify the field's value. 7927 o If the field is allowable in trailers; by default, it will not be 7928 (see Section 6.5.1). 7930 o Whether it is appropriate to list the field name in the Connection 7931 header field (i.e., if the field is to be hop-by-hop; see 7932 Section 7.6.1). 7934 o Whether the field introduces any additional security 7935 considerations, such as disclosure of privacy-related data. 7937 Request header fields have additional considerations that need to be 7938 documented if the default behaviour is not appropriate: 7940 o If it is appropriate to list the field name in a Vary response 7941 header field (e.g., when the request header field is used by an 7942 origin server's content selection algorithm; see Section 12.5.5). 7944 o If the field is intended to be stored when received in a PUT 7945 request (see Section 9.3.4). 7947 o If the field ought to be removed when automatically redirecting a 7948 request, due to security concerns (see Section 15.4). 7950 16.3.2.1. Considerations for New Field Names 7952 Authors of specifications defining new fields are advised to choose a 7953 short but descriptive field name. Short names avoid needless data 7954 transmission; descriptive names avoid confusion and "squatting" on 7955 names that might have broader uses. 7957 To that end, limited-use fields (such as a header confined to a 7958 single application or use case) are encouraged to use a name that 7959 includes that use (or an abbreviation) as a prefix; for example, if 7960 the Foo Application needs a Description field, it might use "Foo- 7961 Desc"; "Description" is too generic, and "Foo-Description" is 7962 needlessly long. 7964 While the field-name syntax is defined to allow any token character, 7965 in practice some implementations place limits on the characters they 7966 accept in field-names. To be interoperable, new field names SHOULD 7967 constrain themselves to alphanumeric characters, "-", and ".", and 7968 SHOULD begin with an alphanumeric character. 7970 Field names ought not be prefixed with "X-"; see [BCP178] for further 7971 information. 7973 Other prefixes are sometimes used in HTTP field names; for example, 7974 "Accept-" is used in many content negotiation headers. These 7975 prefixes are only an aid to recognizing the purpose of a field, and 7976 do not trigger automatic processing. 7978 16.3.2.2. Considerations for New Field Values 7980 A major task in the definition of a new HTTP field is the 7981 specification of the field value syntax: what senders should 7982 generate, and how recipients should infer semantics from what is 7983 received. 7985 Authors are encouraged (but not required) to use either the ABNF 7986 rules in this specification or those in [RFCSTRF] to define the 7987 syntax of new field values. 7989 Authors are advised to carefully consider how the combination of 7990 multiple field lines will impact them (see Section 5.3). Because 7991 senders might send erroneously send multiple values, and both 7992 intermediaries and HTTP libraries can perform combination 7993 automatically, this applies to all field values - even when only a 7994 single value is anticipated. 7996 Therefore, authors are advised to delimit or encode values that 7997 contain commas (e.g., with the quoted-string rule of Section 5.6.4, 7998 the String data type of [RFCSTRF]), or a field-specific encoding). 7999 This ensures that commas within field data are not confused with the 8000 commas that delimit a list value. 8002 For example, the Content-Type field value only allows commas inside 8003 quoted strings, which can be reliably parsed even when multiple 8004 values are present. The Location field value provides a counter- 8005 example that should not be emulated: because URIs can include commas, 8006 it is not possible to reliably distinguish between a single value 8007 that includes a comma from two values. 8009 Authors of fields with a singleton value (see Section 5.5) are 8010 additionally advised to document how to treat messages where the 8011 multiple members are present (a sensible default would be to ignore 8012 the field, but this might not always be the right choice). 8014 16.4. Authentication Scheme Extensibility 8016 16.4.1. Authentication Scheme Registry 8018 The "Hypertext Transfer Protocol (HTTP) Authentication Scheme 8019 Registry" defines the namespace for the authentication schemes in 8020 challenges and credentials. It is maintained at 8021 . 8023 Registrations MUST include the following fields: 8025 o Authentication Scheme Name 8027 o Pointer to specification text 8029 o Notes (optional) 8031 Values to be added to this namespace require IETF Review (see 8032 [RFC8126], Section 4.8). 8034 16.4.2. Considerations for New Authentication Schemes 8036 There are certain aspects of the HTTP Authentication framework that 8037 put constraints on how new authentication schemes can work: 8039 o HTTP authentication is presumed to be stateless: all of the 8040 information necessary to authenticate a request MUST be provided 8041 in the request, rather than be dependent on the server remembering 8042 prior requests. Authentication based on, or bound to, the 8043 underlying connection is outside the scope of this specification 8044 and inherently flawed unless steps are taken to ensure that the 8045 connection cannot be used by any party other than the 8046 authenticated user (see Section 3.7). 8048 o The authentication parameter "realm" is reserved for defining 8049 protection spaces as described in Section 11.5. New schemes MUST 8050 NOT use it in a way incompatible with that definition. 8052 o The "token68" notation was introduced for compatibility with 8053 existing authentication schemes and can only be used once per 8054 challenge or credential. Thus, new schemes ought to use the auth- 8055 param syntax instead, because otherwise future extensions will be 8056 impossible. 8058 o The parsing of challenges and credentials is defined by this 8059 specification and cannot be modified by new authentication 8060 schemes. When the auth-param syntax is used, all parameters ought 8061 to support both token and quoted-string syntax, and syntactical 8062 constraints ought to be defined on the field value after parsing 8063 (i.e., quoted-string processing). This is necessary so that 8064 recipients can use a generic parser that applies to all 8065 authentication schemes. 8067 *Note:* The fact that the value syntax for the "realm" parameter 8068 is restricted to quoted-string was a bad design choice not to be 8069 repeated for new parameters. 8071 o Definitions of new schemes ought to define the treatment of 8072 unknown extension parameters. In general, a "must-ignore" rule is 8073 preferable to a "must-understand" rule, because otherwise it will 8074 be hard to introduce new parameters in the presence of legacy 8075 recipients. Furthermore, it's good to describe the policy for 8076 defining new parameters (such as "update the specification" or 8077 "use this registry"). 8079 o Authentication schemes need to document whether they are usable in 8080 origin-server authentication (i.e., using WWW-Authenticate), and/ 8081 or proxy authentication (i.e., using Proxy-Authenticate). 8083 o The credentials carried in an Authorization header field are 8084 specific to the user agent and, therefore, have the same effect on 8085 HTTP caches as the "private" Cache-Control response directive 8086 (Section 5.2.2.7 of [Caching]), within the scope of the request in 8087 which they appear. 8089 Therefore, new authentication schemes that choose not to carry 8090 credentials in the Authorization header field (e.g., using a newly 8091 defined header field) will need to explicitly disallow caching, by 8092 mandating the use of Cache-Control response directives (e.g., 8093 "private"). 8095 o Schemes using Authentication-Info, Proxy-Authentication-Info, or 8096 any other authentication related response header field need to 8097 consider and document the related security considerations (see 8098 Section 17.15.4). 8100 16.5. Range Unit Extensibility 8102 16.5.1. Range Unit Registry 8104 The "HTTP Range Unit Registry" defines the namespace for the range 8105 unit names and refers to their corresponding specifications. It is 8106 maintained at . 8108 Registration of an HTTP Range Unit MUST include the following fields: 8110 o Name 8112 o Description 8114 o Pointer to specification text 8116 Values to be added to this namespace require IETF Review (see 8117 [RFC8126], Section 4.8). 8119 16.5.2. Considerations for New Range Units 8121 Other range units, such as format-specific boundaries like pages, 8122 sections, records, rows, or time, are potentially usable in HTTP for 8123 application-specific purposes, but are not commonly used in practice. 8124 Implementors of alternative range units ought to consider how they 8125 would work with content codings and general-purpose intermediaries. 8127 16.6. Content Coding Extensibility 8128 16.6.1. Content Coding Registry 8130 The "HTTP Content Coding Registry", maintained by IANA at 8131 , registers 8132 content-coding names. 8134 Content coding registrations MUST include the following fields: 8136 o Name 8138 o Description 8140 o Pointer to specification text 8142 Names of content codings MUST NOT overlap with names of transfer 8143 codings (Section 7 of [Messaging]), unless the encoding 8144 transformation is identical (as is the case for the compression 8145 codings defined in Section 8.4.1). 8147 Values to be added to this namespace require IETF Review (see 8148 Section 4.8 of [RFC8126]) and MUST conform to the purpose of content 8149 coding defined in Section 8.4.1. 8151 16.6.2. Considerations for New Content Codings 8153 New content codings ought to be self-descriptive whenever possible, 8154 with optional parameters discoverable within the coding format 8155 itself, rather than rely on external metadata that might be lost 8156 during transit. 8158 16.7. Upgrade Token Registry 8160 The "Hypertext Transfer Protocol (HTTP) Upgrade Token Registry" 8161 defines the namespace for protocol-name tokens used to identify 8162 protocols in the Upgrade header field. The registry is maintained at 8163 . 8165 Each registered protocol name is associated with contact information 8166 and an optional set of specifications that details how the connection 8167 will be processed after it has been upgraded. 8169 Registrations happen on a "First Come First Served" basis (see 8170 Section 4.4 of [RFC8126]) and are subject to the following rules: 8172 1. A protocol-name token, once registered, stays registered forever. 8174 2. A protocol-name token is case-insensitive and registered with the 8175 preferred case to be generated by senders. 8177 3. The registration MUST name a responsible party for the 8178 registration. 8180 4. The registration MUST name a point of contact. 8182 5. The registration MAY name a set of specifications associated with 8183 that token. Such specifications need not be publicly available. 8185 6. The registration SHOULD name a set of expected "protocol-version" 8186 tokens associated with that token at the time of registration. 8188 7. The responsible party MAY change the registration at any time. 8189 The IANA will keep a record of all such changes, and make them 8190 available upon request. 8192 8. The IESG MAY reassign responsibility for a protocol token. This 8193 will normally only be used in the case when a responsible party 8194 cannot be contacted. 8196 17. Security Considerations 8198 This section is meant to inform developers, information providers, 8199 and users of known security concerns relevant to HTTP semantics and 8200 its use for transferring information over the Internet. 8201 Considerations related to caching are discussed in Section 7 of 8202 [Caching] and considerations related to HTTP/1.1 message syntax and 8203 parsing are discussed in Section 11 of [Messaging]. 8205 The list of considerations below is not exhaustive. Most security 8206 concerns related to HTTP semantics are about securing server-side 8207 applications (code behind the HTTP interface), securing user agent 8208 processing of content received via HTTP, or secure use of the 8209 Internet in general, rather than security of the protocol. Various 8210 organizations maintain topical information and links to current 8211 research on Web application security (e.g., [OWASP]). 8213 17.1. Establishing Authority 8215 HTTP relies on the notion of an _authoritative response_: a response 8216 that has been determined by (or at the direction of) the origin 8217 server identified within the target URI to be the most appropriate 8218 response for that request given the state of the target resource at 8219 the time of response message origination. 8221 When a registered name is used in the authority component, the "http" 8222 URI scheme (Section 4.2.1) relies on the user's local name resolution 8223 service to determine where it can find authoritative responses. This 8224 means that any attack on a user's network host table, cached names, 8225 or name resolution libraries becomes an avenue for attack on 8226 establishing authority for "http" URIs. Likewise, the user's choice 8227 of server for Domain Name Service (DNS), and the hierarchy of servers 8228 from which it obtains resolution results, could impact the 8229 authenticity of address mappings; DNS Security Extensions (DNSSEC, 8230 [RFC4033]) are one way to improve authenticity. 8232 Furthermore, after an IP address is obtained, establishing authority 8233 for an "http" URI is vulnerable to attacks on Internet Protocol 8234 routing. 8236 The "https" scheme (Section 4.2.2) is intended to prevent (or at 8237 least reveal) many of these potential attacks on establishing 8238 authority, provided that the negotiated connection is secured and the 8239 client properly verifies that the communicating server's identity 8240 matches the target URI's authority component (Section 4.3.4). 8241 Correctly implementing such verification can be difficult (see 8242 [Georgiev]). 8244 Authority for a given origin server can be delegated through protocol 8245 extensions; for example, [RFC7838]. Likewise, the set of servers for 8246 which a connection is considered authoritative can be changed with a 8247 protocol extension like [RFC8336]. 8249 Providing a response from a non-authoritative source, such as a 8250 shared proxy cache, is often useful to improve performance and 8251 availability, but only to the extent that the source can be trusted 8252 or the distrusted response can be safely used. 8254 Unfortunately, communicating authority to users can be difficult. 8255 For example, _phishing_ is an attack on the user's perception of 8256 authority, where that perception can be misled by presenting similar 8257 branding in hypertext, possibly aided by userinfo obfuscating the 8258 authority component (see Section 4.2.1). User agents can reduce the 8259 impact of phishing attacks by enabling users to easily inspect a 8260 target URI prior to making an action, by prominently distinguishing 8261 (or rejecting) userinfo when present, and by not sending stored 8262 credentials and cookies when the referring document is from an 8263 unknown or untrusted source. 8265 17.2. Risks of Intermediaries 8267 HTTP intermediaries are inherently situated for on-path attacks. 8268 Compromise of the systems on which the intermediaries run can result 8269 in serious security and privacy problems. Intermediaries might have 8270 access to security-related information, personal information about 8271 individual users and organizations, and proprietary information 8272 belonging to users and content providers. A compromised 8273 intermediary, or an intermediary implemented or configured without 8274 regard to security and privacy considerations, might be used in the 8275 commission of a wide range of potential attacks. 8277 Intermediaries that contain a shared cache are especially vulnerable 8278 to cache poisoning attacks, as described in Section 7 of [Caching]. 8280 Implementers need to consider the privacy and security implications 8281 of their design and coding decisions, and of the configuration 8282 options they provide to operators (especially the default 8283 configuration). 8285 Users need to be aware that intermediaries are no more trustworthy 8286 than the people who run them; HTTP itself cannot solve this problem. 8288 17.3. Attacks Based on File and Path Names 8290 Origin servers frequently make use of their local file system to 8291 manage the mapping from target URI to resource representations. Most 8292 file systems are not designed to protect against malicious file or 8293 path names. Therefore, an origin server needs to avoid accessing 8294 names that have a special significance to the system when mapping the 8295 target resource to files, folders, or directories. 8297 For example, UNIX, Microsoft Windows, and other operating systems use 8298 ".." as a path component to indicate a directory level above the 8299 current one, and they use specially named paths or file names to send 8300 data to system devices. Similar naming conventions might exist 8301 within other types of storage systems. Likewise, local storage 8302 systems have an annoying tendency to prefer user-friendliness over 8303 security when handling invalid or unexpected characters, 8304 recomposition of decomposed characters, and case-normalization of 8305 case-insensitive names. 8307 Attacks based on such special names tend to focus on either denial- 8308 of-service (e.g., telling the server to read from a COM port) or 8309 disclosure of configuration and source files that are not meant to be 8310 served. 8312 17.4. Attacks Based on Command, Code, or Query Injection 8314 Origin servers often use parameters within the URI as a means of 8315 identifying system services, selecting database entries, or choosing 8316 a data source. However, data received in a request cannot be 8317 trusted. An attacker could construct any of the request data 8318 elements (method, target URI, header fields, or content) to contain 8319 data that might be misinterpreted as a command, code, or query when 8320 passed through a command invocation, language interpreter, or 8321 database interface. 8323 For example, SQL injection is a common attack wherein additional 8324 query language is inserted within some part of the target URI or 8325 header fields (e.g., Host, Referer, etc.). If the received data is 8326 used directly within a SELECT statement, the query language might be 8327 interpreted as a database command instead of a simple string value. 8328 This type of implementation vulnerability is extremely common, in 8329 spite of being easy to prevent. 8331 In general, resource implementations ought to avoid use of request 8332 data in contexts that are processed or interpreted as instructions. 8333 Parameters ought to be compared to fixed strings and acted upon as a 8334 result of that comparison, rather than passed through an interface 8335 that is not prepared for untrusted data. Received data that isn't 8336 based on fixed parameters ought to be carefully filtered or encoded 8337 to avoid being misinterpreted. 8339 Similar considerations apply to request data when it is stored and 8340 later processed, such as within log files, monitoring tools, or when 8341 included within a data format that allows embedded scripts. 8343 17.5. Attacks via Protocol Element Length 8345 Because HTTP uses mostly textual, character-delimited fields, parsers 8346 are often vulnerable to attacks based on sending very long (or very 8347 slow) streams of data, particularly where an implementation is 8348 expecting a protocol element with no predefined length (Section 2.3). 8350 To promote interoperability, specific recommendations are made for 8351 minimum size limits on fields (Section 5.4). These are minimum 8352 recommendations, chosen to be supportable even by implementations 8353 with limited resources; it is expected that most implementations will 8354 choose substantially higher limits. 8356 A server can reject a message that has a target URI that is too long 8357 (Section 15.5.15) or request content that is too large 8358 (Section 15.5.14). Additional status codes related to capacity 8359 limits have been defined by extensions to HTTP [RFC6585]. 8361 Recipients ought to carefully limit the extent to which they process 8362 other protocol elements, including (but not limited to) request 8363 methods, response status phrases, field names, numeric values, and 8364 chunk lengths. Failure to limit such processing can result in buffer 8365 overflows, arithmetic overflows, or increased vulnerability to 8366 denial-of-service attacks. 8368 17.6. Attacks using Shared-dictionary Compression 8370 Some attacks on encrypted protocols use the differences in size 8371 created by dynamic compression to reveal confidential information; 8372 for example, [BREACH]. These attacks rely on creating a redundancy 8373 between attacker-controlled content and the confidential information, 8374 such that a dynamic compression algorithm using the same dictionary 8375 for both content will compress more efficiently when the attacker- 8376 controlled content matches parts of the confidential content. 8378 HTTP messages can be compressed in a number of ways, including using 8379 TLS compression, content-codings, transfer-codings, and other 8380 extension or version-specific mechanisms. 8382 The most effective mitigation for this risk is to disable compression 8383 on sensitive data, or to strictly separate sensitive data from 8384 attacker-controlled data so that they cannot share the same 8385 compression dictionary. With careful design, a compression scheme 8386 can be designed in a way that is not considered exploitable in 8387 limited use cases, such as HPACK ([RFC7541]). 8389 17.7. Disclosure of Personal Information 8391 Clients are often privy to large amounts of personal information, 8392 including both information provided by the user to interact with 8393 resources (e.g., the user's name, location, mail address, passwords, 8394 encryption keys, etc.) and information about the user's browsing 8395 activity over time (e.g., history, bookmarks, etc.). Implementations 8396 need to prevent unintentional disclosure of personal information. 8398 17.8. Privacy of Server Log Information 8400 A server is in the position to save personal data about a user's 8401 requests over time, which might identify their reading patterns or 8402 subjects of interest. In particular, log information gathered at an 8403 intermediary often contains a history of user agent interaction, 8404 across a multitude of sites, that can be traced to individual users. 8406 HTTP log information is confidential in nature; its handling is often 8407 constrained by laws and regulations. Log information needs to be 8408 securely stored and appropriate guidelines followed for its analysis. 8410 Anonymization of personal information within individual entries 8411 helps, but it is generally not sufficient to prevent real log traces 8412 from being re-identified based on correlation with other access 8413 characteristics. As such, access traces that are keyed to a specific 8414 client are unsafe to publish even if the key is pseudonymous. 8416 To minimize the risk of theft or accidental publication, log 8417 information ought to be purged of personally identifiable 8418 information, including user identifiers, IP addresses, and user- 8419 provided query parameters, as soon as that information is no longer 8420 necessary to support operational needs for security, auditing, or 8421 fraud control. 8423 17.9. Disclosure of Sensitive Information in URIs 8425 URIs are intended to be shared, not secured, even when they identify 8426 secure resources. URIs are often shown on displays, added to 8427 templates when a page is printed, and stored in a variety of 8428 unprotected bookmark lists. Many servers, proxies, and user agents 8429 log or display the target URI in places where it might be visible to 8430 third parties. It is therefore unwise to include information within 8431 a URI that is sensitive, personally identifiable, or a risk to 8432 disclose. 8434 When an application uses client-side mechanisms to construct a target 8435 URI out of user-provided information, such as the query fields of a 8436 form using GET, potentially sensitive data might be provided that 8437 would not be appropriate for disclosure within a URI. POST is often 8438 preferred in such cases because it usually doesn't construct a URI; 8439 instead, POST of a form transmits the potentially sensitive data in 8440 the request content. However, this hinders caching and uses an 8441 unsafe method for what would otherwise be a safe request. 8442 Alternative workarounds include transforming the user-provided data 8443 prior to constructing the URI, or filtering the data to only include 8444 common values that are not sensitive. Likewise, redirecting the 8445 result of a query to a different (server-generated) URI can remove 8446 potentially sensitive data from later links and provide a cacheable 8447 response for later reuse. 8449 Since the Referer header field tells a target site about the context 8450 that resulted in a request, it has the potential to reveal 8451 information about the user's immediate browsing history and any 8452 personal information that might be found in the referring resource's 8453 URI. Limitations on the Referer header field are described in 8454 Section 10.1.3 to address some of its security considerations. 8456 17.10. Disclosure of Fragment after Redirects 8458 Although fragment identifiers used within URI references are not sent 8459 in requests, implementers ought to be aware that they will be visible 8460 to the user agent and any extensions or scripts running as a result 8461 of the response. In particular, when a redirect occurs and the 8462 original request's fragment identifier is inherited by the new 8463 reference in Location (Section 10.2.3), this might have the effect of 8464 disclosing one site's fragment to another site. If the first site 8465 uses personal information in fragments, it ought to ensure that 8466 redirects to other sites include a (possibly empty) fragment 8467 component in order to block that inheritance. 8469 17.11. Disclosure of Product Information 8471 The User-Agent (Section 10.1.6), Via (Section 7.6.3), and Server 8472 (Section 10.2.5) header fields often reveal information about the 8473 respective sender's software systems. In theory, this can make it 8474 easier for an attacker to exploit known security holes; in practice, 8475 attackers tend to try all potential holes regardless of the apparent 8476 software versions being used. 8478 Proxies that serve as a portal through a network firewall ought to 8479 take special precautions regarding the transfer of header information 8480 that might identify hosts behind the firewall. The Via header field 8481 allows intermediaries to replace sensitive machine names with 8482 pseudonyms. 8484 17.12. Browser Fingerprinting 8486 Browser fingerprinting is a set of techniques for identifying a 8487 specific user agent over time through its unique set of 8488 characteristics. These characteristics might include information 8489 related to its TCP behavior, feature capabilities, and scripting 8490 environment, though of particular interest here is the set of unique 8491 characteristics that might be communicated via HTTP. Fingerprinting 8492 is considered a privacy concern because it enables tracking of a user 8493 agent's behavior over time ([Bujlow]) without the corresponding 8494 controls that the user might have over other forms of data collection 8495 (e.g., cookies). Many general-purpose user agents (i.e., Web 8496 browsers) have taken steps to reduce their fingerprints. 8498 There are a number of request header fields that might reveal 8499 information to servers that is sufficiently unique to enable 8500 fingerprinting. The From header field is the most obvious, though it 8501 is expected that From will only be sent when self-identification is 8502 desired by the user. Likewise, Cookie header fields are deliberately 8503 designed to enable re-identification, so fingerprinting concerns only 8504 apply to situations where cookies are disabled or restricted by the 8505 user agent's configuration. 8507 The User-Agent header field might contain enough information to 8508 uniquely identify a specific device, usually when combined with other 8509 characteristics, particularly if the user agent sends excessive 8510 details about the user's system or extensions. However, the source 8511 of unique information that is least expected by users is proactive 8512 negotiation (Section 12.1), including the Accept, Accept-Charset, 8513 Accept-Encoding, and Accept-Language header fields. 8515 In addition to the fingerprinting concern, detailed use of the 8516 Accept-Language header field can reveal information the user might 8517 consider to be of a private nature. For example, understanding a 8518 given language set might be strongly correlated to membership in a 8519 particular ethnic group. An approach that limits such loss of 8520 privacy would be for a user agent to omit the sending of Accept- 8521 Language except for sites that have been whitelisted, perhaps via 8522 interaction after detecting a Vary header field that indicates 8523 language negotiation might be useful. 8525 In environments where proxies are used to enhance privacy, user 8526 agents ought to be conservative in sending proactive negotiation 8527 header fields. General-purpose user agents that provide a high 8528 degree of header field configurability ought to inform users about 8529 the loss of privacy that might result if too much detail is provided. 8530 As an extreme privacy measure, proxies could filter the proactive 8531 negotiation header fields in relayed requests. 8533 17.13. Validator Retention 8535 The validators defined by this specification are not intended to 8536 ensure the validity of a representation, guard against malicious 8537 changes, or detect on-path attacks. At best, they enable more 8538 efficient cache updates and optimistic concurrent writes when all 8539 participants are behaving nicely. At worst, the conditions will fail 8540 and the client will receive a response that is no more harmful than 8541 an HTTP exchange without conditional requests. 8543 An entity-tag can be abused in ways that create privacy risks. For 8544 example, a site might deliberately construct a semantically invalid 8545 entity-tag that is unique to the user or user agent, send it in a 8546 cacheable response with a long freshness time, and then read that 8547 entity-tag in later conditional requests as a means of re-identifying 8548 that user or user agent. Such an identifying tag would become a 8549 persistent identifier for as long as the user agent retained the 8550 original cache entry. User agents that cache representations ought 8551 to ensure that the cache is cleared or replaced whenever the user 8552 performs privacy-maintaining actions, such as clearing stored cookies 8553 or changing to a private browsing mode. 8555 17.14. Denial-of-Service Attacks Using Range 8557 Unconstrained multiple range requests are susceptible to denial-of- 8558 service attacks because the effort required to request many 8559 overlapping ranges of the same data is tiny compared to the time, 8560 memory, and bandwidth consumed by attempting to serve the requested 8561 data in many parts. Servers ought to ignore, coalesce, or reject 8562 egregious range requests, such as requests for more than two 8563 overlapping ranges or for many small ranges in a single set, 8564 particularly when the ranges are requested out of order for no 8565 apparent reason. Multipart range requests are not designed to 8566 support random access. 8568 17.15. Authentication Considerations 8570 Everything about the topic of HTTP authentication is a security 8571 consideration, so the list of considerations below is not exhaustive. 8572 Furthermore, it is limited to security considerations regarding the 8573 authentication framework, in general, rather than discussing all of 8574 the potential considerations for specific authentication schemes 8575 (which ought to be documented in the specifications that define those 8576 schemes). Various organizations maintain topical information and 8577 links to current research on Web application security (e.g., 8578 [OWASP]), including common pitfalls for implementing and using the 8579 authentication schemes found in practice. 8581 17.15.1. Confidentiality of Credentials 8583 The HTTP authentication framework does not define a single mechanism 8584 for maintaining the confidentiality of credentials; instead, each 8585 authentication scheme defines how the credentials are encoded prior 8586 to transmission. While this provides flexibility for the development 8587 of future authentication schemes, it is inadequate for the protection 8588 of existing schemes that provide no confidentiality on their own, or 8589 that do not sufficiently protect against replay attacks. 8590 Furthermore, if the server expects credentials that are specific to 8591 each individual user, the exchange of those credentials will have the 8592 effect of identifying that user even if the content within 8593 credentials remains confidential. 8595 HTTP depends on the security properties of the underlying transport- 8596 or session-level connection to provide confidential transmission of 8597 fields. Services that depend on individual user authentication 8598 require a secured connection prior to exchanging credentials 8599 (Section 4.2.2). 8601 17.15.2. Credentials and Idle Clients 8603 Existing HTTP clients and user agents typically retain authentication 8604 information indefinitely. HTTP does not provide a mechanism for the 8605 origin server to direct clients to discard these cached credentials, 8606 since the protocol has no awareness of how credentials are obtained 8607 or managed by the user agent. The mechanisms for expiring or 8608 revoking credentials can be specified as part of an authentication 8609 scheme definition. 8611 Circumstances under which credential caching can interfere with the 8612 application's security model include but are not limited to: 8614 o Clients that have been idle for an extended period, following 8615 which the server might wish to cause the client to re-prompt the 8616 user for credentials. 8618 o Applications that include a session termination indication (such 8619 as a "logout" or "commit" button on a page) after which the server 8620 side of the application "knows" that there is no further reason 8621 for the client to retain the credentials. 8623 User agents that cache credentials are encouraged to provide a 8624 readily accessible mechanism for discarding cached credentials under 8625 user control. 8627 17.15.3. Protection Spaces 8629 Authentication schemes that solely rely on the "realm" mechanism for 8630 establishing a protection space will expose credentials to all 8631 resources on an origin server. Clients that have successfully made 8632 authenticated requests with a resource can use the same 8633 authentication credentials for other resources on the same origin 8634 server. This makes it possible for a different resource to harvest 8635 authentication credentials for other resources. 8637 This is of particular concern when an origin server hosts resources 8638 for multiple parties under the same origin (Section 11.5). Possible 8639 mitigation strategies include restricting direct access to 8640 authentication credentials (i.e., not making the content of the 8641 Authorization request header field available), and separating 8642 protection spaces by using a different host name (or port number) for 8643 each party. 8645 17.15.4. Additional Response Fields 8647 Adding information to responses that are sent over an unencrypted 8648 channel can affect security and privacy. The presence of the 8649 Authentication-Info and Proxy-Authentication-Info header fields alone 8650 indicates that HTTP authentication is in use. Additional information 8651 could be exposed by the contents of the authentication-scheme 8652 specific parameters; this will have to be considered in the 8653 definitions of these schemes. 8655 18. IANA Considerations 8657 The change controller for the following registrations is: "IETF 8658 (iesg@ietf.org) - Internet Engineering Task Force". 8660 18.1. URI Scheme Registration 8662 Please update the registry of URI Schemes [BCP35] at 8663 with the permanent 8664 schemes listed in the table in Section 4.2. 8666 18.2. Method Registration 8668 Please update the "Hypertext Transfer Protocol (HTTP) Method 8669 Registry" at with the 8670 registration procedure of Section 16.1.1 and the method names 8671 summarized in the following table. 8673 --------- ------ ------------ ------- 8674 Method Safe Idempotent Ref. 8675 --------- ------ ------------ ------- 8676 CONNECT no no 9.3.6 8677 DELETE no yes 9.3.5 8678 GET yes yes 9.3.1 8679 HEAD yes yes 9.3.2 8680 OPTIONS yes yes 9.3.7 8681 POST no no 9.3.3 8682 PUT no yes 9.3.4 8683 TRACE yes yes 9.3.8 8684 * no no 18.2 8685 --------- ------ ------------ ------- 8687 Table 7 8689 The method name "*" is reserved, since using that name as HTTP method 8690 name might conflict with special semantics in fields such as "Access- 8691 Control-Request-Method". 8693 18.3. Status Code Registration 8695 Please update the "Hypertext Transfer Protocol (HTTP) Status Code 8696 Registry" at 8697 with the registration procedure of Section 16.2.1 and the status code 8698 values summarized in the following table. 8700 ------- ------------------------------- --------- 8701 Value Description Ref. 8702 ------- ------------------------------- --------- 8703 100 Continue 15.2.1 8704 101 Switching Protocols 15.2.2 8705 200 OK 15.3.1 8706 201 Created 15.3.2 8707 202 Accepted 15.3.3 8708 203 Non-Authoritative Information 15.3.4 8709 204 No Content 15.3.5 8710 205 Reset Content 15.3.6 8711 206 Partial Content 15.3.7 8712 300 Multiple Choices 15.4.1 8713 301 Moved Permanently 15.4.2 8714 302 Found 15.4.3 8715 303 See Other 15.4.4 8716 304 Not Modified 15.4.5 8717 305 Use Proxy 15.4.6 8718 306 (Unused) 15.4.7 8719 307 Temporary Redirect 15.4.8 8720 308 Permanent Redirect 15.4.9 8721 400 Bad Request 15.5.1 8722 401 Unauthorized 15.5.2 8723 402 Payment Required 15.5.3 8724 403 Forbidden 15.5.4 8725 404 Not Found 15.5.5 8726 405 Method Not Allowed 15.5.6 8727 406 Not Acceptable 15.5.7 8728 407 Proxy Authentication Required 15.5.8 8729 408 Request Timeout 15.5.9 8730 409 Conflict 15.5.10 8731 410 Gone 15.5.11 8732 411 Length Required 15.5.12 8733 412 Precondition Failed 15.5.13 8734 413 Content Too Large 15.5.14 8735 414 URI Too Long 15.5.15 8736 415 Unsupported Media Type 15.5.16 8737 416 Range Not Satisfiable 15.5.17 8738 417 Expectation Failed 15.5.18 8739 418 (Unused) 15.5.19 8740 421 Misdirected Request 15.5.20 8741 422 Unprocessable Content 15.5.21 8742 426 Upgrade Required 15.5.22 8743 500 Internal Server Error 15.6.1 8744 501 Not Implemented 15.6.2 8745 502 Bad Gateway 15.6.3 8746 503 Service Unavailable 15.6.4 8747 504 Gateway Timeout 15.6.5 8748 505 HTTP Version Not Supported 15.6.6 8749 ------- ------------------------------- --------- 8751 Table 8 8753 18.4. Field Name Registration 8755 This specification updates the HTTP related aspects of the existing 8756 registration procedures for message header fields defined in 8757 [RFC3864]. It defines both a new registration procedure and moves 8758 HTTP field definitions into a separate registry. 8760 Please create a new registry as outlined in Section 16.3.1. 8762 After creating the registry, all entries in the Permanent and 8763 Provisional Message Header Registries with the protocol 'http' are to 8764 be moved to it, with the following changes applied: 8766 1. The 'Applicable Protocol' field is to be omitted. 8768 2. Entries with a status of 'standard', 'experimental', 'reserved', 8769 or 'informational' are to have a status of 'permanent'. 8771 3. Provisional entries without a status are to have a status of 8772 'provisional'. 8774 4. Permanent entries without a status (after confirmation that the 8775 registration document did not define one) will have a status of 8776 'provisional'. The Expert(s) can choose to update their status 8777 if there is evidence that another is more appropriate. 8779 Please annotate the Permanent and Provisional Message Header 8780 registries to indicate that HTTP field name registrations have moved, 8781 with an appropriate link. 8783 After that is complete, please update the new registry with the field 8784 names listed in the following table. 8786 --------------------------- ------------ -------- ------------ 8787 Field Name Status Ref. Comments 8788 --------------------------- ------------ -------- ------------ 8789 Accept standard 12.5.1 8790 Accept-Charset deprecated 12.5.2 8791 Accept-Encoding standard 12.5.3 8792 Accept-Language standard 12.5.4 8793 Accept-Ranges standard 14.3 8794 Allow standard 10.2.1 8795 Authentication-Info standard 11.6.3 8796 Authorization standard 11.6.2 8797 Connection standard 7.6.1 8798 Content-Encoding standard 8.4 8799 Content-Language standard 8.5 8800 Content-Length standard 8.6 8801 Content-Location standard 8.7 8802 Content-Range standard 14.4 8803 Content-Type standard 8.3 8804 Date standard 10.2.2 8805 ETag standard 8.8.3 8806 Expect standard 10.1.1 8807 From standard 10.1.2 8808 Host standard 7.2 8809 If-Match standard 13.1.1 8810 If-Modified-Since standard 13.1.3 8811 If-None-Match standard 13.1.2 8812 If-Range standard 13.1.5 8813 If-Unmodified-Since standard 13.1.4 8814 Last-Modified standard 8.8.2 8815 Location standard 10.2.3 8816 Max-Forwards standard 7.6.2 8817 Proxy-Authenticate standard 11.7.1 8818 Proxy-Authentication-Info standard 11.7.3 8819 Proxy-Authorization standard 11.7.2 8820 Range standard 14.2 8821 Referer standard 10.1.3 8822 Retry-After standard 10.2.4 8823 Server standard 10.2.5 8824 TE standard 10.1.4 8825 Trailer standard 10.1.5 8826 Upgrade standard 7.8 8827 User-Agent standard 10.1.6 8828 Vary standard 12.5.5 8829 Via standard 7.6.3 8830 WWW-Authenticate standard 11.6.1 8831 * standard 12.5.5 (reserved) 8832 --------------------------- ------------ -------- ------------ 8834 Table 9 8836 The field name "*" is reserved, since using that name as an HTTP 8837 header field might conflict with its special semantics in the Vary 8838 header field (Section 12.5.5). 8840 Finally, please update the "Content-MD5" entry in the new registry to 8841 have a status of 'obsoleted' with references to Section 14.15 of 8842 [RFC2616] (for the definition of the header field) and Appendix B of 8843 [RFC7231] (which removed the field definition from the updated 8844 specification). 8846 18.5. Authentication Scheme Registration 8848 Please update the "Hypertext Transfer Protocol (HTTP) Authentication 8849 Scheme Registry" at with the registration procedure of Section 16.4.1. No 8851 authentication schemes are defined in this document. 8853 18.6. Content Coding Registration 8855 Please update the "HTTP Content Coding Registry" at 8856 with the 8857 registration procedure of Section 16.6.1 and the content coding names 8858 summarized in the table below. 8860 ------------ ------------------------------------------- --------- 8861 Name Description Ref. 8862 ------------ ------------------------------------------- --------- 8863 compress UNIX "compress" data format [Welch] 8.4.1.1 8864 deflate "deflate" compressed data ([RFC1951]) 8.4.1.2 8865 inside the "zlib" data format ([RFC1950]) 8866 gzip GZIP file format [RFC1952] 8.4.1.3 8867 identity Reserved 12.5.3 8868 x-compress Deprecated (alias for compress) 8.4.1.1 8869 x-gzip Deprecated (alias for gzip) 8.4.1.3 8870 ------------ ------------------------------------------- --------- 8872 Table 10 8874 18.7. Range Unit Registration 8876 Please update the "HTTP Range Unit Registry" at 8877 with the 8878 registration procedure of Section 16.5.1 and the range unit names 8879 summarized in the table below. 8881 ----------------- ---------------------------------- -------- 8882 Range Unit Name Description Ref. 8883 ----------------- ---------------------------------- -------- 8884 bytes a range of octets 14.1.2 8885 none reserved as keyword to indicate 14.3 8886 range requests are not supported 8887 ----------------- ---------------------------------- -------- 8889 Table 11 8891 18.8. Media Type Registration 8893 Please update the "Media Types" registry at 8894 with the registration 8895 information in Section 14.6 for the media type "multipart/ 8896 byteranges". 8898 18.9. Port Registration 8900 Please update the "Service Name and Transport Protocol Port Number" 8901 registry at for the services on ports 80 and 443 that use UDP or TCP 8903 to: 8905 1. use this document as "Reference", and 8906 2. when currently unspecified, set "Assignee" to "IESG" and 8907 "Contact" to "IETF_Chair". 8909 18.10. Upgrade Token Registration 8911 Please update the "Hypertext Transfer Protocol (HTTP) Upgrade Token 8912 Registry" at 8913 with the registration procedure of Section 16.7 and the upgrade token 8914 names summarized in the following table. 8916 ------ ------------------- ------------------------- ------ 8917 Name Description Expected Version Tokens Ref. 8918 ------ ------------------- ------------------------- ------ 8919 HTTP Hypertext any DIGIT.DIGIT (e.g, 2.5 8920 Transfer Protocol "2.0") 8921 ------ ------------------- ------------------------- ------ 8923 Table 12 8925 19. References 8927 19.1. Normative References 8929 [Caching] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 8930 Ed., "HTTP Caching", Work in Progress, Internet-Draft, 8931 draft-ietf-httpbis-cache-14, January 13, 2021, 8932 . 8934 [Messaging] 8935 Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 8936 Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft- 8937 ietf-httpbis-messaging-14, January 13, 2021, 8938 . 8941 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 8942 RFC 793, DOI 10.17487/RFC0793, September 1981, 8943 . 8945 [RFC1950] Deutsch, L.P. and J-L. Gailly, "ZLIB Compressed Data 8946 Format Specification version 3.3", RFC 1950, 8947 DOI 10.17487/RFC1950, May 1996, 8948 . 8950 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 8951 version 1.3", RFC 1951, DOI 10.17487/RFC1951, May 1996, 8952 . 8954 [RFC1952] Deutsch, P., Gailly, J-L., Adler, M., Deutsch, L.P., and 8955 G. Randers-Pehrson, "GZIP file format specification 8956 version 4.3", RFC 1952, DOI 10.17487/RFC1952, May 1996, 8957 . 8959 [RFC2045] Freed, N. and N.S. Borenstein, "Multipurpose Internet Mail 8960 Extensions (MIME) Part One: Format of Internet Message 8961 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 8962 . 8964 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 8965 Extensions (MIME) Part Two: Media Types", RFC 2046, 8966 DOI 10.17487/RFC2046, November 1996, 8967 . 8969 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 8970 Requirement Levels", BCP 14, RFC 2119, 8971 DOI 10.17487/RFC2119, March 1997, 8972 . 8974 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 8975 Resource Identifier (URI): Generic Syntax", STD 66, 8976 RFC 3986, DOI 10.17487/RFC3986, January 2005, 8977 . 8979 [RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of Language 8980 Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 8981 2006, . 8983 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 8984 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 8985 . 8987 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 8988 Specifications: ABNF", STD 68, RFC 5234, 8989 DOI 10.17487/RFC5234, January 2008, 8990 . 8992 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 8993 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 8994 September 2009, . 8996 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 8997 Verification of Domain-Based Application Service Identity 8998 within Internet Public Key Infrastructure Using X.509 8999 (PKIX) Certificates in the Context of Transport Layer 9000 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 9001 2011, . 9003 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in 9004 Internationalization in the IETF", BCP 166, RFC 6365, 9005 DOI 10.17487/RFC6365, September 2011, 9006 . 9008 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 9009 RFC 7405, DOI 10.17487/RFC7405, December 2014, 9010 . 9012 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 9013 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 9014 May 2017, . 9016 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 9017 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 9018 . 9020 [USASCII] American National Standards Institute, "Coded Character 9021 Set -- 7-bit American Standard Code for Information 9022 Interchange", ANSI X3.4, 1986. 9024 [Welch] Welch, T. A., "A Technique for High-Performance Data 9025 Compression", IEEE Computer 17(6), 9026 DOI 10.1109/MC.1984.1659158, June 1984, 9027 . 9029 19.2. Informative References 9031 [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type 9032 Specifications and Registration Procedures", BCP 13, 9033 RFC 6838, January 2013, 9034 . 9036 [BCP178] Saint-Andre, P., Crocker, D., and M. Nottingham, 9037 "Deprecating the "X-" Prefix and Similar Constructs in 9038 Application Protocols", BCP 178, RFC 6648, June 2012, 9039 . 9041 [BCP35] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 9042 and Registration Procedures for URI Schemes", BCP 35, 9043 RFC 7595, June 2015, 9044 . 9046 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the 9047 CRIME Attack", July 2013, 9048 . 9051 [Bujlow] Bujlow, T., Carela-Espanol, V., Sole-Pareta, J., and P. 9052 Barlet-Ros, "A Survey on Web Tracking: Mechanisms, 9053 Implications, and Defenses", 9054 DOI 10.1109/JPROC.2016.2637878, Proceedings of the 9055 IEEE 105(8), August 2017, 9056 . 9058 [Err1912] RFC Errata, Erratum ID 1912, RFC 2978, 9059 . 9061 [Err5433] RFC Errata, Erratum ID 5433, RFC 2978, 9062 . 9064 [Georgiev] Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh, 9065 D., and V. Shmatikov, "The Most Dangerous Code in the 9066 World: Validating SSL Certificates in Non-browser 9067 Software", DOI 10.1145/2382196.2382204, In Proceedings of 9068 the 2012 ACM Conference on Computer and Communications 9069 Security (CCS '12), pp. 38-49, October 2012, 9070 . 9072 [HTTP3] Bishop, M., "Hypertext Transfer Protocol Version 3 9073 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 9074 quic-http-33, December 15, 2020, 9075 . 9077 [ISO-8859-1] 9078 International Organization for Standardization, 9079 "Information technology -- 8-bit single-byte coded graphic 9080 character sets -- Part 1: Latin alphabet No. 1", ISO/ 9081 IEC 8859-1:1998, 1998. 9083 [Kri2001] Kristol, D., "HTTP Cookies: Standards, Privacy, and 9084 Politics", ACM Transactions on Internet Technology 1(2), 9085 November 2001, . 9087 [OWASP] van der Stock, A., Ed., "A Guide to Building Secure Web 9088 Applications and Web Services", The Open Web Application 9089 Security Project (OWASP) 2.0.1, July 27, 2005, 9090 . 9092 [REST] Fielding, R.T., "Architectural Styles and the Design of 9093 Network-based Software Architectures", 9094 Doctoral Dissertation, University of California, Irvine, 9095 September 2000, 9096 . 9098 [RFC1919] Chatel, M., "Classical versus Transparent IP Proxies", 9099 RFC 1919, DOI 10.17487/RFC1919, March 1996, 9100 . 9102 [RFC1945] Berners-Lee, T., Fielding, R.T., and H.F. Nielsen, 9103 "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945, 9104 DOI 10.17487/RFC1945, May 1996, 9105 . 9107 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 9108 Part Three: Message Header Extensions for Non-ASCII Text", 9109 RFC 2047, DOI 10.17487/RFC2047, November 1996, 9110 . 9112 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T. 9113 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 9114 RFC 2068, DOI 10.17487/RFC2068, January 1997, 9115 . 9117 [RFC2145] Mogul, J.C., Fielding, R.T., Gettys, J., and H.F. Nielsen, 9118 "Use and Interpretation of HTTP Version Numbers", 9119 RFC 2145, DOI 10.17487/RFC2145, May 1997, 9120 . 9122 [RFC2295] Holtman, K. and A.H. Mutz, "Transparent Content 9123 Negotiation in HTTP", RFC 2295, DOI 10.17487/RFC2295, 9124 March 1998, . 9126 [RFC2324] Masinter, L., "Hyper Text Coffee Pot Control Protocol 9127 (HTCPCP/1.0)", RFC 2324, DOI 10.17487/RFC2324, April 1, 9128 1998, . 9130 [RFC2557] Palme, F., Hopmann, A., Shelness, N., and E. Stefferud, 9131 "MIME Encapsulation of Aggregate Documents, such as HTML 9132 (MHTML)", RFC 2557, DOI 10.17487/RFC2557, March 1999, 9133 . 9135 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 9136 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 9137 Transfer Protocol -- HTTP/1.1", RFC 2616, 9138 DOI 10.17487/RFC2616, June 1999, 9139 . 9141 [RFC2617] Franks, J., Hallam-Baker, P.M., Hostetler, J.L., Lawrence, 9142 S.D., Leach, P.J., Luotonen, A., and L. Stewart, "HTTP 9143 Authentication: Basic and Digest Access Authentication", 9144 RFC 2617, DOI 10.17487/RFC2617, June 1999, 9145 . 9147 [RFC2774] Frystyk, H., Leach, P., and S. Lawrence, "An HTTP 9148 Extension Framework", RFC 2774, DOI 10.17487/RFC2774, 9149 February 2000, . 9151 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 9152 DOI 10.17487/RFC2818, May 2000, 9153 . 9155 [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration 9156 Procedures", BCP 19, RFC 2978, DOI 10.17487/RFC2978, 9157 October 2000, . 9159 [RFC3040] Cooper, I., Melve, I., and G. Tomlinson, "Internet Web 9160 Replication and Caching Taxonomy", RFC 3040, 9161 DOI 10.17487/RFC3040, January 2001, 9162 . 9164 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 9165 Procedures for Message Header Fields", BCP 90, RFC 3864, 9166 DOI 10.17487/RFC3864, September 2004, 9167 . 9169 [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S. 9170 Rose, "DNS Security Introduction and Requirements", 9171 RFC 4033, DOI 10.17487/RFC4033, March 2005, 9172 . 9174 [RFC4559] Jaganathan, K., Zhu, L., and J. Brezak, "SPNEGO-based 9175 Kerberos and NTLM HTTP Authentication in Microsoft 9176 Windows", RFC 4559, DOI 10.17487/RFC4559, June 2006, 9177 . 9179 [RFC4918] Dusseault, L.M., Ed., "HTTP Extensions for Web Distributed 9180 Authoring and Versioning (WebDAV)", RFC 4918, 9181 DOI 10.17487/RFC4918, June 2007, 9182 . 9184 [RFC5322] Resnick, P., "Internet Message Format", RFC 5322, 9185 DOI 10.17487/RFC5322, October 2008, 9186 . 9188 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 9189 RFC 5789, DOI 10.17487/RFC5789, March 2010, 9190 . 9192 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 9193 "Network Time Protocol Version 4: Protocol and Algorithms 9194 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 9195 . 9197 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 9198 DOI 10.17487/RFC6265, April 2011, 9199 . 9201 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 9202 DOI 10.17487/RFC6454, December 2011, 9203 . 9205 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 9206 Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, 9207 . 9209 [RFC7230] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9210 Transfer Protocol (HTTP/1.1): Message Syntax and Routing", 9211 RFC 7230, DOI 10.17487/RFC7230, June 2014, 9212 . 9214 [RFC7231] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9215 Transfer Protocol (HTTP/1.1): Semantics and Content", 9216 RFC 7231, DOI 10.17487/RFC7231, June 2014, 9217 . 9219 [RFC7232] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9220 Transfer Protocol (HTTP/1.1): Conditional Requests", 9221 RFC 7232, DOI 10.17487/RFC7232, June 2014, 9222 . 9224 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. F. Reschke, Ed., 9225 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 9226 RFC 7233, DOI 10.17487/RFC7233, June 2014, 9227 . 9229 [RFC7235] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9230 Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, 9231 DOI 10.17487/RFC7235, June 2014, 9232 . 9234 [RFC7538] Reschke, J. F., "The Hypertext Transfer Protocol Status 9235 Code 308 (Permanent Redirect)", RFC 7538, 9236 DOI 10.17487/RFC7538, April 2015, 9237 . 9239 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 9240 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 9241 DOI 10.17487/RFC7540, May 2015, 9242 . 9244 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 9245 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 9246 . 9248 [RFC7578] Masinter, L., "Returning Values from Forms: multipart/ 9249 form-data", RFC 7578, DOI 10.17487/RFC7578, July 2015, 9250 . 9252 [RFC7615] Reschke, J. F., "HTTP Authentication-Info and Proxy- 9253 Authentication-Info Response Header Fields", RFC 7615, 9254 DOI 10.17487/RFC7615, September 2015, 9255 . 9257 [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP 9258 Digest Access Authentication", RFC 7616, 9259 DOI 10.17487/RFC7616, September 2015, 9260 . 9262 [RFC7617] Reschke, J. F., "The 'Basic' HTTP Authentication Scheme", 9263 RFC 7617, DOI 10.17487/RFC7617, September 2015, 9264 . 9266 [RFC7694] Reschke, J. F., "Hypertext Transfer Protocol (HTTP) 9267 Client-Initiated Content-Encoding", RFC 7694, 9268 DOI 10.17487/RFC7694, November 2015, 9269 . 9271 [RFC7838] Nottingham, M., McManus, P., and J. Reschke, "HTTP 9272 Alternative Services", RFC 7838, DOI 10.17487/RFC7838, 9273 April 2016, . 9275 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 9276 Writing an IANA Considerations Section in RFCs", BCP 26, 9277 RFC 8126, DOI 10.17487/RFC8126, June 2017, 9278 . 9280 [RFC8187] Reschke, J. F., "Indicating Character Encoding and 9281 Language for HTTP Header Field Parameters", RFC 8187, 9282 DOI 10.17487/RFC8187, September 2017, 9283 . 9285 [RFC8246] McManus, P., "HTTP Immutable Responses", RFC 8246, 9286 DOI 10.17487/RFC8246, September 2017, 9287 . 9289 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 9290 DOI 10.17487/RFC8288, October 2017, 9291 . 9293 [RFC8336] Nottingham, M. and E. Nygren, "The ORIGIN HTTP/2 Frame", 9294 RFC 8336, DOI 10.17487/RFC8336, March 2018, 9295 . 9297 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 9298 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 9299 . 9301 [RFCSTRF] Nottingham, M. and P-H. Kamp, "Structured Field Values for 9302 HTTP", Work in Progress, Internet-Draft, draft-ietf- 9303 httpbis-header-structure-19, June 2020, 9304 . 9307 [Sniffing] WHATWG, "MIME Sniffing", 9308 . 9310 Appendix A. Collected ABNF 9312 In the collected ABNF below, list rules are expanded as per 9313 Section 5.6.1.1. 9315 Accept = [ ( media-range [ weight ] ) *( OWS "," OWS ( media-range [ 9316 weight ] ) ) ] 9317 Accept-Charset = [ ( ( charset / "*" ) [ weight ] ) *( OWS "," OWS ( 9318 ( charset / "*" ) [ weight ] ) ) ] 9319 Accept-Encoding = [ ( codings [ weight ] ) *( OWS "," OWS ( codings [ 9320 weight ] ) ) ] 9321 Accept-Language = [ ( language-range [ weight ] ) *( OWS "," OWS ( 9322 language-range [ weight ] ) ) ] 9323 Accept-Ranges = acceptable-ranges 9324 Allow = [ method *( OWS "," OWS method ) ] 9325 Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) ] 9326 Authorization = credentials 9328 BWS = OWS 9330 Connection = [ connection-option *( OWS "," OWS connection-option ) 9331 ] 9332 Content-Encoding = [ content-coding *( OWS "," OWS content-coding ) 9333 ] 9334 Content-Language = [ language-tag *( OWS "," OWS language-tag ) ] 9335 Content-Length = 1*DIGIT 9336 Content-Location = absolute-URI / partial-URI 9337 Content-Range = range-unit SP ( range-resp / unsatisfied-range ) 9338 Content-Type = media-type 9340 Date = HTTP-date 9342 ETag = entity-tag 9343 Expect = [ expectation *( OWS "," OWS expectation ) ] 9345 From = mailbox 9347 GMT = %x47.4D.54 ; GMT 9349 HTTP-date = IMF-fixdate / obs-date 9350 Host = uri-host [ ":" port ] 9352 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 9353 If-Match = "*" / [ entity-tag *( OWS "," OWS entity-tag ) ] 9354 If-Modified-Since = HTTP-date 9355 If-None-Match = "*" / [ entity-tag *( OWS "," OWS entity-tag ) ] 9356 If-Range = entity-tag / HTTP-date 9357 If-Unmodified-Since = HTTP-date 9359 Last-Modified = HTTP-date 9360 Location = URI-reference 9362 Max-Forwards = 1*DIGIT 9364 OWS = *( SP / HTAB ) 9366 Proxy-Authenticate = [ challenge *( OWS "," OWS challenge ) ] 9367 Proxy-Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) 9368 ] 9369 Proxy-Authorization = credentials 9371 RWS = 1*( SP / HTAB ) 9372 Range = ranges-specifier 9373 Referer = absolute-URI / partial-URI 9374 Retry-After = HTTP-date / delay-seconds 9376 Server = product *( RWS ( product / comment ) ) 9378 TE = [ t-codings *( OWS "," OWS t-codings ) ] 9379 Trailer = [ field-name *( OWS "," OWS field-name ) ] 9380 URI-reference = 9381 Upgrade = [ protocol *( OWS "," OWS protocol ) ] 9382 User-Agent = product *( RWS ( product / comment ) ) 9384 Vary = [ ( "*" / field-name ) *( OWS "," OWS ( "*" / field-name ) ) 9385 ] 9386 Via = [ ( received-protocol RWS received-by [ RWS comment ] ) *( OWS 9387 "," OWS ( received-protocol RWS received-by [ RWS comment ] ) ) ] 9389 WWW-Authenticate = [ challenge *( OWS "," OWS challenge ) ] 9391 absolute-URI = 9392 absolute-path = 1*( "/" segment ) 9393 acceptable-ranges = ( range-unit *( OWS "," OWS range-unit ) ) / 9394 "none" 9395 asctime-date = day-name SP date3 SP time-of-day SP year 9396 auth-param = token BWS "=" BWS ( token / quoted-string ) 9397 auth-scheme = token 9398 authority = 9400 challenge = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS "," 9401 OWS auth-param ) ] ) ] 9402 charset = token 9403 codings = content-coding / "identity" / "*" 9404 comment = "(" *( ctext / quoted-pair / comment ) ")" 9405 complete-length = 1*DIGIT 9406 connection-option = token 9407 content-coding = token 9408 credentials = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS "," 9409 OWS auth-param ) ] ) ] 9410 ctext = HTAB / SP / %x21-27 ; '!'-''' 9411 / %x2A-5B ; '*'-'[' 9412 / %x5D-7E ; ']'-'~' 9413 / obs-text 9415 date1 = day SP month SP year 9416 date2 = day "-" month "-" 2DIGIT 9417 date3 = month SP ( 2DIGIT / ( SP DIGIT ) ) 9418 day = 2DIGIT 9419 day-name = %x4D.6F.6E ; Mon 9420 / %x54.75.65 ; Tue 9421 / %x57.65.64 ; Wed 9422 / %x54.68.75 ; Thu 9423 / %x46.72.69 ; Fri 9424 / %x53.61.74 ; Sat 9425 / %x53.75.6E ; Sun 9426 day-name-l = %x4D.6F.6E.64.61.79 ; Monday 9427 / %x54.75.65.73.64.61.79 ; Tuesday 9428 / %x57.65.64.6E.65.73.64.61.79 ; Wednesday 9429 / %x54.68.75.72.73.64.61.79 ; Thursday 9430 / %x46.72.69.64.61.79 ; Friday 9431 / %x53.61.74.75.72.64.61.79 ; Saturday 9432 / %x53.75.6E.64.61.79 ; Sunday 9433 delay-seconds = 1*DIGIT 9435 entity-tag = [ weak ] opaque-tag 9436 etagc = "!" / %x23-7E ; '#'-'~' 9437 / obs-text 9438 expectation = token [ "=" ( token / quoted-string ) parameters ] 9440 field-content = field-vchar [ 1*( SP / HTAB / field-vchar ) 9441 field-vchar ] 9442 field-name = token 9443 field-value = *field-content 9444 field-vchar = VCHAR / obs-text 9445 first-pos = 1*DIGIT 9447 hour = 2DIGIT 9448 http-URI = "http://" authority path-abempty [ "?" query ] 9449 https-URI = "https://" authority path-abempty [ "?" query ] 9451 incl-range = first-pos "-" last-pos 9452 int-range = first-pos "-" [ last-pos ] 9454 language-range = 9455 language-tag = 9456 last-pos = 1*DIGIT 9458 mailbox = 9459 media-range = ( "*/*" / ( type "/*" ) / ( type "/" subtype ) ) 9460 parameters 9461 media-type = type "/" subtype parameters 9462 method = token 9463 minute = 2DIGIT 9464 month = %x4A.61.6E ; Jan 9465 / %x46.65.62 ; Feb 9466 / %x4D.61.72 ; Mar 9467 / %x41.70.72 ; Apr 9468 / %x4D.61.79 ; May 9469 / %x4A.75.6E ; Jun 9470 / %x4A.75.6C ; Jul 9471 / %x41.75.67 ; Aug 9472 / %x53.65.70 ; Sep 9473 / %x4F.63.74 ; Oct 9474 / %x4E.6F.76 ; Nov 9475 / %x44.65.63 ; Dec 9477 obs-date = rfc850-date / asctime-date 9478 obs-text = %x80-FF 9479 opaque-tag = DQUOTE *etagc DQUOTE 9480 other-range = 1*( %x21-2B ; '!'-'+' 9481 / %x2D-7E ; '-'-'~' 9482 ) 9484 parameter = parameter-name "=" parameter-value 9485 parameter-name = token 9486 parameter-value = ( token / quoted-string ) 9487 parameters = *( OWS ";" OWS [ parameter ] ) 9488 partial-URI = relative-part [ "?" query ] 9489 path-abempty = 9490 port = 9491 product = token [ "/" product-version ] 9492 product-version = token 9493 protocol = protocol-name [ "/" protocol-version ] 9494 protocol-name = token 9495 protocol-version = token 9496 pseudonym = token 9498 qdtext = HTAB / SP / "!" / %x23-5B ; '#'-'[' 9499 / %x5D-7E ; ']'-'~' 9500 / obs-text 9501 query = 9502 quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) 9503 quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE 9504 qvalue = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] ) 9506 range-resp = incl-range "/" ( complete-length / "*" ) 9507 range-set = range-spec *( OWS "," OWS range-spec ) 9508 range-spec = int-range / suffix-range / other-range 9509 range-unit = token 9510 ranges-specifier = range-unit "=" range-set 9511 received-by = pseudonym [ ":" port ] 9512 received-protocol = [ protocol-name "/" ] protocol-version 9513 relative-part = 9514 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 9516 second = 2DIGIT 9517 segment = 9518 subtype = token 9519 suffix-length = 1*DIGIT 9520 suffix-range = "-" suffix-length 9522 t-codings = "trailers" / ( transfer-coding [ weight ] ) 9523 tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / 9524 "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA 9526 time-of-day = hour ":" minute ":" second 9527 token = 1*tchar 9528 token68 = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) 9529 *"=" 9530 transfer-coding = token *( OWS ";" OWS transfer-parameter ) 9531 transfer-parameter = token BWS "=" BWS ( token / quoted-string ) 9532 type = token 9534 unsatisfied-range = "*/" complete-length 9535 uri-host = 9537 weak = %x57.2F ; W/ 9538 weight = OWS ";" OWS "q=" qvalue 9540 year = 4DIGIT 9542 Appendix B. Changes from previous RFCs 9544 B.1. Changes from RFC 2818 9546 None. 9548 B.2. Changes from RFC 7230 9550 The sections introducing HTTP's design goals, history, architecture, 9551 conformance criteria, protocol versioning, URIs, message routing, and 9552 header fields have been moved here (without substantive change). 9554 The description of an origin and authoritative access to origin 9555 servers has been extended for both "http" and "https" URIs to account 9556 for alternative services and secured connections that are not 9557 necessarily based on TCP. (Section 4.2.1, Section 4.2.2, 9558 Section 4.3.1, Section 7.3.3) 9560 "Field value" now refers to the value after multiple field lines are 9561 combined with commas - by far the most common use. To refer to a 9562 single header line's value, use "field line value". (Section 6.3) 9564 Parameters in media type, media range, and expectation can be empty 9565 via one or more trailing semicolons. (Section 5.6.6) 9566 Trailer field semantics now transcend the specifics of chunked 9567 encoding. Use of trailer fields has been further limited to only 9568 allow generation as a trailer field when the sender knows the field 9569 defines that usage and to only allow merging into the header section 9570 if the recipient knows the corresponding field definition permits and 9571 defines how to merge. In all other cases, implementations are 9572 encouraged to either store the trailer fields separately or discard 9573 them instead of merging. (Section 6.5.1) 9575 Trailer fields can now potentially appear as multiple trailer 9576 sections, if allowed by the HTTP version and framing in use, with 9577 processing described as being iterative as each section is received. 9578 (Section 6.5.2) 9580 Made the priority of the absolute form of the request URI over the 9581 Host header by origin servers explicit, to align with proxy handling. 9582 (Section 7.2) 9584 The grammar definition for the Via field's "received-by" was expanded 9585 in 7230 due to changes in the URI grammar for host [RFC3986] that are 9586 not desirable for Via. For simplicity, we have removed uri-host from 9587 the received-by production because it can be encompassed by the 9588 existing grammar for pseudonym. In particular, this change removed 9589 comma from the allowed set of charaters for a host name in received- 9590 by. (Section 7.6.3) 9592 B.3. Changes from RFC 7231 9594 Minimum URI lengths to be supported by implementations are now 9595 recommended. (Section 3.1) 9597 Clarify that control characters in field values are to be rejected or 9598 mapped to SP. (Section 5.5) 9600 Parameters in media type, media range, and expectation can be empty 9601 via one or more trailing semicolons. (Section 5.6.6) 9603 An abstract data type for HTTP messages has been introduced to define 9604 the components of a message and their semantics as an abstraction 9605 across multiple HTTP versions, rather than in terms of the specific 9606 syntax form of HTTP/1.1 in [Messaging], and reflect the contents 9607 after the message is parsed. This makes it easier to distinguish 9608 between requirements on the content (what is conveyed) versus 9609 requirements on the messaging syntax (how it is conveyed) and avoids 9610 baking limitations of early protocol versions into the future of 9611 HTTP. (Section 6) 9612 The term "effective request URI" has been replaced with "target URI". 9613 (Section 7.1) 9615 Restrictions on client retries have been loosened, to reflect 9616 implementation behavior. (Section 9.2.2) 9618 Clarified that request bodies on GET and DELETE are not 9619 interoperable. (Section 9.3.1, Section 9.3.5) 9621 Removed a superfluous requirement about setting Content-Length from 9622 the description of the OPTIONS method. (Section 9.3.7) 9624 Restore list-based grammar for Expect for compatibility with RFC 9625 2616. (Section 10.1.1) 9627 Allow Accept and Accept-Encoding in response messages; the latter was 9628 introduced by [RFC7694]. (Section 12.3) 9630 "Accept Parameters" (accept-params) have been removed from the 9631 definition of the Accept field. (Section 12.5.1) 9633 The semantics of "*" in the Vary header field when other values are 9634 present was clarified. (Section 12.5.5) 9636 Range units are compared in a case insensitive fashion. 9637 (Section 14.1) 9639 The process of creating a redirected request has been clarified. 9640 (Section 15.4) 9642 Added status code 308 (previously defined in [RFC7538]) so that it's 9643 defined closer to status codes 301, 302, and 307. (Section 15.4.9) 9645 Added status code 421 (previously defined in Section 9.1.2 of 9646 [RFC7540]) because of its general applicability. 421 is no longer 9647 defined as heuristically cacheable, since the response is specific to 9648 the connection (not the target resource). (Section 15.5.20) 9650 Added status code 422 (previously defined in Section 11.2 of 9651 [RFC4918]) because of its general applicability. (Section 15.5.21) 9653 Allowed use of the Content-Range header field (Section 14.4) as a 9654 request modifier on PUT. (Section 9.3.4) 9656 B.4. Changes from RFC 7232 9658 Previous revisions of HTTP imposed an arbitrary 60-second limit on 9659 the determination of whether Last-Modified was a strong validator to 9660 guard against the possibility that the Date and Last-Modified values 9661 are generated from different clocks or at somewhat different times 9662 during the preparation of the response. This specification has 9663 relaxed that to allow reasonable discretion. (Section 8.8.2.2) 9665 Removed edge case requirement on If-Match and If-Unmodified-Since 9666 that a validator not be sent in a 2xx response when validation fails 9667 and the server decides that the same change request has already been 9668 applied. (Section 13.1.1 and Section 13.1.4) 9670 Clarified that If-Unmodified-Since doesn't apply to a resource 9671 without a concept of modification time. (Section 13.1.4) 9673 Preconditions can now be evaluated before the request content is 9674 processed rather than waiting until the response would otherwise be 9675 successful. (Section 13.2) 9677 B.5. Changes from RFC 7233 9679 Refactored the range-unit and ranges-specifier grammars to simplify 9680 and reduce artificial distinctions between bytes and other 9681 (extension) range units, removing the overlapping grammar of other- 9682 range-unit by defining range units generically as a token and placing 9683 extensions within the scope of a range-spec (other-range). This 9684 disambiguates the role of list syntax (commas) in all range sets, 9685 including extension range units, for indicating a range-set of more 9686 than one range. Moving the extension grammar into range specifiers 9687 also allows protocol specific to byte ranges to be specified 9688 separately. 9690 It is now possible to define Range handling on extension methods. 9691 (Section 14.2) 9693 Described use of the Content-Range header field (Section 14.4) as a 9694 request modifier to perform a partial PUT. (Section 14.5) 9696 B.6. Changes from RFC 7235 9698 None. 9700 B.7. Changes from RFC 7538 9702 None. 9704 B.8. Changes from RFC 7615 9706 None. 9708 B.9. Changes from RFC 7694 9710 This specification includes the extension defined in [RFC7694], but 9711 leaves out examples and deployment considerations. 9713 Appendix C. Change Log 9715 This section is to be removed before publishing as an RFC. 9717 C.1. Between RFC723x and draft 00 9719 The changes were purely editorial: 9721 o Change boilerplate and abstract to indicate the "draft" status, 9722 and update references to ancestor specifications. 9724 o Remove version "1.1" from document title, indicating that this 9725 specification applies to all HTTP versions. 9727 o Adjust historical notes. 9729 o Update links to sibling specifications. 9731 o Replace sections listing changes from RFC 2616 by new empty 9732 sections referring to RFC 723x. 9734 o Remove acknowledgements specific to RFC 723x. 9736 o Move "Acknowledgements" to the very end and make them unnumbered. 9738 C.2. Since draft-ietf-httpbis-semantics-00 9740 The changes in this draft are editorial, with respect to HTTP as a 9741 whole, to merge core HTTP semantics into this document: 9743 o Merged introduction, architecture, conformance, and ABNF 9744 extensions from RFC 7230 (Messaging). 9746 o Rearranged architecture to extract conformance, http(s) schemes, 9747 and protocol versioning into a separate major section. 9749 o Moved discussion of MIME differences to [Messaging] since that is 9750 primarily concerned with transforming 1.1 messages. 9752 o Merged entire content of RFC 7232 (Conditional Requests). 9754 o Merged entire content of RFC 7233 (Range Requests). 9756 o Merged entire content of RFC 7235 (Auth Framework). 9758 o Moved all extensibility tips, registration procedures, and 9759 registry tables from the IANA considerations to normative 9760 sections, reducing the IANA considerations to just instructions 9761 that will be removed prior to publication as an RFC. 9763 C.3. Since draft-ietf-httpbis-semantics-01 9765 o Improve [Welch] citation () 9768 o Remove HTTP/1.1-ism about Range Requests 9769 () 9771 o Cite RFC 8126 instead of RFC 5226 () 9774 o Cite RFC 7538 instead of RFC 7238 () 9777 o Cite RFC 8288 instead of RFC 5988 () 9780 o Cite RFC 8187 instead of RFC 5987 () 9783 o Cite RFC 7578 instead of RFC 2388 () 9786 o Cite RFC 7595 instead of RFC 4395 () 9789 o improve ABNF readability for qdtext (, ) 9792 o Clarify "resource" vs "representation" in definition of status 9793 code 416 (, 9794 ) 9796 o Resolved erratum 4072, no change needed here 9797 (, 9798 ) 9800 o Clarify DELETE status code suggestions 9801 (, 9802 ) 9804 o In Section 14.4, fix ABNF for "other-range-resp" to use VCHAR 9805 instead of CHAR (, 9806 ) 9808 o Resolved erratum 5162, no change needed here 9809 (, 9810 ) 9812 o Replace "response code" with "response status code" and "status- 9813 code" (the ABNF production name from the HTTP/1.1 message format) 9814 by "status code" (, 9815 ) 9817 o Added a missing word in Section 15.4 (, ) 9820 o In Section 5.6.1, fixed an example that had trailing whitespace 9821 where it shouldn't (, ) 9824 o In Section 15.3.7, remove words that were potentially misleading 9825 with respect to the relation to the requested ranges 9826 (, 9827 ) 9829 C.4. Since draft-ietf-httpbis-semantics-02 9831 o Included (Proxy-)Auth-Info header field definition from RFC 7615 9832 () 9834 o In Section 9.3.3, clarify POST caching 9835 () 9837 o Add Section 15.5.19 to reserve the 418 status code 9838 () 9840 o In Section 3.4 and Section 10.1.1, clarified when a response can 9841 be sent () 9843 o In Section 8.3.2, explain the difference between the "token" 9844 production, the RFC 2978 ABNF for charset names, and the actual 9845 registration practice (, ) 9848 o In Section 3.1, removed the fragment component in the URI scheme 9849 definitions as per Section 4.3 of [RFC3986], furthermore moved 9850 fragment discussion into a separate section 9851 (, 9852 , ) 9855 o In Section 2.5, add language about minor HTTP version number 9856 defaulting () 9858 o Added Section 15.5.21 for status code 422, previously defined in 9859 Section 11.2 of [RFC4918] () 9862 o In Section 15.5.17, fixed prose about byte range comparison 9863 (, 9864 ) 9866 o In Section 3.4, explain that request/response correlation is 9867 version specific () 9870 C.5. Since draft-ietf-httpbis-semantics-03 9872 o In Section 15.4.9, include status code 308 from RFC 7538 9873 () 9875 o In Section 8.3.1, clarify that the charset parameter value is 9876 case-insensitive due to the definition in RFC 2046 9877 () 9879 o Define a separate registry for HTTP header field names 9880 () 9882 o In Section 12.1, refactor and clarify description of wildcard 9883 ("*") handling () 9885 o Deprecate Accept-Charset () 9888 o In Section 13.2, mention Cache-Control: immutable 9889 () 9891 o In Section 5.3, clarify when header field combination is allowed 9892 () 9894 o In Section 18.4, instruct IANA to mark Content-MD5 as obsolete 9895 () 9897 o Use RFC 7405 ABNF notation for case-sensitive string constants 9898 () 9900 o Rework Section 3.4 to be more version-independent 9901 () 9903 o In Section 9.3.5, clarify that DELETE needs to be successful to 9904 invalidate cache (, ) 9907 C.6. Since draft-ietf-httpbis-semantics-04 9909 o In Section 5.5, fix field-content ABNF 9910 (, 9911 ) 9913 o Move Section 5.6.6 into its own section 9914 () 9916 o In Section 8.3, reference MIME Sniffing 9917 () 9919 o In Section 5.6.1, simplify the #rule mapping for recipients 9920 (, 9921 ) 9923 o In Section 9.3.7, remove misleading text about "extension" of HTTP 9924 is needed to define method content () 9927 o Fix editorial issue in Section 3.2 () 9930 o In Section 15.5.21, rephrase language not to use "entity" anymore, 9931 and also avoid lowercase "may" () 9934 o Move discussion of retries from [Messaging] into Section 9.2.2 9935 () 9937 C.7. Since draft-ietf-httpbis-semantics-05 9939 o Moved transport-independent part of the description of trailers 9940 into Section 6.5 () 9942 o Loosen requirements on retries based upon implementation behavior 9943 () 9945 o In Section 18.9, update IANA port registry for TCP/UDP on ports 80 9946 and 443 () 9948 o In Section 16.3.2.2, revise guidelines for new header field names 9949 () 9951 o In Section 9.2.3, remove concept of "cacheable methods" in favor 9952 of prose (, 9953 ) 9955 o In Section 17.1, mention that the concept of authority can be 9956 modified by protocol extensions () 9959 o Create new subsection on content in Section 6.4, taken from 9960 portions of message body () 9963 o Moved definition of "Whitespace" into new container "Generic 9964 Syntax" () 9966 o In Section 3.1, recommend minimum URI size support for 9967 implementations () 9969 o In Section 14.1, refactored the range-unit and ranges-specifier 9970 grammars (, 9971 ) 9973 o In Section 9.3.1, caution against a request content more strongly 9974 () 9976 o Reorganized text in Section 16.3.2.2 () 9979 o In Section 15.5.4, replace "authorize" with "fulfill" 9980 () 9982 o In Section 9.3.7, removed a misleading statement about Content- 9983 Length (, 9984 ) 9986 o In Section 17.1, add text from RFC 2818 9987 () 9989 o Changed "cacheable by default" to "heuristically cacheable" 9990 throughout () 9992 C.8. Since draft-ietf-httpbis-semantics-06 9994 o In Section 7.6.3, simplify received-by grammar (and disallow comma 9995 character) () 9997 o In Section 5.1, give guidance on interoperable field names 9998 () 10000 o In Section 5.6.3, define the semantics and possible replacement of 10001 whitespace when it is known to occur (, ) 10004 o In Section 6.3, introduce field terminology and distinguish 10005 between field line values and field values; use terminology 10006 consistently throughout () 10009 o Moved #rule definition into Section 5.5 and whitespace into 10010 Section 2.1 () 10012 o In Section 14.1, explicitly call out range unit names as case- 10013 insensitive, and encourage registration 10014 () 10016 o In Section 8.4.1, explicitly call out content codings as case- 10017 insensitive, and encourage registration 10018 () 10020 o In Section 5.1, explicitly call out field names as case- 10021 insensitive () 10023 o In Section 17.12, cite [Bujlow] () 10026 o In Section 15, formally define "final" and "interim" status codes 10027 () 10029 o In Section 9.3.5, caution against a request content more strongly 10030 () 10032 o In Section 8.8.3, note that Etag can be used in trailers 10033 () 10035 o In Section 18.4, consider reserved fields as well 10036 () 10038 o In Section 4.2.4, be more correct about what was deprecated by RFC 10039 3986 (, 10040 ) 10042 o In Section 5.3, recommend comma SP when combining field lines 10043 () 10045 o In Section 7.2, make explicit requirements on origin server to use 10046 authority from absolute-form when available 10047 () 10049 o In Section 4.2.1, Section 4.2.2, Section 4.3.1, and Section 7.3.3, 10050 refactored schemes to define origin and authoritative access to an 10051 origin server for both "http" and "https" URIs to account for 10052 alternative services and secured connections that are not 10053 necessarily based on TCP () 10056 o In Section 2.2, reference RFC 8174 as well 10057 () 10059 C.9. Since draft-ietf-httpbis-semantics-07 10061 o In Section 14.2, explicitly reference the definition of 10062 representation data as including any content codings 10063 () 10065 o Move TE: trailers from [Messaging] into Section 6.5.1 10066 () 10068 o In Section 8.6, adjust requirements for handling multiple content- 10069 length values () 10071 o In Section 13.1.1 and Section 13.1.2, clarified condition 10072 evaluation () 10074 o In Section 5.5, remove concept of obs-fold, as that is 10075 HTTP/1-specific () 10077 o In Section 12, introduce the concept of request content 10078 negotiation (Section 12.3) and define for Accept-Encoding 10079 () 10081 o In Section 15.3.6, Section 15.5.9, and Section 15.5.14, remove 10082 HTTP/1-specific, connection-related requirements 10083 () 10085 o In Section 9.3.6, correct language about what is forwarded 10086 () 10088 o Throughout, replace "effective request URI", "request-target" and 10089 similar with "target URI" () 10092 o In Section 16.3.2.2 and Section 16.2.2, describe how extensions 10093 should consider scope of applicability 10094 () 10096 o In Section 3.4, don't rely on the HTTP/1.1 Messaging specification 10097 to define "message" () 10100 o In Section 8.7 and Section 10.1.3, note that URL resolution is 10101 necessary () 10103 o In Section 3.2, explicitly reference 206 as one of the status 10104 codes that provide representation data 10105 () 10107 o In Section 13.1.4, refine requirements so that they don't apply to 10108 resources without a concept of modification time 10109 () 10111 o In Section 11.7.1, specify the scope as a request, not a target 10112 resource () 10114 o In Section 3.4, introduce concept of "complete" messages 10115 () 10117 o In Section 7.1, Section 9.3.6, and Section 9.3.7, refine use of 10118 "request target" () 10121 o Throughout, remove "status-line" and "request-line", as these are 10122 HTTP/1.1-specific () 10125 C.10. Since draft-ietf-httpbis-semantics-08 10127 o In Section 15.5.17, remove duplicate definition of what makes a 10128 range satisfiable and refer instead to each range unit's 10129 definition () 10131 o In Section 14.1.2 and Section 14.2, clarify that a selected 10132 representation of zero length can only be satisfiable as a suffix 10133 range and that a server can still ignore Range for that case 10134 () 10136 o In Section 12.5.1 and Section 15.5.16, allow "Accept" as response 10137 field () 10139 o Appendix A now uses the sender variant of the "#" list expansion 10140 () 10142 o In Section 12.5.5, make the field list-based even when "*" is 10143 present () 10145 o In Section 16.3.1, add optional "Comments" entry 10146 () 10148 o In Section 18.4, reserve "*" as field name 10149 () 10151 o In Section 18.2, reserve "*" as method name 10152 () 10154 o In Section 13.1.1 and Section 13.1.2, state that multiple "*" is 10155 unlikely to be interoperable () 10158 o In Section 12.5.1, avoid use of obsolete media type parameter on 10159 text/html (, 10160 ) 10162 o Rephrase prose in Section 3.4 to become version-agnostic 10163 () 10165 o In Section 5.5, instruct recipients how to deal with control 10166 characters in field values () 10169 o In Section 5.5, update note about field ABNF 10170 () 10172 o Add Section 16 about Extending and Versioning HTTP 10173 () 10175 o In Section 15.1, include status 308 in list of heuristically 10176 cacheable status codes () 10179 o In Section 8.4, make it clearer that "identity" is not to be 10180 included () 10182 C.11. Since draft-ietf-httpbis-semantics-09 10184 o Switch to xml2rfc v3 mode for draft generation 10185 () 10187 C.12. Since draft-ietf-httpbis-semantics-10 10189 o In Section 17.6, mention compression attacks 10190 () 10192 o In Section 16.6.1, advise to make new content codings self- 10193 descriptive () 10195 o In Section 5.6.6, introduced the "parameters" ABNF rule, allowing 10196 empty parameters and trailing semicolons within media type, media 10197 range, and expectation () 10200 o In Section 15.4, explain how to create a redirected request 10201 () 10203 o In Section 8.3, defined error handling for multiple members 10204 () 10206 o In Section 1, revise the introduction and introduce HTTP/2 and 10207 HTTP/3 () 10209 o In Section 8.6, added a definition for Content-Length that 10210 encompasses its various roles in describing message content or 10211 selected representation length; in Section 15.3.7, noted that 10212 Content-Length counts only the message content (not the selected 10213 representation) and that the representation length is in each 10214 Content-Range () 10216 o Noted that "WWW-Authenticate" with more than one value on a line 10217 is sometimes not interoperable [Messaging] 10218 () 10220 o In Section 13.1.1 and Section 13.1.4, removed requirement that a 10221 validator not be sent in a 2xx response when validation fails and 10222 the server decides that the same change request has already been 10223 applied () 10225 o Moved requirements specific to HTTP/1.1 from Section 7.2 to 10226 [Messaging] () 10228 o In Section 5.5, introduce the terms "singleton field" and "list- 10229 based field" (also - in various places - discuss what to do when a 10230 singleton field is received as a list) 10231 () 10233 o In Section 10.1.1, change the ABNF back to be a list of 10234 expectations, as defined in RFC 2616 () 10237 o In Section 10.1.5 (Trailer), Section 7.6.3 (Via), Section 7.8 10238 (Upgrade), Section 7.6.1 (Connection), Section 8.4 10239 (Content-Encoding), Section 8.5 (Content-Language), Section 10.1.1 10240 (Expect), Section 13.1.1 (If-Match), Section 13.1.2 10241 (If-None-Match), Section 12.5.2 (Accept-Charset), Section 12.5.4 10242 (Accept-Language), Section 12.5.5 (Vary), Section 11.6.1 10243 (WWW-Authenticate), and Section 11.7.1 (Proxy-Authenticate), 10244 adjust ABNF to allow empty lists () 10247 o In Section 9.3.1 and Section 17.9, provide a more nuanced 10248 explanation of sensitive data in GET-based forms and describe 10249 workarounds () 10251 o In Section 13.2, allow preconditions to be evaluated before the 10252 request content (if any) is processed () 10255 o In Section 6.3 and Section 6.5.2, allow for trailer fields in 10256 multiple trailer sections, depending on the HTTP version and 10257 framing in use, with processing being iterative as each section is 10258 received () 10260 o Moved definitions of "TE" and "Upgrade" from [Messaging] 10261 () 10263 o Moved 1.1-specific discussion of TLS to Messaging and rewrote 10264 Section 4.3.4 to refer to RFC6125 () 10267 o Moved definition of "Connection" from [Messaging] 10268 () 10270 C.13. Since draft-ietf-httpbis-semantics-11 10272 o The entire document has been reorganized, with no changes to 10273 content except editorial for the reorganization 10274 () 10276 o Move IANA Upgrade Token Registry instructions from [Messaging] 10277 () 10279 C.14. Since draft-ietf-httpbis-semantics-12 10281 o In Appendix "Acknowledgments" (Appendix D), added acks for the 10282 work since 2014 () 10284 o In Section 15.3.7, specifically require that a client check the 10285 206 response header fields to determine what ranges are enclosed, 10286 since it cannot assume they exactly match those requested 10287 () 10289 o In Section 16.3, explain why new fields need to be backwards- 10290 compatible () 10292 o In Section 5.3, constrain field combination to be within a section 10293 () 10295 o In Section 5.6.7, mention that caching relaxes date sensitivity 10296 () 10298 o In Section 18.4, moved "*" field registration into main table 10299 () 10301 o In Section 1.2, reference HTTP/0.9 () 10304 o In Section 9.3.4, clarify handling of unrecognized fields 10305 () 10307 o In Section 15.2, align language about bodies and trailers with 204 10308 and 304 () 10310 o Moved table of content codings into Section 18.6, moved table of 10311 range units into Section 18.7 () 10314 o In Section 6, add an abstract data type for message to help define 10315 semantics without being dependent on the specific structure of 10316 HTTP/1.1 () 10318 o In Section 8.8.2.2, relax arbitrary 60-second comparison limit 10319 () 10321 o In Section 7.2, add ":authority" pseudo-header to Host discussion 10322 and make section applicable to both () 10325 o In Section 18.4, note that this document updates [RFC3864] 10326 () 10328 o Moved transfer-coding ABNF from [Messaging] to Section 10.1.4 and 10329 replaced "t-ranking" ABNF by equivalent "weight" 10330 () 10332 o In Section 11.5, replace "canonical root URI" by "origin" 10333 () 10335 o In Section 10.1.1, remove obsolete note about a change in RFC 723x 10336 () 10338 o Changed to using "payload" when defining requirements about the 10339 data being conveyed within a message, instead of the terms 10340 "payload body" or "response body" or "representation body", since 10341 they often get confused with the HTTP/1.1 message body (which 10342 includes transfer coding) () 10345 o Rewrite definition of HEAD method () 10348 o In Section 13.1.5, fix an off-by-one bug about how many chars to 10349 consider when checking for etags () 10352 o In Section 15.1, clarify that "no reason phrase" is fine as well 10353 () 10355 o In Section 15.3.4, remove an obsolete reference to the Warning 10356 response header field () 10359 o In Section 15.5.9, rephrase prose about connection re-use 10360 () 10362 o In Section 14.2, potentially allow Range handling on methods other 10363 than GET () 10365 o In Section 18.3, remove redundant text about status code 418 10366 () 10368 o In Section 17.15.1, rewrite requirement to refer to "secured 10369 connection" () 10371 o Make reference to [RFC8446] normative () 10374 C.15. Since draft-ietf-httpbis-semantics-13 10376 o In Section 12.5.1, remove the unused "accept parameters" 10377 () 10379 o In Section 1.2, mention that RFC 1945 describes HTTP/0.9 as well 10380 () 10382 o In Section 14.5, describe non-standard use of the Content-Range 10383 header field (Section 14.4) as a request modifier to perform a 10384 partial PUT () 10386 o In Section 15.5.20, import the 421 (Misdirected Request) status 10387 code from [RFC7540] () 10390 o In Section 2.3, rephrase the actual recipient parsing requirements 10391 () 10393 o In Section 16.1.2, mention request target forms in considerations 10394 for new methods () 10396 o Changed to using "content" instead of "payload" or "payload data" 10397 to avoid confusion with the payload of version-specific messaging 10398 frames () 10400 o In Section 13.1.3, Section 13.1.4, and Section 13.1.5, specify 10401 evaluation in a way similar to other conditional header fields 10402 () 10404 o In Section 10.2.2, specify that recipients can replace an invalid 10405 Date header field value with the time received 10406 () 10408 Acknowledgments 10410 This edition of the HTTP specification builds on the many 10411 contributions that went into RFC 1945, RFC 2068, RFC 2145, RFC 2616, 10412 and RFC 2818, including substantial contributions made by the 10413 previous authors, editors, and Working Group Chairs: Tim Berners-Lee, 10414 Jean-François Groff, Ari Luotonen, Roy T. Fielding, Henrik Frystyk 10415 Nielsen, Jim Gettys, Jeffrey C. Mogul, Larry Masinter, Paul J. 10416 Leach, Eric Rescorla, and Yves Lafon. 10418 In addition, this document has reincorporated the HTTP Authentication 10419 Framework, previously defined in RFC 7235 and RFC 2617. We thank 10420 John Franks, Phillip M. Hallam-Baker, Jeffery L. Hostetler, Scott 10421 D. Lawrence, Paul J. Leach, Ari Luotonen, and Lawrence C. Stewart 10422 for their work on that specification. See Section 6 of [RFC2617] for 10423 further acknowledgements. 10425 Since 2014, the following contributors have helped improve the HTTP 10426 specification by reporting bugs, asking smart questions, drafting or 10427 reviewing text, and evaluating open issues: 10429 Alan Egerton, Alex Rousskov, Amichai Rothman, Amos Jeffries, Anders 10430 Kaseorg, Andreas Gebhardt, Anne van Kesteren, Armin Abfalterer, Aron 10431 Duby, Asanka Herath, Asbjørn Ulsberg, Attila Gulyas, Austin Wright, 10432 Barry Pollard, Ben Burkert, Björn Höhrmann, Brad Fitzpatrick, Chris 10433 Pacejo, Colin Bendell, Cory Benfield, Cory Nelson, Daisuke Miyakawa, 10434 Daniel Stenberg, Danil Suits, David Benjamin, David Matson, David 10435 Schinazi, Дилян Палаузов (Dilyan Palauzov), Eric Anderson, Eric 10436 Rescorla, Erwin Pe, Etan Kissling, Evert Pot, Evgeny Vrublevsky, 10437 Florian Best, Igor Lubashev, James Callahan, James Peach, Jeffrey 10438 Yasskin, Kalin Gyokov, Kannan Goundan, 奥 一穂 (Kazuho Oku), Ken 10439 Murchison, Lucas Pardue, Martin Dürst, Martin Thomson, Martynas 10440 Jusevičius, Matt Menke, Matthias Pigulla, Michael Osipov, Mike 10441 Bishop, Mike Pennisi, Mike West, Nicholas Hurley, Nikita Piskunov, 10442 Patrick McManus, Piotr Sikora, Poul-Henning Kamp, Rick van Rein, 10443 Roberto Polli, Semyon Kholodnov, Simon Pieters, Simon Schüppel, Todd 10444 Greer, Tommy Pauly, Vasiliy Faronov, Vladimir Lashchev, Wenbo Zhu, 10445 William A. Rowe Jr., Willy Tarreau, Xingwei Liu, and Yishuai Li. 10447 See Section 10 of [RFC7230] for further acknowledgements from prior 10448 revisions. 10450 Authors' Addresses 10452 Roy T. Fielding (editor) 10453 Adobe 10454 345 Park Ave 10455 San Jose, CA 95110 10456 United States of America 10458 Email: fielding@gbiv.com 10459 URI: https://roy.gbiv.com/ 10460 Mark Nottingham (editor) 10461 Fastly 10462 Prahran VIC 10463 Australia 10465 Email: mnot@mnot.net 10466 URI: https://www.mnot.net/ 10468 Julian Reschke (editor) 10469 greenbytes GmbH 10470 Hafenweg 16 10471 48155 Münster 10472 Germany 10474 Email: julian.reschke@greenbytes.de 10475 URI: https://greenbytes.de/tech/webdav/