idnits 2.17.1 draft-ietf-httpbis-semantics-10.txt: 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 is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 6 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. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, 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 (July 12, 2020) is 1376 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 8487, but no explicit reference was found in the text == Unused Reference: 'RFC2818' is defined on line 8521, but no explicit reference was found in the text == Unused Reference: 'RFC7232' is defined on line 8591, but no explicit reference was found in the text == Unused Reference: 'RFC7233' is defined on line 8596, but no explicit reference was found in the text == Unused Reference: 'RFC7235' is defined on line 8601, but no explicit reference was found in the text == Unused Reference: 'RFC7615' is defined on line 8620, but no explicit reference was found in the text == Unused Reference: 'RFC7617' is defined on line 8630, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-cache-10 -- Possible downref: Normative reference to a draft: ref. 'Caching' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-messaging-10 -- 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 -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' -- Possible downref: Non-RFC (?) normative reference: ref. 'Welch' -- Duplicate reference: RFC2978, mentioned in 'Err5433', was also mentioned in 'Err1912'. -- Obsolete informational reference (is this intentional?): RFC 2068 (Obsoleted by RFC 2616) -- Obsolete informational reference (is this intentional?): RFC 2145 (Obsoleted by RFC 7230) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Duplicate reference: RFC2978, mentioned in 'RFC2978', was also mentioned in 'Err5433'. -- Obsolete informational reference (is this intentional?): RFC 6125 (Obsoleted by RFC 9525) -- 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: 4 errors (**), 0 flaws (~~), 13 warnings (==), 27 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 Intended status: Standards Track J. F. Reschke, Ed. 7 Expires: January 13, 2021 greenbytes 8 July 12, 2020 10 HTTP Semantics 11 draft-ietf-httpbis-semantics-10 13 Abstract 15 The Hypertext Transfer Protocol (HTTP) is a stateless application- 16 level protocol for distributed, collaborative, hypertext information 17 systems. This document defines the semantics of HTTP: its 18 architecture, terminology, the "http" and "https" Uniform Resource 19 Identifier (URI) schemes, core request methods, request header 20 fields, response status codes, response header fields, and content 21 negotiation. 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 D.11. 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 January 13, 2021. 57 Copyright Notice 59 Copyright (c) 2020 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 . . . . . . . . . . . . . . . . . . . . . . . . 8 86 1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 9 87 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 10 88 1.2.1. Whitespace . . . . . . . . . . . . . . . . . . . . . 10 89 2. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 11 90 2.1. Client/Server Messaging . . . . . . . . . . . . . . . . . 11 91 2.2. Intermediaries . . . . . . . . . . . . . . . . . . . . . 14 92 2.3. Caches . . . . . . . . . . . . . . . . . . . . . . . . . 16 93 2.4. Uniform Resource Identifiers . . . . . . . . . . . . . . 16 94 2.5. Resources . . . . . . . . . . . . . . . . . . . . . . . . 17 95 2.5.1. http URI Scheme . . . . . . . . . . . . . . . . . . . 18 96 2.5.2. https URI Scheme . . . . . . . . . . . . . . . . . . 19 97 2.5.3. http and https URI Normalization and Comparison . . . 20 98 2.5.4. Deprecated userinfo . . . . . . . . . . . . . . . . . 20 99 2.5.5. Fragment Identifiers on http(s) URI References . . . 21 100 3. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 21 101 3.1. Implementation Diversity . . . . . . . . . . . . . . . . 21 102 3.2. Role-based Requirements . . . . . . . . . . . . . . . . . 22 103 3.3. Parsing Elements . . . . . . . . . . . . . . . . . . . . 23 104 3.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 23 105 4. Extending and Versioning HTTP . . . . . . . . . . . . . . . . 24 106 4.1. Extending HTTP . . . . . . . . . . . . . . . . . . . . . 24 107 4.2. Protocol Versioning . . . . . . . . . . . . . . . . . . . 25 108 5. Header and Trailer Fields . . . . . . . . . . . . . . . . . . 26 109 5.1. Field Ordering and Combination . . . . . . . . . . . . . 27 110 5.2. Field Limits . . . . . . . . . . . . . . . . . . . . . . 28 111 5.3. Field Names . . . . . . . . . . . . . . . . . . . . . . . 28 112 5.3.1. Field Extensibility . . . . . . . . . . . . . . . . . 29 113 5.3.2. Field Name Registry . . . . . . . . . . . . . . . . . 30 114 5.4. Field Values . . . . . . . . . . . . . . . . . . . . . . 31 115 5.4.1. Common Field Value Components . . . . . . . . . . . . 32 116 5.5. ABNF List Extension: #rule . . . . . . . . . . . . . . . 36 117 5.5.1. Sender Requirements . . . . . . . . . . . . . . . . . 36 118 5.5.2. Recipient Requirements . . . . . . . . . . . . . . . 37 119 5.6. Trailer Fields . . . . . . . . . . . . . . . . . . . . . 37 120 5.6.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . 38 121 5.6.2. Limitations . . . . . . . . . . . . . . . . . . . . . 38 122 5.6.3. Trailer . . . . . . . . . . . . . . . . . . . . . . . 39 123 5.7. Considerations for New HTTP Fields . . . . . . . . . . . 39 124 5.8. Fields Defined In This Document . . . . . . . . . . . . . 40 125 6. Message Routing . . . . . . . . . . . . . . . . . . . . . . . 42 126 6.1. Identifying a Target Resource . . . . . . . . . . . . . . 42 127 6.2. Determining Origin . . . . . . . . . . . . . . . . . . . 43 128 6.3. Routing Inbound . . . . . . . . . . . . . . . . . . . . . 43 129 6.4. Direct Authoritative Access . . . . . . . . . . . . . . . 44 130 6.4.1. http origins . . . . . . . . . . . . . . . . . . . . 44 131 6.4.2. https origins . . . . . . . . . . . . . . . . . . . . 45 132 6.4.3. Initiating HTTP Over TLS . . . . . . . . . . . . . . 46 133 6.5. Reconstructing the Target URI . . . . . . . . . . . . . . 48 134 6.6. Host . . . . . . . . . . . . . . . . . . . . . . . . . . 49 135 6.7. Message Forwarding . . . . . . . . . . . . . . . . . . . 50 136 6.7.1. Via . . . . . . . . . . . . . . . . . . . . . . . . . 50 137 6.7.2. Transformations . . . . . . . . . . . . . . . . . . . 52 138 7. Representations . . . . . . . . . . . . . . . . . . . . . . . 53 139 7.1. Representation Data . . . . . . . . . . . . . . . . . . . 54 140 7.1.1. Media Type . . . . . . . . . . . . . . . . . . . . . 54 141 7.1.2. Content Codings . . . . . . . . . . . . . . . . . . . 56 142 7.1.3. Language Tags . . . . . . . . . . . . . . . . . . . . 58 143 7.1.4. Range Units . . . . . . . . . . . . . . . . . . . . . 59 144 7.2. Representation Metadata . . . . . . . . . . . . . . . . . 63 145 7.2.1. Content-Type . . . . . . . . . . . . . . . . . . . . 63 146 7.2.2. Content-Encoding . . . . . . . . . . . . . . . . . . 64 147 7.2.3. Content-Language . . . . . . . . . . . . . . . . . . 65 148 7.2.4. Content-Length . . . . . . . . . . . . . . . . . . . 66 149 7.2.5. Content-Location . . . . . . . . . . . . . . . . . . 67 150 7.3. Payload . . . . . . . . . . . . . . . . . . . . . . . . . 69 151 7.3.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . 69 152 7.3.2. Identification . . . . . . . . . . . . . . . . . . . 70 153 7.3.3. Payload Body . . . . . . . . . . . . . . . . . . . . 71 154 7.3.4. Content-Range . . . . . . . . . . . . . . . . . . . . 72 155 7.3.5. Media Type multipart/byteranges . . . . . . . . . . . 73 156 7.4. Content Negotiation . . . . . . . . . . . . . . . . . . . 75 157 7.4.1. Proactive Negotiation . . . . . . . . . . . . . . . . 76 158 7.4.2. Reactive Negotiation . . . . . . . . . . . . . . . . 77 159 7.4.3. Request Payload Negotiation . . . . . . . . . . . . . 78 160 7.4.4. Quality Values . . . . . . . . . . . . . . . . . . . 78 161 8. Request Methods . . . . . . . . . . . . . . . . . . . . . . . 79 162 8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 79 163 8.2. Common Method Properties . . . . . . . . . . . . . . . . 80 164 8.2.1. Safe Methods . . . . . . . . . . . . . . . . . . . . 81 165 8.2.2. Idempotent Methods . . . . . . . . . . . . . . . . . 82 166 8.2.3. Methods and Caching . . . . . . . . . . . . . . . . . 83 167 8.3. Method Definitions . . . . . . . . . . . . . . . . . . . 83 168 8.3.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 83 169 8.3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 84 170 8.3.3. POST . . . . . . . . . . . . . . . . . . . . . . . . 84 171 8.3.4. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 85 172 8.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 88 173 8.3.6. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 89 174 8.3.7. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 91 175 8.3.8. TRACE . . . . . . . . . . . . . . . . . . . . . . . . 92 176 8.4. Method Extensibility . . . . . . . . . . . . . . . . . . 92 177 8.4.1. Method Registry . . . . . . . . . . . . . . . . . . . 92 178 8.4.2. Considerations for New Methods . . . . . . . . . . . 93 179 9. Request Header Fields . . . . . . . . . . . . . . . . . . . . 94 180 9.1. Controls . . . . . . . . . . . . . . . . . . . . . . . . 94 181 9.1.1. Expect . . . . . . . . . . . . . . . . . . . . . . . 94 182 9.1.2. Max-Forwards . . . . . . . . . . . . . . . . . . . . 97 183 9.2. Preconditions . . . . . . . . . . . . . . . . . . . . . . 97 184 9.2.1. Evaluation . . . . . . . . . . . . . . . . . . . . . 98 185 9.2.2. Precedence . . . . . . . . . . . . . . . . . . . . . 99 186 9.2.3. If-Match . . . . . . . . . . . . . . . . . . . . . . 101 187 9.2.4. If-None-Match . . . . . . . . . . . . . . . . . . . . 102 188 9.2.5. If-Modified-Since . . . . . . . . . . . . . . . . . . 103 189 9.2.6. If-Unmodified-Since . . . . . . . . . . . . . . . . . 105 190 9.2.7. If-Range . . . . . . . . . . . . . . . . . . . . . . 106 191 9.3. Range . . . . . . . . . . . . . . . . . . . . . . . . . . 107 192 9.4. Negotiation . . . . . . . . . . . . . . . . . . . . . . . 109 193 9.4.1. Accept . . . . . . . . . . . . . . . . . . . . . . . 110 194 9.4.2. Accept-Charset . . . . . . . . . . . . . . . . . . . 112 195 9.4.3. Accept-Encoding . . . . . . . . . . . . . . . . . . . 113 196 9.4.4. Accept-Language . . . . . . . . . . . . . . . . . . . 115 197 9.5. Authentication Credentials . . . . . . . . . . . . . . . 116 198 9.5.1. Challenge and Response . . . . . . . . . . . . . . . 116 199 9.5.2. Protection Space (Realm) . . . . . . . . . . . . . . 118 200 9.5.3. Authorization . . . . . . . . . . . . . . . . . . . . 119 201 9.5.4. Proxy-Authorization . . . . . . . . . . . . . . . . . 119 202 9.5.5. Authentication Scheme Extensibility . . . . . . . . . 120 203 9.6. Request Context . . . . . . . . . . . . . . . . . . . . . 122 204 9.6.1. From . . . . . . . . . . . . . . . . . . . . . . . . 122 205 9.6.2. Referer . . . . . . . . . . . . . . . . . . . . . . . 123 206 9.6.3. User-Agent . . . . . . . . . . . . . . . . . . . . . 124 207 10. Response Status Codes . . . . . . . . . . . . . . . . . . . . 125 208 10.1. Overview of Status Codes . . . . . . . . . . . . . . . . 126 209 10.2. Informational 1xx . . . . . . . . . . . . . . . . . . . 127 210 10.2.1. 100 Continue . . . . . . . . . . . . . . . . . . . . 127 211 10.2.2. 101 Switching Protocols . . . . . . . . . . . . . . 128 212 10.3. Successful 2xx . . . . . . . . . . . . . . . . . . . . . 128 213 10.3.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . 128 214 10.3.2. 201 Created . . . . . . . . . . . . . . . . . . . . 129 215 10.3.3. 202 Accepted . . . . . . . . . . . . . . . . . . . . 129 216 10.3.4. 203 Non-Authoritative Information . . . . . . . . . 130 217 10.3.5. 204 No Content . . . . . . . . . . . . . . . . . . . 130 218 10.3.6. 205 Reset Content . . . . . . . . . . . . . . . . . 131 219 10.3.7. 206 Partial Content . . . . . . . . . . . . . . . . 131 220 10.4. Redirection 3xx . . . . . . . . . . . . . . . . . . . . 135 221 10.4.1. 300 Multiple Choices . . . . . . . . . . . . . . . . 136 222 10.4.2. 301 Moved Permanently . . . . . . . . . . . . . . . 137 223 10.4.3. 302 Found . . . . . . . . . . . . . . . . . . . . . 137 224 10.4.4. 303 See Other . . . . . . . . . . . . . . . . . . . 138 225 10.4.5. 304 Not Modified . . . . . . . . . . . . . . . . . . 138 226 10.4.6. 305 Use Proxy . . . . . . . . . . . . . . . . . . . 139 227 10.4.7. 306 (Unused) . . . . . . . . . . . . . . . . . . . . 139 228 10.4.8. 307 Temporary Redirect . . . . . . . . . . . . . . . 139 229 10.4.9. 308 Permanent Redirect . . . . . . . . . . . . . . . 140 230 10.5. Client Error 4xx . . . . . . . . . . . . . . . . . . . . 140 231 10.5.1. 400 Bad Request . . . . . . . . . . . . . . . . . . 140 232 10.5.2. 401 Unauthorized . . . . . . . . . . . . . . . . . . 140 233 10.5.3. 402 Payment Required . . . . . . . . . . . . . . . . 141 234 10.5.4. 403 Forbidden . . . . . . . . . . . . . . . . . . . 141 235 10.5.5. 404 Not Found . . . . . . . . . . . . . . . . . . . 141 236 10.5.6. 405 Method Not Allowed . . . . . . . . . . . . . . . 142 237 10.5.7. 406 Not Acceptable . . . . . . . . . . . . . . . . . 142 238 10.5.8. 407 Proxy Authentication Required . . . . . . . . . 142 239 10.5.9. 408 Request Timeout . . . . . . . . . . . . . . . . 142 240 10.5.10. 409 Conflict . . . . . . . . . . . . . . . . . . . . 143 241 10.5.11. 410 Gone . . . . . . . . . . . . . . . . . . . . . . 143 242 10.5.12. 411 Length Required . . . . . . . . . . . . . . . . 143 243 10.5.13. 412 Precondition Failed . . . . . . . . . . . . . . 144 244 10.5.14. 413 Payload Too Large . . . . . . . . . . . . . . . 144 245 10.5.15. 414 URI Too Long . . . . . . . . . . . . . . . . . . 144 246 10.5.16. 415 Unsupported Media Type . . . . . . . . . . . . . 144 247 10.5.17. 416 Range Not Satisfiable . . . . . . . . . . . . . 145 248 10.5.18. 417 Expectation Failed . . . . . . . . . . . . . . . 145 249 10.5.19. 418 (Unused) . . . . . . . . . . . . . . . . . . . . 146 250 10.5.20. 422 Unprocessable Payload . . . . . . . . . . . . . 146 251 10.5.21. 426 Upgrade Required . . . . . . . . . . . . . . . . 146 252 10.6. Server Error 5xx . . . . . . . . . . . . . . . . . . . . 147 253 10.6.1. 500 Internal Server Error . . . . . . . . . . . . . 147 254 10.6.2. 501 Not Implemented . . . . . . . . . . . . . . . . 147 255 10.6.3. 502 Bad Gateway . . . . . . . . . . . . . . . . . . 147 256 10.6.4. 503 Service Unavailable . . . . . . . . . . . . . . 147 257 10.6.5. 504 Gateway Timeout . . . . . . . . . . . . . . . . 148 258 10.6.6. 505 HTTP Version Not Supported . . . . . . . . . . . 148 259 10.7. Status Code Extensibility . . . . . . . . . . . . . . . 148 260 10.7.1. Status Code Registry . . . . . . . . . . . . . . . . 148 261 10.7.2. Considerations for New Status Codes . . . . . . . . 149 262 11. Response Header Fields . . . . . . . . . . . . . . . . . . . 150 263 11.1. Control Data . . . . . . . . . . . . . . . . . . . . . . 150 264 11.1.1. Date . . . . . . . . . . . . . . . . . . . . . . . . 150 265 11.1.2. Location . . . . . . . . . . . . . . . . . . . . . . 151 266 11.1.3. Retry-After . . . . . . . . . . . . . . . . . . . . 153 267 11.1.4. Vary . . . . . . . . . . . . . . . . . . . . . . . . 153 268 11.2. Validators . . . . . . . . . . . . . . . . . . . . . . . 154 269 11.2.1. Weak versus Strong . . . . . . . . . . . . . . . . . 155 270 11.2.2. Last-Modified . . . . . . . . . . . . . . . . . . . 157 271 11.2.3. ETag . . . . . . . . . . . . . . . . . . . . . . . . 159 272 11.2.4. When to Use Entity-Tags and Last-Modified Dates . . 162 273 11.3. Authentication Challenges . . . . . . . . . . . . . . . 163 274 11.3.1. WWW-Authenticate . . . . . . . . . . . . . . . . . . 163 275 11.3.2. Proxy-Authenticate . . . . . . . . . . . . . . . . . 164 276 11.3.3. Authentication-Info . . . . . . . . . . . . . . . . 165 277 11.3.4. Proxy-Authentication-Info . . . . . . . . . . . . . 166 278 11.4. Response Context . . . . . . . . . . . . . . . . . . . . 166 279 11.4.1. Accept-Ranges . . . . . . . . . . . . . . . . . . . 166 280 11.4.2. Allow . . . . . . . . . . . . . . . . . . . . . . . 167 281 11.4.3. Server . . . . . . . . . . . . . . . . . . . . . . . 167 282 12. Security Considerations . . . . . . . . . . . . . . . . . . . 168 283 12.1. Establishing Authority . . . . . . . . . . . . . . . . . 168 284 12.2. Risks of Intermediaries . . . . . . . . . . . . . . . . 169 285 12.3. Attacks Based on File and Path Names . . . . . . . . . . 170 286 12.4. Attacks Based on Command, Code, or Query Injection . . . 171 287 12.5. Attacks via Protocol Element Length . . . . . . . . . . 171 288 12.6. Disclosure of Personal Information . . . . . . . . . . . 172 289 12.7. Privacy of Server Log Information . . . . . . . . . . . 172 290 12.8. Disclosure of Sensitive Information in URIs . . . . . . 173 291 12.9. Disclosure of Fragment after Redirects . . . . . . . . . 173 292 12.10. Disclosure of Product Information . . . . . . . . . . . 173 293 12.11. Browser Fingerprinting . . . . . . . . . . . . . . . . . 174 294 12.12. Validator Retention . . . . . . . . . . . . . . . . . . 175 295 12.13. Denial-of-Service Attacks Using Range . . . . . . . . . 175 296 12.14. Authentication Considerations . . . . . . . . . . . . . 176 297 12.14.1. Confidentiality of Credentials . . . . . . . . . . 176 298 12.14.2. Credentials and Idle Clients . . . . . . . . . . . 176 299 12.14.3. Protection Spaces . . . . . . . . . . . . . . . . . 177 300 12.14.4. Additional Response Fields . . . . . . . . . . . . 177 301 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 177 302 13.1. URI Scheme Registration . . . . . . . . . . . . . . . . 178 303 13.2. Method Registration . . . . . . . . . . . . . . . . . . 178 304 13.3. Status Code Registration . . . . . . . . . . . . . . . . 178 305 13.4. HTTP Field Name Registration . . . . . . . . . . . . . . 178 306 13.5. Authentication Scheme Registration . . . . . . . . . . . 179 307 13.6. Content Coding Registration . . . . . . . . . . . . . . 179 308 13.7. Range Unit Registration . . . . . . . . . . . . . . . . 180 309 13.8. Media Type Registration . . . . . . . . . . . . . . . . 180 310 13.9. Port Registration . . . . . . . . . . . . . . . . . . . 180 311 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 180 312 14.1. Normative References . . . . . . . . . . . . . . . . . . 180 313 14.2. Informative References . . . . . . . . . . . . . . . . . 182 314 Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 188 315 Appendix B. Changes from previous RFCs . . . . . . . . . . . . . 192 316 B.1. Changes from RFC 2818 . . . . . . . . . . . . . . . . . . 192 317 B.2. Changes from RFC 7230 . . . . . . . . . . . . . . . . . . 192 318 B.3. Changes from RFC 7231 . . . . . . . . . . . . . . . . . . 193 319 B.4. Changes from RFC 7232 . . . . . . . . . . . . . . . . . . 194 320 B.5. Changes from RFC 7233 . . . . . . . . . . . . . . . . . . 194 321 B.6. Changes from RFC 7235 . . . . . . . . . . . . . . . . . . 194 322 B.7. Changes from RFC 7538 . . . . . . . . . . . . . . . . . . 194 323 B.8. Changes from RFC 7615 . . . . . . . . . . . . . . . . . . 194 324 Appendix C. Changes from RFC 7694 . . . . . . . . . . . . . . . 195 325 Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 195 326 D.1. Between RFC723x and draft 00 . . . . . . . . . . . . . . 195 327 D.2. Since draft-ietf-httpbis-semantics-00 . . . . . . . . . . 195 328 D.3. Since draft-ietf-httpbis-semantics-01 . . . . . . . . . . 196 329 D.4. Since draft-ietf-httpbis-semantics-02 . . . . . . . . . . 197 330 D.5. Since draft-ietf-httpbis-semantics-03 . . . . . . . . . . 198 331 D.6. Since draft-ietf-httpbis-semantics-04 . . . . . . . . . . 199 332 D.7. Since draft-ietf-httpbis-semantics-05 . . . . . . . . . . 199 333 D.8. Since draft-ietf-httpbis-semantics-06 . . . . . . . . . . 201 334 D.9. Since draft-ietf-httpbis-semantics-07 . . . . . . . . . . 202 335 D.10. Since draft-ietf-httpbis-semantics-08 . . . . . . . . . . 203 336 D.11. Since draft-ietf-httpbis-semantics-09 . . . . . . . . . . 204 337 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 205 338 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 205 340 1. Introduction 342 The Hypertext Transfer Protocol (HTTP) is a stateless application- 343 level request/response protocol that uses extensible semantics and 344 self-descriptive messages for flexible interaction with network-based 345 hypertext information systems. HTTP is defined by a series of 346 documents that collectively form the HTTP/1.1 specification: 348 o "HTTP Semantics" (this document) 350 o "HTTP Caching" [Caching] 352 o "HTTP/1.1 Messaging" [Messaging] 354 HTTP is a generic interface protocol for information systems. It is 355 designed to hide the details of how a service is implemented by 356 presenting a uniform interface to clients that is independent of the 357 types of resources provided. Likewise, servers do not need to be 358 aware of each client's purpose: an HTTP request can be considered in 359 isolation rather than being associated with a specific type of client 360 or a predetermined sequence of application steps. The result is a 361 protocol that can be used effectively in many different contexts and 362 for which implementations can evolve independently over time. 364 HTTP is also designed for use as an intermediation protocol for 365 translating communication to and from non-HTTP information systems. 366 HTTP proxies and gateways can provide access to alternative 367 information services by translating their diverse protocols into a 368 hypertext format that can be viewed and manipulated by clients in the 369 same way as HTTP services. 371 One consequence of this flexibility is that the protocol cannot be 372 defined in terms of what occurs behind the interface. Instead, we 373 are limited to defining the syntax of communication, the intent of 374 received communication, and the expected behavior of recipients. If 375 the communication is considered in isolation, then successful actions 376 ought to be reflected in corresponding changes to the observable 377 interface provided by servers. However, since multiple clients might 378 act in parallel and perhaps at cross-purposes, we cannot require that 379 such changes be observable beyond the scope of a single response. 381 Each HTTP message is either a request or a response. A server 382 listens on a connection for a request, parses each message received, 383 interprets the message semantics in relation to the identified target 384 resource, and responds to that request with one or more response 385 messages. A client constructs request messages to communicate 386 specific intentions, examines received responses to see if the 387 intentions were carried out, and determines how to interpret the 388 results. 390 HTTP provides a uniform interface for interacting with a resource 391 (Section 2.5), regardless of its type, nature, or implementation, via 392 the manipulation and transfer of representations (Section 7). 394 This document defines semantics that are common to all versions of 395 HTTP. HTTP semantics include the intentions defined by each request 396 method (Section 8), extensions to those semantics that might be 397 described in request header fields (Section 9), the meaning of status 398 codes to indicate a machine-readable response (Section 10), and the 399 meaning of other control data and resource metadata that might be 400 given in response header fields (Section 11). 402 This document also defines representation metadata that describe how 403 a payload is intended to be interpreted by a recipient, the request 404 header fields that might influence content selection, and the various 405 selection algorithms that are collectively referred to as "content 406 negotiation" (Section 7.4). 408 This document defines HTTP range requests, partial responses, and the 409 multipart/byteranges media type. 411 This document obsoletes the portions of RFC 7230 that are independent 412 of the HTTP/1.1 messaging syntax and connection management, with the 413 changes being summarized in Appendix B.2. The other parts of RFC 414 7230 are obsoleted by "HTTP/1.1 Messaging" [Messaging]. This 415 document also obsoletes RFC 2818 (see Appendix B.1), RFC 7231 (see 416 Appendix B.3), RFC 7232 (see Appendix B.4), RFC 7233 (see 417 Appendix B.5), RFC 7235 (see Appendix B.6), RFC 7538 (see 418 Appendix B.7), RFC 7615 (see Appendix B.8), and RFC 7694 (see 419 Appendix C). 421 1.1. Requirements Notation 423 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 424 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 425 "OPTIONAL" in this document are to be interpreted as described in BCP 426 14 [RFC2119] [RFC8174] when, and only when, they appear in all 427 capitals, as shown here. 429 Conformance criteria and considerations regarding error handling are 430 defined in Section 3. 432 1.2. Syntax Notation 434 This specification uses the Augmented Backus-Naur Form (ABNF) 435 notation of [RFC5234], extended with the notation for case- 436 sensitivity in strings defined in [RFC7405]. 438 It also uses a list extension, defined in Section 5.5, that allows 439 for compact definition of comma-separated lists using a '#' operator 440 (similar to how the '*' operator indicates repetition). Appendix A 441 shows the collected grammar with all list operators expanded to 442 standard ABNF notation. 444 As a convention, ABNF rule names prefixed with "obs-" denote 445 "obsolete" grammar rules that appear for historical reasons. 447 The following core rules are included by reference, as defined in 448 Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), 449 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 450 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF 451 (line feed), OCTET (any 8-bit sequence of data), SP (space), and 452 VCHAR (any visible US-ASCII character). 454 Section 5.4.1 defines some generic syntactic components for field 455 values. 457 The rules below are defined in [Messaging]: 459 protocol-name = 460 protocol-version = 462 This specification uses the terms "character", "character encoding 463 scheme", "charset", and "protocol element" as they are defined in 464 [RFC6365]. 466 1.2.1. Whitespace 468 This specification uses three rules to denote the use of linear 469 whitespace: OWS (optional whitespace), RWS (required whitespace), and 470 BWS ("bad" whitespace). 472 The OWS rule is used where zero or more linear whitespace octets 473 might appear. For protocol elements where optional whitespace is 474 preferred to improve readability, a sender SHOULD generate the 475 optional whitespace as a single SP; otherwise, a sender SHOULD NOT 476 generate optional whitespace except as needed to white out invalid or 477 unwanted protocol elements during in-place message filtering. 479 The RWS rule is used when at least one linear whitespace octet is 480 required to separate field tokens. A sender SHOULD generate RWS as a 481 single SP. 483 OWS and RWS have the same semantics as a single SP. Any content 484 known to be defined as OWS or RWS MAY be replaced with a single SP 485 before interpreting it or forwarding the message downstream. 487 The BWS rule is used where the grammar allows optional whitespace 488 only for historical reasons. A sender MUST NOT generate BWS in 489 messages. A recipient MUST parse for such bad whitespace and remove 490 it before interpreting the protocol element. 492 BWS has no semantics. Any content known to be defined as BWS MAY be 493 removed before interpreting it or forwarding the message downstream. 495 OWS = *( SP / HTAB ) 496 ; optional whitespace 497 RWS = 1*( SP / HTAB ) 498 ; required whitespace 499 BWS = OWS 500 ; "bad" whitespace 502 2. Architecture 504 HTTP was created for the World Wide Web (WWW) architecture and has 505 evolved over time to support the scalability needs of a worldwide 506 hypertext system. Much of that architecture is reflected in the 507 terminology and syntax productions used to define HTTP. 509 2.1. Client/Server Messaging 511 HTTP is a stateless request/response protocol that operates by 512 exchanging messages across a reliable transport- or session-layer 513 "connection". An HTTP "client" is a program that establishes a 514 connection to a server for the purpose of sending one or more HTTP 515 requests. An HTTP "server" is a program that accepts connections in 516 order to service HTTP requests by sending HTTP responses. 518 The terms "client" and "server" refer only to the roles that these 519 programs perform for a particular connection. The same program might 520 act as a client on some connections and a server on others. The term 521 "user agent" refers to any of the various client programs that 522 initiate a request, including (but not limited to) browsers, spiders 523 (web-based robots), command-line tools, custom applications, and 524 mobile apps. The term "origin server" refers to the program that can 525 originate authoritative responses for a given target resource. The 526 terms "sender" and "recipient" refer to any implementation that sends 527 or receives a given message, respectively. 529 HTTP relies upon the Uniform Resource Identifier (URI) standard 530 [RFC3986] to indicate the target resource (Section 6.1) and 531 relationships between resources. 533 Most HTTP communication consists of a retrieval request (GET) for a 534 representation of some resource identified by a URI. In the simplest 535 case, this might be accomplished via a single bidirectional 536 connection (===) between the user agent (UA) and the origin server 537 (O). 539 request > 540 UA ======================================= O 541 < response 543 Figure 1 545 Each major version of HTTP defines its own syntax for the inclusion 546 of information in messages. Nevertheless, a common abstraction is 547 that a message includes some form of envelope/framing, a potential 548 set of named fields up front (a header section), a potential body, 549 and a potential following set of named fields (a trailer section). 551 A client sends an HTTP request to a server in the form of a request 552 message with a method (Section 8) and request target. The request 553 might also contain header fields for request modifiers, client 554 information, and representation metadata (Section 5), a payload body 555 (Section 7.3.3) to be processed in accordance with the method, and 556 trailer fields for metadata collected while sending the payload. 558 A server responds to a client's request by sending one or more HTTP 559 response messages, each including a success or error code 560 (Section 10). The response might also contain header fields for 561 server information, resource metadata, and representation metadata 562 (Section 5), a payload body (Section 7.3.3) to be interpreted in 563 accordance with the status code, and trailer fields for metadata 564 collected while sending the payload. 566 One of the functions of the message framing mechanism is to assure 567 that messages are complete. A message is considered complete when 568 all of the octets indicated by its framing are available. Note that, 569 when no explicit framing is used, a response message that is ended by 570 the transport connection's close is considered complete even though 571 it might be indistinguishable from an incomplete response, unless a 572 transport-level error indicates that it is not complete. 574 A connection might be used for multiple request/response exchanges. 575 The mechanism used to correlate between request and response messages 576 is version dependent; some versions of HTTP use implicit ordering of 577 messages, while others use an explicit identifier. 579 Responses (both final and interim) can be sent at any time after a 580 request is received, even if it is not yet complete. However, 581 clients (including intermediaries) might abandon a request if the 582 response is not forthcoming within a reasonable period of time. 584 The following example illustrates a typical message exchange for a 585 GET request (Section 8.3.1) on the URI "http://www.example.com/ 586 hello.txt": 588 Client request: 590 GET /hello.txt HTTP/1.1 591 User-Agent: curl/7.16.3 libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3 592 Host: www.example.com 593 Accept-Language: en, mi 595 Server response: 597 HTTP/1.1 200 OK 598 Date: Mon, 27 Jul 2009 12:28:53 GMT 599 Server: Apache 600 Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT 601 ETag: "34aa387-d-1568eb00" 602 Accept-Ranges: bytes 603 Content-Length: 51 604 Vary: Accept-Encoding 605 Content-Type: text/plain 607 Hello World! My payload includes a trailing CRLF. 609 2.2. Intermediaries 611 HTTP enables the use of intermediaries to satisfy requests through a 612 chain of connections. There are three common forms of HTTP 613 intermediary: proxy, gateway, and tunnel. In some cases, a single 614 intermediary might act as an origin server, proxy, gateway, or 615 tunnel, switching behavior based on the nature of each request. 617 > > > > 618 UA =========== A =========== B =========== C =========== O 619 < < < < 621 Figure 2 623 The figure above shows three intermediaries (A, B, and C) between the 624 user agent and origin server. A request or response message that 625 travels the whole chain will pass through four separate connections. 626 Some HTTP communication options might apply only to the connection 627 with the nearest, non-tunnel neighbor, only to the endpoints of the 628 chain, or to all connections along the chain. Although the diagram 629 is linear, each participant might be engaged in multiple, 630 simultaneous communications. For example, B might be receiving 631 requests from many clients other than A, and/or forwarding requests 632 to servers other than C, at the same time that it is handling A's 633 request. Likewise, later requests might be sent through a different 634 path of connections, often based on dynamic configuration for load 635 balancing. 637 The terms "upstream" and "downstream" are used to describe 638 directional requirements in relation to the message flow: all 639 messages flow from upstream to downstream. The terms "inbound" and 640 "outbound" are used to describe directional requirements in relation 641 to the request route: "inbound" means toward the origin server and 642 "outbound" means toward the user agent. 644 A "proxy" is a message-forwarding agent that is selected by the 645 client, usually via local configuration rules, to receive requests 646 for some type(s) of absolute URI and attempt to satisfy those 647 requests via translation through the HTTP interface. Some 648 translations are minimal, such as for proxy requests for "http" URIs, 649 whereas other requests might require translation to and from entirely 650 different application-level protocols. Proxies are often used to 651 group an organization's HTTP requests through a common intermediary 652 for the sake of security, annotation services, or shared caching. 653 Some proxies are designed to apply transformations to selected 654 messages or payloads while they are being forwarded, as described in 655 Section 6.7.2. 657 A "gateway" (a.k.a. "reverse proxy") is an intermediary that acts as 658 an origin server for the outbound connection but translates received 659 requests and forwards them inbound to another server or servers. 660 Gateways are often used to encapsulate legacy or untrusted 661 information services, to improve server performance through 662 "accelerator" caching, and to enable partitioning or load balancing 663 of HTTP services across multiple machines. 665 All HTTP requirements applicable to an origin server also apply to 666 the outbound communication of a gateway. A gateway communicates with 667 inbound servers using any protocol that it desires, including private 668 extensions to HTTP that are outside the scope of this specification. 669 However, an HTTP-to-HTTP gateway that wishes to interoperate with 670 third-party HTTP servers ought to conform to user agent requirements 671 on the gateway's inbound connection. 673 A "tunnel" acts as a blind relay between two connections without 674 changing the messages. Once active, a tunnel is not considered a 675 party to the HTTP communication, though the tunnel might have been 676 initiated by an HTTP request. A tunnel ceases to exist when both 677 ends of the relayed connection are closed. Tunnels are used to 678 extend a virtual connection through an intermediary, such as when 679 Transport Layer Security (TLS, [RFC8446]) is used to establish 680 confidential communication through a shared firewall proxy. 682 The above categories for intermediary only consider those acting as 683 participants in the HTTP communication. There are also 684 intermediaries that can act on lower layers of the network protocol 685 stack, filtering or redirecting HTTP traffic without the knowledge or 686 permission of message senders. Network intermediaries are 687 indistinguishable (at a protocol level) from a man-in-the-middle 688 attack, often introducing security flaws or interoperability problems 689 due to mistakenly violating HTTP semantics. 691 For example, an "interception proxy" [RFC3040] (also commonly known 692 as a "transparent proxy" [RFC1919] or "captive portal") differs from 693 an HTTP proxy because it is not selected by the client. Instead, an 694 interception proxy filters or redirects outgoing TCP port 80 packets 695 (and occasionally other common port traffic). Interception proxies 696 are commonly found on public network access points, as a means of 697 enforcing account subscription prior to allowing use of non-local 698 Internet services, and within corporate firewalls to enforce network 699 usage policies. 701 HTTP is defined as a stateless protocol, meaning that each request 702 message can be understood in isolation. Many implementations depend 703 on HTTP's stateless design in order to reuse proxied connections or 704 dynamically load balance requests across multiple servers. Hence, a 705 server MUST NOT assume that two requests on the same connection are 706 from the same user agent unless the connection is secured and 707 specific to that agent. Some non-standard HTTP extensions (e.g., 708 [RFC4559]) have been known to violate this requirement, resulting in 709 security and interoperability problems. 711 2.3. Caches 713 A "cache" is a local store of previous response messages and the 714 subsystem that controls its message storage, retrieval, and deletion. 715 A cache stores cacheable responses in order to reduce the response 716 time and network bandwidth consumption on future, equivalent 717 requests. Any client or server MAY employ a cache, though a cache 718 cannot be used by a server while it is acting as a tunnel. 720 The effect of a cache is that the request/response chain is shortened 721 if one of the participants along the chain has a cached response 722 applicable to that request. The following illustrates the resulting 723 chain if B has a cached copy of an earlier response from O (via C) 724 for a request that has not been cached by UA or A. 726 > > 727 UA =========== A =========== B - - - - - - C - - - - - - O 728 < < 730 Figure 3 732 A response is "cacheable" if a cache is allowed to store a copy of 733 the response message for use in answering subsequent requests. Even 734 when a response is cacheable, there might be additional constraints 735 placed by the client or by the origin server on when that cached 736 response can be used for a particular request. HTTP requirements for 737 cache behavior and cacheable responses are defined in Section 2 of 738 [Caching]. 740 There is a wide variety of architectures and configurations of caches 741 deployed across the World Wide Web and inside large organizations. 742 These include national hierarchies of proxy caches to save 743 transoceanic bandwidth, collaborative systems that broadcast or 744 multicast cache entries, archives of pre-fetched cache entries for 745 use in off-line or high-latency environments, and so on. 747 2.4. Uniform Resource Identifiers 749 Uniform Resource Identifiers (URIs) [RFC3986] are used throughout 750 HTTP as the means for identifying resources (Section 2.5). URI 751 references are used to target requests, indicate redirects, and 752 define relationships. 754 The definitions of "URI-reference", "absolute-URI", "relative-part", 755 "authority", "port", "host", "path-abempty", "segment", and "query" 756 are adopted from the URI generic syntax. An "absolute-path" rule is 757 defined for protocol elements that can contain a non-empty path 758 component. (This rule differs slightly from the path-abempty rule of 759 RFC 3986, which allows for an empty path to be used in references, 760 and path-absolute rule, which does not allow paths that begin with 761 "//".) A "partial-URI" rule is defined for protocol elements that 762 can contain a relative URI but not a fragment component. 764 URI-reference = 765 absolute-URI = 766 relative-part = 767 authority = 768 uri-host = 769 port = 770 path-abempty = 771 segment = 772 query = 774 absolute-path = 1*( "/" segment ) 775 partial-URI = relative-part [ "?" query ] 777 Each protocol element in HTTP that allows a URI reference will 778 indicate in its ABNF production whether the element allows any form 779 of reference (URI-reference), only a URI in absolute form (absolute- 780 URI), only the path and optional query components, or some 781 combination of the above. Unless otherwise indicated, URI references 782 are parsed relative to the target URI (Section 6.1). 784 It is RECOMMENDED that all senders and recipients support, at a 785 minimum, URIs with lengths of 8000 octets in protocol elements. Note 786 that this implies some structures and on-wire representations (for 787 example, the request line in HTTP/1.1) will necessarily be larger in 788 some cases. 790 2.5. Resources 792 The target of an HTTP request is called a "resource". HTTP does not 793 limit the nature of a resource; it merely defines an interface that 794 might be used to interact with resources. Most resources are 795 identified by a Uniform Resource Identifier (URI), as described in 796 Section 2.4. 798 One design goal of HTTP is to separate resource identification from 799 request semantics, which is made possible by vesting the request 800 semantics in the request method (Section 8) and a few request- 801 modifying header fields (Section 9). If there is a conflict between 802 the method semantics and any semantic implied by the URI itself, as 803 described in Section 8.2.1, the method semantics take precedence. 805 IANA maintains the registry of URI Schemes [BCP35] at 806 . Although requests 807 might target any URI scheme, the following schemes are inherent to 808 HTTP servers: 810 +------------+------------------------------------+---------------+ 811 | URI Scheme | Description | Reference | 812 | http | Hypertext Transfer Protocol | Section 2.5.1 | 813 | https | Hypertext Transfer Protocol Secure | Section 2.5.2 | 814 +------------+------------------------------------+---------------+ 816 Table 1 818 Note that the presence of an "http" or "https" URI does not imply 819 that there is always an HTTP server at the identified origin 820 listening for connections. Anyone can mint a URI, whether or not a 821 server exists and whether or not that server currently maps that 822 identifier to a resource. The delegated nature of registered names 823 and IP addresses creates a federated namespace whether or not an HTTP 824 server is present. 826 2.5.1. http URI Scheme 828 The "http" URI scheme is hereby defined for minting identifiers 829 within the hierarchical namespace governed by a potential HTTP origin 830 server listening for TCP ([RFC0793]) connections on a given port. 832 http-URI = "http" "://" authority path-abempty [ "?" query ] 834 The origin server for an "http" URI is identified by the authority 835 component, which includes a host identifier and optional port number 836 ([RFC3986], Section 3.2.2). If the port subcomponent is empty or not 837 given, TCP port 80 (the reserved port for WWW services) is the 838 default. The origin determines who has the right to respond 839 authoritatively to requests that target the identified resource, as 840 defined in Section 6.4.1. 842 A sender MUST NOT generate an "http" URI with an empty host 843 identifier. A recipient that processes such a URI reference MUST 844 reject it as invalid. 846 The hierarchical path component and optional query component identify 847 the target resource within that origin server's name space. 849 2.5.2. https URI Scheme 851 The "https" URI scheme is hereby defined for minting identifiers 852 within the hierarchical namespace governed by a potential origin 853 server listening for TCP connections on a given port and capable of 854 establishing a TLS ([RFC8446]) connection that has been secured for 855 HTTP communication. In this context, "secured" specifically means 856 that the server has been authenticated as acting on behalf of the 857 identified authority and all HTTP communication with that server has 858 been protected for confidentiality and integrity through the use of 859 strong encryption. 861 https-URI = "https" "://" authority path-abempty [ "?" query ] 863 The origin server for an "https" URI is identified by the authority 864 component, which includes a host identifier and optional port number 865 ([RFC3986], Section 3.2.2). If the port subcomponent is empty or not 866 given, TCP port 443 (the reserved port for HTTP over TLS) is the 867 default. The origin determines who has the right to respond 868 authoritatively to requests that target the identified resource, as 869 defined in Section 6.4.2. 871 A sender MUST NOT generate an "https" URI with an empty host 872 identifier. A recipient that processes such a URI reference MUST 873 reject it as invalid. 875 The hierarchical path component and optional query component identify 876 the target resource within that origin server's name space. 878 A client MUST ensure that its HTTP requests for an "https" resource 879 are secured, prior to being communicated, and that it only accepts 880 secured responses to those requests. 882 Resources made available via the "https" scheme have no shared 883 identity with the "http" scheme. They are distinct origins with 884 separate namespaces. However, an extension to HTTP that is defined 885 to apply to all origins with the same host, such as the Cookie 886 protocol [RFC6265], can allow information set by one service to 887 impact communication with other services within a matching group of 888 host domains. 890 2.5.3. http and https URI Normalization and Comparison 892 Since the "http" and "https" schemes conform to the URI generic 893 syntax, such URIs are normalized and compared according to the 894 algorithm defined in Section 6 of [RFC3986], using the defaults 895 described above for each scheme. 897 If the port is equal to the default port for a scheme, the normal 898 form is to omit the port subcomponent. When not being used as the 899 target of an OPTIONS request, an empty path component is equivalent 900 to an absolute path of "/", so the normal form is to provide a path 901 of "/" instead. The scheme and host are case-insensitive and 902 normally provided in lowercase; all other components are compared in 903 a case-sensitive manner. Characters other than those in the 904 "reserved" set are equivalent to their percent-encoded octets: the 905 normal form is to not encode them (see Sections 2.1 and 2.2 of 906 [RFC3986]). 908 For example, the following three URIs are equivalent: 910 http://example.com:80/~smith/home.html 911 http://EXAMPLE.com/%7Esmith/home.html 912 http://EXAMPLE.com:/%7esmith/home.html 914 2.5.4. Deprecated userinfo 916 The URI generic syntax for authority also includes a userinfo 917 subcomponent ([RFC3986], Section 3.2.1) for including user 918 authentication information in the URI. In that subcomponent, the use 919 of the format "user:password" is deprecated. 921 Some implementations make use of the userinfo component for internal 922 configuration of authentication information, such as within command 923 invocation options, configuration files, or bookmark lists, even 924 though such usage might expose a user identifier or password. 926 A sender MUST NOT generate the userinfo subcomponent (and its "@" 927 delimiter) when an "http" or "https" URI reference is generated 928 within a message as a target URI or field value. 930 Before making use of an "http" or "https" URI reference received from 931 an untrusted source, a recipient SHOULD parse for userinfo and treat 932 its presence as an error; it is likely being used to obscure the 933 authority for the sake of phishing attacks. 935 2.5.5. Fragment Identifiers on http(s) URI References 937 Fragment identifiers allow for indirect identification of a secondary 938 resource, independent of the URI scheme, as defined in Section 3.5 of 939 [RFC3986]. Some protocol elements that refer to a URI allow 940 inclusion of a fragment, while others do not. They are distinguished 941 by use of the ABNF rule for elements where fragment is allowed; 942 otherwise, a specific rule that excludes fragments is used (see 943 Section 6.1). 945 | *Note:* the fragment identifier component is not part of the 946 | actual scheme definition for a URI scheme (see Section 4.3 of 947 | [RFC3986]), thus does not appear in the ABNF definitions for 948 | the "http" and "https" URI schemes above. 950 3. Conformance 952 3.1. Implementation Diversity 954 When considering the design of HTTP, it is easy to fall into a trap 955 of thinking that all user agents are general-purpose browsers and all 956 origin servers are large public websites. That is not the case in 957 practice. Common HTTP user agents include household appliances, 958 stereos, scales, firmware update scripts, command-line programs, 959 mobile apps, and communication devices in a multitude of shapes and 960 sizes. Likewise, common HTTP origin servers include home automation 961 units, configurable networking components, office machines, 962 autonomous robots, news feeds, traffic cameras, ad selectors, and 963 video-delivery platforms. 965 The term "user agent" does not imply that there is a human user 966 directly interacting with the software agent at the time of a 967 request. In many cases, a user agent is installed or configured to 968 run in the background and save its results for later inspection (or 969 save only a subset of those results that might be interesting or 970 erroneous). Spiders, for example, are typically given a start URI 971 and configured to follow certain behavior while crawling the Web as a 972 hypertext graph. 974 The implementation diversity of HTTP means that not all user agents 975 can make interactive suggestions to their user or provide adequate 976 warning for security or privacy concerns. In the few cases where 977 this specification requires reporting of errors to the user, it is 978 acceptable for such reporting to only be observable in an error 979 console or log file. Likewise, requirements that an automated action 980 be confirmed by the user before proceeding might be met via advance 981 configuration choices, run-time options, or simple avoidance of the 982 unsafe action; confirmation does not imply any specific user 983 interface or interruption of normal processing if the user has 984 already made that choice. 986 3.2. Role-based Requirements 988 This specification targets conformance criteria according to the role 989 of a participant in HTTP communication. Hence, HTTP requirements are 990 placed on senders, recipients, clients, servers, user agents, 991 intermediaries, origin servers, proxies, gateways, or caches, 992 depending on what behavior is being constrained by the requirement. 993 Additional (social) requirements are placed on implementations, 994 resource owners, and protocol element registrations when they apply 995 beyond the scope of a single communication. 997 The verb "generate" is used instead of "send" where a requirement 998 differentiates between creating a protocol element and merely 999 forwarding a received element downstream. 1001 An implementation is considered conformant if it complies with all of 1002 the requirements associated with the roles it partakes in HTTP. 1004 Conformance includes both the syntax and semantics of protocol 1005 elements. A sender MUST NOT generate protocol elements that convey a 1006 meaning that is known by that sender to be false. A sender MUST NOT 1007 generate protocol elements that do not match the grammar defined by 1008 the corresponding ABNF rules. Within a given message, a sender MUST 1009 NOT generate protocol elements or syntax alternatives that are only 1010 allowed to be generated by participants in other roles (i.e., a role 1011 that the sender does not have for that message). 1013 3.3. Parsing Elements 1015 When a received protocol element is parsed, the recipient MUST be 1016 able to parse any value of reasonable length that is applicable to 1017 the recipient's role and that matches the grammar defined by the 1018 corresponding ABNF rules. Note, however, that some received protocol 1019 elements might not be parsed. For example, an intermediary 1020 forwarding a message might parse a field into generic field name and 1021 field value components, but then forward the field without further 1022 parsing inside the field value. 1024 HTTP does not have specific length limitations for many of its 1025 protocol elements because the lengths that might be appropriate will 1026 vary widely, depending on the deployment context and purpose of the 1027 implementation. Hence, interoperability between senders and 1028 recipients depends on shared expectations regarding what is a 1029 reasonable length for each protocol element. Furthermore, what is 1030 commonly understood to be a reasonable length for some protocol 1031 elements has changed over the course of the past two decades of HTTP 1032 use and is expected to continue changing in the future. 1034 At a minimum, a recipient MUST be able to parse and process protocol 1035 element lengths that are at least as long as the values that it 1036 generates for those same protocol elements in other messages. For 1037 example, an origin server that publishes very long URI references to 1038 its own resources needs to be able to parse and process those same 1039 references when received as a target URI. 1041 3.4. Error Handling 1043 A recipient MUST interpret a received protocol element according to 1044 the semantics defined for it by this specification, including 1045 extensions to this specification, unless the recipient has determined 1046 (through experience or configuration) that the sender incorrectly 1047 implements what is implied by those semantics. For example, an 1048 origin server might disregard the contents of a received 1049 Accept-Encoding header field if inspection of the User-Agent header 1050 field indicates a specific implementation version that is known to 1051 fail on receipt of certain content codings. 1053 Unless noted otherwise, a recipient MAY attempt to recover a usable 1054 protocol element from an invalid construct. HTTP does not define 1055 specific error handling mechanisms except when they have a direct 1056 impact on security, since different applications of the protocol 1057 require different error handling strategies. For example, a Web 1058 browser might wish to transparently recover from a response where the 1059 Location header field doesn't parse according to the ABNF, whereas a 1060 systems control client might consider any form of error recovery to 1061 be dangerous. 1063 Some requests can be automatically retried by a client in the event 1064 of an underlying connection failure, as described in Section 8.2.2. 1066 4. Extending and Versioning HTTP 1068 While HTTP's core semantics don't change between protocol versions, 1069 the expression of them "on the wire" can change, and so the HTTP 1070 version number changes when incompatible changes are made to the wire 1071 format. Additionally, HTTP allows incremental, backwards-compatible 1072 changes to be made to the protocol without changing its version 1073 through the use of defined extension points. 1075 4.1. Extending HTTP 1077 HTTP defines a number of generic extension points that can be used to 1078 introduce capabilities to the protocol without introducing a new 1079 version, including methods (Section 8.4), status codes 1080 (Section 10.7), header and trailer fields (Section 5.7), and further 1081 extensibility points within defined fields (such as Cache-Control in 1082 Section 5.2.3 of [Caching]). Because the semantics of HTTP are not 1083 versioned, these extension points are persistent; the version of the 1084 protocol in use does not affect their semantics. 1086 Version-independent extensions are discouraged from depending on or 1087 interacting with the specific version of the protocol in use. When 1088 this is unavoidable, careful consideration needs to be given to how 1089 the extension can interoperate across versions. 1091 Additionally, specific versions of HTTP might have their own 1092 extensibility points, such as transfer-codings in HTTP/1.1 1093 (Section 6.1 of [Messaging]) and HTTP/2 ([RFC7540]) SETTINGS or frame 1094 types. These extension points are specific to the version of the 1095 protocol they occur within. 1097 Version-specific extensions cannot override or modify the semantics 1098 of a version-independent mechanism or extension point (like a method 1099 or header field) without explicitly being allowed by that protocol 1100 element. For example, the CONNECT method (Section 8.3.6) allows 1101 this. 1103 These guidelines assure that the protocol operates correctly and 1104 predictably, even when parts of the path implement different versions 1105 of HTTP. 1107 4.2. Protocol Versioning 1109 The HTTP version number consists of two decimal digits separated by a 1110 "." (period or decimal point). The first digit ("major version") 1111 indicates the HTTP messaging syntax, whereas the second digit ("minor 1112 version") indicates the highest minor version within that major 1113 version to which the sender is conformant and able to understand for 1114 future communication. 1116 The protocol version as a whole indicates the sender's conformance 1117 with the set of requirements laid out in that version's corresponding 1118 specification of HTTP. For example, the version "HTTP/1.1" is 1119 defined by the combined specifications of this document, "HTTP 1120 Caching" [Caching], and "HTTP/1.1 Messaging" [Messaging]. 1122 The minor version advertises the sender's communication capabilities 1123 even when the sender is only using a backwards-compatible subset of 1124 the protocol, thereby letting the recipient know that more advanced 1125 features can be used in response (by servers) or in future requests 1126 (by clients). 1128 A client SHOULD send a request version equal to the highest version 1129 to which the client is conformant and whose major version is no 1130 higher than the highest version supported by the server, if this is 1131 known. A client MUST NOT send a version to which it is not 1132 conformant. 1134 A client MAY send a lower request version if it is known that the 1135 server incorrectly implements the HTTP specification, but only after 1136 the client has attempted at least one normal request and determined 1137 from the response status code or header fields (e.g., Server) that 1138 the server improperly handles higher request versions. 1140 A server SHOULD send a response version equal to the highest version 1141 to which the server is conformant that has a major version less than 1142 or equal to the one received in the request. A server MUST NOT send 1143 a version to which it is not conformant. A server can send a 505 1144 (HTTP Version Not Supported) response if it wishes, for any reason, 1145 to refuse service of the client's major protocol version. 1147 HTTP's major version number is incremented when an incompatible 1148 message syntax is introduced. The minor number is incremented when 1149 changes made to the protocol have the effect of adding to the message 1150 semantics or implying additional capabilities of the sender. 1152 When an HTTP message is received with a major version number that the 1153 recipient implements, but a higher minor version number than what the 1154 recipient implements, the recipient SHOULD process the message as if 1155 it were in the highest minor version within that major version to 1156 which the recipient is conformant. A recipient can assume that a 1157 message with a higher minor version, when sent to a recipient that 1158 has not yet indicated support for that higher version, is 1159 sufficiently backwards-compatible to be safely processed by any 1160 implementation of the same major version. 1162 When a major version of HTTP does not define any minor versions, the 1163 minor version "0" is implied and is used when referring to that 1164 protocol within a protocol element that requires sending a minor 1165 version. 1167 5. Header and Trailer Fields 1169 HTTP messages use key/value pairs to convey data about the message, 1170 its payload, the target resource, or the connection (i.e., control 1171 data). They are called "HTTP fields" or just "fields". 1173 Every message can have two separate areas that such fields can occur 1174 within; the "header field section" (or just "header section") 1175 preceding the message body and containing "header fields" (or just 1176 "headers", colloquially) and the "trailer field section" (or just 1177 "trailer section") after the message body containing "trailer fields" 1178 (or just "trailers" colloquially). Header fields are more common; 1179 see Section 5.6 for discussion of the applicability and limitations 1180 of trailer fields. 1182 Both sections are composed of any number of "field lines", each with 1183 a "field name" (see Section 5.3) identifying the field, and a "field 1184 line value" that conveys data for the field. 1186 Each field name present in a section has a corresponding "field 1187 value" for that section, composed from all field line values with 1188 that given field name in that section, concatenated together and 1189 separated with commas. See Section 5.1 for further discussion of the 1190 semantics of field ordering and combination in messages, and 1191 Section 5.4 for more discussion of field values. 1193 For example, this section: 1195 Example-Field: Foo, Bar 1196 Example-Field: Baz 1198 contains two field lines, both with the field name "Example-Field". 1199 The first field line has a field line value of "Foo, Bar", while the 1200 second field line value is "Baz". The field value for "Example- 1201 Field" is a list with three members: "Foo", "Bar", and "Baz". 1203 The interpretation of a field does not change between minor versions 1204 of the same major HTTP version, though the default behavior of a 1205 recipient in the absence of such a field can change. Unless 1206 specified otherwise, fields are defined for all versions of HTTP. In 1207 particular, the Host and Connection fields ought to be implemented by 1208 all HTTP/1.x implementations whether or not they advertise 1209 conformance with HTTP/1.1. 1211 New fields can be introduced without changing the protocol version if 1212 their defined semantics allow them to be safely ignored by recipients 1213 that do not recognize them; see Section 5.3.1. 1215 5.1. Field Ordering and Combination 1217 The order in which field lines with differing names are received in a 1218 message is not significant. However, it is good practice to send 1219 header fields that contain control data first, such as Host on 1220 requests and Date on responses, so that implementations can decide 1221 when not to handle a message as early as possible. A server MUST NOT 1222 apply a request to the target resource until the entire request 1223 header section is received, since later header field lines might 1224 include conditionals, authentication credentials, or deliberately 1225 misleading duplicate header fields that would impact request 1226 processing. 1228 A recipient MAY combine multiple field lines with the same field name 1229 into one field line, without changing the semantics of the message, 1230 by appending each subsequent field line value to the initial field 1231 line value in order, separated by a comma and OWS (optional 1232 whitespace). For consistency, use comma SP. 1234 The order in which field lines with the same name are received is 1235 therefore significant to the interpretation of the field value; a 1236 proxy MUST NOT change the order of these field line values when 1237 forwarding a message. 1239 This means that, aside from the well-known exception noted below, a 1240 sender MUST NOT generate multiple field lines with the same name in a 1241 message (whether in the headers or trailers), or append a field line 1242 when a field line of the same name already exists in the message, 1243 unless that field's definition allows multiple field line values to 1244 be recombined as a comma-separated list [i.e., at least one 1245 alternative of the field's definition allows a comma-separated list, 1246 such as an ABNF rule of #(values) defined in Section 5.5]. 1248 | *Note:* In practice, the "Set-Cookie" header field ([RFC6265]) 1249 | often appears in a response message across multiple field lines 1250 | and does not use the list syntax, violating the above 1251 | requirements on multiple field lines with the same field name. 1252 | Since it cannot be combined into a single field value, 1253 | recipients ought to handle "Set-Cookie" as a special case while 1254 | processing fields. (See Appendix A.2.3 of [Kri2001] for 1255 | details.) 1257 5.2. Field Limits 1259 HTTP does not place a predefined limit on the length of each field 1260 line, field value, or on the length of the header or trailer section 1261 as a whole, as described in Section 3. Various ad hoc limitations on 1262 individual lengths are found in practice, often depending on the 1263 specific field's semantics. 1265 A server that receives a request header field line, field value, or 1266 set of fields larger than it wishes to process MUST respond with an 1267 appropriate 4xx (Client Error) status code. Ignoring such header 1268 fields would increase the server's vulnerability to request smuggling 1269 attacks (Section 11.2 of [Messaging]). 1271 A client MAY discard or truncate received field lines that are larger 1272 than the client wishes to process if the field semantics are such 1273 that the dropped value(s) can be safely ignored without changing the 1274 message framing or response semantics. 1276 5.3. Field Names 1278 The field-name token labels the corresponding field value as having 1279 the semantics defined by that field. For example, the Date header 1280 field is defined in Section 11.1.1 as containing the origination 1281 timestamp for the message in which it appears. 1283 field-name = token 1285 Field names are case-insensitive and ought to be registered within 1286 the "Hypertext Transfer Protocol (HTTP) Field Name Registry"; see 1287 Section 5.3.2. 1289 Authors of specifications defining new fields are advised to choose a 1290 short but descriptive field name. Short names avoid needless data 1291 transmission; descriptive names avoid confusion and "squatting" on 1292 names that might have broader uses. 1294 To that end, limited-use fields (such as a header confined to a 1295 single application or use case) are encouraged to use a name that 1296 includes its name (or an abbreviation) as a prefix; for example, if 1297 the Foo Application needs a Description field, it might use "Foo- 1298 Desc"; "Description" is too generic, and "Foo-Description" is 1299 needlessly long. 1301 While the field-name syntax is defined to allow any token character, 1302 in practice some implementations place limits on the characters they 1303 accept in field-names. To be interoperable, new field names SHOULD 1304 constrain themselves to alphanumeric characters, "-", and ".", and 1305 SHOULD begin with an alphanumeric character. 1307 Field names ought not be prefixed with "X-"; see [BCP178] for further 1308 information. 1310 Other prefixes are sometimes used in HTTP field names; for example, 1311 "Accept-" is used in many content negotiation headers. These 1312 prefixes are only an aid to recognizing the purpose of a field, and 1313 do not trigger automatic processing. 1315 5.3.1. Field Extensibility 1317 There is no limit on the introduction of new field names, each 1318 presumably defining new semantics. 1320 New fields can be defined such that, when they are understood by a 1321 recipient, they might override or enhance the interpretation of 1322 previously defined fields, define preconditions on request 1323 evaluation, or refine the meaning of responses. 1325 A proxy MUST forward unrecognized header fields unless the field name 1326 is listed in the Connection header field (Section 9.1 of [Messaging]) 1327 or the proxy is specifically configured to block, or otherwise 1328 transform, such fields. Other recipients SHOULD ignore unrecognized 1329 header and trailer fields. These requirements allow HTTP's 1330 functionality to be enhanced without requiring prior update of 1331 deployed intermediaries. 1333 5.3.2. Field Name Registry 1335 The "Hypertext Transfer Protocol (HTTP) Field Name Registry" defines 1336 the namespace for HTTP field names. 1338 Any party can request registration of a HTTP field. See Section 5.7 1339 for considerations to take into account when creating a new HTTP 1340 field. 1342 The "Hypertext Transfer Protocol (HTTP) Field Name Registry" is 1343 located at . 1344 Registration requests can be made by following the instructions 1345 located there or by sending an email to the "ietf-http-wg@ietf.org" 1346 mailing list. 1348 Field names are registered on the advice of a Designated Expert 1349 (appointed by the IESG or their delegate). Fields with the status 1350 'permanent' are Specification Required ([RFC8126], Section 4.6). 1352 Registration requests consist of at least the following information: 1354 Field name: 1355 The requested field name. It MUST conform to the field-name 1356 syntax defined in Section 5.3, and SHOULD be restricted to just 1357 letters, digits, hyphen ('-') and underscore ('_') characters, 1358 with the first character being a letter. 1360 Status: 1361 "permanent" or "provisional". 1363 Specification document(s): 1364 Reference to the document that specifies the field, preferably 1365 including a URI that can be used to retrieve a copy of the 1366 document. An indication of the relevant section(s) can also be 1367 included, but is not required. 1369 And, optionally: 1371 Comments: Additional information, such as about reserved entries. 1373 The Expert(s) can define additional fields to be collected in the 1374 registry, in consultation with the community. 1376 Standards-defined names have a status of "permanent". Other names 1377 can also be registered as permanent, if the Expert(s) find that they 1378 are in use, in consultation with the community. Other names should 1379 be registered as "provisional". 1381 Provisional entries can be removed by the Expert(s) if - in 1382 consultation with the community - the Expert(s) find that they are 1383 not in use. The Experts can change a provisional entry's status to 1384 permanent at any time. 1386 Note that names can be registered by third parties (including the 1387 Expert(s)), if the Expert(s) determines that an unregistered name is 1388 widely deployed and not likely to be registered in a timely manner 1389 otherwise. 1391 5.4. Field Values 1393 HTTP field values typically have their syntax defined using ABNF 1394 ([RFC5234]), using the extension defined in Section 5.5 as necessary, 1395 and are usually constrained to the range of US-ASCII characters. 1396 Fields needing a greater range of characters can use an encoding such 1397 as the one defined in [RFC8187]. 1399 field-value = *field-content 1400 field-content = field-vchar 1401 [ 1*( SP / HTAB / field-vchar ) field-vchar ] 1402 field-vchar = VCHAR / obs-text 1404 Historically, HTTP allowed field content with text in the ISO-8859-1 1405 charset [ISO-8859-1], supporting other charsets only through use of 1406 [RFC2047] encoding. In practice, most HTTP field values use only a 1407 subset of the US-ASCII charset [USASCII]. Newly defined fields 1408 SHOULD limit their values to US-ASCII octets. A recipient SHOULD 1409 treat other octets in field content (obs-text) as opaque data. 1411 Field values containing control (CTL) characters such as CR or LF are 1412 invalid; recipients MUST either reject a field value containing 1413 control characters, or convert them to SP before processing or 1414 forwarding the message. 1416 Leading and trailing whitespace in raw field values is removed upon 1417 field parsing (Section 5.1 of [Messaging]). Field definitions where 1418 leading or trailing whitespace in values is significant will have to 1419 use a container syntax such as quoted-string (Section 5.4.1.2). 1421 Because commas (",") are used as a generic delimiter between members 1422 of a list-based field value, they need to be treated with care if 1423 they are allowed as data within those members. Typically, list 1424 members that might contain a comma are enclosed in a quoted-string. 1426 For example, a textual date and a URI (either of which might contain 1427 a comma) could be safely carried in list-based field values like 1428 these: 1430 Example-URI-Field: "http://example.com/a.html,foo", 1431 "http://without-a-comma.example.com/" 1432 Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005" 1434 Note that double-quote delimiters almost always are used with the 1435 quoted-string production; using a different syntax inside double- 1436 quotes will likely cause unnecessary confusion. 1438 Many fields (such as Content-Type, defined in Section 7.2.1) use a 1439 common syntax for parameters that allows both unquoted (token) and 1440 quoted (quoted-string) syntax for a parameter value 1441 (Section 5.4.1.4). Use of common syntax allows recipients to reuse 1442 existing parser components. When allowing both forms, the meaning of 1443 a parameter value ought to be the same whether it was received as a 1444 token or a quoted string. 1446 Historically, HTTP field values could be extended over multiple lines 1447 by preceding each extra line with at least one space or horizontal 1448 tab (obs-fold). This document assumes that any such obsolete line 1449 folding has been replaced with one or more SP octets prior to 1450 interpreting the field value, as described in Section 5.2 of 1451 [Messaging]. 1453 | *Note:* This specification does not use ABNF rules to define 1454 | each "Field Name: Field Value" pair, as was done in earlier 1455 | editions (published before [RFC7230]). Instead, ABNF rules are 1456 | named according to each registered field name, wherein the rule 1457 | defines the valid grammar for that field's corresponding field 1458 | values (i.e., after the field value has been extracted by a 1459 | generic field parser). 1461 5.4.1. Common Field Value Components 1463 Many HTTP field values are defined using common syntax components, 1464 separated by whitespace or specific delimiting characters. 1465 Delimiters are chosen from the set of US-ASCII visual characters not 1466 allowed in a token (DQUOTE and "(),/:;<=>?@[\]{}"). 1468 5.4.1.1. Tokens 1470 Tokens are short textual identifiers that do not include whitespace 1471 or delimiters. 1473 token = 1*tchar 1475 tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" 1476 / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" 1477 / DIGIT / ALPHA 1478 ; any VCHAR, except delimiters 1480 5.4.1.2. Quoted Strings 1482 A string of text is parsed as a single value if it is quoted using 1483 double-quote marks. 1485 quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE 1486 qdtext = HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text 1487 obs-text = %x80-FF 1489 The backslash octet ("\") can be used as a single-octet quoting 1490 mechanism within quoted-string and comment constructs. Recipients 1491 that process the value of a quoted-string MUST handle a quoted-pair 1492 as if it were replaced by the octet following the backslash. 1494 quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) 1496 A sender SHOULD NOT generate a quoted-pair in a quoted-string except 1497 where necessary to quote DQUOTE and backslash octets occurring within 1498 that string. A sender SHOULD NOT generate a quoted-pair in a comment 1499 except where necessary to quote parentheses ["(" and ")"] and 1500 backslash octets occurring within that comment. 1502 5.4.1.3. Comments 1504 Comments can be included in some HTTP fields by surrounding the 1505 comment text with parentheses. Comments are only allowed in fields 1506 containing "comment" as part of their field value definition. 1508 comment = "(" *( ctext / quoted-pair / comment ) ")" 1509 ctext = HTAB / SP / %x21-27 / %x2A-5B / %x5D-7E / obs-text 1511 5.4.1.4. Parameters 1513 A parameter is a name=value pair that is often defined within field 1514 values as a common syntax for appending auxiliary information to an 1515 item. Each parameter is usually delimited by an immediately 1516 preceding semicolon. 1518 parameter = parameter-name "=" parameter-value 1519 parameter-name = token 1520 parameter-value = ( token / quoted-string ) 1522 Parameter names are case-insensitive. Parameter values might or 1523 might not be case-sensitive, depending on the semantics of the 1524 parameter name. Examples of parameters and some equivalent forms can 1525 be seen in media types (Section 7.1.1) and the Accept header field 1526 (Section 9.4.1). 1528 A parameter value that matches the token production can be 1529 transmitted either as a token or within a quoted-string. The quoted 1530 and unquoted values are equivalent. 1532 | *Note:* Parameters do not allow whitespace (not even "bad" 1533 | whitespace) around the "=" character. 1535 5.4.1.5. Date/Time Formats 1537 Prior to 1995, there were three different formats commonly used by 1538 servers to communicate timestamps. For compatibility with old 1539 implementations, all three are defined here. The preferred format is 1540 a fixed-length and single-zone subset of the date and time 1541 specification used by the Internet Message Format [RFC5322]. 1543 HTTP-date = IMF-fixdate / obs-date 1545 An example of the preferred format is 1547 Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate 1549 Examples of the two obsolete formats are 1551 Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format 1552 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format 1554 A recipient that parses a timestamp value in an HTTP field MUST 1555 accept all three HTTP-date formats. When a sender generates a field 1556 that contains one or more timestamps defined as HTTP-date, the sender 1557 MUST generate those timestamps in the IMF-fixdate format. 1559 An HTTP-date value represents time as an instance of Coordinated 1560 Universal Time (UTC). The first two formats indicate UTC by the 1561 three-letter abbreviation for Greenwich Mean Time, "GMT", a 1562 predecessor of the UTC name; values in the asctime format are assumed 1563 to be in UTC. A sender that generates HTTP-date values from a local 1564 clock ought to use NTP ([RFC5905]) or some similar protocol to 1565 synchronize its clock to UTC. 1567 Preferred format: 1569 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 1570 ; fixed length/zone/capitalization subset of the format 1571 ; see Section 3.3 of [RFC5322] 1573 day-name = %s"Mon" / %s"Tue" / %s"Wed" 1574 / %s"Thu" / %s"Fri" / %s"Sat" / %s"Sun" 1576 date1 = day SP month SP year 1577 ; e.g., 02 Jun 1982 1579 day = 2DIGIT 1580 month = %s"Jan" / %s"Feb" / %s"Mar" / %s"Apr" 1581 / %s"May" / %s"Jun" / %s"Jul" / %s"Aug" 1582 / %s"Sep" / %s"Oct" / %s"Nov" / %s"Dec" 1583 year = 4DIGIT 1585 GMT = %s"GMT" 1587 time-of-day = hour ":" minute ":" second 1588 ; 00:00:00 - 23:59:60 (leap second) 1590 hour = 2DIGIT 1591 minute = 2DIGIT 1592 second = 2DIGIT 1594 Obsolete formats: 1596 obs-date = rfc850-date / asctime-date 1598 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 1599 date2 = day "-" month "-" 2DIGIT 1600 ; e.g., 02-Jun-82 1602 day-name-l = %s"Monday" / %s"Tuesday" / %s"Wednesday" 1603 / %s"Thursday" / %s"Friday" / %s"Saturday" / %s"Sunday" 1605 asctime-date = day-name SP date3 SP time-of-day SP year 1606 date3 = month SP ( 2DIGIT / ( SP 1DIGIT )) 1607 ; e.g., Jun 2 1609 HTTP-date is case sensitive. A sender MUST NOT generate additional 1610 whitespace in an HTTP-date beyond that specifically included as SP in 1611 the grammar. The semantics of day-name, day, month, year, and 1612 time-of-day are the same as those defined for the Internet Message 1613 Format constructs with the corresponding name ([RFC5322], 1614 Section 3.3). 1616 Recipients of a timestamp value in rfc850-date format, which uses a 1617 two-digit year, MUST interpret a timestamp that appears to be more 1618 than 50 years in the future as representing the most recent year in 1619 the past that had the same last two digits. 1621 Recipients of timestamp values are encouraged to be robust in parsing 1622 timestamps unless otherwise restricted by the field definition. For 1623 example, messages are occasionally forwarded over HTTP from a non- 1624 HTTP source that might generate any of the date and time 1625 specifications defined by the Internet Message Format. 1627 | *Note:* HTTP requirements for the date/time stamp format apply 1628 | only to their usage within the protocol stream. 1629 | Implementations are not required to use these formats for user 1630 | presentation, request logging, etc. 1632 5.5. ABNF List Extension: #rule 1634 A #rule extension to the ABNF rules of [RFC5234] is used to improve 1635 readability in the definitions of some list-based field values. 1637 A construct "#" is defined, similar to "*", for defining comma- 1638 delimited lists of elements. The full form is "#element" 1639 indicating at least and at most elements, each separated by a 1640 single comma (",") and optional whitespace (OWS). 1642 5.5.1. Sender Requirements 1644 In any production that uses the list construct, a sender MUST NOT 1645 generate empty list elements. In other words, a sender MUST generate 1646 lists that satisfy the following syntax: 1648 1#element => element *( OWS "," OWS element ) 1650 and: 1652 #element => [ 1#element ] 1654 and for n >= 1 and m > 1: 1656 #element => element *( OWS "," OWS element ) 1658 Appendix A shows the collected ABNF for senders after the list 1659 constructs have been expanded. 1661 5.5.2. Recipient Requirements 1663 Empty elements do not contribute to the count of elements present. A 1664 recipient MUST parse and ignore a reasonable number of empty list 1665 elements: enough to handle common mistakes by senders that merge 1666 values, but not so much that they could be used as a denial-of- 1667 service mechanism. In other words, a recipient MUST accept lists 1668 that satisfy the following syntax: 1670 #element => [ element ] *( OWS "," OWS [ element ] ) 1672 Note that because of the potential presence of empty list elements, 1673 the RFC 5234 ABNF cannot enforce the cardinality of list elements, 1674 and consequently all cases are mapped is if there was no cardinality 1675 specified. 1677 For example, given these ABNF productions: 1679 example-list = 1#example-list-elmt 1680 example-list-elmt = token ; see Section 5.4.1.1 1682 Then the following are valid values for example-list (not including 1683 the double quotes, which are present for delimitation only): 1685 "foo,bar" 1686 "foo ,bar," 1687 "foo , ,bar,charlie" 1689 In contrast, the following values would be invalid, since at least 1690 one non-empty element is required by the example-list production: 1692 "" 1693 "," 1694 ", ," 1696 5.6. Trailer Fields 1697 5.6.1. Purpose 1699 In some HTTP versions, additional metadata can be sent after the 1700 initial header section has been completed (during or after 1701 transmission of the payload body), such as a message integrity check, 1702 digital signature, or post-processing status. For example, the 1703 chunked coding in HTTP/1.1 allows a trailer section after the payload 1704 body (Section 7.1.2 of [Messaging]) which can contain trailer fields: 1705 field names and values that share the same syntax and namespace as 1706 header fields but that are received after the header section. 1708 Trailer fields ought to be processed and stored separately from the 1709 fields in the header section to avoid contradicting message semantics 1710 known at the time the header section was complete. The presence or 1711 absence of certain header fields might impact choices made for the 1712 routing or processing of the message as a whole before the trailers 1713 are received; those choices cannot be unmade by the later discovery 1714 of trailer fields. 1716 5.6.2. Limitations 1718 Many fields cannot be processed outside the header section because 1719 their evaluation is necessary prior to receiving the message body, 1720 such as those that describe message framing, routing, authentication, 1721 request modifiers, response controls, or payload format. A sender 1722 MUST NOT generate a trailer field unless the sender knows the 1723 corresponding header field name's definition permits the field to be 1724 sent in trailers. 1726 Trailer fields can be difficult to process by intermediaries that 1727 forward messages from one protocol version to another. If the entire 1728 message can be buffered in transit, some intermediaries could merge 1729 trailer fields into the header section (as appropriate) before it is 1730 forwarded. However, in most cases, the trailers are simply 1731 discarded. A recipient MUST NOT merge a trailer field into a header 1732 section unless the recipient understands the corresponding header 1733 field definition and that definition explicitly permits and defines 1734 how trailer field values can be safely merged. 1736 The presence of the keyword "trailers" in the TE header field 1737 (Section 7.4 of [Messaging]) indicates that the client is willing to 1738 accept trailer fields, on behalf of itself and any downstream 1739 clients. For requests from an intermediary, this implies that all 1740 downstream clients are willing to accept trailer fields in the 1741 forwarded response. Note that the presence of "trailers" does not 1742 mean that the client(s) will process any particular trailer field in 1743 the response; only that the trailer section as a whole will not be 1744 dropped by any of the clients. 1746 Because of the potential for trailer fields to be discarded in 1747 transit, a server SHOULD NOT generate trailer fields that it believes 1748 are necessary for the user agent to receive. 1750 5.6.3. Trailer 1752 The "Trailer" header field provides a list of field names that the 1753 sender anticipates sending as trailer fields within that message. 1754 This allows a recipient to prepare for receipt of the indicated 1755 metadata before it starts processing the body. 1757 Trailer = 1#field-name 1759 For example, a sender might indicate that a message integrity check 1760 will be computed as the payload is being streamed and provide the 1761 final signature as a trailer field. This allows a recipient to 1762 perform the same check on the fly as the payload data is received. 1764 A sender that intends to generate one or more trailer fields in a 1765 message SHOULD generate a Trailer header field in the header section 1766 of that message to indicate which fields might be present in the 1767 trailers. 1769 5.7. Considerations for New HTTP Fields 1771 See Section 5.3 for a general requirements for field names, and 1772 Section 5.4 for a discussion of field values. 1774 Authors of specifications defining new fields are advised to consider 1775 documenting: 1777 o Whether the field is a single value or whether it can be a list 1778 (delimited by commas; see Section 5.4). 1780 If it is not a list, document how to treat messages where the 1781 field occurs multiple times (a sensible default would be to ignore 1782 the field, but this might not always be the right choice). 1784 Note that intermediaries and software libraries might combine 1785 multiple field instances into a single one, despite the field's 1786 definition not allowing the list syntax. A robust format enables 1787 recipients to discover these situations (good example: "Content- 1788 Type", as the comma can only appear inside quoted strings; bad 1789 example: "Location", as a comma can occur inside a URI). 1791 o Under what conditions the field can be used; e.g., only in 1792 responses or requests, in all messages, only on responses to a 1793 particular request method, etc. 1795 o What the scope of applicability for the information conveyed in 1796 the field is. By default, fields apply only to the message they 1797 are associated with, but some response fields are designed to 1798 apply to all representations of a resource, the resource itself, 1799 or an even broader scope. Specifications that expand the scope of 1800 a response field will need to carefully consider issues such as 1801 content negotiation, the time period of applicability, and (in 1802 some cases) multi-tenant server deployments. 1804 o Whether the field should be stored by origin servers that 1805 understand it upon a PUT request. 1807 o Whether the field semantics are further refined by the context, 1808 such as by existing request methods or status codes. 1810 o Whether it is appropriate to list the field name in the Connection 1811 header field (i.e., if the field is to be hop-by-hop; see 1812 Section 9.1 of [Messaging]). 1814 o Under what conditions intermediaries are allowed to insert, 1815 delete, or modify the field's value. 1817 o Whether it is appropriate to list the field name in a Vary 1818 response header field (e.g., when the request header field is used 1819 by an origin server's content selection algorithm; see 1820 Section 11.1.4). 1822 o Whether the field is allowable in trailers (see Section 5.6). 1824 o Whether the field ought to be preserved across redirects. 1826 o Whether it introduces any additional security considerations, such 1827 as disclosure of privacy-related data. 1829 5.8. Fields Defined In This Document 1831 The following fields are defined by this document: 1833 +---------------------------+------------+----------------+ 1834 | Field Name | Status | Reference | 1835 | Accept | standard | Section 9.4.1 | 1836 | Accept-Charset | deprecated | Section 9.4.2 | 1837 | Accept-Encoding | standard | Section 9.4.3 | 1838 | Accept-Language | standard | Section 9.4.4 | 1839 | Accept-Ranges | standard | Section 11.4.1 | 1840 | Allow | standard | Section 11.4.2 | 1841 | Authentication-Info | standard | Section 11.3.3 | 1842 | Authorization | standard | Section 9.5.3 | 1843 | Content-Encoding | standard | Section 7.2.2 | 1844 | Content-Language | standard | Section 7.2.3 | 1845 | Content-Length | standard | Section 7.2.4 | 1846 | Content-Location | standard | Section 7.2.5 | 1847 | Content-Range | standard | Section 7.3.4 | 1848 | Content-Type | standard | Section 7.2.1 | 1849 | Date | standard | Section 11.1.1 | 1850 | ETag | standard | Section 11.2.3 | 1851 | Expect | standard | Section 9.1.1 | 1852 | From | standard | Section 9.6.1 | 1853 | Host | standard | Section 6.6 | 1854 | If-Match | standard | Section 9.2.3 | 1855 | If-Modified-Since | standard | Section 9.2.5 | 1856 | If-None-Match | standard | Section 9.2.4 | 1857 | If-Range | standard | Section 9.2.7 | 1858 | If-Unmodified-Since | standard | Section 9.2.6 | 1859 | Last-Modified | standard | Section 11.2.2 | 1860 | Location | standard | Section 11.1.2 | 1861 | Max-Forwards | standard | Section 9.1.2 | 1862 | Proxy-Authenticate | standard | Section 11.3.2 | 1863 | Proxy-Authentication-Info | standard | Section 11.3.4 | 1864 | Proxy-Authorization | standard | Section 9.5.4 | 1865 | Range | standard | Section 9.3 | 1866 | Referer | standard | Section 9.6.2 | 1867 | Retry-After | standard | Section 11.1.3 | 1868 | Server | standard | Section 11.4.3 | 1869 | Trailer | standard | Section 5.6.3 | 1870 | User-Agent | standard | Section 9.6.3 | 1871 | Vary | standard | Section 11.1.4 | 1872 | Via | standard | Section 6.7.1 | 1873 | WWW-Authenticate | standard | Section 11.3.1 | 1874 +---------------------------+------------+----------------+ 1876 Table 2 1878 Furthermore, the field name "*" is reserved, since using that name as 1879 an HTTP header field might conflict with its special semantics in the 1880 Vary header field (Section 11.1.4). 1882 +------------+----------+-------------+------------+ 1883 | Field Name | Status | Reference | Comments | 1884 | * | standard | Section 5.8 | (reserved) | 1885 +------------+----------+-------------+------------+ 1887 Table 3 1889 6. Message Routing 1891 HTTP request message routing is determined by each client based on 1892 the target resource, the client's proxy configuration, and 1893 establishment or reuse of an inbound connection. The corresponding 1894 response routing follows the same connection chain back to the 1895 client. 1897 6.1. Identifying a Target Resource 1899 HTTP is used in a wide variety of applications, ranging from general- 1900 purpose computers to home appliances. In some cases, communication 1901 options are hard-coded in a client's configuration. However, most 1902 HTTP clients rely on the same resource identification mechanism and 1903 configuration techniques as general-purpose Web browsers. 1905 HTTP communication is initiated by a user agent for some purpose. 1906 The purpose is a combination of request semantics and a target 1907 resource upon which to apply those semantics. The "request target" 1908 is the protocol element that identifies the "target resource". 1910 Typically, the request target is a URI reference (Section 2.4) which 1911 a user agent would resolve to its absolute form in order to obtain 1912 the "target URI". The target URI excludes the reference's fragment 1913 component, if any, since fragment identifiers are reserved for 1914 client-side processing ([RFC3986], Section 3.5). 1916 However, there are two special, method-specific forms allowed for the 1917 request target in specific circumstances: 1919 o For CONNECT (Section 8.3.6), the request target is the host name 1920 and port number of the tunnel destination, separated by a colon. 1922 o For OPTIONS (Section 8.3.7), the request target can be a single 1923 asterisk ("*"). 1925 See the respective method definitions for details. These forms MUST 1926 NOT be used with other methods. 1928 6.2. Determining Origin 1930 The "origin" for a given URI is the triple of scheme, host, and port 1931 after normalizing the scheme and host to lowercase and normalizing 1932 the port to remove any leading zeros. If port is elided from the 1933 URI, the default port for that scheme is used. For example, the URI 1935 https://Example.Com/happy.js 1937 would have the origin 1939 { "https", "example.com", "443" } 1941 which can also be described as the normalized URI prefix with port 1942 always present: 1944 https://example.com:443 1946 Each origin defines its own namespace and controls how identifiers 1947 within that namespace are mapped to resources. In turn, how the 1948 origin responds to valid requests, consistently over time, determines 1949 the semantics that users will associate with a URI, and the 1950 usefulness of those semantics is what ultimately transforms these 1951 mechanisms into a "resource" for users to reference and access in the 1952 future. 1954 Two origins are distinct if they differ in scheme, host, or port. 1955 Even when it can be verified that the same entity controls two 1956 distinct origins, the two namespaces under those origins are distinct 1957 unless explicitly aliased by a server authoritative for that origin. 1959 Origin is also used within HTML and related Web protocols, beyond the 1960 scope of this document, as described in [RFC6454]. 1962 6.3. Routing Inbound 1964 Once the target URI and its origin are determined, a client decides 1965 whether a network request is necessary to accomplish the desired 1966 semantics and, if so, where that request is to be directed. 1968 If the client has a cache [Caching] and the request can be satisfied 1969 by it, then the request is usually directed there first. 1971 If the request is not satisfied by a cache, then a typical client 1972 will check its configuration to determine whether a proxy is to be 1973 used to satisfy the request. Proxy configuration is implementation- 1974 dependent, but is often based on URI prefix matching, selective 1975 authority matching, or both, and the proxy itself is usually 1976 identified by an "http" or "https" URI. If a proxy is applicable, 1977 the client connects inbound by establishing (or reusing) a connection 1978 to that proxy. 1980 If no proxy is applicable, a typical client will invoke a handler 1981 routine, usually specific to the target URI's scheme, to connect 1982 directly to an origin for the target resource. How that is 1983 accomplished is dependent on the target URI scheme and defined by its 1984 associated specification, similar to how this specification defines 1985 origin server access for resolution of the "http" (Section 2.5.1) and 1986 "https" (Section 2.5.2) schemes. 1988 6.4. Direct Authoritative Access 1990 6.4.1. http origins 1992 Although HTTP is independent of the transport protocol, the "http" 1993 scheme is specific to associating authority with whomever controls 1994 the origin server listening for TCP connections on the indicated port 1995 of whatever host is identified within the authority component. This 1996 is a very weak sense of authority because it depends on both client- 1997 specific name resolution mechanisms and communication that might not 1998 be secured from man-in-the-middle attacks. Nevertheless, it is a 1999 sufficient minimum for binding "http" identifiers to an origin server 2000 for consistent resolution within a trusted environment. 2002 If the host identifier is provided as an IP address, the origin 2003 server is the listener (if any) on the indicated TCP port at that IP 2004 address. If host is a registered name, the registered name is an 2005 indirect identifier for use with a name resolution service, such as 2006 DNS, to find an address for an appropriate origin server. 2008 When an "http" URI is used within a context that calls for access to 2009 the indicated resource, a client MAY attempt access by resolving the 2010 host identifier to an IP address, establishing a TCP connection to 2011 that address on the indicated port, and sending an HTTP request 2012 message to the server containing the URI's identifying data 2013 (Section 2 of [Messaging]). 2015 If the server responds to such a request with a non-interim HTTP 2016 response message, as described in Section 10, then that response is 2017 considered an authoritative answer to the client's request. 2019 Note, however, that the above is not the only means for obtaining an 2020 authoritative response, nor does it imply that an authoritative 2021 response is always necessary (see [Caching]). For example, the Alt- 2022 Svc header field [RFC7838] allows an origin server to identify other 2023 services that are also authoritative for that origin. Access to 2024 "http" identified resources might also be provided by protocols 2025 outside the scope of this document. 2027 See Section 12.1 for security considerations related to establishing 2028 authority. 2030 6.4.2. https origins 2032 The "https" scheme associates authority based on the ability of a 2033 server to use a private key associated with a certificate that the 2034 client considers to be trustworthy for the identified host. If a 2035 server presents a certificate that verifiably applies to the host, 2036 along with proof that it controls the corresponding private key, then 2037 a client will accept a secured connection to that server as being 2038 authoritative for all origins with the same scheme and host. 2040 A client is therefore relying upon a chain of trust, conveyed from 2041 some trust anchor (which is usually prearranged or configured), 2042 through a chain of certificates (e.g., [RFC5280]) to a final 2043 certificate that binds a private key to the host name of the origin. 2044 The handshake and certificate validation in Section 6.4.3 describe 2045 how that final certificate can be used to initiate a secured 2046 connection. 2048 Note that the "https" scheme does not rely on TCP and the connected 2049 port number for associating authority, since both are outside the 2050 secured communication and thus cannot be trusted as definitive. 2051 Hence, the HTTP communication might take place over any channel that 2052 has been secured, as defined in Section 2.5.2, including protocols 2053 that don't use TCP. It is the origin's responsibility to ensure that 2054 any services provided with control over its certificate's private key 2055 are equally responsible for managing the corresponding "https" 2056 namespaces, or at least prepared to reject requests that appear to 2057 have been misdirected. Regardless, the origin's host and port value 2058 are passed within each HTTP request, identifying the target resource 2059 and distinguishing it from other namespaces that might be controlled 2060 by the same server. 2062 In HTTP/1.1 and earlier, the only URIs for which a client will 2063 attribute authority to a server are those for which a TLS connection 2064 was specifically established toward the origin's host. Only the 2065 characteristics of the connection establishment and certificate are 2066 used. For a host that is a domain name, the client MUST include that 2067 name in the TLS server_name extension (if used) and MUST verify that 2068 the name also appears as either the CN field of the certificate 2069 subject or as a dNSName in the subjectAltName field of the 2070 certificate (see [RFC6125]). For a host that is an IP address, the 2071 client MUST verify that the address appears in the subjectAltName of 2072 the certificate. 2074 In HTTP/2, a client will associate authority to all names that are 2075 present in the certificate. However, a client will only do that if 2076 it concludes that it could open a connection to the origin for that 2077 URI. In practice, a client will make a DNS query and see that it 2078 contains the same server IP address. A server sending the ORIGIN 2079 frame removes this restriction [RFC8336]. 2081 In addition to the client's verification, an origin server is 2082 responsible for verifying that requests it receives over a connection 2083 correspond to resources for which it actually wants to be the origin. 2084 If a network attacker causes connections for port N to be received at 2085 port Q, checking the target URI is necessary to ensure that the 2086 attacker can't cause "https://example.com:N/foo" to be replaced by 2087 "https://example.com:Q/foo" without consent. Likewise, a server 2088 might be unwilling to serve as the origin for some hosts even when 2089 they have the authority to do so. 2091 When an "https" URI is used within a context that calls for access to 2092 the indicated resource, a client MAY attempt access by resolving the 2093 host identifier to an IP address, establishing a TCP connection to 2094 that address on the indicated port, securing the connection end-to- 2095 end by successfully initiating TLS over TCP with confidentiality and 2096 integrity protection, and sending an HTTP request message to the 2097 server over that secured connection containing the URI's identifying 2098 data (Section 2 of [Messaging]). 2100 If the server responds to such a request with a non-interim HTTP 2101 response message, as described in Section 10, then that response is 2102 considered an authoritative answer to the client's request. 2104 Note, however, that the above is not the only means for obtaining an 2105 authoritative response, nor does it imply that an authoritative 2106 response is always necessary (see [Caching]). 2108 6.4.3. Initiating HTTP Over TLS 2110 Conceptually, HTTP/TLS is very simple. Simply use HTTP over TLS 2111 precisely as you would use HTTP over TCP. 2113 The agent acting as the HTTP client should also act as the TLS 2114 client. It should initiate a connection to the server on the 2115 appropriate port and then send the TLS ClientHello to begin the TLS 2116 handshake. When the TLS handshake has finished. The client may then 2117 initiate the first HTTP request. All HTTP data MUST be sent as TLS 2118 "application data". Normal HTTP behavior, including retained 2119 connections should be followed. 2121 6.4.3.1. Identifying HTTPS Servers 2123 In general, HTTP/TLS requests are generated by dereferencing a URI. 2124 As a consequence, the hostname for the server is known to the client. 2125 If the hostname is available, the client MUST check it against the 2126 server's identity as presented in the server's Certificate message, 2127 in order to prevent man-in-the-middle attacks. 2129 If the client has external information as to the expected identity of 2130 the server, the hostname check MAY be omitted. (For instance, a 2131 client may be connecting to a machine whose address and hostname are 2132 dynamic but the client knows the certificate that the server will 2133 present.) In such cases, it is important to narrow the scope of 2134 acceptable certificates as much as possible in order to prevent man 2135 in the middle attacks. In special cases, it may be appropriate for 2136 the client to simply ignore the server's identity, but it must be 2137 understood that this leaves the connection open to active attack. 2139 If a subjectAltName extension of type dNSName is present, that MUST 2140 be used as the identity. Otherwise, the (most specific) Common Name 2141 field in the Subject field of the certificate MUST be used. Although 2142 the use of the Common Name is existing practice, it is deprecated and 2143 Certification Authorities are encouraged to use the dNSName instead. 2145 Matching is performed using the matching rules specified by 2146 [RFC5280]. If more than one identity of a given type is present in 2147 the certificate (e.g., more than one dNSName name, a match in any one 2148 of the set is considered acceptable.) Names may contain the wildcard 2149 character * which is considered to match any single domain name 2150 component or component fragment. E.g., *.a.com matches foo.a.com but 2151 not bar.foo.a.com. f*.com matches foo.com but not bar.com. 2153 In some cases, the URI is specified as an IP address rather than a 2154 hostname. In this case, the iPAddress subjectAltName must be present 2155 in the certificate and must exactly match the IP in the URI. 2157 If the hostname does not match the identity in the certificate, user 2158 oriented clients MUST either notify the user (clients MAY give the 2159 user the opportunity to continue with the connection in any case) or 2160 terminate the connection with a bad certificate error. Automated 2161 clients MUST log the error to an appropriate audit log (if available) 2162 and SHOULD terminate the connection (with a bad certificate error). 2163 Automated clients MAY provide a configuration setting that disables 2164 this check, but MUST provide a setting which enables it. 2166 Note that in many cases the URI itself comes from an untrusted 2167 source. The above-described check provides no protection against 2168 attacks where this source is compromised. For example, if the URI 2169 was obtained by clicking on an HTML page which was itself obtained 2170 without using HTTP/TLS, a man in the middle could have replaced the 2171 URI. In order to prevent this form of attack, users should carefully 2172 examine the certificate presented by the server to determine if it 2173 meets their expectations. 2175 6.4.3.2. Identifying HTTPS Clients 2177 Typically, the server has no external knowledge of what the client's 2178 identity ought to be and so checks (other than that the client has a 2179 certificate chain rooted in an appropriate CA) are not possible. If 2180 a server has such knowledge (typically from some source external to 2181 HTTP or TLS) it SHOULD check the identity as described above. 2183 6.5. Reconstructing the Target URI 2185 Once an inbound connection is obtained, the client sends an HTTP 2186 request message (Section 2 of [Messaging]). 2188 Depending on the nature of the request, the client's target URI might 2189 be split into components and transmitted (or implied) within various 2190 parts of a request message. These parts are recombined by each 2191 recipient, in accordance with their local configuration and incoming 2192 connection context, to determine the target URI. Appendix of 2193 [Messaging] defines how a server determines the target URI for an 2194 HTTP/1.1 request. 2196 Once the target URI has been reconstructed, an origin server needs to 2197 decide whether or not to provide service for that URI via the 2198 connection in which the request was received. For example, the 2199 request might have been misdirected, deliberately or accidentally, 2200 such that the information within a received Host header field differs 2201 from the host or port upon which the connection has been made. If 2202 the connection is from a trusted gateway, that inconsistency might be 2203 expected; otherwise, it might indicate an attempt to bypass security 2204 filters, trick the server into delivering non-public content, or 2205 poison a cache. See Section 12 for security considerations regarding 2206 message routing. 2208 | *Note:* previous specifications defined the recomposed target 2209 | URI as a distinct concept, the effective request URI. 2211 6.6. Host 2213 The "Host" header field in a request provides the host and port 2214 information from the target URI, enabling the origin server to 2215 distinguish among resources while servicing requests for multiple 2216 host names on a single IP address. 2218 Host = uri-host [ ":" port ] ; Section 2.4 2220 A client MUST send a Host header field in all HTTP/1.1 request 2221 messages. If the target URI includes an authority component, then a 2222 client MUST send a field value for Host that is identical to that 2223 authority component, excluding any userinfo subcomponent and its "@" 2224 delimiter (Section 2.5.1). If the authority component is missing or 2225 undefined for the target URI, then a client MUST send a Host header 2226 field with an empty field value. 2228 Since the Host field value is critical information for handling a 2229 request, a user agent SHOULD generate Host as the first header field 2230 following the request-line. 2232 For example, a GET request to the origin server for 2233 would begin with: 2235 GET /pub/WWW/ HTTP/1.1 2236 Host: www.example.org 2238 Since the Host header field acts as an application-level routing 2239 mechanism, it is a frequent target for malware seeking to poison a 2240 shared cache or redirect a request to an unintended server. An 2241 interception proxy is particularly vulnerable if it relies on the 2242 Host field value for redirecting requests to internal servers, or for 2243 use as a cache key in a shared cache, without first verifying that 2244 the intercepted connection is targeting a valid IP address for that 2245 host. 2247 A server MUST respond with a 400 (Bad Request) status code to any 2248 HTTP/1.1 request message that lacks a Host header field and to any 2249 request message that contains more than one Host header field or a 2250 Host header field with an invalid field value. 2252 6.7. Message Forwarding 2254 As described in Section 2.2, intermediaries can serve a variety of 2255 roles in the processing of HTTP requests and responses. Some 2256 intermediaries are used to improve performance or availability. 2257 Others are used for access control or to filter content. Since an 2258 HTTP stream has characteristics similar to a pipe-and-filter 2259 architecture, there are no inherent limits to the extent an 2260 intermediary can enhance (or interfere) with either direction of the 2261 stream. 2263 An intermediary not acting as a tunnel MUST implement the Connection 2264 header field, as specified in Section 9.1 of [Messaging], and exclude 2265 fields from being forwarded that are only intended for the incoming 2266 connection. 2268 An intermediary MUST NOT forward a message to itself unless it is 2269 protected from an infinite request loop. In general, an intermediary 2270 ought to recognize its own server names, including any aliases, local 2271 variations, or literal IP addresses, and respond to such requests 2272 directly. 2274 An HTTP message can be parsed as a stream for incremental processing 2275 or forwarding downstream. However, recipients cannot rely on 2276 incremental delivery of partial messages, since some implementations 2277 will buffer or delay message forwarding for the sake of network 2278 efficiency, security checks, or payload transformations. 2280 6.7.1. Via 2282 The "Via" header field indicates the presence of intermediate 2283 protocols and recipients between the user agent and the server (on 2284 requests) or between the origin server and the client (on responses), 2285 similar to the "Received" header field in email (Section 3.6.7 of 2286 [RFC5322]). Via can be used for tracking message forwards, avoiding 2287 request loops, and identifying the protocol capabilities of senders 2288 along the request/response chain. 2290 Via = 1#( received-protocol RWS received-by [ RWS comment ] ) 2292 received-protocol = [ protocol-name "/" ] protocol-version 2293 ; see [Messaging], Section 9.9 2294 received-by = pseudonym [ ":" port ] 2295 pseudonym = token 2297 Each member of the Via field value represents a proxy or gateway that 2298 has forwarded the message. Each intermediary appends its own 2299 information about how the message was received, such that the end 2300 result is ordered according to the sequence of forwarding recipients. 2302 A proxy MUST send an appropriate Via header field, as described 2303 below, in each message that it forwards. An HTTP-to-HTTP gateway 2304 MUST send an appropriate Via header field in each inbound request 2305 message and MAY send a Via header field in forwarded response 2306 messages. 2308 For each intermediary, the received-protocol indicates the protocol 2309 and protocol version used by the upstream sender of the message. 2310 Hence, the Via field value records the advertised protocol 2311 capabilities of the request/response chain such that they remain 2312 visible to downstream recipients; this can be useful for determining 2313 what backwards-incompatible features might be safe to use in 2314 response, or within a later request, as described in Section 4.2. 2315 For brevity, the protocol-name is omitted when the received protocol 2316 is HTTP. 2318 The received-by portion is normally the host and optional port number 2319 of a recipient server or client that subsequently forwarded the 2320 message. However, if the real host is considered to be sensitive 2321 information, a sender MAY replace it with a pseudonym. If a port is 2322 not provided, a recipient MAY interpret that as meaning it was 2323 received on the default TCP port, if any, for the received-protocol. 2325 A sender MAY generate comments to identify the software of each 2326 recipient, analogous to the User-Agent and Server header fields. 2327 However, comments in Via are optional, and a recipient MAY remove 2328 them prior to forwarding the message. 2330 For example, a request message could be sent from an HTTP/1.0 user 2331 agent to an internal proxy code-named "fred", which uses HTTP/1.1 to 2332 forward the request to a public proxy at p.example.net, which 2333 completes the request by forwarding it to the origin server at 2334 www.example.com. The request received by www.example.com would then 2335 have the following Via header field: 2337 Via: 1.0 fred, 1.1 p.example.net 2339 An intermediary used as a portal through a network firewall SHOULD 2340 NOT forward the names and ports of hosts within the firewall region 2341 unless it is explicitly enabled to do so. If not enabled, such an 2342 intermediary SHOULD replace each received-by host of any host behind 2343 the firewall by an appropriate pseudonym for that host. 2345 An intermediary MAY combine an ordered subsequence of Via header 2346 field list members into a single member if the entries have identical 2347 received-protocol values. For example, 2349 Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy 2351 could be collapsed to 2353 Via: 1.0 ricky, 1.1 mertz, 1.0 lucy 2355 A sender SHOULD NOT combine multiple list members unless they are all 2356 under the same organizational control and the hosts have already been 2357 replaced by pseudonyms. A sender MUST NOT combine members that have 2358 different received-protocol values. 2360 6.7.2. Transformations 2362 Some intermediaries include features for transforming messages and 2363 their payloads. A proxy might, for example, convert between image 2364 formats in order to save cache space or to reduce the amount of 2365 traffic on a slow link. However, operational problems might occur 2366 when these transformations are applied to payloads intended for 2367 critical applications, such as medical imaging or scientific data 2368 analysis, particularly when integrity checks or digital signatures 2369 are used to ensure that the payload received is identical to the 2370 original. 2372 An HTTP-to-HTTP proxy is called a "transforming proxy" if it is 2373 designed or configured to modify messages in a semantically 2374 meaningful way (i.e., modifications, beyond those required by normal 2375 HTTP processing, that change the message in a way that would be 2376 significant to the original sender or potentially significant to 2377 downstream recipients). For example, a transforming proxy might be 2378 acting as a shared annotation server (modifying responses to include 2379 references to a local annotation database), a malware filter, a 2380 format transcoder, or a privacy filter. Such transformations are 2381 presumed to be desired by whichever client (or client organization) 2382 selected the proxy. 2384 If a proxy receives a target URI with a host name that is not a fully 2385 qualified domain name, it MAY add its own domain to the host name it 2386 received when forwarding the request. A proxy MUST NOT change the 2387 host name if the target URI contains a fully qualified domain name. 2389 A proxy MUST NOT modify the "absolute-path" and "query" parts of the 2390 received target URI when forwarding it to the next inbound server, 2391 except as noted above to replace an empty path with "/" or "*". 2393 A proxy MAY modify the message body through application or removal of 2394 a transfer coding (Section 7 of [Messaging]). 2396 A proxy MUST NOT transform the payload (Section 7.3) of a message 2397 that contains a no-transform cache-control response directive 2398 (Section 5.2 of [Caching]). 2400 A proxy MAY transform the payload of a message that does not contain 2401 a no-transform cache-control directive. A proxy that transforms the 2402 payload of a 200 (OK) response can inform downstream recipients that 2403 a transformation has been applied by changing the response status 2404 code to 203 (Non-Authoritative Information) (Section 10.3.4). 2406 A proxy SHOULD NOT modify header fields that provide information 2407 about the endpoints of the communication chain, the resource state, 2408 or the selected representation (other than the payload) unless the 2409 field's definition specifically allows such modification or the 2410 modification is deemed necessary for privacy or security. 2412 7. Representations 2414 Considering that a resource could be anything, and that the uniform 2415 interface provided by HTTP is similar to a window through which one 2416 can observe and act upon such a thing only through the communication 2417 of messages to some independent actor on the other side, an 2418 abstraction is needed to represent ("take the place of") the current 2419 or desired state of that thing in our communications. That 2420 abstraction is called a representation [REST]. 2422 For the purposes of HTTP, a "representation" is information that is 2423 intended to reflect a past, current, or desired state of a given 2424 resource, in a format that can be readily communicated via the 2425 protocol, and that consists of a set of representation metadata and a 2426 potentially unbounded stream of representation data. 2428 An origin server might be provided with, or be capable of generating, 2429 multiple representations that are each intended to reflect the 2430 current state of a target resource. In such cases, some algorithm is 2431 used by the origin server to select one of those representations as 2432 most applicable to a given request, usually based on content 2433 negotiation. This "selected representation" is used to provide the 2434 data and metadata for evaluating conditional requests (Section 9.2) 2435 and constructing the payload for 200 (OK), 206 (Partial Content), and 2436 304 (Not Modified) responses to GET (Section 8.3.1). 2438 7.1. Representation Data 2440 The representation data associated with an HTTP message is either 2441 provided as the payload body of the message or referred to by the 2442 message semantics and the target URI. The representation data is in 2443 a format and encoding defined by the representation metadata header 2444 fields. 2446 The data type of the representation data is determined via the header 2447 fields Content-Type and Content-Encoding. These define a two-layer, 2448 ordered encoding model: 2450 representation-data := Content-Encoding( Content-Type( bits ) ) 2452 7.1.1. Media Type 2454 HTTP uses media types [RFC2046] in the Content-Type (Section 7.2.1) 2455 and Accept (Section 9.4.1) header fields in order to provide open and 2456 extensible data typing and type negotiation. Media types define both 2457 a data format and various processing models: how to process that data 2458 in accordance with each context in which it is received. 2460 media-type = type "/" subtype *( OWS ";" OWS parameter ) 2461 type = token 2462 subtype = token 2464 The type and subtype tokens are case-insensitive. 2466 The type/subtype MAY be followed by semicolon-delimited parameters 2467 (Section 5.4.1.4) in the form of name=value pairs. The presence or 2468 absence of a parameter might be significant to the processing of a 2469 media type, depending on its definition within the media type 2470 registry. Parameter values might or might not be case-sensitive, 2471 depending on the semantics of the parameter name. 2473 For example, the following media types are equivalent in describing 2474 HTML text data encoded in the UTF-8 character encoding scheme, but 2475 the first is preferred for consistency (the "charset" parameter value 2476 is defined as being case-insensitive in [RFC2046], Section 4.1.2): 2478 text/html;charset=utf-8 2479 Text/HTML;Charset="utf-8" 2480 text/html; charset="utf-8" 2481 text/html;charset=UTF-8 2483 Media types ought to be registered with IANA according to the 2484 procedures defined in [BCP13]. 2486 7.1.1.1. Charset 2488 HTTP uses charset names to indicate or negotiate the character 2489 encoding scheme of a textual representation [RFC6365]. A charset is 2490 identified by a case-insensitive token. 2492 charset = token 2494 Charset names ought to be registered in the IANA "Character Sets" 2495 registry () 2496 according to the procedures defined in Section 2 of [RFC2978]. 2498 | *Note:* In theory, charset names are defined by the "mime- 2499 | charset" ABNF rule defined in Section 2.3 of [RFC2978] (as 2500 | corrected in [Err1912]). That rule allows two characters that 2501 | are not included in "token" ("{" and "}"), but no charset name 2502 | registered at the time of this writing includes braces (see 2503 | [Err5433]). 2505 7.1.1.2. Canonicalization and Text Defaults 2507 Media types are registered with a canonical form in order to be 2508 interoperable among systems with varying native encoding formats. 2509 Representations selected or transferred via HTTP ought to be in 2510 canonical form, for many of the same reasons described by the 2511 Multipurpose Internet Mail Extensions (MIME) [RFC2045]. However, the 2512 performance characteristics of email deployments (i.e., store and 2513 forward messages to peers) are significantly different from those 2514 common to HTTP and the Web (server-based information services). 2515 Furthermore, MIME's constraints for the sake of compatibility with 2516 older mail transfer protocols do not apply to HTTP (see Appendix B of 2517 [Messaging]). 2519 MIME's canonical form requires that media subtypes of the "text" type 2520 use CRLF as the text line break. HTTP allows the transfer of text 2521 media with plain CR or LF alone representing a line break, when such 2522 line breaks are consistent for an entire representation. An HTTP 2523 sender MAY generate, and a recipient MUST be able to parse, line 2524 breaks in text media that consist of CRLF, bare CR, or bare LF. In 2525 addition, text media in HTTP is not limited to charsets that use 2526 octets 13 and 10 for CR and LF, respectively. This flexibility 2527 regarding line breaks applies only to text within a representation 2528 that has been assigned a "text" media type; it does not apply to 2529 "multipart" types or HTTP elements outside the payload body (e.g., 2530 header fields). 2532 If a representation is encoded with a content-coding, the underlying 2533 data ought to be in a form defined above prior to being encoded. 2535 7.1.1.3. Multipart Types 2537 MIME provides for a number of "multipart" types - encapsulations of 2538 one or more representations within a single message body. All 2539 multipart types share a common syntax, as defined in Section 5.1.1 of 2540 [RFC2046], and include a boundary parameter as part of the media type 2541 value. The message body is itself a protocol element; a sender MUST 2542 generate only CRLF to represent line breaks between body parts. 2544 HTTP message framing does not use the multipart boundary as an 2545 indicator of message body length, though it might be used by 2546 implementations that generate or process the payload. For example, 2547 the "multipart/form-data" type is often used for carrying form data 2548 in a request, as described in [RFC7578], and the "multipart/ 2549 byteranges" type is defined by this specification for use in some 206 2550 (Partial Content) responses (see Section 10.3.7). 2552 7.1.2. Content Codings 2554 Content coding values indicate an encoding transformation that has 2555 been or can be applied to a representation. Content codings are 2556 primarily used to allow a representation to be compressed or 2557 otherwise usefully transformed without losing the identity of its 2558 underlying media type and without loss of information. Frequently, 2559 the representation is stored in coded form, transmitted directly, and 2560 only decoded by the final recipient. 2562 content-coding = token 2564 All content codings are case-insensitive and ought to be registered 2565 within the "HTTP Content Coding Registry", as defined in 2566 Section 7.1.2.4 2568 Content-coding values are used in the Accept-Encoding (Section 9.4.3) 2569 and Content-Encoding (Section 7.2.2) header fields. 2571 The following content-coding values are defined by this 2572 specification: 2574 +------------+-------------------------------+-----------+ 2575 | Name | Description | Reference | 2576 | compress | UNIX "compress" data format | Section | 2577 | | [Welch] | 7.1.2.1 | 2578 | deflate | "deflate" compressed data | Section | 2579 | | ([RFC1951]) inside the "zlib" | 7.1.2.2 | 2580 | | data format ([RFC1950]) | | 2581 | gzip | GZIP file format [RFC1952] | Section | 2582 | | | 7.1.2.3 | 2583 | identity | Reserved | Section | 2584 | | | 9.4.3 | 2585 | x-compress | Deprecated (alias for | Section | 2586 | | compress) | 7.1.2.1 | 2587 | x-gzip | Deprecated (alias for gzip) | Section | 2588 | | | 7.1.2.3 | 2589 +------------+-------------------------------+-----------+ 2591 Table 4 2593 7.1.2.1. Compress Coding 2595 The "compress" coding is an adaptive Lempel-Ziv-Welch (LZW) coding 2596 [Welch] that is commonly produced by the UNIX file compression 2597 program "compress". A recipient SHOULD consider "x-compress" to be 2598 equivalent to "compress". 2600 7.1.2.2. Deflate Coding 2602 The "deflate" coding is a "zlib" data format [RFC1950] containing a 2603 "deflate" compressed data stream [RFC1951] that uses a combination of 2604 the Lempel-Ziv (LZ77) compression algorithm and Huffman coding. 2606 | *Note:* Some non-conformant implementations send the "deflate" 2607 | compressed data without the zlib wrapper. 2609 7.1.2.3. Gzip Coding 2611 The "gzip" coding is an LZ77 coding with a 32-bit Cyclic Redundancy 2612 Check (CRC) that is commonly produced by the gzip file compression 2613 program [RFC1952]. A recipient SHOULD consider "x-gzip" to be 2614 equivalent to "gzip". 2616 7.1.2.4. Content Coding Registry 2618 The "HTTP Content Coding Registry", maintained by IANA at 2619 , registers 2620 content-coding names. 2622 Content coding registrations MUST include the following fields: 2624 o Name 2626 o Description 2628 o Pointer to specification text 2630 Names of content codings MUST NOT overlap with names of transfer 2631 codings (Section 7 of [Messaging]), unless the encoding 2632 transformation is identical (as is the case for the compression 2633 codings defined in Section 7.1.2). 2635 Values to be added to this namespace require IETF Review (see 2636 Section 4.8 of [RFC8126]) and MUST conform to the purpose of content 2637 coding defined in Section 7.1.2. 2639 7.1.3. Language Tags 2641 A language tag, as defined in [RFC5646], identifies a natural 2642 language spoken, written, or otherwise conveyed by human beings for 2643 communication of information to other human beings. Computer 2644 languages are explicitly excluded. 2646 HTTP uses language tags within the Accept-Language and 2647 Content-Language header fields. Accept-Language uses the broader 2648 language-range production defined in Section 9.4.4, whereas 2649 Content-Language uses the language-tag production defined below. 2651 language-tag = 2653 A language tag is a sequence of one or more case-insensitive subtags, 2654 each separated by a hyphen character ("-", %x2D). In most cases, a 2655 language tag consists of a primary language subtag that identifies a 2656 broad family of related languages (e.g., "en" = English), which is 2657 optionally followed by a series of subtags that refine or narrow that 2658 language's range (e.g., "en-CA" = the variety of English as 2659 communicated in Canada). Whitespace is not allowed within a language 2660 tag. Example tags include: 2662 fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN 2664 See [RFC5646] for further information. 2666 7.1.4. Range Units 2668 Representation data can be partitioned into subranges when there are 2669 addressable structural units inherent to that data's content coding 2670 or media type. For example, octet (a.k.a., byte) boundaries are a 2671 structural unit common to all representation data, allowing 2672 partitions of the data to be identified as a range of bytes at some 2673 offset from the start or end of that data. 2675 This general notion of a "range unit" is used in the Accept-Ranges 2676 (Section 11.4.1) response header field to advertise support for range 2677 requests, the Range (Section 9.3) request header field to delineate 2678 the parts of a representation that are requested, and the 2679 Content-Range (Section 7.3.4) payload header field to describe which 2680 part of a representation is being transferred. 2682 range-unit = token 2684 All range unit names are case-insensitive and ought to be registered 2685 within the "HTTP Range Unit Registry", as defined in Section 7.1.4.4 2687 The following range unit names are defined by this document: 2689 +-----------------+----------------------------------+-----------+ 2690 | Range Unit Name | Description | Reference | 2691 | bytes | a range of octets | Section | 2692 | | | 7.1.4.2 | 2693 | none | reserved as keyword to indicate | Section | 2694 | | range requests are not supported | 11.4.1 | 2695 +-----------------+----------------------------------+-----------+ 2697 Table 5 2699 7.1.4.1. Range Specifiers 2701 Ranges are expressed in terms of a range unit paired with a set of 2702 range specifiers. The range unit name determines what kinds of 2703 range-spec are applicable to its own specifiers. Hence, the 2704 following gramar is generic: each range unit is expected to specify 2705 requirements on when int-range, suffix-range, and other-range are 2706 allowed. 2708 A range request can specify a single range or a set of ranges within 2709 a single representation. 2711 ranges-specifier = range-unit "=" range-set 2712 range-set = 1#range-spec 2713 range-spec = int-range 2714 / suffix-range 2715 / other-range 2717 An int-range is a range expressed as two non-negative integers or as 2718 one non-negative integer through to the end of the representation 2719 data. The range unit specifies what the integers mean (e.g., they 2720 might indicate unit offsets from the beginning, inclusive numbered 2721 parts, etc.). 2723 int-range = first-pos "-" [ last-pos ] 2724 first-pos = 1*DIGIT 2725 last-pos = 1*DIGIT 2727 An int-range is invalid if the last-pos value is present and less 2728 than the first-pos. 2730 A suffix-range is a range expressed as a suffix of the representation 2731 data with the provided non-negative integer maximum length (in range 2732 units). In other words, the last N units of the representation data. 2734 suffix-range = "-" suffix-length 2735 suffix-length = 1*DIGIT 2737 To provide for extensibility, the other-range rule is a mostly 2738 unconstrained grammar that allows application-specific or future 2739 range units to define additional range specifiers. 2741 other-range = 1*( %x21-2B / %x2D-7E ) 2742 ; 1*(VCHAR excluding comma) 2744 7.1.4.2. Byte Ranges 2746 The "bytes" range unit is used to express subranges of a 2747 representation data's octet sequence. Each byte range is expressed 2748 as an integer range at some offset, relative to either the beginning 2749 (int-range) or end (suffix-range) of the representation data. Byte 2750 ranges do not use the other-range specifier. 2752 The first-pos value in a bytes int-range gives the offset of the 2753 first byte in a range. The last-pos value gives the offset of the 2754 last byte in the range; that is, the byte positions specified are 2755 inclusive. Byte offsets start at zero. 2757 If the representation data has a content coding applied, each byte 2758 range is calculated with respect to the encoded sequence of bytes, 2759 not the sequence of underlying bytes that would be obtained after 2760 decoding. 2762 Examples of bytes range specifiers: 2764 o The first 500 bytes (byte offsets 0-499, inclusive): 2766 bytes=0-499 2768 o The second 500 bytes (byte offsets 500-999, inclusive): 2770 bytes=500-999 2772 A client can limit the number of bytes requested without knowing the 2773 size of the selected representation. If the last-pos value is 2774 absent, or if the value is greater than or equal to the current 2775 length of the representation data, the byte range is interpreted as 2776 the remainder of the representation (i.e., the server replaces the 2777 value of last-pos with a value that is one less than the current 2778 length of the selected representation). 2780 A client can request the last N bytes (N > 0) of the selected 2781 representation using a suffix-range. If the selected representation 2782 is shorter than the specified suffix-length, the entire 2783 representation is used. 2785 Additional examples, assuming a representation of length 10000: 2787 o The final 500 bytes (byte offsets 9500-9999, inclusive): 2789 bytes=-500 2791 Or: 2793 bytes=9500- 2795 o The first and last bytes only (bytes 0 and 9999): 2797 bytes=0-0,-1 2799 o The first, middle, and last 1000 bytes: 2801 bytes= 0-999, 4500-5499, -1000 2803 o Other valid (but not canonical) specifications of the second 500 2804 bytes (byte offsets 500-999, inclusive): 2806 bytes=500-600,601-999 2807 bytes=500-700,601-999 2809 If a valid bytes range-set includes at least one range-spec with a 2810 first-pos that is less than the current length of the representation, 2811 or at least one suffix-range with a non-zero suffix-length, then the 2812 bytes range-set is satisfiable. Otherwise, the bytes range-set is 2813 unsatisfiable. 2815 If the selected representation has zero length, the only satisfiable 2816 form of range-spec is a suffix-range with a non-zero suffix-length. 2818 In the byte-range syntax, first-pos, last-pos, and suffix-length are 2819 expressed as decimal number of octets. Since there is no predefined 2820 limit to the length of a payload, recipients MUST anticipate 2821 potentially large decimal numerals and prevent parsing errors due to 2822 integer conversion overflows. 2824 7.1.4.3. Other Range Units 2826 Other range units, such as format-specific boundaries like pages, 2827 sections, records, rows, or time, are potentially usable in HTTP for 2828 application-specific purposes, but are not commonly used in practice. 2829 Implementors of alternative range units ought to consider how they 2830 would work with content codings and general-purpose intermediaries. 2832 Range units are intended to be extensible. New range units ought to 2833 be registered with IANA, as defined in Section 7.1.4.4. 2835 7.1.4.4. Range Unit Registry 2837 The "HTTP Range Unit Registry" defines the namespace for the range 2838 unit names and refers to their corresponding specifications. It is 2839 maintained at . 2841 Registration of an HTTP Range Unit MUST include the following fields: 2843 o Name 2845 o Description 2847 o Pointer to specification text 2849 Values to be added to this namespace require IETF Review (see 2850 [RFC8126], Section 4.8). 2852 7.2. Representation Metadata 2854 Representation header fields provide metadata about the 2855 representation. When a message includes a payload body, the 2856 representation header fields describe how to interpret the 2857 representation data enclosed in the payload body. In a response to a 2858 HEAD request, the representation header fields describe the 2859 representation data that would have been enclosed in the payload body 2860 if the same request had been a GET. 2862 The following header fields convey representation metadata: 2864 +------------------+---------------+ 2865 | Field Name | Defined in... | 2866 | Content-Type | Section 7.2.1 | 2867 | Content-Encoding | Section 7.2.2 | 2868 | Content-Language | Section 7.2.3 | 2869 | Content-Length | Section 7.2.4 | 2870 | Content-Location | Section 7.2.5 | 2871 +------------------+---------------+ 2873 Table 6 2875 7.2.1. Content-Type 2877 The "Content-Type" header field indicates the media type of the 2878 associated representation: either the representation enclosed in the 2879 message payload or the selected representation, as determined by the 2880 message semantics. The indicated media type defines both the data 2881 format and how that data is intended to be processed by a recipient, 2882 within the scope of the received message semantics, after any content 2883 codings indicated by Content-Encoding are decoded. 2885 Content-Type = media-type 2887 Media types are defined in Section 7.1.1. An example of the field is 2889 Content-Type: text/html; charset=ISO-8859-4 2891 A sender that generates a message containing a payload body SHOULD 2892 generate a Content-Type header field in that message unless the 2893 intended media type of the enclosed representation is unknown to the 2894 sender. If a Content-Type header field is not present, the recipient 2895 MAY either assume a media type of "application/octet-stream" 2896 ([RFC2046], Section 4.5.1) or examine the data to determine its type. 2898 In practice, resource owners do not always properly configure their 2899 origin server to provide the correct Content-Type for a given 2900 representation. Some user agents examine a payload's content and, in 2901 certain cases, override the received type (for example, see 2902 [Sniffing]). This "MIME sniffing" risks drawing incorrect 2903 conclusions about the data, which might expose the user to additional 2904 security risks (e.g., "privilege escalation"). Furthermore, it is 2905 impossible to determine the sender's intended processing model by 2906 examining the data format: many data formats match multiple media 2907 types that differ only in processing semantics. Implementers are 2908 encouraged to provide a means to disable such sniffing. 2910 7.2.2. Content-Encoding 2912 The "Content-Encoding" header field indicates what content codings 2913 have been applied to the representation, beyond those inherent in the 2914 media type, and thus what decoding mechanisms have to be applied in 2915 order to obtain data in the media type referenced by the Content-Type 2916 header field. Content-Encoding is primarily used to allow a 2917 representation's data to be compressed without losing the identity of 2918 its underlying media type. 2920 Content-Encoding = 1#content-coding 2922 An example of its use is 2924 Content-Encoding: gzip 2926 If one or more encodings have been applied to a representation, the 2927 sender that applied the encodings MUST generate a Content-Encoding 2928 header field that lists the content codings in the order in which 2929 they were applied. Note that the coding named "identity" is reserved 2930 for its special role in Accept-Encoding, and thus SHOULD NOT be 2931 included. 2933 Additional information about the encoding parameters can be provided 2934 by other header fields not defined by this specification. 2936 Unlike Transfer-Encoding (Section 6.1 of [Messaging]), the codings 2937 listed in Content-Encoding are a characteristic of the 2938 representation; the representation is defined in terms of the coded 2939 form, and all other metadata about the representation is about the 2940 coded form unless otherwise noted in the metadata definition. 2941 Typically, the representation is only decoded just prior to rendering 2942 or analogous usage. 2944 If the media type includes an inherent encoding, such as a data 2945 format that is always compressed, then that encoding would not be 2946 restated in Content-Encoding even if it happens to be the same 2947 algorithm as one of the content codings. Such a content coding would 2948 only be listed if, for some bizarre reason, it is applied a second 2949 time to form the representation. Likewise, an origin server might 2950 choose to publish the same data as multiple representations that 2951 differ only in whether the coding is defined as part of Content-Type 2952 or Content-Encoding, since some user agents will behave differently 2953 in their handling of each response (e.g., open a "Save as ..." dialog 2954 instead of automatic decompression and rendering of content). 2956 An origin server MAY respond with a status code of 415 (Unsupported 2957 Media Type) if a representation in the request message has a content 2958 coding that is not acceptable. 2960 7.2.3. Content-Language 2962 The "Content-Language" header field describes the natural language(s) 2963 of the intended audience for the representation. Note that this 2964 might not be equivalent to all the languages used within the 2965 representation. 2967 Content-Language = 1#language-tag 2969 Language tags are defined in Section 7.1.3. The primary purpose of 2970 Content-Language is to allow a user to identify and differentiate 2971 representations according to the users' own preferred language. 2972 Thus, if the content is intended only for a Danish-literate audience, 2973 the appropriate field is 2975 Content-Language: da 2977 If no Content-Language is specified, the default is that the content 2978 is intended for all language audiences. This might mean that the 2979 sender does not consider it to be specific to any natural language, 2980 or that the sender does not know for which language it is intended. 2982 Multiple languages MAY be listed for content that is intended for 2983 multiple audiences. For example, a rendition of the "Treaty of 2984 Waitangi", presented simultaneously in the original Maori and English 2985 versions, would call for 2987 Content-Language: mi, en 2989 However, just because multiple languages are present within a 2990 representation does not mean that it is intended for multiple 2991 linguistic audiences. An example would be a beginner's language 2992 primer, such as "A First Lesson in Latin", which is clearly intended 2993 to be used by an English-literate audience. In this case, the 2994 Content-Language would properly only include "en". 2996 Content-Language MAY be applied to any media type - it is not limited 2997 to textual documents. 2999 7.2.4. Content-Length 3001 // The "Content-Length" header field indicates the number of data 3002 // octets (body length) for the representation. In some cases, 3003 // Content-Length is used to define or estimate message framing. 3005 Content-Length = 1*DIGIT 3007 An example is 3009 Content-Length: 3495 3011 A sender MUST NOT send a Content-Length header field in any message 3012 that contains a Transfer-Encoding header field. 3014 A user agent SHOULD send a Content-Length in a request message when 3015 no Transfer-Encoding is sent and the request method defines a meaning 3016 for an enclosed payload body. For example, a Content-Length header 3017 field is normally sent in a POST request even when the value is 0 3018 (indicating an empty payload body). A user agent SHOULD NOT send a 3019 Content-Length header field when the request message does not contain 3020 a payload body and the method semantics do not anticipate such a 3021 body. 3023 A server MAY send a Content-Length header field in a response to a 3024 HEAD request (Section 8.3.2); a server MUST NOT send Content-Length 3025 in such a response unless its field value equals the decimal number 3026 of octets that would have been sent in the payload body of a response 3027 if the same request had used the GET method. 3029 A server MAY send a Content-Length header field in a 304 (Not 3030 Modified) response to a conditional GET request (Section 10.4.5); a 3031 server MUST NOT send Content-Length in such a response unless its 3032 field value equals the decimal number of octets that would have been 3033 sent in the payload body of a 200 (OK) response to the same request. 3035 A server MUST NOT send a Content-Length header field in any response 3036 with a status code of 1xx (Informational) or 204 (No Content). A 3037 server MUST NOT send a Content-Length header field in any 2xx 3038 (Successful) response to a CONNECT request (Section 8.3.6). 3040 Aside from the cases defined above, in the absence of Transfer- 3041 Encoding, an origin server SHOULD send a Content-Length header field 3042 when the payload body size is known prior to sending the complete 3043 header section. This will allow downstream recipients to measure 3044 transfer progress, know when a received message is complete, and 3045 potentially reuse the connection for additional requests. 3047 Any Content-Length field value greater than or equal to zero is 3048 valid. Since there is no predefined limit to the length of a 3049 payload, a recipient MUST anticipate potentially large decimal 3050 numerals and prevent parsing errors due to integer conversion 3051 overflows (Section 12.5). 3053 If a message is received that has a Content-Length header field value 3054 consisting of the same decimal value as a comma-separated list 3055 (Section 5.5) - for example, "Content-Length: 42, 42" - indicating 3056 that duplicate Content-Length header fields have been generated or 3057 combined by an upstream message processor, then the recipient MUST 3058 either reject the message as invalid or replace the duplicated field 3059 values with a single valid Content-Length field containing that 3060 decimal value prior to determining the message body length or 3061 forwarding the message. 3063 7.2.5. Content-Location 3065 The "Content-Location" header field references a URI that can be used 3066 as an identifier for a specific resource corresponding to the 3067 representation in this message's payload. In other words, if one 3068 were to perform a GET request on this URI at the time of this 3069 message's generation, then a 200 (OK) response would contain the same 3070 representation that is enclosed as payload in this message. 3072 Content-Location = absolute-URI / partial-URI 3074 The field value is either an absolute-URI or a partial-URI. In the 3075 latter case (Section 2.4), the referenced URI is relative to the 3076 target URI ([RFC3986], Section 5). 3078 The Content-Location value is not a replacement for the target URI 3079 (Section 6.1). It is representation metadata. It has the same 3080 syntax and semantics as the header field of the same name defined for 3081 MIME body parts in Section 4 of [RFC2557]. However, its appearance 3082 in an HTTP message has some special implications for HTTP recipients. 3084 If Content-Location is included in a 2xx (Successful) response 3085 message and its value refers (after conversion to absolute form) to a 3086 URI that is the same as the target URI, then the recipient MAY 3087 consider the payload to be a current representation of that resource 3088 at the time indicated by the message origination date. For a GET 3089 (Section 8.3.1) or HEAD (Section 8.3.2) request, this is the same as 3090 the default semantics when no Content-Location is provided by the 3091 server. For a state-changing request like PUT (Section 8.3.4) or 3092 POST (Section 8.3.3), it implies that the server's response contains 3093 the new representation of that resource, thereby distinguishing it 3094 from representations that might only report about the action (e.g., 3095 "It worked!"). This allows authoring applications to update their 3096 local copies without the need for a subsequent GET request. 3098 If Content-Location is included in a 2xx (Successful) response 3099 message and its field value refers to a URI that differs from the 3100 target URI, then the origin server claims that the URI is an 3101 identifier for a different resource corresponding to the enclosed 3102 representation. Such a claim can only be trusted if both identifiers 3103 share the same resource owner, which cannot be programmatically 3104 determined via HTTP. 3106 o For a response to a GET or HEAD request, this is an indication 3107 that the target URI refers to a resource that is subject to 3108 content negotiation and the Content-Location field value is a more 3109 specific identifier for the selected representation. 3111 o For a 201 (Created) response to a state-changing method, a 3112 Content-Location field value that is identical to the Location 3113 field value indicates that this payload is a current 3114 representation of the newly created resource. 3116 o Otherwise, such a Content-Location indicates that this payload is 3117 a representation reporting on the requested action's status and 3118 that the same report is available (for future access with GET) at 3119 the given URI. For example, a purchase transaction made via a 3120 POST request might include a receipt document as the payload of 3121 the 200 (OK) response; the Content-Location field value provides 3122 an identifier for retrieving a copy of that same receipt in the 3123 future. 3125 A user agent that sends Content-Location in a request message is 3126 stating that its value refers to where the user agent originally 3127 obtained the content of the enclosed representation (prior to any 3128 modifications made by that user agent). In other words, the user 3129 agent is providing a back link to the source of the original 3130 representation. 3132 An origin server that receives a Content-Location field in a request 3133 message MUST treat the information as transitory request context 3134 rather than as metadata to be saved verbatim as part of the 3135 representation. An origin server MAY use that context to guide in 3136 processing the request or to save it for other uses, such as within 3137 source links or versioning metadata. However, an origin server MUST 3138 NOT use such context information to alter the request semantics. 3140 For example, if a client makes a PUT request on a negotiated resource 3141 and the origin server accepts that PUT (without redirection), then 3142 the new state of that resource is expected to be consistent with the 3143 one representation supplied in that PUT; the Content-Location cannot 3144 be used as a form of reverse content selection identifier to update 3145 only one of the negotiated representations. If the user agent had 3146 wanted the latter semantics, it would have applied the PUT directly 3147 to the Content-Location URI. 3149 7.3. Payload 3151 Some HTTP messages transfer a complete or partial representation as 3152 the message "payload". In some cases, a payload might contain only 3153 the associated representation's header fields (e.g., responses to 3154 HEAD) or only some part(s) of the representation data (e.g., the 206 3155 (Partial Content) status code). 3157 Header fields that specifically describe the payload, rather than the 3158 associated representation, are referred to as "payload header 3159 fields". Payload header fields are defined in other parts of this 3160 specification, due to their impact on message parsing. 3162 +-------------------+----------------------------+ 3163 | Field Name | Defined in... | 3164 | Content-Range | Section 7.3.4 | 3165 | Trailer | Section 5.6.3 | 3166 | Transfer-Encoding | Section 6.1 of [Messaging] | 3167 +-------------------+----------------------------+ 3169 Table 7 3171 7.3.1. Purpose 3173 The purpose of a payload in a request is defined by the method 3174 semantics. For example, a representation in the payload of a PUT 3175 request (Section 8.3.4) represents the desired state of the target 3176 resource if the request is successfully applied, whereas a 3177 representation in the payload of a POST request (Section 8.3.3) 3178 represents information to be processed by the target resource. 3180 In a response, the payload's purpose is defined by both the request 3181 method and the response status code. For example, the payload of a 3182 200 (OK) response to GET (Section 8.3.1) represents the current state 3183 of the target resource, as observed at the time of the message 3184 origination date (Section 11.1.1), whereas the payload of the same 3185 status code in a response to POST might represent either the 3186 processing result or the new state of the target resource after 3187 applying the processing. Response messages with an error status code 3188 usually contain a payload that represents the error condition, such 3189 that it describes the error state and what next steps are suggested 3190 for resolving it. 3192 7.3.2. Identification 3194 When a complete or partial representation is transferred in a message 3195 payload, it is often desirable for the sender to supply, or the 3196 recipient to determine, an identifier for a resource corresponding to 3197 that representation. 3199 For a request message: 3201 o If the request has a Content-Location header field, then the 3202 sender asserts that the payload is a representation of the 3203 resource identified by the Content-Location field value. However, 3204 such an assertion cannot be trusted unless it can be verified by 3205 other means (not defined by this specification). The information 3206 might still be useful for revision history links. 3208 o Otherwise, the payload is unidentified. 3210 For a response message, the following rules are applied in order 3211 until a match is found: 3213 1. If the request method is GET or HEAD and the response status code 3214 is 200 (OK), 204 (No Content), 206 (Partial Content), or 304 (Not 3215 Modified), the payload is a representation of the resource 3216 identified by the target URI (Section 6.1). 3218 2. If the request method is GET or HEAD and the response status code 3219 is 203 (Non-Authoritative Information), the payload is a 3220 potentially modified or enhanced representation of the target 3221 resource as provided by an intermediary. 3223 3. If the response has a Content-Location header field and its field 3224 value is a reference to the same URI as the target URI, the 3225 payload is a representation of the target resource. 3227 4. If the response has a Content-Location header field and its field 3228 value is a reference to a URI different from the target URI, then 3229 the sender asserts that the payload is a representation of the 3230 resource identified by the Content-Location field value. 3231 However, such an assertion cannot be trusted unless it can be 3232 verified by other means (not defined by this specification). 3234 5. Otherwise, the payload is unidentified. 3236 7.3.3. Payload Body 3238 The payload body contains the data of a request or response. This is 3239 distinct from the message body (e.g., Section 6 of [Messaging]), 3240 which is how the payload body is transferred "on the wire", and might 3241 be encoded, depending on the HTTP version in use. 3243 It is also distinct from a request or response's representation data 3244 (Section 7.1), which can be inferred from protocol operation, rather 3245 than necessarily appearing "on the wire." 3247 The presence of a payload body in a request depends on whether the 3248 request method used defines semantics for it. 3250 The presence of a payload body in a response depends on both the 3251 request method to which it is responding and the response status code 3252 (Section 10). 3254 Responses to the HEAD request method (Section 8.3.2) never include a 3255 payload body because the associated response header fields indicate 3256 only what their values would have been if the request method had been 3257 GET (Section 8.3.1). 3259 2xx (Successful) responses to a CONNECT request method 3260 (Section 8.3.6) switch the connection to tunnel mode instead of 3261 having a payload body. 3263 All 1xx (Informational), 204 (No Content), and 304 (Not Modified) 3264 responses do not include a payload body. 3266 All other responses do include a payload body, although that body 3267 might be of zero length. 3269 7.3.4. Content-Range 3271 The "Content-Range" header field is sent in a single part 206 3272 (Partial Content) response to indicate the partial range of the 3273 selected representation enclosed as the message payload, sent in each 3274 part of a multipart 206 response to indicate the range enclosed 3275 within each body part, and sent in 416 (Range Not Satisfiable) 3276 responses to provide information about the selected representation. 3278 Content-Range = range-unit SP 3279 ( range-resp / unsatisfied-range ) 3281 range-resp = incl-range "/" ( complete-length / "*" ) 3282 incl-range = first-pos "-" last-pos 3283 unsatisfied-range = "*/" complete-length 3285 complete-length = 1*DIGIT 3287 If a 206 (Partial Content) response contains a Content-Range header 3288 field with a range unit (Section 7.1.4) that the recipient does not 3289 understand, the recipient MUST NOT attempt to recombine it with a 3290 stored representation. A proxy that receives such a message SHOULD 3291 forward it downstream. 3293 For byte ranges, a sender SHOULD indicate the complete length of the 3294 representation from which the range has been extracted, unless the 3295 complete length is unknown or difficult to determine. An asterisk 3296 character ("*") in place of the complete-length indicates that the 3297 representation length was unknown when the header field was 3298 generated. 3300 The following example illustrates when the complete length of the 3301 selected representation is known by the sender to be 1234 bytes: 3303 Content-Range: bytes 42-1233/1234 3305 and this second example illustrates when the complete length is 3306 unknown: 3308 Content-Range: bytes 42-1233/* 3310 A Content-Range field value is invalid if it contains a range-resp 3311 that has a last-pos value less than its first-pos value, or a 3312 complete-length value less than or equal to its last-pos value. The 3313 recipient of an invalid Content-Range MUST NOT attempt to recombine 3314 the received content with a stored representation. 3316 A server generating a 416 (Range Not Satisfiable) response to a byte- 3317 range request SHOULD send a Content-Range header field with an 3318 unsatisfied-range value, as in the following example: 3320 Content-Range: bytes */1234 3322 The complete-length in a 416 response indicates the current length of 3323 the selected representation. 3325 The Content-Range header field has no meaning for status codes that 3326 do not explicitly describe its semantic. For this specification, 3327 only the 206 (Partial Content) and 416 (Range Not Satisfiable) status 3328 codes describe a meaning for Content-Range. 3330 The following are examples of Content-Range values in which the 3331 selected representation contains a total of 1234 bytes: 3333 o The first 500 bytes: 3335 Content-Range: bytes 0-499/1234 3337 o The second 500 bytes: 3339 Content-Range: bytes 500-999/1234 3341 o All except for the first 500 bytes: 3343 Content-Range: bytes 500-1233/1234 3345 o The last 500 bytes: 3347 Content-Range: bytes 734-1233/1234 3349 7.3.5. Media Type multipart/byteranges 3351 When a 206 (Partial Content) response message includes the content of 3352 multiple ranges, they are transmitted as body parts in a multipart 3353 message body ([RFC2046], Section 5.1) with the media type of 3354 "multipart/byteranges". 3356 The multipart/byteranges media type includes one or more body parts, 3357 each with its own Content-Type and Content-Range fields. The 3358 required boundary parameter specifies the boundary string used to 3359 separate each body part. 3361 Implementation Notes: 3363 1. Additional CRLFs might precede the first boundary string in the 3364 body. 3366 2. Although [RFC2046] permits the boundary string to be quoted, some 3367 existing implementations handle a quoted boundary string 3368 incorrectly. 3370 3. A number of clients and servers were coded to an early draft of 3371 the byteranges specification that used a media type of multipart/ 3372 x-byteranges , which is almost (but not quite) compatible with 3373 this type. 3375 Despite the name, the "multipart/byteranges" media type is not 3376 limited to byte ranges. The following example uses an "exampleunit" 3377 range unit: 3379 HTTP/1.1 206 Partial Content 3380 Date: Tue, 14 Nov 1995 06:25:24 GMT 3381 Last-Modified: Tue, 14 July 04:58:08 GMT 3382 Content-Length: 2331785 3383 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 3385 --THIS_STRING_SEPARATES 3386 Content-Type: video/example 3387 Content-Range: exampleunit 1.2-4.3/25 3389 ...the first range... 3390 --THIS_STRING_SEPARATES 3391 Content-Type: video/example 3392 Content-Range: exampleunit 11.2-14.3/25 3394 ...the second range 3395 --THIS_STRING_SEPARATES-- 3397 The following information serves as the registration form for the 3398 multipart/byteranges media type. 3400 Type name: multipart 3402 Subtype name: byteranges 3404 Required parameters: boundary 3406 Optional parameters: N/A 3408 Encoding considerations: only "7bit", "8bit", or "binary" are 3409 permitted 3411 Security considerations: see Section 12 3413 Interoperability considerations: N/A 3415 Published specification: This specification (see Section 7.3.5). 3417 Applications that use this media type: HTTP components supporting 3418 multiple ranges in a single request. 3420 Fragment identifier considerations: N/A 3422 Additional information: Deprecated alias names for this type: N/A 3424 Magic number(s): N/A 3426 File extension(s): N/A 3428 Macintosh file type code(s): N/A 3430 Person and email address to contact for further information: See Aut 3431 hors' Addresses section. 3433 Intended usage: COMMON 3435 Restrictions on usage: N/A 3437 Author: See Authors' Addresses section. 3439 Change controller: IESG 3441 7.4. Content Negotiation 3443 When responses convey payload information, whether indicating a 3444 success or an error, the origin server often has different ways of 3445 representing that information; for example, in different formats, 3446 languages, or encodings. Likewise, different users or user agents 3447 might have differing capabilities, characteristics, or preferences 3448 that could influence which representation, among those available, 3449 would be best to deliver. For this reason, HTTP provides mechanisms 3450 for content negotiation. 3452 This specification defines three patterns of content negotiation that 3453 can be made visible within the protocol: "proactive" negotiation, 3454 where the server selects the representation based upon the user 3455 agent's stated preferences, "reactive" negotiation, where the server 3456 provides a list of representations for the user agent to choose from, 3457 and "request payload" negotiation, where the user agent selects the 3458 representation for a future request based upon the server's stated 3459 preferences in past responses. Other patterns of content negotiation 3460 include "conditional content", where the representation consists of 3461 multiple parts that are selectively rendered based on user agent 3462 parameters, "active content", where the representation contains a 3463 script that makes additional (more specific) requests based on the 3464 user agent characteristics, and "Transparent Content Negotiation" 3465 ([RFC2295]), where content selection is performed by an intermediary. 3466 These patterns are not mutually exclusive, and each has trade-offs in 3467 applicability and practicality. 3469 Note that, in all cases, HTTP is not aware of the resource semantics. 3470 The consistency with which an origin server responds to requests, 3471 over time and over the varying dimensions of content negotiation, and 3472 thus the "sameness" of a resource's observed representations over 3473 time, is determined entirely by whatever entity or algorithm selects 3474 or generates those responses. 3476 7.4.1. Proactive Negotiation 3478 When content negotiation preferences are sent by the user agent in a 3479 request to encourage an algorithm located at the server to select the 3480 preferred representation, it is called proactive negotiation (a.k.a., 3481 server-driven negotiation). Selection is based on the available 3482 representations for a response (the dimensions over which it might 3483 vary, such as language, content-coding, etc.) compared to various 3484 information supplied in the request, including both the explicit 3485 negotiation fields of Section 9.4 and implicit characteristics, such 3486 as the client's network address or parts of the User-Agent field. 3488 Proactive negotiation is advantageous when the algorithm for 3489 selecting from among the available representations is difficult to 3490 describe to a user agent, or when the server desires to send its 3491 "best guess" to the user agent along with the first response (hoping 3492 to avoid the round trip delay of a subsequent request if the "best 3493 guess" is good enough for the user). In order to improve the 3494 server's guess, a user agent MAY send request header fields that 3495 describe its preferences. 3497 Proactive negotiation has serious disadvantages: 3499 o It is impossible for the server to accurately determine what might 3500 be "best" for any given user, since that would require complete 3501 knowledge of both the capabilities of the user agent and the 3502 intended use for the response (e.g., does the user want to view it 3503 on screen or print it on paper?); 3505 o Having the user agent describe its capabilities in every request 3506 can be both very inefficient (given that only a small percentage 3507 of responses have multiple representations) and a potential risk 3508 to the user's privacy; 3510 o It complicates the implementation of an origin server and the 3511 algorithms for generating responses to a request; and, 3513 o It limits the reusability of responses for shared caching. 3515 A user agent cannot rely on proactive negotiation preferences being 3516 consistently honored, since the origin server might not implement 3517 proactive negotiation for the requested resource or might decide that 3518 sending a response that doesn't conform to the user agent's 3519 preferences is better than sending a 406 (Not Acceptable) response. 3521 A Vary header field (Section 11.1.4) is often sent in a response 3522 subject to proactive negotiation to indicate what parts of the 3523 request information were used in the selection algorithm. 3525 7.4.2. Reactive Negotiation 3527 With reactive negotiation (a.k.a., agent-driven negotiation), 3528 selection of the best response representation (regardless of the 3529 status code) is performed by the user agent after receiving an 3530 initial response from the origin server that contains a list of 3531 resources for alternative representations. If the user agent is not 3532 satisfied by the initial response representation, it can perform a 3533 GET request on one or more of the alternative resources, selected 3534 based on metadata included in the list, to obtain a different form of 3535 representation for that response. Selection of alternatives might be 3536 performed automatically by the user agent or manually by the user 3537 selecting from a generated (possibly hypertext) menu. 3539 Note that the above refers to representations of the response, in 3540 general, not representations of the resource. The alternative 3541 representations are only considered representations of the target 3542 resource if the response in which those alternatives are provided has 3543 the semantics of being a representation of the target resource (e.g., 3544 a 200 (OK) response to a GET request) or has the semantics of 3545 providing links to alternative representations for the target 3546 resource (e.g., a 300 (Multiple Choices) response to a GET request). 3548 A server might choose not to send an initial representation, other 3549 than the list of alternatives, and thereby indicate that reactive 3550 negotiation by the user agent is preferred. For example, the 3551 alternatives listed in responses with the 300 (Multiple Choices) and 3552 406 (Not Acceptable) status codes include information about the 3553 available representations so that the user or user agent can react by 3554 making a selection. 3556 Reactive negotiation is advantageous when the response would vary 3557 over commonly used dimensions (such as type, language, or encoding), 3558 when the origin server is unable to determine a user agent's 3559 capabilities from examining the request, and generally when public 3560 caches are used to distribute server load and reduce network usage. 3562 Reactive negotiation suffers from the disadvantages of transmitting a 3563 list of alternatives to the user agent, which degrades user-perceived 3564 latency if transmitted in the header section, and needing a second 3565 request to obtain an alternate representation. Furthermore, this 3566 specification does not define a mechanism for supporting automatic 3567 selection, though it does not prevent such a mechanism from being 3568 developed as an extension. 3570 7.4.3. Request Payload Negotiation 3572 When content negotiation preferences are sent in a server's response, 3573 the listed preferences are called request payload negotiation because 3574 they intend to influence selection of an appropriate payload for 3575 subsequent requests to that resource. For example, the 3576 Accept-Encoding field (Section 9.4.3) can be sent in a response to 3577 indicate preferred content codings for subsequent requests to that 3578 resource [RFC7694]. 3580 | Similarly, Section 3.1 of [RFC5789] defines the "Accept-Patch" 3581 | response header field which allows discovery of which content 3582 | types are accepted in PATCH requests. 3584 7.4.4. Quality Values 3586 The content negotiation fields defined by this specification use a 3587 common parameter, named "q" (case-insensitive), to assign a relative 3588 "weight" to the preference for that associated kind of content. This 3589 weight is referred to as a "quality value" (or "qvalue") because the 3590 same parameter name is often used within server configurations to 3591 assign a weight to the relative quality of the various 3592 representations that can be selected for a resource. 3594 The weight is normalized to a real number in the range 0 through 1, 3595 where 0.001 is the least preferred and 1 is the most preferred; a 3596 value of 0 means "not acceptable". If no "q" parameter is present, 3597 the default weight is 1. 3599 weight = OWS ";" OWS "q=" qvalue 3600 qvalue = ( "0" [ "." 0*3DIGIT ] ) 3601 / ( "1" [ "." 0*3("0") ] ) 3603 A sender of qvalue MUST NOT generate more than three digits after the 3604 decimal point. User configuration of these values ought to be 3605 limited in the same fashion. 3607 8. Request Methods 3609 8.1. Overview 3611 The request method token is the primary source of request semantics; 3612 it indicates the purpose for which the client has made this request 3613 and what is expected by the client as a successful result. 3615 The request method's semantics might be further specialized by the 3616 semantics of some header fields when present in a request (Section 9) 3617 if those additional semantics do not conflict with the method. For 3618 example, a client can send conditional request header fields 3619 (Section 9.2) to make the requested action conditional on the current 3620 state of the target resource. 3622 method = token 3624 HTTP was originally designed to be usable as an interface to 3625 distributed object systems. The request method was envisioned as 3626 applying semantics to a target resource in much the same way as 3627 invoking a defined method on an identified object would apply 3628 semantics. 3630 The method token is case-sensitive because it might be used as a 3631 gateway to object-based systems with case-sensitive method names. By 3632 convention, standardized methods are defined in all-uppercase US- 3633 ASCII letters. 3635 Unlike distributed objects, the standardized request methods in HTTP 3636 are not resource-specific, since uniform interfaces provide for 3637 better visibility and reuse in network-based systems [REST]. Once 3638 defined, a standardized method ought to have the same semantics when 3639 applied to any resource, though each resource determines for itself 3640 whether those semantics are implemented or allowed. 3642 This specification defines a number of standardized methods that are 3643 commonly used in HTTP, as outlined by the following table. 3645 +---------+--------------------------------------------+-------+ 3646 | Method | Description | Sec. | 3647 | GET | Transfer a current representation of the | 8.3.1 | 3648 | | target resource. | | 3649 | HEAD | Same as GET, but do not transfer the | 8.3.2 | 3650 | | response body. | | 3651 | POST | Perform resource-specific processing on | 8.3.3 | 3652 | | the request payload. | | 3653 | PUT | Replace all current representations of the | 8.3.4 | 3654 | | target resource with the request payload. | | 3655 | DELETE | Remove all current representations of the | 8.3.5 | 3656 | | target resource. | | 3657 | CONNECT | Establish a tunnel to the server | 8.3.6 | 3658 | | identified by the target resource. | | 3659 | OPTIONS | Describe the communication options for the | 8.3.7 | 3660 | | target resource. | | 3661 | TRACE | Perform a message loop-back test along the | 8.3.8 | 3662 | | path to the target resource. | | 3663 +---------+--------------------------------------------+-------+ 3665 Table 8 3667 All general-purpose servers MUST support the methods GET and HEAD. 3668 All other methods are OPTIONAL. 3670 The set of methods allowed by a target resource can be listed in an 3671 Allow header field (Section 11.4.2). However, the set of allowed 3672 methods can change dynamically. When a request method is received 3673 that is unrecognized or not implemented by an origin server, the 3674 origin server SHOULD respond with the 501 (Not Implemented) status 3675 code. When a request method is received that is known by an origin 3676 server but not allowed for the target resource, the origin server 3677 SHOULD respond with the 405 (Method Not Allowed) status code. 3679 8.2. Common Method Properties 3681 +---------+------+------------+---------------+ 3682 | Method | Safe | Idempotent | Reference | 3683 | CONNECT | no | no | Section 8.3.6 | 3684 | DELETE | no | yes | Section 8.3.5 | 3685 | GET | yes | yes | Section 8.3.1 | 3686 | HEAD | yes | yes | Section 8.3.2 | 3687 | OPTIONS | yes | yes | Section 8.3.7 | 3688 | POST | no | no | Section 8.3.3 | 3689 | PUT | no | yes | Section 8.3.4 | 3690 | TRACE | yes | yes | Section 8.3.8 | 3691 +---------+------+------------+---------------+ 3693 Table 9 3695 8.2.1. Safe Methods 3697 Request methods are considered "safe" if their defined semantics are 3698 essentially read-only; i.e., the client does not request, and does 3699 not expect, any state change on the origin server as a result of 3700 applying a safe method to a target resource. Likewise, reasonable 3701 use of a safe method is not expected to cause any harm, loss of 3702 property, or unusual burden on the origin server. 3704 This definition of safe methods does not prevent an implementation 3705 from including behavior that is potentially harmful, that is not 3706 entirely read-only, or that causes side effects while invoking a safe 3707 method. What is important, however, is that the client did not 3708 request that additional behavior and cannot be held accountable for 3709 it. For example, most servers append request information to access 3710 log files at the completion of every response, regardless of the 3711 method, and that is considered safe even though the log storage might 3712 become full and crash the server. Likewise, a safe request initiated 3713 by selecting an advertisement on the Web will often have the side 3714 effect of charging an advertising account. 3716 Of the request methods defined by this specification, the GET, HEAD, 3717 OPTIONS, and TRACE methods are defined to be safe. 3719 The purpose of distinguishing between safe and unsafe methods is to 3720 allow automated retrieval processes (spiders) and cache performance 3721 optimization (pre-fetching) to work without fear of causing harm. In 3722 addition, it allows a user agent to apply appropriate constraints on 3723 the automated use of unsafe methods when processing potentially 3724 untrusted content. 3726 A user agent SHOULD distinguish between safe and unsafe methods when 3727 presenting potential actions to a user, such that the user can be 3728 made aware of an unsafe action before it is requested. 3730 When a resource is constructed such that parameters within the target 3731 URI have the effect of selecting an action, it is the resource 3732 owner's responsibility to ensure that the action is consistent with 3733 the request method semantics. For example, it is common for Web- 3734 based content editing software to use actions within query 3735 parameters, such as "page?do=delete". If the purpose of such a 3736 resource is to perform an unsafe action, then the resource owner MUST 3737 disable or disallow that action when it is accessed using a safe 3738 request method. Failure to do so will result in unfortunate side 3739 effects when automated processes perform a GET on every URI reference 3740 for the sake of link maintenance, pre-fetching, building a search 3741 index, etc. 3743 8.2.2. Idempotent Methods 3745 A request method is considered "idempotent" if the intended effect on 3746 the server of multiple identical requests with that method is the 3747 same as the effect for a single such request. Of the request methods 3748 defined by this specification, PUT, DELETE, and safe request methods 3749 are idempotent. 3751 Like the definition of safe, the idempotent property only applies to 3752 what has been requested by the user; a server is free to log each 3753 request separately, retain a revision control history, or implement 3754 other non-idempotent side effects for each idempotent request. 3756 Idempotent methods are distinguished because the request can be 3757 repeated automatically if a communication failure occurs before the 3758 client is able to read the server's response. For example, if a 3759 client sends a PUT request and the underlying connection is closed 3760 before any response is received, then the client can establish a new 3761 connection and retry the idempotent request. It knows that repeating 3762 the request will have the same intended effect, even if the original 3763 request succeeded, though the response might differ. 3765 A client SHOULD NOT automatically retry a request with a non- 3766 idempotent method unless it has some means to know that the request 3767 semantics are actually idempotent, regardless of the method, or some 3768 means to detect that the original request was never applied. 3770 For example, a user agent that knows (through design or 3771 configuration) that a POST request to a given resource is safe can 3772 repeat that request automatically. Likewise, a user agent designed 3773 specifically to operate on a version control repository might be able 3774 to recover from partial failure conditions by checking the target 3775 resource revision(s) after a failed connection, reverting or fixing 3776 any changes that were partially applied, and then automatically 3777 retrying the requests that failed. 3779 Some clients use weaker signals to initiate automatic retries. For 3780 example, when a POST request is sent, but the underlying transport 3781 connection is closed before any part of the response is received. 3782 Although this is commonly implemented, it is not recommended. 3784 A proxy MUST NOT automatically retry non-idempotent requests. A 3785 client SHOULD NOT automatically retry a failed automatic retry. 3787 8.2.3. Methods and Caching 3789 For a cache to store and use a response, the associated method needs 3790 to explicitly allow caching, and detail under what conditions a 3791 response can be used to satisfy subsequent requests; a method 3792 definition which does not do so cannot be cached. For additional 3793 requirements see [Caching]. 3795 This specification defines caching semantics for GET, HEAD, and POST, 3796 although the overwhelming majority of cache implementations only 3797 support GET and HEAD. 3799 8.3. Method Definitions 3801 8.3.1. GET 3803 The GET method requests transfer of a current selected representation 3804 for the target resource. GET is the primary mechanism of information 3805 retrieval and the focus of almost all performance optimizations. 3806 Hence, when people speak of retrieving some identifiable information 3807 via HTTP, they are generally referring to making a GET request. 3809 The GET method is specifically intended to reflect the quality of 3810 "sameness" identified by the request URI as if it were referenced as 3811 an ordinary hypertext link. 3813 It is tempting to think of resource identifiers as remote file system 3814 pathnames and of representations as being a copy of the contents of 3815 such files. In fact, that is how many resources are implemented (see 3816 Section 12.3 for related security considerations). However, there 3817 are no such limitations in practice. The HTTP interface for a 3818 resource is just as likely to be implemented as a tree of content 3819 objects, a programmatic view on various database records, or a 3820 gateway to other information systems. Even when the URI mapping 3821 mechanism is tied to a file system, an origin server might be 3822 configured to execute the files with the request as input and send 3823 the output as the representation rather than transfer the files 3824 directly. Regardless, only the origin server needs to know how each 3825 of its resource identifiers corresponds to an implementation and how 3826 each implementation manages to select and send a current 3827 representation of the target resource in a response to GET. 3829 A client can alter the semantics of GET to be a "range request", 3830 requesting transfer of only some part(s) of the selected 3831 representation, by sending a Range header field in the request 3832 (Section 9.3). 3834 A client SHOULD NOT generate a body in a GET request. A payload 3835 received in a GET request has no defined semantics, cannot alter the 3836 meaning or target of the request, and might lead some implementations 3837 to reject the request and close the connection because of its 3838 potential as a request smuggling attack (Section 11.2 of 3839 [Messaging]). 3841 The response to a GET request is cacheable; a cache MAY use it to 3842 satisfy subsequent GET and HEAD requests unless otherwise indicated 3843 by the Cache-Control header field (Section 5.2 of [Caching]). A 3844 cache that receives a payload in a GET request is likely to ignore 3845 that payload and cache regardless of the payload contents. 3847 8.3.2. HEAD 3849 The HEAD method is identical to GET except that the server MUST NOT 3850 send a message body in the response (i.e., the response terminates at 3851 the end of the header section). The server SHOULD send the same 3852 header fields in response to a HEAD request as it would have sent if 3853 the request had been a GET, except that the payload header fields 3854 (Section 7.3) MAY be omitted. This method can be used for obtaining 3855 metadata about the selected representation without transferring the 3856 representation data and is often used for testing hypertext links for 3857 validity, accessibility, and recent modification. 3859 A payload within a HEAD request message has no defined semantics; 3860 sending a payload body on a HEAD request might cause some existing 3861 implementations to reject the request. 3863 The response to a HEAD request is cacheable; a cache MAY use it to 3864 satisfy subsequent HEAD requests unless otherwise indicated by the 3865 Cache-Control header field (Section 5.2 of [Caching]). A HEAD 3866 response might also have an effect on previously cached responses to 3867 GET; see Section 4.3.5 of [Caching]. 3869 8.3.3. POST 3871 The POST method requests that the target resource process the 3872 representation enclosed in the request according to the resource's 3873 own specific semantics. For example, POST is used for the following 3874 functions (among others): 3876 o Providing a block of data, such as the fields entered into an HTML 3877 form, to a data-handling process; 3879 o Posting a message to a bulletin board, newsgroup, mailing list, 3880 blog, or similar group of articles; 3882 o Creating a new resource that has yet to be identified by the 3883 origin server; and 3885 o Appending data to a resource's existing representation(s). 3887 An origin server indicates response semantics by choosing an 3888 appropriate status code depending on the result of processing the 3889 POST request; almost all of the status codes defined by this 3890 specification might be received in a response to POST (the exceptions 3891 being 206 (Partial Content), 304 (Not Modified), and 416 (Range Not 3892 Satisfiable)). 3894 If one or more resources has been created on the origin server as a 3895 result of successfully processing a POST request, the origin server 3896 SHOULD send a 201 (Created) response containing a Location header 3897 field that provides an identifier for the primary resource created 3898 (Section 11.1.2) and a representation that describes the status of 3899 the request while referring to the new resource(s). 3901 Responses to POST requests are only cacheable when they include 3902 explicit freshness information (see Section 4.2.1 of [Caching]) and a 3903 Content-Location header field that has the same value as the POST's 3904 target URI (Section 7.2.5). A cached POST response can be reused to 3905 satisfy a later GET or HEAD request, but not a POST request, since 3906 POST is required to be written through to the origin server, because 3907 it is unsafe; see Section 4 of [Caching]. 3909 If the result of processing a POST would be equivalent to a 3910 representation of an existing resource, an origin server MAY redirect 3911 the user agent to that resource by sending a 303 (See Other) response 3912 with the existing resource's identifier in the Location field. This 3913 has the benefits of providing the user agent a resource identifier 3914 and transferring the representation via a method more amenable to 3915 shared caching, though at the cost of an extra request if the user 3916 agent does not already have the representation cached. 3918 8.3.4. PUT 3920 The PUT method requests that the state of the target resource be 3921 created or replaced with the state defined by the representation 3922 enclosed in the request message payload. A successful PUT of a given 3923 representation would suggest that a subsequent GET on that same 3924 target resource will result in an equivalent representation being 3925 sent in a 200 (OK) response. However, there is no guarantee that 3926 such a state change will be observable, since the target resource 3927 might be acted upon by other user agents in parallel, or might be 3928 subject to dynamic processing by the origin server, before any 3929 subsequent GET is received. A successful response only implies that 3930 the user agent's intent was achieved at the time of its processing by 3931 the origin server. 3933 If the target resource does not have a current representation and the 3934 PUT successfully creates one, then the origin server MUST inform the 3935 user agent by sending a 201 (Created) response. If the target 3936 resource does have a current representation and that representation 3937 is successfully modified in accordance with the state of the enclosed 3938 representation, then the origin server MUST send either a 200 (OK) or 3939 a 204 (No Content) response to indicate successful completion of the 3940 request. 3942 An origin server SHOULD ignore unrecognized header and trailer fields 3943 received in a PUT request (i.e., do not save them as part of the 3944 resource state). 3946 An origin server SHOULD verify that the PUT representation is 3947 consistent with any constraints the server has for the target 3948 resource that cannot or will not be changed by the PUT. This is 3949 particularly important when the origin server uses internal 3950 configuration information related to the URI in order to set the 3951 values for representation metadata on GET responses. When a PUT 3952 representation is inconsistent with the target resource, the origin 3953 server SHOULD either make them consistent, by transforming the 3954 representation or changing the resource configuration, or respond 3955 with an appropriate error message containing sufficient information 3956 to explain why the representation is unsuitable. The 409 (Conflict) 3957 or 415 (Unsupported Media Type) status codes are suggested, with the 3958 latter being specific to constraints on Content-Type values. 3960 For example, if the target resource is configured to always have a 3961 Content-Type of "text/html" and the representation being PUT has a 3962 Content-Type of "image/jpeg", the origin server ought to do one of: 3964 a. reconfigure the target resource to reflect the new media type; 3966 b. transform the PUT representation to a format consistent with that 3967 of the resource before saving it as the new resource state; or, 3969 c. reject the request with a 415 (Unsupported Media Type) response 3970 indicating that the target resource is limited to "text/html", 3971 perhaps including a link to a different resource that would be a 3972 suitable target for the new representation. 3974 HTTP does not define exactly how a PUT method affects the state of an 3975 origin server beyond what can be expressed by the intent of the user 3976 agent request and the semantics of the origin server response. It 3977 does not define what a resource might be, in any sense of that word, 3978 beyond the interface provided via HTTP. It does not define how 3979 resource state is "stored", nor how such storage might change as a 3980 result of a change in resource state, nor how the origin server 3981 translates resource state into representations. Generally speaking, 3982 all implementation details behind the resource interface are 3983 intentionally hidden by the server. 3985 An origin server MUST NOT send a validator header field 3986 (Section 11.2), such as an ETag or Last-Modified field, in a 3987 successful response to PUT unless the request's representation data 3988 was saved without any transformation applied to the body (i.e., the 3989 resource's new representation data is identical to the representation 3990 data received in the PUT request) and the validator field value 3991 reflects the new representation. This requirement allows a user 3992 agent to know when the representation body it has in memory remains 3993 current as a result of the PUT, thus not in need of being retrieved 3994 again from the origin server, and that the new validator(s) received 3995 in the response can be used for future conditional requests in order 3996 to prevent accidental overwrites (Section 9.2). 3998 The fundamental difference between the POST and PUT methods is 3999 highlighted by the different intent for the enclosed representation. 4000 The target resource in a POST request is intended to handle the 4001 enclosed representation according to the resource's own semantics, 4002 whereas the enclosed representation in a PUT request is defined as 4003 replacing the state of the target resource. Hence, the intent of PUT 4004 is idempotent and visible to intermediaries, even though the exact 4005 effect is only known by the origin server. 4007 Proper interpretation of a PUT request presumes that the user agent 4008 knows which target resource is desired. A service that selects a 4009 proper URI on behalf of the client, after receiving a state-changing 4010 request, SHOULD be implemented using the POST method rather than PUT. 4011 If the origin server will not make the requested PUT state change to 4012 the target resource and instead wishes to have it applied to a 4013 different resource, such as when the resource has been moved to a 4014 different URI, then the origin server MUST send an appropriate 3xx 4015 (Redirection) response; the user agent MAY then make its own decision 4016 regarding whether or not to redirect the request. 4018 A PUT request applied to the target resource can have side effects on 4019 other resources. For example, an article might have a URI for 4020 identifying "the current version" (a resource) that is separate from 4021 the URIs identifying each particular version (different resources 4022 that at one point shared the same state as the current version 4023 resource). A successful PUT request on "the current version" URI 4024 might therefore create a new version resource in addition to changing 4025 the state of the target resource, and might also cause links to be 4026 added between the related resources. 4028 An origin server that allows PUT on a given target resource MUST send 4029 a 400 (Bad Request) response to a PUT request that contains a 4030 Content-Range header field (Section 7.3.4), since the payload is 4031 likely to be partial content that has been mistakenly PUT as a full 4032 representation. Partial content updates are possible by targeting a 4033 separately identified resource with state that overlaps a portion of 4034 the larger resource, or by using a different method that has been 4035 specifically defined for partial updates (for example, the PATCH 4036 method defined in [RFC5789]). 4038 Responses to the PUT method are not cacheable. If a successful PUT 4039 request passes through a cache that has one or more stored responses 4040 for the target URI, those stored responses will be invalidated (see 4041 Section 4.4 of [Caching]). 4043 8.3.5. DELETE 4045 The DELETE method requests that the origin server remove the 4046 association between the target resource and its current 4047 functionality. In effect, this method is similar to the rm command 4048 in UNIX: it expresses a deletion operation on the URI mapping of the 4049 origin server rather than an expectation that the previously 4050 associated information be deleted. 4052 If the target resource has one or more current representations, they 4053 might or might not be destroyed by the origin server, and the 4054 associated storage might or might not be reclaimed, depending 4055 entirely on the nature of the resource and its implementation by the 4056 origin server (which are beyond the scope of this specification). 4057 Likewise, other implementation aspects of a resource might need to be 4058 deactivated or archived as a result of a DELETE, such as database or 4059 gateway connections. In general, it is assumed that the origin 4060 server will only allow DELETE on resources for which it has a 4061 prescribed mechanism for accomplishing the deletion. 4063 Relatively few resources allow the DELETE method - its primary use is 4064 for remote authoring environments, where the user has some direction 4065 regarding its effect. For example, a resource that was previously 4066 created using a PUT request, or identified via the Location header 4067 field after a 201 (Created) response to a POST request, might allow a 4068 corresponding DELETE request to undo those actions. Similarly, 4069 custom user agent implementations that implement an authoring 4070 function, such as revision control clients using HTTP for remote 4071 operations, might use DELETE based on an assumption that the server's 4072 URI space has been crafted to correspond to a version repository. 4074 If a DELETE method is successfully applied, the origin server SHOULD 4075 send 4077 o a 202 (Accepted) status code if the action will likely succeed but 4078 has not yet been enacted, 4080 o a 204 (No Content) status code if the action has been enacted and 4081 no further information is to be supplied, or 4083 o a 200 (OK) status code if the action has been enacted and the 4084 response message includes a representation describing the status. 4086 A client SHOULD NOT generate a body in a DELETE request. A payload 4087 received in a DELETE request has no defined semantics, cannot alter 4088 the meaning or target of the request, and might lead some 4089 implementations to reject the request. 4091 Responses to the DELETE method are not cacheable. If a successful 4092 DELETE request passes through a cache that has one or more stored 4093 responses for the target URI, those stored responses will be 4094 invalidated (see Section 4.4 of [Caching]). 4096 8.3.6. CONNECT 4098 The CONNECT method requests that the recipient establish a tunnel to 4099 the destination origin server identified by the request target and, 4100 if successful, thereafter restrict its behavior to blind forwarding 4101 of data, in both directions, until the tunnel is closed. Tunnels are 4102 commonly used to create an end-to-end virtual connection, through one 4103 or more proxies, which can then be secured using TLS (Transport Layer 4104 Security, [RFC8446]). 4106 Because CONNECT changes the request/response nature of an HTTP 4107 connection, specific HTTP versions might have different ways of 4108 mapping its semantics into the protocol's wire format. 4110 CONNECT is intended only for use in requests to a proxy. An origin 4111 server that receives a CONNECT request for itself MAY respond with a 4112 2xx (Successful) status code to indicate that a connection is 4113 established. However, most origin servers do not implement CONNECT. 4115 A client sending a CONNECT request MUST send the authority component 4116 (described in Section 3.2 of [RFC3986]) as the request target; i.e., 4117 the request target consists of only the host name and port number of 4118 the tunnel destination, separated by a colon. For example, 4120 CONNECT server.example.com:80 HTTP/1.1 4121 Host: server.example.com:80 4123 The recipient proxy can establish a tunnel either by directly 4124 connecting to the request target or, if configured to use another 4125 proxy, by forwarding the CONNECT request to the next inbound proxy. 4126 Any 2xx (Successful) response indicates that the sender (and all 4127 inbound proxies) will switch to tunnel mode immediately after the 4128 blank line that concludes the successful response's header section; 4129 data received after that blank line is from the server identified by 4130 the request target. Any response other than a successful response 4131 indicates that the tunnel has not yet been formed and that the 4132 connection remains governed by HTTP. 4134 A tunnel is closed when a tunnel intermediary detects that either 4135 side has closed its connection: the intermediary MUST attempt to send 4136 any outstanding data that came from the closed side to the other 4137 side, close both connections, and then discard any remaining data 4138 left undelivered. 4140 Proxy authentication might be used to establish the authority to 4141 create a tunnel. For example, 4143 CONNECT server.example.com:80 HTTP/1.1 4144 Host: server.example.com:80 4145 Proxy-Authorization: basic aGVsbG86d29ybGQ= 4147 There are significant risks in establishing a tunnel to arbitrary 4148 servers, particularly when the destination is a well-known or 4149 reserved TCP port that is not intended for Web traffic. For example, 4150 a CONNECT to "example.com:25" would suggest that the proxy connect to 4151 the reserved port for SMTP traffic; if allowed, that could trick the 4152 proxy into relaying spam email. Proxies that support CONNECT SHOULD 4153 restrict its use to a limited set of known ports or a configurable 4154 whitelist of safe request targets. 4156 A server MUST NOT send any Transfer-Encoding or Content-Length header 4157 fields in a 2xx (Successful) response to CONNECT. A client MUST 4158 ignore any Content-Length or Transfer-Encoding header fields received 4159 in a successful response to CONNECT. 4161 A payload within a CONNECT request message has no defined semantics; 4162 sending a payload body on a CONNECT request might cause some existing 4163 implementations to reject the request. 4165 Responses to the CONNECT method are not cacheable. 4167 8.3.7. OPTIONS 4169 The OPTIONS method requests information about the communication 4170 options available for the target resource, at either the origin 4171 server or an intervening intermediary. This method allows a client 4172 to determine the options and/or requirements associated with a 4173 resource, or the capabilities of a server, without implying a 4174 resource action. 4176 An OPTIONS request with an asterisk ("*") as the request target 4177 (Section 6.1) applies to the server in general rather than to a 4178 specific resource. Since a server's communication options typically 4179 depend on the resource, the "*" request is only useful as a "ping" or 4180 "no-op" type of method; it does nothing beyond allowing the client to 4181 test the capabilities of the server. For example, this can be used 4182 to test a proxy for HTTP/1.1 conformance (or lack thereof). 4184 If the request target is not an asterisk, the OPTIONS request applies 4185 to the options that are available when communicating with the target 4186 resource. 4188 A server generating a successful response to OPTIONS SHOULD send any 4189 header that might indicate optional features implemented by the 4190 server and applicable to the target resource (e.g., Allow), including 4191 potential extensions not defined by this specification. The response 4192 payload, if any, might also describe the communication options in a 4193 machine or human-readable representation. A standard format for such 4194 a representation is not defined by this specification, but might be 4195 defined by future extensions to HTTP. 4197 A client MAY send a Max-Forwards header field in an OPTIONS request 4198 to target a specific recipient in the request chain (see 4199 Section 9.1.2). A proxy MUST NOT generate a Max-Forwards header 4200 field while forwarding a request unless that request was received 4201 with a Max-Forwards field. 4203 A client that generates an OPTIONS request containing a payload body 4204 MUST send a valid Content-Type header field describing the 4205 representation media type. Note that this specification does not 4206 define any use for such a payload. 4208 Responses to the OPTIONS method are not cacheable. 4210 8.3.8. TRACE 4212 The TRACE method requests a remote, application-level loop-back of 4213 the request message. The final recipient of the request SHOULD 4214 reflect the message received, excluding some fields described below, 4215 back to the client as the message body of a 200 (OK) response with a 4216 Content-Type of "message/http" (Section 10.1 of [Messaging]). The 4217 final recipient is either the origin server or the first server to 4218 receive a Max-Forwards value of zero (0) in the request 4219 (Section 9.1.2). 4221 A client MUST NOT generate fields in a TRACE request containing 4222 sensitive data that might be disclosed by the response. For example, 4223 it would be foolish for a user agent to send stored user credentials 4224 Section 9.5 or cookies [RFC6265] in a TRACE request. The final 4225 recipient of the request SHOULD exclude any request fields that are 4226 likely to contain sensitive data when that recipient generates the 4227 response body. 4229 TRACE allows the client to see what is being received at the other 4230 end of the request chain and use that data for testing or diagnostic 4231 information. The value of the Via header field (Section 6.7.1) is of 4232 particular interest, since it acts as a trace of the request chain. 4233 Use of the Max-Forwards header field allows the client to limit the 4234 length of the request chain, which is useful for testing a chain of 4235 proxies forwarding messages in an infinite loop. 4237 A client MUST NOT send a message body in a TRACE request. 4239 Responses to the TRACE method are not cacheable. 4241 8.4. Method Extensibility 4243 Additional methods, outside the scope of this specification, have 4244 been specified for use in HTTP. All such methods ought to be 4245 registered within the "Hypertext Transfer Protocol (HTTP) Method 4246 Registry". 4248 8.4.1. Method Registry 4250 The "Hypertext Transfer Protocol (HTTP) Method Registry", maintained 4251 by IANA at , registers 4252 method names. 4254 HTTP method registrations MUST include the following fields: 4256 o Method Name (see Section 8) 4257 o Safe ("yes" or "no", see Section 8.2.1) 4259 o Idempotent ("yes" or "no", see Section 8.2.2) 4261 o Pointer to specification text 4263 Values to be added to this namespace require IETF Review (see 4264 [RFC8126], Section 4.8). 4266 8.4.2. Considerations for New Methods 4268 Standardized methods are generic; that is, they are potentially 4269 applicable to any resource, not just one particular media type, kind 4270 of resource, or application. As such, it is preferred that new 4271 methods be registered in a document that isn't specific to a single 4272 application or data format, since orthogonal technologies deserve 4273 orthogonal specification. 4275 Since message parsing (Section 6 of [Messaging]) needs to be 4276 independent of method semantics (aside from responses to HEAD), 4277 definitions of new methods cannot change the parsing algorithm or 4278 prohibit the presence of a message body on either the request or the 4279 response message. Definitions of new methods can specify that only a 4280 zero-length message body is allowed by requiring a Content-Length 4281 header field with a value of "0". 4283 A new method definition needs to indicate whether it is safe 4284 (Section 8.2.1), idempotent (Section 8.2.2), cacheable 4285 (Section 8.2.3), what semantics are to be associated with the payload 4286 body if any is present in the request and what refinements the method 4287 makes to header field or status code semantics. If the new method is 4288 cacheable, its definition ought to describe how, and under what 4289 conditions, a cache can store a response and use it to satisfy a 4290 subsequent request. The new method ought to describe whether it can 4291 be made conditional (Section 9.2) and, if so, how a server responds 4292 when the condition is false. Likewise, if the new method might have 4293 some use for partial response semantics (Section 9.3), it ought to 4294 document this, too. 4296 | *Note:* Avoid defining a method name that starts with "M-", 4297 | since that prefix might be misinterpreted as having the 4298 | semantics assigned to it by [RFC2774]. 4300 9. Request Header Fields 4302 A client sends request header fields to provide more information 4303 about the request context, make the request conditional based on the 4304 target resource state, suggest preferred formats for the response, 4305 supply authentication credentials, or modify the expected request 4306 processing. These fields act as request modifiers, similar to the 4307 parameters on a programming language method invocation. 4309 9.1. Controls 4311 Controls are request header fields that direct specific handling of 4312 the request. 4314 +---------------+----------------------------+ 4315 | Field Name | Defined in... | 4316 | Cache-Control | Section 5.2 of [Caching] | 4317 | Expect | Section 9.1.1 | 4318 | Host | Section 6.6 | 4319 | Max-Forwards | Section 9.1.2 | 4320 | Pragma | Section 5.4 of [Caching] | 4321 | TE | Section 7.4 of [Messaging] | 4322 +---------------+----------------------------+ 4324 Table 10 4326 9.1.1. Expect 4328 The "Expect" header field in a request indicates a certain set of 4329 behaviors (expectations) that need to be supported by the server in 4330 order to properly handle this request. The only such expectation 4331 defined by this specification is 100-continue. 4333 Expect = "100-continue" 4335 The Expect field value is case-insensitive. 4337 A server that receives an Expect field value other than 100-continue 4338 MAY respond with a 417 (Expectation Failed) status code to indicate 4339 that the unexpected expectation cannot be met. 4341 A 100-continue expectation informs recipients that the client is 4342 about to send a (presumably large) message body in this request and 4343 wishes to receive a 100 (Continue) interim response if the method, 4344 target URI, and header fields are not sufficient to cause an 4345 immediate success, redirect, or error response. This allows the 4346 client to wait for an indication that it is worthwhile to send the 4347 message body before actually doing so, which can improve efficiency 4348 when the message body is huge or when the client anticipates that an 4349 error is likely (e.g., when sending a state-changing method, for the 4350 first time, without previously verified authentication credentials). 4352 For example, a request that begins with 4354 PUT /somewhere/fun HTTP/1.1 4355 Host: origin.example.com 4356 Content-Type: video/h264 4357 Content-Length: 1234567890987 4358 Expect: 100-continue 4360 allows the origin server to immediately respond with an error 4361 message, such as 401 (Unauthorized) or 405 (Method Not Allowed), 4362 before the client starts filling the pipes with an unnecessary data 4363 transfer. 4365 Requirements for clients: 4367 o A client MUST NOT generate a 100-continue expectation in a request 4368 that does not include a message body. 4370 o A client that will wait for a 100 (Continue) response before 4371 sending the request message body MUST send an Expect header field 4372 containing a 100-continue expectation. 4374 o A client that sends a 100-continue expectation is not required to 4375 wait for any specific length of time; such a client MAY proceed to 4376 send the message body even if it has not yet received a response. 4377 Furthermore, since 100 (Continue) responses cannot be sent through 4378 an HTTP/1.0 intermediary, such a client SHOULD NOT wait for an 4379 indefinite period before sending the message body. 4381 o A client that receives a 417 (Expectation Failed) status code in 4382 response to a request containing a 100-continue expectation SHOULD 4383 repeat that request without a 100-continue expectation, since the 4384 417 response merely indicates that the response chain does not 4385 support expectations (e.g., it passes through an HTTP/1.0 server). 4387 Requirements for servers: 4389 o A server that receives a 100-continue expectation in an HTTP/1.0 4390 request MUST ignore that expectation. 4392 o A server MAY omit sending a 100 (Continue) response if it has 4393 already received some or all of the message body for the 4394 corresponding request, or if the framing indicates that there is 4395 no message body. 4397 o A server that sends a 100 (Continue) response MUST ultimately send 4398 a final status code, once the message body is received and 4399 processed, unless the connection is closed prematurely. 4401 o A server that responds with a final status code before reading the 4402 entire request payload body SHOULD indicate whether it intends to 4403 close the connection (see Section 9.7 of [Messaging]) or continue 4404 reading the payload body. 4406 An origin server MUST, upon receiving an HTTP/1.1 (or later) request 4407 that has a method, target URI, and complete header section that 4408 contains a 100-continue expectation and indicates a request message 4409 body will follow, either send an immediate response with a final 4410 status code, if that status can be determined by examining just the 4411 method, target URI, and header fields, or send an immediate 100 4412 (Continue) response to encourage the client to send the request's 4413 message body. The origin server MUST NOT wait for the message body 4414 before sending the 100 (Continue) response. 4416 A proxy MUST, upon receiving an HTTP/1.1 (or later) request that has 4417 a method, target URI, and complete header section that contains a 4418 100-continue expectation and indicates a request message body will 4419 follow, either send an immediate response with a final status code, 4420 if that status can be determined by examining just the method, target 4421 URI, and header fields, or begin forwarding the request toward the 4422 origin server by sending a corresponding request-line and header 4423 section to the next inbound server. If the proxy believes (from 4424 configuration or past interaction) that the next inbound server only 4425 supports HTTP/1.0, the proxy MAY generate an immediate 100 (Continue) 4426 response to encourage the client to begin sending the message body. 4428 | *Note:* The Expect header field was added after the original 4429 | publication of HTTP/1.1 [RFC2068] as both the means to request 4430 | an interim 100 (Continue) response and the general mechanism 4431 | for indicating must-understand extensions. However, the 4432 | extension mechanism has not been used by clients and the must- 4433 | understand requirements have not been implemented by many 4434 | servers, rendering the extension mechanism useless. This 4435 | specification has removed the extension mechanism in order to 4436 | simplify the definition and processing of 100-continue. 4438 9.1.2. Max-Forwards 4440 The "Max-Forwards" header field provides a mechanism with the TRACE 4441 (Section 8.3.8) and OPTIONS (Section 8.3.7) request methods to limit 4442 the number of times that the request is forwarded by proxies. This 4443 can be useful when the client is attempting to trace a request that 4444 appears to be failing or looping mid-chain. 4446 Max-Forwards = 1*DIGIT 4448 The Max-Forwards value is a decimal integer indicating the remaining 4449 number of times this request message can be forwarded. 4451 Each intermediary that receives a TRACE or OPTIONS request containing 4452 a Max-Forwards header field MUST check and update its value prior to 4453 forwarding the request. If the received value is zero (0), the 4454 intermediary MUST NOT forward the request; instead, the intermediary 4455 MUST respond as the final recipient. If the received Max-Forwards 4456 value is greater than zero, the intermediary MUST generate an updated 4457 Max-Forwards field in the forwarded message with a field value that 4458 is the lesser of a) the received value decremented by one (1) or b) 4459 the recipient's maximum supported value for Max-Forwards. 4461 A recipient MAY ignore a Max-Forwards header field received with any 4462 other request methods. 4464 9.2. Preconditions 4466 A conditional request is an HTTP request with one or more request 4467 header fields that indicate a precondition to be tested before 4468 applying the request method to the target resource. Section 9.2.1 4469 defines when preconditions are applied. Section 9.2.2 defines the 4470 order of evaluation when more than one precondition is present. 4472 Conditional GET requests are the most efficient mechanism for HTTP 4473 cache updates [Caching]. Conditionals can also be applied to state- 4474 changing methods, such as PUT and DELETE, to prevent the "lost 4475 update" problem: one client accidentally overwriting the work of 4476 another client that has been acting in parallel. 4478 Conditional request preconditions are based on the state of the 4479 target resource as a whole (its current value set) or the state as 4480 observed in a previously obtained representation (one value in that 4481 set). A resource might have multiple current representations, each 4482 with its own observable state. The conditional request mechanisms 4483 assume that the mapping of requests to a selected representation 4484 (Section 7) will be consistent over time if the server intends to 4485 take advantage of conditionals. Regardless, if the mapping is 4486 inconsistent and the server is unable to select the appropriate 4487 representation, then no harm will result when the precondition 4488 evaluates to false. 4490 The following request header fields allow a client to place a 4491 precondition on the state of the target resource, so that the action 4492 corresponding to the method semantics will not be applied if the 4493 precondition evaluates to false. Each precondition defined by this 4494 specification consists of a comparison between a set of validators 4495 obtained from prior representations of the target resource to the 4496 current state of validators for the selected representation 4497 (Section 11.2). Hence, these preconditions evaluate whether the 4498 state of the target resource has changed since a given state known by 4499 the client. The effect of such an evaluation depends on the method 4500 semantics and choice of conditional, as defined in Section 9.2.1. 4502 +---------------------+---------------+ 4503 | Field Name | Defined in... | 4504 | If-Match | Section 9.2.3 | 4505 | If-None-Match | Section 9.2.4 | 4506 | If-Modified-Since | Section 9.2.5 | 4507 | If-Unmodified-Since | Section 9.2.6 | 4508 | If-Range | Section 9.2.7 | 4509 +---------------------+---------------+ 4511 Table 11 4513 9.2.1. Evaluation 4515 Except when excluded below, a recipient cache or origin server MUST 4516 evaluate received request preconditions after it has successfully 4517 performed its normal request checks and just before it would perform 4518 the action associated with the request method. A server MUST ignore 4519 all received preconditions if its response to the same request 4520 without those conditions would have been a status code other than a 4521 2xx (Successful) or 412 (Precondition Failed). In other words, 4522 redirects and failures take precedence over the evaluation of 4523 preconditions in conditional requests. 4525 A server that is not the origin server for the target resource and 4526 cannot act as a cache for requests on the target resource MUST NOT 4527 evaluate the conditional request header fields defined by this 4528 specification, and it MUST forward them if the request is forwarded, 4529 since the generating client intends that they be evaluated by a 4530 server that can provide a current representation. Likewise, a server 4531 MUST ignore the conditional request header fields defined by this 4532 specification when received with a request method that does not 4533 involve the selection or modification of a selected representation, 4534 such as CONNECT, OPTIONS, or TRACE. 4536 Note that protocol extensions can modify the conditions under which 4537 revalidation is triggered. For example, the "immutable" cache 4538 directive (defined by [RFC8246]) instructs caches to forgo 4539 revalidation of fresh responses even when requested by the client. 4541 Conditional request header fields that are defined by extensions to 4542 HTTP might place conditions on all recipients, on the state of the 4543 target resource in general, or on a group of resources. For 4544 instance, the "If" header field in WebDAV can make a request 4545 conditional on various aspects of multiple resources, such as locks, 4546 if the recipient understands and implements that field ([RFC4918], 4547 Section 10.4). 4549 Although conditional request header fields are defined as being 4550 usable with the HEAD method (to keep HEAD's semantics consistent with 4551 those of GET), there is no point in sending a conditional HEAD 4552 because a successful response is around the same size as a 304 (Not 4553 Modified) response and more useful than a 412 (Precondition Failed) 4554 response. 4556 9.2.2. Precedence 4558 When more than one conditional request header field is present in a 4559 request, the order in which the fields are evaluated becomes 4560 important. In practice, the fields defined in this document are 4561 consistently implemented in a single, logical order, since "lost 4562 update" preconditions have more strict requirements than cache 4563 validation, a validated cache is more efficient than a partial 4564 response, and entity tags are presumed to be more accurate than date 4565 validators. 4567 A recipient cache or origin server MUST evaluate the request 4568 preconditions defined by this specification in the following order: 4570 1. When recipient is the origin server and If-Match is present, 4571 evaluate the If-Match precondition: 4573 o if true, continue to step 3 4575 o if false, respond 412 (Precondition Failed) unless it can be 4576 determined that the state-changing request has already 4577 succeeded (see Section 9.2.3) 4579 2. When recipient is the origin server, If-Match is not present, and 4580 If-Unmodified-Since is present, evaluate the If-Unmodified-Since 4581 precondition: 4583 o if true, continue to step 3 4585 o if false, respond 412 (Precondition Failed) unless it can be 4586 determined that the state-changing request has already 4587 succeeded (see Section 9.2.6) 4589 3. When If-None-Match is present, evaluate the If-None-Match 4590 precondition: 4592 o if true, continue to step 5 4594 o if false for GET/HEAD, respond 304 (Not Modified) 4596 o if false for other methods, respond 412 (Precondition Failed) 4598 4. When the method is GET or HEAD, If-None-Match is not present, and 4599 If-Modified-Since is present, evaluate the If-Modified-Since 4600 precondition: 4602 o if true, continue to step 5 4604 o if false, respond 304 (Not Modified) 4606 5. When the method is GET and both Range and If-Range are present, 4607 evaluate the If-Range precondition: 4609 o if the validator matches and the Range specification is 4610 applicable to the selected representation, respond 206 4611 (Partial Content) 4613 6. Otherwise, 4615 o all conditions are met, so perform the requested action and 4616 respond according to its success or failure. 4618 Any extension to HTTP that defines additional conditional request 4619 header fields ought to define its own expectations regarding the 4620 order for evaluating such fields in relation to those defined in this 4621 document and other conditionals that might be found in practice. 4623 9.2.3. If-Match 4625 The "If-Match" header field makes the request method conditional on 4626 the recipient origin server either having at least one current 4627 representation of the target resource, when the field value is "*", 4628 or having a current representation of the target resource that has an 4629 entity-tag matching a member of the list of entity-tags provided in 4630 the field value. 4632 An origin server MUST use the strong comparison function when 4633 comparing entity-tags for If-Match (Section 11.2.3.2), since the 4634 client intends this precondition to prevent the method from being 4635 applied if there have been any changes to the representation data. 4637 If-Match = "*" / 1#entity-tag 4639 Examples: 4641 If-Match: "xyzzy" 4642 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 4643 If-Match: * 4645 If-Match is most often used with state-changing methods (e.g., POST, 4646 PUT, DELETE) to prevent accidental overwrites when multiple user 4647 agents might be acting in parallel on the same resource (i.e., to 4648 prevent the "lost update" problem). It can also be used with safe 4649 methods to abort a request if the selected representation does not 4650 match one already stored (or partially stored) from a prior request. 4652 An origin server that receives an If-Match header field MUST evaluate 4653 the condition as per Section 9.2.1 prior to performing the method. 4655 To evaluate a received If-Match header field: 4657 1. If the field value is "*", the condition is true if the origin 4658 server has a current representation for the target resource. 4660 2. If the field value is a list of entity-tags, the condition is 4661 true if any of the listed tags match the entity-tag of the 4662 selected representation. 4664 3. Otherwise, the condition is false. 4666 An origin server MUST NOT perform the requested method if a received 4667 If-Match condition evaluates to false; instead, the origin server 4668 MUST respond with either a) the 412 (Precondition Failed) status code 4669 or b) one of the 2xx (Successful) status codes if the origin server 4670 has verified that a state change is being requested and the final 4671 state is already reflected in the current state of the target 4672 resource (i.e., the change requested by the user agent has already 4673 succeeded, but the user agent might not be aware of it, perhaps 4674 because the prior response was lost or a compatible change was made 4675 by some other user agent). In the latter case, the origin server 4676 MUST NOT send a validator header field in the response unless it can 4677 verify that the request is a duplicate of an immediately prior change 4678 made by the same user agent. 4680 The If-Match header field can be ignored by caches and intermediaries 4681 because it is not applicable to a stored response. 4683 Note that an If-Match header field with a list value containing "*" 4684 and other values (including other instances of "*") is unlikely to be 4685 interoperable. 4687 9.2.4. If-None-Match 4689 The "If-None-Match" header field makes the request method conditional 4690 on a recipient cache or origin server either not having any current 4691 representation of the target resource, when the field value is "*", 4692 or having a selected representation with an entity-tag that does not 4693 match any of those listed in the field value. 4695 A recipient MUST use the weak comparison function when comparing 4696 entity-tags for If-None-Match (Section 11.2.3.2), since weak entity- 4697 tags can be used for cache validation even if there have been changes 4698 to the representation data. 4700 If-None-Match = "*" / 1#entity-tag 4702 Examples: 4704 If-None-Match: "xyzzy" 4705 If-None-Match: W/"xyzzy" 4706 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 4707 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 4708 If-None-Match: * 4710 If-None-Match is primarily used in conditional GET requests to enable 4711 efficient updates of cached information with a minimum amount of 4712 transaction overhead. When a client desires to update one or more 4713 stored responses that have entity-tags, the client SHOULD generate an 4714 If-None-Match header field containing a list of those entity-tags 4715 when making a GET request; this allows recipient servers to send a 4716 304 (Not Modified) response to indicate when one of those stored 4717 responses matches the selected representation. 4719 If-None-Match can also be used with a value of "*" to prevent an 4720 unsafe request method (e.g., PUT) from inadvertently modifying an 4721 existing representation of the target resource when the client 4722 believes that the resource does not have a current representation 4723 (Section 8.2.1). This is a variation on the "lost update" problem 4724 that might arise if more than one client attempts to create an 4725 initial representation for the target resource. 4727 An origin server that receives an If-None-Match header field MUST 4728 evaluate the condition as per Section 9.2.1 prior to performing the 4729 method. 4731 To evaluate a received If-None-Match header field: 4733 1. If the field value is "*", the condition is false if the origin 4734 server has a current representation for the target resource. 4736 2. If the field value is a list of entity-tags, the condition is 4737 false if one of the listed tags matches the entity-tag of the 4738 selected representation. 4740 3. Otherwise, the condition is true. 4742 An origin server MUST NOT perform the requested method if the 4743 condition evaluates to false; instead, the origin server MUST respond 4744 with either a) the 304 (Not Modified) status code if the request 4745 method is GET or HEAD or b) the 412 (Precondition Failed) status code 4746 for all other request methods. 4748 Requirements on cache handling of a received If-None-Match header 4749 field are defined in Section 4.3.2 of [Caching]. 4751 Note that an If-None-Match header field with a list value containing 4752 "*" and other values (including other instances of "*") is unlikely 4753 to be interoperable. 4755 9.2.5. If-Modified-Since 4757 The "If-Modified-Since" header field makes a GET or HEAD request 4758 method conditional on the selected representation's modification date 4759 being more recent than the date provided in the field value. 4760 Transfer of the selected representation's data is avoided if that 4761 data has not changed. 4763 If-Modified-Since = HTTP-date 4765 An example of the field is: 4767 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 4769 A recipient MUST ignore If-Modified-Since if the request contains an 4770 If-None-Match header field; the condition in If-None-Match is 4771 considered to be a more accurate replacement for the condition in If- 4772 Modified-Since, and the two are only combined for the sake of 4773 interoperating with older intermediaries that might not implement 4774 If-None-Match. 4776 A recipient MUST ignore the If-Modified-Since header field if the 4777 received field value is not a valid HTTP-date, or if the request 4778 method is neither GET nor HEAD. 4780 A recipient MUST interpret an If-Modified-Since field value's 4781 timestamp in terms of the origin server's clock. 4783 If-Modified-Since is typically used for two distinct purposes: 1) to 4784 allow efficient updates of a cached representation that does not have 4785 an entity-tag and 2) to limit the scope of a web traversal to 4786 resources that have recently changed. 4788 When used for cache updates, a cache will typically use the value of 4789 the cached message's Last-Modified field to generate the field value 4790 of If-Modified-Since. This behavior is most interoperable for cases 4791 where clocks are poorly synchronized or when the server has chosen to 4792 only honor exact timestamp matches (due to a problem with Last- 4793 Modified dates that appear to go "back in time" when the origin 4794 server's clock is corrected or a representation is restored from an 4795 archived backup). However, caches occasionally generate the field 4796 value based on other data, such as the Date header field of the 4797 cached message or the local clock time that the message was received, 4798 particularly when the cached message does not contain a Last-Modified 4799 field. 4801 When used for limiting the scope of retrieval to a recent time 4802 window, a user agent will generate an If-Modified-Since field value 4803 based on either its own local clock or a Date header field received 4804 from the server in a prior response. Origin servers that choose an 4805 exact timestamp match based on the selected representation's 4806 Last-Modified field will not be able to help the user agent limit its 4807 data transfers to only those changed during the specified window. 4809 An origin server that receives an If-Modified-Since header field 4810 SHOULD evaluate the condition as per Section 9.2.1 prior to 4811 performing the method. The origin server SHOULD NOT perform the 4812 requested method if the selected representation's last modification 4813 date is earlier than or equal to the date provided in the field 4814 value; instead, the origin server SHOULD generate a 304 (Not 4815 Modified) response, including only those metadata that are useful for 4816 identifying or updating a previously cached response. 4818 Requirements on cache handling of a received If-Modified-Since header 4819 field are defined in Section 4.3.2 of [Caching]. 4821 9.2.6. If-Unmodified-Since 4823 The "If-Unmodified-Since" header field makes the request method 4824 conditional on the selected representation's last modification date 4825 being earlier than or equal to the date provided in the field value. 4826 This field accomplishes the same purpose as If-Match for cases where 4827 the user agent does not have an entity-tag for the representation. 4829 If-Unmodified-Since = HTTP-date 4831 An example of the field is: 4833 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 4835 A recipient MUST ignore If-Unmodified-Since if the request contains 4836 an If-Match header field; the condition in If-Match is considered to 4837 be a more accurate replacement for the condition in If-Unmodified- 4838 Since, and the two are only combined for the sake of interoperating 4839 with older intermediaries that might not implement If-Match. 4841 A recipient MUST ignore the If-Unmodified-Since header field if the 4842 received field value is not a valid HTTP-date. 4844 A recipient MUST interpret an If-Unmodified-Since field value's 4845 timestamp in terms of the origin server's clock. 4847 If-Unmodified-Since is most often used with state-changing methods 4848 (e.g., POST, PUT, DELETE) to prevent accidental overwrites when 4849 multiple user agents might be acting in parallel on a resource that 4850 does not supply entity-tags with its representations (i.e., to 4851 prevent the "lost update" problem). It can also be used with safe 4852 methods to abort a request if the selected representation does not 4853 match one already stored (or partially stored) from a prior request. 4855 An origin server that receives an If-Unmodified-Since header field 4856 MUST evaluate the condition as per Section 9.2.1 prior to performing 4857 the method. 4859 If the selected representation has a last modification date, the 4860 origin server MUST NOT perform the requested method if that date is 4861 more recent than the date provided in the field value. Instead, the 4862 origin server MUST respond with either a) the 412 (Precondition 4863 Failed) status code or b) one of the 2xx (Successful) status codes if 4864 the origin server has verified that a state change is being requested 4865 and the final state is already reflected in the current state of the 4866 target resource (i.e., the change requested by the user agent has 4867 already succeeded, but the user agent might not be aware of that 4868 because the prior response message was lost or a compatible change 4869 was made by some other user agent). In the latter case, the origin 4870 server MUST NOT send a validator header field in the response unless 4871 it can verify that the request is a duplicate of an immediately prior 4872 change made by the same user agent. 4874 The If-Unmodified-Since header field can be ignored by caches and 4875 intermediaries because it is not applicable to a stored response. 4877 9.2.7. If-Range 4879 The "If-Range" header field provides a special conditional request 4880 mechanism that is similar to the If-Match and If-Unmodified-Since 4881 header fields but that instructs the recipient to ignore the Range 4882 header field if the validator doesn't match, resulting in transfer of 4883 the new selected representation instead of a 412 (Precondition 4884 Failed) response. 4886 If a client has a partial copy of a representation and wishes to have 4887 an up-to-date copy of the entire representation, it could use the 4888 Range header field with a conditional GET (using either or both of 4889 If-Unmodified-Since and If-Match.) However, if the precondition 4890 fails because the representation has been modified, the client would 4891 then have to make a second request to obtain the entire current 4892 representation. 4894 The "If-Range" header field allows a client to "short-circuit" the 4895 second request. Informally, its meaning is as follows: if the 4896 representation is unchanged, send me the part(s) that I am requesting 4897 in Range; otherwise, send me the entire representation. 4899 If-Range = entity-tag / HTTP-date 4901 A client MUST NOT generate an If-Range header field in a request that 4902 does not contain a Range header field. A server MUST ignore an If- 4903 Range header field received in a request that does not contain a 4904 Range header field. An origin server MUST ignore an If-Range header 4905 field received in a request for a target resource that does not 4906 support Range requests. 4908 A client MUST NOT generate an If-Range header field containing an 4909 entity-tag that is marked as weak. A client MUST NOT generate an If- 4910 Range header field containing an HTTP-date unless the client has no 4911 entity-tag for the corresponding representation and the date is a 4912 strong validator in the sense defined by Section 11.2.2.2. 4914 A server that evaluates an If-Range precondition MUST use the strong 4915 comparison function when comparing entity-tags (Section 11.2.3.2) and 4916 MUST evaluate the condition as false if an HTTP-date validator is 4917 provided that is not a strong validator in the sense defined by 4918 Section 11.2.2.2. A valid entity-tag can be distinguished from a 4919 valid HTTP-date by examining the first two characters for a DQUOTE. 4921 If the validator given in the If-Range header field matches the 4922 current validator for the selected representation of the target 4923 resource, then the server SHOULD process the Range header field as 4924 requested. If the validator does not match, the server MUST ignore 4925 the Range header field. Note that this comparison by exact match, 4926 including when the validator is an HTTP-date, differs from the 4927 "earlier than or equal to" comparison used when evaluating an 4928 If-Unmodified-Since conditional. 4930 9.3. Range 4932 The "Range" header field on a GET request modifies the method 4933 semantics to request transfer of only one or more subranges of the 4934 selected representation data (Section 7.1), rather than the entire 4935 selected representation. 4937 Range = ranges-specifier 4939 Clients often encounter interrupted data transfers as a result of 4940 canceled requests or dropped connections. When a client has stored a 4941 partial representation, it is desirable to request the remainder of 4942 that representation in a subsequent request rather than transfer the 4943 entire representation. Likewise, devices with limited local storage 4944 might benefit from being able to request only a subset of a larger 4945 representation, such as a single page of a very large document, or 4946 the dimensions of an embedded image. 4948 Range requests are an OPTIONAL feature of HTTP, designed so that 4949 recipients not implementing this feature (or not supporting it for 4950 the target resource) can respond as if it is a normal GET request 4951 without impacting interoperability. Partial responses are indicated 4952 by a distinct status code to not be mistaken for full responses by 4953 caches that might not implement the feature. 4955 A server MAY ignore the Range header field. However, origin servers 4956 and intermediate caches ought to support byte ranges when possible, 4957 since they support efficient recovery from partially failed transfers 4958 and partial retrieval of large representations. A server MUST ignore 4959 a Range header field received with a request method other than GET. 4961 Although the range request mechanism is designed to allow for 4962 extensible range types, this specification only defines requests for 4963 byte ranges. 4965 An origin server MUST ignore a Range header field that contains a 4966 range unit it does not understand. A proxy MAY discard a Range 4967 header field that contains a range unit it does not understand. 4969 A server that supports range requests MAY ignore or reject a Range 4970 header field that consists of more than two overlapping ranges, or a 4971 set of many small ranges that are not listed in ascending order, 4972 since both are indications of either a broken client or a deliberate 4973 denial-of-service attack (Section 12.13). A client SHOULD NOT 4974 request multiple ranges that are inherently less efficient to process 4975 and transfer than a single range that encompasses the same data. 4977 A server that supports range requests MAY ignore a Range header field 4978 when the selected representation has no body (i.e., the selected 4979 representation data is of zero length). 4981 A client that is requesting multiple ranges SHOULD list those ranges 4982 in ascending order (the order in which they would typically be 4983 received in a complete representation) unless there is a specific 4984 need to request a later part earlier. For example, a user agent 4985 processing a large representation with an internal catalog of parts 4986 might need to request later parts first, particularly if the 4987 representation consists of pages stored in reverse order and the user 4988 agent wishes to transfer one page at a time. 4990 The Range header field is evaluated after evaluating the precondition 4991 header fields defined in Section 9.2, and only if the result in 4992 absence of the Range header field would be a 200 (OK) response. In 4993 other words, Range is ignored when a conditional GET would result in 4994 a 304 (Not Modified) response. 4996 The If-Range header field (Section 9.2.7) can be used as a 4997 precondition to applying the Range header field. 4999 If all of the preconditions are true, the server supports the Range 5000 header field for the target resource, and the specified range(s) are 5001 valid and satisfiable (as defined in Section 7.1.4.2), the server 5002 SHOULD send a 206 (Partial Content) response with a payload 5003 containing one or more partial representations that correspond to the 5004 satisfiable ranges requested. 5006 If all of the preconditions are true, the server supports the Range 5007 header field for the target resource, and the specified range(s) are 5008 invalid or unsatisfiable, the server SHOULD send a 416 (Range Not 5009 Satisfiable) response. 5011 9.4. Negotiation 5013 The following request header fields can be sent by a user agent to 5014 engage in proactive negotiation of the response content, as defined 5015 in Section 7.4.1. The preferences sent in these fields apply to any 5016 content in the response, including representations of the target 5017 resource, representations of error or processing status, and 5018 potentially even the miscellaneous text strings that might appear 5019 within the protocol. 5021 +-----------------+---------------+ 5022 | Field Name | Defined in... | 5023 | Accept | Section 9.4.1 | 5024 | Accept-Charset | Section 9.4.2 | 5025 | Accept-Encoding | Section 9.4.3 | 5026 | Accept-Language | Section 9.4.4 | 5027 +-----------------+---------------+ 5029 Table 12 5031 For each of these header fields, a request that does not contain it 5032 implies that the user agent has no preference on that axis of 5033 negotiation. If the header field is present in a request and none of 5034 the available representations for the response can be considered 5035 acceptable according to it, the origin server can either honor the 5036 header field by sending a 406 (Not Acceptable) response or disregard 5037 the header field by treating the response as if it is not subject to 5038 content negotiation for that request header field. This does not 5039 imply, however, that the client will be able to use the 5040 representation. 5042 *Note:* Sending these header fields makes it easier for a server to 5043 identify an individual by virtue of the user agent's request 5044 characteristics (Section 12.11). 5046 Each of these header fields defines a wildcard value (often, "*") to 5047 select unspecified values. If no wildcard is present, all values not 5048 explicitly mentioned in the field are considered "not acceptable" to 5049 the client. 5051 *Note:* In practice, using wildcards in content negotiation has 5052 limited practical value, because it is seldom useful to say, for 5053 example, "I prefer image/* more or less than (some other specific 5054 value)". Clients can explicitly request a 406 (Not Acceptable) 5055 response if a more preferred format is not available by sending 5056 Accept: */*;q=0, but they still need to be able to handle a different 5057 response, since the server is allowed to ignore their preference. 5059 9.4.1. Accept 5061 The "Accept" header field can be used by user agents to specify their 5062 preferences regarding response media types. For example, Accept 5063 header fields can be used to indicate that the request is 5064 specifically limited to a small set of desired types, as in the case 5065 of a request for an in-line image. 5067 When sent by a server in a response, Accept provides information 5068 about what content types are preferred in the payload of a subsequent 5069 request to the same resource. 5071 Accept = #( media-range [ accept-params ] ) 5073 media-range = ( "*/*" 5074 / ( type "/" "*" ) 5075 / ( type "/" subtype ) 5076 ) *( OWS ";" OWS parameter ) 5077 accept-params = weight *( accept-ext ) 5078 accept-ext = OWS ";" OWS token [ "=" ( token / quoted-string ) ] 5080 The asterisk "*" character is used to group media types into ranges, 5081 with "*/*" indicating all media types and "type/*" indicating all 5082 subtypes of that type. The media-range can include media type 5083 parameters that are applicable to that range. 5085 Each media-range might be followed by zero or more applicable media 5086 type parameters (e.g., charset), an optional "q" parameter for 5087 indicating a relative weight (Section 7.4.4), and then zero or more 5088 extension parameters. The "q" parameter is necessary if any 5089 extensions (accept-ext) are present, since it acts as a separator 5090 between the two parameter sets. 5092 | *Note:* Use of the "q" parameter name to separate media type 5093 | parameters from Accept extension parameters is due to 5094 | historical practice. Although this prevents any media type 5095 | parameter named "q" from being used with a media range, such an 5096 | event is believed to be unlikely given the lack of any "q" 5097 | parameters in the IANA media type registry and the rare usage 5098 | of any media type parameters in Accept. Future media types are 5099 | discouraged from registering any parameter named "q". 5101 The example 5103 Accept: audio/*; q=0.2, audio/basic 5105 is interpreted as "I prefer audio/basic, but send me any audio type 5106 if it is the best available after an 80% markdown in quality". 5108 A more elaborate example is 5110 Accept: text/plain; q=0.5, text/html, 5111 text/x-dvi; q=0.8, text/x-c 5113 Verbally, this would be interpreted as "text/html and text/x-c are 5114 the equally preferred media types, but if they do not exist, then 5115 send the text/x-dvi representation, and if that does not exist, send 5116 the text/plain representation". 5118 Media ranges can be overridden by more specific media ranges or 5119 specific media types. If more than one media range applies to a 5120 given type, the most specific reference has precedence. For example, 5122 Accept: text/*, text/plain, text/plain;format=flowed, */* 5124 have the following precedence: 5126 1. text/plain;format=flowed 5128 2. text/plain 5130 3. text/* 5132 4. */* 5133 The media type quality factor associated with a given type is 5134 determined by finding the media range with the highest precedence 5135 that matches the type. For example, 5137 Accept: text/*;q=0.3, text/plain;q=0.7, text/plain;format=flowed, 5138 text/plain;format=fixed;q=0.4, */*;q=0.5 5140 would cause the following values to be associated: 5142 +--------------------------+---------------+ 5143 | Media Type | Quality Value | 5144 | text/plain;format=flowed | 1 | 5145 | text/plain | 0.7 | 5146 | text/html | 0.3 | 5147 | image/jpeg | 0.5 | 5148 | text/plain;format=fixed | 0.4 | 5149 | text/html;level=3 | 0.7 | 5150 +--------------------------+---------------+ 5152 Table 13 5154 *Note:* A user agent might be provided with a default set of quality 5155 values for certain media ranges. However, unless the user agent is a 5156 closed system that cannot interact with other rendering agents, this 5157 default set ought to be configurable by the user. 5159 9.4.2. Accept-Charset 5161 The "Accept-Charset" header field can be sent by a user agent to 5162 indicate its preferences for charsets in textual response content. 5163 For example, this field allows user agents capable of understanding 5164 more comprehensive or special-purpose charsets to signal that 5165 capability to an origin server that is capable of representing 5166 information in those charsets. 5168 Accept-Charset = 1#( ( charset / "*" ) [ weight ] ) 5170 Charset names are defined in Section 7.1.1.1. A user agent MAY 5171 associate a quality value with each charset to indicate the user's 5172 relative preference for that charset, as defined in Section 7.4.4. 5173 An example is 5175 Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 5177 The special value "*", if present in the Accept-Charset field, 5178 matches every charset that is not mentioned elsewhere in the Accept- 5179 Charset field. 5181 *Note:* Accept-Charset is deprecated because UTF-8 has become nearly 5182 ubiquitous and sending a detailed list of user-preferred charsets 5183 wastes bandwidth, increases latency, and makes passive fingerprinting 5184 far too easy (Section 12.11). Most general-purpose user agents do 5185 not send Accept-Charset, unless specifically configured to do so. 5187 9.4.3. Accept-Encoding 5189 The "Accept-Encoding" header field can be used to indicate 5190 preferences regarding the use of content codings (Section 7.1.2). 5192 When sent by a user agent in a request, Accept-Encoding indicates the 5193 content codings acceptable in a response. 5195 When sent by a server in a response, Accept-Encoding provides 5196 information about what content codings are preferred in the payload 5197 of a subsequent request to the same resource. 5199 An "identity" token is used as a synonym for "no encoding" in order 5200 to communicate when no encoding is preferred. 5202 Accept-Encoding = #( codings [ weight ] ) 5203 codings = content-coding / "identity" / "*" 5205 Each codings value MAY be given an associated quality value 5206 representing the preference for that encoding, as defined in 5207 Section 7.4.4. The asterisk "*" symbol in an Accept-Encoding field 5208 matches any available content-coding not explicitly listed in the 5209 header field. 5211 For example, 5213 Accept-Encoding: compress, gzip 5214 Accept-Encoding: 5215 Accept-Encoding: * 5216 Accept-Encoding: compress;q=0.5, gzip;q=1.0 5217 Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 5219 A server tests whether a content-coding for a given representation is 5220 acceptable using these rules: 5222 1. If no Accept-Encoding field is in the request, any content-coding 5223 is considered acceptable by the user agent. 5225 2. If the representation has no content-coding, then it is 5226 acceptable by default unless specifically excluded by the Accept- 5227 Encoding field stating either "identity;q=0" or "*;q=0" without a 5228 more specific entry for "identity". 5230 3. If the representation's content-coding is one of the content- 5231 codings listed in the Accept-Encoding field value, then it is 5232 acceptable unless it is accompanied by a qvalue of 0. (As 5233 defined in Section 7.4.4, a qvalue of 0 means "not acceptable".) 5235 4. If multiple content-codings are acceptable, then the acceptable 5236 content-coding with the highest non-zero qvalue is preferred. 5238 An Accept-Encoding header field with a field value that is empty 5239 implies that the user agent does not want any content-coding in 5240 response. If an Accept-Encoding header field is present in a request 5241 and none of the available representations for the response have a 5242 content-coding that is listed as acceptable, the origin server SHOULD 5243 send a response without any content-coding. 5245 When the Accept-Encoding header field is present in a response, it 5246 indicates what content codings the resource was willing to accept in 5247 the associated request. The field value is evaluated the same way as 5248 in a request. 5250 Note that this information is specific to the associated request; the 5251 set of supported encodings might be different for other resources on 5252 the same server and could change over time or depend on other aspects 5253 of the request (such as the request method). 5255 Servers that fail a request due to an unsupported content coding 5256 ought to respond with a 415 (Unsupported Media Type) status and 5257 include an Accept-Encoding header field in that response, allowing 5258 clients to distinguish between issues related to content codings and 5259 media types. In order to avoid confusion with issues related to 5260 media types, servers that fail a request with a 415 status for 5261 reasons unrelated to content codings MUST NOT include the Accept- 5262 Encoding header field. 5264 The most common use of Accept-Encoding is in responses with a 415 5265 (Unsupported Media Type) status code, in response to optimistic use 5266 of a content coding by clients. However, the header field can also 5267 be used to indicate to clients that content codings are supported, to 5268 optimize future interactions. For example, a resource might include 5269 it in a 2xx (Successful) response when the request payload was big 5270 enough to justify use of a compression coding but the client failed 5271 do so. 5273 | *Note:* Most HTTP/1.0 applications do not recognize or obey 5274 | qvalues associated with content-codings. This means that 5275 | qvalues might not work and are not permitted with x-gzip or 5276 | x-compress. 5278 9.4.4. Accept-Language 5280 The "Accept-Language" header field can be used by user agents to 5281 indicate the set of natural languages that are preferred in the 5282 response. Language tags are defined in Section 7.1.3. 5284 Accept-Language = 1#( language-range [ weight ] ) 5285 language-range = 5286 5288 Each language-range can be given an associated quality value 5289 representing an estimate of the user's preference for the languages 5290 specified by that range, as defined in Section 7.4.4. For example, 5292 Accept-Language: da, en-gb;q=0.8, en;q=0.7 5294 would mean: "I prefer Danish, but will accept British English and 5295 other types of English". 5297 Note that some recipients treat the order in which language tags are 5298 listed as an indication of descending priority, particularly for tags 5299 that are assigned equal quality values (no value is the same as q=1). 5300 However, this behavior cannot be relied upon. For consistency and to 5301 maximize interoperability, many user agents assign each language tag 5302 a unique quality value while also listing them in order of decreasing 5303 quality. Additional discussion of language priority lists can be 5304 found in Section 2.3 of [RFC4647]. 5306 For matching, Section 3 of [RFC4647] defines several matching 5307 schemes. Implementations can offer the most appropriate matching 5308 scheme for their requirements. The "Basic Filtering" scheme 5309 ([RFC4647], Section 3.3.1) is identical to the matching scheme that 5310 was previously defined for HTTP in Section 14.4 of [RFC2616]. 5312 It might be contrary to the privacy expectations of the user to send 5313 an Accept-Language header field with the complete linguistic 5314 preferences of the user in every request (Section 12.11). 5316 Since intelligibility is highly dependent on the individual user, 5317 user agents need to allow user control over the linguistic preference 5318 (either through configuration of the user agent itself or by 5319 defaulting to a user controllable system setting). A user agent that 5320 does not provide such control to the user MUST NOT send an Accept- 5321 Language header field. 5323 | *Note:* User agents ought to provide guidance to users when 5324 | setting a preference, since users are rarely familiar with the 5325 | details of language matching as described above. For example, 5326 | users might assume that on selecting "en-gb", they will be 5327 | served any kind of English document if British English is not 5328 | available. A user agent might suggest, in such a case, to add 5329 | "en" to the list for better matching behavior. 5331 9.5. Authentication Credentials 5333 HTTP provides a general framework for access control and 5334 authentication, via an extensible set of challenge-response 5335 authentication schemes, which can be used by a server to challenge a 5336 client request and by a client to provide authentication information. 5338 Two header fields are used for carrying authentication credentials. 5339 Note that various custom mechanisms for user authentication use the 5340 Cookie header field for this purpose, as defined in [RFC6265]. 5342 +---------------------+---------------+ 5343 | Field Name | Defined in... | 5344 | Authorization | Section 9.5.3 | 5345 | Proxy-Authorization | Section 9.5.4 | 5346 +---------------------+---------------+ 5348 Table 14 5350 9.5.1. Challenge and Response 5352 HTTP provides a simple challenge-response authentication framework 5353 that can be used by a server to challenge a client request and by a 5354 client to provide authentication information. It uses a case- 5355 insensitive token as a means to identify the authentication scheme, 5356 followed by additional information necessary for achieving 5357 authentication via that scheme. The latter can be either a comma- 5358 separated list of parameters or a single sequence of characters 5359 capable of holding base64-encoded information. 5361 Authentication parameters are name=value pairs, where the name token 5362 is matched case-insensitively, and each parameter name MUST only 5363 occur once per challenge. 5365 auth-scheme = token 5367 auth-param = token BWS "=" BWS ( token / quoted-string ) 5369 token68 = 1*( ALPHA / DIGIT / 5370 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 5372 The token68 syntax allows the 66 unreserved URI characters 5373 ([RFC3986]), plus a few others, so that it can hold a base64, 5374 base64url (URL and filename safe alphabet), base32, or base16 (hex) 5375 encoding, with or without padding, but excluding whitespace 5376 ([RFC4648]). 5378 A 401 (Unauthorized) response message is used by an origin server to 5379 challenge the authorization of a user agent, including a 5380 WWW-Authenticate header field containing at least one challenge 5381 applicable to the requested resource. 5383 A 407 (Proxy Authentication Required) response message is used by a 5384 proxy to challenge the authorization of a client, including a 5385 Proxy-Authenticate header field containing at least one challenge 5386 applicable to the proxy for the requested resource. 5388 challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 5390 | *Note:* Many clients fail to parse a challenge that contains an 5391 | unknown scheme. A workaround for this problem is to list well- 5392 | supported schemes (such as "basic") first. 5394 A user agent that wishes to authenticate itself with an origin server 5395 - usually, but not necessarily, after receiving a 401 (Unauthorized) 5396 - can do so by including an Authorization header field with the 5397 request. 5399 A client that wishes to authenticate itself with a proxy - usually, 5400 but not necessarily, after receiving a 407 (Proxy Authentication 5401 Required) - can do so by including a Proxy-Authorization header field 5402 with the request. 5404 Both the Authorization field value and the Proxy-Authorization field 5405 value contain the client's credentials for the realm of the resource 5406 being requested, based upon a challenge received in a response 5407 (possibly at some point in the past). When creating their values, 5408 the user agent ought to do so by selecting the challenge with what it 5409 considers to be the most secure auth-scheme that it understands, 5410 obtaining credentials from the user as appropriate. Transmission of 5411 credentials within header field values implies significant security 5412 considerations regarding the confidentiality of the underlying 5413 connection, as described in Section 12.14.1. 5415 credentials = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 5417 Upon receipt of a request for a protected resource that omits 5418 credentials, contains invalid credentials (e.g., a bad password) or 5419 partial credentials (e.g., when the authentication scheme requires 5420 more than one round trip), an origin server SHOULD send a 401 5421 (Unauthorized) response that contains a WWW-Authenticate header field 5422 with at least one (possibly new) challenge applicable to the 5423 requested resource. 5425 Likewise, upon receipt of a request that omits proxy credentials or 5426 contains invalid or partial proxy credentials, a proxy that requires 5427 authentication SHOULD generate a 407 (Proxy Authentication Required) 5428 response that contains a Proxy-Authenticate header field with at 5429 least one (possibly new) challenge applicable to the proxy. 5431 A server that receives valid credentials that are not adequate to 5432 gain access ought to respond with the 403 (Forbidden) status code 5433 (Section 10.5.4). 5435 HTTP does not restrict applications to this simple challenge-response 5436 framework for access authentication. Additional mechanisms can be 5437 used, such as authentication at the transport level or via message 5438 encapsulation, and with additional header fields specifying 5439 authentication information. However, such additional mechanisms are 5440 not defined by this specification. 5442 9.5.2. Protection Space (Realm) 5444 The "realm" authentication parameter is reserved for use by 5445 authentication schemes that wish to indicate a scope of protection. 5447 A protection space is defined by the canonical root URI (the scheme 5448 and authority components of the target URI; see Section 6.1) of the 5449 server being accessed, in combination with the realm value if 5450 present. These realms allow the protected resources on a server to 5451 be partitioned into a set of protection spaces, each with its own 5452 authentication scheme and/or authorization database. The realm value 5453 is a string, generally assigned by the origin server, that can have 5454 additional semantics specific to the authentication scheme. Note 5455 that a response can have multiple challenges with the same auth- 5456 scheme but with different realms. 5458 The protection space determines the domain over which credentials can 5459 be automatically applied. If a prior request has been authorized, 5460 the user agent MAY reuse the same credentials for all other requests 5461 within that protection space for a period of time determined by the 5462 authentication scheme, parameters, and/or user preferences (such as a 5463 configurable inactivity timeout). Unless specifically allowed by the 5464 authentication scheme, a single protection space cannot extend 5465 outside the scope of its server. 5467 For historical reasons, a sender MUST only generate the quoted-string 5468 syntax. Recipients might have to support both token and quoted- 5469 string syntax for maximum interoperability with existing clients that 5470 have been accepting both notations for a long time. 5472 9.5.3. Authorization 5474 The "Authorization" header field allows a user agent to authenticate 5475 itself with an origin server - usually, but not necessarily, after 5476 receiving a 401 (Unauthorized) response. Its value consists of 5477 credentials containing the authentication information of the user 5478 agent for the realm of the resource being requested. 5480 Authorization = credentials 5482 If a request is authenticated and a realm specified, the same 5483 credentials are presumed to be valid for all other requests within 5484 this realm (assuming that the authentication scheme itself does not 5485 require otherwise, such as credentials that vary according to a 5486 challenge value or using synchronized clocks). 5488 A proxy forwarding a request MUST NOT modify any Authorization fields 5489 in that request. See Section 3.3 of [Caching] for details of and 5490 requirements pertaining to handling of the Authorization field by 5491 HTTP caches. 5493 9.5.4. Proxy-Authorization 5495 The "Proxy-Authorization" header field allows the client to identify 5496 itself (or its user) to a proxy that requires authentication. Its 5497 value consists of credentials containing the authentication 5498 information of the client for the proxy and/or realm of the resource 5499 being requested. 5501 Proxy-Authorization = credentials 5503 Unlike Authorization, the Proxy-Authorization header field applies 5504 only to the next inbound proxy that demanded authentication using the 5505 Proxy-Authenticate field. When multiple proxies are used in a chain, 5506 the Proxy-Authorization header field is consumed by the first inbound 5507 proxy that was expecting to receive credentials. A proxy MAY relay 5508 the credentials from the client request to the next proxy if that is 5509 the mechanism by which the proxies cooperatively authenticate a given 5510 request. 5512 9.5.5. Authentication Scheme Extensibility 5514 Aside from the general framework, this document does not specify any 5515 authentication schemes. New and existing authentication schemes are 5516 specified independently and ought to be registered within the 5517 "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry". 5518 For example, the "basic" and "digest" authentication schemes are 5519 defined by RFC 7617 and RFC 7616, respectively. 5521 9.5.5.1. Authentication Scheme Registry 5523 The "Hypertext Transfer Protocol (HTTP) Authentication Scheme 5524 Registry" defines the namespace for the authentication schemes in 5525 challenges and credentials. It is maintained at 5526 . 5528 Registrations MUST include the following fields: 5530 o Authentication Scheme Name 5532 o Pointer to specification text 5534 o Notes (optional) 5536 Values to be added to this namespace require IETF Review (see 5537 [RFC8126], Section 4.8). 5539 9.5.5.2. Considerations for New Authentication Schemes 5541 There are certain aspects of the HTTP Authentication framework that 5542 put constraints on how new authentication schemes can work: 5544 o HTTP authentication is presumed to be stateless: all of the 5545 information necessary to authenticate a request MUST be provided 5546 in the request, rather than be dependent on the server remembering 5547 prior requests. Authentication based on, or bound to, the 5548 underlying connection is outside the scope of this specification 5549 and inherently flawed unless steps are taken to ensure that the 5550 connection cannot be used by any party other than the 5551 authenticated user (see Section 2.2). 5553 o The authentication parameter "realm" is reserved for defining 5554 protection spaces as described in Section 9.5.2. New schemes MUST 5555 NOT use it in a way incompatible with that definition. 5557 o The "token68" notation was introduced for compatibility with 5558 existing authentication schemes and can only be used once per 5559 challenge or credential. Thus, new schemes ought to use the auth- 5560 param syntax instead, because otherwise future extensions will be 5561 impossible. 5563 o The parsing of challenges and credentials is defined by this 5564 specification and cannot be modified by new authentication 5565 schemes. When the auth-param syntax is used, all parameters ought 5566 to support both token and quoted-string syntax, and syntactical 5567 constraints ought to be defined on the field value after parsing 5568 (i.e., quoted-string processing). This is necessary so that 5569 recipients can use a generic parser that applies to all 5570 authentication schemes. 5572 *Note:* The fact that the value syntax for the "realm" parameter 5573 is restricted to quoted-string was a bad design choice not to be 5574 repeated for new parameters. 5576 o Definitions of new schemes ought to define the treatment of 5577 unknown extension parameters. In general, a "must-ignore" rule is 5578 preferable to a "must-understand" rule, because otherwise it will 5579 be hard to introduce new parameters in the presence of legacy 5580 recipients. Furthermore, it's good to describe the policy for 5581 defining new parameters (such as "update the specification" or 5582 "use this registry"). 5584 o Authentication schemes need to document whether they are usable in 5585 origin-server authentication (i.e., using WWW-Authenticate), and/ 5586 or proxy authentication (i.e., using Proxy-Authenticate). 5588 o The credentials carried in an Authorization header field are 5589 specific to the user agent and, therefore, have the same effect on 5590 HTTP caches as the "private" Cache-Control response directive 5591 (Section 5.2.2.7 of [Caching]), within the scope of the request in 5592 which they appear. 5594 Therefore, new authentication schemes that choose not to carry 5595 credentials in the Authorization header field (e.g., using a newly 5596 defined header field) will need to explicitly disallow caching, by 5597 mandating the use of Cache-Control response directives (e.g., 5598 "private"). 5600 o Schemes using Authentication-Info, Proxy-Authentication-Info, or 5601 any other authentication related response header field need to 5602 consider and document the related security considerations (see 5603 Section 12.14.4). 5605 9.6. Request Context 5607 The following request header fields provide additional information 5608 about the request context, including information about the user, user 5609 agent, and resource behind the request. 5611 +------------+---------------+ 5612 | Field Name | Defined in... | 5613 | From | Section 9.6.1 | 5614 | Referer | Section 9.6.2 | 5615 | User-Agent | Section 9.6.3 | 5616 +------------+---------------+ 5618 Table 15 5620 9.6.1. From 5622 The "From" header field contains an Internet email address for a 5623 human user who controls the requesting user agent. The address ought 5624 to be machine-usable, as defined by "mailbox" in Section 3.4 of 5625 [RFC5322]: 5627 From = mailbox 5629 mailbox = 5631 An example is: 5633 From: webmaster@example.org 5635 The From header field is rarely sent by non-robotic user agents. A 5636 user agent SHOULD NOT send a From header field without explicit 5637 configuration by the user, since that might conflict with the user's 5638 privacy interests or their site's security policy. 5640 A robotic user agent SHOULD send a valid From header field so that 5641 the person responsible for running the robot can be contacted if 5642 problems occur on servers, such as if the robot is sending excessive, 5643 unwanted, or invalid requests. 5645 A server SHOULD NOT use the From header field for access control or 5646 authentication, since most recipients will assume that the field 5647 value is public information. 5649 9.6.2. Referer 5651 The "Referer" [sic] header field allows the user agent to specify a 5652 URI reference for the resource from which the target URI was obtained 5653 (i.e., the "referrer", though the field name is misspelled). A user 5654 agent MUST NOT include the fragment and userinfo components of the 5655 URI reference [RFC3986], if any, when generating the Referer field 5656 value. 5658 Referer = absolute-URI / partial-URI 5660 The field value is either an absolute-URI or a partial-URI. In the 5661 latter case (Section 2.4), the referenced URI is relative to the 5662 target URI ([RFC3986], Section 5). 5664 The Referer header field allows servers to generate back-links to 5665 other resources for simple analytics, logging, optimized caching, 5666 etc. It also allows obsolete or mistyped links to be found for 5667 maintenance. Some servers use the Referer header field as a means of 5668 denying links from other sites (so-called "deep linking") or 5669 restricting cross-site request forgery (CSRF), but not all requests 5670 contain it. 5672 Example: 5674 Referer: http://www.example.org/hypertext/Overview.html 5676 If the target URI was obtained from a source that does not have its 5677 own URI (e.g., input from the user keyboard, or an entry within the 5678 user's bookmarks/favorites), the user agent MUST either exclude the 5679 Referer field or send it with a value of "about:blank". 5681 The Referer field has the potential to reveal information about the 5682 request context or browsing history of the user, which is a privacy 5683 concern if the referring resource's identifier reveals personal 5684 information (such as an account name) or a resource that is supposed 5685 to be confidential (such as behind a firewall or internal to a 5686 secured service). Most general-purpose user agents do not send the 5687 Referer header field when the referring resource is a local "file" or 5688 "data" URI. A user agent MUST NOT send a Referer header field in an 5689 unsecured HTTP request if the referring page was received with a 5690 secure protocol. See Section 12.8 for additional security 5691 considerations. 5693 Some intermediaries have been known to indiscriminately remove 5694 Referer header fields from outgoing requests. This has the 5695 unfortunate side effect of interfering with protection against CSRF 5696 attacks, which can be far more harmful to their users. 5698 Intermediaries and user agent extensions that wish to limit 5699 information disclosure in Referer ought to restrict their changes to 5700 specific edits, such as replacing internal domain names with 5701 pseudonyms or truncating the query and/or path components. An 5702 intermediary SHOULD NOT modify or delete the Referer header field 5703 when the field value shares the same scheme and host as the target 5704 URI. 5706 9.6.3. User-Agent 5708 The "User-Agent" header field contains information about the user 5709 agent originating the request, which is often used by servers to help 5710 identify the scope of reported interoperability problems, to work 5711 around or tailor responses to avoid particular user agent 5712 limitations, and for analytics regarding browser or operating system 5713 use. A user agent SHOULD send a User-Agent field in each request 5714 unless specifically configured not to do so. 5716 User-Agent = product *( RWS ( product / comment ) ) 5718 The User-Agent field value consists of one or more product 5719 identifiers, each followed by zero or more comments 5720 (Section 5.4.1.3), which together identify the user agent software 5721 and its significant subproducts. By convention, the product 5722 identifiers are listed in decreasing order of their significance for 5723 identifying the user agent software. Each product identifier 5724 consists of a name and optional version. 5726 product = token ["/" product-version] 5727 product-version = token 5729 A sender SHOULD limit generated product identifiers to what is 5730 necessary to identify the product; a sender MUST NOT generate 5731 advertising or other nonessential information within the product 5732 identifier. A sender SHOULD NOT generate information in 5733 product-version that is not a version identifier (i.e., successive 5734 versions of the same product name ought to differ only in the 5735 product-version portion of the product identifier). 5737 Example: 5739 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 5741 A user agent SHOULD NOT generate a User-Agent field containing 5742 needlessly fine-grained detail and SHOULD limit the addition of 5743 subproducts by third parties. Overly long and detailed User-Agent 5744 field values increase request latency and the risk of a user being 5745 identified against their wishes ("fingerprinting"). 5747 Likewise, implementations are encouraged not to use the product 5748 tokens of other implementations in order to declare compatibility 5749 with them, as this circumvents the purpose of the field. If a user 5750 agent masquerades as a different user agent, recipients can assume 5751 that the user intentionally desires to see responses tailored for 5752 that identified user agent, even if they might not work as well for 5753 the actual user agent being used. 5755 10. Response Status Codes 5757 The (response) status code is a three-digit integer code giving the 5758 result of the attempt to understand and satisfy the request. 5760 HTTP status codes are extensible. HTTP clients are not required to 5761 understand the meaning of all registered status codes, though such 5762 understanding is obviously desirable. However, a client MUST 5763 understand the class of any status code, as indicated by the first 5764 digit, and treat an unrecognized status code as being equivalent to 5765 the x00 status code of that class. 5767 For example, if an unrecognized status code of 471 is received by a 5768 client, the client can assume that there was something wrong with its 5769 request and treat the response as if it had received a 400 (Bad 5770 Request) status code. The response message will usually contain a 5771 representation that explains the status. 5773 The first digit of the status code defines the class of response. 5774 The last two digits do not have any categorization role. There are 5775 five values for the first digit: 5777 o 1xx (Informational): The request was received, continuing process 5779 o 2xx (Successful): The request was successfully received, 5780 understood, and accepted 5782 o 3xx (Redirection): Further action needs to be taken in order to 5783 complete the request 5785 o 4xx (Client Error): The request contains bad syntax or cannot be 5786 fulfilled 5788 o 5xx (Server Error): The server failed to fulfill an apparently 5789 valid request 5791 A single request can have multiple associated responses: zero or more 5792 interim (non-final) responses with status codes in the 5793 "informational" (1xx) range, followed by exactly one final response 5794 with a status code in one of the other ranges. 5796 10.1. Overview of Status Codes 5798 The status codes listed below are defined in this specification. The 5799 reason phrases listed here are only recommendations - they can be 5800 replaced by local equivalents without affecting the protocol. 5802 Responses with status codes that are defined as heuristically 5803 cacheable (e.g., 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 5804 414, and 501 in this specification) can be reused by a cache with 5805 heuristic expiration unless otherwise indicated by the method 5806 definition or explicit cache controls [Caching]; all other status 5807 codes are not heuristically cacheable. 5809 +-------+-------------------------------+-----------------+ 5810 | Value | Description | Reference | 5811 | 100 | Continue | Section 10.2.1 | 5812 | 101 | Switching Protocols | Section 10.2.2 | 5813 | 200 | OK | Section 10.3.1 | 5814 | 201 | Created | Section 10.3.2 | 5815 | 202 | Accepted | Section 10.3.3 | 5816 | 203 | Non-Authoritative Information | Section 10.3.4 | 5817 | 204 | No Content | Section 10.3.5 | 5818 | 205 | Reset Content | Section 10.3.6 | 5819 | 206 | Partial Content | Section 10.3.7 | 5820 | 300 | Multiple Choices | Section 10.4.1 | 5821 | 301 | Moved Permanently | Section 10.4.2 | 5822 | 302 | Found | Section 10.4.3 | 5823 | 303 | See Other | Section 10.4.4 | 5824 | 304 | Not Modified | Section 10.4.5 | 5825 | 305 | Use Proxy | Section 10.4.6 | 5826 | 306 | (Unused) | Section 10.4.7 | 5827 | 307 | Temporary Redirect | Section 10.4.8 | 5828 | 308 | Permanent Redirect | Section 10.4.9 | 5829 | 400 | Bad Request | Section 10.5.1 | 5830 | 401 | Unauthorized | Section 10.5.2 | 5831 | 402 | Payment Required | Section 10.5.3 | 5832 | 403 | Forbidden | Section 10.5.4 | 5833 | 404 | Not Found | Section 10.5.5 | 5834 | 405 | Method Not Allowed | Section 10.5.6 | 5835 | 406 | Not Acceptable | Section 10.5.7 | 5836 | 407 | Proxy Authentication Required | Section 10.5.8 | 5837 | 408 | Request Timeout | Section 10.5.9 | 5838 | 409 | Conflict | Section 10.5.10 | 5839 | 410 | Gone | Section 10.5.11 | 5840 | 411 | Length Required | Section 10.5.12 | 5841 | 412 | Precondition Failed | Section 10.5.13 | 5842 | 413 | Payload Too Large | Section 10.5.14 | 5843 | 414 | URI Too Long | Section 10.5.15 | 5844 | 415 | Unsupported Media Type | Section 10.5.16 | 5845 | 416 | Range Not Satisfiable | Section 10.5.17 | 5846 | 417 | Expectation Failed | Section 10.5.18 | 5847 | 418 | (Unused) | Section 10.5.19 | 5848 | 422 | Unprocessable Payload | Section 10.5.20 | 5849 | 426 | Upgrade Required | Section 10.5.21 | 5850 | 500 | Internal Server Error | Section 10.6.1 | 5851 | 501 | Not Implemented | Section 10.6.2 | 5852 | 502 | Bad Gateway | Section 10.6.3 | 5853 | 503 | Service Unavailable | Section 10.6.4 | 5854 | 504 | Gateway Timeout | Section 10.6.5 | 5855 | 505 | HTTP Version Not Supported | Section 10.6.6 | 5856 +-------+-------------------------------+-----------------+ 5858 Table 16 5860 Note that this list is not exhaustive - it does not include extension 5861 status codes defined in other specifications (Section 10.7). 5863 10.2. Informational 1xx 5865 The 1xx (Informational) class of status code indicates an interim 5866 response for communicating connection status or request progress 5867 prior to completing the requested action and sending a final 5868 response. 1xx responses are terminated by the end of the header 5869 section. Since HTTP/1.0 did not define any 1xx status codes, a 5870 server MUST NOT send a 1xx response to an HTTP/1.0 client. 5872 A client MUST be able to parse one or more 1xx responses received 5873 prior to a final response, even if the client does not expect one. A 5874 user agent MAY ignore unexpected 1xx responses. 5876 A proxy MUST forward 1xx responses unless the proxy itself requested 5877 the generation of the 1xx response. For example, if a proxy adds an 5878 "Expect: 100-continue" field when it forwards a request, then it need 5879 not forward the corresponding 100 (Continue) response(s). 5881 10.2.1. 100 Continue 5883 The 100 (Continue) status code indicates that the initial part of a 5884 request has been received and has not yet been rejected by the 5885 server. The server intends to send a final response after the 5886 request has been fully received and acted upon. 5888 When the request contains an Expect header field that includes a 5889 100-continue expectation, the 100 response indicates that the server 5890 wishes to receive the request payload body, as described in 5891 Section 9.1.1. The client ought to continue sending the request and 5892 discard the 100 response. 5894 If the request did not contain an Expect header field containing the 5895 100-continue expectation, the client can simply discard this interim 5896 response. 5898 10.2.2. 101 Switching Protocols 5900 The 101 (Switching Protocols) status code indicates that the server 5901 understands and is willing to comply with the client's request, via 5902 the Upgrade header field (Section 9.9 of [Messaging]), for a change 5903 in the application protocol being used on this connection. The 5904 server MUST generate an Upgrade header field in the response that 5905 indicates which protocol(s) will be switched to immediately after the 5906 empty line that terminates the 101 response. 5908 It is assumed that the server will only agree to switch protocols 5909 when it is advantageous to do so. For example, switching to a newer 5910 version of HTTP might be advantageous over older versions, and 5911 switching to a real-time, synchronous protocol might be advantageous 5912 when delivering resources that use such features. 5914 10.3. Successful 2xx 5916 The 2xx (Successful) class of status code indicates that the client's 5917 request was successfully received, understood, and accepted. 5919 10.3.1. 200 OK 5921 The 200 (OK) status code indicates that the request has succeeded. 5922 The payload sent in a 200 response depends on the request method. 5923 For the methods defined by this specification, the intended meaning 5924 of the payload can be summarized as: 5926 GET a representation of the target resource; 5928 HEAD the same representation as GET, but without the representation 5929 data; 5931 POST a representation of the status of, or results obtained from, 5932 the action; 5934 PUT, DELETE a representation of the status of the action; 5935 OPTIONS a representation of the communications options; 5937 TRACE a representation of the request message as received by the end 5938 server. 5940 Aside from responses to CONNECT, a 200 response always has a payload, 5941 though an origin server MAY generate a payload body of zero length. 5942 If no payload is desired, an origin server ought to send 204 (No 5943 Content) instead. For CONNECT, no payload is allowed because the 5944 successful result is a tunnel, which begins immediately after the 200 5945 response header section. 5947 A 200 response is heuristically cacheable; i.e., unless otherwise 5948 indicated by the method definition or explicit cache controls (see 5949 Section 4.2.2 of [Caching]). 5951 10.3.2. 201 Created 5953 The 201 (Created) status code indicates that the request has been 5954 fulfilled and has resulted in one or more new resources being 5955 created. The primary resource created by the request is identified 5956 by either a Location header field in the response or, if no Location 5957 field is received, by the target URI. 5959 The 201 response payload typically describes and links to the 5960 resource(s) created. See Section 11.2 for a discussion of the 5961 meaning and purpose of validator header fields, such as ETag and 5962 Last-Modified, in a 201 response. 5964 10.3.3. 202 Accepted 5966 The 202 (Accepted) status code indicates that the request has been 5967 accepted for processing, but the processing has not been completed. 5968 The request might or might not eventually be acted upon, as it might 5969 be disallowed when processing actually takes place. There is no 5970 facility in HTTP for re-sending a status code from an asynchronous 5971 operation. 5973 The 202 response is intentionally noncommittal. Its purpose is to 5974 allow a server to accept a request for some other process (perhaps a 5975 batch-oriented process that is only run once per day) without 5976 requiring that the user agent's connection to the server persist 5977 until the process is completed. The representation sent with this 5978 response ought to describe the request's current status and point to 5979 (or embed) a status monitor that can provide the user with an 5980 estimate of when the request will be fulfilled. 5982 10.3.4. 203 Non-Authoritative Information 5984 The 203 (Non-Authoritative Information) status code indicates that 5985 the request was successful but the enclosed payload has been modified 5986 from that of the origin server's 200 (OK) response by a transforming 5987 proxy (Section 6.7.2). This status code allows the proxy to notify 5988 recipients when a transformation has been applied, since that 5989 knowledge might impact later decisions regarding the content. For 5990 example, future cache validation requests for the content might only 5991 be applicable along the same request path (through the same proxies). 5993 The 203 response is similar to the Warning code of 214 Transformation 5994 Applied (Section 5.5 of [Caching]), which has the advantage of being 5995 applicable to responses with any status code. 5997 A 203 response is heuristically cacheable; i.e., unless otherwise 5998 indicated by the method definition or explicit cache controls (see 5999 Section 4.2.2 of [Caching]). 6001 10.3.5. 204 No Content 6003 The 204 (No Content) status code indicates that the server has 6004 successfully fulfilled the request and that there is no additional 6005 content to send in the response payload body. Metadata in the 6006 response header fields refer to the target resource and its selected 6007 representation after the requested action was applied. 6009 For example, if a 204 status code is received in response to a PUT 6010 request and the response contains an ETag field, then the PUT was 6011 successful and the ETag field value contains the entity-tag for the 6012 new representation of that target resource. 6014 The 204 response allows a server to indicate that the action has been 6015 successfully applied to the target resource, while implying that the 6016 user agent does not need to traverse away from its current "document 6017 view" (if any). The server assumes that the user agent will provide 6018 some indication of the success to its user, in accord with its own 6019 interface, and apply any new or updated metadata in the response to 6020 its active representation. 6022 For example, a 204 status code is commonly used with document editing 6023 interfaces corresponding to a "save" action, such that the document 6024 being saved remains available to the user for editing. It is also 6025 frequently used with interfaces that expect automated data transfers 6026 to be prevalent, such as within distributed version control systems. 6028 A 204 response is terminated by the first empty line after the header 6029 fields because it cannot contain a message body. 6031 A 204 response is heuristically cacheable; i.e., unless otherwise 6032 indicated by the method definition or explicit cache controls (see 6033 Section 4.2.2 of [Caching]). 6035 10.3.6. 205 Reset Content 6037 The 205 (Reset Content) status code indicates that the server has 6038 fulfilled the request and desires that the user agent reset the 6039 "document view", which caused the request to be sent, to its original 6040 state as received from the origin server. 6042 This response is intended to support a common data entry use case 6043 where the user receives content that supports data entry (a form, 6044 notepad, canvas, etc.), enters or manipulates data in that space, 6045 causes the entered data to be submitted in a request, and then the 6046 data entry mechanism is reset for the next entry so that the user can 6047 easily initiate another input action. 6049 Since the 205 status code implies that no additional content will be 6050 provided, a server MUST NOT generate a payload in a 205 response. 6052 10.3.7. 206 Partial Content 6054 The 206 (Partial Content) status code indicates that the server is 6055 successfully fulfilling a range request for the target resource by 6056 transferring one or more parts of the selected representation. 6058 When a 206 response is generated, the server MUST generate the 6059 following header fields, in addition to those required in the 6060 subsections below, if the field would have been sent in a 200 (OK) 6061 response to the same request: Date, Cache-Control, ETag, Expires, 6062 Content-Location, and Vary. 6064 If a 206 is generated in response to a request with an If-Range 6065 header field, the sender SHOULD NOT generate other representation 6066 header fields beyond those required, because the client is understood 6067 to already have a prior response containing those header fields. 6068 Otherwise, the sender MUST generate all of the representation header 6069 fields that would have been sent in a 200 (OK) response to the same 6070 request. 6072 A 206 response is heuristically cacheable; i.e., unless otherwise 6073 indicated by explicit cache controls (see Section 4.2.2 of 6074 [Caching]). 6076 10.3.7.1. Single Part 6078 If a single part is being transferred, the server generating the 206 6079 response MUST generate a Content-Range header field, describing what 6080 range of the selected representation is enclosed, and a payload 6081 consisting of the range. For example: 6083 HTTP/1.1 206 Partial Content 6084 Date: Wed, 15 Nov 1995 06:25:24 GMT 6085 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 6086 Content-Range: bytes 21010-47021/47022 6087 Content-Length: 26012 6088 Content-Type: image/gif 6090 ... 26012 bytes of partial image data ... 6092 10.3.7.2. Multiple Parts 6094 If multiple parts are being transferred, the server generating the 6095 206 response MUST generate a "multipart/byteranges" payload, as 6096 defined in Section 7.3.5, and a Content-Type header field containing 6097 the multipart/byteranges media type and its required boundary 6098 parameter. To avoid confusion with single-part responses, a server 6099 MUST NOT generate a Content-Range header field in the HTTP header 6100 section of a multiple part response (this field will be sent in each 6101 part instead). 6103 Within the header area of each body part in the multipart payload, 6104 the server MUST generate a Content-Range header field corresponding 6105 to the range being enclosed in that body part. If the selected 6106 representation would have had a Content-Type header field in a 200 6107 (OK) response, the server SHOULD generate that same Content-Type 6108 field in the header area of each body part. For example: 6110 HTTP/1.1 206 Partial Content 6111 Date: Wed, 15 Nov 1995 06:25:24 GMT 6112 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 6113 Content-Length: 1741 6114 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 6116 --THIS_STRING_SEPARATES 6117 Content-Type: application/pdf 6118 Content-Range: bytes 500-999/8000 6120 ...the first range... 6121 --THIS_STRING_SEPARATES 6122 Content-Type: application/pdf 6123 Content-Range: bytes 7000-7999/8000 6125 ...the second range 6126 --THIS_STRING_SEPARATES-- 6128 When multiple ranges are requested, a server MAY coalesce any of the 6129 ranges that overlap, or that are separated by a gap that is smaller 6130 than the overhead of sending multiple parts, regardless of the order 6131 in which the corresponding range-spec appeared in the received Range 6132 header field. Since the typical overhead between parts of a 6133 multipart/byteranges payload is around 80 bytes, depending on the 6134 selected representation's media type and the chosen boundary 6135 parameter length, it can be less efficient to transfer many small 6136 disjoint parts than it is to transfer the entire selected 6137 representation. 6139 A server MUST NOT generate a multipart response to a request for a 6140 single range, since a client that does not request multiple parts 6141 might not support multipart responses. However, a server MAY 6142 generate a multipart/byteranges payload with only a single body part 6143 if multiple ranges were requested and only one range was found to be 6144 satisfiable or only one range remained after coalescing. A client 6145 that cannot process a multipart/byteranges response MUST NOT generate 6146 a request that asks for multiple ranges. 6148 When a multipart response payload is generated, the server SHOULD 6149 send the parts in the same order that the corresponding range-spec 6150 appeared in the received Range header field, excluding those ranges 6151 that were deemed unsatisfiable or that were coalesced into other 6152 ranges. A client that receives a multipart response MUST inspect the 6153 Content-Range header field present in each body part in order to 6154 determine which range is contained in that body part; a client cannot 6155 rely on receiving the same ranges that it requested, nor the same 6156 order that it requested. 6158 10.3.7.3. Combining Parts 6160 A response might transfer only a subrange of a representation if the 6161 connection closed prematurely or if the request used one or more 6162 Range specifications. After several such transfers, a client might 6163 have received several ranges of the same representation. These 6164 ranges can only be safely combined if they all have in common the 6165 same strong validator (Section 11.2.1). 6167 A client that has received multiple partial responses to GET requests 6168 on a target resource MAY combine those responses into a larger 6169 continuous range if they share the same strong validator. 6171 If the most recent response is an incomplete 200 (OK) response, then 6172 the header fields of that response are used for any combined response 6173 and replace those of the matching stored responses. 6175 If the most recent response is a 206 (Partial Content) response and 6176 at least one of the matching stored responses is a 200 (OK), then the 6177 combined response header fields consist of the most recent 200 6178 response's header fields. If all of the matching stored responses 6179 are 206 responses, then the stored response with the most recent 6180 header fields is used as the source of header fields for the combined 6181 response, except that the client MUST use other header fields 6182 provided in the new response, aside from Content-Range, to replace 6183 all instances of the corresponding header fields in the stored 6184 response. 6186 The combined response message body consists of the union of partial 6187 content ranges in the new response and each of the selected 6188 responses. If the union consists of the entire range of the 6189 representation, then the client MUST process the combined response as 6190 if it were a complete 200 (OK) response, including a Content-Length 6191 header field that reflects the complete length. Otherwise, the 6192 client MUST process the set of continuous ranges as one of the 6193 following: an incomplete 200 (OK) response if the combined response 6194 is a prefix of the representation, a single 206 (Partial Content) 6195 response containing a multipart/byteranges body, or multiple 206 6196 (Partial Content) responses, each with one continuous range that is 6197 indicated by a Content-Range header field. 6199 10.4. Redirection 3xx 6201 The 3xx (Redirection) class of status code indicates that further 6202 action needs to be taken by the user agent in order to fulfill the 6203 request. If a Location header field (Section 11.1.2) is provided, 6204 the user agent MAY automatically redirect its request to the URI 6205 referenced by the Location field value, even if the specific status 6206 code is not understood. Automatic redirection needs to be done with 6207 care for methods not known to be safe, as defined in Section 8.2.1, 6208 since the user might not wish to redirect an unsafe request. 6210 There are several types of redirects: 6212 1. Redirects that indicate the resource might be available at a 6213 different URI, as provided by the Location field, as in the 6214 status codes 301 (Moved Permanently), 302 (Found), 307 (Temporary 6215 Redirect), and 308 (Permanent Redirect). 6217 2. Redirection that offers a choice of matching resources, each 6218 capable of representing the original target resource, as in the 6219 300 (Multiple Choices) status code. 6221 3. Redirection to a different resource, identified by the Location 6222 field, that can represent an indirect response to the request, as 6223 in the 303 (See Other) status code. 6225 4. Redirection to a previously cached result, as in the 304 (Not 6226 Modified) status code. 6228 | *Note:* In HTTP/1.0, the status codes 301 (Moved Permanently) 6229 | and 302 (Found) were defined for the first type of redirect 6230 | ([RFC1945], Section 9.3). Early user agents split on whether 6231 | the method applied to the redirect target would be the same as 6232 | the original request or would be rewritten as GET. Although 6233 | HTTP originally defined the former semantics for 301 and 302 6234 | (to match its original implementation at CERN), and defined 303 6235 | (See Other) to match the latter semantics, prevailing practice 6236 | gradually converged on the latter semantics for 301 and 302 as 6237 | well. The first revision of HTTP/1.1 added 307 (Temporary 6238 | Redirect) to indicate the former semantics of 302 without being 6239 | impacted by divergent practice. For the same reason, 308 6240 | (Permanent Redirect) was later on added in [RFC7538] to match 6241 | 301. Over 10 years later, most user agents still do method 6242 | rewriting for 301 and 302; therefore, [RFC7231] made that 6243 | behavior conformant when the original request is POST. 6245 A client SHOULD detect and intervene in cyclical redirections (i.e., 6246 "infinite" redirection loops). 6248 | *Note:* An earlier version of this specification recommended a 6249 | maximum of five redirections ([RFC2068], Section 10.3). 6250 | Content developers need to be aware that some clients might 6251 | implement such a fixed limitation. 6253 10.4.1. 300 Multiple Choices 6255 The 300 (Multiple Choices) status code indicates that the target 6256 resource has more than one representation, each with its own more 6257 specific identifier, and information about the alternatives is being 6258 provided so that the user (or user agent) can select a preferred 6259 representation by redirecting its request to one or more of those 6260 identifiers. In other words, the server desires that the user agent 6261 engage in reactive negotiation to select the most appropriate 6262 representation(s) for its needs (Section 7.4). 6264 If the server has a preferred choice, the server SHOULD generate a 6265 Location header field containing a preferred choice's URI reference. 6266 The user agent MAY use the Location field value for automatic 6267 redirection. 6269 For request methods other than HEAD, the server SHOULD generate a 6270 payload in the 300 response containing a list of representation 6271 metadata and URI reference(s) from which the user or user agent can 6272 choose the one most preferred. The user agent MAY make a selection 6273 from that list automatically if it understands the provided media 6274 type. A specific format for automatic selection is not defined by 6275 this specification because HTTP tries to remain orthogonal to the 6276 definition of its payloads. In practice, the representation is 6277 provided in some easily parsed format believed to be acceptable to 6278 the user agent, as determined by shared design or content 6279 negotiation, or in some commonly accepted hypertext format. 6281 A 300 response is heuristically cacheable; i.e., unless otherwise 6282 indicated by the method definition or explicit cache controls (see 6283 Section 4.2.2 of [Caching]). 6285 | *Note:* The original proposal for the 300 status code defined 6286 | the URI header field as providing a list of alternative 6287 | representations, such that it would be usable for 200, 300, and 6288 | 406 responses and be transferred in responses to the HEAD 6289 | method. However, lack of deployment and disagreement over 6290 | syntax led to both URI and Alternates (a subsequent proposal) 6291 | being dropped from this specification. It is possible to 6292 | communicate the list as a Link header field value [RFC8288] 6293 | whose members have a relationship of "alternate", though 6294 | deployment is a chicken-and-egg problem. 6296 10.4.2. 301 Moved Permanently 6298 The 301 (Moved Permanently) status code indicates that the target 6299 resource has been assigned a new permanent URI and any future 6300 references to this resource ought to use one of the enclosed URIs. 6301 Clients with link-editing capabilities ought to automatically re-link 6302 references to the target URI to one or more of the new references 6303 sent by the server, where possible. 6305 The server SHOULD generate a Location header field in the response 6306 containing a preferred URI reference for the new permanent URI. The 6307 user agent MAY use the Location field value for automatic 6308 redirection. The server's response payload usually contains a short 6309 hypertext note with a hyperlink to the new URI(s). 6311 | *Note:* For historical reasons, a user agent MAY change the 6312 | request method from POST to GET for the subsequent request. If 6313 | this behavior is undesired, the 308 (Permanent Redirect) status 6314 | code can be used instead. 6316 A 301 response is heuristically cacheable; i.e., unless otherwise 6317 indicated by the method definition or explicit cache controls (see 6318 Section 4.2.2 of [Caching]). 6320 10.4.3. 302 Found 6322 The 302 (Found) status code indicates that the target resource 6323 resides temporarily under a different URI. Since the redirection 6324 might be altered on occasion, the client ought to continue to use the 6325 target URI for future requests. 6327 The server SHOULD generate a Location header field in the response 6328 containing a URI reference for the different URI. The user agent MAY 6329 use the Location field value for automatic redirection. The server's 6330 response payload usually contains a short hypertext note with a 6331 hyperlink to the different URI(s). 6333 | *Note:* For historical reasons, a user agent MAY change the 6334 | request method from POST to GET for the subsequent request. If 6335 | this behavior is undesired, the 307 (Temporary Redirect) status 6336 | code can be used instead. 6338 10.4.4. 303 See Other 6340 The 303 (See Other) status code indicates that the server is 6341 redirecting the user agent to a different resource, as indicated by a 6342 URI in the Location header field, which is intended to provide an 6343 indirect response to the original request. A user agent can perform 6344 a retrieval request targeting that URI (a GET or HEAD request if 6345 using HTTP), which might also be redirected, and present the eventual 6346 result as an answer to the original request. Note that the new URI 6347 in the Location header field is not considered equivalent to the 6348 target URI. 6350 This status code is applicable to any HTTP method. It is primarily 6351 used to allow the output of a POST action to redirect the user agent 6352 to a selected resource, since doing so provides the information 6353 corresponding to the POST response in a form that can be separately 6354 identified, bookmarked, and cached, independent of the original 6355 request. 6357 A 303 response to a GET request indicates that the origin server does 6358 not have a representation of the target resource that can be 6359 transferred by the server over HTTP. However, the Location field 6360 value refers to a resource that is descriptive of the target 6361 resource, such that making a retrieval request on that other resource 6362 might result in a representation that is useful to recipients without 6363 implying that it represents the original target resource. Note that 6364 answers to the questions of what can be represented, what 6365 representations are adequate, and what might be a useful description 6366 are outside the scope of HTTP. 6368 Except for responses to a HEAD request, the representation of a 303 6369 response ought to contain a short hypertext note with a hyperlink to 6370 the same URI reference provided in the Location header field. 6372 10.4.5. 304 Not Modified 6374 The 304 (Not Modified) status code indicates that a conditional GET 6375 or HEAD request has been received and would have resulted in a 200 6376 (OK) response if it were not for the fact that the condition 6377 evaluated to false. In other words, there is no need for the server 6378 to transfer a representation of the target resource because the 6379 request indicates that the client, which made the request 6380 conditional, already has a valid representation; the server is 6381 therefore redirecting the client to make use of that stored 6382 representation as if it were the payload of a 200 (OK) response. 6384 The server generating a 304 response MUST generate any of the 6385 following header fields that would have been sent in a 200 (OK) 6386 response to the same request: Cache-Control, Content-Location, Date, 6387 ETag, Expires, and Vary. 6389 Since the goal of a 304 response is to minimize information transfer 6390 when the recipient already has one or more cached representations, a 6391 sender SHOULD NOT generate representation metadata other than the 6392 above listed fields unless said metadata exists for the purpose of 6393 guiding cache updates (e.g., Last-Modified might be useful if the 6394 response does not have an ETag field). 6396 Requirements on a cache that receives a 304 response are defined in 6397 Section 4.3.4 of [Caching]. If the conditional request originated 6398 with an outbound client, such as a user agent with its own cache 6399 sending a conditional GET to a shared proxy, then the proxy SHOULD 6400 forward the 304 response to that client. 6402 A 304 response cannot contain a message-body; it is always terminated 6403 by the first empty line after the header fields. 6405 10.4.6. 305 Use Proxy 6407 The 305 (Use Proxy) status code was defined in a previous version of 6408 this specification and is now deprecated (Appendix B of [RFC7231]). 6410 10.4.7. 306 (Unused) 6412 The 306 status code was defined in a previous version of this 6413 specification, is no longer used, and the code is reserved. 6415 10.4.8. 307 Temporary Redirect 6417 The 307 (Temporary Redirect) status code indicates that the target 6418 resource resides temporarily under a different URI and the user agent 6419 MUST NOT change the request method if it performs an automatic 6420 redirection to that URI. Since the redirection can change over time, 6421 the client ought to continue using the original target URI for future 6422 requests. 6424 The server SHOULD generate a Location header field in the response 6425 containing a URI reference for the different URI. The user agent MAY 6426 use the Location field value for automatic redirection. The server's 6427 response payload usually contains a short hypertext note with a 6428 hyperlink to the different URI(s). 6430 10.4.9. 308 Permanent Redirect 6432 The 308 (Permanent Redirect) status code indicates that the target 6433 resource has been assigned a new permanent URI and any future 6434 references to this resource ought to use one of the enclosed URIs. 6435 Clients with link editing capabilities ought to automatically re-link 6436 references to the target URI to one or more of the new references 6437 sent by the server, where possible. 6439 The server SHOULD generate a Location header field in the response 6440 containing a preferred URI reference for the new permanent URI. The 6441 user agent MAY use the Location field value for automatic 6442 redirection. The server's response payload usually contains a short 6443 hypertext note with a hyperlink to the new URI(s). 6445 A 308 response is heuristically cacheable; i.e., unless otherwise 6446 indicated by the method definition or explicit cache controls (see 6447 Section 4.2.2 of [Caching]). 6449 | *Note:* This status code is much younger (June 2014) than its 6450 | sibling codes, and thus might not be recognized everywhere. 6451 | See Section 4 of [RFC7538] for deployment considerations. 6453 10.5. Client Error 4xx 6455 The 4xx (Client Error) class of status code indicates that the client 6456 seems to have erred. Except when responding to a HEAD request, the 6457 server SHOULD send a representation containing an explanation of the 6458 error situation, and whether it is a temporary or permanent 6459 condition. These status codes are applicable to any request method. 6460 User agents SHOULD display any included representation to the user. 6462 10.5.1. 400 Bad Request 6464 The 400 (Bad Request) status code indicates that the server cannot or 6465 will not process the request due to something that is perceived to be 6466 a client error (e.g., malformed request syntax, invalid request 6467 message framing, or deceptive request routing). 6469 10.5.2. 401 Unauthorized 6471 The 401 (Unauthorized) status code indicates that the request has not 6472 been applied because it lacks valid authentication credentials for 6473 the target resource. The server generating a 401 response MUST send 6474 a WWW-Authenticate header field (Section 11.3.1) containing at least 6475 one challenge applicable to the target resource. 6477 If the request included authentication credentials, then the 401 6478 response indicates that authorization has been refused for those 6479 credentials. The user agent MAY repeat the request with a new or 6480 replaced Authorization header field (Section 9.5.3). If the 401 6481 response contains the same challenge as the prior response, and the 6482 user agent has already attempted authentication at least once, then 6483 the user agent SHOULD present the enclosed representation to the 6484 user, since it usually contains relevant diagnostic information. 6486 10.5.3. 402 Payment Required 6488 The 402 (Payment Required) status code is reserved for future use. 6490 10.5.4. 403 Forbidden 6492 The 403 (Forbidden) status code indicates that the server understood 6493 the request but refuses to fulfill it. A server that wishes to make 6494 public why the request has been forbidden can describe that reason in 6495 the response payload (if any). 6497 If authentication credentials were provided in the request, the 6498 server considers them insufficient to grant access. The client 6499 SHOULD NOT automatically repeat the request with the same 6500 credentials. The client MAY repeat the request with new or different 6501 credentials. However, a request might be forbidden for reasons 6502 unrelated to the credentials. 6504 An origin server that wishes to "hide" the current existence of a 6505 forbidden target resource MAY instead respond with a status code of 6506 404 (Not Found). 6508 10.5.5. 404 Not Found 6510 The 404 (Not Found) status code indicates that the origin server did 6511 not find a current representation for the target resource or is not 6512 willing to disclose that one exists. A 404 status code does not 6513 indicate whether this lack of representation is temporary or 6514 permanent; the 410 (Gone) status code is preferred over 404 if the 6515 origin server knows, presumably through some configurable means, that 6516 the condition is likely to be permanent. 6518 A 404 response is heuristically cacheable; i.e., unless otherwise 6519 indicated by the method definition or explicit cache controls (see 6520 Section 4.2.2 of [Caching]). 6522 10.5.6. 405 Method Not Allowed 6524 The 405 (Method Not Allowed) status code indicates that the method 6525 received in the request-line is known by the origin server but not 6526 supported by the target resource. The origin server MUST generate an 6527 Allow header field in a 405 response containing a list of the target 6528 resource's currently supported methods. 6530 A 405 response is heuristically cacheable; i.e., unless otherwise 6531 indicated by the method definition or explicit cache controls (see 6532 Section 4.2.2 of [Caching]). 6534 10.5.7. 406 Not Acceptable 6536 The 406 (Not Acceptable) status code indicates that the target 6537 resource does not have a current representation that would be 6538 acceptable to the user agent, according to the proactive negotiation 6539 header fields received in the request (Section 9.4), and the server 6540 is unwilling to supply a default representation. 6542 The server SHOULD generate a payload containing a list of available 6543 representation characteristics and corresponding resource identifiers 6544 from which the user or user agent can choose the one most 6545 appropriate. A user agent MAY automatically select the most 6546 appropriate choice from that list. However, this specification does 6547 not define any standard for such automatic selection, as described in 6548 Section 10.4.1. 6550 10.5.8. 407 Proxy Authentication Required 6552 The 407 (Proxy Authentication Required) status code is similar to 401 6553 (Unauthorized), but it indicates that the client needs to 6554 authenticate itself in order to use a proxy for this request. The 6555 proxy MUST send a Proxy-Authenticate header field (Section 11.3.2) 6556 containing a challenge applicable to that proxy for the request. The 6557 client MAY repeat the request with a new or replaced 6558 Proxy-Authorization header field (Section 9.5.4). 6560 10.5.9. 408 Request Timeout 6562 The 408 (Request Timeout) status code indicates that the server did 6563 not receive a complete request message within the time that it was 6564 prepared to wait. If the client has an outstanding request in 6565 transit, the client MAY repeat that request on a new connection. 6567 10.5.10. 409 Conflict 6569 The 409 (Conflict) status code indicates that the request could not 6570 be completed due to a conflict with the current state of the target 6571 resource. This code is used in situations where the user might be 6572 able to resolve the conflict and resubmit the request. The server 6573 SHOULD generate a payload that includes enough information for a user 6574 to recognize the source of the conflict. 6576 Conflicts are most likely to occur in response to a PUT request. For 6577 example, if versioning were being used and the representation being 6578 PUT included changes to a resource that conflict with those made by 6579 an earlier (third-party) request, the origin server might use a 409 6580 response to indicate that it can't complete the request. In this 6581 case, the response representation would likely contain information 6582 useful for merging the differences based on the revision history. 6584 10.5.11. 410 Gone 6586 The 410 (Gone) status code indicates that access to the target 6587 resource is no longer available at the origin server and that this 6588 condition is likely to be permanent. If the origin server does not 6589 know, or has no facility to determine, whether or not the condition 6590 is permanent, the status code 404 (Not Found) ought to be used 6591 instead. 6593 The 410 response is primarily intended to assist the task of web 6594 maintenance by notifying the recipient that the resource is 6595 intentionally unavailable and that the server owners desire that 6596 remote links to that resource be removed. Such an event is common 6597 for limited-time, promotional services and for resources belonging to 6598 individuals no longer associated with the origin server's site. It 6599 is not necessary to mark all permanently unavailable resources as 6600 "gone" or to keep the mark for any length of time - that is left to 6601 the discretion of the server owner. 6603 A 410 response is heuristically cacheable; i.e., unless otherwise 6604 indicated by the method definition or explicit cache controls (see 6605 Section 4.2.2 of [Caching]). 6607 10.5.12. 411 Length Required 6609 The 411 (Length Required) status code indicates that the server 6610 refuses to accept the request without a defined Content-Length 6611 (Section 7.2.4). The client MAY repeat the request if it adds a 6612 valid Content-Length header field containing the length of the 6613 message body in the request message. 6615 10.5.13. 412 Precondition Failed 6617 The 412 (Precondition Failed) status code indicates that one or more 6618 conditions given in the request header fields evaluated to false when 6619 tested on the server. This response status code allows the client to 6620 place preconditions on the current resource state (its current 6621 representations and metadata) and, thus, prevent the request method 6622 from being applied if the target resource is in an unexpected state. 6624 10.5.14. 413 Payload Too Large 6626 The 413 (Payload Too Large) status code indicates that the server is 6627 refusing to process a request because the request payload is larger 6628 than the server is willing or able to process. The server MAY 6629 terminate the request, if the protocol version in use allows it; 6630 otherwise, the server MAY close the connection. 6632 If the condition is temporary, the server SHOULD generate a 6633 Retry-After header field to indicate that it is temporary and after 6634 what time the client MAY try again. 6636 10.5.15. 414 URI Too Long 6638 The 414 (URI Too Long) status code indicates that the server is 6639 refusing to service the request because the target URI is longer than 6640 the server is willing to interpret. This rare condition is only 6641 likely to occur when a client has improperly converted a POST request 6642 to a GET request with long query information, when the client has 6643 descended into a "black hole" of redirection (e.g., a redirected URI 6644 prefix that points to a suffix of itself) or when the server is under 6645 attack by a client attempting to exploit potential security holes. 6647 A 414 response is heuristically cacheable; i.e., unless otherwise 6648 indicated by the method definition or explicit cache controls (see 6649 Section 4.2.2 of [Caching]). 6651 10.5.16. 415 Unsupported Media Type 6653 The 415 (Unsupported Media Type) status code indicates that the 6654 origin server is refusing to service the request because the payload 6655 is in a format not supported by this method on the target resource. 6657 The format problem might be due to the request's indicated 6658 Content-Type or Content-Encoding, or as a result of inspecting the 6659 data directly. 6661 If the problem was caused by an unsupported content coding, the 6662 Accept-Encoding response header field (Section 9.4.3) ought to be 6663 used to indicate what (if any) content codings would have been 6664 accepted in the request. 6666 On the other hand, if the cause was an unsupported media type, the 6667 Accept response header field (Section 9.4.1) can be used to indicate 6668 what media types would have been accepted in the request. 6670 10.5.17. 416 Range Not Satisfiable 6672 The 416 (Range Not Satisfiable) status code indicates that the set of 6673 ranges in the request's Range header field (Section 9.3) has been 6674 rejected either because none of the requested ranges are satisfiable 6675 or because the client has requested an excessive number of small or 6676 overlapping ranges (a potential denial of service attack). 6678 Each range unit defines what is required for its own range sets to be 6679 satisfiable. For example, Section 7.1.4.2 defines what makes a bytes 6680 range set satisfiable. 6682 When this status code is generated in response to a byte-range 6683 request, the sender SHOULD generate a Content-Range header field 6684 specifying the current length of the selected representation 6685 (Section 7.3.4). 6687 For example: 6689 HTTP/1.1 416 Range Not Satisfiable 6690 Date: Fri, 20 Jan 2012 15:41:54 GMT 6691 Content-Range: bytes */47022 6693 | *Note:* Because servers are free to ignore Range, many 6694 | implementations will respond with the entire selected 6695 | representation in a 200 (OK) response. That is partly because 6696 | most clients are prepared to receive a 200 (OK) to complete the 6697 | task (albeit less efficiently) and partly because clients might 6698 | not stop making an invalid partial request until they have 6699 | received a complete representation. Thus, clients cannot 6700 | depend on receiving a 416 (Range Not Satisfiable) response even 6701 | when it is most appropriate. 6703 10.5.18. 417 Expectation Failed 6705 The 417 (Expectation Failed) status code indicates that the 6706 expectation given in the request's Expect header field 6707 (Section 9.1.1) could not be met by at least one of the inbound 6708 servers. 6710 10.5.19. 418 (Unused) 6712 [RFC2324] was an April 1 RFC that lampooned the various ways HTTP was 6713 abused; one such abuse was the definition of an application-specific 6714 418 status code. In the intervening years, this status code has been 6715 widely implemented as an "Easter Egg", and therefore is effectively 6716 consumed by this use. 6718 Therefore, the 418 status code is reserved in the IANA HTTP Status 6719 Code Registry. This indicates that the status code cannot be 6720 assigned to other applications currently. If future circumstances 6721 require its use (e.g., exhaustion of 4NN status codes), it can be re- 6722 assigned to another use. 6724 10.5.20. 422 Unprocessable Payload 6726 The 422 (Unprocessable Payload) status code indicates that the server 6727 understands the content type of the request payload (hence a 415 6728 (Unsupported Media Type) status code is inappropriate), and the 6729 syntax of the request payload is correct, but was unable to process 6730 the contained instructions. For example, this status code can be 6731 sent if an XML request payload contains well-formed (i.e., 6732 syntactically correct), but semantically erroneous XML instructions. 6734 10.5.21. 426 Upgrade Required 6736 The 426 (Upgrade Required) status code indicates that the server 6737 refuses to perform the request using the current protocol but might 6738 be willing to do so after the client upgrades to a different 6739 protocol. The server MUST send an Upgrade header field in a 426 6740 response to indicate the required protocol(s) (Section 9.9 of 6741 [Messaging]). 6743 Example: 6745 HTTP/1.1 426 Upgrade Required 6746 Upgrade: HTTP/3.0 6747 Connection: Upgrade 6748 Content-Length: 53 6749 Content-Type: text/plain 6751 This service requires use of the HTTP/3.0 protocol. 6753 10.6. Server Error 5xx 6755 The 5xx (Server Error) class of status code indicates that the server 6756 is aware that it has erred or is incapable of performing the 6757 requested method. Except when responding to a HEAD request, the 6758 server SHOULD send a representation containing an explanation of the 6759 error situation, and whether it is a temporary or permanent 6760 condition. A user agent SHOULD display any included representation 6761 to the user. These response codes are applicable to any request 6762 method. 6764 10.6.1. 500 Internal Server Error 6766 The 500 (Internal Server Error) status code indicates that the server 6767 encountered an unexpected condition that prevented it from fulfilling 6768 the request. 6770 10.6.2. 501 Not Implemented 6772 The 501 (Not Implemented) status code indicates that the server does 6773 not support the functionality required to fulfill the request. This 6774 is the appropriate response when the server does not recognize the 6775 request method and is not capable of supporting it for any resource. 6777 A 501 response is heuristically cacheable; i.e., unless otherwise 6778 indicated by the method definition or explicit cache controls (see 6779 Section 4.2.2 of [Caching]). 6781 10.6.3. 502 Bad Gateway 6783 The 502 (Bad Gateway) status code indicates that the server, while 6784 acting as a gateway or proxy, received an invalid response from an 6785 inbound server it accessed while attempting to fulfill the request. 6787 10.6.4. 503 Service Unavailable 6789 The 503 (Service Unavailable) status code indicates that the server 6790 is currently unable to handle the request due to a temporary overload 6791 or scheduled maintenance, which will likely be alleviated after some 6792 delay. The server MAY send a Retry-After header field 6793 (Section 11.1.3) to suggest an appropriate amount of time for the 6794 client to wait before retrying the request. 6796 | *Note:* The existence of the 503 status code does not imply 6797 | that a server has to use it when becoming overloaded. Some 6798 | servers might simply refuse the connection. 6800 10.6.5. 504 Gateway Timeout 6802 The 504 (Gateway Timeout) status code indicates that the server, 6803 while acting as a gateway or proxy, did not receive a timely response 6804 from an upstream server it needed to access in order to complete the 6805 request. 6807 10.6.6. 505 HTTP Version Not Supported 6809 The 505 (HTTP Version Not Supported) status code indicates that the 6810 server does not support, or refuses to support, the major version of 6811 HTTP that was used in the request message. The server is indicating 6812 that it is unable or unwilling to complete the request using the same 6813 major version as the client, as described in Section 4.2, other than 6814 with this error message. The server SHOULD generate a representation 6815 for the 505 response that describes why that version is not supported 6816 and what other protocols are supported by that server. 6818 10.7. Status Code Extensibility 6820 Additional status codes, outside the scope of this specification, 6821 have been specified for use in HTTP. All such status codes ought to 6822 be registered within the "Hypertext Transfer Protocol (HTTP) Status 6823 Code Registry". 6825 10.7.1. Status Code Registry 6827 The "Hypertext Transfer Protocol (HTTP) Status Code Registry", 6828 maintained by IANA at , registers status code numbers. 6831 A registration MUST include the following fields: 6833 o Status Code (3 digits) 6835 o Short Description 6837 o Pointer to specification text 6839 Values to be added to the HTTP status code namespace require IETF 6840 Review (see [RFC8126], Section 4.8). 6842 10.7.2. Considerations for New Status Codes 6844 When it is necessary to express semantics for a response that are not 6845 defined by current status codes, a new status code can be registered. 6846 Status codes are generic; they are potentially applicable to any 6847 resource, not just one particular media type, kind of resource, or 6848 application of HTTP. As such, it is preferred that new status codes 6849 be registered in a document that isn't specific to a single 6850 application. 6852 New status codes are required to fall under one of the categories 6853 defined in Section 10. To allow existing parsers to process the 6854 response message, new status codes cannot disallow a payload, 6855 although they can mandate a zero-length payload body. 6857 Proposals for new status codes that are not yet widely deployed ought 6858 to avoid allocating a specific number for the code until there is 6859 clear consensus that it will be registered; instead, early drafts can 6860 use a notation such as "4NN", or "3N0" .. "3N9", to indicate the 6861 class of the proposed status code(s) without consuming a number 6862 prematurely. 6864 The definition of a new status code ought to explain the request 6865 conditions that would cause a response containing that status code 6866 (e.g., combinations of request header fields and/or method(s)) along 6867 with any dependencies on response header fields (e.g., what fields 6868 are required, what fields can modify the semantics, and what field 6869 semantics are further refined when used with the new status code). 6871 By default, a status code applies only to the request corresponding 6872 to the response it occurs within. If a status code applies to a 6873 larger scope of applicability - for example, all requests to the 6874 resource in question, or all requests to a server - this must be 6875 explicitly specified. When doing so, it should be noted that not all 6876 clients can be expected to consistently apply a larger scope, because 6877 they might not understand the new status code. 6879 The definition of a new status code ought to specify whether or not 6880 it is cacheable. Note that all status codes can be cached if the 6881 response they occur in has explicit freshness information; however, 6882 status codes that are defined as being cacheable are allowed to be 6883 cached without explicit freshness information. Likewise, the 6884 definition of a status code can place constraints upon cache 6885 behavior. See [Caching] for more information. 6887 Finally, the definition of a new status code ought to indicate 6888 whether the payload has any implied association with an identified 6889 resource (Section 7.3.2). 6891 11. Response Header Fields 6893 The response header fields allow the server to pass additional 6894 information about the response beyond the status code. These header 6895 fields give information about the server, about further access to the 6896 target resource, or about related resources. 6898 Although each response header field has a defined meaning, in 6899 general, the precise semantics might be further refined by the 6900 semantics of the request method and/or response status code. 6902 11.1. Control Data 6904 Response header fields can supply control data that supplements the 6905 status code, directs caching, or instructs the client where to go 6906 next. 6908 +---------------+--------------------------+ 6909 | Field Name | Defined in... | 6910 | Age | Section 5.1 of [Caching] | 6911 | Cache-Control | Section 5.2 of [Caching] | 6912 | Expires | Section 5.3 of [Caching] | 6913 | Date | Section 11.1.1 | 6914 | Location | Section 11.1.2 | 6915 | Retry-After | Section 11.1.3 | 6916 | Vary | Section 11.1.4 | 6917 | Warning | Section 5.5 of [Caching] | 6918 +---------------+--------------------------+ 6920 Table 17 6922 11.1.1. Date 6924 The "Date" header field represents the date and time at which the 6925 message was originated, having the same semantics as the Origination 6926 Date Field (orig-date) defined in Section 3.6.1 of [RFC5322]. The 6927 field value is an HTTP-date, as defined in Section 5.4.1.5. 6929 Date = HTTP-date 6931 An example is 6933 Date: Tue, 15 Nov 1994 08:12:31 GMT 6935 When a Date header field is generated, the sender SHOULD generate its 6936 field value as the best available approximation of the date and time 6937 of message generation. In theory, the date ought to represent the 6938 moment just before the payload is generated. In practice, the date 6939 can be generated at any time during message origination. 6941 An origin server MUST NOT send a Date header field if it does not 6942 have a clock capable of providing a reasonable approximation of the 6943 current instance in Coordinated Universal Time. An origin server MAY 6944 send a Date header field if the response is in the 1xx 6945 (Informational) or 5xx (Server Error) class of status codes. An 6946 origin server MUST send a Date header field in all other cases. 6948 A recipient with a clock that receives a response message without a 6949 Date header field MUST record the time it was received and append a 6950 corresponding Date header field to the message's header section if it 6951 is cached or forwarded downstream. 6953 A user agent MAY send a Date header field in a request, though 6954 generally will not do so unless it is believed to convey useful 6955 information to the server. For example, custom applications of HTTP 6956 might convey a Date if the server is expected to adjust its 6957 interpretation of the user's request based on differences between the 6958 user agent and server clocks. 6960 11.1.2. Location 6962 The "Location" header field is used in some responses to refer to a 6963 specific resource in relation to the response. The type of 6964 relationship is defined by the combination of request method and 6965 status code semantics. 6967 Location = URI-reference 6969 The field value consists of a single URI-reference. When it has the 6970 form of a relative reference ([RFC3986], Section 4.2), the final 6971 value is computed by resolving it against the target URI ([RFC3986], 6972 Section 5). 6974 For 201 (Created) responses, the Location value refers to the primary 6975 resource created by the request. For 3xx (Redirection) responses, 6976 the Location value refers to the preferred target resource for 6977 automatically redirecting the request. 6979 If the Location value provided in a 3xx (Redirection) response does 6980 not have a fragment component, a user agent MUST process the 6981 redirection as if the value inherits the fragment component of the 6982 URI reference used to generate the target URI (i.e., the redirection 6983 inherits the original reference's fragment, if any). 6985 For example, a GET request generated for the URI reference 6986 "http://www.example.org/~tim" might result in a 303 (See Other) 6987 response containing the header field: 6989 Location: /People.html#tim 6991 which suggests that the user agent redirect to 6992 "http://www.example.org/People.html#tim" 6994 Likewise, a GET request generated for the URI reference 6995 "http://www.example.org/index.html#larry" might result in a 301 6996 (Moved Permanently) response containing the header field: 6998 Location: http://www.example.net/index.html 7000 which suggests that the user agent redirect to 7001 "http://www.example.net/index.html#larry", preserving the original 7002 fragment identifier. 7004 There are circumstances in which a fragment identifier in a Location 7005 value would not be appropriate. For example, the Location header 7006 field in a 201 (Created) response is supposed to provide a URI that 7007 is specific to the created resource. 7009 | *Note:* Some recipients attempt to recover from Location fields 7010 | that are not valid URI references. This specification does not 7011 | mandate or define such processing, but does allow it for the 7012 | sake of robustness. 7014 | *Note:* The Content-Location header field (Section 7.2.5) 7015 | differs from Location in that the Content-Location refers to 7016 | the most specific resource corresponding to the enclosed 7017 | representation. It is therefore possible for a response to 7018 | contain both the Location and Content-Location header fields. 7020 11.1.3. Retry-After 7022 Servers send the "Retry-After" header field to indicate how long the 7023 user agent ought to wait before making a follow-up request. When 7024 sent with a 503 (Service Unavailable) response, Retry-After indicates 7025 how long the service is expected to be unavailable to the client. 7026 When sent with any 3xx (Redirection) response, Retry-After indicates 7027 the minimum time that the user agent is asked to wait before issuing 7028 the redirected request. 7030 The value of this field can be either an HTTP-date or a number of 7031 seconds to delay after the response is received. 7033 Retry-After = HTTP-date / delay-seconds 7035 A delay-seconds value is a non-negative decimal integer, representing 7036 time in seconds. 7038 delay-seconds = 1*DIGIT 7040 Two examples of its use are 7042 Retry-After: Fri, 31 Dec 1999 23:59:59 GMT 7043 Retry-After: 120 7045 In the latter example, the delay is 2 minutes. 7047 11.1.4. Vary 7049 The "Vary" header field in a response describes what parts of a 7050 request message, aside from the method, Host header field, and target 7051 URI, might influence the origin server's process for selecting and 7052 representing this response. 7054 Vary = 1#( "*" / field-name ) 7056 A Vary field value is a list of request field names, known as the 7057 selecting header fields, that might have a role in selecting the 7058 representation for this response. Potential selecting header fields 7059 are not limited to those defined by this specification. 7061 If the list contains "*", it signals that other aspects of the 7062 request might play a role in selecting the response representation, 7063 possibly including elements outside the message syntax (e.g., the 7064 client's network address). A recipient will not be able to determine 7065 whether this response is appropriate for a later request without 7066 forwarding the request to the origin server. A proxy MUST NOT 7067 generate "*" in a Vary field value. 7069 For example, a response that contains 7071 Vary: accept-encoding, accept-language 7073 indicates that the origin server might have used the request's 7074 Accept-Encoding and Accept-Language fields (or lack thereof) as 7075 determining factors while choosing the content for this response. 7077 An origin server might send Vary with a list of fields for two 7078 purposes: 7080 1. To inform cache recipients that they MUST NOT use this response 7081 to satisfy a later request unless the later request has the same 7082 values for the listed fields as the original request (Section 4.1 7083 of [Caching]). In other words, Vary expands the cache key 7084 required to match a new request to the stored cache entry. 7086 2. To inform user agent recipients that this response is subject to 7087 content negotiation (Section 9.4) and that a different 7088 representation might be sent in a subsequent request if 7089 additional parameters are provided in the listed header fields 7090 (proactive negotiation). 7092 An origin server SHOULD send a Vary header field when its algorithm 7093 for selecting a representation varies based on aspects of the request 7094 message other than the method and target URI, unless the variance 7095 cannot be crossed or the origin server has been deliberately 7096 configured to prevent cache transparency. For example, there is no 7097 need to send the Authorization field name in Vary because reuse 7098 across users is constrained by the field definition (Section 9.5.3). 7099 Likewise, an origin server might use Cache-Control response 7100 directives (Section 5.2 of [Caching]) to supplant Vary if it 7101 considers the variance less significant than the performance cost of 7102 Vary's impact on caching. 7104 11.2. Validators 7106 Validator header fields convey metadata about the selected 7107 representation (Section 7). In responses to safe requests, validator 7108 fields describe the selected representation chosen by the origin 7109 server while handling the response. Note that, depending on the 7110 status code semantics, the selected representation for a given 7111 response is not necessarily the same as the representation enclosed 7112 as response payload. 7114 In a successful response to a state-changing request, validator 7115 fields describe the new representation that has replaced the prior 7116 selected representation as a result of processing the request. 7118 For example, an ETag field in a 201 (Created) response communicates 7119 the entity-tag of the newly created resource's representation, so 7120 that it can be used in later conditional requests to prevent the 7121 "lost update" problem Section 9.2. 7123 +---------------+----------------+ 7124 | Field Name | Defined in... | 7125 | ETag | Section 11.2.3 | 7126 | Last-Modified | Section 11.2.2 | 7127 +---------------+----------------+ 7129 Table 18 7131 This specification defines two forms of metadata that are commonly 7132 used to observe resource state and test for preconditions: 7133 modification dates (Section 11.2.2) and opaque entity tags 7134 (Section 11.2.3). Additional metadata that reflects resource state 7135 has been defined by various extensions of HTTP, such as Web 7136 Distributed Authoring and Versioning (WebDAV, [RFC4918]), that are 7137 beyond the scope of this specification. A resource metadata value is 7138 referred to as a "validator" when it is used within a precondition. 7140 11.2.1. Weak versus Strong 7142 Validators come in two flavors: strong or weak. Weak validators are 7143 easy to generate but are far less useful for comparisons. Strong 7144 validators are ideal for comparisons but can be very difficult (and 7145 occasionally impossible) to generate efficiently. Rather than impose 7146 that all forms of resource adhere to the same strength of validator, 7147 HTTP exposes the type of validator in use and imposes restrictions on 7148 when weak validators can be used as preconditions. 7150 A "strong validator" is representation metadata that changes value 7151 whenever a change occurs to the representation data that would be 7152 observable in the payload body of a 200 (OK) response to GET. 7154 A strong validator might change for reasons other than a change to 7155 the representation data, such as when a semantically significant part 7156 of the representation metadata is changed (e.g., Content-Type), but 7157 it is in the best interests of the origin server to only change the 7158 value when it is necessary to invalidate the stored responses held by 7159 remote caches and authoring tools. 7161 Cache entries might persist for arbitrarily long periods, regardless 7162 of expiration times. Thus, a cache might attempt to validate an 7163 entry using a validator that it obtained in the distant past. A 7164 strong validator is unique across all versions of all representations 7165 associated with a particular resource over time. However, there is 7166 no implication of uniqueness across representations of different 7167 resources (i.e., the same strong validator might be in use for 7168 representations of multiple resources at the same time and does not 7169 imply that those representations are equivalent). 7171 There are a variety of strong validators used in practice. The best 7172 are based on strict revision control, wherein each change to a 7173 representation always results in a unique node name and revision 7174 identifier being assigned before the representation is made 7175 accessible to GET. A collision-resistant hash function applied to 7176 the representation data is also sufficient if the data is available 7177 prior to the response header fields being sent and the digest does 7178 not need to be recalculated every time a validation request is 7179 received. However, if a resource has distinct representations that 7180 differ only in their metadata, such as might occur with content 7181 negotiation over media types that happen to share the same data 7182 format, then the origin server needs to incorporate additional 7183 information in the validator to distinguish those representations. 7185 In contrast, a "weak validator" is representation metadata that might 7186 not change for every change to the representation data. This 7187 weakness might be due to limitations in how the value is calculated, 7188 such as clock resolution, an inability to ensure uniqueness for all 7189 possible representations of the resource, or a desire of the resource 7190 owner to group representations by some self-determined set of 7191 equivalency rather than unique sequences of data. An origin server 7192 SHOULD change a weak entity-tag whenever it considers prior 7193 representations to be unacceptable as a substitute for the current 7194 representation. In other words, a weak entity-tag ought to change 7195 whenever the origin server wants caches to invalidate old responses. 7197 For example, the representation of a weather report that changes in 7198 content every second, based on dynamic measurements, might be grouped 7199 into sets of equivalent representations (from the origin server's 7200 perspective) with the same weak validator in order to allow cached 7201 representations to be valid for a reasonable period of time (perhaps 7202 adjusted dynamically based on server load or weather quality). 7203 Likewise, a representation's modification time, if defined with only 7204 one-second resolution, might be a weak validator if it is possible 7205 for the representation to be modified twice during a single second 7206 and retrieved between those modifications. 7208 Likewise, a validator is weak if it is shared by two or more 7209 representations of a given resource at the same time, unless those 7210 representations have identical representation data. For example, if 7211 the origin server sends the same validator for a representation with 7212 a gzip content coding applied as it does for a representation with no 7213 content coding, then that validator is weak. However, two 7214 simultaneous representations might share the same strong validator if 7215 they differ only in the representation metadata, such as when two 7216 different media types are available for the same representation data. 7218 Strong validators are usable for all conditional requests, including 7219 cache validation, partial content ranges, and "lost update" 7220 avoidance. Weak validators are only usable when the client does not 7221 require exact equality with previously obtained representation data, 7222 such as when validating a cache entry or limiting a web traversal to 7223 recent changes. 7225 11.2.2. Last-Modified 7227 The "Last-Modified" header field in a response provides a timestamp 7228 indicating the date and time at which the origin server believes the 7229 selected representation was last modified, as determined at the 7230 conclusion of handling the request. 7232 Last-Modified = HTTP-date 7234 An example of its use is 7236 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 7238 11.2.2.1. Generation 7240 An origin server SHOULD send Last-Modified for any selected 7241 representation for which a last modification date can be reasonably 7242 and consistently determined, since its use in conditional requests 7243 and evaluating cache freshness ([Caching]) results in a substantial 7244 reduction of HTTP traffic on the Internet and can be a significant 7245 factor in improving service scalability and reliability. 7247 A representation is typically the sum of many parts behind the 7248 resource interface. The last-modified time would usually be the most 7249 recent time that any of those parts were changed. How that value is 7250 determined for any given resource is an implementation detail beyond 7251 the scope of this specification. What matters to HTTP is how 7252 recipients of the Last-Modified header field can use its value to 7253 make conditional requests and test the validity of locally cached 7254 responses. 7256 An origin server SHOULD obtain the Last-Modified value of the 7257 representation as close as possible to the time that it generates the 7258 Date field value for its response. This allows a recipient to make 7259 an accurate assessment of the representation's modification time, 7260 especially if the representation changes near the time that the 7261 response is generated. 7263 An origin server with a clock MUST NOT send a Last-Modified date that 7264 is later than the server's time of message origination (Date). If 7265 the last modification time is derived from implementation-specific 7266 metadata that evaluates to some time in the future, according to the 7267 origin server's clock, then the origin server MUST replace that value 7268 with the message origination date. This prevents a future 7269 modification date from having an adverse impact on cache validation. 7271 An origin server without a clock MUST NOT assign Last-Modified values 7272 to a response unless these values were associated with the resource 7273 by some other system or user with a reliable clock. 7275 11.2.2.2. Comparison 7277 A Last-Modified time, when used as a validator in a request, is 7278 implicitly weak unless it is possible to deduce that it is strong, 7279 using the following rules: 7281 o The validator is being compared by an origin server to the actual 7282 current validator for the representation and, 7284 o That origin server reliably knows that the associated 7285 representation did not change twice during the second covered by 7286 the presented validator. 7288 or 7290 o The validator is about to be used by a client in an 7291 If-Modified-Since, If-Unmodified-Since, or If-Range header field, 7292 because the client has a cache entry for the associated 7293 representation, and 7295 o That cache entry includes a Date value, which gives the time when 7296 the origin server sent the original response, and 7298 o The presented Last-Modified time is at least 60 seconds before the 7299 Date value. 7301 or 7303 o The validator is being compared by an intermediate cache to the 7304 validator stored in its cache entry for the representation, and 7306 o That cache entry includes a Date value, which gives the time when 7307 the origin server sent the original response, and 7309 o The presented Last-Modified time is at least 60 seconds before the 7310 Date value. 7312 This method relies on the fact that if two different responses were 7313 sent by the origin server during the same second, but both had the 7314 same Last-Modified time, then at least one of those responses would 7315 have a Date value equal to its Last-Modified time. The arbitrary 7316 60-second limit guards against the possibility that the Date and 7317 Last-Modified values are generated from different clocks or at 7318 somewhat different times during the preparation of the response. An 7319 implementation MAY use a value larger than 60 seconds, if it is 7320 believed that 60 seconds is too short. 7322 11.2.3. ETag 7324 The "ETag" field in a response provides the current entity-tag for 7325 the selected representation, as determined at the conclusion of 7326 handling the request. An entity-tag is an opaque validator for 7327 differentiating between multiple representations of the same 7328 resource, regardless of whether those multiple representations are 7329 due to resource state changes over time, content negotiation 7330 resulting in multiple representations being valid at the same time, 7331 or both. An entity-tag consists of an opaque quoted string, possibly 7332 prefixed by a weakness indicator. 7334 ETag = entity-tag 7336 entity-tag = [ weak ] opaque-tag 7337 weak = %s"W/" 7338 opaque-tag = DQUOTE *etagc DQUOTE 7339 etagc = %x21 / %x23-7E / obs-text 7340 ; VCHAR except double quotes, plus obs-text 7342 | *Note:* Previously, opaque-tag was defined to be a quoted- 7343 | string ([RFC2616], Section 3.11); thus, some recipients might 7344 | perform backslash unescaping. Servers therefore ought to avoid 7345 | backslash characters in entity tags. 7347 An entity-tag can be more reliable for validation than a modification 7348 date in situations where it is inconvenient to store modification 7349 dates, where the one-second resolution of HTTP date values is not 7350 sufficient, or where modification dates are not consistently 7351 maintained. 7353 Examples: 7355 ETag: "xyzzy" 7356 ETag: W/"xyzzy" 7357 ETag: "" 7359 An entity-tag can be either a weak or strong validator, with strong 7360 being the default. If an origin server provides an entity-tag for a 7361 representation and the generation of that entity-tag does not satisfy 7362 all of the characteristics of a strong validator (Section 11.2.1), 7363 then the origin server MUST mark the entity-tag as weak by prefixing 7364 its opaque value with "W/" (case-sensitive). 7366 A sender MAY send the Etag field in a trailer section (see 7367 Section 5.6). However, since trailers are often ignored, it is 7368 preferable to send Etag as a header field unless the entity-tag is 7369 generated while sending the message body. 7371 11.2.3.1. Generation 7373 The principle behind entity-tags is that only the service author 7374 knows the implementation of a resource well enough to select the most 7375 accurate and efficient validation mechanism for that resource, and 7376 that any such mechanism can be mapped to a simple sequence of octets 7377 for easy comparison. Since the value is opaque, there is no need for 7378 the client to be aware of how each entity-tag is constructed. 7380 For example, a resource that has implementation-specific versioning 7381 applied to all changes might use an internal revision number, perhaps 7382 combined with a variance identifier for content negotiation, to 7383 accurately differentiate between representations. Other 7384 implementations might use a collision-resistant hash of 7385 representation content, a combination of various file attributes, or 7386 a modification timestamp that has sub-second resolution. 7388 An origin server SHOULD send an ETag for any selected representation 7389 for which detection of changes can be reasonably and consistently 7390 determined, since the entity-tag's use in conditional requests and 7391 evaluating cache freshness ([Caching]) can result in a substantial 7392 reduction of HTTP network traffic and can be a significant factor in 7393 improving service scalability and reliability. 7395 11.2.3.2. Comparison 7397 There are two entity-tag comparison functions, depending on whether 7398 or not the comparison context allows the use of weak validators: 7400 o Strong comparison: two entity-tags are equivalent if both are not 7401 weak and their opaque-tags match character-by-character. 7403 o Weak comparison: two entity-tags are equivalent if their opaque- 7404 tags match character-by-character, regardless of either or both 7405 being tagged as "weak". 7407 The example below shows the results for a set of entity-tag pairs and 7408 both the weak and strong comparison function results: 7410 +--------+--------+-------------------+-----------------+ 7411 | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | 7412 | W/"1" | W/"1" | no match | match | 7413 | W/"1" | W/"2" | no match | no match | 7414 | W/"1" | "1" | no match | match | 7415 | "1" | "1" | match | match | 7416 +--------+--------+-------------------+-----------------+ 7418 Table 19 7420 11.2.3.3. Example: Entity-Tags Varying on Content-Negotiated Resources 7422 Consider a resource that is subject to content negotiation 7423 (Section 7.4), and where the representations sent in response to a 7424 GET request vary based on the Accept-Encoding request header field 7425 (Section 9.4.3): 7427 >> Request: 7429 GET /index HTTP/1.1 7430 Host: www.example.com 7431 Accept-Encoding: gzip 7433 In this case, the response might or might not use the gzip content 7434 coding. If it does not, the response might look like: 7436 >> Response: 7438 HTTP/1.1 200 OK 7439 Date: Fri, 26 Mar 2010 00:05:00 GMT 7440 ETag: "123-a" 7441 Content-Length: 70 7442 Vary: Accept-Encoding 7443 Content-Type: text/plain 7445 Hello World! 7446 Hello World! 7447 Hello World! 7448 Hello World! 7449 Hello World! 7451 An alternative representation that does use gzip content coding would 7452 be: 7454 >> Response: 7456 HTTP/1.1 200 OK 7457 Date: Fri, 26 Mar 2010 00:05:00 GMT 7458 ETag: "123-b" 7459 Content-Length: 43 7460 Vary: Accept-Encoding 7461 Content-Type: text/plain 7462 Content-Encoding: gzip 7464 ...binary data... 7466 | *Note:* Content codings are a property of the representation 7467 | data, so a strong entity-tag for a content-encoded 7468 | representation has to be distinct from the entity tag of an 7469 | unencoded representation to prevent potential conflicts during 7470 | cache updates and range requests. In contrast, transfer 7471 | codings (Section 7 of [Messaging]) apply only during message 7472 | transfer and do not result in distinct entity-tags. 7474 11.2.4. When to Use Entity-Tags and Last-Modified Dates 7476 In 200 (OK) responses to GET or HEAD, an origin server: 7478 o SHOULD send an entity-tag validator unless it is not feasible to 7479 generate one. 7481 o MAY send a weak entity-tag instead of a strong entity-tag, if 7482 performance considerations support the use of weak entity-tags, or 7483 if it is unfeasible to send a strong entity-tag. 7485 o SHOULD send a Last-Modified value if it is feasible to send one. 7487 In other words, the preferred behavior for an origin server is to 7488 send both a strong entity-tag and a Last-Modified value in successful 7489 responses to a retrieval request. 7491 A client: 7493 o MUST send that entity-tag in any cache validation request (using 7494 If-Match or If-None-Match) if an entity-tag has been provided by 7495 the origin server. 7497 o SHOULD send the Last-Modified value in non-subrange cache 7498 validation requests (using If-Modified-Since) if only a Last- 7499 Modified value has been provided by the origin server. 7501 o MAY send the Last-Modified value in subrange cache validation 7502 requests (using If-Unmodified-Since) if only a Last-Modified value 7503 has been provided by an HTTP/1.0 origin server. The user agent 7504 SHOULD provide a way to disable this, in case of difficulty. 7506 o SHOULD send both validators in cache validation requests if both 7507 an entity-tag and a Last-Modified value have been provided by the 7508 origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to 7509 respond appropriately. 7511 11.3. Authentication Challenges 7513 Authentication challenges indicate what mechanisms are available for 7514 the client to provide authentication credentials in future requests. 7516 +--------------------+----------------+ 7517 | Field Name | Defined in... | 7518 | WWW-Authenticate | Section 11.3.1 | 7519 | Proxy-Authenticate | Section 11.3.2 | 7520 +--------------------+----------------+ 7522 Table 20 7524 Furthermore, the "Authentication-Info" and "Proxy-Authentication- 7525 Info" response header fields are defined for use in authentication 7526 schemes that need to return information once the client's 7527 authentication credentials have been accepted. 7529 +---------------------------+----------------+ 7530 | Field Name | Defined in... | 7531 | Authentication-Info | Section 11.3.3 | 7532 | Proxy-Authentication-Info | Section 11.3.4 | 7533 +---------------------------+----------------+ 7535 Table 21 7537 11.3.1. WWW-Authenticate 7539 The "WWW-Authenticate" header field indicates the authentication 7540 scheme(s) and parameters applicable to the target resource. 7542 WWW-Authenticate = 1#challenge 7544 A server generating a 401 (Unauthorized) response MUST send a WWW- 7545 Authenticate header field containing at least one challenge. A 7546 server MAY generate a WWW-Authenticate header field in other response 7547 messages to indicate that supplying credentials (or different 7548 credentials) might affect the response. 7550 A proxy forwarding a response MUST NOT modify any WWW-Authenticate 7551 fields in that response. 7553 User agents are advised to take special care in parsing the field 7554 value, as it might contain more than one challenge, and each 7555 challenge can contain a comma-separated list of authentication 7556 parameters. Furthermore, the header field itself can occur multiple 7557 times. 7559 For instance: 7561 WWW-Authenticate: Newauth realm="apps", type=1, 7562 title="Login to \"apps\"", Basic realm="simple" 7564 This header field contains two challenges; one for the "Newauth" 7565 scheme with a realm value of "apps", and two additional parameters 7566 "type" and "title", and another one for the "Basic" scheme with a 7567 realm value of "simple". 7569 | *Note:* The challenge grammar production uses the list syntax 7570 | as well. Therefore, a sequence of comma, whitespace, and comma 7571 | can be considered either as applying to the preceding 7572 | challenge, or to be an empty entry in the list of challenges. 7573 | In practice, this ambiguity does not affect the semantics of 7574 | the header field value and thus is harmless. 7576 11.3.2. Proxy-Authenticate 7578 The "Proxy-Authenticate" header field consists of at least one 7579 challenge that indicates the authentication scheme(s) and parameters 7580 applicable to the proxy for this request. A proxy MUST send at least 7581 one Proxy-Authenticate header field in each 407 (Proxy Authentication 7582 Required) response that it generates. 7584 Proxy-Authenticate = 1#challenge 7586 Unlike WWW-Authenticate, the Proxy-Authenticate header field applies 7587 only to the next outbound client on the response chain. This is 7588 because only the client that chose a given proxy is likely to have 7589 the credentials necessary for authentication. However, when multiple 7590 proxies are used within the same administrative domain, such as 7591 office and regional caching proxies within a large corporate network, 7592 it is common for credentials to be generated by the user agent and 7593 passed through the hierarchy until consumed. Hence, in such a 7594 configuration, it will appear as if Proxy-Authenticate is being 7595 forwarded because each proxy will send the same challenge set. 7597 Note that the parsing considerations for WWW-Authenticate apply to 7598 this header field as well; see Section 11.3.1 for details. 7600 11.3.3. Authentication-Info 7602 HTTP authentication schemes can use the Authentication-Info response 7603 header field to communicate information after the client's 7604 authentication credentials have been accepted. This information can 7605 include a finalization message from the server (e.g., it can contain 7606 the server authentication). 7608 The field value is a list of parameters (name/value pairs), using the 7609 "auth-param" syntax defined in Section 9.5.1. This specification 7610 only describes the generic format; authentication schemes using 7611 Authentication-Info will define the individual parameters. The 7612 "Digest" Authentication Scheme, for instance, defines multiple 7613 parameters in Section 3.5 of [RFC7616]. 7615 Authentication-Info = #auth-param 7617 The Authentication-Info header field can be used in any HTTP 7618 response, independently of request method and status code. Its 7619 semantics are defined by the authentication scheme indicated by the 7620 Authorization header field (Section 9.5.3) of the corresponding 7621 request. 7623 A proxy forwarding a response is not allowed to modify the field 7624 value in any way. 7626 Authentication-Info can be used inside trailers (Section 5.6) when 7627 the authentication scheme explicitly allows this. 7629 11.3.3.1. Parameter Value Format 7631 Parameter values can be expressed either as "token" or as "quoted- 7632 string" (Section 5.4.1). 7634 Authentication scheme definitions need to allow both notations, both 7635 for senders and recipients. This allows recipients to use generic 7636 parsing components, independent of the authentication scheme in use. 7638 For backwards compatibility, authentication scheme definitions can 7639 restrict the format for senders to one of the two variants. This can 7640 be important when it is known that deployed implementations will fail 7641 when encountering one of the two formats. 7643 11.3.4. Proxy-Authentication-Info 7645 The Proxy-Authentication-Info response header field is equivalent to 7646 Authentication-Info, except that it applies to proxy authentication 7647 (Section 9.5.1) and its semantics are defined by the authentication 7648 scheme indicated by the Proxy-Authorization header field 7649 (Section 9.5.4) of the corresponding request: 7651 Proxy-Authentication-Info = #auth-param 7653 However, unlike Authentication-Info, the Proxy-Authentication-Info 7654 header field applies only to the next outbound client on the response 7655 chain. This is because only the client that chose a given proxy is 7656 likely to have the credentials necessary for authentication. 7657 However, when multiple proxies are used within the same 7658 administrative domain, such as office and regional caching proxies 7659 within a large corporate network, it is common for credentials to be 7660 generated by the user agent and passed through the hierarchy until 7661 consumed. Hence, in such a configuration, it will appear as if 7662 Proxy-Authentication-Info is being forwarded because each proxy will 7663 send the same field value. 7665 11.4. Response Context 7667 The remaining response header fields provide more information about 7668 the target resource for potential use in later requests. 7670 +---------------+----------------+ 7671 | Field Name | Defined in... | 7672 | Accept-Ranges | Section 11.4.1 | 7673 | Allow | Section 11.4.2 | 7674 | Server | Section 11.4.3 | 7675 +---------------+----------------+ 7677 Table 22 7679 11.4.1. Accept-Ranges 7681 The "Accept-Ranges" header field allows a server to indicate that it 7682 supports range requests for the target resource. 7684 Accept-Ranges = acceptable-ranges 7685 acceptable-ranges = 1#range-unit / "none" 7687 An origin server that supports byte-range requests for a given target 7688 resource MAY send 7690 Accept-Ranges: bytes 7692 to indicate what range units are supported. A client MAY generate 7693 range requests without having received this header field for the 7694 resource involved. Range units are defined in Section 7.1.4. 7696 A server that does not support any kind of range request for the 7697 target resource MAY send 7699 Accept-Ranges: none 7701 to advise the client not to attempt a range request. 7703 11.4.2. Allow 7705 The "Allow" header field lists the set of methods advertised as 7706 supported by the target resource. The purpose of this field is 7707 strictly to inform the recipient of valid request methods associated 7708 with the resource. 7710 Allow = #method 7712 Example of use: 7714 Allow: GET, HEAD, PUT 7716 The actual set of allowed methods is defined by the origin server at 7717 the time of each request. An origin server MUST generate an Allow 7718 field in a 405 (Method Not Allowed) response and MAY do so in any 7719 other response. An empty Allow field value indicates that the 7720 resource allows no methods, which might occur in a 405 response if 7721 the resource has been temporarily disabled by configuration. 7723 A proxy MUST NOT modify the Allow header field - it does not need to 7724 understand all of the indicated methods in order to handle them 7725 according to the generic message handling rules. 7727 11.4.3. Server 7729 The "Server" header field contains information about the software 7730 used by the origin server to handle the request, which is often used 7731 by clients to help identify the scope of reported interoperability 7732 problems, to work around or tailor requests to avoid particular 7733 server limitations, and for analytics regarding server or operating 7734 system use. An origin server MAY generate a Server field in its 7735 responses. 7737 Server = product *( RWS ( product / comment ) ) 7739 The Server field value consists of one or more product identifiers, 7740 each followed by zero or more comments (Section 5.4.1.3), which 7741 together identify the origin server software and its significant 7742 subproducts. By convention, the product identifiers are listed in 7743 decreasing order of their significance for identifying the origin 7744 server software. Each product identifier consists of a name and 7745 optional version, as defined in Section 9.6.3. 7747 Example: 7749 Server: CERN/3.0 libwww/2.17 7751 An origin server SHOULD NOT generate a Server field containing 7752 needlessly fine-grained detail and SHOULD limit the addition of 7753 subproducts by third parties. Overly long and detailed Server field 7754 values increase response latency and potentially reveal internal 7755 implementation details that might make it (slightly) easier for 7756 attackers to find and exploit known security holes. 7758 12. Security Considerations 7760 This section is meant to inform developers, information providers, 7761 and users of known security concerns relevant to HTTP semantics and 7762 its use for transferring information over the Internet. 7763 Considerations related to message syntax, parsing, and routing are 7764 discussed in Section 11 of [Messaging]. 7766 The list of considerations below is not exhaustive. Most security 7767 concerns related to HTTP semantics are about securing server-side 7768 applications (code behind the HTTP interface), securing user agent 7769 processing of payloads received via HTTP, or secure use of the 7770 Internet in general, rather than security of the protocol. Various 7771 organizations maintain topical information and links to current 7772 research on Web application security (e.g., [OWASP]). 7774 12.1. Establishing Authority 7776 HTTP relies on the notion of an authoritative response: a response 7777 that has been determined by (or at the direction of) the origin 7778 server identified within the target URI to be the most appropriate 7779 response for that request given the state of the target resource at 7780 the time of response message origination. 7782 When a registered name is used in the authority component, the "http" 7783 URI scheme (Section 2.5.1) relies on the user's local name resolution 7784 service to determine where it can find authoritative responses. This 7785 means that any attack on a user's network host table, cached names, 7786 or name resolution libraries becomes an avenue for attack on 7787 establishing authority for "http" URIs. Likewise, the user's choice 7788 of server for Domain Name Service (DNS), and the hierarchy of servers 7789 from which it obtains resolution results, could impact the 7790 authenticity of address mappings; DNS Security Extensions (DNSSEC, 7791 [RFC4033]) are one way to improve authenticity. 7793 Furthermore, after an IP address is obtained, establishing authority 7794 for an "http" URI is vulnerable to attacks on Internet Protocol 7795 routing. 7797 The "https" scheme (Section 2.5.2) is intended to prevent (or at 7798 least reveal) many of these potential attacks on establishing 7799 authority, provided that the negotiated TLS connection is secured and 7800 the client properly verifies that the communicating server's identity 7801 matches the target URI's authority component (Section 6.4.3.1). 7802 Correctly implementing such verification can be difficult (see 7803 [Georgiev]). 7805 Authority for a given origin server can be delegated through protocol 7806 extensions; for example, [RFC7838]. Likewise, the set of servers 7807 that a connection is considered authoritative for can be changed with 7808 a protocol extension like [RFC8336]. 7810 Providing a response from a non-authoritative source, such as a 7811 shared proxy cache, is often useful to improve performance and 7812 availability, but only to the extent that the source can be trusted 7813 or the distrusted response can be safely used. 7815 Unfortunately, communicating authority to users can be difficult. 7816 For example, phishing is an attack on the user's perception of 7817 authority, where that perception can be misled by presenting similar 7818 branding in hypertext, possibly aided by userinfo obfuscating the 7819 authority component (see Section 2.5.1). User agents can reduce the 7820 impact of phishing attacks by enabling users to easily inspect a 7821 target URI prior to making an action, by prominently distinguishing 7822 (or rejecting) userinfo when present, and by not sending stored 7823 credentials and cookies when the referring document is from an 7824 unknown or untrusted source. 7826 12.2. Risks of Intermediaries 7828 By their very nature, HTTP intermediaries are men-in-the-middle and, 7829 thus, represent an opportunity for man-in-the-middle attacks. 7830 Compromise of the systems on which the intermediaries run can result 7831 in serious security and privacy problems. Intermediaries might have 7832 access to security-related information, personal information about 7833 individual users and organizations, and proprietary information 7834 belonging to users and content providers. A compromised 7835 intermediary, or an intermediary implemented or configured without 7836 regard to security and privacy considerations, might be used in the 7837 commission of a wide range of potential attacks. 7839 Intermediaries that contain a shared cache are especially vulnerable 7840 to cache poisoning attacks, as described in Section 7 of [Caching]. 7842 Implementers need to consider the privacy and security implications 7843 of their design and coding decisions, and of the configuration 7844 options they provide to operators (especially the default 7845 configuration). 7847 Users need to be aware that intermediaries are no more trustworthy 7848 than the people who run them; HTTP itself cannot solve this problem. 7850 12.3. Attacks Based on File and Path Names 7852 Origin servers frequently make use of their local file system to 7853 manage the mapping from target URI to resource representations. Most 7854 file systems are not designed to protect against malicious file or 7855 path names. Therefore, an origin server needs to avoid accessing 7856 names that have a special significance to the system when mapping the 7857 target resource to files, folders, or directories. 7859 For example, UNIX, Microsoft Windows, and other operating systems use 7860 ".." as a path component to indicate a directory level above the 7861 current one, and they use specially named paths or file names to send 7862 data to system devices. Similar naming conventions might exist 7863 within other types of storage systems. Likewise, local storage 7864 systems have an annoying tendency to prefer user-friendliness over 7865 security when handling invalid or unexpected characters, 7866 recomposition of decomposed characters, and case-normalization of 7867 case-insensitive names. 7869 Attacks based on such special names tend to focus on either denial- 7870 of-service (e.g., telling the server to read from a COM port) or 7871 disclosure of configuration and source files that are not meant to be 7872 served. 7874 12.4. Attacks Based on Command, Code, or Query Injection 7876 Origin servers often use parameters within the URI as a means of 7877 identifying system services, selecting database entries, or choosing 7878 a data source. However, data received in a request cannot be 7879 trusted. An attacker could construct any of the request data 7880 elements (method, target URI, header fields, or body) to contain data 7881 that might be misinterpreted as a command, code, or query when passed 7882 through a command invocation, language interpreter, or database 7883 interface. 7885 For example, SQL injection is a common attack wherein additional 7886 query language is inserted within some part of the target URI or 7887 header fields (e.g., Host, Referer, etc.). If the received data is 7888 used directly within a SELECT statement, the query language might be 7889 interpreted as a database command instead of a simple string value. 7890 This type of implementation vulnerability is extremely common, in 7891 spite of being easy to prevent. 7893 In general, resource implementations ought to avoid use of request 7894 data in contexts that are processed or interpreted as instructions. 7895 Parameters ought to be compared to fixed strings and acted upon as a 7896 result of that comparison, rather than passed through an interface 7897 that is not prepared for untrusted data. Received data that isn't 7898 based on fixed parameters ought to be carefully filtered or encoded 7899 to avoid being misinterpreted. 7901 Similar considerations apply to request data when it is stored and 7902 later processed, such as within log files, monitoring tools, or when 7903 included within a data format that allows embedded scripts. 7905 12.5. Attacks via Protocol Element Length 7907 Because HTTP uses mostly textual, character-delimited fields, parsers 7908 are often vulnerable to attacks based on sending very long (or very 7909 slow) streams of data, particularly where an implementation is 7910 expecting a protocol element with no predefined length (Section 3.3). 7912 To promote interoperability, specific recommendations are made for 7913 minimum size limits on request-line (Section 3 of [Messaging]) and 7914 fields (Section 5). These are minimum recommendations, chosen to be 7915 supportable even by implementations with limited resources; it is 7916 expected that most implementations will choose substantially higher 7917 limits. 7919 A server can reject a message that has a target URI that is too long 7920 (Section 10.5.15) or a request payload that is too large 7921 (Section 10.5.14). Additional status codes related to capacity 7922 limits have been defined by extensions to HTTP [RFC6585]. 7924 Recipients ought to carefully limit the extent to which they process 7925 other protocol elements, including (but not limited to) request 7926 methods, response status phrases, field names, numeric values, and 7927 body chunks. Failure to limit such processing can result in buffer 7928 overflows, arithmetic overflows, or increased vulnerability to 7929 denial-of-service attacks. 7931 12.6. Disclosure of Personal Information 7933 Clients are often privy to large amounts of personal information, 7934 including both information provided by the user to interact with 7935 resources (e.g., the user's name, location, mail address, passwords, 7936 encryption keys, etc.) and information about the user's browsing 7937 activity over time (e.g., history, bookmarks, etc.). Implementations 7938 need to prevent unintentional disclosure of personal information. 7940 12.7. Privacy of Server Log Information 7942 A server is in the position to save personal data about a user's 7943 requests over time, which might identify their reading patterns or 7944 subjects of interest. In particular, log information gathered at an 7945 intermediary often contains a history of user agent interaction, 7946 across a multitude of sites, that can be traced to individual users. 7948 HTTP log information is confidential in nature; its handling is often 7949 constrained by laws and regulations. Log information needs to be 7950 securely stored and appropriate guidelines followed for its analysis. 7951 Anonymization of personal information within individual entries 7952 helps, but it is generally not sufficient to prevent real log traces 7953 from being re-identified based on correlation with other access 7954 characteristics. As such, access traces that are keyed to a specific 7955 client are unsafe to publish even if the key is pseudonymous. 7957 To minimize the risk of theft or accidental publication, log 7958 information ought to be purged of personally identifiable 7959 information, including user identifiers, IP addresses, and user- 7960 provided query parameters, as soon as that information is no longer 7961 necessary to support operational needs for security, auditing, or 7962 fraud control. 7964 12.8. Disclosure of Sensitive Information in URIs 7966 URIs are intended to be shared, not secured, even when they identify 7967 secure resources. URIs are often shown on displays, added to 7968 templates when a page is printed, and stored in a variety of 7969 unprotected bookmark lists. It is therefore unwise to include 7970 information within a URI that is sensitive, personally identifiable, 7971 or a risk to disclose. 7973 Authors of services ought to avoid GET-based forms for the submission 7974 of sensitive data because that data will be placed in the target URI. 7975 Many existing servers, proxies, and user agents log or display the 7976 target URI in places where it might be visible to third parties. 7977 Such services ought to use POST-based form submission instead. 7979 Since the Referer header field tells a target site about the context 7980 that resulted in a request, it has the potential to reveal 7981 information about the user's immediate browsing history and any 7982 personal information that might be found in the referring resource's 7983 URI. Limitations on the Referer header field are described in 7984 Section 9.6.2 to address some of its security considerations. 7986 12.9. Disclosure of Fragment after Redirects 7988 Although fragment identifiers used within URI references are not sent 7989 in requests, implementers ought to be aware that they will be visible 7990 to the user agent and any extensions or scripts running as a result 7991 of the response. In particular, when a redirect occurs and the 7992 original request's fragment identifier is inherited by the new 7993 reference in Location (Section 11.1.2), this might have the effect of 7994 disclosing one site's fragment to another site. If the first site 7995 uses personal information in fragments, it ought to ensure that 7996 redirects to other sites include a (possibly empty) fragment 7997 component in order to block that inheritance. 7999 12.10. Disclosure of Product Information 8001 The User-Agent (Section 9.6.3), Via (Section 6.7.1), and Server 8002 (Section 11.4.3) header fields often reveal information about the 8003 respective sender's software systems. In theory, this can make it 8004 easier for an attacker to exploit known security holes; in practice, 8005 attackers tend to try all potential holes regardless of the apparent 8006 software versions being used. 8008 Proxies that serve as a portal through a network firewall ought to 8009 take special precautions regarding the transfer of header information 8010 that might identify hosts behind the firewall. The Via header field 8011 allows intermediaries to replace sensitive machine names with 8012 pseudonyms. 8014 12.11. Browser Fingerprinting 8016 Browser fingerprinting is a set of techniques for identifying a 8017 specific user agent over time through its unique set of 8018 characteristics. These characteristics might include information 8019 related to its TCP behavior, feature capabilities, and scripting 8020 environment, though of particular interest here is the set of unique 8021 characteristics that might be communicated via HTTP. Fingerprinting 8022 is considered a privacy concern because it enables tracking of a user 8023 agent's behavior over time ([Bujlow]) without the corresponding 8024 controls that the user might have over other forms of data collection 8025 (e.g., cookies). Many general-purpose user agents (i.e., Web 8026 browsers) have taken steps to reduce their fingerprints. 8028 There are a number of request header fields that might reveal 8029 information to servers that is sufficiently unique to enable 8030 fingerprinting. The From header field is the most obvious, though it 8031 is expected that From will only be sent when self-identification is 8032 desired by the user. Likewise, Cookie header fields are deliberately 8033 designed to enable re-identification, so fingerprinting concerns only 8034 apply to situations where cookies are disabled or restricted by the 8035 user agent's configuration. 8037 The User-Agent header field might contain enough information to 8038 uniquely identify a specific device, usually when combined with other 8039 characteristics, particularly if the user agent sends excessive 8040 details about the user's system or extensions. However, the source 8041 of unique information that is least expected by users is proactive 8042 negotiation (Section 9.4), including the Accept, Accept-Charset, 8043 Accept-Encoding, and Accept-Language header fields. 8045 In addition to the fingerprinting concern, detailed use of the 8046 Accept-Language header field can reveal information the user might 8047 consider to be of a private nature. For example, understanding a 8048 given language set might be strongly correlated to membership in a 8049 particular ethnic group. An approach that limits such loss of 8050 privacy would be for a user agent to omit the sending of Accept- 8051 Language except for sites that have been whitelisted, perhaps via 8052 interaction after detecting a Vary header field that indicates 8053 language negotiation might be useful. 8055 In environments where proxies are used to enhance privacy, user 8056 agents ought to be conservative in sending proactive negotiation 8057 header fields. General-purpose user agents that provide a high 8058 degree of header field configurability ought to inform users about 8059 the loss of privacy that might result if too much detail is provided. 8060 As an extreme privacy measure, proxies could filter the proactive 8061 negotiation header fields in relayed requests. 8063 12.12. Validator Retention 8065 The validators defined by this specification are not intended to 8066 ensure the validity of a representation, guard against malicious 8067 changes, or detect man-in-the-middle attacks. At best, they enable 8068 more efficient cache updates and optimistic concurrent writes when 8069 all participants are behaving nicely. At worst, the conditions will 8070 fail and the client will receive a response that is no more harmful 8071 than an HTTP exchange without conditional requests. 8073 An entity-tag can be abused in ways that create privacy risks. For 8074 example, a site might deliberately construct a semantically invalid 8075 entity-tag that is unique to the user or user agent, send it in a 8076 cacheable response with a long freshness time, and then read that 8077 entity-tag in later conditional requests as a means of re-identifying 8078 that user or user agent. Such an identifying tag would become a 8079 persistent identifier for as long as the user agent retained the 8080 original cache entry. User agents that cache representations ought 8081 to ensure that the cache is cleared or replaced whenever the user 8082 performs privacy-maintaining actions, such as clearing stored cookies 8083 or changing to a private browsing mode. 8085 12.13. Denial-of-Service Attacks Using Range 8087 Unconstrained multiple range requests are susceptible to denial-of- 8088 service attacks because the effort required to request many 8089 overlapping ranges of the same data is tiny compared to the time, 8090 memory, and bandwidth consumed by attempting to serve the requested 8091 data in many parts. Servers ought to ignore, coalesce, or reject 8092 egregious range requests, such as requests for more than two 8093 overlapping ranges or for many small ranges in a single set, 8094 particularly when the ranges are requested out of order for no 8095 apparent reason. Multipart range requests are not designed to 8096 support random access. 8098 12.14. Authentication Considerations 8100 Everything about the topic of HTTP authentication is a security 8101 consideration, so the list of considerations below is not exhaustive. 8102 Furthermore, it is limited to security considerations regarding the 8103 authentication framework, in general, rather than discussing all of 8104 the potential considerations for specific authentication schemes 8105 (which ought to be documented in the specifications that define those 8106 schemes). Various organizations maintain topical information and 8107 links to current research on Web application security (e.g., 8108 [OWASP]), including common pitfalls for implementing and using the 8109 authentication schemes found in practice. 8111 12.14.1. Confidentiality of Credentials 8113 The HTTP authentication framework does not define a single mechanism 8114 for maintaining the confidentiality of credentials; instead, each 8115 authentication scheme defines how the credentials are encoded prior 8116 to transmission. While this provides flexibility for the development 8117 of future authentication schemes, it is inadequate for the protection 8118 of existing schemes that provide no confidentiality on their own, or 8119 that do not sufficiently protect against replay attacks. 8120 Furthermore, if the server expects credentials that are specific to 8121 each individual user, the exchange of those credentials will have the 8122 effect of identifying that user even if the content within 8123 credentials remains confidential. 8125 HTTP depends on the security properties of the underlying transport- 8126 or session-level connection to provide confidential transmission of 8127 fields. In other words, if a server limits access to authenticated 8128 users using this framework, the server needs to ensure that the 8129 connection is properly secured in accordance with the nature of the 8130 authentication scheme used. For example, services that depend on 8131 individual user authentication often require a connection to be 8132 secured with TLS ("Transport Layer Security", [RFC8446]) prior to 8133 exchanging any credentials. 8135 12.14.2. Credentials and Idle Clients 8137 Existing HTTP clients and user agents typically retain authentication 8138 information indefinitely. HTTP does not provide a mechanism for the 8139 origin server to direct clients to discard these cached credentials, 8140 since the protocol has no awareness of how credentials are obtained 8141 or managed by the user agent. The mechanisms for expiring or 8142 revoking credentials can be specified as part of an authentication 8143 scheme definition. 8145 Circumstances under which credential caching can interfere with the 8146 application's security model include but are not limited to: 8148 o Clients that have been idle for an extended period, following 8149 which the server might wish to cause the client to re-prompt the 8150 user for credentials. 8152 o Applications that include a session termination indication (such 8153 as a "logout" or "commit" button on a page) after which the server 8154 side of the application "knows" that there is no further reason 8155 for the client to retain the credentials. 8157 User agents that cache credentials are encouraged to provide a 8158 readily accessible mechanism for discarding cached credentials under 8159 user control. 8161 12.14.3. Protection Spaces 8163 Authentication schemes that solely rely on the "realm" mechanism for 8164 establishing a protection space will expose credentials to all 8165 resources on an origin server. Clients that have successfully made 8166 authenticated requests with a resource can use the same 8167 authentication credentials for other resources on the same origin 8168 server. This makes it possible for a different resource to harvest 8169 authentication credentials for other resources. 8171 This is of particular concern when an origin server hosts resources 8172 for multiple parties under the same canonical root URI 8173 (Section 9.5.2). Possible mitigation strategies include restricting 8174 direct access to authentication credentials (i.e., not making the 8175 content of the Authorization request header field available), and 8176 separating protection spaces by using a different host name (or port 8177 number) for each party. 8179 12.14.4. Additional Response Fields 8181 Adding information to responses that are sent over an unencrypted 8182 channel can affect security and privacy. The presence of the 8183 Authentication-Info and Proxy-Authentication-Info header fields alone 8184 indicates that HTTP authentication is in use. Additional information 8185 could be exposed by the contents of the authentication-scheme 8186 specific parameters; this will have to be considered in the 8187 definitions of these schemes. 8189 13. IANA Considerations 8191 The change controller for the following registrations is: "IETF 8192 (iesg@ietf.org) - Internet Engineering Task Force". 8194 13.1. URI Scheme Registration 8196 Please update the registry of URI Schemes [BCP35] at 8197 with the permanent 8198 schemes listed in the first table of Section 2.5. 8200 13.2. Method Registration 8202 Please update the "Hypertext Transfer Protocol (HTTP) Method 8203 Registry" at with the 8204 registration procedure of Section 8.4.1 and the method names 8205 summarized in the table of Section 8.2. 8207 Furthermore, the method name "*" is reserved, since using that name 8208 as HTTP method name might conflict with special semantics in fields 8209 such as "Access-Control-Request-Method". Thus, please add the entry 8210 below to the registry: 8212 Method Name: * 8214 Safe: no 8216 Idempotent: no 8218 Reference: Section 13.2 8220 13.3. Status Code Registration 8222 Please update the "Hypertext Transfer Protocol (HTTP) Status Code 8223 Registry" at 8224 with the registration procedure of Section 10.7.1 and the status code 8225 values summarized in the table of Section 10.1. 8227 Additionally, please update the following entry in the Hypertext 8228 Transfer Protocol (HTTP) Status Code Registry: 8230 Value: 418 8232 Description: (Unused) 8234 Reference Section 10.5.19 8236 13.4. HTTP Field Name Registration 8238 Please create a new registry as outlined in Section 5.3.2. 8240 After creating the registry, all entries in the Permanent and 8241 Provisional Message Header Registries with the protocol 'http' are to 8242 be moved to it, with the following changes applied: 8244 1. The 'Applicable Protocol' field is to be omitted. 8246 2. Entries with a status of 'standard', 'experimental', 'reserved', 8247 or 'informational' are to have a status of 'permanent'. 8249 3. Provisional entries without a status are to have a status of 8250 'provisional'. 8252 4. Permanent entries without a status (after confirmation that the 8253 registration document did not define one) will have a status of 8254 'provisional'. The Expert(s) can choose to update their status 8255 if there is evidence that another is more appropriate. 8257 Please annotate the Permanent and Provisional Message Header 8258 registries to indicate that HTTP field name registrations have moved, 8259 with an appropriate link. 8261 After that is complete, please update the new registry with the field 8262 names listed in the table of Section 5.8. 8264 Finally, please update the "Content-MD5" entry in the new registry to 8265 have a status of 'obsoleted' with references to Section 14.15 of 8266 [RFC2616] (for the definition of the header field) and Appendix B of 8267 [RFC7231] (which removed the field definition from the updated 8268 specification). 8270 13.5. Authentication Scheme Registration 8272 Please update the "Hypertext Transfer Protocol (HTTP) Authentication 8273 Scheme Registry" at with the registration procedure of Section 9.5.5.1. No 8275 authentication schemes are defined in this document. 8277 13.6. Content Coding Registration 8279 Please update the "HTTP Content Coding Registry" at 8280 with the 8281 registration procedure of Section 7.1.2.4 and the content coding 8282 names summarized in the table of Section 7.1.2. 8284 13.7. Range Unit Registration 8286 Please update the "HTTP Range Unit Registry" at 8287 with the 8288 registration procedure of Section 7.1.4.4 and the range unit names 8289 summarized in the table of Section 7.1.4. 8291 13.8. Media Type Registration 8293 Please update the "Media Types" registry at 8294 with the registration 8295 information in Section 7.3.5 for the media type "multipart/ 8296 byteranges". 8298 13.9. Port Registration 8300 Please update the "Service Name and Transport Protocol Port Number" 8301 registry at for the services on ports 80 and 443 that use UDP or TCP 8303 to: 8305 1. use this document as "Reference", and 8307 2. when currently unspecified, set "Assignee" to "IESG" and 8308 "Contact" to "IETF_Chair". 8310 14. References 8312 14.1. Normative References 8314 [Caching] Fielding, R., Ed., Nottingham, M., Ed., and J. F. Reschke, 8315 Ed., "HTTP Caching", Work in Progress, Internet-Draft, 8316 draft-ietf-httpbis-cache-10, July 12, 2020, 8317 . 8319 [Messaging] 8320 Fielding, R., Ed., Nottingham, M., Ed., and J. F. Reschke, 8321 Ed., "HTTP/1.1 Messaging", Work in Progress, Internet- 8322 Draft, draft-ietf-httpbis-messaging-10, July 12, 2020, 8323 . 8326 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 8327 RFC 793, DOI 10.17487/RFC0793, September 1981, 8328 . 8330 [RFC1950] Deutsch, L.P. and J-L. Gailly, "ZLIB Compressed Data 8331 Format Specification version 3.3", RFC 1950, 8332 DOI 10.17487/RFC1950, May 1996, 8333 . 8335 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 8336 version 1.3", RFC 1951, DOI 10.17487/RFC1951, May 1996, 8337 . 8339 [RFC1952] Deutsch, P., Gailly, J-L., Adler, M., Deutsch, L.P., and 8340 G. Randers-Pehrson, "GZIP file format specification 8341 version 4.3", RFC 1952, DOI 10.17487/RFC1952, May 1996, 8342 . 8344 [RFC2045] Freed, N. and N.S. Borenstein, "Multipurpose Internet Mail 8345 Extensions (MIME) Part One: Format of Internet Message 8346 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 8347 . 8349 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 8350 Extensions (MIME) Part Two: Media Types", RFC 2046, 8351 DOI 10.17487/RFC2046, November 1996, 8352 . 8354 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 8355 Requirement Levels", BCP 14, RFC 2119, 8356 DOI 10.17487/RFC2119, March 1997, 8357 . 8359 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 8360 Resource Identifier (URI): Generic Syntax", STD 66, 8361 RFC 3986, DOI 10.17487/RFC3986, January 2005, 8362 . 8364 [RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of Language 8365 Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 8366 2006, . 8368 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 8369 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 8370 . 8372 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 8373 Specifications: ABNF", STD 68, RFC 5234, 8374 DOI 10.17487/RFC5234, January 2008, 8375 . 8377 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 8378 Housley, R., and W. Polk, "Internet X.509 Public Key 8379 Infrastructure Certificate and Certificate Revocation List 8380 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 8381 . 8383 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 8384 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 8385 September 2009, . 8387 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in 8388 Internationalization in the IETF", BCP 166, RFC 6365, 8389 DOI 10.17487/RFC6365, September 2011, 8390 . 8392 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 8393 RFC 7405, DOI 10.17487/RFC7405, December 2014, 8394 . 8396 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 8397 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 8398 May 2017, . 8400 [USASCII] American National Standards Institute, "Coded Character 8401 Set -- 7-bit American Standard Code for Information 8402 Interchange", ANSI X3.4, 1986. 8404 [Welch] Welch, T. A., "A Technique for High-Performance Data 8405 Compression", IEEE Computer 17(6), 8406 DOI 10.1109/MC.1984.1659158, June 1984, 8407 . 8409 14.2. Informative References 8411 [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type 8412 Specifications and Registration Procedures", BCP 13, 8413 RFC 6838, January 2013, 8414 . 8416 [BCP178] Saint-Andre, P., Crocker, D., and M. Nottingham, 8417 "Deprecating the "X-" Prefix and Similar Constructs in 8418 Application Protocols", BCP 178, RFC 6648, June 2012, 8419 . 8421 [BCP35] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 8422 and Registration Procedures for URI Schemes", BCP 35, 8423 RFC 7595, June 2015, 8424 . 8426 [Bujlow] Bujlow, T., Carela-Espanol, V., Sole-Pareta, J., and P. 8427 Barlet-Ros, "A Survey on Web Tracking: Mechanisms, 8428 Implications, and Defenses", 8429 DOI 10.1109/JPROC.2016.2637878, Proceedings of the 8430 IEEE 105(8), August 2017, 8431 . 8433 [Err1912] RFC Errata, Erratum ID 1912, RFC 2978, 8434 . 8436 [Err5433] RFC Errata, Erratum ID 5433, RFC 2978, 8437 . 8439 [Georgiev] Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh, 8440 D., and V. Shmatikov, "The Most Dangerous Code in the 8441 World: Validating SSL Certificates in Non-browser 8442 Software", DOI 10.1145/2382196.2382204, In Proceedings of 8443 the 2012 ACM Conference on Computer and Communications 8444 Security (CCS '12), pp. 38-49, October 2012, 8445 . 8447 [ISO-8859-1] 8448 International Organization for Standardization, 8449 "Information technology -- 8-bit single-byte coded graphic 8450 character sets -- Part 1: Latin alphabet No. 1", ISO/ 8451 IEC 8859-1:1998, 1998. 8453 [Kri2001] Kristol, D., "HTTP Cookies: Standards, Privacy, and 8454 Politics", ACM Transactions on Internet Technology 1(2), 8455 November 2001, . 8457 [OWASP] van der Stock, A., Ed., "A Guide to Building Secure Web 8458 Applications and Web Services", The Open Web Application 8459 Security Project (OWASP) 2.0.1, July 27, 2005, 8460 . 8462 [REST] Fielding, R.T., "Architectural Styles and the Design of 8463 Network-based Software Architectures", 8464 Doctoral Dissertation, University of California, Irvine, 8465 September 2000, 8466 . 8468 [RFC1919] Chatel, M., "Classical versus Transparent IP Proxies", 8469 RFC 1919, DOI 10.17487/RFC1919, March 1996, 8470 . 8472 [RFC1945] Berners-Lee, T., Fielding, R.T., and H.F. Nielsen, 8473 "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945, 8474 DOI 10.17487/RFC1945, May 1996, 8475 . 8477 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 8478 Part Three: Message Header Extensions for Non-ASCII Text", 8479 RFC 2047, DOI 10.17487/RFC2047, November 1996, 8480 . 8482 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T. 8483 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 8484 RFC 2068, DOI 10.17487/RFC2068, January 1997, 8485 . 8487 [RFC2145] Mogul, J.C., Fielding, R.T., Gettys, J., and H.F. Nielsen, 8488 "Use and Interpretation of HTTP Version Numbers", 8489 RFC 2145, DOI 10.17487/RFC2145, May 1997, 8490 . 8492 [RFC2295] Holtman, K. and A.H. Mutz, "Transparent Content 8493 Negotiation in HTTP", RFC 2295, DOI 10.17487/RFC2295, 8494 March 1998, . 8496 [RFC2324] Masinter, L., "Hyper Text Coffee Pot Control Protocol 8497 (HTCPCP/1.0)", RFC 2324, DOI 10.17487/RFC2324, April 1, 8498 1998, . 8500 [RFC2557] Palme, F., Hopmann, A., Shelness, N., and E. Stefferud, 8501 "MIME Encapsulation of Aggregate Documents, such as HTML 8502 (MHTML)", RFC 2557, DOI 10.17487/RFC2557, March 1999, 8503 . 8505 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 8506 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 8507 Transfer Protocol -- HTTP/1.1", RFC 2616, 8508 DOI 10.17487/RFC2616, June 1999, 8509 . 8511 [RFC2617] Franks, J., Hallam-Baker, P.M., Hostetler, J.L., Lawrence, 8512 S.D., Leach, P.J., Luotonen, A., and L. Stewart, "HTTP 8513 Authentication: Basic and Digest Access Authentication", 8514 RFC 2617, DOI 10.17487/RFC2617, June 1999, 8515 . 8517 [RFC2774] Frystyk, H., Leach, P., and S. Lawrence, "An HTTP 8518 Extension Framework", RFC 2774, DOI 10.17487/RFC2774, 8519 February 2000, . 8521 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 8522 DOI 10.17487/RFC2818, May 2000, 8523 . 8525 [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration 8526 Procedures", BCP 19, RFC 2978, DOI 10.17487/RFC2978, 8527 October 2000, . 8529 [RFC3040] Cooper, I., Melve, I., and G. Tomlinson, "Internet Web 8530 Replication and Caching Taxonomy", RFC 3040, 8531 DOI 10.17487/RFC3040, January 2001, 8532 . 8534 [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S. 8535 Rose, "DNS Security Introduction and Requirements", 8536 RFC 4033, DOI 10.17487/RFC4033, March 2005, 8537 . 8539 [RFC4559] Jaganathan, K., Zhu, L., and J. Brezak, "SPNEGO-based 8540 Kerberos and NTLM HTTP Authentication in Microsoft 8541 Windows", RFC 4559, DOI 10.17487/RFC4559, June 2006, 8542 . 8544 [RFC4918] Dusseault, L.M., Ed., "HTTP Extensions for Web Distributed 8545 Authoring and Versioning (WebDAV)", RFC 4918, 8546 DOI 10.17487/RFC4918, June 2007, 8547 . 8549 [RFC5322] Resnick, P., "Internet Message Format", RFC 5322, 8550 DOI 10.17487/RFC5322, October 2008, 8551 . 8553 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 8554 RFC 5789, DOI 10.17487/RFC5789, March 2010, 8555 . 8557 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 8558 "Network Time Protocol Version 4: Protocol and Algorithms 8559 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 8560 . 8562 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 8563 Verification of Domain-Based Application Service Identity 8564 within Internet Public Key Infrastructure Using X.509 8565 (PKIX) Certificates in the Context of Transport Layer 8566 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 8567 2011, . 8569 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 8570 DOI 10.17487/RFC6265, April 2011, 8571 . 8573 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 8574 DOI 10.17487/RFC6454, December 2011, 8575 . 8577 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 8578 Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, 8579 . 8581 [RFC7230] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 8582 Transfer Protocol (HTTP/1.1): Message Syntax and Routing", 8583 RFC 7230, DOI 10.17487/RFC7230, June 2014, 8584 . 8586 [RFC7231] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 8587 Transfer Protocol (HTTP/1.1): Semantics and Content", 8588 RFC 7231, DOI 10.17487/RFC7231, June 2014, 8589 . 8591 [RFC7232] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 8592 Transfer Protocol (HTTP/1.1): Conditional Requests", 8593 RFC 7232, DOI 10.17487/RFC7232, June 2014, 8594 . 8596 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. F. Reschke, Ed., 8597 "Hypertext Transfer Protocol (HTTP): Range Requests", 8598 RFC 7233, DOI 10.17487/RFC7233, June 2014, 8599 . 8601 [RFC7235] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 8602 Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, 8603 DOI 10.17487/RFC7235, June 2014, 8604 . 8606 [RFC7538] Reschke, J. F., "The Hypertext Transfer Protocol Status 8607 Code 308 (Permanent Redirect)", RFC 7538, 8608 DOI 10.17487/RFC7538, April 2015, 8609 . 8611 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 8612 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 8613 DOI 10.17487/RFC7540, May 2015, 8614 . 8616 [RFC7578] Masinter, L., "Returning Values from Forms: multipart/ 8617 form-data", RFC 7578, DOI 10.17487/RFC7578, July 2015, 8618 . 8620 [RFC7615] Reschke, J. F., "HTTP Authentication-Info and Proxy- 8621 Authentication-Info Response Header Fields", RFC 7615, 8622 DOI 10.17487/RFC7615, September 2015, 8623 . 8625 [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP 8626 Digest Access Authentication", RFC 7616, 8627 DOI 10.17487/RFC7616, September 2015, 8628 . 8630 [RFC7617] Reschke, J. F., "The 'Basic' HTTP Authentication Scheme", 8631 RFC 7617, DOI 10.17487/RFC7617, September 2015, 8632 . 8634 [RFC7694] Reschke, J. F., "Hypertext Transfer Protocol (HTTP) 8635 Client-Initiated Content-Encoding", RFC 7694, 8636 DOI 10.17487/RFC7694, November 2015, 8637 . 8639 [RFC7838] Nottingham, M., McManus, P., and J. Reschke, "HTTP 8640 Alternative Services", RFC 7838, DOI 10.17487/RFC7838, 8641 April 2016, . 8643 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 8644 Writing an IANA Considerations Section in RFCs", BCP 26, 8645 RFC 8126, DOI 10.17487/RFC8126, June 2017, 8646 . 8648 [RFC8187] Reschke, J. F., "Indicating Character Encoding and 8649 Language for HTTP Header Field Parameters", RFC 8187, 8650 DOI 10.17487/RFC8187, September 2017, 8651 . 8653 [RFC8246] McManus, P., "HTTP Immutable Responses", RFC 8246, 8654 DOI 10.17487/RFC8246, September 2017, 8655 . 8657 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 8658 DOI 10.17487/RFC8288, October 2017, 8659 . 8661 [RFC8336] Nottingham, M. and E. Nygren, "The ORIGIN HTTP/2 Frame", 8662 RFC 8336, DOI 10.17487/RFC8336, March 2018, 8663 . 8665 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 8666 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 8667 . 8669 [Sniffing] WHATWG, "MIME Sniffing", 8670 . 8672 Appendix A. Collected ABNF 8674 In the collected ABNF below, list rules are expanded as per 8675 Section 5.5.1. 8677 Accept = [ ( media-range [ accept-params ] ) *( OWS "," OWS ( 8678 media-range [ accept-params ] ) ) ] 8679 Accept-Charset = ( ( charset / "*" ) [ weight ] ) *( OWS "," OWS ( ( 8680 charset / "*" ) [ weight ] ) ) 8681 Accept-Encoding = [ ( codings [ weight ] ) *( OWS "," OWS ( codings [ 8682 weight ] ) ) ] 8683 Accept-Language = ( language-range [ weight ] ) *( OWS "," OWS ( 8684 language-range [ weight ] ) ) 8685 Accept-Ranges = acceptable-ranges 8686 Allow = [ method *( OWS "," OWS method ) ] 8687 Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) ] 8688 Authorization = credentials 8690 BWS = OWS 8692 Content-Encoding = content-coding *( OWS "," OWS content-coding ) 8693 Content-Language = language-tag *( OWS "," OWS language-tag ) 8694 Content-Length = 1*DIGIT 8695 Content-Location = absolute-URI / partial-URI 8696 Content-Range = range-unit SP ( range-resp / unsatisfied-range ) 8697 Content-Type = media-type 8699 Date = HTTP-date 8701 ETag = entity-tag 8702 Expect = "100-continue" 8704 From = mailbox 8706 GMT = %x47.4D.54 ; GMT 8708 HTTP-date = IMF-fixdate / obs-date 8709 Host = uri-host [ ":" port ] 8711 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 8712 If-Match = "*" / ( entity-tag *( OWS "," OWS entity-tag ) ) 8713 If-Modified-Since = HTTP-date 8714 If-None-Match = "*" / ( entity-tag *( OWS "," OWS entity-tag ) ) 8715 If-Range = entity-tag / HTTP-date 8716 If-Unmodified-Since = HTTP-date 8718 Last-Modified = HTTP-date 8719 Location = URI-reference 8721 Max-Forwards = 1*DIGIT 8723 OWS = *( SP / HTAB ) 8725 Proxy-Authenticate = challenge *( OWS "," OWS challenge ) 8726 Proxy-Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) 8727 ] 8728 Proxy-Authorization = credentials 8730 RWS = 1*( SP / HTAB ) 8731 Range = ranges-specifier 8732 Referer = absolute-URI / partial-URI 8733 Retry-After = HTTP-date / delay-seconds 8735 Server = product *( RWS ( product / comment ) ) 8737 Trailer = field-name *( OWS "," OWS field-name ) 8739 URI-reference = 8740 User-Agent = product *( RWS ( product / comment ) ) 8742 Vary = ( "*" / field-name ) *( OWS "," OWS ( "*" / field-name ) ) 8743 Via = ( received-protocol RWS received-by [ RWS comment ] ) *( OWS 8744 "," OWS ( received-protocol RWS received-by [ RWS comment ] ) ) 8746 WWW-Authenticate = challenge *( OWS "," OWS challenge ) 8748 absolute-URI = 8749 absolute-path = 1*( "/" segment ) 8750 accept-ext = OWS ";" OWS token [ "=" ( token / quoted-string ) ] 8751 accept-params = weight *accept-ext 8752 acceptable-ranges = ( range-unit *( OWS "," OWS range-unit ) ) / 8753 "none" 8754 asctime-date = day-name SP date3 SP time-of-day SP year 8755 auth-param = token BWS "=" BWS ( token / quoted-string ) 8756 auth-scheme = token 8757 authority = 8759 challenge = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS "," 8760 OWS auth-param ) ] ) ] 8762 charset = token 8763 codings = content-coding / "identity" / "*" 8764 comment = "(" *( ctext / quoted-pair / comment ) ")" 8765 complete-length = 1*DIGIT 8766 content-coding = token 8767 credentials = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS "," 8768 OWS auth-param ) ] ) ] 8769 ctext = HTAB / SP / %x21-27 ; '!'-''' 8770 / %x2A-5B ; '*'-'[' 8771 / %x5D-7E ; ']'-'~' 8772 / obs-text 8774 date1 = day SP month SP year 8775 date2 = day "-" month "-" 2DIGIT 8776 date3 = month SP ( 2DIGIT / ( SP DIGIT ) ) 8777 day = 2DIGIT 8778 day-name = %x4D.6F.6E ; Mon 8779 / %x54.75.65 ; Tue 8780 / %x57.65.64 ; Wed 8781 / %x54.68.75 ; Thu 8782 / %x46.72.69 ; Fri 8783 / %x53.61.74 ; Sat 8784 / %x53.75.6E ; Sun 8785 day-name-l = %x4D.6F.6E.64.61.79 ; Monday 8786 / %x54.75.65.73.64.61.79 ; Tuesday 8787 / %x57.65.64.6E.65.73.64.61.79 ; Wednesday 8788 / %x54.68.75.72.73.64.61.79 ; Thursday 8789 / %x46.72.69.64.61.79 ; Friday 8790 / %x53.61.74.75.72.64.61.79 ; Saturday 8791 / %x53.75.6E.64.61.79 ; Sunday 8792 delay-seconds = 1*DIGIT 8794 entity-tag = [ weak ] opaque-tag 8795 etagc = "!" / %x23-7E ; '#'-'~' 8796 / obs-text 8798 field-content = field-vchar [ 1*( SP / HTAB / field-vchar ) 8799 field-vchar ] 8800 field-name = token 8801 field-value = *field-content 8802 field-vchar = VCHAR / obs-text 8803 first-pos = 1*DIGIT 8805 hour = 2DIGIT 8806 http-URI = "http://" authority path-abempty [ "?" query ] 8807 https-URI = "https://" authority path-abempty [ "?" query ] 8809 incl-range = first-pos "-" last-pos 8810 int-range = first-pos "-" [ last-pos ] 8812 language-range = 8813 language-tag = 8814 last-pos = 1*DIGIT 8816 mailbox = 8817 media-range = ( "*/*" / ( type "/*" ) / ( type "/" subtype ) ) *( OWS 8818 ";" OWS parameter ) 8819 media-type = type "/" subtype *( OWS ";" OWS parameter ) 8820 method = token 8821 minute = 2DIGIT 8822 month = %x4A.61.6E ; Jan 8823 / %x46.65.62 ; Feb 8824 / %x4D.61.72 ; Mar 8825 / %x41.70.72 ; Apr 8826 / %x4D.61.79 ; May 8827 / %x4A.75.6E ; Jun 8828 / %x4A.75.6C ; Jul 8829 / %x41.75.67 ; Aug 8830 / %x53.65.70 ; Sep 8831 / %x4F.63.74 ; Oct 8832 / %x4E.6F.76 ; Nov 8833 / %x44.65.63 ; Dec 8835 obs-date = rfc850-date / asctime-date 8836 obs-text = %x80-FF 8837 opaque-tag = DQUOTE *etagc DQUOTE 8838 other-range = 1*( %x21-2B ; '!'-'+' 8839 / %x2D-7E ; '-'-'~' 8840 ) 8842 parameter = parameter-name "=" parameter-value 8843 parameter-name = token 8844 parameter-value = ( token / quoted-string ) 8845 partial-URI = relative-part [ "?" query ] 8846 path-abempty = 8847 port = 8848 product = token [ "/" product-version ] 8849 product-version = token 8850 protocol-name = 8851 protocol-version = 8852 pseudonym = token 8854 qdtext = HTAB / SP / "!" / %x23-5B ; '#'-'[' 8855 / %x5D-7E ; ']'-'~' 8856 / obs-text 8857 query = 8858 quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) 8859 quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE 8860 qvalue = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] ) 8862 range-resp = incl-range "/" ( complete-length / "*" ) 8863 range-set = range-spec *( OWS "," OWS range-spec ) 8864 range-spec = int-range / suffix-range / other-range 8865 range-unit = token 8866 ranges-specifier = range-unit "=" range-set 8867 received-by = pseudonym [ ":" port ] 8868 received-protocol = [ protocol-name "/" ] protocol-version 8869 relative-part = 8870 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 8872 second = 2DIGIT 8873 segment = 8874 subtype = token 8875 suffix-length = 1*DIGIT 8876 suffix-range = "-" suffix-length 8878 tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / 8879 "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA 8880 time-of-day = hour ":" minute ":" second 8881 token = 1*tchar 8882 token68 = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) 8883 *"=" 8884 type = token 8886 unsatisfied-range = "*/" complete-length 8887 uri-host = 8889 weak = %x57.2F ; W/ 8890 weight = OWS ";" OWS "q=" qvalue 8892 year = 4DIGIT 8894 Appendix B. Changes from previous RFCs 8896 B.1. Changes from RFC 2818 8898 None yet. 8900 B.2. Changes from RFC 7230 8902 The sections introducing HTTP's design goals, history, architecture, 8903 conformance criteria, protocol versioning, URIs, message routing, and 8904 header fields have been moved here (without substantive change). 8906 "Field value" now refers to the value after multiple instances are 8907 combined with commas - by far the most common use. To refer to a 8908 single header line's value, use "field line value". (Section 5) 8910 Trailer field semantics now transcend the specifics of chunked 8911 encoding. Use of trailer fields has been further limited to only 8912 allow generation as a trailer field when the sender knows the field 8913 defines that usage and to only allow merging into the header section 8914 if the recipient knows the corresponding field definition permits and 8915 defines how to merge. In all other cases, implementations are 8916 encouraged to either store the trailer fields separately or discard 8917 them instead of merging. (Section 5.6.2) 8919 Made the priority of the absolute form of the request URI over the 8920 Host header by origin servers explicit, to align with proxy handling. 8921 (Section 6.6) 8923 The grammar definition for the Via field's "received-by" was expanded 8924 in 7230 due to changes in the URI grammar for host [RFC3986] that are 8925 not desirable for Via. For simplicity, we have removed uri-host from 8926 the received-by production because it can be encompassed by the 8927 existing grammar for pseudonym. In particular, this change removed 8928 comma from the allowed set of charaters for a host name in received- 8929 by. (Section 6.7.1) 8931 Added status code 308 (previously defined in [RFC7538]) so that it's 8932 defined closer to status codes 301, 302, and 307. (Section 10.4.9) 8934 Added status code 422 (previously defined in Section 11.2 of 8935 [RFC4918]) because of its general applicability. (Section 10.5.20) 8937 The description of an origin and authoritative access to origin 8938 servers has been extended for both "http" and "https" URIs to account 8939 for alternative services and secured connections that are not 8940 necessarily based on TCP. (Section 2.5.1, Section 2.5.2, 8941 Section 6.2, Section 6.4) 8943 B.3. Changes from RFC 7231 8945 Minimum URI lengths to be supported by implementations are now 8946 recommended. (Section 2.5) 8948 Clarify that control characters in field values are to be rejected or 8949 mapped to SP. (Section 5.4) 8951 The term "effective request URI" has been replaced with "target URI". 8952 (Section 6.1) 8953 Range units are compared in a case insensitive fashion. 8954 (Section 7.1.4) 8956 Restrictions on client retries have been loosened, to reflect 8957 implementation behavior. (Section 8.2.2) 8959 Clarified that request bodies on GET and DELETE are not 8960 interoperable. (Section 8.3.1, Section 8.3.5) 8962 Removed a superfluous requirement about setting Content-Length from 8963 the description of the OPTIONS method. (Section 8.3.7) 8965 Allow Accept and Accept-Encoding in response messages; the latter was 8966 introduced by [RFC7694]. (Section 9.4) 8968 B.4. Changes from RFC 7232 8970 Clarify that If-Unmodified-Since doesn't apply to a resource without 8971 a concept of modification time. (Section 9.2.6) 8973 B.5. Changes from RFC 7233 8975 Refactored the range-unit and ranges-specifier grammars to simplify 8976 and reduce artificial distinctions between bytes and other 8977 (extension) range units, removing the overlapping grammar of other- 8978 range-unit by defining range units generically as a token and placing 8979 extensions within the scope of a range-spec (other-range). This 8980 disambiguates the role of list syntax (commas) in all range sets, 8981 including extension range units, for indicating a range-set of more 8982 than one range. Moving the extension grammar into range specifiers 8983 also allows protocol specific to byte ranges to be specified 8984 separately. 8986 B.6. Changes from RFC 7235 8988 None yet. 8990 B.7. Changes from RFC 7538 8992 None yet. 8994 B.8. Changes from RFC 7615 8996 None yet. 8998 Appendix C. Changes from RFC 7694 9000 This specification includes the extension defined in [RFC7694], but 9001 leaves out examples and deployment considerations. 9003 Appendix D. Change Log 9005 This section is to be removed before publishing as an RFC. 9007 D.1. Between RFC723x and draft 00 9009 The changes were purely editorial: 9011 o Change boilerplate and abstract to indicate the "draft" status, 9012 and update references to ancestor specifications. 9014 o Remove version "1.1" from document title, indicating that this 9015 specification applies to all HTTP versions. 9017 o Adjust historical notes. 9019 o Update links to sibling specifications. 9021 o Replace sections listing changes from RFC 2616 by new empty 9022 sections referring to RFC 723x. 9024 o Remove acknowledgements specific to RFC 723x. 9026 o Move "Acknowledgements" to the very end and make them unnumbered. 9028 D.2. Since draft-ietf-httpbis-semantics-00 9030 The changes in this draft are editorial, with respect to HTTP as a 9031 whole, to merge core HTTP semantics into this document: 9033 o Merged introduction, architecture, conformance, and ABNF 9034 extensions from RFC 7230 (Messaging). 9036 o Rearranged architecture to extract conformance, http(s) schemes, 9037 and protocol versioning into a separate major section. 9039 o Moved discussion of MIME differences to [Messaging] since that is 9040 primarily concerned with transforming 1.1 messages. 9042 o Merged entire content of RFC 7232 (Conditional Requests). 9044 o Merged entire content of RFC 7233 (Range Requests). 9046 o Merged entire content of RFC 7235 (Auth Framework). 9048 o Moved all extensibility tips, registration procedures, and 9049 registry tables from the IANA considerations to normative 9050 sections, reducing the IANA considerations to just instructions 9051 that will be removed prior to publication as an RFC. 9053 D.3. Since draft-ietf-httpbis-semantics-01 9055 o Improve [Welch] citation () 9058 o Remove HTTP/1.1-ism about Range Requests 9059 () 9061 o Cite RFC 8126 instead of RFC 5226 () 9064 o Cite RFC 7538 instead of RFC 7238 () 9067 o Cite RFC 8288 instead of RFC 5988 () 9070 o Cite RFC 8187 instead of RFC 5987 () 9073 o Cite RFC 7578 instead of RFC 2388 () 9076 o Cite RFC 7595 instead of RFC 4395 () 9079 o improve ABNF readability for qdtext (, ) 9082 o Clarify "resource" vs "representation" in definition of status 9083 code 416 (, 9084 ) 9086 o Resolved erratum 4072, no change needed here 9087 (, 9088 ) 9090 o Clarify DELETE status code suggestions 9091 (, 9092 ) 9094 o In Section 7.3.4, fix ABNF for "other-range-resp" to use VCHAR 9095 instead of CHAR (, 9096 ) 9098 o Resolved erratum 5162, no change needed here 9099 (, 9100 ) 9102 o Replace "response code" with "response status code" and "status- 9103 code" (the ABNF production name from the HTTP/1.1 message format) 9104 by "status code" (, 9105 ) 9107 o Added a missing word in Section 10.4 (, ) 9110 o In Section 5.5, fixed an example that had trailing whitespace 9111 where it shouldn't (, ) 9114 o In Section 10.3.7, remove words that were potentially misleading 9115 with respect to the relation to the requested ranges 9116 (, 9117 ) 9119 D.4. Since draft-ietf-httpbis-semantics-02 9121 o Included (Proxy-)Auth-Info header field definition from RFC 7615 9122 () 9124 o In Section 8.3.3, clarify POST caching 9125 () 9127 o Add Section 10.5.19 to reserve the 418 status code 9128 () 9130 o In Section 2.1 and Section 9.1.1, clarified when a response can be 9131 sent () 9133 o In Section 7.1.1.1, explain the difference between the "token" 9134 production, the RFC 2978 ABNF for charset names, and the actual 9135 registration practice (, ) 9138 o In Section 2.5, removed the fragment component in the URI scheme 9139 definitions as per Section 4.3 of [RFC3986], furthermore moved 9140 fragment discussion into a separate section 9141 (, 9142 , ) 9145 o In Section 4.2, add language about minor HTTP version number 9146 defaulting () 9148 o Added Section 10.5.20 for status code 422, previously defined in 9149 Section 11.2 of [RFC4918] () 9152 o In Section 10.5.17, fixed prose about byte range comparison 9153 (, 9154 ) 9156 o In Section 2.1, explain that request/response correlation is 9157 version specific () 9160 D.5. Since draft-ietf-httpbis-semantics-03 9162 o In Section 10.4.9, include status code 308 from RFC 7538 9163 () 9165 o In Section 7.1.1, clarify that the charset parameter value is 9166 case-insensitive due to the definition in RFC 2046 9167 () 9169 o Define a separate registry for HTTP header field names 9170 () 9172 o In Section 9.4, refactor and clarify description of wildcard ("*") 9173 handling () 9175 o Deprecate Accept-Charset () 9178 o In Section 9.2.1, mention Cache-Control: immutable 9179 () 9181 o In Section 5.1, clarify when header field combination is allowed 9182 () 9184 o In Section 13.4, instruct IANA to mark Content-MD5 as obsolete 9185 () 9187 o Use RFC 7405 ABNF notation for case-sensitive string constants 9188 () 9190 o Rework Section 2.1 to be more version-independent 9191 () 9193 o In Section 8.3.5, clarify that DELETE needs to be successful to 9194 invalidate cache (, ) 9197 D.6. Since draft-ietf-httpbis-semantics-04 9199 o In Section 5.4, fix field-content ABNF 9200 (, 9201 ) 9203 o Move Section 5.4.1.4 into its own section 9204 () 9206 o In Section 7.2.1, reference MIME Sniffing 9207 () 9209 o In Section 5.5, simplify the #rule mapping for recipients 9210 (, 9211 ) 9213 o In Section 8.3.7, remove misleading text about "extension" of HTTP 9214 is needed to define method payloads () 9217 o Fix editorial issue in Section 7 () 9220 o In Section 10.5.20, rephrase language not to use "entity" anymore, 9221 and also avoid lowercase "may" () 9224 o Move discussion of retries from [Messaging] into Section 8.2.2 9225 () 9227 D.7. Since draft-ietf-httpbis-semantics-05 9229 o Moved transport-independent part of the description of trailers 9230 into Section 5.6 () 9232 o Loosen requirements on retries based upon implementation behavior 9233 () 9235 o In Section 13.9, update IANA port registry for TCP/UDP on ports 80 9236 and 443 () 9238 o In Section 5.7, revise guidelines for new header field names 9239 () 9241 o In Section 8.2.3, remove concept of "cacheable methods" in favor 9242 of prose (, 9243 ) 9245 o In Section 12.1, mention that the concept of authority can be 9246 modified by protocol extensions () 9249 o Create new subsection on payload body in Section 7.3.3, taken from 9250 portions of message body () 9253 o Moved definition of "Whitespace" into new container "Generic 9254 Syntax" () 9256 o In Section 2.5, recommend minimum URI size support for 9257 implementations () 9259 o In Section 7.1.4, refactored the range-unit and ranges-specifier 9260 grammars (, 9261 ) 9263 o In Section 8.3.1, caution against a request body more strongly 9264 () 9266 o Reorganized text in Section 5.7 () 9269 o In Section 10.5.4, replace "authorize" with "fulfill" 9270 () 9272 o In Section 8.3.7, removed a misleading statement about Content- 9273 Length (, 9274 ) 9276 o In Section 12.1, add text from RFC 2818 9277 () 9279 o Changed "cacheable by default" to "heuristically cacheable" 9280 throughout () 9282 D.8. Since draft-ietf-httpbis-semantics-06 9284 o In Section 6.7.1, simplify received-by grammar (and disallow comma 9285 character) () 9287 o In Section 5.3, give guidance on interoperable field names 9288 () 9290 o In Section 1.2.1, define the semantics and possible replacement of 9291 whitespace when it is known to occur (, ) 9294 o In Section 5, introduce field terminology and distinguish between 9295 field line values and field values; use terminology consistently 9296 throughout () 9298 o Moved #rule definition into Section 5.4 and whitespace into 9299 Section 1.2 () 9301 o In Section 7.1.4, explicitly call out range unit names as case- 9302 insensitive, and encourage registration 9303 () 9305 o In Section 7.1.2, explicitly call out content codings as case- 9306 insensitive, and encourage registration 9307 () 9309 o In Section 5.3, explicitly call out field names as case- 9310 insensitive () 9312 o In Section 12.11, cite [Bujlow] () 9315 o In Section 10, formally define "final" and "interim" status codes 9316 () 9318 o In Section 8.3.5, caution against a request body more strongly 9319 () 9321 o In Section 11.2.3, note that Etag can be used in trailers 9322 () 9324 o In Section 13.4, consider reserved fields as well 9325 () 9327 o In Section 2.5.4, be more correct about what was deprecated by RFC 9328 3986 (, 9329 ) 9331 o In Section 5.1, recommend comma SP when combining field lines 9332 () 9334 o In Section 6.6, make explicit requirements on origin server to use 9335 authority from absolute-form when available 9336 () 9338 o In Section 2.5.1, Section 2.5.2, Section 6.2, and Section 6.4, 9339 refactored schemes to define origin and authoritative access to an 9340 origin server for both "http" and "https" URIs to account for 9341 alternative services and secured connections that are not 9342 necessarily based on TCP () 9345 o In Section 1.1, reference RFC 8174 as well 9346 () 9348 D.9. Since draft-ietf-httpbis-semantics-07 9350 o In Section 9.3, explicitly reference the definition of 9351 representation data as including any content codings 9352 () 9354 o Move TE: trailers from [Messaging] into Section 5.6.2 9355 () 9357 o In Section 7.2.4, adjust requirements for handling multiple 9358 content-length values () 9361 o In Section 9.2.3 and Section 9.2.4, clarified condition evaluation 9362 () 9364 o In Section 5.4, remove concept of obs-fold, as that is 9365 HTTP/1-specific () 9367 o In Section 7.4, introduce the concept of request payload 9368 negotiation (Section 7.4.3) and define for Accept-Encoding 9369 () 9371 o In Section 10.3.6, Section 10.5.9, and Section 10.5.14, remove 9372 HTTP/1-specific, connection-related requirements 9373 () 9375 o In Section 8.3.6, correct language about what is forwarded 9376 () 9378 o Throughout, replace "effective request URI", "request-target" and 9379 similar with "target URI" () 9382 o In Section 5.7 and Section 10.7.2, describe how extensions should 9383 consider scope of applicability () 9386 o In Section 2.1, don't rely on the HTTP/1.1 Messaging specification 9387 to define "message" () 9390 o In Section 7.2.5 and Section 9.6.2, note that URL resolution is 9391 necessary () 9393 o In Section 7, explicitly reference 206 as one of the status codes 9394 that provide representation data () 9397 o In Section 9.2.6, refine requirements so that they don't apply to 9398 resources without a concept of modification time 9399 () 9401 o In Section 11.3.2, specify the scope as a request, not a target 9402 resource () 9404 o In Section 2.1, introduce concept of "complete" messages 9405 () 9407 o In Section 6.1, Section 8.3.6, and Section 8.3.7, refine use of 9408 "request target" () 9411 o Throughout, remove "status-line" and "request-line", as these are 9412 HTTP/1.1-specific () 9415 D.10. Since draft-ietf-httpbis-semantics-08 9417 o In Section 10.5.17, remove duplicate definition of what makes a 9418 range satisfiable and refer instead to each range unit's 9419 definition () 9421 o In Section 7.1.4.2 and Section 9.3, clarify that a selected 9422 representation of zero length can only be satisfiable as a suffix 9423 range and that a server can still ignore Range for that case 9424 () 9426 o In Section 9.4.1 and Section 10.5.16, allow "Accept" as response 9427 field () 9429 o Appendix A now uses the sender variant of the "#" list expansion 9430 () 9432 o In Section 11.1.4, make the field list-based even when "*" is 9433 present () 9435 o In Section 5.3.2, add optional "Comments" entry 9436 () 9438 o In Section 5.8, reserve "*" as field name 9439 () 9441 o In Section 13.2, reserve "*" as method name 9442 () 9444 o In Section 9.2.3 and Section 9.2.4, state that multiple "*" is 9445 unlikely to be interoperable () 9448 o In Section 9.4.1, avoid use of obsolete media type parameter on 9449 text/html (, 9450 ) 9452 o Rephrase prose in Section 2.1 to become version-agnostic 9453 () 9455 o In Section 5.4, instruct recipients how to deal with control 9456 characters in field values () 9459 o In Section 5.4, update note about field ABNF 9460 () 9462 o Add Section 4 about Extending and Versioning HTTP 9463 () 9465 o In Section 10.1, include status 308 in list of heuristically 9466 cacheable status codes () 9469 o In Section 7.2.2, make it clearer that "identity" is not to be 9470 included () 9472 D.11. Since draft-ietf-httpbis-semantics-09 9473 o Switch to xml2rfc v3 mode for draft generation 9474 () 9476 Acknowledgments 9478 This edition of the HTTP specification builds on the many 9479 contributions that went into RFC 1945, RFC 2068, RFC 2145, RFC 2616, 9480 and RFC 2818, including substantial contributions made by the 9481 previous authors, editors, and Working Group Chairs: Tim Berners-Lee, 9482 Ari Luotonen, Roy T. Fielding, Henrik Frystyk Nielsen, Jim Gettys, 9483 Jeffrey C. Mogul, Larry Masinter, Paul J. Leach, Eric Rescorla, and 9484 Yves Lafon. 9486 See Section 10 of [RFC7230] for further acknowledgements from prior 9487 revisions. 9489 In addition, this document has reincorporated the HTTP Authentication 9490 Framework, previously defined in RFC 7235 and RFC 2617. We thank 9491 John Franks, Phillip M. Hallam-Baker, Jeffery L. Hostetler, Scott 9492 D. Lawrence, Paul J. Leach, Ari Luotonen, and Lawrence C. Stewart 9493 for their work on that specification. See Section 6 of [RFC2617] for 9494 further acknowledgements. 9496 // New acks to be added here. 9498 Authors' Addresses 9500 Roy T. Fielding (editor) 9501 Adobe 9502 345 Park Ave 9503 San Jose, CA 95110 9504 United States of America 9506 Email: fielding@gbiv.com 9507 URI: https://roy.gbiv.com/ 9509 Mark Nottingham (editor) 9510 Fastly 9512 Email: mnot@mnot.net 9513 URI: https://www.mnot.net/ 9515 Julian F. Reschke (editor) 9516 greenbytes GmbH 9517 Hafenweg 16 9518 48155 Münster 9519 Germany 9521 Email: julian.reschke@greenbytes.de 9522 URI: https://greenbytes.de/tech/webdav/