idnits 2.17.1 draft-ietf-http-v11-spec-rev-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 4 longer pages, the longest (page 3) being 63 lines == It seems as if not all pages are separated by form feeds - found 164 form feeds but 166 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([47], [33]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 4 instances of lines with non-RFC2606-compliant FQDNs in the document. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1172 has weird spacing: '... are in the f...' == Line 1251 has weird spacing: '... of the respo...' == Line 1723 has weird spacing: '... Method token...' == Line 3463 has weird spacing: '...he Vary heade...' == Line 4357 has weird spacing: '...ich are trans...' == (3 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 18, 1998) is 9284 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) == Missing Reference: '47' is mentioned on line 389, but not defined == Missing Reference: '33' is mentioned on line 8265, but not defined == Missing Reference: '20' is mentioned on line 913, but not defined == Missing Reference: '16' is mentioned on line 398, but not defined == Missing Reference: '13' is mentioned on line 398, but not defined == Missing Reference: '18' is mentioned on line 398, but not defined == Missing Reference: '10' is mentioned on line 399, but not defined == Missing Reference: '34' is mentioned on line 8147, but not defined == Missing Reference: '19' is mentioned on line 1302, but not defined == Missing Reference: '21' is mentioned on line 769, but not defined -- Looks like a reference, but probably isn't: 'CRLF' on line 798 == Missing Reference: '22' is mentioned on line 803, but not defined == Missing Reference: '14' is mentioned on line 7039, but not defined == Missing Reference: '36' is mentioned on line 884, but not defined == Missing Reference: '11' is mentioned on line 925, but not defined == Missing Reference: '42' is mentioned on line 1801, but not defined == Missing Reference: '24' is mentioned on line 7312, but not defined == Missing Reference: '12' is mentioned on line 999, but not defined == Missing Reference: '38' is mentioned on line 1088, but not defined == Missing Reference: '41' is mentioned on line 1089, but not defined == Missing Reference: '25' is mentioned on line 1130, but not defined == Missing Reference: '31' is mentioned on line 1146, but not defined == Missing Reference: '29' is mentioned on line 1147, but not defined == Missing Reference: '17' is mentioned on line 7738, but not defined == Missing Reference: '40' is mentioned on line 7816, but not defined == Missing Reference: '15' is mentioned on line 1372, but not defined == Missing Reference: '1' is mentioned on line 1425, but not defined == Missing Reference: '26' is mentioned on line 2107, but not defined == Missing Reference: '30' is mentioned on line 2107, but not defined == Missing Reference: '39' is mentioned on line 8254, but not defined == Missing Reference: '27' is mentioned on line 2110, but not defined == Missing Reference: '44' is mentioned on line 8424, but not defined -- Looks like a reference, but probably isn't: 'RFC 2068' on line 3032 == Missing Reference: '43' is mentioned on line 8439, but not defined == Missing Reference: '28' is mentioned on line 5930, but not defined == Missing Reference: '23' is mentioned on line 5719, but not defined == Missing Reference: '35' is mentioned on line 8019, but not defined == Missing Reference: '49' is mentioned on line 7335, but not defined == Missing Reference: '48' is mentioned on line 7907, but not defined == Missing Reference: '45' is mentioned on line 8158, but not defined == Missing Reference: '37' is mentioned on line 8012, but not defined == Unused Reference: '5' is defined on line 7500, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 1436 (ref. '2') ** Downref: Normative reference to an Informational RFC: RFC 1630 (ref. '3') ** Obsolete normative reference: RFC 1738 (ref. '4') (Obsoleted by RFC 4248, RFC 4266) ** Obsolete normative reference: RFC 1866 (ref. '5') (Obsoleted by RFC 2854) ** Downref: Normative reference to an Informational RFC: RFC 1945 (ref. '6') ** Obsolete normative reference: RFC 822 (ref. '9') (Obsoleted by RFC 2822) Summary: 15 errors (**), 0 flaws (~~), 52 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP Working Group R. Fielding, UC Irvine 3 INTERNET-DRAFT J. Gettys, Compaq/W3C 4 J. C. Mogul, Compaq 5 H. Frystyk, W3C/MIT 6 L. Masinter, Xerox 7 P. Leach, Microsoft 8 T. Berners-Lee, W3C/MIT 9 Expires May 18, 1999 November 18, 1998 11 Hypertext Transfer Protocol -- HTTP/1.1 13 Status of this Memo 15 This document is an Internet-Draft. Internet-Drafts are working 16 documents of the Internet Engineering Task Force (IETF), its areas, 17 and its working groups. Note that other groups may also distribute 18 working documents as Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or made obsolete by other documents at 22 any time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress". 25 To learn the current status of any Internet-Draft, please check the 26 "1id-abstracts.txt" listing contained in the Internet-Draft's Shadow 27 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 28 munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or 29 ftp.isi.edu (US West Coast). 31 Distribution of this document is unlimited. Please send comments to 32 the HTTP working group at . Discussions of 33 the working group are archived at 34 http://www.ics.uci.edu/pub/ietf/http/. General discussions about HTTP 35 and the applications which use HTTP should take place on the mailing list. 38 The IETF takes no position regarding the validity or scope of any 39 intellectual property or other rights that might be claimed to 40 pertain to the implementation or use of the technology described in 41 this document or the extent to which any license under such rights 42 might or might not be available; neither does it represent that it 43 has made any effort to identify any such rights. Information on the 44 IETF's procedures with respect to rights in standards-track and 45 standards-related documentation can be found in BCP-9 [46]. Copies of 46 claims of rights made available for publication and any assurances of 47 licenses to be made available, or the result of an attempt made to 48 obtain a general license or permission for the use of such 49 proprietary rights by implementors or users of this specification can 50 be obtained from the IETF Secretariat. 52 Abstract 54 The Hypertext Transfer Protocol (HTTP) is an application-level 55 protocol for distributed, collaborative, hypermedia information 56 systems. It is a generic, stateless, protocol which can be used for 57 many tasks beyond its use for hypertext, such as name servers and 58 distributed object management systems, through extension of its 59 request methods, error codes and headers [47]. A feature of HTTP is 60 the typing and negotiation of data representation, allowing systems 61 to be built independently of the data being transferred. 63 HTTP has been in use by the World-Wide Web global information 64 initiative since 1990. This specification defines the protocol 65 referred to as "HTTP/1.1", and is an update to RFC 2068 [33]. 67 Copyright Notice 69 Copyright (C) The Internet Society (1998). All Rights Reserved. See 70 section 20 for the full copyright notice. 72 Table of Contents 74 HYPERTEXT TRANSFER PROTOCOL -- HTTP/1.1..............................1 76 Status of this Memo..................................................1 78 Abstract.............................................................2 80 Copyright Notice.....................................................2 82 Table of Contents....................................................3 84 1 Introduction ....................................................8 85 1.1 Purpose.......................................................8 86 1.2 Requirements ..................................................9 87 1.3 Terminology ...................................................9 88 1.4 Overall Operation ............................................12 90 2 Notational Conventions and Generic Grammar .....................14 91 2.1 Augmented BNF ................................................14 92 2.2 Basic Rules ..................................................16 94 3 Protocol Parameters ............................................17 95 3.1 HTTP Version .................................................17 96 3.2 Uniform Resource Identifiers .................................18 97 3.2.1 General Syntax ............................................18 98 3.2.2 http URL ..................................................19 99 3.2.3 URI Comparison ............................................19 100 3.3 Date/Time Formats ............................................20 101 3.3.1 Full Date .................................................20 102 3.3.2 Delta Seconds .............................................21 103 3.4 Character Sets ...............................................21 104 3.4.1 Missing Charset ...........................................22 105 3.5 Content Codings ..............................................22 106 3.6 Transfer Codings .............................................23 107 3.6.1 Chunked Transfer Coding ...................................24 108 3.7 Media Types ..................................................25 109 3.7.1 Canonicalization and Text Defaults ........................26 110 3.7.2 Multipart Types ...........................................26 111 3.8 Product Tokens ...............................................27 112 3.9 Quality Values ...............................................27 113 3.10 Language Tags ................................................28 114 3.11 Entity Tags ..................................................28 115 3.12 Range Units ..................................................29 117 4 HTTP Message ...................................................29 118 4.1 Message Types ................................................29 119 4.2 Message Headers ..............................................30 120 4.3 Message Body .................................................31 121 4.4 Message Length ...............................................31 122 4.5 General Header Fields ........................................33 123 5 Request ........................................................33 124 5.1 Request-Line .................................................33 125 5.1.1 Method ....................................................34 126 5.1.2 Request-URI ...............................................34 127 5.2 The Resource Identified by a Request .........................35 128 5.3 Request Header Fields ........................................36 130 6 Response .......................................................36 131 6.1 Status-Line ..................................................37 132 6.1.1 Status Code and Reason Phrase .............................37 133 6.2 Response Header Fields .......................................39 135 7 Entity .........................................................39 136 7.1 Entity Header Fields .........................................39 137 7.2 Entity Body ..................................................40 138 7.2.1 Type ......................................................40 139 7.2.2 Entity Length .............................................40 141 8 Connections ....................................................41 142 8.1 Persistent Connections .......................................41 143 8.1.1 Purpose ...................................................41 144 8.1.2 Overall Operation .........................................41 145 8.1.3 Proxy Servers .............................................43 146 8.1.4 Practical Considerations ..................................43 147 8.2 Message Transmission Requirements ............................44 148 8.2.1 Persistent Connections and Flow Control ...................44 149 8.2.2 Monitoring Connections for Error Status Messages ..........44 150 8.2.3 Use of the 100 (Continue) Status ..........................44 151 8.2.4 Client Behavior if Server Prematurely Closes Connection ...46 153 9 Method Definitions .............................................47 154 9.1 Safe and Idempotent Methods ..................................47 155 9.1.1 Safe Methods ..............................................47 156 9.1.2 Idempotent Methods ........................................48 157 9.2 OPTIONS ......................................................48 158 9.3 GET ..........................................................49 159 9.4 HEAD .........................................................49 160 9.5 POST .........................................................50 161 9.6 PUT ..........................................................51 162 9.7 DELETE .......................................................52 163 9.8 TRACE ........................................................52 164 9.9 CONNECT ......................................................52 166 10 Status Code Definitions .......................................53 167 10.1 Informational 1xx ............................................53 168 10.1.1 100 Continue ..............................................53 169 10.1.2 101 Switching Protocols ...................................53 170 10.2 Successful 2xx ...............................................54 171 10.2.1 200 OK ....................................................54 172 10.2.2 201 Created ...............................................54 173 10.2.3 202 Accepted ..............................................54 174 10.2.4 203 Non-Authoritative Information .........................55 175 10.2.5 204 No Content ............................................55 176 10.2.6 205 Reset Content .........................................55 177 10.2.7 206 Partial Content .......................................56 178 10.3 Redirection 3xx ..............................................56 179 10.3.1 300 Multiple Choices ......................................57 180 10.3.2 301 Moved Permanently .....................................57 181 10.3.3 302 Found .................................................57 182 10.3.4 303 See Other .............................................58 183 10.3.5 304 Not Modified ..........................................58 184 10.3.6 305 Use Proxy .............................................59 185 10.3.7 306 (Unused) ..............................................59 186 10.3.8 307 Temporary Redirect ....................................59 187 10.4 Client Error 4xx .............................................60 188 10.4.1 400 Bad Request ..........................................60 189 10.4.2 401 Unauthorized .........................................60 190 10.4.3 402 Payment Required .....................................61 191 10.4.4 403 Forbidden ............................................61 192 10.4.5 404 Not Found ............................................61 193 10.4.6 405 Method Not Allowed ...................................61 194 10.4.7 406 Not Acceptable .......................................61 195 10.4.8 407 Proxy Authentication Required ........................62 196 10.4.9 408 Request Timeout ......................................62 197 10.4.10 409 Conflict .............................................62 198 10.4.11 410 Gone .................................................62 199 10.4.12 411 Length Required ......................................63 200 10.4.13 412 Precondition Failed ..................................63 201 10.4.14 413 Request Entity Too Large .............................63 202 10.4.15 414 Request-URI Too Long .................................63 203 10.4.16 415 Unsupported Media Type ...............................64 204 10.4.17 416 Requested Range Not Satisfiable ......................64 205 10.4.18 417 Expectation Failed ...................................64 206 10.5 Server Error 5xx .............................................64 207 10.5.1 500 Internal Server Error .................................64 208 10.5.2 501 Not Implemented .......................................65 209 10.5.3 502 Bad Gateway ...........................................65 210 10.5.4 503 Service Unavailable ...................................65 211 10.5.5 504 Gateway Timeout .......................................65 212 10.5.6 505 HTTP Version Not Supported ............................65 214 11 Access Authentication .........................................65 216 12 Content Negotiation ...........................................66 217 12.1 Server-driven Negotiation ....................................66 218 12.2 Agent-driven Negotiation .....................................67 219 12.3 Transparent Negotiation ......................................68 221 13 Caching in HTTP ...............................................68 222 13.1.1 Cache Correctness .........................................69 223 13.1.2 Warnings ..................................................70 224 13.1.3 Cache-control Mechanisms ..................................71 225 13.1.4 Explicit User Agent Warnings ..............................72 226 13.1.5 Exceptions to the Rules and Warnings ......................72 227 13.1.6 Client-controlled Behavior ................................72 228 13.2 Expiration Model .............................................73 229 13.2.1 Server-Specified Expiration ...............................73 230 13.2.2 Heuristic Expiration ......................................74 231 13.2.3 Age Calculations ..........................................74 232 13.2.4 Expiration Calculations ...................................76 233 13.2.5 Disambiguating Expiration Values ..........................77 234 13.2.6 Disambiguating Multiple Responses .........................77 235 13.3 Validation Model .............................................78 236 13.3.1 Last-Modified Dates .......................................79 237 13.3.2 Entity Tag Cache Validators ...............................79 238 13.3.3 Weak and Strong Validators ................................79 239 13.3.4 Rules for When to Use Entity Tags and Last-Modified Dates .81 240 13.3.5 Non-validating Conditionals ...............................83 241 13.4 Response Cacheability ........................................83 242 13.5 Constructing Responses From Caches ...........................84 243 13.5.1 End-to-end and Hop-by-hop Headers .........................84 244 13.5.2 Non-modifiable Headers ....................................85 245 13.5.3 Combining Headers .........................................86 246 13.5.4 Combining Byte Ranges .....................................87 247 13.6 Caching Negotiated Responses .................................87 248 13.7 Shared and Non-Shared Caches .................................88 249 13.8 Errors or Incomplete Response Cache Behavior .................89 250 13.9 Side Effects of GET and HEAD .................................89 251 13.10 Invalidation After Updates or Deletions ....................89 252 13.11 Write-Through Mandatory ....................................90 253 13.12 Cache Replacement ..........................................90 254 13.13 History Lists ..............................................91 256 14 Header Field Definitions ......................................91 257 14.1 Accept .......................................................91 258 14.2 Accept-Charset ...............................................93 259 14.3 Accept-Encoding ..............................................94 260 14.4 Accept-Language ..............................................95 261 14.5 Accept-Ranges ................................................96 262 14.6 Age ..........................................................97 263 14.7 Allow ........................................................97 264 14.8 Authorization ................................................98 265 14.9 Cache-Control ................................................98 266 14.9.1 What is Cacheable ........................................100 267 14.9.2 What May be Stored by Caches .............................101 268 14.9.3 Modifications of the Basic Expiration Mechanism ..........101 269 14.9.4 Cache Revalidation and Reload Controls ...................103 270 14.9.5 No-Transform Directive ...................................105 271 14.9.6 Cache Control Extensions .................................106 272 14.10 Connection ................................................106 273 14.11 Content-Encoding ..........................................107 274 14.12 Content-Language ..........................................108 275 14.13 Content-Length ............................................109 276 14.14 Content-Location ..........................................109 277 14.15 Content-MD5 ...............................................110 278 14.16 Content-Range .............................................111 279 14.17 Content-Type ..............................................113 280 14.18 Date ......................................................113 281 14.18.1 Clockless Origin Server Operation .......................114 282 14.19 ETag ......................................................114 283 14.20 Expect ....................................................115 284 14.21 Expires ...................................................115 285 14.22 From ......................................................116 286 14.23 Host ......................................................117 287 14.24 If-Match ..................................................118 288 14.25 If-Modified-Since .........................................119 289 14.26 If-None-Match .............................................120 290 14.27 If-Range ..................................................121 291 14.28 If-Unmodified-Since .......................................122 292 14.29 Last-Modified .............................................122 293 14.30 Location ..................................................123 294 14.31 Max-Forwards ..............................................123 295 14.32 Pragma ....................................................124 296 14.33 Proxy-Authenticate ........................................124 297 14.34 Proxy-Authorization .......................................125 298 14.35 Range .....................................................125 299 14.35.1 Byte Ranges ............................................125 300 14.35.2 Range Retrieval Requests ...............................127 301 14.36 Referer ...................................................127 302 14.37 Retry-After ...............................................128 303 14.38 Server ....................................................128 304 14.39 TE ........................................................129 305 14.40 Trailer ...................................................130 306 14.41 Transfer-Encoding...........................................130 307 14.42 Upgrade ...................................................131 308 14.43 User-Agent ................................................132 309 14.44 Vary ......................................................132 310 14.45 Via .......................................................133 311 14.46 Warning ...................................................134 312 14.47 WWW-Authenticate ..........................................136 314 15 Security Considerations ........................................136 315 15.1 Personal Information.....................................137 316 15.1.1 Abuse of Server Log Information ..........................137 317 15.1.2 Transfer of Sensitive Information ........................137 318 15.1.3 Encoding Sensitive Information in URI's ..................138 319 15.1.4 Privacy Issues Connected to Accept Headers ...............138 320 15.2 Attacks Based On File and Path Names ........................139 321 15.3 DNS Spoofing ................................................139 322 15.4 Location Headers and Spoofing ...............................140 323 15.5 Content-Disposition Issues ..................................140 324 15.6 Authentication Credentials and Idle Clients .................140 325 15.7 Proxies and Caching .........................................141 326 15.7.1 Denial of Service Attacks on Proxies.....................142 328 16 Acknowledgments ..............................................142 330 17 References ...................................................143 332 18 Authors' Addresses ...........................................147 334 19 Appendices ...................................................148 335 19.1 Internet Media Type message/http and application/http .......148 336 19.2 Internet Media Type multipart/byteranges ....................149 337 19.3 Tolerant Applications .......................................150 338 19.4 Differences Between HTTP Entities and RFC 2045 Entities .....151 339 19.4.1 MIME-Version .............................................151 340 19.4.2 Conversion to Canonical Form .............................151 341 19.4.3 Conversion of Date Formats ...............................152 342 19.4.4 Introduction of Content-Encoding .........................152 343 19.4.5 No Content-Transfer-Encoding .............................152 344 19.4.6 Introduction of Transfer-Encoding ........................152 345 19.4.7 MHTML and Line Length Limitations ........................153 346 19.5 Additional Features .........................................153 347 19.5.1 Content-Disposition ......................................153 348 19.6 Compatibility with Previous Versions ........................154 349 19.6.1 Changes from HTTP/1.0 ....................................155 350 19.6.2 Compatibility with HTTP/1.0 Persistent Connections .......155 351 19.6.3 Changes from RFC 2068 ....................................156 352 19.7 Notes to the RFC Editor and IANA ............................158 353 19.7.1 Transfer-coding Values ...................................158 354 19.7.2 Definition of application/http ...........................159 355 19.7.3 Addition of "identity" content-coding to content-coding 356 Registry 159 358 20 Full Copyright Statement .....................................159 360 21 Index ........................................................160 362 1 Introduction 364 1.1 Purpose 366 The Hypertext Transfer Protocol (HTTP) is an application-level 367 protocol for distributed, collaborative, hypermedia information 368 systems. HTTP has been in use by the World-Wide Web global 369 information initiative since 1990. The first version of HTTP, 370 referred to as HTTP/0.9, was a simple protocol for raw data transfer 371 across the Internet. HTTP/1.0, as defined by RFC 1945 [6], improved 372 the protocol by allowing messages to be in the format of MIME-like 373 messages, containing metainformation about the data transferred and 374 modifiers on the request/response semantics. However, HTTP/1.0 does 375 not sufficiently take into consideration the effects of hierarchical 376 proxies, caching, the need for persistent connections, or virtual 377 hosts. In addition, the proliferation of incompletely-implemented 378 applications calling themselves "HTTP/1.0" has necessitated a 379 protocol version change in order for two communicating applications 380 to determine each other's true capabilities. 382 This specification defines the protocol referred to as "HTTP/1.1". 383 This protocol includes more stringent requirements than HTTP/1.0 in 384 order to ensure reliable implementation of its features. 386 Practical information systems require more functionality than simple 387 retrieval, including search, front-end update, and annotation. HTTP 388 allows an open-ended set of methods and headers that indicate the 389 purpose of a request [47]. It builds on the discipline of reference 390 provided by the Uniform Resource Identifier (URI) [3], as a location 391 (URL) [4] or name (URN) [20], for indicating the resource to which a 392 method is to be applied. Messages are passed in a format similar to 393 that used by Internet mail [9] as defined by the Multipurpose 394 Internet Mail Extensions (MIME) [7]. 396 HTTP is also used as a generic protocol for communication between 397 user agents and proxies/gateways to other Internet systems, including 398 those supported by the SMTP [16], NNTP [13], FTP [18], Gopher [2], 399 and WAIS [10] protocols. In this way, HTTP allows basic hypermedia 400 access to resources available from diverse applications. 402 1.2 Requirements 404 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 405 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 406 document are to be interpreted as described in RFC 2119 [34]. 408 An implementation is not compliant if it fails to satisfy one or more 409 of the MUST or REQUIRED level requirements for the protocols it 410 implements. An implementation that satisfies all the MUST or REQUIRED 411 level and all the SHOULD level requirements for its protocols is said 412 to be "unconditionally compliant"; one that satisfies all the MUST 413 level requirements but not all the SHOULD level requirements for its 414 protocols is said to be "conditionally compliant." 416 1.3 Terminology 418 This specification uses a number of terms to refer to the roles 419 played by participants in, and objects of, the HTTP communication. 421 connection 422 A transport layer virtual circuit established between two programs 423 for the purpose of communication. 425 message 426 The basic unit of HTTP communication, consisting of a structured 427 sequence of octets matching the syntax defined in section 4 and 428 transmitted via the connection. 430 request 431 An HTTP request message, as defined in section 5. 433 response 434 An HTTP response message, as defined in section 6. 436 resource 437 A network data object or service that can be identified by a URI, 438 as defined in section 3.2. Resources may be available in multiple 439 representations (e.g. multiple languages, data formats, size, and 440 resolutions) or vary in other ways. 442 entity 443 The information transferred as the payload of a request or 444 response. An entity consists of metainformation in the form of 445 entity-header fields and content in the form of an entity-body, as 446 described in section 7. 448 representation 449 An entity included with a response that is subject to content 450 negotiation, as described in section 12. There may exist multiple 451 representations associated with a particular response status. 453 content negotiation 454 The mechanism for selecting the appropriate representation when 455 servicing a request, as described in section 12. The 456 representation of entities in any response can be negotiated 457 (including error responses). 459 variant 460 A resource may have one, or more than one, representation(s) 461 associated with it at any given instant. Each of these 462 representations is termed a `variant.' Use of the term `variant' 463 does not necessarily imply that the resource is subject to content 464 negotiation. 466 client 467 A program that establishes connections for the purpose of sending 468 requests. 470 user agent 471 The client which initiates a request. These are often browsers, 472 editors, spiders (web-traversing robots), or other end user tools. 474 server 475 An application program that accepts connections in order to 476 service requests by sending back responses. Any given program may 477 be capable of being both a client and a server; our use of these 478 terms refers only to the role being performed by the program for a 479 particular connection, rather than to the program's capabilities 480 in general. Likewise, any server may act as an origin server, 481 proxy, gateway, or tunnel, switching behavior based on the nature 482 of each request. 484 origin server 485 The server on which a given resource resides or is to be created. 487 proxy 488 An intermediary program which acts as both a server and a client 489 for the purpose of making requests on behalf of other clients. 490 Requests are serviced internally or by passing them on, with 491 possible translation, to other servers. A proxy MUST implement 492 both the client and server requirements of this specification. A 493 "transparent proxy" is a proxy that does not modify the request or 494 response beyond what is required for proxy authentication and 495 identification. A "non-transparent proxy" is a proxy that modifies 496 the request or response in order to provide some added service to 497 the user agent, such as group annotation services, media type 498 transformation, protocol reduction, or anonymity filtering. Except 499 where either transparent or non-transparent behavior is explicitly 500 stated, the HTTP proxy requirements apply to both types of 501 proxies. 503 gateway 504 A server which acts as an intermediary for some other server. 505 Unlike a proxy, a gateway receives requests as if it were the 506 origin server for the requested resource; the requesting client 507 may not be aware that it is communicating with a gateway. 509 tunnel 510 An intermediary program which is acting as a blind relay between 511 two connections. Once active, a tunnel is not considered a party 512 to the HTTP communication, though the tunnel may have been 513 initiated by an HTTP request. The tunnel ceases to exist when both 514 ends of the relayed connections are closed. 516 cache 517 A program's local store of response messages and the subsystem 518 that controls its message storage, retrieval, and deletion. A 519 cache stores cacheable responses in order to reduce the response 520 time and network bandwidth consumption on future, equivalent 521 requests. Any client or server may include a cache, though a cache 522 cannot be used by a server that is acting as a tunnel. 524 cacheable 525 A response is cacheable if a cache is allowed to store a copy of 526 the response message for use in answering subsequent requests. The 527 rules for determining the cacheability of HTTP responses are 528 defined in section 13. Even if a resource is cacheable, there may 529 be additional constraints on whether a cache can use the cached 530 copy for a particular request. 532 first-hand 533 A response is first-hand if it comes directly and without 534 unnecessary delay from the origin server, perhaps via one or more 535 proxies. A response is also first-hand if its validity has just 536 been checked directly with the origin server. 538 explicit expiration time 539 The time at which the origin server intends that an entity should 540 no longer be returned by a cache without further validation. 542 heuristic expiration time 543 An expiration time assigned by a cache when no explicit expiration 544 time is available. 546 age 547 The age of a response is the time since it was sent by, or 548 successfully validated with, the origin server. 550 freshness lifetime 551 The length of time between the generation of a response and its 552 expiration time. 554 fresh 555 A response is fresh if its age has not yet exceeded its freshness 556 lifetime. 558 stale 559 A response is stale if its age has passed its freshness lifetime. 561 semantically transparent 562 A cache behaves in a "semantically transparent" manner, with 563 respect to a particular response, when its use affects neither the 564 requesting client nor the origin server, except to improve 565 performance. When a cache is semantically transparent, the client 566 receives exactly the same response (except for hop-by-hop headers) 567 that it would have received had its request been handled directly 568 by the origin server. 570 validator 571 A protocol element (e.g., an entity tag or a Last-Modified time) 572 that is used to find out whether a cache entry is an equivalent 573 copy of an entity. 575 upstream/downstream 576 Upstream and downstream describe the flow of a message: all 577 messages flow from upstream to downstream. 579 inbound/outbound 580 Inbound and outbound refer to the request and response paths for 581 messages: "inbound" means "traveling toward the origin server", 582 and "outbound" means "traveling toward the user agent" 584 1.4 Overall Operation 586 The HTTP protocol is a request/response protocol. A client sends a 587 request to the server in the form of a request method, URI, and 588 protocol version, followed by a MIME-like message containing request 589 modifiers, client information, and possible body content over a 590 connection with a server. The server responds with a status line, 591 including the message's protocol version and a success or error code, 592 followed by a MIME-like message containing server information, entity 593 metainformation, and possible entity-body content. The relationship 594 between HTTP and MIME is described in appendix 19.4. 596 Most HTTP communication is initiated by a user agent and consists of 597 a request to be applied to a resource on some origin server. In the 598 simplest case, this may be accomplished via a single connection (v) 599 between the user agent (UA) and the origin server (O). 601 request chain ------------------------> 602 UA -------------------v------------------- O 603 <----------------------- response chain 605 A more complicated situation occurs when one or more intermediaries 606 are present in the request/response chain. There are three common 607 forms of intermediary: proxy, gateway, and tunnel. A proxy is a 608 forwarding agent, receiving requests for a URI in its absolute form, 609 rewriting all or part of the message, and forwarding the reformatted 610 request toward the server identified by the URI. A gateway is a 611 receiving agent, acting as a layer above some other server(s) and, if 612 necessary, translating the requests to the underlying server's 613 protocol. A tunnel acts as a relay point between two connections 614 without changing the messages; tunnels are used when the 615 communication needs to pass through an intermediary (such as a 616 firewall) even when the intermediary cannot understand the contents 617 of the messages. 619 request chain --------------------------------------> 620 UA -----v----- A -----v----- B -----v----- C -----v----- O 621 <------------------------------------- response chain 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 This distinction is important because some HTTP communication options 627 may apply only to the connection with the nearest, non-tunnel 628 neighbor, only to the end-points of the chain, or to all connections 629 along the chain. Although the diagram is linear, each participant may 630 be engaged in multiple, simultaneous communications. For example, B 631 may be receiving requests from many clients other than A, and/or 632 forwarding requests to servers other than C, at the same time that it 633 is handling A's request. 635 Any party to the communication which is not acting as a tunnel may 636 employ an internal cache for handling requests. The effect of a cache 637 is that the request/response chain is shortened if one of the 638 participants along the chain has a cached response applicable to that 639 request. The following illustrates the resulting chain if B has a 640 cached copy of an earlier response from O (via C) for a request which 641 has not been cached by UA or A. 643 request chain ----------> 644 UA -----v----- A -----v----- B - - - - - - C - - - - - - O 645 <--------- response chain 647 Not all responses are usefully cacheable, and some requests may 648 contain modifiers which place special requirements on cache behavior. 649 HTTP requirements for cache behavior and cacheable responses are 650 defined in section 13. 652 In fact, there are a wide variety of architectures and configurations 653 of caches and proxies currently being experimented with or deployed 654 across the World Wide Web. These systems include national hierarchies 655 of proxy caches to save transoceanic bandwidth, systems that 656 broadcast or multicast cache entries, organizations that distribute 657 subsets of cached data via CD-ROM, and so on. HTTP systems are used 658 in corporate intranets over high-bandwidth links, and for access via 659 PDAs with low-power radio links and intermittent connectivity. The 660 goal of HTTP/1.1 is to support the wide diversity of configurations 661 already deployed while introducing protocol constructs that meet the 662 needs of those who build web applications that require high 663 reliability and, failing that, at least reliable indications of 664 failure. 666 HTTP communication usually takes place over TCP/IP connections. The 667 default port is TCP 80 [19], but other ports can be used. This does 668 not preclude HTTP from being implemented on top of any other protocol 669 on the Internet, or on other networks. HTTP only presumes a reliable 670 transport; any protocol that provides such guarantees can be used; 671 the mapping of the HTTP/1.1 request and response structures onto the 672 transport data units of the protocol in question is outside the scope 673 of this specification. 675 In HTTP/1.0, most implementations used a new connection for each 676 request/response exchange. In HTTP/1.1, a connection may be used for 677 one or more request/response exchanges, although connections may be 678 closed for a variety of reasons (see section 8.1). 680 2 Notational Conventions and Generic Grammar 682 2.1 Augmented BNF 684 All of the mechanisms specified in this document are described in 685 both prose and an augmented Backus-Naur Form (BNF) similar to that 686 used by RFC 822 [9]. Implementors will need to be familiar with the 687 notation in order to understand this specification. The augmented BNF 688 includes the following constructs: 690 name = definition 691 The name of a rule is simply the name itself (without any 692 enclosing "<" and ">") and is separated from its definition by the 693 equal "=" character. White space is only significant in that 694 indentation of continuation lines is used to indicate a rule 695 definition that spans more than one line. Certain basic rules are 696 in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle 697 brackets are used within definitions whenever their presence will 698 facilitate discerning the use of rule names. 700 "literal" 701 Quotation marks surround literal text. Unless stated otherwise, 702 the text is case-insensitive. 704 rule1 | rule2 705 Elements separated by a bar ("|") are alternatives, e.g., "yes | 706 no" will accept yes or no. 708 (rule1 rule2) 709 Elements enclosed in parentheses are treated as a single element. 711 Thus, "(elem (foo | bar) elem)" allows the token sequences 712 "elem foo elem" and "elem bar elem". 714 *rule 715 The character "*" preceding an element indicates repetition. The 716 full form is "*element" indicating at least and at most 717 occurrences of element. Default values are 0 and infinity so 718 that "*(element)" allows any number, including zero; "1*element" 719 requires at least one; and "1*2element" allows one or two. 721 [rule] 722 Square brackets enclose optional elements; "[foo bar]" is 723 equivalent to "*1(foo bar)". 725 N rule 726 Specific repetition: "(element)" is equivalent to 727 "*(element)"; that is, exactly occurrences of (element). 728 Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three 729 alphabetic characters. 731 #rule 732 A construct "#" is defined, similar to "*", for defining lists of 733 elements. The full form is "#element" indicating at least 734 and at most elements, each separated by one or more commas 735 (",") and OPTIONAL linear white space (LWS). This makes the usual 736 form of lists very easy; a rule such as 737 ( *LWS element *( *LWS "," *LWS element )) 738 can be shown as 739 1#element 740 Wherever this construct is used, null elements are allowed, but do 741 not contribute to the count of elements present. That is, 742 "(element), , (element) " is permitted, but counts as only two 743 elements. Therefore, where at least one element is required, at 744 least one non-null element MUST be present. Default values are 0 745 and infinity so that "#element" allows any number, including zero; 746 "1#element" requires at least one; and "1#2element" allows one or 747 two. 749 ; comment 750 A semi-colon, set off some distance to the right of rule text, 751 starts a comment that continues to the end of line. This is a 752 simple way of including useful notes in parallel with the 753 specifications. 755 implied *LWS 756 The grammar described by this specification is word-based. Except 757 where noted otherwise, linear white space (LWS) can be included 758 between any two adjacent words (token or quoted-string), and 759 between adjacent words and separators, without changing the 760 interpretation of a field. At least one delimiter (LWS and/or 761 separators) MUST exist between any two tokens (for the definition 762 of "token" below), since they would otherwise be interpreted as a 763 single token. 765 2.2 Basic Rules 767 The following rules are used throughout this specification to 768 describe basic parsing constructs. The US-ASCII coded character set 769 is defined by ANSI X3.4-1986 [21]. 771 OCTET = 772 CHAR = 773 UPALPHA = 774 LOALPHA = 775 ALPHA = UPALPHA | LOALPHA 776 DIGIT = 777 CTL = 779 CR = 780 LF = 781 SP = 782 HT = 783 <"> = 785 HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all 786 protocol elements except the entity-body (see appendix 19.3 for 787 tolerant applications). The end-of-line marker within an entity-body 788 is defined by its associated media type, as described in section 3.7. 790 CRLF = CR LF 792 HTTP/1.1 header field values can be folded onto multiple lines if the 793 continuation line begins with a space or horizontal tab. All linear 794 white space, including folding, has the same semantics as SP. A 795 recipient MAY replace any linear white space with a single SP before 796 interpreting the field value or forwarding the message downstream. 798 LWS = [CRLF] 1*( SP | HT ) 800 The TEXT rule is only used for descriptive field contents and values 801 that are not intended to be interpreted by the message parser. Words 802 of *TEXT MAY contain characters from character sets other than ISO- 803 8859-1 [22] only when encoded according to the rules of RFC 2047 804 [14]. 806 TEXT = 809 A CRLF is allowed in the definition of TEXT only as part of a header 810 field continuation. It is expected that the folding LWS will be 811 replaced with a single SP before interpretation of the TEXT value. 813 Hexadecimal numeric characters are used in several protocol elements. 815 HEX = "A" | "B" | "C" | "D" | "E" | "F" 816 | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT 818 Many HTTP/1.1 header field values consist of words separated by LWS 819 or special characters. These special characters MUST be in a quoted 820 string to be used within a parameter value (as defined in section 821 3.6). 823 token = 1* 824 separators = "(" | ")" | "<" | ">" | "@" 825 | "," | ";" | ":" | "\" | <"> 826 | "/" | "[" | "]" | "?" | "=" 827 | "{" | "}" | SP | HT 829 Comments can be included in some HTTP header fields by surrounding 830 the comment text with parentheses. Comments are only allowed in 831 fields containing "comment" as part of their field value definition. 832 In all other fields, parentheses are considered part of the field 833 value. 835 comment = "(" *( ctext | quoted-pair | comment ) ")" 836 ctext = 838 A string of text is parsed as a single word if it is quoted using 839 double-quote marks. 841 quoted-string = ( <"> *(qdtext | quoted-pair ) <"> ) 842 qdtext = > 844 The backslash character ("\") MAY be used as a single-character 845 quoting mechanism only within quoted-string and comment constructs. 847 quoted-pair = "\" CHAR 849 3 Protocol Parameters 851 3.1 HTTP Version 853 HTTP uses a "." numbering scheme to indicate versions 854 of the protocol. The protocol versioning policy is intended to allow 855 the sender to indicate the format of a message and its capacity for 856 understanding further HTTP communication, rather than the features 857 obtained via that communication. No change is made to the version 858 number for the addition of message components which do not affect 859 communication behavior or which only add to extensible field values. 860 The number is incremented when the changes made to the 861 protocol add features which do not change the general message parsing 862 algorithm, but which may add to the message semantics and imply 863 additional capabilities of the sender. The number is 864 incremented when the format of a message within the protocol is 865 changed. See RFC 2145 [36] for a fuller explanation. 867 The version of an HTTP message is indicated by an HTTP-Version field 868 in the first line of the message. 870 HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT 872 Note that the major and minor numbers MUST be treated as separate 873 integers and that each MAY be incremented higher than a single digit. 874 Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in turn is 875 lower than HTTP/12.3. Leading zeros MUST be ignored by recipients and 876 MUST NOT be sent. 878 An application that sends a request or response message that includes 879 HTTP-Version of "HTTP/1.1" MUST be at least conditionally compliant 880 with this specification. Applications that are at least conditionally 881 compliant with this specification SHOULD use an HTTP-Version of 882 "HTTP/1.1" in their messages, and MUST do so for any message that is 883 not compatible with HTTP/1.0. For more details on when to send 884 specific HTTP-Version values, see RFC 2145 [36]. 886 The HTTP version of an application is the highest HTTP version for 887 which the application is at least conditionally compliant. 889 Proxy and gateway applications need to be careful when forwarding 890 messages in protocol versions different from that of the application. 891 Since the protocol version indicates the protocol capability of the 892 sender, a proxy/gateway MUST NOT send a message with a version 893 indicator which is greater than its actual version. If a higher 894 version request is received, the proxy/gateway MUST either downgrade 895 the request version, or respond with an error, or switch to tunnel 896 behavior. 898 Due to interoperability problems with HTTP/1.0 proxies discovered 899 since the publication of RFC 2068[33], caching proxies MUST, gateways 900 MAY, and tunnels MUST NOT upgrade the request to the highest version 901 they support. The proxy/gateway's response to that request MUST be in 902 the same major version as the request. 904 Note: Converting between versions of HTTP may involve 905 modification of header fields required or forbidden by the 906 versions involved. 908 3.2 Uniform Resource Identifiers 910 URIs have been known by many names: WWW addresses, Universal Document 911 Identifiers, Universal Resource Identifiers [3], and finally the 912 combination of Uniform Resource Locators (URL) [4] and Names (URN) 913 [20]. As far as HTTP is concerned, Uniform Resource Identifiers are 914 simply formatted strings which identify--via name, location, or any 915 other characteristic--a resource. 917 3.2.1 General Syntax 919 URIs in HTTP can be represented in absolute form or relative to some 920 known base URI [11], depending upon the context of their use. The two 921 forms are differentiated by the fact that absolute URIs always begin 922 with a scheme name followed by a colon. For definitive information on 923 URL syntax and semantics, see "Uniform Resource Identifiers (URI): 924 Generic Syntax and Semantics," RFC 2396 [42] (which replaces RFCs 925 1738 [4] and RFC 1808 [11]). This specification adopts the 926 definitions of "URI-reference", "absoluteURI", "relativeURI", "port", 927 "host","abs_path", "rel_path", and "authority" from that 928 specification. 930 The HTTP protocol does not place any a priori limit on the length of 931 a URI. Servers MUST be able to handle the URI of any resource they 932 serve, and SHOULD be able to handle URIs of unbounded length if they 933 provide GET-based forms that could generate such URIs. A server 934 SHOULD return 414 (Request-URI Too Long) status if a URI is longer 935 than the server can handle (see section 10.4.15). 937 Note: Servers ought to be cautious about depending on URI 938 lengths above 255 bytes, because some older client or proxy 939 implementations might not properly support these lengths. 941 3.2.2 http URL 943 The "http" scheme is used to locate network resources via the HTTP 944 protocol. This section defines the scheme-specific syntax and 945 semantics for http URLs. 947 http_URL = "http:" "//" host [ ":" port ] [ abs_path ] 949 If the port is empty or not given, port 80 is assumed. The semantics 950 are that the identified resource is located at the server listening 951 for TCP connections on that port of that host, and the Request-URI 952 for the resource is abs_path (section 5.1.2). The use of IP addresses 953 in URLs SHOULD be avoided whenever possible (see RFC 1900 [24]). If 954 the abs_path is not present in the URL, it MUST be given as "/" when 955 used as a Request-URI for a resource (section 5.1.2). If a proxy 956 receives a host name which is not a fully qualified domain name, it 957 MAY add its domain to the host name it received. If a proxy receives 958 a fully qualified domain name, the proxy MUST NOT change the host 959 name. 961 3.2.3 URI Comparison 963 When comparing two URIs to decide if they match or not, a client 964 SHOULD use a case-sensitive octet-by-octet comparison of the entire 965 URIs, with these exceptions: 967 . A port that is empty or not given is equivalent to the default 968 port for that URI-reference; 970 . Comparisons of host names MUST be case-insensitive; 972 . Comparisons of scheme names MUST be case-insensitive; 974 . An empty abs_path is equivalent to an abs_path of "/". 976 Characters other than those in the "reserved" and "unsafe" sets (see 977 section 3.2) are equivalent to their ""%" HEX HEX" encoding. 979 For example, the following three URIs are equivalent: 981 http://abc.com:80/~smith/home.html 982 http://ABC.com/%7Esmith/home.html 983 http://ABC.com:/%7esmith/home.html 985 3.3 Date/Time Formats 987 3.3.1 Full Date 989 HTTP applications have historically allowed three different formats 990 for the representation of date/time stamps: 992 Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123 993 Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036 994 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format 996 The first format is preferred as an Internet standard and represents 997 a fixed-length subset of that defined by RFC 1123 [8] (an update to 998 RFC 822 [9]). The second format is in common use, but is based on the 999 obsolete RFC 850 [12] date format and lacks a four-digit year. 1000 HTTP/1.1 clients and servers that parse the date value MUST accept 1001 all three formats (for compatibility with HTTP/1.0), though they MUST 1002 only generate the RFC 1123 format for representing HTTP-date values 1003 in header fields. See section 19.3 for further information. 1005 Note: Recipients of date values are encouraged to be robust in 1006 accepting date values that may have been sent by non-HTTP 1007 applications, as is sometimes the case when retrieving or 1008 posting messages via proxies/gateways to SMTP or NNTP. 1010 All HTTP date/time stamps MUST be represented in Greenwich Mean Time 1011 (GMT), without exception. For the purposes of HTTP, GMT is exactly 1012 equal to UTC (Coordinated Universal Time). This is indicated in the 1013 first two formats by the inclusion of "GMT" as the three-letter 1014 abbreviation for time zone, and MUST be assumed when reading the 1015 asctime format. HTTP-date is case sensitive and MUST NOT include 1016 additional LWS beyond that specifically included as SP in the 1017 grammar. 1019 HTTP-date = rfc1123-date | rfc850-date | asctime-date 1020 rfc1123-date = wkday "," SP date1 SP time SP "GMT" 1021 rfc850-date = weekday "," SP date2 SP time SP "GMT" 1022 asctime-date = wkday SP date3 SP time SP 4DIGIT 1023 date1 = 2DIGIT SP month SP 4DIGIT 1024 ; day month year (e.g., 02 Jun 1982) 1025 date2 = 2DIGIT "-" month "-" 2DIGIT 1026 ; day-month-year (e.g., 02-Jun-82) 1027 date3 = month SP ( 2DIGIT | ( SP 1DIGIT )) 1028 ; month day (e.g., Jun 2) 1029 time = 2DIGIT ":" 2DIGIT ":" 2DIGIT 1030 ; 00:00:00 - 23:59:59 1031 wkday = "Mon" | "Tue" | "Wed" 1032 | "Thu" | "Fri" | "Sat" | "Sun" 1033 weekday = "Monday" | "Tuesday" | "Wednesday" 1034 | "Thursday" | "Friday" | "Saturday" | "Sunday" 1035 month = "Jan" | "Feb" | "Mar" | "Apr" 1036 | "May" | "Jun" | "Jul" | "Aug" 1037 | "Sep" | "Oct" | "Nov" | "Dec" 1039 Note: HTTP requirements for the date/time stamp format apply 1040 only to their usage within the protocol stream. Clients and 1041 servers are not required to use these formats for user 1042 presentation, request logging, etc. 1044 3.3.2 Delta Seconds 1046 Some HTTP header fields allow a time value to be specified as an 1047 integer number of seconds, represented in decimal, after the time 1048 that the message was received. 1050 delta-seconds = 1*DIGIT 1052 3.4 Character Sets 1054 HTTP uses the same definition of the term "character set" as that 1055 described for MIME: 1057 The term "character set" is used in this document to refer to a 1058 method used with one or more tables to convert a sequence of octets 1059 into a sequence of characters. Note that unconditional conversion in 1060 the other direction is not required, in that not all characters may 1061 be available in a given character set and a character set may provide 1062 more than one sequence of octets to represent a particular character. 1063 This definition is intended to allow various kinds of character 1064 encoding, from simple single-table mappings such as US-ASCII to 1065 complex table switching methods such as those that use ISO-2022's 1066 techniques. However, the definition associated with a MIME character 1067 set name MUST fully specify the mapping to be performed from octets 1068 to characters. In particular, use of external profiling information 1069 to determine the exact mapping is not permitted. 1071 Note: This use of the term "character set" is more commonly 1072 referred to as a "character encoding." However, since HTTP and 1073 MIME share the same registry, it is important that the 1074 terminology also be shared. 1076 HTTP character sets are identified by case-insensitive tokens. The 1077 complete set of tokens is defined by the IANA Character Set registry 1078 [19]. 1080 charset = token 1082 Although HTTP allows an arbitrary token to be used as a charset 1083 value, any token that has a predefined value within the IANA 1084 Character Set registry [19] MUST represent the character set defined 1085 by that registry. Applications SHOULD limit their use of character 1086 sets to those defined by the IANA registry. 1088 Implementors should be aware of IETF character set requirements [38] 1089 [41]. 1091 3.4.1 Missing Charset 1093 Some HTTP/1.0 software has interpreted a Content-Type header without 1094 charset parameter incorrectly to mean "recipient should guess." 1095 Senders wishing to defeat this behavior MAY include a charset 1096 parameter even when the charset is ISO-8859-1 and SHOULD do so when 1097 it is known that it will not confuse the recipient. 1099 Unfortunately, some older HTTP/1.0 clients did not deal properly with 1100 an explicit charset parameter. HTTP/1.1 recipients MUST respect the 1101 charset label provided by the sender; and those user agents that have 1102 a provision to "guess" a charset MUST use the charset from the 1103 content-type field if they support that charset, rather than the 1104 recipient's preference, when initially displaying a document. See 1105 section 3.7.1. 1107 3.5 Content Codings 1109 Content coding values indicate an encoding transformation that has 1110 been or can be applied to an entity. Content codings are primarily 1111 used to allow a document to be compressed or otherwise usefully 1112 transformed without losing the identity of its underlying media type 1113 and without loss of information. Frequently, the entity is stored in 1114 coded form, transmitted directly, and only decoded by the recipient. 1116 content-coding = token 1118 All content-coding values are case-insensitive. HTTP/1.1 uses 1119 content-coding values in the Accept-Encoding (section 14.3) and 1120 Content-Encoding (section 14.11) header fields. Although the value 1121 describes the content-coding, what is more important is that it 1122 indicates what decoding mechanism will be required to remove the 1123 encoding. 1125 The Internet Assigned Numbers Authority (IANA) acts as a registry for 1126 content-coding value tokens. Initially, the registry contains the 1127 following tokens: 1129 gzip An encoding format produced by the file compression program 1130 "gzip" (GNU zip) as described in RFC 1952 [25]. This format is a 1131 Lempel-Ziv coding (LZ77) with a 32 bit CRC. 1133 compress 1134 The encoding format produced by the common UNIX file compression 1135 program "compress". This format is an adaptive Lempel-Ziv-Welch 1136 coding (LZW). 1138 Use of program names for the identification of encoding formats 1139 is not desirable and is discouraged for future encodings. Their 1140 use here is representative of historical practice, not good 1141 design. For compatibility with previous implementations of HTTP, 1142 applications SHOULD consider "x-gzip" and "x-compress" to be 1143 equivalent to "gzip" and "compress" respectively. 1145 deflate 1146 The "zlib" format defined in RFC 1950 [31] in combination with 1147 the "deflate" compression mechanism described in RFC 1951 [29]. 1149 identity 1150 The default (identity) encoding; the use of no transformation 1151 whatsoever. This content-coding is used only in the Accept- 1152 Encoding header, and SHOULD NOT be used in the Content-Encoding 1153 header. 1155 New content-coding value tokens SHOULD be registered; to allow 1156 interoperability between clients and servers, specifications of the 1157 content coding algorithms needed to implement a new value SHOULD be 1158 publicly available and adequate for independent implementation, and 1159 conform to the purpose of content coding defined in this section. 1161 3.6 Transfer Codings 1163 Transfer-coding values are used to indicate an encoding 1164 transformation that has been, can be, or may need to be applied to an 1165 entity-body in order to ensure "safe transport" through the network. 1166 This differs from a content coding in that the transfer-coding is a 1167 property of the message, not of the original entity. 1169 transfer-coding = "chunked" | transfer-extension 1170 transfer-extension = token *( ";" parameter ) 1172 Parameters are in the form of attribute/value pairs. 1174 parameter = attribute "=" value 1175 attribute = token 1176 value = token | quoted-string 1178 All transfer-coding values are case-insensitive. HTTP/1.1 uses 1179 transfer-coding values in the TE header field (section 14.39) and in 1180 the Transfer-Encoding header field (section 14.41). 1182 Whenever a transfer-coding is applied to a message-body, the set of 1183 transfer-codings MUST include "chunked", unless the message is 1184 terminated by closing the connection. When the "chunked" transfer- 1185 coding is used, it MUST be the last transfer-coding applied to the 1186 message-body. The "chunked" transfer-coding MUST NOT be applied more 1187 than once to a message-body. These rules allow the recipient to 1188 determine the transfer-length of the message (section 4.4). 1190 Transfer-codings are analogous to the Content-Transfer-Encoding 1191 values of MIME [7], which were designed to enable safe transport of 1192 binary data over a 7-bit transport service. However, safe transport 1193 has a different focus for an 8bit-clean transfer protocol. In HTTP, 1194 the only unsafe characteristic of message-bodies is the difficulty in 1195 determining the exact body length (section 7.2.2), or the desire to 1196 encrypt data over a shared transport. 1198 The Internet Assigned Numbers Authority (IANA) acts as a registry for 1199 transfer-coding value tokens. Initially, the registry contains the 1200 following tokens: "chunked" (section 3.6.1), "identity" (section 1201 3.6.2), "gzip" (section 3.5), "compress" (section 3.5), and "deflate" 1202 (section 3.5). 1204 New transfer-coding value tokens SHOULD be registered in the same way 1205 as new content-coding value tokens (section 3.5). 1207 A server which receives an entity-body with a transfer-coding it does 1208 not understand SHOULD return 501 (Unimplemented), and close the 1209 connection. A server MUST NOT send transfer-codings to an HTTP/1.0 1210 client. 1212 3.6.1 Chunked Transfer Coding 1214 The chunked encoding modifies the body of a message in order to 1215 transfer it as a series of chunks, each with its own size indicator, 1216 followed by an OPTIONAL trailer containing entity-header fields. This 1217 allows dynamically produced content to be transferred along with the 1218 information necessary for the recipient to verify that it has 1219 received the full message. 1221 Chunked-Body = *chunk 1222 last-chunk 1223 trailer 1224 CRLF 1226 chunk = chunk-size [ chunk-extension ] CRLF 1227 chunk-data CRLF 1228 chunk-size = 1*HEX 1229 last-chunk = 1*("0") [ chunk-extension ] CRLF 1231 chunk-extension= *( ";" chunk-ext-name [ "=" chunk-ext-val ] ) 1232 chunk-ext-name = token 1233 chunk-ext-val = token | quoted-string 1234 chunk-data = chunk-size(OCTET) 1235 trailer = *entity-header 1237 The chunk-size field is a string of hex digits indicating the size of 1238 the chunk. The chunked encoding is ended by any chunk whose size is 1239 zero, followed by the trailer, which is terminated by an empty line. 1241 The trailer allows the sender to include additional HTTP header 1242 fields at the end of the message. The Trailer header field can be 1243 used to indicate which header fields are included in a trailer (see 1244 section 14.40). 1246 A server using chunked transfer-coding in a response MUST NOT use the 1247 trailer for any header fields unless at least one of the following is 1248 true: 1250 a)the request included a TE header field that indicates "trailers" 1251 is acceptable in the transfer-coding of the response, as 1252 described in section 14.39; or, 1254 b)the server is the origin server for the response, the trailer 1255 fields consist entirely of optional metadata, and the recipient 1256 could use the message (in a manner acceptable to the origin 1257 server) without receiving this metadata. In other words, the 1258 origin server is willing to accept the possibility that the 1259 trailer fields might be silently discarded along the path 1260 to the client. 1262 This requirement prevents an interoperability failure when the 1263 message is being received by an HTTP/1.1 (or later) proxy and 1264 forwarded to an HTTP/1.0 recipient. It avoids a situation where 1265 compliance with the protocol would have necessitated a possibly 1266 infinite buffer on the proxy. 1268 An example process for decoding a Chunked-Body is presented in 1269 appendix 19.4.6. 1271 All HTTP/1.1 applications MUST be able to receive and decode the 1272 "chunked" transfer-coding, and MUST ignore chunk-extension extensions 1273 they do not understand. 1275 3.7 Media Types 1277 HTTP uses Internet Media Types [17] in the Content-Type (section 1278 14.17) and Accept (section 14.1) header fields in order to provide 1279 open and extensible data typing and type negotiation. 1281 media-type = type "/" subtype *( ";" parameter ) 1282 type = token 1283 subtype = token 1285 Parameters MAY follow the type/subtype in the form of attribute/value 1286 pairs (as defined in section 3.6). 1288 The type, subtype, and parameter attribute names are case- 1289 insensitive. Parameter values might or might not be case-sensitive, 1290 depending on the semantics of the parameter name. Linear white space 1291 (LWS) MUST NOT be used between the type and subtype, nor between an 1292 attribute and its value. The presence or absence of a parameter might 1293 be significant to the processing of a media-type, depending on its 1294 definition within the media type registry. 1296 Note that some older HTTP applications do not recognize media type 1297 parameters. When sending data to older HTTP applications, 1298 implementations SHOULD only use media type parameters when they are 1299 required by that type/subtype definition. 1301 Media-type values are registered with the Internet Assigned Number 1302 Authority (IANA [19]). The media type registration process is 1303 outlined in RFC 1590 [17]. Use of non-registered media types is 1304 discouraged. 1306 3.7.1 Canonicalization and Text Defaults 1308 Internet media types are registered with a canonical form. An entity- 1309 body transferred via HTTP messages MUST be represented in the 1310 appropriate canonical form prior to its transmission except for 1311 "text" types, as defined in the next paragraph. 1313 When in canonical form, media subtypes of the "text" type use CRLF as 1314 the text line break. HTTP relaxes this requirement and allows the 1315 transport of text media with plain CR or LF alone representing a line 1316 break when it is done consistently for an entire entity-body. HTTP 1317 applications MUST accept CRLF, bare CR, and bare LF as being 1318 representative of a line break in text media received via HTTP. In 1319 addition, if the text is represented in a character set that does not 1320 use octets 13 and 10 for CR and LF respectively, as is the case for 1321 some multi-byte character sets, HTTP allows the use of whatever octet 1322 sequences are defined by that character set to represent the 1323 equivalent of CR and LF for line breaks. This flexibility regarding 1324 line breaks applies only to text media in the entity-body; a bare CR 1325 or LF MUST NOT be substituted for CRLF within any of the HTTP control 1326 structures (such as header fields and multipart boundaries). 1328 If an entity-body is encoded with a content-coding, the underlying 1329 data MUST be in a form defined above prior to being encoded. 1331 The "charset" parameter is used with some media types to define the 1332 character set (section 3.4) of the data. When no explicit charset 1333 parameter is provided by the sender, media subtypes of the "text" 1334 type are defined to have a default charset value of "ISO-8859-1" when 1335 received via HTTP. Data in character sets other than "ISO-8859-1" or 1336 its subsets MUST be labeled with an appropriate charset value. See 1337 section 3.4.1 for compatibility problems. 1339 3.7.2 Multipart Types 1341 MIME provides for a number of "multipart" types -- encapsulations of 1342 one or more entities within a single message-body. All multipart 1343 types share a common syntax, as defined in section 5.1.1 of RFC 2046 1344 [40], and MUST include a boundary parameter as part of the media type 1345 value. The message body is itself a protocol element and MUST 1346 therefore use only CRLF to represent line breaks between body-parts. 1347 Unlike in RFC 2046, the epilogue of any multipart message MUST be 1348 empty; HTTP applications MUST NOT transmit the epilogue (even if the 1349 original multipart contains an epilogue). These restrictions exist in 1350 order to preserve the self-delimiting nature of a multipart message- 1351 body, wherein the "end" of the message-body is indicated by the 1352 ending multipart boundary. 1354 In general, HTTP treats a multipart message-body no differently than 1355 any other media type: strictly as payload. The one exception is the 1356 "multipart/byteranges" type (appendix 19.2) when it appears in a 206 1357 (Partial Content) response, which will be interpreted by some HTTP 1358 caching mechanisms as described in sections 13.5.4 and 14.16. In all 1359 other cases, an HTTP user agent SHOULD follow the same or similar 1360 behavior as a MIME user agent would upon receipt of a multipart type. 1361 The MIME header fields within each body-part of a multipart message- 1362 body do not have any significance to HTTP beyond that defined by 1363 their MIME semantics. 1365 In general, an HTTP user agent SHOULD follow the same or similar 1366 behavior as a MIME user agent would upon receipt of a multipart type. 1367 If an application receives an unrecognized multipart subtype, the 1368 application MUST treat it as being equivalent to "multipart/mixed". 1370 Note: The "multipart/form-data" type has been specifically 1371 defined for carrying form data suitable for processing via the 1372 POST request method, as described in RFC 1867 [15]. 1374 3.8 Product Tokens 1376 Product tokens are used to allow communicating applications to 1377 identify themselves by software name and version. Most fields using 1378 product tokens also allow sub-products which form a significant part 1379 of the application to be listed, separated by white space. By 1380 convention, the products are listed in order of their significance 1381 for identifying the application. 1383 product = token ["/" product-version] 1384 product-version = token 1386 Examples: 1388 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 1389 Server: Apache/0.8.4 1391 Product tokens SHOULD be short and to the point. They MUST NOT be 1392 used for advertising or other non-essential information. Although any 1393 token character MAY appear in a product-version, this token SHOULD 1394 only be used for a version identifier (i.e., successive versions of 1395 the same product SHOULD only differ in the product-version portion of 1396 the product value). 1398 3.9 Quality Values 1400 HTTP content negotiation (section 12) uses short "floating point" 1401 numbers to indicate the relative importance ("weight") of various 1402 negotiable parameters. A weight is normalized to a real number in 1403 the range 0 through 1, where 0 is the minimum and 1 the maximum 1404 value. If a parameter has a quality value of 0, then content with 1405 this parameter is `not acceptable' for the client. HTTP/1.1 1406 applications MUST NOT generate more than three digits after the 1407 decimal point. User configuration of these values SHOULD also be 1408 limited in this fashion. 1410 qvalue = ( "0" [ "." 0*3DIGIT ] ) 1411 | ( "1" [ "." 0*3("0") ] ) 1413 "Quality values" is a misnomer, since these values merely represent 1414 relative degradation in desired quality. 1416 3.10 Language Tags 1418 A language tag identifies a natural language spoken, written, or 1419 otherwise conveyed by human beings for communication of information 1420 to other human beings. Computer languages are explicitly excluded. 1421 HTTP uses language tags within the Accept-Language and Content- 1422 Language fields. 1424 The syntax and registry of HTTP language tags is the same as that 1425 defined by RFC 1766 [1]. In summary, a language tag is composed of 1 1426 or more parts: A primary language tag and a possibly empty series of 1427 subtags: 1429 language-tag = primary-tag *( "-" subtag ) 1430 primary-tag = 1*8ALPHA 1431 subtag = 1*8ALPHA 1433 White space is not allowed within the tag and all tags are case- 1434 insensitive. The name space of language tags is administered by the 1435 IANA. Example tags include: 1437 en, en-US, en-cockney, i-cherokee, x-pig-latin 1439 where any two-letter primary-tag is an ISO-639 language abbreviation 1440 and any two-letter initial subtag is an ISO-3166 country code. (The 1441 last three tags above are not registered tags; all but the last are 1442 examples of tags which could be registered in future.) 1444 3.11 Entity Tags 1446 Entity tags are used for comparing two or more entities from the same 1447 requested resource. HTTP/1.1 uses entity tags in the ETag (section 1448 14.19), If-Match (section 14.24), If-None-Match (section 14.26), and 1449 If-Range (section 14.27) header fields. The definition of how they 1450 are used and compared as cache validators is in section 13.3.3. An 1451 entity tag consists of an opaque quoted string, possibly prefixed by 1452 a weakness indicator. 1454 entity-tag = [ weak ] opaque-tag 1455 weak = "W/" 1456 opaque-tag = quoted-string 1458 A "strong entity tag" MAY be shared by two entities of a resource 1459 only if they are equivalent by octet equality. 1461 A "weak entity tag," indicated by the "W/" prefix, MAY be shared by 1462 two entities of a resource only if the entities are equivalent and 1463 could be substituted for each other with no significant change in 1464 semantics. A weak entity tag can only be used for weak comparison. 1466 An entity tag MUST be unique across all versions of all entities 1467 associated with a particular resource. A given entity tag value MAY 1468 be used for entities obtained by requests on different URIs. The use 1469 of the same entity tag value in conjunction with entities obtained by 1470 requests on different URIs does not imply the equivalence of those 1471 entities. 1473 3.12 Range Units 1475 HTTP/1.1 allows a client to request that only part (a range of) the 1476 response entity be included within the response. HTTP/1.1 uses range 1477 units in the Range (section 14.35) and Content-Range (section 14.16) 1478 header fields. An entity can be broken down into subranges according 1479 to various structural units. 1481 range-unit = bytes-unit | other-range-unit 1482 bytes-unit = "bytes" 1483 other-range-unit = token 1485 The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1 1486 implementations MAY ignore ranges specified using other units. 1487 HTTP/1.1 has been designed to allow implementations of applications 1488 that do not depend on knowledge of ranges. 1490 4 HTTP Message 1492 4.1 Message Types 1494 HTTP messages consist of requests from client to server and responses 1495 from server to client. 1497 HTTP-message = Request | Response ; HTTP/1.1 messages 1499 Request (section 5) and Response (section 6) messages use the generic 1500 message format of RFC 822 [9] for transferring entities (the payload 1501 of the message). Both types of message consist of a start-line, zero 1502 or more header fields (also known as "headers"), an empty line (i.e., 1503 a line with nothing preceding the CRLF) indicating the end of the 1504 header fields, and possibly a message-body. 1506 generic-message = start-line 1507 *message-header 1508 CRLF 1509 [ message-body ] 1511 start-line = Request-Line | Status-Line 1513 In the interest of robustness, servers SHOULD ignore any empty 1514 line(s) received where a Request-Line is expected. In other words, if 1515 the server is reading the protocol stream at the beginning of a 1516 message and receives a CRLF first, it should ignore the CRLF. 1518 Certain buggy HTTP/1.0 client implementations generate extra CRLF's 1519 after a POST request. To restate what is explicitly forbidden by the 1520 BNF, an HTTP/1.1 client MUST NOT preface or follow a request with an 1521 extra CRLF. 1523 4.2 Message Headers 1525 HTTP header fields, which include general-header (section 4.5), 1526 request-header (section 5.3), response-header (section 6.2), and 1527 entity-header (section 7.1) fields, follow the same generic format as 1528 that given in Section 3.1 of RFC 822 [9]. Each header field consists 1529 of a name followed by a colon (":") and the field value. Field names 1530 are case-insensitive. The field value MAY be preceded by any amount 1531 of LWS, though a single SP is preferred. Header fields can be 1532 extended over multiple lines by preceding each extra line with at 1533 least one SP or HT. Applications ought to follow "common form", where 1534 one is known or indicated, when generating HTTP constructs, since 1535 there might exist some implementations that fail to accept anything 1536 beyond the common forms. 1538 message-header = field-name ":" [ field-value ] CRLF 1539 field-name = token 1540 field-value = *( field-content | LWS ) 1541 field-content = 1545 The field-content does not include any leading or trailing LWS: 1546 linear white space occurring before the first non-whitespace 1547 character of the field-value or after the last non-whitespace 1548 character of the field-value. Such leading or trailing LWS MAY be 1549 removed without changing the semantics of the field value. Any LWS 1550 that occurs between field-content MAY be replaced with a single SP 1551 before interpreting the field value or forwarding the message 1552 downstream. 1554 The order in which header fields with differing field names are 1555 received is not significant. However, it is "good practice" to send 1556 general-header fields first, followed by request-header or response- 1557 header fields, and ending with the entity-header fields. 1559 Multiple message-header fields with the same field-name MAY be 1560 present in a message if and only if the entire field-value for that 1561 header field is defined as a comma-separated list [i.e., #(values)]. 1562 It MUST be possible to combine the multiple header fields into one 1563 "field-name: field-value" pair, without changing the semantics of the 1564 message, by appending each subsequent field-value to the first, each 1565 separated by a comma. The order in which header fields with the same 1566 field-name are received is therefore significant to the 1567 interpretation of the combined field value, and thus a proxy MUST NOT 1568 change the order of these field values when a message is forwarded. 1570 4.3 Message Body 1572 The message-body (if any) of an HTTP message is used to carry the 1573 entity-body associated with the request or response. The message-body 1574 differs from the entity-body only when a transfer-coding has been 1575 applied, as indicated by the Transfer-Encoding header field (section 1576 14.41). 1578 message-body = entity-body 1579 | 1581 Transfer-Encoding MUST be used to indicate any transfer-codings 1582 applied by an application to ensure safe and proper transfer of the 1583 message. Transfer-Encoding is a property of the message, not of the 1584 entity, and thus MAY be added or removed by any application along the 1585 request/response chain. (However, section 3.6 places restrictions on 1586 when certain transfer-codings may be used.) 1588 The rules for when a message-body is allowed in a message differ for 1589 requests and responses. 1591 The presence of a message-body in a request is signaled by the 1592 inclusion of a Content-Length or Transfer-Encoding header field in 1593 the request's message-headers. A message-body MUST NOT be included in 1594 a request if the specification of the request method (section 5.1.1) 1595 does not allow sending an entity-body in requests. A server SHOULD 1596 read and forward a message-body on any request; if the request method 1597 does not include defined semantics for an entity-body, then the 1598 message-body SHOULD be ignored when handling the request. 1600 For response messages, whether or not a message-body is included with 1601 a message is dependent on both the request method and the response 1602 status code (section 6.1.1). All responses to the HEAD request method 1603 MUST NOT include a message-body, even though the presence of entity- 1604 header fields might lead one to believe they do. All 1xx 1605 (informational), 204 (no content), and 304 (not modified) responses 1606 MUST NOT include a message-body. All other responses do include a 1607 message-body, although it MAY be of zero length. 1609 4.4 Message Length 1611 The transfer-length of a message is the length of the message-body as 1612 it appears in the message; that is, after any transfer-codings have 1613 been applied. When a message-body is included with a message, the 1614 transfer-length of that body is determined by one of the following 1615 (in order of precedence): 1617 1.Any response message which "MUST NOT" include a message-body (such 1618 as the 1xx, 204, and 304 responses and any response to a HEAD 1619 request) is always terminated by the first empty line after the 1620 header fields, regardless of the entity-header fields present in 1621 the message. 1623 2.If a Transfer-Encoding header field (section 14.41) is present and 1624 has any value other than "identity", then the transfer-length is 1625 defined by use of the "chunked" transfer-coding (section 3.6), 1626 unless the message is terminated by closing the connection. 1628 3.If a Content-Length header field (section 14.13) is present, its 1629 decimal value in OCTETs represents both the entity-length and the 1630 transfer-length. The Content-Length header field MUST NOT be sent 1631 if these two lengths are different (i.e., if a Transfer-Encoding 1632 header field is present). If a message is received with both a 1633 Transfer-Encoding header field and a Content-Length header field, 1634 the latter MUST be ignored. 1636 4.If the message uses the media type "multipart/byteranges", and the 1637 transfer-length is not otherwise specified, then this self- 1638 delimiting media type defines the transfer-length. This media type 1639 MUST NOT be used unless the sender knows that the recipient can 1640 parse it; the presence in a request of a Range header with 1641 multiple byte-range specifiers from a 1.1 client implies that the 1642 client can parse multipart/byteranges responses. 1644 A range header might be forwarded by a 1.0 proxy that does not 1645 understand multipart/byteranges; in this case the server MUST 1646 delimit the message using methods defined in items 1,3 or 5 of 1647 this section. 1649 5. By the server closing the connection. (Closing the connection 1650 cannot be used to indicate the end of a request body, since that 1651 would leave no possibility for the server to send back a response.) 1653 For compatibility with HTTP/1.0 applications, HTTP/1.1 requests 1654 containing a message-body MUST include a valid Content-Length header 1655 field unless the server is known to be HTTP/1.1 compliant. If a 1656 request contains a message-body and a Content-Length is not given, 1657 the server SHOULD respond with 400 (bad request) if it cannot 1658 determine the length of the message, or with 411 (length required) if 1659 it wishes to insist on receiving a valid Content-Length. 1661 All HTTP/1.1 applications that receive entities MUST accept the 1662 "chunked" transfer-coding (section 3.6), thus allowing this mechanism 1663 to be used for messages when the message length cannot be determined 1664 in advance. 1666 Messages MUST NOT include both a Content-Length header field and a 1667 non-identity transfer-coding. If the message does include a non- 1668 identity transfer-coding, the Content-Length MUST be ignored. 1670 When a Content-Length is given in a message where a message-body is 1671 allowed, its field value MUST exactly match the number of OCTETs in 1672 the message-body. HTTP/1.1 user agents MUST notify the user when an 1673 invalid length is received and detected. 1675 4.5 General Header Fields 1677 There are a few header fields which have general applicability for 1678 both request and response messages, but which do not apply to the 1679 entity being transferred. These header fields apply only to the 1680 message being transmitted. 1682 general-header = Cache-Control ; Section 14.9 1683 | Connection ; Section 14.10 1684 | Date ; Section 14.18 1685 | Pragma ; Section 14.32 1686 | Trailer ; Section 14.40 1687 | Transfer-Encoding ; Section 14.41 1688 | Upgrade ; Section 14.42 1689 | Via ; Section 14.45 1690 | Warning ; Section 14.46 1692 General-header field names can be extended reliably only in 1693 combination with a change in the protocol version. However, new or 1694 experimental header fields may be given the semantics of general 1695 header fields if all parties in the communication recognize them to 1696 be general-header fields. Unrecognized header fields are treated as 1697 entity-header fields. 1699 5 Request 1701 A request message from a client to a server includes, within the 1702 first line of that message, the method to be applied to the resource, 1703 the identifier of the resource, and the protocol version in use. 1705 Request = Request-Line ; Section 5.1 1706 *( general-header ; Section 4.5 1707 | request-header ; Section 5.3 1708 | entity-header ) ; Section 7.1 1709 CRLF 1710 [ message-body ] ; Section 4.3 1712 5.1 Request-Line 1714 The Request-Line begins with a method token, followed by the Request- 1715 URI and the protocol version, and ending with CRLF. The elements are 1716 separated by SP characters. No CR or LF is allowed except in the 1717 final CRLF sequence. 1719 Request-Line = Method SP Request-URI SP HTTP-Version CRLF 1721 5.1.1 Method 1723 The Method token indicates the method to be performed on the 1724 resource identified by the Request-URI. The method is case-sensitive. 1726 Method = "OPTIONS" ; Section 9.2 1727 | "GET" ; Section 9.3 1728 | "HEAD" ; Section 9.4 1729 | "POST" ; Section 9.5 1730 | "PUT" ; Section 9.6 1731 | "DELETE" ; Section 9.7 1732 | "TRACE" ; Section 9.8 1733 | "CONNECT" ; Section 9.9 1734 | extension-method 1735 extension-method = token 1737 The list of methods allowed by a resource can be specified in an 1738 Allow header field (section 14.7). The return code of the response 1739 always notifies the client whether a method is currently allowed on a 1740 resource, since the set of allowed methods can change dynamically. An 1741 origin server SHOULD return the status code 405 (Method Not Allowed) 1742 if the method is known by the origin server but not allowed for the 1743 requested resource, and 501 (Not Implemented) if the method is 1744 unrecognized or not implemented by the origin server. The methods GET 1745 and HEAD MUST be supported by all general-purpose servers. All other 1746 methods are OPTIONAL; however, if the above methods are implemented, 1747 they MUST be implemented with the same semantics as those specified 1748 in section 9. 1750 5.1.2 Request-URI 1752 The Request-URI is a Uniform Resource Identifier (section 3.2) and 1753 identifies the resource upon which to apply the request. 1755 Request-URI = "*" | absoluteURI | abs_path | authority 1757 The four options for Request-URI are dependent on the nature of the 1758 request. The asterisk "*" means that the request does not apply to a 1759 particular resource, but to the server itself, and is only allowed 1760 when the method used does not necessarily apply to a resource. One 1761 example would be 1763 OPTIONS * HTTP/1.1 1765 The absoluteURI form is REQUIRED when the request is being made to a 1766 proxy. The proxy is requested to forward the request or service it 1767 from a valid cache, and return the response. Note that the proxy MAY 1768 forward the request on to another proxy or directly to the server 1769 specified by the absoluteURI. In order to avoid request loops, a 1770 proxy MUST be able to recognize all of its server names, including 1771 any aliases, local variations, and the numeric IP address. An example 1772 Request-Line would be: 1774 GET http://www.w3.org/pub/WWW/TheProject.html HTTP/1.1 1776 To allow for transition to absoluteURIs in all requests in future 1777 versions of HTTP, all HTTP/1.1 servers MUST accept the absoluteURI 1778 form in requests, even though HTTP/1.1 clients will only generate 1779 them in requests to proxies. 1781 The authority form is only used by the CONNECT method (section 9.9). 1783 The most common form of Request-URI is that used to identify a 1784 resource on an origin server or gateway. In this case the absolute 1785 path of the URI MUST be transmitted (see section 3.2.1, abs_path) as 1786 the Request-URI, and the network location of the URI (authority) MUST 1787 be transmitted in a Host header field. For example, a client wishing 1788 to retrieve the resource above directly from the origin server would 1789 create a TCP connection to port 80 of the host "www.w3.org" and send 1790 the lines: 1792 GET /pub/WWW/TheProject.html HTTP/1.1 1793 Host: www.w3.org 1795 followed by the remainder of the Request. Note that the absolute path 1796 cannot be empty; if none is present in the original URI, it MUST be 1797 given as "/" (the server root). 1799 The Request-URI is transmitted in the format specified in section 1800 3.2.1. If the Request-URI is encoded using the "% HEX HEX" encoding 1801 [42], the origin server MUST decode the Request-URI in order to 1802 properly interpret the request. Servers SHOULD respond to invalid 1803 Request-URIs with an appropriate status code. 1805 A transparent proxy MUST NOT rewrite the "abs_path" part of the 1806 received Request-URI when forwarding it to the next inbound server, 1807 except as noted above to replace a null abs_path with "/". 1809 Note: The "no rewrite" rule prevents the proxy from changing 1810 the meaning of the request when the origin server is improperly 1811 using a non-reserved URI character for a reserved purpose. 1812 Implementors should be aware that some pre-HTTP/1.1 proxies 1813 have been known to rewrite the Request-URI. 1815 5.2 The Resource Identified by a Request 1817 The exact resource identified by an Internet request is determined by 1818 examining both the Request-URI and the Host header field. 1820 An origin server that does not allow resources to differ by the 1821 requested host MAY ignore the Host header field value when 1822 determining the resource identified by an HTTP/1.1 request. (But see 1823 section 19.6.1.1 for other requirements on Host support in HTTP/1.1.) 1825 An origin server that does differentiate resources based on the host 1826 requested (sometimes referred to as virtual hosts or vanity host 1827 names) MUST use the following rules for determining the requested 1828 resource on an HTTP/1.1 request: 1830 1. If Request-URI is an absoluteURI, the host is part of the Request- 1831 URI. Any Host header field value in the request MUST be ignored. 1833 2. If the Request-URI is not an absoluteURI, and the request includes 1834 a Host header field, the host is determined by the Host header 1835 field value. 1837 3. If the host as determined by rule 1 or 2 is not a valid host on 1838 the server, the response MUST be a 400 (Bad Request) error message. 1840 Recipients of an HTTP/1.0 request that lacks a Host header field MAY 1841 attempt to use heuristics (e.g., examination of the URI path for 1842 something unique to a particular host) in order to determine what 1843 exact resource is being requested. 1845 5.3 Request Header Fields 1847 The request-header fields allow the client to pass additional 1848 information about the request, and about the client itself, to the 1849 server. These fields act as request modifiers, with semantics 1850 equivalent to the parameters on a programming language method 1851 invocation. 1853 request-header = Accept ; Section 14.1 1854 | Accept-Charset ; Section 14.2 1855 | Accept-Encoding ; Section 14.3 1856 | Accept-Language ; Section 14.4 1857 | Authorization ; Section 14.8 1858 | Expect ; Section 14.20 1859 | From ; Section 14.22 1860 | Host ; Section 14.23 1861 | If-Match ; Section 14.24 1862 | If-Modified-Since ; Section 14.25 1863 | If-None-Match ; Section 14.26 1864 | If-Range ; Section 14.27 1865 | If-Unmodified-Since ; Section 14.28 1866 | Max-Forwards ; Section 14.31 1867 | Proxy-Authorization ; Section 14.34 1868 | Range ; Section 14.35 1869 | Referer ; Section 14.36 1870 | TE ; Section 14.39 1871 | User-Agent ; Section 14.43 1873 Request-header field names can be extended reliably only in 1874 combination with a change in the protocol version. However, new or 1875 experimental header fields MAY be given the semantics of request- 1876 header fields if all parties in the communication recognize them to 1877 be request-header fields. Unrecognized header fields are treated as 1878 entity-header fields. 1880 6 Response 1881 After receiving and interpreting a request message, a server responds 1882 with an HTTP response message. 1884 Response = Status-Line ; Section 6.1 1885 *( general-header ; Section 4.5 1886 | response-header ; Section 6.2 1887 | entity-header ) ; Section 7.1 1888 CRLF 1889 [ message-body ] ; Section 7.2 1891 6.1 Status-Line 1893 The first line of a Response message is the Status-Line, consisting 1894 of the protocol version followed by a numeric status code and its 1895 associated textual phrase, with each element separated by SP 1896 characters. No CR or LF is allowed except in the final CRLF sequence. 1898 Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF 1900 6.1.1 Status Code and Reason Phrase 1902 The Status-Code element is a 3-digit integer result code of the 1903 attempt to understand and satisfy the request. These codes are fully 1904 defined in section 10. The Reason-Phrase is intended to give a short 1905 textual description of the Status-Code. The Status-Code is intended 1906 for use by automata and the Reason-Phrase is intended for the human 1907 user. The client is not required to examine or display the Reason- 1908 Phrase. 1910 The first digit of the Status-Code defines the class of response. The 1911 last two digits do not have any categorization role. There are 5 1912 values for the first digit: 1914 . 1xx: Informational - Request received, continuing process 1916 . 2xx: Success - The action was successfully received, 1917 understood, and accepted 1919 . 3xx: Redirection - Further action must be taken in order to 1920 complete the request 1922 . 4xx: Client Error - The request contains bad syntax or cannot 1923 be fulfilled 1925 . 5xx: Server Error - The server failed to fulfill an apparently 1926 valid request 1928 The individual values of the numeric status codes defined for 1929 HTTP/1.1, and an example set of corresponding Reason-Phrase's, are 1930 presented below. The reason phrases listed here are only 1931 recommendations -- they MAY be replaced by local equivalents without 1932 affecting the protocol. 1934 Status-Code = 1935 "100" ; Section 10.1.1: Continue 1936 | "101" ; Section 10.1.2: Switching Protocols 1937 | "200" ; Section 10.2.1: OK 1938 | "201" ; Section 10.2.2: Created 1939 | "202" ; Section 10.2.3: Accepted 1940 | "203" ; Section 10.2.4: Non-Authoritative Information 1941 | "204" ; Section 10.2.5: No Content 1942 | "205" ; Section 10.2.6: Reset Content 1943 | "206" ; Section 10.2.7: Partial Content 1944 | "300" ; Section 10.3.1: Multiple Choices 1945 | "301" ; Section 10.3.2: Moved Permanently 1946 | "302" ; Section 10.3.3: Found 1947 | "303" ; Section 10.3.4: See Other 1948 | "304" ; Section 10.3.5: Not Modified 1949 | "305" ; Section 10.3.6: Use Proxy 1950 | "307" ; Section 10.3.8: Temporary Redirect 1951 | "400" ; Section 10.4.1: Bad Request 1952 | "401" ; Section 10.4.2: Unauthorized 1953 | "402" ; Section 10.4.3: Payment Required 1954 | "403" ; Section 10.4.4: Forbidden 1955 | "404" ; Section 10.4.5: Not Found 1956 | "405" ; Section 10.4.6: Method Not Allowed 1957 | "406" ; Section 10.4.7: Not Acceptable 1958 | "407" ; Section 10.4.8: Proxy Authentication Required 1959 | "408" ; Section 10.4.9: Request Time-out 1960 | "409" ; Section 10.4.10: Conflict 1961 | "410" ; Section 10.4.11: Gone 1962 | "411" ; Section 10.4.12: Length Required 1963 | "412" ; Section 10.4.13: Precondition Failed 1964 | "413" ; Section 10.4.14: Request Entity Too Large 1965 | "414" ; Section 10.4.15: Request-URI Too Large 1966 | "415" ; Section 10.4.16: Unsupported Media Type 1967 | "416" ; Section 10.4.17: Requested range not satisfiable 1968 | "417" ; Section 10.4.18: Expectation Failed 1969 | "500" ; Section 10.5.1: Internal Server Error 1970 | "501" ; Section 10.5.2: Not Implemented 1971 | "502" ; Section 10.5.3: Bad Gateway 1972 | "503" ; Section 10.5.4: Service Unavailable 1973 | "504" ; Section 10.5.5: Gateway Time-out 1974 | "505" ; Section 10.5.6: HTTP Version not supported 1975 | extension-code 1977 extension-code = 3DIGIT 1978 Reason-Phrase = * 1980 HTTP status codes are extensible. HTTP applications are not required 1981 to understand the meaning of all registered status codes, though such 1982 understanding is obviously desirable. However, applications MUST 1983 understand the class of any status code, as indicated by the first 1984 digit, and treat any unrecognized response as being equivalent to the 1985 x00 status code of that class, with the exception that an 1986 unrecognized response MUST NOT be cached. For example, if an 1987 unrecognized status code of 431 is received by the client, it can 1988 safely assume that there was something wrong with its request and 1989 treat the response as if it had received a 400 status code. In such 1990 cases, user agents SHOULD present to the user the entity returned 1991 with the response, since that entity is likely to include human- 1992 readable information which will explain the unusual status. 1994 6.2 Response Header Fields 1996 The response-header fields allow the server to pass additional 1997 information about the response which cannot be placed in the Status- 1998 Line. These header fields give information about the server and about 1999 further access to the resource identified by the Request-URI. 2001 response-header = Accept-Ranges ; Section 14.5 2002 | Age ; Section 14.6 2003 | ETag ; Section 14.19 2004 | Location ; Section 14.30 2005 | Proxy-Authenticate ; Section 14.33 2006 | Retry-After ; Section 14.37 2007 | Server ; Section 14.38 2008 | Vary ; Section 14.44 2009 | WWW-Authenticate ; Section 14.47 2011 Response-header field names can be extended reliably only in 2012 combination with a change in the protocol version. However, new or 2013 experimental header fields MAY be given the semantics of response- 2014 header fields if all parties in the communication recognize them to 2015 be response-header fields. Unrecognized header fields are treated as 2016 entity-header fields. 2018 7 Entity 2020 Request and Response messages MAY transfer an entity if not otherwise 2021 restricted by the request method or response status code. An entity 2022 consists of entity-header fields and an entity-body, although some 2023 responses will only include the entity-headers. 2025 In this section, both sender and recipient refer to either the client 2026 or the server, depending on who sends and who receives the entity. 2028 7.1 Entity Header Fields 2030 Entity-header fields define metainformation about the entity-body or, 2031 if no body is present, about the resource identified by the request. 2032 Some of this metainformation is OPTIONAL; some might be REQUIRED by 2033 portions of this specification. 2035 entity-header = Allow ; Section 14.7 2036 | Content-Encoding ; Section 14.11 2037 | Content-Language ; Section 14.12 2038 | Content-Length ; Section 14.13 2039 | Content-Location ; Section 14.14 2040 | Content-MD5 ; Section 14.15 2041 | Content-Range ; Section 14.16 2042 | Content-Type ; Section 14.17 2043 | Expires ; Section 14.21 2044 | Last-Modified ; Section 14.29 2045 | extension-header 2047 extension-header = message-header 2049 The extension-header mechanism allows additional entity-header fields 2050 to be defined without changing the protocol, but these fields cannot 2051 be assumed to be recognizable by the recipient. Unrecognized header 2052 fields SHOULD be ignored by the recipient and MUST be forwarded by 2053 transparent proxies. 2055 7.2 Entity Body 2057 The entity-body (if any) sent with an HTTP request or response is in 2058 a format and encoding defined by the entity-header fields. 2060 entity-body = *OCTET 2062 An entity-body is only present in a message when a message-body is 2063 present, as described in section 4.3. The entity-body is obtained 2064 from the message-body by decoding any Transfer-Encoding that might 2065 have been applied to ensure safe and proper transfer of the message. 2067 7.2.1 Type 2069 When an entity-body is included with a message, the data type of that 2070 body is determined via the header fields Content-Type and Content- 2071 Encoding. These define a two-layer, ordered encoding model: 2073 entity-body := Content-Encoding( Content-Type( data ) ) 2075 Content-Type specifies the media type of the underlying data. 2076 Content-Encoding may be used to indicate any additional content 2077 codings applied to the data, usually for the purpose of data 2078 compression, that are a property of the requested resource. There is 2079 no default encoding. 2081 Any HTTP/1.1 message containing an entity-body SHOULD include a 2082 Content-Type header field defining the media type of that body. If 2083 and only if the media type is not given by a Content-Type field, the 2084 recipient MAY attempt to guess the media type via inspection of its 2085 content and/or the name extension(s) of the URI used to identify the 2086 resource. If the media type remains unknown, the recipient SHOULD 2087 treat it as type "application/octet-stream". 2089 7.2.2 Entity Length 2091 The entity-length of a message is the length of the message-body 2092 before any transfer-codings have been applied. Section 4.4 defines 2093 how the transfer-length of a message-body is determined. 2095 8 Connections 2097 8.1 Persistent Connections 2099 8.1.1 Purpose 2101 Prior to persistent connections, a separate TCP connection was 2102 established to fetch each URL, increasing the load on HTTP servers 2103 and causing congestion on the Internet. The use of inline images and 2104 other associated data often require a client to make multiple 2105 requests of the same server in a short amount of time. Analysis of 2106 these performance problems and results from a prototype 2107 implementation are available [26] [30]. Implementation experience and 2108 measurements of actual HTTP/1.1 (RFC 2068) implementations show good 2109 results [39]. Alternatives have also been explored, for example, 2110 T/TCP [27]. 2112 Persistent HTTP connections have a number of advantages: 2113 . By opening and closing fewer TCP connections, CPU time is saved 2114 in routers and hosts (clients, servers, proxies, gateways, 2115 tunnels, or caches), and memory used for TCP protocol control 2116 blocks can be saved in hosts. 2118 . HTTP requests and responses can be pipelined on a connection. 2119 Pipelining allows a client to make multiple requests without 2120 waiting for each response, allowing a single TCP connection to 2121 be used much more efficiently, with much lower elapsed time. 2123 . Network congestion is reduced by reducing the number of packets 2124 caused by TCP opens, and by allowing TCP sufficient time to 2125 determine the congestion state of the network. 2127 . Latency on subsequent requests is reduced since there is no 2128 time spent in TCP's connection opening handshake. 2130 . HTTP can evolve more gracefully, since errors can be reported 2131 without the penalty of closing the TCP connection. Clients 2132 using future versions of HTTP might optimistically try a new 2133 feature, but if communicating with an older server, retry with 2134 old semantics after an error is reported. 2136 HTTP implementations SHOULD implement persistent connections. 2138 8.1.2 Overall Operation 2140 A significant difference between HTTP/1.1 and earlier versions of 2141 HTTP is that persistent connections are the default behavior of any 2142 HTTP connection. That is, unless otherwise indicated, the client 2143 SHOULD assume that the server will maintain a persistent connection, 2144 even after error responses from the server. 2146 Persistent connections provide a mechanism by which a client and a 2147 server can signal the close of a TCP connection. This signaling takes 2148 place using the Connection header field (section 14.10). Once a close 2149 has been signaled, the client MUST NOT send any more requests on that 2150 connection. 2152 8.1.2.1 Negotiation 2154 An HTTP/1.1 server MAY assume that a HTTP/1.1 client intends to 2155 maintain a persistent connection unless a Connection header including 2156 the connection-token "close" was sent in the request. If the server 2157 chooses to close the connection immediately after sending the 2158 response, it SHOULD send a Connection header including the 2159 connection-token close. 2161 An HTTP/1.1 client MAY expect a connection to remain open, but would 2162 decide to keep it open based on whether the response from a server 2163 contains a Connection header with the connection-token close. In case 2164 the client does not want to maintain a connection for more than that 2165 request, it SHOULD send a Connection header including the connection- 2166 token close. 2168 If either the client or the server sends the close token in the 2169 Connection header, that request becomes the last one for the 2170 connection. 2172 Clients and servers SHOULD NOT assume that a persistent connection is 2173 maintained for HTTP versions less than 1.1 unless it is explicitly 2174 signaled. See section 19.6.2 for more information on backward 2175 compatibility with HTTP/1.0 clients. 2177 In order to remain persistent, all messages on the connection MUST 2178 have a self-defined message length (i.e., one not defined by closure 2179 of the connection), as described in section 4.4. 2181 8.1.2.2 Pipelining 2183 A client that supports persistent connections MAY "pipeline" its 2184 requests (i.e., send multiple requests without waiting for each 2185 response). A server MUST send its responses to those requests in the 2186 same order that the requests were received. 2188 Clients which assume persistent connections and pipeline immediately 2189 after connection establishment SHOULD be prepared to retry their 2190 connection if the first pipelined attempt fails. If a client does 2191 such a retry, it MUST NOT pipeline before it knows the connection is 2192 persistent. Clients MUST also be prepared to resend their requests if 2193 the server closes the connection before sending all of the 2194 corresponding responses. 2196 Clients SHOULD NOT pipeline requests using non-idempotent methods or 2197 non-idempotent sequences of methods (see section 9.1.2). Otherwise, a 2198 premature termination of the transport connection could lead to 2199 indeterminate results. A client wishing to send a non-idempotent 2200 request SHOULD wait to send that request until it has received the 2201 response status for the previous request. 2203 8.1.3 Proxy Servers 2205 It is especially important that proxies correctly implement the 2206 properties of the Connection header field as specified in section 2207 14.10. 2209 The proxy server MUST signal persistent connections separately with 2210 its clients and the origin servers (or other proxy servers) that it 2211 connects to. Each persistent connection applies to only one transport 2212 link. 2214 A proxy server MUST NOT establish a HTTP/1.1 persistent connection 2215 with an HTTP/1.0 client (but see RFC 2068 [33] for information and 2216 discussion of the problems with the Keep-Alive header implemented by 2217 many HTTP/1.0 clients). 2219 8.1.4 Practical Considerations 2221 Servers will usually have some time-out value beyond which they will 2222 no longer maintain an inactive connection. Proxy servers might make 2223 this a higher value since it is likely that the client will be making 2224 more connections through the same server. The use of persistent 2225 connections places no requirements on the length (or existence) of 2226 this time-out for either the client or the server. 2228 When a client or server wishes to time-out it SHOULD issue a graceful 2229 close on the transport connection. Clients and servers SHOULD both 2230 constantly watch for the other side of the transport close, and 2231 respond to it as appropriate. If a client or server does not detect 2232 the other side's close promptly it could cause unnecessary resource 2233 drain on the network. 2235 A client, server, or proxy MAY close the transport connection at any 2236 time. For example, a client might have started to send a new request 2237 at the same time that the server has decided to close the "idle" 2238 connection. From the server's point of view, the connection is being 2239 closed while it was idle, but from the client's point of view, a 2240 request is in progress. 2242 This means that clients, servers, and proxies MUST be able to recover 2243 from asynchronous close events. Client software SHOULD reopen the 2244 transport connection and retransmit the aborted sequence of requests 2245 without user interaction so long as the request sequence is 2246 idempotent (see section 9.1.2). Non-idempotent methods or sequences 2247 MUST NOT be automatically retried, although user agents MAY offer a 2248 human operator the choice of retrying the request(s). Confirmation by 2249 user-agent software with semantic understanding of the application 2250 MAY substitute for user confirmation. The automatic retry SHOULD NOT 2251 be repeated if the second sequence of requests fails. 2253 Servers SHOULD always respond to at least one request per connection, 2254 if at all possible. Servers SHOULD NOT close a connection in the 2255 middle of transmitting a response, unless a network or client failure 2256 is suspected. 2258 Clients that use persistent connections SHOULD limit the number of 2259 simultaneous connections that they maintain to a given server. A 2260 single-user client SHOULD NOT maintain more than connections with any 2261 server or proxy. A proxy SHOULD use up to 2*N connections to another 2262 server or proxy, where N is the number of simultaneously active 2263 users. These guidelines are intended to improve HTTP response times 2264 and avoid congestion. 2266 8.2 Message Transmission Requirements 2268 8.2.1 Persistent Connections and Flow Control 2270 HTTP/1.1 servers SHOULD maintain persistent connections and use TCP's 2271 flow control mechanisms to resolve temporary overloads, rather than 2272 terminating connections with the expectation that clients will retry. 2273 The latter technique can exacerbate network congestion. 2275 8.2.2 Monitoring Connections for Error Status Messages 2277 An HTTP/1.1 (or later) client sending a message-body SHOULD monitor 2278 the network connection for an error status while it is transmitting 2279 the request. If the client sees an error status, it SHOULD 2280 immediately cease transmitting the body. If the body is being sent 2281 using a "chunked" encoding (section 3.6), a zero length chunk and 2282 empty trailer MAY be used to prematurely mark the end of the message. 2283 If the body was preceded by a Content-Length header, the client MUST 2284 close the connection. 2286 8.2.3 Use of the 100 (Continue) Status 2288 The purpose of the 100 (Continue) status (see section 10.1.1) is to 2289 allow an client that is sending a request message with a request body 2290 to determine if the origin server is willing to accept the request 2291 (based on the request headers) before the client sends the request 2292 body. In some cases, it might either be inappropriate or highly 2293 inefficient for the client to send the body if the server will reject 2294 the message without looking at the body. 2296 Requirements for HTTP/1.1 clients: 2298 . If a client will wait for a 100 (Continue) response before 2299 sending the request body, it MUST send an Expect request-header 2300 field (section 14.20) with the "100-continue" expectation. 2302 . A client MUST NOT send an Expect request-header field (section 2303 14.20) with the "100-continue" expectation if it does not intend 2304 to send a request body. 2306 Because of the presence of older implementations, the protocol allows 2307 ambiguous situations in which a client may send "Expect: 100- 2308 continue" without receiving either a 417 (Expectation Failed) status 2309 or a 100 (Continue) status. Therefore, when a client sends this 2310 header field to an origin server (possibly via a proxy) from which it 2311 has never seen a 100 (Continue) status, the client SHOULD NOT wait 2312 for an indefinite period before sending the request body. 2314 Requirements for HTTP/1.1 origin servers: 2316 . Upon receiving a request which includes an Expect request- 2317 header field with the "100-continue" expectation, an origin 2318 server MUST either respond with 100 (Continue) status and 2319 continue to read from the input stream, or respond with a final 2320 status code. The origin server MUST NOT wait for the request 2321 body before sending the 100 (Continue) response. If it responds 2322 with a final status code, it MAY close the transport connection 2323 or it MAY continue to read and discard the rest of the request. 2324 It MUST NOT perform the requested method if it returns a final 2325 status code. 2327 . An origin server SHOULD NOT send a 100 (Continue) response if 2328 the request message does not include an Expect request-header 2329 field with the "100-continue" expectation, and MUST NOT send a 2330 100 (Continue) response if such a request comes from an HTTP/1.0 2331 (or earlier) client. There is an exception to this rule: for 2332 compatibility with RFC 2068, a server MAY send a 100 (Continue) 2333 status in response to an HTTP/1.1 PUT or POST request that does 2334 not include an Expect request-header field with the "100- 2335 continue" expectation. This exception, the purpose of which is 2336 to minimize any client processing delays associated with an 2337 undeclared wait for 100 (Continue) status, applies only to 2338 HTTP/1.1 requests, and not to requests with any other HTTP- 2339 version value. 2341 . An origin server MAY omit a 100 (Continue) response if it has 2342 already received some or all of the request body for the 2343 corresponding request. 2345 . An origin server that sends a 100 (Continue) response MUST 2346 ultimately send a final status code, once the request body is 2347 received and processed, unless it terminates the transport 2348 connection prematurely. 2350 . If an origin server receives a request that does not include an 2351 Expect request-header field with the "100-continue" expectation, 2352 the request includes a request body, and the server responds 2353 with a final status code before reading the entire request body 2354 from the transport connection, then the server SHOULD NOT close 2355 the transport connection until it has read the entire request, 2356 or until the client closes the connection. Otherwise, the client 2357 might not reliably receive the response message. However, this 2358 requirement is not be construed as preventing a server from 2359 defending itself against denial-of-service attacks, or from 2360 badly broken client implementations. 2362 Requirements for HTTP/1.1 proxies: 2364 . If a proxy receives a request that includes an Expect request- 2365 header field with the "100-continue" expectation, and the proxy 2366 either knows that the next-hop server complies with HTTP/1.1 or 2367 higher, or does not know the HTTP version of the next-hop 2368 server, it MUST forward the request, including the Expect header 2369 field. 2371 . If the proxy knows that the version of the next-hop server is 2372 HTTP/1.0 or lower, it MUST NOT forward the request, and it MUST 2373 respond with a 417 (Expectation Failed) status. 2375 . Proxies SHOULD maintain a cache recording the HTTP version 2376 numbers received from recently-referenced next-hop servers. 2378 . A proxy MUST NOT forward a 100 (Continue) response if the 2379 request message was received from an HTTP/1.0 (or earlier) 2380 client and did not include an Expect request-header field with 2381 the "100-continue" expectation. This requirement overrides the 2382 general rule for forwarding of 1xx responses (see section 10.1). 2384 8.2.4 Client Behavior if Server Prematurely Closes Connection 2386 If an HTTP/1.1 client sends a request which includes a request body, 2387 but which does not include an Expect request-header field with the 2388 "100-continue" expectation, and if the client is not directly 2389 connected to an HTTP/1.1 origin server, and if the client sees the 2390 connection close before receiving any status from the server, the 2391 client SHOULD retry the request, subject to the restrictions in 2392 section 8.2.3. If the client does retry this request, it MAY use the 2393 following "binary exponential backoff" algorithm to be assured of 2394 obtaining a reliable response: 2396 1. Initiate a new connection to the server 2398 2. Transmit the request-headers 2400 3. Initialize a variable R to the estimated round-trip time to the 2401 server (e.g., based on the time it took to establish the 2402 connection), or to a constant value of 5 seconds if the round- 2403 trip time is not available. 2405 4. Compute T = R * (2**N), where N is the number of previous 2406 retries of this request. 2408 5. Wait either for an error response from the server, or for T 2409 seconds (whichever comes first) 2411 6. If no error response is received, after T seconds transmit the 2412 body of the request. 2414 7. If client sees that the connection is closed prematurely, repeat 2415 from step 1 until the request is accepted, an error response is 2416 received, or the user becomes impatient and terminates the retry 2417 process. 2419 If at any point an error status is received, the client 2421 . SHOULD NOT continue and 2423 . SHOULD close the connection if it has not completed sending the 2424 request message. 2426 9 Method Definitions 2428 The set of common methods for HTTP/1.1 is defined below. Although 2429 this set can be expanded, additional methods cannot be assumed to 2430 share the same semantics for separately extended clients and servers. 2432 The Host request-header field (section 14.23) MUST accompany all 2433 HTTP/1.1 requests. 2435 9.1 Safe and Idempotent Methods 2437 9.1.1 Safe Methods 2439 Implementors should be aware that the software represents the user in 2440 their interactions over the Internet, and should be careful to allow 2441 the user to be aware of any actions they might take which may have an 2442 unexpected significance to themselves or others. 2444 In particular, the convention has been established that the GET and 2445 HEAD methods SHOULD NOT have the significance of taking an action 2446 other than retrieval. These methods ought to be considered "safe." 2447 This allows user agents to represent other methods, such as POST, PUT 2448 and DELETE, in a special way, so that the user is made aware of the 2449 fact that a possibly unsafe action is being requested. 2451 Naturally, it is not possible to ensure that the server does not 2452 generate side-effects as a result of performing a GET request; in 2453 fact, some dynamic resources consider that a feature. The important 2454 distinction here is that the user did not request the side-effects, 2455 so therefore cannot be held accountable for them. 2457 9.1.2 Idempotent Methods 2459 Methods can also have the property of "idempotence" in that (aside 2460 from error or expiration issues) the side-effects of N > 0 identical 2461 requests is the same as for a single request. The methods GET, HEAD, 2462 PUT and DELETE share this property. Also, the methods OPTIONS and 2463 TRACE SHOULD NOT have side effects, and so are inherently idempotent. 2465 However, it is possible that a sequence of several requests is non- 2466 idempotent, even if all of the methods executed in that sequence are 2467 idempotent. (A sequence is idempotent if a single execution of the 2468 entire sequence always yields a result that is not changed by a 2469 reexecution of all, or part, of that sequence.) For example, a 2470 sequence is non-idempotent if its result depends on a value that is 2471 later modified in the same sequence. 2473 A sequence that never has side effects is idempotent, by definition 2474 (provided that no concurrent operations are being executed on the 2475 same set of resources). 2477 9.2 OPTIONS 2479 The OPTIONS method represents a request for information about the 2480 communication options available on the request/response chain 2481 identified by the Request-URI. This method allows the client to 2482 determine the options and/or requirements associated with a resource, 2483 or the capabilities of a server, without implying a resource action 2484 or initiating a resource retrieval. 2486 Responses to this method are not cacheable. 2488 If the OPTIONS request includes an entity-body (as indicated by the 2489 presence of Content-Length or Transfer-Encoding), then the media type 2490 MUST be indicated by a Content-Type field. Although this 2491 specification does not define any use for such a body, future 2492 extensions to HTTP might use the OPTIONS body to make more detailed 2493 queries on the server. A server that does not support such an 2494 extension MAY discard the request body. 2496 If the Request-URI is an asterisk ("*"), the OPTIONS request is 2497 intended to apply to the server in general rather than to a specific 2498 resource. Since a server's communication options typically depend on 2499 the resource, the "*" request is only useful as a "ping" or "no-op" 2500 type of method; it does nothing beyond allowing the client to test 2501 the capabilities of the server. For example, this can be used to test 2502 a proxy for HTTP/1.1 compliance (or lack thereof). 2504 If the Request-URI is not an asterisk, the OPTIONS request applies 2505 only to the options that are available when communicating with that 2506 resource. 2508 A 200 response SHOULD include any header fields that indicate 2509 optional features implemented by the server and applicable to that 2510 resource (e.g., Allow), possibly including extensions not defined by 2511 this specification. The response body, if any, SHOULD also include 2512 information about the communication options. The format for such a 2513 body is not defined by this specification, but might be defined by 2514 future extensions to HTTP. Content negotiation MAY be used to select 2515 the appropriate response format. If no response body is included, the 2516 response MUST include a Content-Length field with a field-value of 2517 "0". 2519 The Max-Forwards request-header field MAY be used to target a 2520 specific proxy in the request chain. When a proxy receives an OPTIONS 2521 request on an absoluteURI for which request forwarding is permitted, 2522 the proxy MUST check for a Max-Forwards field. If the Max-Forwards 2523 field-value is zero ("0"), the proxy MUST NOT forward the message; 2524 instead, the proxy SHOULD respond with its own communication options. 2525 If the Max-Forwards field-value is an integer greater than zero, the 2526 proxy MUST decrement the field-value when it forwards the request. If 2527 no Max-Forwards field is present in the request, then the forwarded 2528 request MUST NOT include a Max-Forwards field. 2530 9.3 GET 2532 The GET method means retrieve whatever information (in the form of an 2533 entity) is identified by the Request-URI. If the Request-URI refers 2534 to a data-producing process, it is the produced data which shall be 2535 returned as the entity in the response and not the source text of the 2536 process, unless that text happens to be the output of the process. 2538 The semantics of the GET method change to a "conditional GET" if the 2539 request message includes an If-Modified-Since, If-Unmodified-Since, 2540 If-Match, If-None-Match, or If-Range header field. A conditional GET 2541 method requests that the entity be transferred only under the 2542 circumstances described by the conditional header field(s). The 2543 conditional GET method is intended to reduce unnecessary network 2544 usage by allowing cached entities to be refreshed without requiring 2545 multiple requests or transferring data already held by the client. 2547 The semantics of the GET method change to a "partial GET" if the 2548 request message includes a Range header field. A partial GET requests 2549 that only part of the entity be transferred, as described in section 2550 14.35. The partial GET method is intended to reduce unnecessary 2551 network usage by allowing partially-retrieved entities to be 2552 completed without transferring data already held by the client. 2554 The response to a GET request is cacheable if and only if it meets 2555 the requirements for HTTP caching described in section 13. 2557 See section 15.1.3 for security considerations when used for forms. 2559 9.4 HEAD 2561 The HEAD method is identical to GET except that the server MUST NOT 2562 return a message-body in the response. The metainformation contained 2563 in the HTTP headers in response to a HEAD request SHOULD be identical 2564 to the information sent in response to a GET request. This method can 2565 be used for obtaining metainformation about the entity implied by the 2566 request without transferring the entity-body itself. This method is 2567 often used for testing hypertext links for validity, accessibility, 2568 and recent modification. 2570 The response to a HEAD request MAY be cacheable in the sense that the 2571 information contained in the response MAY be used to update a 2572 previously cached entity from that resource. If the new field values 2573 indicate that the cached entity differs from the current entity (as 2574 would be indicated by a change in Content-Length, Content-MD5, ETag 2575 or Last-Modified), then the cache MUST treat the cache entry as 2576 stale. 2578 9.5 POST 2580 The POST method is used to request that the origin server accept the 2581 entity enclosed in the request as a new subordinate of the resource 2582 identified by the Request-URI in the Request-Line. POST is designed 2583 to allow a uniform method to cover the following functions: 2585 . Annotation of existing resources; 2587 . Posting a message to a bulletin board, newsgroup, mailing list, 2588 or similar group of articles; 2590 . Providing a block of data, such as the result of submitting a 2591 form, to a data-handling process; 2593 . Extending a database through an append operation. 2595 The actual function performed by the POST method is determined by the 2596 server and is usually dependent on the Request-URI. The posted entity 2597 is subordinate to that URI in the same way that a file is subordinate 2598 to a directory containing it, a news article is subordinate to a 2599 newsgroup to which it is posted, or a record is subordinate to a 2600 database. 2602 The action performed by the POST method might not result in a 2603 resource that can be identified by a URI. In this case, either 200 2604 (OK) or 204 (No Content) is the appropriate response status, 2605 depending on whether or not the response includes an entity that 2606 describes the result. 2608 If a resource has been created on the origin server, the response 2609 SHOULD be 201 (Created) and contain an entity which describes the 2610 status of the request and refers to the new resource, and a Location 2611 header (see section 14.30). 2613 Responses to this method are not cacheable, unless the response 2614 includes appropriate Cache-Control or Expires header fields. However, 2615 the 303 (See Other) response can be used to direct the user agent to 2616 retrieve a cacheable resource. 2618 POST requests MUST obey the message transmission requirements set out 2619 in section 8.2. 2621 See section 15.1.3 for security considerations. 2623 9.6 PUT 2625 The PUT method requests that the enclosed entity be stored under the 2626 supplied Request-URI. If the Request-URI refers to an already 2627 existing resource, the enclosed entity SHOULD be considered as a 2628 modified version of the one residing on the origin server. If the 2629 Request-URI does not point to an existing resource, and that URI is 2630 capable of being defined as a new resource by the requesting user 2631 agent, the origin server can create the resource with that URI. If a 2632 new resource is created, the origin server MUST inform the user agent 2633 via the 201 (Created) response. If an existing resource is modified, 2634 either the 200 (OK) or 204 (No Content) response codes SHOULD be sent 2635 to indicate successful completion of the request. If the resource 2636 could not be created or modified with the Request-URI, an appropriate 2637 error response SHOULD be given that reflects the nature of the 2638 problem. The recipient of the entity MUST NOT ignore any Content-* 2639 (e.g. Content-Range) headers that it does not understand or implement 2640 and MUST return a 501 (Not Implemented) response in such cases. 2642 If the request passes through a cache and the Request-URI identifies 2643 one or more currently cached entities, those entries SHOULD be 2644 treated as stale. Responses to this method are not cacheable. 2646 The fundamental difference between the POST and PUT requests is 2647 reflected in the different meaning of the Request-URI. The URI in a 2648 POST request identifies the resource that will handle the enclosed 2649 entity. That resource might be a data-accepting process, a gateway to 2650 some other protocol, or a separate entity that accepts annotations. 2651 In contrast, the URI in a PUT request identifies the entity enclosed 2652 with the request -- the user agent knows what URI is intended and the 2653 server MUST NOT attempt to apply the request to some other resource. 2654 If the server desires that the request be applied to a different URI, 2655 it MUST send a 301 (Moved Permanently) response; the user agent MAY 2656 then make its own decision regarding whether or not to redirect the 2657 request. 2659 A single resource MAY be identified by many different URIs. For 2660 example, an article might have a URI for identifying "the current 2661 version" which is separate from the URI identifying each particular 2662 version. In this case, a PUT request on a general URI might result in 2663 several other URIs being defined by the origin server. 2665 HTTP/1.1 does not define how a PUT method affects the state of an 2666 origin server. 2668 PUT requests MUST obey the message transmission requirements set out 2669 in section 8.2. 2671 Unless otherwise specified for a particular entity-header, the 2672 entity-headers in the PUT request SHOULD be applied to the resource 2673 created or modified by the PUT. 2675 9.7 DELETE 2677 The DELETE method requests that the origin server delete the resource 2678 identified by the Request-URI. This method MAY be overridden by human 2679 intervention (or other means) on the origin server. The client cannot 2680 be guaranteed that the operation has been carried out, even if the 2681 status code returned from the origin server indicates that the action 2682 has been completed successfully. However, the server SHOULD NOT 2683 indicate success unless, at the time the response is given, it 2684 intends to delete the resource or move it to an inaccessible 2685 location. 2687 A successful response SHOULD be 200 (OK) if the response includes an 2688 entity describing the status, 202 (Accepted) if the action has not 2689 yet been enacted, or 204 (No Content) if the action has been enacted 2690 but the response does not include an entity. 2692 If the request passes through a cache and the Request-URI identifies 2693 one or more currently cached entities, those entries SHOULD be 2694 treated as stale. Responses to this method are not cacheable. 2696 9.8 TRACE 2698 The TRACE method is used to invoke a remote, application-layer loop- 2699 back of the request message. The final recipient of the request 2700 SHOULD reflect the message received back to the client as the entity- 2701 body of a 200 (OK) response. The final recipient is either the origin 2702 server or the first proxy or gateway to receive a Max-Forwards value 2703 of zero (0) in the request (see section 14.31). A TRACE request MUST 2704 NOT include an entity. 2706 TRACE allows the client to see what is being received at the other 2707 end of the request chain and use that data for testing or diagnostic 2708 information. The value of the Via header field (section 14.45) is of 2709 particular interest, since it acts as a trace of the request chain. 2710 Use of the Max-Forwards header field allows the client to limit the 2711 length of the request chain, which is useful for testing a chain of 2712 proxies forwarding messages in an infinite loop. 2714 If the request is valid, the response SHOULD contain the entire 2715 request message in the entity-body, with a Content-Type of 2716 "message/http". Responses to this method MUST NOT be cached. 2718 9.9 CONNECT 2720 This specification reserves the method name CONNECT for use with a 2721 proxy that can dynamically switch to being a tunnel (e.g. SSL 2722 tunneling [44]). 2724 10 Status Code Definitions 2726 Each Status-Code is described below, including a description of which 2727 method(s) it can follow and any metainformation required in the 2728 response. 2730 10.1 Informational 1xx 2732 This class of status code indicates a provisional response, 2733 consisting only of the Status-Line and optional headers, and is 2734 terminated by an empty line. There are no required headers for this 2735 class of status code. Since HTTP/1.0 did not define any 1xx status 2736 codes, servers MUST NOT send a 1xx response to an HTTP/1.0 client 2737 except under experimental conditions. 2739 A client MUST be prepared to accept one or more 1xx status responses 2740 prior to a regular response, even if the client does not expect a 100 2741 (Continue) status message. Unexpected 1xx status responses MAY be 2742 ignored by a user agent. 2744 Proxies MUST forward 1xx responses, unless the connection between the 2745 proxy and its client has been closed, or unless the proxy itself 2746 requested the generation of the 1xx response. (For example, if a 2747 proxy adds a "Expect: 100-continue" field when it forwards a request, 2748 then it need not forward the corresponding 100 (Continue) 2749 response(s).) 2751 10.1.1 100 Continue 2753 The client SHOULD continue with its request. This interim response is 2754 used to inform the client that the initial part of the request has 2755 been received and has not yet been rejected by the server. The client 2756 SHOULD continue by sending the remainder of the request or, if the 2757 request has already been completed, ignore this response. The server 2758 MUST send a final response after the request has been completed. See 2759 section 8.2.3 for detailed discussion of the use and handling of this 2760 status code. 2762 10.1.2 101 Switching Protocols 2764 The server understands and is willing to comply with the client's 2765 request, via the Upgrade message header field (section 14.42), for a 2766 change in the application protocol being used on this connection. The 2767 server will switch protocols to those defined by the response's 2768 Upgrade header field immediately after the empty line which 2769 terminates the 101 response. 2771 The protocol SHOULD be switched only when it is advantageous to do 2772 so. For example, switching to a newer version of HTTP is advantageous 2773 over older versions, and switching to a real-time, synchronous 2774 protocol might be advantageous when delivering resources that use 2775 such features. 2777 10.2 Successful 2xx 2779 This class of status code indicates that the client's request was 2780 successfully received, understood, and accepted. 2782 10.2.1 200 OK 2784 The request has succeeded. The information returned with the response 2785 is dependent on the method used in the request, for example: 2787 GET an entity corresponding to the requested resource is sent in the 2788 response; 2790 HEAD the entity-header fields corresponding to the requested resource 2791 are sent in the response without any message-body; 2793 POST an entity describing or containing the result of the action; 2795 TRACE an entity containing the request message as received by 2796 the end server. 2798 10.2.2 201 Created 2800 The request has been fulfilled and resulted in a new resource being 2801 created. The newly created resource can be referenced by the URI(s) 2802 returned in the entity of the response, with the most specific URI 2803 for the resource given by a Location header field. The response 2804 SHOULD include an entity containing a list of resource 2805 characteristics and location(s) from which the user or user agent can 2806 choose the one most appropriate. The entity format is specified by 2807 the media type given in the Content-Type header field. The origin 2808 server MUST create the resource before returning the 201 status code. 2809 If the action cannot be carried out immediately, the server SHOULD 2810 respond with 202 (Accepted) response instead. 2812 A 201 response MAY contain an ETag response header field indicating 2813 the current value of the entity tag for the requested variant just 2814 created, see section 14.19. 2816 10.2.3 202 Accepted 2818 The request has been accepted for processing, but the processing has 2819 not been completed. The request might or might not eventually be 2820 acted upon, as it might be disallowed when processing actually takes 2821 place. There is no facility for re-sending a status code from an 2822 asynchronous operation such as this. 2824 The 202 response is intentionally non-committal. Its purpose is to 2825 allow a server to accept a request for some other process (perhaps a 2826 batch-oriented process that is only run once per day) without 2827 requiring that the user agent's connection to the server persist 2828 until the process is completed. The entity returned with this 2829 response SHOULD include an indication of the request's current status 2830 and either a pointer to a status monitor or some estimate of when the 2831 user can expect the request to be fulfilled. 2833 10.2.4 203 Non-Authoritative Information 2835 The returned metainformation in the entity-header is not the 2836 definitive set as available from the origin server, but is gathered 2837 from a local or a third-party copy. The set presented MAY be a subset 2838 or superset of the original version. For example, including local 2839 annotation information about the resource might result in a superset 2840 of the metainformation known by the origin server. Use of this 2841 response code is not required and is only appropriate when the 2842 response would otherwise be 200 (OK). 2844 10.2.5 204 No Content 2846 The server has fulfilled the request but does not need to return an 2847 entity-body, and might want to return updated metainformation. The 2848 response MAY include new or updated metainformation in the form of 2849 entity-headers, which if present SHOULD be associated with the 2850 requested variant. 2852 If the client is a user agent, it SHOULD NOT change its document view 2853 from that which caused the request to be sent. This response is 2854 primarily intended to allow input for actions to take place without 2855 causing a change to the user agent's active document view, although 2856 any new or updated metainformation SHOULD be applied to the document 2857 currently in the user agent's active view. 2859 The 204 response MUST NOT include a message-body, and thus is always 2860 terminated by the first empty line after the header fields. 2862 10.2.6 205 Reset Content 2864 The server has fulfilled the request and the user agent SHOULD reset 2865 the document view which caused the request to be sent. This response 2866 is primarily intended to allow input for actions to take place via 2867 user input, followed by a clearing of the form in which the input is 2868 given so that the user can easily initiate another input action. The 2869 response MUST NOT include an entity. 2871 10.2.7 206 Partial Content 2873 The server has fulfilled the partial GET request for the resource. 2874 The request MUST have included a Range header field (section 14.35) 2875 indicating the desired range, and MAY have included an If-Range 2876 header field (section 14.27) to make the request conditional. 2878 The response MUST include the following header fields: 2880 . Either a Content-Range header field (section 14.16) indicating 2881 the range included with this response, or a multipart/byteranges 2882 Content-Type including Content-Range fields for each part. If a 2883 Content-Length header field is present in the response, its 2884 value MUST match the actual number of OCTETs transmitted in the 2885 message-body. 2887 . Date 2889 . ETag and/or Content-Location, if the header would have been sent 2890 in a 200 response to the same request 2892 . Expires, Cache-Control, and/or Vary, if the field-value might 2893 differ from that sent in any previous response for the same 2894 variant 2896 If the 206 response is the result of an If-Range request that used a 2897 strong cache validator (see section 13.3.3), the response SHOULD NOT 2898 include other entity-headers. If the response is the result of an If- 2899 Range request that used a weak validator, the response MUST NOT 2900 include other entity-headers; this prevents inconsistencies between 2901 cached entity-bodies and updated headers. Otherwise, the response 2902 MUST include all of the entity-headers that would have been returned 2903 with a 200 (OK) response to the same request. 2905 A cache MUST NOT combine a 206 response with other previously cached 2906 content if the ETag or Last-Modified headers do not match exactly, 2907 see 13.5.4. 2909 A cache that does not support the Range and Content-Range headers 2910 MUST NOT cache 206 (Partial) responses. 2912 10.3 Redirection 3xx 2914 This class of status code indicates that further action needs to be 2915 taken by the user agent in order to fulfill the request. The action 2916 required MAY be carried out by the user agent without interaction 2917 with the user if and only if the method used in the second request is 2918 GET or HEAD. A client SHOULD detect infinite redirection loops, since 2919 such loops generate network traffic for each redirection. 2921 Note: previous versions of this specification recommended a 2922 maximum of five redirections. Content developers should be 2923 aware that there might be clients that implement such a fixed 2924 limitation. 2926 10.3.1 300 Multiple Choices 2928 The requested resource corresponds to any one of a set of 2929 representations, each with its own specific location, and agent- 2930 driven negotiation information (section 12) is being provided so that 2931 the user (or user agent) can select a preferred representation and 2932 redirect its request to that location. 2934 Unless it was a HEAD request, the response SHOULD include an entity 2935 containing a list of resource characteristics and location(s) from 2936 which the user or user agent can choose the one most appropriate. The 2937 entity format is specified by the media type given in the Content- 2938 Type header field. Depending upon the format and the capabilities of 2939 the user agent, selection of the most appropriate choice MAY be 2940 performed automatically. However, this specification does not define 2941 any standard for such automatic selection. 2943 If the server has a preferred choice of representation, it SHOULD 2944 include the specific URI for that representation in the Location 2945 field; user agents MAY use the Location field value for automatic 2946 redirection. This response is cacheable unless indicated otherwise. 2948 10.3.2 301 Moved Permanently 2950 The requested resource has been assigned a new permanent URI and any 2951 future references to this resource SHOULD use one of the returned 2952 URIs. Clients with link editing capabilities ought to automatically 2953 re-link references to the Request-URI to one or more of the new 2954 references returned by the server, where possible. This response is 2955 cacheable unless indicated otherwise. 2957 The new permanent URI SHOULD be given by the Location field in the 2958 response. Unless the request method was HEAD, the entity of the 2959 response SHOULD contain a short hypertext note with a hyperlink to 2960 the new URI(s). 2962 If the 301 status code is received in response to a request other 2963 than GET or HEAD, the user agent MUST NOT automatically redirect the 2964 request unless it can be confirmed by the user, since this might 2965 change the conditions under which the request was issued. 2967 Note: When automatically redirecting a POST request after 2968 receiving a 301 status code, some existing HTTP/1.0 user agents 2969 will erroneously change it into a GET request. 2971 10.3.3 302 Found 2973 The requested resource resides temporarily under a different URI. 2974 Since the redirection might be altered on occasion, the client SHOULD 2975 continue to use the Request-URI for future requests. This response 2976 is only cacheable if indicated by a Cache-Control or Expires header 2977 field. 2979 The temporary URI SHOULD be given by the Location field in the 2980 response. Unless the request method was HEAD, the entity of the 2981 response SHOULD contain a short hypertext note with a hyperlink to 2982 the new URI(s). 2984 If the 302 status code is received in response to a request other 2985 than GET or HEAD, the user agent MUST NOT automatically redirect the 2986 request unless it can be confirmed by the user, since this might 2987 change the conditions under which the request was issued. 2989 Note: RFC 1945 and RFC 2068 specify that the client is not 2990 allowed to change the method on the redirected request. 2991 However, most existing user agent implementations treat 302 as 2992 if it were a 303 response, performing a GET on the Location 2993 field-value regardless of the original request method. The 2994 status codes 303 and 307 have been added for servers that wish 2995 to make unambiguously clear which kind of reaction is expected 2996 of the client. 2998 10.3.4 303 See Other 3000 The response to the request can be found under a different URI and 3001 SHOULD be retrieved using a GET method on that resource. This method 3002 exists primarily to allow the output of a POST-activated script to 3003 redirect the user agent to a selected resource. The new URI is not a 3004 substitute reference for the originally requested resource. The 303 3005 response MUST NOT be cached, but the response to the second 3006 (redirected) request might be cacheable. 3008 The different URI SHOULD be given by the Location field in the 3009 response. Unless the request method was HEAD, the entity of the 3010 response SHOULD contain a short hypertext note with a hyperlink to 3011 the new URI(s). 3013 Note: Many pre-HTTP/1.1 user agents do not understand the 303 3014 status. When interoperability with such clients is a concern, 3015 the 302 status code may be used instead, since most user agents 3016 react to a 302 response as described here for 303. 3018 10.3.5 304 Not Modified 3020 If the client has performed a conditional GET request and access is 3021 allowed, but the document has not been modified, the server SHOULD 3022 respond with this status code. The 304 response MUST NOT contain a 3023 message-body, and thus is always terminated by the first empty line 3024 after the header fields. 3026 The response MUST include the following header fields: 3028 . Date, unless its omission is required by section 14.18.1 3030 If a clockless origin server obeys these rules, and proxies and 3031 clients add their own Date to any response received without one (as 3032 already specified by [RFC 2068], section 14.19), caches will operate 3033 correctly. 3035 . ETag and/or Content-Location, if the header would have been sent 3036 in a 200 response to the same request 3038 . Expires, Cache-Control, and/or Vary, if the field-value might 3039 differ from that sent in any previous response for the same 3040 variant 3042 If the conditional GET used a strong cache validator (see section 3043 13.3.3), the response SHOULD NOT include other entity-headers. 3044 Otherwise (i.e., the conditional GET used a weak validator), the 3045 response MUST NOT include other entity-headers; this prevents 3046 inconsistencies between cached entity-bodies and updated headers. 3048 If a 304 response indicates an entity not currently cached, then the 3049 cache MUST disregard the response and repeat the request without the 3050 conditional. 3052 If a cache uses a received 304 response to update a cache entry, the 3053 cache MUST update the entry to reflect any new field values given in 3054 the response. 3056 10.3.6 305 Use Proxy 3058 The requested resource MUST be accessed through the proxy given by 3059 the Location field. The Location field gives the URI of the proxy. 3060 The recipient is expected to repeat this single request via the 3061 proxy. 305 responses MUST only be generated by origin servers. 3063 Note: RFC 2068 was not clear that 305 was intended to redirect 3064 a single request, and to be generated by origin servers only. 3065 Not observing these limitations has significant security 3066 consequences. 3068 10.3.7 306 (Unused) 3070 The 306 status code was used in a previous version of the 3071 specification, is no longer used, and the code is reserved. 3073 10.3.8 307 Temporary Redirect 3075 The requested resource resides temporarily under a different URI. 3076 Since the redirection MAY be altered on occasion, the client SHOULD 3077 continue to use the Request-URI for future requests. This response 3078 is only cacheable if indicated by a Cache-Control or Expires header 3079 field. 3081 The temporary URI SHOULD be given by the Location field in the 3082 response. Unless the request method was HEAD, the entity of the 3083 response SHOULD contain a short hypertext note with a hyperlink to 3084 the new URI(s) , since many pre-HTTP/1.1 user agents do not 3085 understand the 307 status. Therefore, the note SHOULD contain the 3086 information necessary for a user to repeat the original request on 3087 the new URI. 3089 If the 307 status code is received in response to a request other 3090 than GET or HEAD, the user agent MUST NOT automatically redirect the 3091 request unless it can be confirmed by the user, since this might 3092 change the conditions under which the request was issued. 3094 10.4 Client Error 4xx 3096 The 4xx class of status code is intended for cases in which the 3097 client seems to have erred. Except when responding to a HEAD request, 3098 the server SHOULD include an entity containing an explanation of the 3099 error situation, and whether it is a temporary or permanent 3100 condition. These status codes are applicable to any request method. 3101 User agents SHOULD display any included entity to the user. 3103 If the client is sending data, a server implementation using TCP 3104 SHOULD be careful to ensure that the client acknowledges receipt of 3105 the packet(s) containing the response, before the server closes the 3106 input connection. If the client continues sending data to the server 3107 after the close, the server's TCP stack will send a reset packet to 3108 the client, which may erase the client's unacknowledged input buffers 3109 before they can be read and interpreted by the HTTP application. 3111 10.4.1 400 Bad Request 3113 The request could not be understood by the server due to malformed 3114 syntax. The client SHOULD NOT repeat the request without 3115 modifications. 3117 10.4.2 401 Unauthorized 3119 The request requires user authentication. The response MUST include a 3120 WWW-Authenticate header field (section 14.47) containing a challenge 3121 applicable to the requested resource. The client MAY repeat the 3122 request with a suitable Authorization header field (section 14.8). If 3123 the request already included Authorization credentials, then the 401 3124 response indicates that authorization has been refused for those 3125 credentials. If the 401 response contains the same challenge as the 3126 prior response, and the user agent has already attempted 3127 authentication at least once, then the user SHOULD be presented the 3128 entity that was given in the response, since that entity might 3129 include relevant diagnostic information. HTTP access authentication 3130 is explained in "HTTP Authentication: Basic and Digest Access 3131 Authentication" [43]. 3133 10.4.3 402 Payment Required 3135 This code is reserved for future use. 3137 10.4.4 403 Forbidden 3139 The server understood the request, but is refusing to fulfill it. 3140 Authorization will not help and the request SHOULD NOT be repeated. 3141 If the request method was not HEAD and the server wishes to make 3142 public why the request has not been fulfilled, it SHOULD describe the 3143 reason for the refusal in the entity. If the server does not wish to 3144 make this information available to the client, the status code 404 3145 (Not Found) can be used instead. 3147 10.4.5 404 Not Found 3149 The server has not found anything matching the Request-URI. No 3150 indication is given of whether the condition is temporary or 3151 permanent. The 410 (Gone) status code SHOULD be used if the server 3152 knows, through some internally configurable mechanism, that an old 3153 resource is permanently unavailable and has no forwarding address. 3154 This status code is commonly used when the server does not wish to 3155 reveal exactly why the request has been refused, or when no other 3156 response is applicable. 3158 10.4.6 405 Method Not Allowed 3160 The method specified in the Request-Line is not allowed for the 3161 resource identified by the Request-URI. The response MUST include an 3162 Allow header containing a list of valid methods for the requested 3163 resource. 3165 10.4.7 406 Not Acceptable 3167 The resource identified by the request is only capable of generating 3168 response entities which have content characteristics not acceptable 3169 according to the accept headers sent in the request. 3171 Unless it was a HEAD request, the response SHOULD include an entity 3172 containing a list of available entity characteristics and location(s) 3173 from which the user or user agent can choose the one most 3174 appropriate. The entity format is specified by the media type given 3175 in the Content-Type header field. Depending upon the format and the 3176 capabilities of the user agent, selection of the most appropriate 3177 choice MAY be performed automatically. However, this specification 3178 does not define any standard for such automatic selection. 3180 Note: HTTP/1.1 servers are allowed to return responses which 3181 are not acceptable according to the accept headers sent in the 3182 request. In some cases, this may even be preferable to sending 3183 a 406 response. User agents are encouraged to inspect the 3184 headers of an incoming response to determine if it is 3185 acceptable. 3187 If the response could be unacceptable, a user agent SHOULD 3188 temporarily stop receipt of more data and query the user for a 3189 decision on further actions. 3191 10.4.8 407 Proxy Authentication Required 3193 This code is similar to 401 (Unauthorized), but indicates that the 3194 client must first authenticate itself with the proxy. The proxy MUST 3195 return a Proxy-Authenticate header field (section 14.33) containing a 3196 challenge applicable to the proxy for the requested resource. The 3197 client MAY repeat the request with a suitable Proxy-Authorization 3198 header field (section 14.34). HTTP access authentication is explained 3199 in "HTTP Authentication: Basic and Digest Access Authentication" 3200 [43]. 3202 10.4.9 408 Request Timeout 3204 The client did not produce a request within the time that the server 3205 was prepared to wait. The client MAY repeat the request without 3206 modifications at any later time. 3208 10.4.10 409 Conflict 3210 The request could not be completed due to a conflict with the current 3211 state of the resource. This code is only allowed in situations where 3212 it is expected that the user might be able to resolve the conflict 3213 and resubmit the request. The response body SHOULD include enough 3214 information for the user to recognize the source of the conflict. 3215 Ideally, the response entity would include enough information for the 3216 user or user agent to fix the problem; however, that might not be 3217 possible and is not required. 3219 Conflicts are most likely to occur in response to a PUT request. For 3220 example, if versioning were being used and the entity being PUT 3221 included changes to a resource which conflict with those made by an 3222 earlier (third-party) request, the server might use the 409 response 3223 to indicate that it can't complete the request. In this case, the 3224 response entity would likely contain a list of the differences 3225 between the two versions in a format defined by the response Content- 3226 Type. 3228 10.4.11 410 Gone 3230 The requested resource is no longer available at the server and no 3231 forwarding address is known. This condition is expected to be 3232 considered permanent. Clients with link editing capabilities SHOULD 3233 delete references to the Request-URI after user approval. If the 3234 server does not know, or has no facility to determine, whether or not 3235 the condition is permanent, the status code 404 (Not Found) SHOULD be 3236 used instead. This response is cacheable unless indicated otherwise. 3238 The 410 response is primarily intended to assist the task of web 3239 maintenance by notifying the recipient that the resource is 3240 intentionally unavailable and that the server owners desire that 3241 remote links to that resource be removed. Such an event is common for 3242 limited-time, promotional services and for resources belonging to 3243 individuals no longer working at the server's site. It is not 3244 necessary to mark all permanently unavailable resources as "gone" or 3245 to keep the mark for any length of time -- that is left to the 3246 discretion of the server owner. 3248 10.4.12 411 Length Required 3250 The server refuses to accept the request without a defined Content- 3251 Length. The client MAY repeat the request if it adds a valid Content- 3252 Length header field containing the length of the message-body in the 3253 request message. 3255 10.4.13 412 Precondition Failed 3257 The precondition given in one or more of the request-header fields 3258 evaluated to false when it was tested on the server. This response 3259 code allows the client to place preconditions on the current resource 3260 metainformation (header field data) and thus prevent the requested 3261 method from being applied to a resource other than the one intended. 3263 10.4.14 413 Request Entity Too Large 3265 The server is refusing to process a request because the request 3266 entity is larger than the server is willing or able to process. The 3267 server MAY close the connection to prevent the client from continuing 3268 the request. 3270 If the condition is temporary, the server SHOULD include a Retry- 3271 After header field to indicate that it is temporary and after what 3272 time the client MAY try again. 3274 10.4.15 414 Request-URI Too Long 3276 The server is refusing to service the request because the Request-URI 3277 is longer than the server is willing to interpret. This rare 3278 condition is only likely to occur when a client has improperly 3279 converted a POST request to a GET request with long query 3280 information, when the client has descended into a URI "black hole" of 3281 redirection (e.g., a redirected URI prefix that points to a suffix of 3282 itself), or when the server is under attack by a client attempting to 3283 exploit security holes present in some servers using fixed-length 3284 buffers for reading or manipulating the Request-URI. 3286 10.4.16 415 Unsupported Media Type 3288 The server is refusing to service the request because the entity of 3289 the request is in a format not supported by the requested resource 3290 for the requested method. 3292 10.4.17 416 Requested Range Not Satisfiable 3294 A server SHOULD return a response with this status code if a request 3295 included a Range request-header field (section 14.35) , and none of 3296 the range-specifier values in this field overlap the current extent 3297 of the selected resource, and the request did not include an If-Range 3298 request-header field. (For byte-ranges, this means that the first- 3299 byte-pos of all of the byte-range-spec values were greater than the 3300 current length of the selected resource.) 3302 When this status code is returned for a byte-range request, the 3303 response SHOULD include a Content-Range entity-header field 3304 specifying the current length of the selected resource (see section 3305 14.16). This response MUST NOT use the multipart/byteranges content- 3306 type. 3308 10.4.18 417 Expectation Failed 3310 The expectation given in an Expect request-header field (see section 3311 14.20) could not be met by this server, or, if the server is a proxy, 3312 the server has unambiguous evidence that the request could not be met 3313 by the next-hop server. 3315 10.5 Server Error 5xx 3317 Response status codes beginning with the digit "5" indicate cases in 3318 which the server is aware that it has erred or is incapable of 3319 performing the request. Except when responding to a HEAD request, the 3320 server SHOULD include an entity containing an explanation of the 3321 error situation, and whether it is a temporary or permanent 3322 condition. User agents SHOULD display any included entity to the 3323 user. These response codes are applicable to any request method. 3325 10.5.1 500 Internal Server Error 3327 The server encountered an unexpected condition which prevented it 3328 from fulfilling the request. 3330 10.5.2 501 Not Implemented 3332 The server does not support the functionality required to fulfill the 3333 request. This is the appropriate response when the server does not 3334 recognize the request method and is not capable of supporting it for 3335 any resource. 3337 10.5.3 502 Bad Gateway 3339 The server, while acting as a gateway or proxy, received an invalid 3340 response from the upstream server it accessed in attempting to 3341 fulfill the request. 3343 10.5.4 503 Service Unavailable 3345 The server is currently unable to handle the request due to a 3346 temporary overloading or maintenance of the server. The implication 3347 is that this is a temporary condition which will be alleviated after 3348 some delay. If known, the length of the delay MAY be indicated in a 3349 Retry-After header. If no Retry-After is given, the client SHOULD 3350 handle the response as it would for a 500 response. 3352 Note: The existence of the 503 status code does not imply that 3353 a server must use it when becoming overloaded. Some servers may 3354 wish to simply refuse the connection. 3356 10.5.5 504 Gateway Timeout 3358 The server, while acting as a gateway or proxy, did not receive a 3359 timely response from the upstream server specified by the URI (e.g. 3360 HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed 3361 to access in attempting to complete the request. 3363 Note: Note to implementors: some deployed proxies are known to 3364 return 400 or 500 when DNS lookups time out. 3366 10.5.6 505 HTTP Version Not Supported 3368 The server does not support, or refuses to support, the HTTP protocol 3369 version that was used in the request message. The server is 3370 indicating that it is unable or unwilling to complete the request 3371 using the same major version as the client, as described in section 3372 3.1, other than with this error message. The response SHOULD contain 3373 an entity describing why that version is not supported and what other 3374 protocols are supported by that server. 3376 11 Access Authentication 3377 HTTP provides several OPTIONAL challenge-response authentication 3378 mechanisms which can be used by a server to challenge a client 3379 request and by a client to provide authentication information. The 3380 general framework for access authentication, and the specification of 3381 "basic" and "digest" authentication, are specified in "HTTP 3382 Authentication: Basic and Digest Access Authentication" [43]. This 3383 specification adopts the definitions of "challenge" and "credentials" 3384 from that specification. 3386 12 Content Negotiation 3388 Most HTTP responses include an entity which contains information for 3389 interpretation by a human user. Naturally, it is desirable to supply 3390 the user with the "best available" entity corresponding to the 3391 request. Unfortunately for servers and caches, not all users have the 3392 same preferences for what is "best," and not all user agents are 3393 equally capable of rendering all entity types. For that reason, HTTP 3394 has provisions for several mechanisms for "content negotiation" -- 3395 the process of selecting the best representation for a given response 3396 when there are multiple representations available. 3398 Note: This is not called "format negotiation" because the 3399 alternate representations may be of the same media type, but 3400 use different capabilities of that type, be in different 3401 languages, etc. 3403 Any response containing an entity-body MAY be subject to negotiation, 3404 including error responses. 3406 There are two kinds of content negotiation which are possible in 3407 HTTP: server-driven and agent-driven negotiation. These two kinds of 3408 negotiation are orthogonal and thus may be used separately or in 3409 combination. One method of combination, referred to as transparent 3410 negotiation, occurs when a cache uses the agent-driven negotiation 3411 information provided by the origin server in order to provide server- 3412 driven negotiation for subsequent requests. 3414 12.1 Server-driven Negotiation 3416 If the selection of the best representation for a response is made by 3417 an algorithm located at the server, it is called server-driven 3418 negotiation. Selection is based on the available representations of 3419 the response (the dimensions over which it can vary; e.g. language, 3420 content-coding, etc.) and the contents of particular header fields in 3421 the request message or on other information pertaining to the request 3422 (such as the network address of the client). 3424 Server-driven negotiation is advantageous when the algorithm for 3425 selecting from among the available representations is difficult to 3426 describe to the user agent, or when the server desires to send its 3427 "best guess" to the client along with the first response (hoping to 3428 avoid the round-trip delay of a subsequent request if the "best 3429 guess" is good enough for the user). In order to improve the server's 3430 guess, the user agent MAY include request header fields (Accept, 3431 Accept-Language, Accept-Encoding, etc.) which describe its 3432 preferences for such a response. 3434 Server-driven negotiation has disadvantages: 3436 1. It is impossible for the server to accurately determine what 3437 might be "best" for any given user, since that would require 3438 complete knowledge of both the capabilities of the user agent 3439 and the intended use for the response (e.g., does the user want 3440 to view it on screen or print it on paper?). 3442 2. Having the user agent describe its capabilities in every request 3443 can be both very inefficient (given that only a small percentage 3444 of responses have multiple representations) and a potential 3445 violation of the user's privacy. 3447 3. It complicates the implementation of an origin server and the 3448 algorithms for generating responses to a request. 3450 4. It may limit a public cache's ability to use the same response 3451 for multiple user's requests. 3453 HTTP/1.1 includes the following request-header fields for enabling 3454 server-driven negotiation through description of user agent 3455 capabilities and user preferences: Accept (section 14.1), Accept- 3456 Charset (section 14.2), Accept-Encoding (section 14.3), Accept- 3457 Language (section 14.4), and User-Agent (section 14.43). However, an 3458 origin server is not limited to these dimensions and MAY vary the 3459 response based on any aspect of the request, including information 3460 outside the request-header fields or within extension header fields 3461 not defined by this specification. 3463 The Vary header field can be used to express the parameters the 3464 server uses to select a representation that is subject to server- 3465 driven negotiation. See section 13.6 for use of the Vary header field 3466 by caches and section 14.44 for use of the Vary header field by 3467 servers. 3469 12.2 Agent-driven Negotiation 3471 With agent-driven negotiation, selection of the best representation 3472 for a response is performed by the user agent after receiving an 3473 initial response from the origin server. Selection is based on a list 3474 of the available representations of the response included within the 3475 header fields (this specification reserves the header name 3476 Alternates) or entity-body of the initial response, with each 3477 representation identified by its own URI. Selection from among the 3478 representations may be performed automatically (if the user agent is 3479 capable of doing so) or manually by the user selecting from a 3480 generated (possibly hypertext) menu. 3482 Agent-driven negotiation is advantageous when the response would vary 3483 over commonly-used dimensions (such as type, language, or encoding), 3484 when the origin server is unable to determine a user agent's 3485 capabilities from examining the request, and generally when public 3486 caches are used to distribute server load and reduce network usage. 3488 Agent-driven negotiation suffers from the disadvantage of needing a 3489 second request to obtain the best alternate representation. This 3490 second request is only efficient when caching is used. In addition, 3491 this specification does not define any mechanism for supporting 3492 automatic selection, though it also does not prevent any such 3493 mechanism from being developed as an extension and used within 3494 HTTP/1.1. 3496 HTTP/1.1 defines the 300 (Multiple Choices) and 406 (Not Acceptable) 3497 status codes for enabling agent-driven negotiation when the server is 3498 unwilling or unable to provide a varying response using server-driven 3499 negotiation. 3501 12.3 Transparent Negotiation 3503 Transparent negotiation is a combination of both server-driven and 3504 agent-driven negotiation. When a cache is supplied with a form of the 3505 list of available representations of the response (as in agent-driven 3506 negotiation) and the dimensions of variance are completely understood 3507 by the cache, then the cache becomes capable of performing server- 3508 driven negotiation on behalf of the origin server for subsequent 3509 requests on that resource. 3511 Transparent negotiation has the advantage of distributing the 3512 negotiation work that would otherwise be required of the origin 3513 server and also removing the second request delay of agent-driven 3514 negotiation when the cache is able to correctly guess the right 3515 response. 3517 This specification does not define any mechanism for transparent 3518 negotiation, though it also does not prevent any such mechanism from 3519 being developed as an extension that could be used within HTTP/1.1. 3521 13 Caching in HTTP 3523 HTTP is typically used for distributed information systems, where 3524 performance can be improved by the use of response caches. The 3525 HTTP/1.1 protocol includes a number of elements intended to make 3526 caching work as well as possible. Because these elements are 3527 inextricable from other aspects of the protocol, and because they 3528 interact with each other, it is useful to describe the basic caching 3529 design of HTTP separately from the detailed descriptions of methods, 3530 headers, response codes, etc. 3532 Caching would be useless if it did not significantly improve 3533 performance. The goal of caching in HTTP/1.1 is to eliminate the need 3534 to send requests in many cases, and to eliminate the need to send 3535 full responses in many other cases. The former reduces the number of 3536 network round-trips required for many operations; we use an 3537 "expiration" mechanism for this purpose (see section 13.2). The 3538 latter reduces network bandwidth requirements; we use a "validation" 3539 mechanism for this purpose (see section 13.3). 3541 Requirements for performance, availability, and disconnected 3542 operation require us to be able to relax the goal of semantic 3543 transparency. The HTTP/1.1 protocol allows origin servers, caches, 3544 and clients to explicitly reduce transparency when necessary. 3545 However, because non-transparent operation may confuse non-expert 3546 users, and might be incompatible with certain server applications 3547 (such as those for ordering merchandise), the protocol requires that 3548 transparency be relaxed 3550 . only by an explicit protocol-level request when relaxed by 3551 client or origin server 3553 . only with an explicit warning to the end user when relaxed by 3554 cache or client 3556 Therefore, the HTTP/1.1 protocol provides these important elements: 3558 1. Protocol features that provide full semantic transparency when 3559 this is required by all parties. 3561 2. Protocol features that allow an origin server or user agent to 3562 explicitly request and control non-transparent operation. 3564 3. Protocol features that allow a cache to attach warnings to 3565 responses that do not preserve the requested approximation of 3566 semantic transparency. 3568 A basic principle is that it must be possible for the clients to 3569 detect any potential relaxation of semantic transparency. 3571 Note: The server, cache, or client implementor might be faced 3572 with design decisions not explicitly discussed in this 3573 specification. If a decision might affect semantic 3574 transparency, the implementor ought to err on the side of 3575 maintaining transparency unless a careful and complete analysis 3576 shows significant benefits in breaking transparency. 3578 13.1.1 Cache Correctness 3580 A correct cache MUST respond to a request with the most up-to-date 3581 response held by the cache that is appropriate to the request (see 3582 sections 13.2.5, 13.2.6, and 13.12) which meets one of the following 3583 conditions: 3585 1. It has been checked for equivalence with what the origin server 3586 would have returned by revalidating the response with the origin 3587 server (section 13.3); 3589 2. It is "fresh enough" (see section 13.2). In the default case, 3590 this means it meets the least restrictive freshness requirement 3591 of the client, origin server, and cache (see section 14.9); if 3592 the origin server so specifies, it is the freshness requirement 3593 of the origin server alone. 3595 If a stored response is not "fresh enough" by the most 3596 restrictive freshness requirement of both the client and the 3597 origin server, in carefully considered circumstances the cache 3598 MAY still return the response with the appropriate Warning 3599 header (see section 13.1.5 and 14.46), unless such a response is 3600 prohibited (e.g., by a "no-store" cache-directive, or by a "no- 3601 cache" cache-request-directive; see section 14.9). 3603 3. It is an appropriate 304 (Not Modified), 305 (Proxy Redirect), 3604 or error (4xx or 5xx) response message. 3606 If the cache can not communicate with the origin server, then a 3607 correct cache SHOULD respond as above if the response can be 3608 correctly served from the cache; if not it MUST return an error or 3609 warning indicating that there was a communication failure. 3611 If a cache receives a response (either an entire response, or a 304 3612 (Not Modified) response) that it would normally forward to the 3613 requesting client, and the received response is no longer fresh, the 3614 cache SHOULD forward it to the requesting client without adding a new 3615 Warning (but without removing any existing Warning headers). A cache 3616 SHOULD NOT attempt to revalidate a response simply because that 3617 response became stale in transit; this might lead to an infinite 3618 loop. A user agent that receives a stale response without a Warning 3619 MAY display a warning indication to the user. 3621 13.1.2 Warnings 3623 Whenever a cache returns a response that is neither first-hand nor 3624 "fresh enough" (in the sense of condition 2 in section 13.1.1), it 3625 MUST attach a warning to that effect, using a Warning general-header. 3626 The Warning header and the currently defined warnings are described 3627 in section 14.46. The warning allows clients to take appropriate 3628 action. 3630 Warnings MAY be used for other purposes, both cache-related and 3631 otherwise. The use of a warning, rather than an error status code, 3632 distinguish these responses from true failures. 3634 Warnings are assigned three digit warn-codes. The first digit 3635 indicates whether the Warning MUST or MUST NOT be deleted from a 3636 stored cache entry after a successful revalidation: 3638 1xx Warnings that describe the freshness or revalidation status of 3639 the response, and so MUST be deleted after a successful 3640 revalidation. 1XX warn-codes MAY be generated by a cache only when 3641 validating a cached entry. It MUST NOT be generated by clients. 3643 2xx Warnings that describe some aspect of the entity body or entity 3644 headers that is not rectified by a revalidation (for example, a 3645 lossy compression of the entity bodies) and which MUST NOT be 3646 deleted after a successful revalidation. 3648 See section 14.46 for the definitions of the codes themselves. 3650 HTTP/1.0 caches will cache all Warnings in responses, without 3651 deleting the ones in the first category. Warnings in responses that 3652 are passed to HTTP/1.0 caches carry an extra warning-date field, 3653 which prevents a future HTTP/1.1 recipient from believing an 3654 erroneously cached Warning. 3656 Warnings also carry a warning text. The text MAY be in any 3657 appropriate natural language (perhaps based on the client's Accept 3658 headers), and include an OPTIONAL indication of what character set is 3659 used. 3661 Multiple warnings MAY be attached to a response (either by the origin 3662 server or by a cache), including multiple warnings with the same code 3663 number. For example, a server might provide the same warning with 3664 texts in both English and Basque. 3666 When multiple warnings are attached to a response, it might not be 3667 practical or reasonable to display all of them to the user. This 3668 version of HTTP does not specify strict priority rules for deciding 3669 which warnings to display and in what order, but does suggest some 3670 heuristics. 3672 13.1.3 Cache-control Mechanisms 3674 The basic cache mechanisms in HTTP/1.1 (server-specified expiration 3675 times and validators) are implicit directives to caches. In some 3676 cases, a server or client might need to provide explicit directives 3677 to the HTTP caches. We use the Cache-Control header for this purpose. 3679 The Cache-Control header allows a client or server to transmit a 3680 variety of directives in either requests or responses. These 3681 directives typically override the default caching algorithms. As a 3682 general rule, if there is any apparent conflict between header 3683 values, the most restrictive interpretation is applied (that is, the 3684 one that is most likely to preserve semantic transparency). However, 3685 in some cases, cache-control directives are explicitly specified as 3686 weakening the approximation of semantic transparency (for example, 3687 "max-stale" or "public"). 3689 The cache-control directives are described in detail in section 14.9. 3691 13.1.4 Explicit User Agent Warnings 3693 Many user agents make it possible for users to override the basic 3694 caching mechanisms. For example, the user agent might allow the user 3695 to specify that cached entities (even explicitly stale ones) are 3696 never validated. Or the user agent might habitually add "Cache- 3697 Control: max-stale=3600" to every request. The user agent SHOULD NOT 3698 default to either non-transparent behavior, or behavior that results 3699 in abnormally ineffective caching, but MAY be explicitly configured 3700 to do so by an explicit action of the user. 3702 If the user has overridden the basic caching mechanisms, the user 3703 agent SHOULD explicitly indicate to the user whenever this results in 3704 the display of information that might not meet the server's 3705 transparency requirements (in particular, if the displayed entity is 3706 known to be stale). Since the protocol normally allows the user agent 3707 to determine if responses are stale or not, this indication need only 3708 be displayed when this actually happens. The indication need not be a 3709 dialog box; it could be an icon (for example, a picture of a rotting 3710 fish) or some other indicator. 3712 If the user has overridden the caching mechanisms in a way that would 3713 abnormally reduce the effectiveness of caches, the user agent SHOULD 3714 continually indicate this state to the user (for example, by a 3715 display of a picture of currency in flames) so that the user does not 3716 inadvertently consume excess resources or suffer from excessive 3717 latency. 3719 13.1.5 Exceptions to the Rules and Warnings 3721 In some cases, the operator of a cache MAY choose to configure it to 3722 return stale responses even when not requested by clients. This 3723 decision ought not be made lightly, but may be necessary for reasons 3724 of availability or performance, especially when the cache is poorly 3725 connected to the origin server. Whenever a cache returns a stale 3726 response, it MUST mark it as such (using a Warning header) enabling 3727 the client software to alert the user that there might be a potential 3728 problem. 3730 It also allows the user agent to take steps to obtain a first-hand or 3731 fresh response. For this reason, a cache SHOULD NOT return a stale 3732 response if the client explicitly requests a first-hand or fresh one, 3733 unless it is impossible to comply for technical or policy reasons. 3735 13.1.6 Client-controlled Behavior 3737 While the origin server (and to a lesser extent, intermediate caches, 3738 by their contribution to the age of a response) are the primary 3739 source of expiration information, in some cases the client might need 3740 to control a cache's decision about whether to return a cached 3741 response without validating it. Clients do this using several 3742 directives of the Cache-Control header. 3744 A client's request MAY specify the maximum age it is willing to 3745 accept of an unvalidated response; specifying a value of zero forces 3746 the cache(s) to revalidate all responses. A client MAY also specify 3747 the minimum time remaining before a response expires. Both of these 3748 options increase constraints on the behavior of caches, and so cannot 3749 further relax the cache's approximation of semantic transparency. 3751 A client MAY also specify that it will accept stale responses, up to 3752 some maximum amount of staleness. This loosens the constraints on the 3753 caches, and so might violate the origin server's specified 3754 constraints on semantic transparency, but might be necessary to 3755 support disconnected operation, or high availability in the face of 3756 poor connectivity. 3758 13.2 Expiration Model 3760 13.2.1 Server-Specified Expiration 3762 HTTP caching works best when caches can entirely avoid making 3763 requests to the origin server. The primary mechanism for avoiding 3764 requests is for an origin server to provide an explicit expiration 3765 time in the future, indicating that a response MAY be used to satisfy 3766 subsequent requests. In other words, a cache can return a fresh 3767 response without first contacting the server. 3769 Our expectation is that servers will assign future explicit 3770 expiration times to responses in the belief that the entity is not 3771 likely to change, in a semantically significant way, before the 3772 expiration time is reached. This normally preserves semantic 3773 transparency, as long as the server's expiration times are carefully 3774 chosen. 3776 The expiration mechanism applies only to responses taken from a cache 3777 and not to first-hand responses forwarded immediately to the 3778 requesting client. 3780 If an origin server wishes to force a semantically transparent cache 3781 to validate every request, it MAY assign an explicit expiration time 3782 in the past. This means that the response is always stale, and so the 3783 cache SHOULD validate it before using it for subsequent requests. See 3784 section 14.9.4 for a more restrictive way to force revalidation. 3786 If an origin server wishes to force any HTTP/1.1 cache, no matter how 3787 it is configured, to validate every request, it SHOULD use the "must- 3788 revalidate" cache-control directive (see section 14.9). 3790 Servers specify explicit expiration times using either the Expires 3791 header, or the max-age directive of the Cache-Control header. 3793 An expiration time cannot be used to force a user agent to refresh 3794 its display or reload a resource; its semantics apply only to caching 3795 mechanisms, and such mechanisms need only check a resource's 3796 expiration status when a new request for that resource is initiated. 3797 See section 13.13 for an explanation of the difference between caches 3798 and history mechanisms. 3800 13.2.2 Heuristic Expiration 3802 Since origin servers do not always provide explicit expiration times, 3803 HTTP caches typically assign heuristic expiration times, employing 3804 algorithms that use other header values (such as the Last-Modified 3805 time) to estimate a plausible expiration time. The HTTP/1.1 3806 specification does not provide specific algorithms, but does impose 3807 worst-case constraints on their results. Since heuristic expiration 3808 times might compromise semantic transparency, they ought to used 3809 cautiously, and we encourage origin servers to provide explicit 3810 expiration times as much as possible. 3812 13.2.3 Age Calculations 3814 In order to know if a cached entry is fresh, a cache needs to know if 3815 its age exceeds its freshness lifetime. We discuss how to calculate 3816 the latter in section 13.2.4; this section describes how to calculate 3817 the age of a response or cache entry. 3819 In this discussion, we use the term "now" to mean "the current value 3820 of the clock at the host performing the calculation." Hosts that use 3821 HTTP, but especially hosts running origin servers and caches, SHOULD 3822 use NTP [28] or some similar protocol to synchronize their clocks to 3823 a globally accurate time standard. 3825 HTTP/1.1 requires origin servers to send a Date header, if possible, 3826 with every response, giving the time at which the response was 3827 generated (see section 14.18). We use the term "date_value" to denote 3828 the value of the Date header, in a form appropriate for arithmetic 3829 operations. 3831 HTTP/1.1 uses the Age response-header to convey the estimated age of 3832 the response message when obtained from a cache. The Age field value 3833 is the cache's estimate of the amount of time since the response was 3834 generated or revalidated by the origin server. 3836 In essence, the Age value is the sum of the time that the response 3837 has been resident in each of the caches along the path from the 3838 origin server, plus the amount of time it has been in transit along 3839 network paths. 3841 We use the term "age_value" to denote the value of the Age header, in 3842 a form appropriate for arithmetic operations. 3844 A response's age can be calculated in two entirely independent ways: 3846 1. now minus date_value, if the local clock is reasonably well 3847 synchronized to the origin server's clock. If the result is 3848 negative, the result is replaced by zero. 3850 2. age_value, if all of the caches along the response path 3851 implement HTTP/1.1. 3853 Given that we have two independent ways to compute the age of a 3854 response when it is received, we can combine these as 3856 corrected_received_age = max(now - date_value, age_value) 3858 and as long as we have either nearly synchronized clocks or all- 3859 HTTP/1.1 paths, one gets a reliable (conservative) result. 3861 Because of network-imposed delays, some significant interval might 3862 pass between the time that a server generates a response and the time 3863 it is received at the next outbound cache or client. If uncorrected, 3864 this delay could result in improperly low ages. 3866 Because the request that resulted in the returned Age value must have 3867 been initiated prior to that Age value's generation, we can correct 3868 for delays imposed by the network by recording the time at which the 3869 request was initiated. Then, when an Age value is received, it MUST 3870 be interpreted relative to the time the request was initiated, not 3871 the time that the response was received. This algorithm results in 3872 conservative behavior no matter how much delay is experienced. So, we 3873 compute: 3875 corrected_initial_age = corrected_received_age 3876 + (now - request_time) 3878 where "request_time" is the time (according to the local clock) when 3879 the request that elicited this response was sent. 3881 Summary of age calculation algorithm, when a cache receives a 3882 response: 3884 /* 3885 * age_value 3886 * is the value of Age: header received by the cache with 3887 * this response. 3888 * date_value 3889 * is the value of the origin server's Date: header 3890 * request_time 3891 * is the (local) time when the cache made the request 3892 * that resulted in this cached response 3893 * response_time 3894 * is the (local) time when the cache received the 3895 * response 3896 * now 3897 * is the current (local) time 3898 */ 3900 apparent_age = max(0, response_time - date_value); 3901 corrected_received_age = max(apparent_age, age_value); 3902 response_delay = response_time - request_time; 3903 corrected_initial_age = corrected_received_age + response_delay; 3904 resident_time = now - response_time; 3905 current_age = corrected_initial_age + resident_time; 3907 The current_age of a cache entry is calculated by adding the amount 3908 of time (in seconds) since the cache entry was last validated by the 3909 origin server to the corrected_initial_age. When a response is 3910 generated from a cache entry, the cache MUST include a single Age 3911 header field in the response with a value equal to the cache entry's 3912 current_age. 3914 The presence of an Age header field in a response implies that a 3915 response is not first-hand. However, the converse is not true, since 3916 the lack of an Age header field in a response does not imply that the 3917 response is first-hand unless all caches along the request path are 3918 compliant with HTTP/1.1 (i.e., older HTTP caches did not implement 3919 the Age header field). 3921 13.2.4 Expiration Calculations 3923 In order to decide whether a response is fresh or stale, we need to 3924 compare its freshness lifetime to its age. The age is calculated as 3925 described in section 13.2.3; this section describes how to calculate 3926 the freshness lifetime, and to determine if a response has expired. 3927 In the discussion below, the values can be represented in any form 3928 appropriate for arithmetic operations. 3930 We use the term "expires_value" to denote the value of the Expires 3931 header. We use the term "max_age_value" to denote an appropriate 3932 value of the number of seconds carried by the "max-age" directive of 3933 the Cache-Control header in a response (see section 14.9.3). 3935 The max-age directive takes priority over Expires, so if max-age is 3936 present in a response, the calculation is simply: 3938 freshness_lifetime = max_age_value 3940 Otherwise, if Expires is present in the response, the calculation is: 3942 freshness_lifetime = expires_value - date_value 3944 Note that neither of these calculations is vulnerable to clock skew, 3945 since all of the information comes from the origin server. 3947 If none of Expires, Cache-Control: max-age, or Cache-Control: s- 3948 maxage (see section 14.9.3) appears in the response, and the response 3949 does not include other restrictions on caching, the cache MAY compute 3950 a freshness lifetime using a heuristic. The cache MUST attach Warning 3951 113 to any response whose age is more than 24 hours if such warning 3952 has not already been added. 3954 Also, if the response does have a Last-Modified time, the heuristic 3955 expiration value SHOULD be no more than some fraction of the interval 3956 since that time. A typical setting of this fraction might be 10%. 3958 The calculation to determine if a response has expired is quite 3959 simple: 3961 response_is_fresh = (freshness_lifetime > current_age) 3963 13.2.5 Disambiguating Expiration Values 3965 Because expiration values are assigned optimistically, it is possible 3966 for two caches to contain fresh values for the same resource that are 3967 different. 3969 If a client performing a retrieval receives a non-first-hand response 3970 for a request that was already fresh in its own cache, and the Date 3971 header in its existing cache entry is newer than the Date on the new 3972 response, then the client MAY ignore the response. If so, it MAY 3973 retry the request with a "Cache-Control: max-age=0" directive (see 3974 section 14.9), to force a check with the origin server. 3976 If a cache has two fresh responses for the same representation with 3977 different validators, it MUST use the one with the more recent Date 3978 header. This situation might arise because the cache is pooling 3979 responses from other caches, or because a client has asked for a 3980 reload or a revalidation of an apparently fresh cache entry. 3982 13.2.6 Disambiguating Multiple Responses 3984 Because a client might be receiving responses via multiple paths, so 3985 that some responses flow through one set of caches and other 3986 responses flow through a different set of caches, a client might 3987 receive responses in an order different from that in which the origin 3988 server sent them. We would like the client to use the most recently 3989 generated response, even if older responses are still apparently 3990 fresh. 3992 Neither the entity tag nor the expiration value can impose an 3993 ordering on responses, since it is possible that a later response 3994 intentionally carries an earlier expiration time. The Date values are 3995 ordered to a granularity of one second. 3997 When a client tries to revalidate a cache entry, and the response it 3998 receives contains a Date header that appears to be older than the one 3999 for the existing entry, then the client SHOULD repeat the request 4000 unconditionally, and include 4002 Cache-Control: max-age=0 4004 to force any intermediate caches to validate their copies directly 4005 with the origin server, or 4006 Cache-Control: no-cache 4008 to force any intermediate caches to obtain a new copy from the origin 4009 server. 4011 If the Date values are equal, then the client MAY use either response 4012 (or MAY, if it is being extremely prudent, request a new response). 4013 Servers MUST NOT depend on clients being able to choose 4014 deterministically between responses generated during the same second, 4015 if their expiration times overlap. 4017 13.3 Validation Model 4019 When a cache has a stale entry that it would like to use as a 4020 response to a client's request, it first has to check with the origin 4021 server (or possibly an intermediate cache with a fresh response) to 4022 see if its cached entry is still usable. We call this "validating" 4023 the cache entry. Since we do not want to have to pay the overhead of 4024 retransmitting the full response if the cached entry is good, and we 4025 do not want to pay the overhead of an extra round trip if the cached 4026 entry is invalid, the HTTP/1.1 protocol supports the use of 4027 conditional methods. 4029 The key protocol features for supporting conditional methods are 4030 those concerned with "cache validators." When an origin server 4031 generates a full response, it attaches some sort of validator to it, 4032 which is kept with the cache entry. When a client (user agent or 4033 proxy cache) makes a conditional request for a resource for which it 4034 has a cache entry, it includes the associated validator in the 4035 request. 4037 The server then checks that validator against the current validator 4038 for the entity, and, if they match (see section 13.3.3), it responds 4039 with a special status code (usually, 304 (Not Modified)) and no 4040 entity-body. Otherwise, it returns a full response (including entity- 4041 body). Thus, we avoid transmitting the full response if the validator 4042 matches, and we avoid an extra round trip if it does not match. 4044 In HTTP/1.1, a conditional request looks exactly the same as a normal 4045 request for the same resource, except that it carries a special 4046 header (which includes the validator) that implicitly turns the 4047 method (usually, GET) into a conditional. 4049 The protocol includes both positive and negative senses of cache- 4050 validating conditions. That is, it is possible to request either that 4051 a method be performed if and only if a validator matches or if and 4052 only if no validators match. 4054 Note: a response that lacks a validator may still be cached, 4055 and served from cache until it expires, unless this is 4056 explicitly prohibited by a cache-control directive. However, a 4057 cache cannot do a conditional retrieval if it does not have a 4058 validator for the entity, which means it will not be 4059 refreshable after it expires. 4061 13.3.1 Last-Modified Dates 4063 The Last-Modified entity-header field value is often used as a cache 4064 validator. In simple terms, a cache entry is considered to be valid 4065 if the entity has not been modified since the Last-Modified value. 4067 13.3.2 Entity Tag Cache Validators 4069 The ETag response-header field value, an entity tag, provides for an 4070 "opaque" cache validator. This might allow more reliable validation 4071 in situations where it is inconvenient to store modification dates, 4072 where the one-second resolution of HTTP date values is not 4073 sufficient, or where the origin server wishes to avoid certain 4074 paradoxes that might arise from the use of modification dates. 4076 Entity Tags are described in section 3.11. The headers used with 4077 entity tags are described in sections 14.19, 14.24, 14.26 and 14.44. 4079 13.3.3 Weak and Strong Validators 4081 Since both origin servers and caches will compare two validators to 4082 decide if they represent the same or different entities, one normally 4083 would expect that if the entity (the entity-body or any entity- 4084 headers) changes in any way, then the associated validator would 4085 change as well. If this is true, then we call this validator a 4086 "strong validator." 4088 However, there might be cases when a server prefers to change the 4089 validator only on semantically significant changes, and not when 4090 insignificant aspects of the entity change. A validator that does not 4091 always change when the resource changes is a "weak validator." 4093 Entity tags are normally "strong validators," but the protocol 4094 provides a mechanism to tag an entity tag as "weak." One can think of 4095 a strong validator as one that changes whenever the bits of an entity 4096 changes, while a weak value changes whenever the meaning of an entity 4097 changes. Alternatively, one can think of a strong validator as part 4098 of an identifier for a specific entity, while a weak validator is 4099 part of an identifier for a set of semantically equivalent entities. 4101 Note: One example of a strong validator is an integer that is 4102 incremented in stable storage every time an entity is changed. 4104 An entity's modification time, if represented with one-second 4105 resolution, could be a weak validator, since it is possible 4106 that the resource might be modified twice during a single 4107 second. 4109 Support for weak validators is optional. However, weak 4110 validators allow for more efficient caching of equivalent 4111 objects; for example, a hit counter on a site is probably good 4112 enough if it is updated every few days or weeks, and any value 4113 during that period is likely "good enough" to be equivalent. 4115 A "use" of a validator is either when a client generates a request 4116 and includes the validator in a validating header field, or when a 4117 server compares two validators. 4119 Strong validators are usable in any context. Weak validators are only 4120 usable in contexts that do not depend on exact equality of an entity. 4121 For example, either kind is usable for a conditional GET of a full 4122 entity. However, only a strong validator is usable for a sub-range 4123 retrieval, since otherwise the client might end up with an internally 4124 inconsistent entity. 4126 Clients MAY issue simple (non-subrange) GET requests with either weak 4127 validators or strong validators. Clients MUST NOT use weak validators 4128 in other forms of request. 4130 The only function that the HTTP/1.1 protocol defines on validators is 4131 comparison. There are two validator comparison functions, depending 4132 on whether the comparison context allows the use of weak validators 4133 or not: 4135 . The strong comparison function: in order to be considered 4136 equal, both validators MUST be identical in every way, and both 4137 MUST NOT be weak. 4139 . The weak comparison function: in order to be considered equal, 4140 both validators MUST be identical in every way, but either or 4141 both of them MAY be tagged as "weak" without affecting the 4142 result. 4144 An entity tag is strong unless it is explicitly tagged as weak. 4145 Section 3.11 gives the syntax for entity tags. 4147 A Last-Modified time, when used as a validator in a request, is 4148 implicitly weak unless it is possible to deduce that it is strong, 4149 using the following rules: 4151 . The validator is being compared by an origin server to the 4152 actual current validator for the entity and, 4154 . That origin server reliably knows that the associated entity 4155 did not change twice during the second covered by the presented 4156 validator. 4158 or 4160 . The validator is about to be used by a client in an If- 4161 Modified-Since or If-Unmodified-Since header, because the 4162 client has a cache entry for the associated entity, and 4164 . That cache entry includes a Date value, which gives the time 4165 when the origin server sent the original response, and 4167 . The presented Last-Modified time is at least 60 seconds before 4168 the Date value. 4170 or 4172 . The validator is being compared by an intermediate cache to the 4173 validator stored in its cache entry for the entity, and 4175 . That cache entry includes a Date value, which gives the time 4176 when the origin server sent the original response, and 4178 . The presented Last-Modified time is at least 60 seconds before 4179 the Date value. 4181 This method relies on the fact that if two different responses were 4182 sent by the origin server during the same second, but both had the 4183 same Last-Modified time, then at least one of those responses would 4184 have a Date value equal to its Last-Modified time. The arbitrary 60- 4185 second limit guards against the possibility that the Date and Last- 4186 Modified values are generated from different clocks, or at somewhat 4187 different times during the preparation of the response. An 4188 implementation MAY use a value larger than 60 seconds, if it is 4189 believed that 60 seconds is too short. 4191 If a client wishes to perform a sub-range retrieval on a value for 4192 which it has only a Last-Modified time and no opaque validator, it 4193 MAY do this only if the Last-Modified time is strong in the sense 4194 described here. 4196 A cache or origin server receiving a conditional request, other than 4197 a full-body GET request, MUST use the strong comparison function to 4198 evaluate the condition. 4200 These rules allow HTTP/1.1 caches and clients to safely perform sub- 4201 range retrievals on values that have been obtained from HTTP/1.0 4202 servers. 4204 13.3.4 Rules for When to Use Entity Tags and Last-Modified Dates 4206 We adopt a set of rules and recommendations for origin servers, 4207 clients, and caches regarding when various validator types ought to 4208 be used, and for what purposes. 4210 HTTP/1.1 origin servers: 4212 . SHOULD send an entity tag validator unless it is not feasible 4213 to generate one. 4215 . MAY send a weak entity tag instead of a strong entity tag, if 4216 performance considerations support the use of weak entity tags, 4217 or if it is unfeasible to send a strong entity tag. 4219 . SHOULD send a Last-Modified value if it is feasible to send 4220 one, unless the risk of a breakdown in semantic transparency 4221 that could result from using this date in an If-Modified-Since 4222 header would lead to serious problems. 4224 In other words, the preferred behavior for an HTTP/1.1 origin server 4225 is to send both a strong entity tag and a Last-Modified value. 4227 In order to be legal, a strong entity tag MUST change whenever the 4228 associated entity value changes in any way. A weak entity tag SHOULD 4229 change whenever the associated entity changes in a semantically 4230 significant way. 4232 Note: in order to provide semantically transparent caching, an 4233 origin server must avoid reusing a specific strong entity tag 4234 value for two different entities, or reusing a specific weak 4235 entity tag value for two semantically different entities. Cache 4236 entries might persist for arbitrarily long periods, regardless 4237 of expiration times, so it might be inappropriate to expect 4238 that a cache will never again attempt to validate an entry 4239 using a validator that it obtained at some point in the past. 4241 HTTP/1.1 clients: 4243 . If an entity tag has been provided by the origin server, MUST 4244 use that entity tag in any cache-conditional request (using If- 4245 Match or If-None-Match). 4247 . If only a Last-Modified value has been provided by the origin 4248 server, SHOULD use that value in non-subrange cache-conditional 4249 requests (using If-Modified-Since). 4251 . If only a Last-Modified value has been provided by an HTTP/1.0 4252 origin server, MAY use that value in subrange cache-conditional 4253 requests (using If-Unmodified-Since:). The user agent SHOULD 4254 provide a way to disable this, in case of difficulty. 4256 . If both an entity tag and a Last-Modified value have been 4257 provided by the origin server, SHOULD use both validators in 4258 cache-conditional requests. This allows both HTTP/1.0 and 4259 HTTP/1.1 caches to respond appropriately. 4261 An HTTP/1.1 origin server, upon receiving a conditional request that 4262 includes both a Last-Modified date (e.g., in an If-Modified-Since or 4263 If-Unmodified-Since header field) and one or more entity tags (e.g., 4264 in an If-Match, If-None-Match, or If-Range header field) as cache 4265 validators, MUST NOT return a response status of 304 (Not Modified) 4266 unless doing so is consistent with all of the conditional header 4267 fields in the request. 4269 An HTTP/1.1 caching proxy, upon receiving a conditional request that 4270 includes both a Last-Modified date and one or more entity tags as 4271 cache validators, MUST NOT return a locally cached response to the 4272 client unless that cached response is consistent with all of the 4273 conditional header fields in the request. 4275 Note: The general principle behind these rules is that HTTP/1.1 4276 servers and clients should transmit as much non-redundant 4277 information as is available in their responses and requests. 4278 HTTP/1.1 systems receiving this information will make the most 4279 conservative assumptions about the validators they receive. 4281 HTTP/1.0 clients and caches will ignore entity tags. Generally, 4282 last-modified values received or used by these systems will 4283 support transparent and efficient caching, and so HTTP/1.1 4284 origin servers should provide Last-Modified values. In those 4285 rare cases where the use of a Last-Modified value as a 4286 validator by an HTTP/1.0 system could result in a serious 4287 problem, then HTTP/1.1 origin servers should not provide one. 4289 13.3.5 Non-validating Conditionals 4291 The principle behind entity tags is that only the service author 4292 knows the semantics of a resource well enough to select an 4293 appropriate cache validation mechanism, and the specification of any 4294 validator comparison function more complex than byte-equality would 4295 open up a can of worms. Thus, comparisons of any other headers 4296 (except Last-Modified, for compatibility with HTTP/1.0) are never 4297 used for purposes of validating a cache entry. 4299 13.4 Response Cacheability 4301 Unless specifically constrained by a cache-control (section 14.9) 4302 directive, a caching system MAY always store a successful response 4303 (see section 13.8) as a cache entry, MAY return it without validation 4304 if it is fresh, and MAY return it after successful validation. If 4305 there is neither a cache validator nor an explicit expiration time 4306 associated with a response, we do not expect it to be cached, but 4307 certain caches MAY violate this expectation (for example, when little 4308 or no network connectivity is available). A client can usually detect 4309 that such a response was taken from a cache by comparing the Date 4310 header to the current time. 4312 Note: some HTTP/1.0 caches are known to violate this 4313 expectation without providing any Warning. 4315 However, in some cases it might be inappropriate for a cache to 4316 retain an entity, or to return it in response to a subsequent 4317 request. This might be because absolute semantic transparency is 4318 deemed necessary by the service author, or because of security or 4319 privacy considerations. Certain cache-control directives are 4320 therefore provided so that the server can indicate that certain 4321 resource entities, or portions thereof, are not to be cached 4322 regardless of other considerations. 4324 Note that section 14.8 normally prevents a shared cache from saving 4325 and returning a response to a previous request if that request 4326 included an Authorization header. 4328 A response received with a status code of 200, 203, 206, 300, 301 or 4329 410 MAY be stored by a cache and used in reply to a subsequent 4330 request, subject to the expiration mechanism, unless a cache-control 4331 directive prohibits caching. However, a cache that does not support 4332 the Range and Content-Range headers MUST NOT cache 206 (Partial 4333 Content) responses. 4335 A response received with any other status code (e.g. status codes 302 4336 and 307) MUST NOT be returned in a reply to a subsequent request 4337 unless there are cache-control directives or another header(s) that 4338 explicitly allow it. For example, these include the following: an 4339 Expires header (section 14.21); a "max-age", "s-maxage", "must- 4340 revalidate", "proxy-revalidate", "public" or "private" cache-control 4341 directive (section 14.9). 4343 13.5 Constructing Responses From Caches 4345 The purpose of an HTTP cache is to store information received in 4346 response to requests for use in responding to future requests. In 4347 many cases, a cache simply returns the appropriate parts of a 4348 response to the requester. However, if the cache holds a cache entry 4349 based on a previous response, it might have to combine parts of a new 4350 response with what is held in the cache entry. 4352 13.5.1 End-to-end and Hop-by-hop Headers 4354 For the purpose of defining the behavior of caches and non-caching 4355 proxies, we divide HTTP headers into two categories: 4357 . End-to-end headers, which are transmitted to the ultimate 4358 recipient of a request or response. End-to-end headers in 4359 responses MUST be stored as part of a cache entry and MUST be 4360 transmitted in any response formed from a cache entry. 4362 . Hop-by-hop headers, which are meaningful only for a single 4363 transport-level connection, and are not stored by caches or 4364 forwarded by proxies. 4366 The following HTTP/1.1 headers are hop-by-hop headers: 4368 . Connection 4370 . Keep-Alive 4372 . Proxy-Authenticate 4373 . Proxy-Authorization 4375 . Transfer-Encoding 4377 . Upgrade 4379 All other headers defined by HTTP/1.1 are end-to-end headers. 4381 Other hop-by-hop headers MUST be listed in a Connection header, 4382 (section 14.10) to be introduced into HTTP/1.1 (or later). 4384 13.5.2 Non-modifiable Headers 4386 Some features of the HTTP/1.1 protocol, such as Digest 4387 Authentication, depend on the value of certain end-to-end headers. A 4388 transparent proxy SHOULD NOT modify an end-to-end header unless the 4389 definition of that header requires or specifically allows that. 4391 A transparent proxy MUST NOT modify any of the following fields in a 4392 request or response, and it MUST NOT add any of these fields if not 4393 already present: 4395 . Content-Location 4397 . Content-MD5 4399 . ETag 4401 . Last-Modified 4403 A transparent proxy MUST NOT modify any of the following fields in a 4404 response: 4406 . Expires 4408 but it MAY add any of these fields if not already present. If an 4409 Expires header is added, it MUST be given a field-value identical to 4410 that of the Date header in that response. 4412 A proxy MUST NOT modify or add any of the following fields in a 4413 message that contains the no-transform cache-control directive, or in 4414 any request: 4416 . Content-Encoding 4418 . Content-Range 4420 . Content-Type 4422 A non-transparent proxy MAY modify or add these fields to a message 4423 that does not include no-transform, but if it does so, it MUST add a 4424 Warning 214 (Transformation applied) if one does not already appear 4425 in the message (see section 14.46). 4427 Warning: unnecessary modification of end-to-end headers might 4428 cause authentication failures if stronger authentication 4429 mechanisms are introduced in later versions of HTTP. Such 4430 authentication mechanisms MAY rely on the values of header 4431 fields not listed here. 4433 The Content-Length field of a request or response is added or deleted 4434 according to the rules in section 4.4. A transparent proxy MUST 4435 preserve the entity-length (section 7.2.2) of the entity-body, 4436 although it MAY change the transfer-length (section 4.4). 4438 13.5.3 Combining Headers 4440 When a cache makes a validating request to a server, and the server 4441 provides a 304 (Not Modified) response or a 206 (Partial Content) 4442 response, the cache then constructs a response to send to the 4443 requesting client. 4445 If the status code is 304 (Not Modified), the cache uses the entity- 4446 body stored in the cache entry as the entity-body of this outgoing 4447 response. If the status code is 206 (Partial Content) and the ETag or 4448 Last-Modified headers match exactly, the cache MAY combine the 4449 contents stored in the cache entry with the new contents received in 4450 the response and use the result as the entity-body of this outgoing 4451 response, (see 13.5.4). 4453 The end-to-end headers stored in the cache entry are used for the 4454 constructed response, except that 4456 . any stored Warning headers with warn-code 1xx (see section 4457 14.46) MUST be deleted from the cache entry and the forwarded 4458 response. 4460 . any stored Warning headers with warn-code 2xx MUST be retained 4461 in the cache entry and the forwarded response. 4463 . any end-to-end headers provided in the 304 or 206 response MUST 4464 replace the corresponding headers from the cache entry. 4466 Unless the cache decides to remove the cache entry, it MUST also 4467 replace the end-to-end headers stored with the cache entry with 4468 corresponding headers received in the incoming response, except for 4469 Warning headers as described immediately above. If a header field- 4470 name in the incoming response matches more than one header in the 4471 cache entry, all such old headers MUST be replaced. 4473 In other words, the set of end-to-end headers received in the 4474 incoming response overrides all corresponding end-to-end headers 4475 stored with the cache entry (except for stored Warning headers with 4476 warn-code 1xx, which are deleted even if not overridden). 4478 Note: this rule allows an origin server to use a 304 (Not 4479 Modified) or a 206 (Partial Content) response to update any 4480 header associated with a previous response for the same entity 4481 or sub-ranges thereof, although it might not always be 4482 meaningful or correct to do so. This rule does not allow an 4483 origin server to use a 304 (Not Modified) or a 206 (Partial 4484 Content) response to entirely delete a header that it had 4485 provided with a previous response. 4487 13.5.4 Combining Byte Ranges 4489 A response might transfer only a subrange of the bytes of an entity- 4490 body, either because the request included one or more Range 4491 specifications, or because a connection was broken prematurely. After 4492 several such transfers, a cache might have received several ranges of 4493 the same entity-body. 4495 If a cache has a stored non-empty set of subranges for an entity, and 4496 an incoming response transfers another subrange, the cache MAY 4497 combine the new subrange with the existing set if both the following 4498 conditions are met: 4500 . Both the incoming response and the cache entry have a cache 4501 validator. 4503 . The two cache validators match using the strong comparison 4504 function (see section 13.3.3). 4506 If either requirement is not met, the cache MUST use only the most 4507 recent partial response (based on the Date values transmitted with 4508 every response, and using the incoming response if these values are 4509 equal or missing), and MUST discard the other partial information. 4511 13.6 Caching Negotiated Responses 4513 Use of server-driven content negotiation (section 12.1), as indicated 4514 by the presence of a Vary header field in a response, alters the 4515 conditions and procedure by which a cache can use the response for 4516 subsequent requests. See section 14.44 for use of the Vary header 4517 field by servers. 4519 A server SHOULD use the Vary header field to inform a cache of what 4520 request-header fields were used to select among multiple 4521 representations of a cacheable response subject to server-driven 4522 negotiation. The set of header fields named by the Vary field value 4523 is known as the "selecting" request-headers. 4525 When the cache receives a subsequent request whose Request-URI 4526 specifies one or more cache entries including a Vary header field, 4527 the cache MUST NOT use such a cache entry to construct a response to 4528 the new request unless all of the selecting request-headers present 4529 in the new request match the corresponding stored request-headers in 4530 the original request. 4532 The selecting request-headers from two requests are defined to match 4533 if and only if the selecting request-headers in the first request can 4534 be transformed to the selecting request-headers in the second request 4535 by adding or removing linear white space (LWS) at places where this 4536 is allowed by the corresponding BNF, and/or combining multiple 4537 message-header fields with the same field name following the rules 4538 about message headers in section 4.2. 4540 A Vary header field-value of "*" always fails to match and subsequent 4541 requests on that resource can only be properly interpreted by the 4542 origin server. 4544 If the selecting request header fields for the cached entry do not 4545 match the selecting request header fields of the new request, then 4546 the cache MUST NOT use a cached entry to satisfy the request unless 4547 it first relays the new request to the origin server in a conditional 4548 request and the server responds with 304 (Not Modified), including an 4549 entity tag or Content-Location that indicates the entity to be used. 4551 If an entity tag was assigned to a cached representation, the 4552 forwarded request SHOULD be conditional and include the entity tags 4553 in an If-None-Match header field from all its cache entries for the 4554 resource. This conveys to the server the set of entities currently 4555 held by the cache, so that if any one of these entities matches the 4556 requested entity, the server can use the ETag header field in its 304 4557 (Not Modified) response to tell the cache which entry is appropriate. 4558 If the entity-tag of the new response matches that of an existing 4559 entry, the new response SHOULD be used to update the header fields of 4560 the existing entry, and the result MUST be returned to the client. 4562 If any of the existing cache entries contains only partial content 4563 for the associated entity, its entity-tag SHOULD NOT be included in 4564 the If-None-Match header field unless the request is for a range that 4565 would be fully satisfied by that entry. 4567 If a cache receives a successful response whose Content-Location 4568 field matches that of an existing cache entry for the same Request- 4569 URI, whose entity-tag differs from that of the existing entry, and 4570 whose Date is more recent than that of the existing entry, the 4571 existing entry SHOULD NOT be returned in response to future requests 4572 and SHOULD be deleted from the cache. 4574 13.7 Shared and Non-Shared Caches 4576 For reasons of security and privacy, it is necessary to make a 4577 distinction between "shared" and "non-shared" caches. A non-shared 4578 cache is one that is accessible only to a single user. Accessibility 4579 in this case SHOULD be enforced by appropriate security mechanisms. 4580 All other caches are considered to be "shared." Other sections of 4581 this specification place certain constraints on the operation of 4582 shared caches in order to prevent loss of privacy or failure of 4583 access controls. 4585 13.8 Errors or Incomplete Response Cache Behavior 4587 A cache that receives an incomplete response (for example, with fewer 4588 bytes of data than specified in a Content-Length header) MAY store 4589 the response. However, the cache MUST treat this as a partial 4590 response. Partial responses MAY be combined as described in section 4591 13.5.4; the result might be a full response or might still be 4592 partial. A cache MUST NOT return a partial response to a client 4593 without explicitly marking it as such, using the 206 (Partial 4594 Content) status code. A cache MUST NOT return a partial response 4595 using a status code of 200 (OK). 4597 If a cache receives a 5xx response while attempting to revalidate an 4598 entry, it MAY either forward this response to the requesting client, 4599 or act as if the server failed to respond. In the latter case, it MAY 4600 return a previously received response unless the cached entry 4601 includes the "must-revalidate" cache-control directive (see section 4602 14.9). 4604 13.9 Side Effects of GET and HEAD 4606 Unless the origin server explicitly prohibits the caching of their 4607 responses, the application of GET and HEAD methods to any resources 4608 SHOULD NOT have side effects that would lead to erroneous behavior if 4609 these responses are taken from a cache. They MAY still have side 4610 effects, but a cache is not required to consider such side effects in 4611 its caching decisions. Caches are always expected to observe an 4612 origin server's explicit restrictions on caching. 4614 We note one exception to this rule: since some applications have 4615 traditionally used GETs and HEADs with query URLs (those containing a 4616 "?" in the rel_path part) to perform operations with significant side 4617 effects, caches MUST NOT treat responses to such URIs as fresh unless 4618 the server provides an explicit expiration time. This specifically 4619 means that responses from HTTP/1.0 servers for such URIs SHOULD NOT 4620 be taken from a cache. See section 9.1.1 for related information. 4622 13.10 Invalidation After Updates or Deletions 4624 The effect of certain methods performed on a resource at the origin 4625 server might cause one or more existing cache entries to become non- 4626 transparently invalid. That is, although they might continue to be 4627 "fresh," they do not accurately reflect what the origin server would 4628 return for a new request on that resource. 4630 There is no way for the HTTP protocol to guarantee that all such 4631 cache entries are marked invalid. For example, the request that 4632 caused the change at the origin server might not have gone through 4633 the proxy where a cache entry is stored. However, several rules help 4634 reduce the likelihood of erroneous behavior. 4636 In this section, the phrase "invalidate an entity" means that the 4637 cache will either remove all instances of that entity from its 4638 storage, or will mark these as "invalid" and in need of a mandatory 4639 revalidation before they can be returned in response to a subsequent 4640 request. 4642 Some HTTP methods MUST cause a cache to invalidate an entity. This is 4643 either the entity referred to by the Request-URI, or by the Location 4644 or Content-Location headers (if present). These methods are: 4646 . PUT 4648 . DELETE 4650 . POST 4652 In order to prevent denial of service attacks, an invalidation based 4653 on the URI in a Location or Content-Location header MUST only be 4654 performed if the host part is the same as in the Request-URI. 4656 A cache that passes through requests for methods it does not 4657 understand SHOULD invalidate any entities referred to by the Request- 4658 URI. 4660 13.11 Write-Through Mandatory 4662 All methods that might be expected to cause modifications to the 4663 origin server's resources MUST be written through to the origin 4664 server. This currently includes all methods except for GET and HEAD. 4665 A cache MUST NOT reply to such a request from a client before having 4666 transmitted the request to the inbound server, and having received a 4667 corresponding response from the inbound server. This does not prevent 4668 a proxy cache from sending a 100 (Continue) response before the 4669 inbound server has sent its final reply. 4671 The alternative (known as "write-back" or "copy-back" caching) is not 4672 allowed in HTTP/1.1, due to the difficulty of providing consistent 4673 updates and the problems arising from server, cache, or network 4674 failure prior to write-back. 4676 13.12 Cache Replacement 4678 If a new cacheable (see sections 14.9.2, 13.2.5, 13.2.6 and 13.8) 4679 response is received from a resource while any existing responses for 4680 the same resource are cached, the cache SHOULD use the new response 4681 to reply to the current request. It MAY insert it into cache storage 4682 and MAY, if it meets all other requirements, use it to respond to any 4683 future requests that would previously have caused the old response to 4684 be returned. If it inserts the new response into cache storage the 4685 rules in section 13.5.3 apply. 4687 Note: a new response that has an older Date header value than 4688 existing cached responses is not cacheable. 4690 13.13 History Lists 4692 User agents often have history mechanisms, such as "Back" buttons and 4693 history lists, which can be used to redisplay an entity retrieved 4694 earlier in a session. 4696 History mechanisms and caches are different. In particular history 4697 mechanisms SHOULD NOT try to show a semantically transparent view of 4698 the current state of a resource. Rather, a history mechanism is meant 4699 to show exactly what the user saw at the time when the resource was 4700 retrieved. 4702 By default, an expiration time does not apply to history mechanisms. 4703 If the entity is still in storage, a history mechanism SHOULD display 4704 it even if the entity has expired, unless the user has specifically 4705 configured the agent to refresh expired history documents. 4707 This is not to be construed to prohibit the history mechanism from 4708 telling the user that a view might be stale. 4710 Note: if history list mechanisms unnecessarily prevent users 4711 from viewing stale resources, this will tend to force service 4712 authors to avoid using HTTP expiration controls and cache 4713 controls when they would otherwise like to. Service authors may 4714 consider it important that users not be presented with error 4715 messages or warning messages when they use navigation controls 4716 (such as BACK) to view previously fetched resources. Even 4717 though sometimes such resources ought not to cached, or ought 4718 to expire quickly, user interface considerations may force 4719 service authors to resort to other means of preventing caching 4720 (e.g. "once-only" URLs) in order not to suffer the effects of 4721 improperly functioning history mechanisms. 4723 14 Header Field Definitions 4725 This section defines the syntax and semantics of all standard 4726 HTTP/1.1 header fields. For entity-header fields, both sender and 4727 recipient refer to either the client or the server, depending on who 4728 sends and who receives the entity. 4730 14.1 Accept 4732 The Accept request-header field can be used to specify certain media 4733 types which are acceptable for the response. Accept headers can be 4734 used to indicate that the request is specifically limited to a small 4735 set of desired types, as in the case of a request for an in-line 4736 image. 4738 Accept = "Accept" ":" 4739 #( media-range [ accept-params ] ) 4741 media-range = ( "*/*" 4742 | ( type "/" "*" ) 4743 | ( type "/" subtype ) 4744 ) *( ";" parameter ) 4745 accept-params = ";" "q" "=" qvalue *( accept-extension ) 4746 accept-extension = ";" token [ "=" ( token | quoted-string ) ] 4748 The asterisk "*" character is used to group media types into ranges, 4749 with "*/*" indicating all media types and "type/*" indicating all 4750 subtypes of that type. The media-range MAY include media type 4751 parameters that are applicable to that range. 4753 Each media-range MAY be followed by one or more accept-params, 4754 beginning with the "q" parameter for indicating a relative quality 4755 factor. The first "q" parameter (if any) separates the media-range 4756 parameter(s) from the accept-params. Quality factors allow the user 4757 or user agent to indicate the relative degree of preference for that 4758 media-range, using the qvalue scale from 0 to 1 (section 3.9). The 4759 default value is q=1. 4761 Note: Use of the "q" parameter name to separate media type 4762 parameters from Accept extension parameters is due to 4763 historical practice. Although this prevents any media type 4764 parameter named "q" from being used with a media range, such an 4765 event is believed to be unlikely given the lack of any "q" 4766 parameters in the IANA media type registry and the rare usage 4767 of any media type parameters in Accept. Future media types are 4768 discouraged from registering any parameter named "q". 4770 The example 4772 Accept: audio/*; q=0.2, audio/basic 4774 SHOULD be interpreted as "I prefer audio/basic, but send me any audio 4775 type if it is the best available after an 80% mark-down in quality." 4777 If no Accept header field is present, then it is assumed that the 4778 client accepts all media types. If an Accept header field is present, 4779 and if the server cannot send a response which is acceptable 4780 according to the combined Accept field value, then the server SHOULD 4781 send a 406 (not acceptable) response. 4783 A more elaborate example is 4785 Accept: text/plain; q=0.5, text/html, 4786 text/x-dvi; q=0.8, text/x-c 4788 Verbally, this would be interpreted as "text/html and text/x-c are 4789 the preferred media types, but if they do not exist, then send the 4790 text/x-dvi entity, and if that does not exist, send the text/plain 4791 entity." 4793 Media ranges can be overridden by more specific media ranges or 4794 specific media types. If more than one media range applies to a given 4795 type, the most specific reference has precedence. For example, 4796 Accept: text/*, text/html, text/html;level=1, */* 4798 have the following precedence: 4800 1) text/html;level=1 4801 2) text/html 4802 3) text/* 4803 4) */* 4805 The media type quality factor associated with a given type is 4806 determined by finding the media range with the highest precedence 4807 which matches that type. For example, 4809 Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1, 4810 text/html;level=2;q=0.4, */*;q=0.5 4812 would cause the following values to be associated: 4814 text/html;level=1 = 1 4815 text/html = 0.7 4816 text/plain = 0.3 4817 image/jpeg = 0.5 4818 text/html;level=2 = 0.4 4819 text/html;level=3 = 0.7 4821 Note: A user agent might be provided with a default set of 4822 quality values for certain media ranges. However, unless the 4823 user agent is a closed system which cannot interact with other 4824 rendering agents, this default set ought to be configurable by 4825 the user. 4827 14.2 Accept-Charset 4829 The Accept-Charset request-header field can be used to indicate what 4830 character sets are acceptable for the response. This field allows 4831 clients capable of understanding more comprehensive or special- 4832 purpose character sets to signal that capability to a server which is 4833 capable of representing documents in those character sets. 4835 Accept-Charset = "Accept-Charset" ":" 4836 1#( ( charset | "*" )[ ";" "q" "=" qvalue ] ) 4838 Character set values are described in section 3.4. Each charset MAY 4839 be given an associated quality value which represents the user's 4840 preference for that charset. The default value is q=1. An example is 4842 Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 4844 The special value "*", if present in the Accept-Charset field, 4845 matches every character set (including ISO-8859-1) which is not 4846 mentioned elsewhere in the Accept-Charset field. If no "*" is present 4847 in an Accept-Charset field, then all character sets not explicitly 4848 mentioned get a quality value of 0, except for ISO-8859-1, which gets 4849 a quality value of 1 if not explicitly mentioned. 4851 If no Accept-Charset header is present, the default is that any 4852 character set is acceptable. If an Accept-Charset header is present, 4853 and if the server cannot send a response which is acceptable 4854 according to the Accept-Charset header, then the server SHOULD send 4855 an error response with the 406 (not acceptable) status code, though 4856 the sending of an unacceptable response is also allowed. 4858 14.3 Accept-Encoding 4860 The Accept-Encoding request-header field is similar to Accept, but 4861 restricts the content-codings (section 3.5) that are acceptable in 4862 the response. 4864 Accept-Encoding = "Accept-Encoding" ":" 4865 1#( codings [ ";" "q" "=" qvalue ] ) 4866 codings = ( content-coding | "*" ) 4868 Examples of its use are: 4870 Accept-Encoding: compress, gzip 4871 Accept-Encoding: 4872 Accept-Encoding: * 4873 Accept-Encoding: compress;q=0.5, gzip;q=1.0 4874 Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 4876 A server tests whether a content-coding is acceptable, according to 4877 an Accept-Encoding field, using these rules: 4879 1. If the content-coding is one of the content-codings listed in 4880 the Accept-Encoding field, then it is acceptable, unless it is 4881 accompanied by a qvalue of 0. (As defined in section 3.9, a qvalue 4882 of 0 means "not acceptable.") 4884 2. The special "*" symbol in an Accept-Encoding field matches any 4885 available content-coding not explicitly listed in the header field. 4887 3. If multiple content-codings are acceptable, then the acceptable 4888 content-coding with the highest non-zero qvalue is preferred. 4890 4. The "identity" content-coding is always acceptable, unless 4891 specifically refused because the Accept-Encoding field includes 4892 "identity;q=0", or because the field includes "*;q=0" and does not 4893 explicitly include the "identity" content-coding. If the Accept- 4894 Encoding field-value is empty, then only the "identity" encoding is 4895 acceptable. 4897 If an Accept-Encoding field is present in a request, and if the 4898 server cannot send a response which is acceptable according to the 4899 Accept-Encoding header, then the server SHOULD send an error response 4900 with the 406 (Not Acceptable) status code. 4902 If no Accept-Encoding field is present in a request, the server MAY 4903 assume that the client will accept any content coding. In this case, 4904 if "identity" is one of the available content-codings, then the 4905 server SHOULD use the "identity" content-coding, unless it has 4906 additional information that a different content-coding is meaningful 4907 to the client. 4909 Note: If the request does not include an Accept-Encoding field, 4910 and if the "identity" content-coding is unavailable, then 4911 content-codings commonly understood by HTTP/1.0 clients (i.e., 4912 "gzip" and "compress") are preferred; some older clients 4913 improperly display messages sent with other content-codings. 4914 The server might also make this decision based on information 4915 about the particular user-agent or client. 4917 Note: Most HTTP/1.0 applications do not recognize or obey 4918 qvalues associated with content-codings. This means that 4919 qvalues will not work and are not permitted with x-gzip or x- 4920 compress. 4922 14.4 Accept-Language 4924 The Accept-Language request-header field is similar to Accept, but 4925 restricts the set of natural languages that are preferred as a 4926 response to the request. Language tags are defined in section 3.10. 4928 Accept-Language = "Accept-Language" ":" 4929 1#( language-range [ ";" "q" "=" qvalue ] ) 4930 language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" ) 4932 Each language-range MAY be given an associated quality value which 4933 represents an estimate of the user's preference for the languages 4934 specified by that range. The quality value defaults to "q=1". For 4935 example, 4937 Accept-Language: da, en-gb;q=0.8, en;q=0.7 4939 would mean: "I prefer Danish, but will accept British English and 4940 other types of English." A language-range matches a language-tag if 4941 it exactly equals the tag, or if it exactly equals a prefix of the 4942 tag such that the first tag character following the prefix is "-". 4943 The special range "*", if present in the Accept-Language field, 4944 matches every tag not matched by any other range present in the 4945 Accept-Language field. 4947 Note: This use of a prefix matching rule does not imply that 4948 language tags are assigned to languages in such a way that it 4949 is always true that if a user understands a language with a 4950 certain tag, then this user will also understand all languages 4951 with tags for which this tag is a prefix. The prefix rule 4952 simply allows the use of prefix tags if this is the case. 4954 The language quality factor assigned to a language-tag by the Accept- 4955 Language field is the quality value of the longest language-range in 4956 the field that matches the language-tag. If no language-range in the 4957 field matches the tag, the language quality factor assigned is 0. If 4958 no Accept-Language header is present in the request, the server 4959 SHOULD assume that all languages are equally acceptable. If an 4960 Accept-Language header is present, then all languages which are 4961 assigned a quality factor greater than 0 are acceptable. 4963 It might be contrary to the privacy expectations of the user to send 4964 an Accept-Language header with the complete linguistic preferences of 4965 the user in every request. For a discussion of this issue, see 4966 section 15.1.4. 4968 As intelligibility is highly dependent on the individual user, it is 4969 recommended that client applications make the choice of linguistic 4970 preference available to the user. If the choice is not made 4971 available, then the Accept-Language header field MUST NOT be given in 4972 the request. 4974 Note: When making the choice of linguistic preference available 4975 to the user, we remind implementors of the fact that users are 4976 not familiar with the details of language matching as described 4977 above, and should provide appropriate guidance. As an example, 4978 users might assume that on selecting "en-gb", they will be 4979 served any kind of English document if British English is not 4980 available. A user agent might suggest in such a case to add 4981 "en" to get the best matching behavior. 4983 14.5 Accept-Ranges 4985 The Accept-Ranges response-header field allows the server to indicate 4986 its acceptance of range requests for a resource: 4988 Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges 4989 acceptable-ranges = 1#range-unit | "none" 4991 Origin servers that accept byte-range requests MAY send 4993 Accept-Ranges: bytes 4995 but are not required to do so. Clients MAY generate byte-range 4996 requests without having received this header for the resource 4997 involved. Range units are defined in section 3.12. 4999 Servers that do not accept any kind of range request for a resource 5000 MAY send 5002 Accept-Ranges: none 5004 to advise the client not to attempt a range request. 5006 14.6 Age 5008 The Age response-header field conveys the sender's estimate of the 5009 amount of time since the response (or its revalidation) was generated 5010 at the origin server. A cached response is "fresh" if its age does 5011 not exceed its freshness lifetime. Age values are calculated as 5012 specified in section 13.2.3. 5014 Age = "Age" ":" age-value 5015 age-value = delta-seconds 5017 Age values are non-negative decimal integers, representing time in 5018 seconds. 5020 If a cache receives a value larger than the largest positive integer 5021 it can represent, or if any of its age calculations overflows, it 5022 MUST transmit an Age header with a value of 2147483648 (2^31). An 5023 HTTP/1.1 server that includes a cache MUST include an Age header 5024 field in every response generated from its own cache. Caches SHOULD 5025 use an arithmetic type of at least 31 bits of range. 5027 14.7 Allow 5029 The Allow entity-header field lists the set of methods supported by 5030 the resource identified by the Request-URI. The purpose of this field 5031 is strictly to inform the recipient of valid methods associated with 5032 the resource. An Allow header field MUST be present in a 405 (Method 5033 Not Allowed) response. 5035 Allow = "Allow" ":" #Method 5037 Example of use: 5039 Allow: GET, HEAD, PUT 5041 This field cannot prevent a client from trying other methods. 5042 However, the indications given by the Allow header field value SHOULD 5043 be followed. The actual set of allowed methods is defined by the 5044 origin server at the time of each request. 5046 The Allow header field MAY be provided with a PUT request to 5047 recommend the methods to be supported by the new or modified 5048 resource. The server is not required to support these methods and 5049 SHOULD include an Allow header in the response giving the actual 5050 supported methods. 5052 A proxy MUST NOT modify the Allow header field even if it does not 5053 understand all the methods specified, since the user agent might have 5054 other means of communicating with the origin server. 5056 14.8 Authorization 5058 A user agent that wishes to authenticate itself with a server-- 5059 usually, but not necessarily, after receiving a 401 response--does so 5060 by including an Authorization request-header field with the request. 5061 The Authorization field value consists of credentials containing the 5062 authentication information of the user agent for the realm of the 5063 resource being requested. 5065 Authorization = "Authorization" ":" credentials 5067 HTTP access authentication is described in "HTTP Authentication: 5068 Basic and Digest Access Authentication" [43]. If a request is 5069 authenticated and a realm specified, the same credentials SHOULD be 5070 valid for all other requests within this realm (assuming that the 5071 authentication scheme itself does not require otherwise, such as 5072 credentials that vary according to a challenge value or using 5073 synchronized clocks). 5075 When a shared cache (see section 13.7) receives a request containing 5076 an Authorization field, it MUST NOT return the corresponding response 5077 as a reply to any other request, unless one of the following specific 5078 exceptions holds: 5080 1. If the response includes the "s-maxage" cache-control directive, 5081 the cache MAY use that response in replying to a subsequent 5082 request. But (if the specified maximum age has passed) a proxy 5083 cache MUST first revalidate it with the origin server, using the 5084 request-headers from the new request to allow the origin server 5085 to authenticate the new request. (This is the defined behavior 5086 for s-maxage.) If the response includes "s-maxage=0", the proxy 5087 MUST always revalidate it before re-using it. 5089 2. If the response includes the "must-revalidate" cache-control 5090 directive, the cache MAY use that response in replying to a 5091 subsequent request. But if the response is stale, all caches 5092 MUST first revalidate it with the origin server, using the 5093 request-headers from the new request to allow the origin server 5094 to authenticate the new request. 5096 3. If the response includes the "public" cache-control directive, 5097 it MAY be returned in reply to any subsequent request. 5099 14.9 Cache-Control 5101 The Cache-Control general-header field is used to specify directives 5102 that MUST be obeyed by all caching mechanisms along the 5103 request/response chain. The directives specify behavior intended to 5104 prevent caches from adversely interfering with the request or 5105 response. These directives typically override the default caching 5106 algorithms. Cache directives are unidirectional in that the presence 5107 of a directive in a request does not imply that the same directive is 5108 to be given in the response. 5110 Note that HTTP/1.0 caches might not implement Cache-Control and 5111 might only implement Pragma: no-cache (see section 14.32). 5113 Cache directives MUST be passed through by a proxy or gateway 5114 application, regardless of their significance to that application, 5115 since the directives might be applicable to all recipients along the 5116 request/response chain. It is not possible to specify a cache- 5117 directive for a specific cache. 5119 Cache-Control = "Cache-Control" ":" 1#cache-directive 5121 cache-directive = cache-request-directive 5122 | cache-response-directive 5124 cache-request-directive = 5125 "no-cache" ; Section 14.9.1 5126 | "no-store" ; Section 14.9.2 5127 | "max-age" "=" delta-seconds ; Section 14.9.3, 14.9.4 5128 | "max-stale" [ "=" delta-seconds ] ; Section 14.9.3 5129 | "min-fresh" "=" delta-seconds ; Section 14.9.3 5130 | "no-transform" ; Section 14.9.5 5131 | "only-if-cached" ; Section 14.9.4 5132 | cache-extension ; Section 14.9.6 5134 cache-response-directive = 5135 "public" ; Section 14.9.1 5136 | "private" [ "=" <"> 1#field-name <"> ] ; Section 14.9.1 5137 | "no-cache" [ "=" <"> 1#field-name <"> ]; Section 14.9.1 5138 | "no-store" ; Section 14.9.2 5139 | "no-transform" ; Section 14.9.5 5140 | "must-revalidate" ; Section 14.9.4 5141 | "proxy-revalidate" ; Section 14.9.4 5142 | "max-age" "=" delta-seconds ; Section 14.9.4 5143 | "s-maxage" "=" delta-seconds ; Section 14.9.3 5144 | cache-extension ; Section 14.9.6 5146 cache-extension = token [ "=" ( token | quoted-string ) ] 5148 When a directive appears without any 1#field-name parameter, the 5149 directive applies to the entire request or response. When such a 5150 directive appears with a 1#field-name parameter, it applies only to 5151 the named field or fields, and not to the rest of the request or 5152 response. This mechanism supports extensibility; implementations of 5153 future versions of the HTTP protocol might apply these directives to 5154 header fields not defined in HTTP/1.1. 5156 The cache-control directives can be broken down into these general 5157 categories: 5159 . Restrictions on what are cacheable; these may only be imposed 5160 by the origin server. 5162 . Restrictions on what may be stored by a cache; these may be 5163 imposed by either the origin server or the user agent. 5165 . Modifications of the basic expiration mechanism; these may be 5166 imposed by either the origin server or the user agent. 5168 . Controls over cache revalidation and reload; these may only be 5169 imposed by a user agent. 5171 . Control over transformation of entities. 5173 . Extensions to the caching system. 5175 14.9.1 What is Cacheable 5177 By default, a response is cacheable if the requirements of the 5178 request method, request header fields, and the response status 5179 indicate that it is cacheable. Section 13.4 summarizes these defaults 5180 for cacheability. The following Cache-Control response directives 5181 allow an origin server to override the default cacheability of a 5182 response: 5184 public 5185 Indicates that the response MAY be cached by any cache, even if it 5186 would normally be non-cacheable or cacheable only within a non- 5187 shared cache. (See also Authorization, section 14.8, for 5188 additional details.) 5190 private 5191 Indicates that all or part of the response message is intended for 5192 a single user and MUST NOT be cached by a shared cache. This 5193 allows an origin server to state that the specified parts of the 5194 response are intended for only one user and are not a valid 5195 response for requests by other users. A private (non-shared) cache 5196 MAY cache the response. 5198 Note: This usage of the word private only controls where the 5199 response may be cached, and cannot ensure the privacy of the 5200 message content. 5202 no-cache 5203 If the no-cache directive does not specify a field-name, then a 5204 cache MUST NOT use the response to satisfy a subsequent request 5205 without successful revalidation with the origin server. This 5206 allows an origin server to prevent caching even by caches that 5207 have been configured to return stale responses to client requests. 5209 If the no-cache directive does specify one or more field-names, 5210 then a cache MAY use the response to satisfy a subsequent request, 5211 subject to any other restrictions on caching. However, the 5212 specified field-name(s) MUST NOT be sent in the response to a 5213 subsequent request without successful revalidation with the origin 5214 server. This allows an origin server to prevent the re-use of 5215 certain header fields in a response, while still allowing caching 5216 of the rest of the response. 5218 Note: Most HTTP/1.0 caches will not recognize or obey this 5219 directive. 5221 14.9.2 What May be Stored by Caches 5223 no-store 5224 The purpose of the no-store directive is to prevent the 5225 inadvertent release or retention of sensitive information (for 5226 example, on backup tapes). The no-store directive applies to the 5227 entire message, and MAY be sent either in a response or in a 5228 request. If sent in a request, a cache MUST NOT store any part of 5229 either this request or any response to it. If sent in a response, 5230 a cache MUST NOT store any part of either this response or the 5231 request that elicited it. This directive applies to both non- 5232 shared and shared caches. "MUST NOT store" in this context means 5233 that the cache MUST NOT intentionally store the information in 5234 non-volatile storage, and MUST make a best-effort attempt to 5235 remove the information from volatile storage as promptly as 5236 possible after forwarding it. 5238 Even when this directive is associated with a response, users 5239 might explicitly store such a response outside of the caching 5240 system (e.g., with a "Save As" dialog). History buffers MAY store 5241 such responses as part of their normal operation. 5243 The purpose of this directive is to meet the stated requirements 5244 of certain users and service authors who are concerned about 5245 accidental releases of information via unanticipated accesses to 5246 cache data structures. While the use of this directive might 5247 improve privacy in some cases, we caution that it is NOT in any 5248 way a reliable or sufficient mechanism for ensuring privacy. In 5249 particular, malicious or compromised caches might not recognize or 5250 obey this directive, and communications networks might be 5251 vulnerable to eavesdropping. 5253 14.9.3 Modifications of the Basic Expiration Mechanism 5255 The expiration time of an entity MAY be specified by the origin 5256 server using the Expires header (see section 14.21). Alternatively, 5257 it MAY be specified using the max-age directive in a response. When 5258 the max-age cache-control directive is present in a cached response, 5259 the response is stale if its current age is greater than the age 5260 value given (in seconds) at the time of a new request for that 5261 resource. The max-age directive on a response implies that the 5262 response is cacheable (i.e., "public") unless some other, more 5263 restrictive cache directive is also present. 5265 If a response includes both an Expires header and a max-age 5266 directive, the max-age directive overrides the Expires header, even 5267 if the Expires header is more restrictive. This rule allows an origin 5268 server to provide, for a given response, a longer expiration time to 5269 an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This might be 5270 useful if certain HTTP/1.0 caches improperly calculate ages or 5271 expiration times, perhaps due to desynchronized clocks. 5273 Many HTTP/1.0 cache implementations will treat an Expires value that 5274 is less than or equal to the response Date value as being equivalent 5275 to the Cache-Control response directive "no-cache". If an HTTP/1.1 5276 cache receives such a response, and the response does not include a 5277 Cache-Control header field, it SHOULD consider the response to be 5278 non-cacheable in order to retain compatibility with HTTP/1.0 servers. 5280 Note: An origin server might wish to use a relatively new HTTP 5281 cache control feature, such as the "private" directive, on a 5282 network including older caches that do not understand that 5283 feature. The origin server will need to combine the new feature 5284 with an Expires field whose value is less than or equal to the 5285 Date value. This will prevent older caches from improperly 5286 caching the response. 5288 s-maxage 5289 If a response includes an s-maxage directive, then for a shared 5290 cache (but not for a private cache), the maximum age specified by 5291 this directive overrides the maximum age specified by either the 5292 max-age directive or the Expires header. The s-maxage directive 5293 also implies the semantics of the proxy-revalidate directive (see 5294 section 14.9.4), i.e., that the shared cache must not use the 5295 entry after it becomes stale to respond to a subsequent request 5296 without first revalidating it with the origin server. The s-maxage 5297 directive is always ignored by a private cache. 5299 Note that most older caches, not compliant with this specification, 5300 do not implement any cache-control directives. An origin server 5301 wishing to use a cache-control directive that restricts, but does not 5302 prevent, caching by an HTTP/1.1-compliant cache MAY exploit the 5303 requirement that the max-age directive overrides the Expires header, 5304 and the fact that pre-HTTP/1.1-compliant caches do not observe the 5305 max-age directive. 5307 Other directives allow a user agent to modify the basic expiration 5308 mechanism. These directives MAY be specified on a request: 5310 max-age 5311 Indicates that the client is willing to accept a response whose 5312 age is no greater than the specified time in seconds. Unless max- 5313 stale directive is also included, the client is not willing to 5314 accept a stale response. 5316 min-fresh 5317 Indicates that the client is willing to accept a response whose 5318 freshness lifetime is no less than its current age plus the 5319 specified time in seconds. That is, the client wants a response 5320 that will still be fresh for at least the specified number of 5321 seconds. 5323 max-stale 5324 Indicates that the client is willing to accept a response that has 5325 exceeded its expiration time. If max-stale is assigned a value, 5326 then the client is willing to accept a response that has exceeded 5327 its expiration time by no more than the specified number of 5328 seconds. If no value is assigned to max-stale, then the client is 5329 willing to accept a stale response of any age. 5331 If a cache returns a stale response, either because of a max-stale 5332 directive on a request, or because the cache is configured to 5333 override the expiration time of a response, the cache MUST attach a 5334 Warning header to the stale response, using Warning 110 (Response is 5335 stale). 5337 A cache MAY be configured to return stale responses without 5338 validation, but only if this does not conflict with any "MUST"-level 5339 requirements concerning cache validation (e.g., a "must-revalidate" 5340 cache-control directive). 5342 If both the new request and the cached entry include "max-age" 5343 directives, then the lesser of the two values is used for determining 5344 the freshness of the cached entry for that request. 5346 14.9.4 Cache Revalidation and Reload Controls 5348 Sometimes a user agent might want or need to insist that a cache 5349 revalidate its cache entry with the origin server (and not just with 5350 the next cache along the path to the origin server), or to reload its 5351 cache entry from the origin server. End-to-end revalidation might be 5352 necessary if either the cache or the origin server has overestimated 5353 the expiration time of the cached response. End-to-end reload may be 5354 necessary if the cache entry has become corrupted for some reason. 5356 End-to-end revalidation may be requested either when the client does 5357 not have its own local cached copy, in which case we call it 5358 "unspecified end-to-end revalidation", or when the client does have a 5359 local cached copy, in which case we call it "specific end-to-end 5360 revalidation." 5362 The client can specify these three kinds of action using Cache- 5363 Control request directives: 5365 End-to-end reload 5366 The request includes a "no-cache" cache-control directive or, for 5367 compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field 5368 names MUST NOT be included with the no-cache directive in a 5369 request. The server MUST NOT use a cached copy when responding to 5370 such a request. 5372 Specific end-to-end revalidation 5373 The request includes a "max-age=0" cache-control directive, which 5374 forces each cache along the path to the origin server to 5375 revalidate its own entry, if any, with the next cache or server. 5377 The initial request includes a cache-validating conditional with 5378 the client's current validator. 5380 Unspecified end-to-end revalidation 5381 The request includes "max-age=0" cache-control directive, which 5382 forces each cache along the path to the origin server to 5383 revalidate its own entry, if any, with the next cache or server. 5384 The initial request does not include a cache-validating 5385 conditional; the first cache along the path (if any) that holds a 5386 cache entry for this resource includes a cache-validating 5387 conditional with its current validator. 5389 max-age 5390 When an intermediate cache is forced, by means of a max-age=0 5391 directive, to revalidate its own cache entry, and the client has 5392 supplied its own validator in the request, the supplied validator 5393 might differ from the validator currently stored with the cache 5394 entry. In this case, the cache MAY use either validator in making 5395 its own request without affecting semantic transparency. 5397 However, the choice of validator might affect performance. The 5398 best approach is for the intermediate cache to use its own 5399 validator when making its request. If the server replies with 304 5400 (Not Modified), then the cache can return its now validated copy 5401 to the client with a 200 (OK) response. If the server replies with 5402 a new entity and cache validator, however, the intermediate cache 5403 can compare the returned validator with the one provided in the 5404 client's request, using the strong comparison function. If the 5405 client's validator is equal to the origin server's, then the 5406 intermediate cache simply returns 304 (Not Modified). Otherwise, 5407 it returns the new entity with a 200 (OK) response. 5409 If a request includes the no-cache directive, it SHOULD NOT 5410 include min-fresh, max-stale, or max-age. 5412 only-if-cached 5413 In some cases, such as times of extremely poor network 5414 connectivity, a client may want a cache to return only those 5415 responses that it currently has stored, and not to reload or 5416 revalidate with the origin server. To do this, the client may 5417 include the only-if-cached directive in a request. If it receives 5418 this directive, a cache SHOULD either respond using a cached entry 5419 that is consistent with the other constraints of the request, or 5420 respond with a 504 (Gateway Timeout) status. However, if a group 5421 of caches is being operated as a unified system with good internal 5422 connectivity, such a request MAY be forwarded within that group of 5423 caches. 5425 must-revalidate 5426 Because a cache MAY be configured to ignore a server's specified 5427 expiration time, and because a client request MAY include a max- 5428 stale directive (which has a similar effect), the protocol also 5429 includes a mechanism for the origin server to require revalidation 5430 of a cache entry on any subsequent use. When the must-revalidate 5431 directive is present in a response received by a cache, that cache 5432 MUST NOT use the entry after it becomes stale to respond to a 5433 subsequent request without first revalidating it with the origin 5434 server. (I.e., the cache MUST do an end-to-end revalidation every 5435 time, if, based solely on the origin server's Expires or max-age 5436 value, the cached response is stale.) 5438 The must-revalidate directive is necessary to support reliable 5439 operation for certain protocol features. In all circumstances an 5440 HTTP/1.1 cache MUST obey the must-revalidate directive; in 5441 particular, if the cache cannot reach the origin server for any 5442 reason, it MUST generate a 504 (Gateway Timeout) response. 5444 Servers SHOULD send the must-revalidate directive if and only if 5445 failure to revalidate a request on the entity could result in 5446 incorrect operation, such as a silently unexecuted financial 5447 transaction. Recipients MUST NOT take any automated action that 5448 violates this directive, and MUST NOT automatically provide an 5449 unvalidated copy of the entity if revalidation fails. 5451 Although this is not recommended, user agents operating under 5452 severe connectivity constraints MAY violate this directive but, if 5453 so, MUST explicitly warn the user that an unvalidated response has 5454 been provided. The warning MUST be provided on each unvalidated 5455 access, and SHOULD require explicit user confirmation. 5457 proxy-revalidate 5458 The proxy-revalidate directive has the same meaning as the must- 5459 revalidate directive, except that it does not apply to non-shared 5460 user agent caches. It can be used on a response to an 5461 authenticated request to permit the user's cache to store and 5462 later return the response without needing to revalidate it (since 5463 it has already been authenticated once by that user), while still 5464 requiring proxies that service many users to revalidate each time 5465 (in order to make sure that each user has been authenticated). 5466 Note that such authenticated responses also need the public cache 5467 control directive in order to allow them to be cached at all. 5469 14.9.5 No-Transform Directive 5471 no-transform 5472 Implementors of intermediate caches (proxies) have found it useful 5473 to convert the media type of certain entity bodies. A non- 5474 transparent proxy might, for example, convert between image 5475 formats in order to save cache space or to reduce the amount of 5476 traffic on a slow link. 5478 Serious operational problems occur, however, when these 5479 transformations are applied to entity bodies intended for certain 5480 kinds of applications. For example, applications for medical 5481 imaging, scientific data analysis and those using end-to-end 5482 authentication, all depend on receiving an entity body that is bit 5483 for bit identical to the original entity-body. 5485 Therefore, if a message includes the no-transform directive, an 5486 intermediate cache or proxy MUST NOT change those headers that are 5487 listed in section 13.5.2 as being subject to the no-transform 5488 directive. This implies that the cache or proxy MUST NOT change 5489 any aspect of the entity-body that is specified by these headers, 5490 including the value of the entity-body itself. 5492 14.9.6 Cache Control Extensions 5494 The Cache-Control header field can be extended through the use of one 5495 or more cache-extension tokens, each with an optional assigned value. 5496 Informational extensions (those which do not require a change in 5497 cache behavior) MAY be added without changing the semantics of other 5498 directives. Behavioral extensions are designed to work by acting as 5499 modifiers to the existing base of cache directives. Both the new 5500 directive and the standard directive are supplied, such that 5501 applications which do not understand the new directive will default 5502 to the behavior specified by the standard directive, and those that 5503 understand the new directive will recognize it as modifying the 5504 requirements associated with the standard directive. In this way, 5505 extensions to the cache-control directives can be made without 5506 requiring changes to the base protocol. 5508 This extension mechanism depends on an HTTP cache obeying all of the 5509 cache-control directives defined for its native HTTP-version, obeying 5510 certain extensions, and ignoring all directives that it does not 5511 understand. 5513 For example, consider a hypothetical new response directive called 5514 community which acts as a modifier to the private directive. We 5515 define this new directive to mean that, in addition to any non-shared 5516 cache, any cache which is shared only by members of the community 5517 named within its value may cache the response. An origin server 5518 wishing to allow the UCI community to use an otherwise private 5519 response in their shared cache(s) could do so by including 5520 Cache-Control: private, community="UCI" 5522 A cache seeing this header field will act correctly even if the cache 5523 does not understand the community cache-extension, since it will also 5524 see and understand the private directive and thus default to the safe 5525 behavior. 5527 Unrecognized cache-directives MUST be ignored; it is assumed that any 5528 cache-directive likely to be unrecognized by an HTTP/1.1 cache will 5529 be combined with standard directives (or the response's default 5530 cacheability) such that the cache behavior will remain minimally 5531 correct even if the cache does not understand the extension(s). 5533 14.10 Connection 5535 The Connection general-header field allows the sender to specify 5536 options that are desired for that particular connection and MUST NOT 5537 be communicated by proxies over further connections. 5539 The Connection header has the following grammar: 5541 Connection = "Connection" ":" 1#(connection-token) 5542 connection-token = token 5544 HTTP/1.1 proxies MUST parse the Connection header field before a 5545 message is forwarded and, for each connection-token in this field, 5546 remove any header field(s) from the message with the same name as the 5547 connection-token. Connection options are signaled by the presence of 5548 a connection-token in the Connection header field, not by any 5549 corresponding additional header field(s), since the additional header 5550 field may not be sent if there are no parameters associated with that 5551 connection option. 5553 Message headers listed in the Connection header MUST NOT include end- 5554 to-end headers, such as Cache-Control. 5556 HTTP/1.1 defines the "close" connection option for the sender to 5557 signal that the connection will be closed after completion of the 5558 response. For example, 5560 Connection: close 5562 in either the request or the response header fields indicates that 5563 the connection SHOULD NOT be considered `persistent' (section 8.1) 5564 after the current request/response is complete. 5566 HTTP/1.1 applications that do not support persistent connections MUST 5567 include the "close" connection option in every message. 5569 A system receiving an HTTP/1.0 (or lower-version) message that 5570 includes a Connection header MUST, for each connection-token in this 5571 field, remove and ignore any header field(s) from the message with 5572 the same name as the connection-token. This protects against mistaken 5573 forwarding of such header fields by pre-HTTP/1.1 proxies. See section 5574 19.6.2. 5576 14.11 Content-Encoding 5578 The Content-Encoding entity-header field is used as a modifier to the 5579 media-type. When present, its value indicates what additional content 5580 codings have been applied to the entity-body, and thus what decoding 5581 mechanisms must be applied in order to obtain the media-type 5582 referenced by the Content-Type header field. Content-Encoding is 5583 primarily used to allow a document to be compressed without losing 5584 the identity of its underlying media type. 5586 Content-Encoding = "Content-Encoding" ":" 1#content-coding 5588 Content codings are defined in section 3.5. An example of its use is 5590 Content-Encoding: gzip 5592 The content-coding is a characteristic of the entity identified by 5593 the Request-URI. Typically, the entity-body is stored with this 5594 encoding and is only decoded before rendering or analogous usage. 5595 However, a non-transparent proxy MAY modify the content-coding if the 5596 new coding is known to be acceptable to the recipient, unless the 5597 "no-transform" cache-control directive is present in the message. 5599 If the content-coding of an entity is not "identity", then the 5600 response MUST including a Content-Encoding entity-header (section 5601 14.11) that lists the non-identity content-coding(s) used. 5603 If the content-coding of an entity in a request message is not 5604 acceptable to the origin server, the server SHOULD respond with a 5605 status code of 415 (Unsupported Media Type). 5607 If multiple encodings have been applied to an entity, the content 5608 codings MUST be listed in the order in which they were applied. 5609 Additional information about the encoding parameters MAY be provided 5610 by other entity-header fields not defined by this specification. 5612 14.12 Content-Language 5614 The Content-Language entity-header field describes the natural 5615 language(s) of the intended audience for the enclosed entity. Note 5616 that this might not be equivalent to all the languages used within 5617 the entity-body. 5619 Content-Language = "Content-Language" ":" 1#language-tag 5621 Language tags are defined in section 3.10. The primary purpose of 5622 Content-Language is to allow a user to identify and differentiate 5623 entities according to the user's own preferred language. Thus, if the 5624 body content is intended only for a Danish-literate audience, the 5625 appropriate field is 5627 Content-Language: da 5629 If no Content-Language is specified, the default is that the content 5630 is intended for all language audiences. This might mean that the 5631 sender does not consider it to be specific to any natural language, 5632 or that the sender does not know for which language it is intended. 5634 Multiple languages MAY be listed for content that is intended for 5635 multiple audiences. For example, a rendition of the "Treaty of 5636 Waitangi," presented simultaneously in the original Maori and English 5637 versions, would call for 5639 Content-Language: mi, en 5641 However, just because multiple languages are present within an entity 5642 does not mean that it is intended for multiple linguistic audiences. 5643 An example would be a beginner's language primer, such as "A First 5644 Lesson in Latin," which is clearly intended to be used by an English- 5645 literate audience. In this case, the Content-Language would properly 5646 only include "en". 5648 Content-Language MAY be applied to any media type -- it is not 5649 limited to textual documents. 5651 14.13 Content-Length 5653 The Content-Length entity-header field indicates the size of the 5654 entity-body, in decimal number of OCTETs, sent to the recipient or, 5655 in the case of the HEAD method, the size of the entity-body that 5656 would have been sent had the request been a GET. 5658 Content-Length = "Content-Length" ":" 1*DIGIT 5660 An example is 5662 Content-Length: 3495 5664 Applications SHOULD use this field to indicate the transfer-length of 5665 the message-body, unless this is prohibited by the rules in section 5666 4.4. 5668 Any Content-Length greater than or equal to zero is a valid value. 5669 Section 4.4 describes how to determine the length of a message-body 5670 if a Content-Length is not given. 5672 Note that the meaning of this field is significantly different from 5673 the corresponding definition in MIME, where it is an optional field 5674 used within the "message/external-body" content-type. In HTTP, it 5675 SHOULD be sent whenever the message's length can be determined prior 5676 to being transferred, unless this is prohibited by the rules in 5677 section 4.4. 5679 14.14 Content-Location 5681 The Content-Location entity-header field MAY be used to supply the 5682 resource location for the entity enclosed in the message when that 5683 entity is accessible from a location separate from the requested 5684 resource's URI. A server SHOULD provide a Content-Location for the 5685 variant corresponding to the response entity; especially in the case 5686 where a resource has multiple entities associated with it, and those 5687 entities actually have separate locations by which they might be 5688 individually accessed, the server SHOULD provide a Content-Location 5689 for the particular variant which is returned. 5691 Content-Location = "Content-Location" ":" 5692 ( absoluteURI | relativeURI ) 5694 The value of Content-Location also defines the base URI for the 5695 entity. 5697 The Content-Location value is not a replacement for the original 5698 requested URI; it is only a statement of the location of the resource 5699 corresponding to this particular entity at the time of the request. 5700 Future requests MAY specify the Content-Location URI as the request- 5701 URI if the desire is to identify the source of that particular 5702 entity. 5704 A cache cannot assume that an entity with a Content-Location 5705 different from the URI used to retrieve it can be used to respond to 5706 later requests on that Content-Location URI. However, the Content- 5707 Location can be used to differentiate between multiple entities 5708 retrieved from a single requested resource, as described in section 5709 13.6. 5711 If the Content-Location is a relative URI, the relative URI is 5712 interpreted relative to the Request-URI. 5714 The meaning of the Content-Location header in PUT or POST requests is 5715 undefined; servers are free to ignore it in those cases. 5717 14.15 Content-MD5 5719 The Content-MD5 entity-header field, as defined in RFC 1864 [23], is 5720 an MD5 digest of the entity-body for the purpose of providing an end- 5721 to-end message integrity check (MIC) of the entity-body. (Note: a MIC 5722 is good for detecting accidental modification of the entity-body in 5723 transit, but is not proof against malicious attacks.) 5725 Content-MD5 = "Content-MD5" ":" md5-digest 5726 md5-digest = 5728 The Content-MD5 header field MAY be generated by an origin server or 5729 client to function as an integrity check of the entity-body. Only 5730 origin servers or clients MAY generate the Content-MD5 header field; 5731 proxies and gateways MUST NOT generate it, as this would defeat its 5732 value as an end-to-end integrity check. Any recipient of the entity- 5733 body, including gateways and proxies, MAY check that the digest value 5734 in this header field matches that of the entity-body as received. 5736 The MD5 digest is computed based on the content of the entity-body, 5737 including any content-coding that has been applied, but not including 5738 any transfer-encoding applied to the message-body. If the message is 5739 received with a transfer-encoding, that encoding MUST be removed 5740 prior to checking the Content-MD5 value against the received entity. 5742 This has the result that the digest is computed on the octets of the 5743 entity-body exactly as, and in the order that, they would be sent if 5744 no transfer-encoding were being applied. 5746 HTTP extends RFC 1864 to permit the digest to be computed for MIME 5747 composite media-types (e.g., multipart/* and message/rfc822), but 5748 this does not change how the digest is computed as defined in the 5749 preceding paragraph. 5751 There are several consequences of this. The entity-body for composite 5752 types MAY contain many body-parts, each with its own MIME and HTTP 5753 headers (including Content-MD5, Content-Transfer-Encoding, and 5754 Content-Encoding headers). If a body-part has a Content-Transfer- 5755 Encoding or Content-Encoding header, it is assumed that the content 5756 of the body-part has had the encoding applied, and the body-part is 5757 included in the Content-MD5 digest as is -- i.e., after the 5758 application. The Transfer-Encoding header field is not allowed within 5759 body-parts. 5761 Conversion of all line breaks to CRLF MUST NOT be done before 5762 computing or checking the digest: the line break convention used in 5763 the text actually transmitted MUST be left unaltered when computing 5764 the digest. 5766 Note: while the definition of Content-MD5 is exactly the same 5767 for HTTP as in RFC 1864 for MIME entity-bodies, there are 5768 several ways in which the application of Content-MD5 to HTTP 5769 entity-bodies differs from its application to MIME entity- 5770 bodies. One is that HTTP, unlike MIME, does not use Content- 5771 Transfer-Encoding, and does use Transfer-Encoding and Content- 5772 Encoding. Another is that HTTP more frequently uses binary 5773 content types than MIME, so it is worth noting that, in such 5774 cases, the byte order used to compute the digest is the 5775 transmission byte order defined for the type. Lastly, HTTP 5776 allows transmission of text types with any of several line 5777 break conventions and not just the canonical form using CRLF. 5779 14.16 Content-Range 5781 The Content-Range entity-header is sent with a partial entity-body to 5782 specify where in the full entity-body the partial body should be 5783 applied. Range units are defined in section 3.12. 5785 Content-Range = "Content-Range" ":" content-range-spec 5787 content-range-spec = byte-content-range-spec 5788 byte-content-range-spec = bytes-unit SP 5789 byte-range-resp-spec "/" 5790 ( instance-length | "*" ) 5792 byte-range-resp-spec = (first-byte-pos "-" last-byte-pos) 5793 | "*" 5794 instance-length = 1*DIGIT 5796 The header SHOULD indicate the total length of the full entity-body, 5797 unless this length is unknown or difficult to determine. The asterisk 5798 "*" character means that the instance-length is unknown at the time 5799 when the response was generated. 5801 Unlike byte-ranges-specifier values (see section 14.35.1), a byte- 5802 range-resp-spec MUST only specify one range, and MUST contain 5803 absolute byte positions for both the first and last byte of the 5804 range. 5806 A byte-content-range-spec with a byte-range-resp-spec whose last- 5807 byte-pos value is less than its first-byte-pos value, or whose 5808 instance-length value is less than or equal to its last-byte-pos 5809 value, is invalid. The recipient of an invalid byte-content-range- 5810 spec MUST ignore it and any content transferred along with it. 5812 A server sending a response with status code 416 (Requested range not 5813 satisfiable) SHOULD include a Content-Range field with a byte-range- 5814 resp-spec of "*". The instance-length specifies the current length of 5815 the selected resource. A response with status code 206 (Partial 5816 Content) MUST NOT include a Content-Range field with a byte-range- 5817 resp-spec of "*". 5819 Examples of byte-content-range-spec values, assuming that the entity 5820 contains a total of 1234 bytes: 5822 . The first 500 bytes: 5823 bytes 0-499/1234 5825 . The second 500 bytes: 5826 bytes 500-999/1234 5828 . All except for the first 500 bytes: 5829 bytes 500-1233/1234 5831 . The last 500 bytes: 5832 bytes 734-1233/1234 5834 When an HTTP message includes the content of a single range (for 5835 example, a response to a request for a single range, or to a request 5836 for a set of ranges that overlap without any holes), this content is 5837 transmitted with a Content-Range header, and a Content-Length header 5838 showing the number of bytes actually transferred. For example, 5840 HTTP/1.1 206 Partial content 5841 Date: Wed, 15 Nov 1995 06:25:24 GMT 5842 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 5843 Content-Range: bytes 21010-47021/47022 5844 Content-Length: 26012 5845 Content-Type: image/gif 5847 When an HTTP message includes the content of multiple ranges (for 5848 example, a response to a request for multiple non-overlapping 5849 ranges), these are transmitted as a multipart message. The multipart 5850 media type used for this purpose is "multipart/byteranges" as defined 5851 in appendix 19.2. See appendix 19.6.3 for a compatibility issue. 5853 A response to a request for a single range MUST NOT be sent using the 5854 multipart/byteranges media type. A response to a request for 5855 multiple ranges, whose result is a single range, MAY be sent as a 5856 multipart/byteranges media type with one part. A client that cannot 5857 decode a multipart/byteranges message MUST NOT ask for multiple byte- 5858 ranges in a single request. 5860 When a client requests multiple byte-ranges in one request, the 5861 server SHOULD return them in the order that they appeared in the 5862 request. 5864 If the server ignores a byte-range-spec because it is syntactically 5865 invalid, the server SHOULD treat the request as if the invalid Range 5866 header field did not exist. (Normally, this means return a 200 5867 response containing the full entity). 5869 If the server receives a request (other than one including an If- 5870 Range request-header field) with an unsatisfiable Range request- 5871 header field (that is, all of whose byte-range-spec values have a 5872 first-byte-pos value greater than the current length of the selected 5873 resource), it SHOULD return a response code of 416 (Requested range 5874 not satisfiable) (section 10.4.17). 5876 Note: clients cannot depend on servers to send a 416 (Requested 5877 range not satisfiable) response instead of a 200 (OK) response 5878 for an unsatisfiable Range request-header, since not all 5879 servers implement this request-header. 5881 14.17 Content-Type 5883 The Content-Type entity-header field indicates the media type of the 5884 entity-body sent to the recipient or, in the case of the HEAD method, 5885 the media type that would have been sent had the request been a GET. 5887 Content-Type = "Content-Type" ":" media-type 5889 Media types are defined in section 3.7. An example of the field is 5891 Content-Type: text/html; charset=ISO-8859-4 5893 Further discussion of methods for identifying the media type of an 5894 entity is provided in section 7.2.1. 5896 14.18 Date 5898 The Date general-header field represents the date and time at which 5899 the message was originated, having the same semantics as orig-date in 5900 RFC 822. The field value is an HTTP-date, as described in section 5901 3.3.1; it MUST be sent in RFC 1123 [8]-date format. 5903 Date = "Date" ":" HTTP-date 5905 An example is 5907 Date: Tue, 15 Nov 1994 08:12:31 GMT 5909 Origin servers MUST include a Date header field in all responses, 5910 except in these cases: 5912 1. If the response status code is 100 (Continue) or 101 (Switching 5913 Protocols), the response MAY include a Date header field, at the 5914 server's option. 5916 2. If the response status code conveys a server error, e.g. 500 5917 (Internal Server Error) or 503 (Service Unavailable), and it is 5918 inconvenient or impossible to generate a valid Date. 5920 3. If the server does not have a clock that can provide a 5921 reasonable approximation of the current time, its responses MUST 5922 NOT include a Date header field. In this case, the rules in 5923 section 14.18.1 MUST be followed. 5925 A received message that does not have a Date header field MUST be 5926 assigned one by the recipient if the message will be cached by that 5927 recipient or gatewayed via a protocol which requires a Date. An HTTP 5928 implementation without a clock MUST NOT cache responses without 5929 revalidating them on every use. An HTTP cache, especially a shared 5930 cache, SHOULD use a mechanism, such as NTP [28], to synchronize its 5931 clock with a reliable external standard. 5933 Clients SHOULD only send a Date header field in messages that include 5934 an entity-body, as in the case of the PUT and POST requests, and even 5935 then it is optional. A client without a clock MUST NOT send a Date 5936 header field in a request. 5938 The HTTP-date sent in a Date header SHOULD NOT represent a date and 5939 time subsequent to the generation of the message. It SHOULD represent 5940 the best available approximation of the date and time of message 5941 generation, unless the implementation has no means of generating a 5942 reasonably accurate date and time. In theory, the date ought to 5943 represent the moment just before the entity is generated. In 5944 practice, the date can be generated at any time during the message 5945 origination without affecting its semantic value. 5947 14.18.1 Clockless Origin Server Operation 5949 Some origin server implementations might not have a clock available. 5950 An origin server without a clock MUST NOT assign Expires or Last- 5951 Modified values to a response, unless these values were associated 5952 with the resource by a system or user with a reliable clock. It MAY 5953 assign an Expires value that is known, at or before server 5954 configuration time, to be in the past (this allows "pre-expiration" 5955 of responses without storing separate Expires values for each 5956 resource). 5958 14.19 ETag 5960 The ETag response-header field provides the current value of the 5961 entity tag for the requested variant. The headers used with entity 5962 tags are described in sections 14.24, 14.26 and 14.44. The entity tag 5963 MAY be used for comparison with other entities from the same resource 5964 (see section 13.3.3). 5966 ETag = "ETag" ":" entity-tag 5968 Examples: 5970 ETag: "xyzzy" 5971 ETag: W/"xyzzy" 5972 ETag: "" 5974 14.20 Expect 5976 The Expect request-header field is used to indicate that particular 5977 server behaviors are required by the client. 5979 Expect = "Expect" ":" 1#expectation 5981 expectation = "100-continue" | expectation-extension 5982 expectation-extension = token [ "=" ( token | quoted-string ) 5983 *expect-params ] 5984 expect-params = ";" token [ "=" ( token | quoted-string ) ] 5986 A server that does not understand or is unable to comply with any of 5987 the expectation values in the Expect field of a request MUST respond 5988 with appropriate error status. The server MUST respond with a 417 5989 (Expectation Failed) status if any of the expectations cannot be met 5990 or, if there are other problems with the request, some other 4xx 5991 status. 5993 This header field is defined with extensible syntax to allow for 5994 future extensions. If a server receives a request containing an 5995 Expect field that includes an expectation-extension that it does not 5996 support, it MUST respond with a 417 (Expectation Failed) status. 5998 Comparison of expectation values is case-insensitive for unquoted 5999 tokens (including the 100-continue token), and is case-sensitive for 6000 quoted-string expectation-extensions. 6002 The Expect mechanism is hop-by-hop: that is, an HTTP/1.1 proxy MUST 6003 return a 417 (Expectation Failed) status if it receives a request 6004 with an expectation that it cannot meet. However, the Expect request- 6005 header itself is end-to-end; it MUST be forwarded if the request is 6006 forwarded. 6008 Many older HTTP/1.0 and HTTP/1.1 applications do not understand the 6009 Expect header. 6011 See section 8.2.3 for the use of the 100 (continue) status. 6013 14.21 Expires 6015 The Expires entity-header field gives the date/time after which the 6016 response is considered stale. A stale cache entry may not normally be 6017 returned by a cache (either a proxy cache or a user agent cache) 6018 unless it is first validated with the origin server (or with an 6019 intermediate cache that has a fresh copy of the entity). See section 6020 13.2 for further discussion of the expiration model. 6022 The presence of an Expires field does not imply that the original 6023 resource will change or cease to exist at, before, or after that 6024 time. 6026 The format is an absolute date and time as defined by HTTP-date in 6027 section 3.3.1; it MUST be in RFC 1123 date format: 6029 Expires = "Expires" ":" HTTP-date 6031 An example of its use is 6033 Expires: Thu, 01 Dec 1994 16:00:00 GMT 6035 Note: if a response includes a Cache-Control field with the 6036 max-age directive (see section 14.9.3), that directive 6037 overrides the Expires field. 6039 HTTP/1.1 clients and caches MUST treat other invalid date formats, 6040 especially including the value "0", as in the past (i.e., "already 6041 expired"). 6043 To mark a response as "already expired," an origin server sends an 6044 Expires date that is equal to the Date header value. (See the rules 6045 for expiration calculations in section 13.2.4.) 6047 To mark a response as "never expires," an origin server sends an 6048 Expires date approximately one year from the time the response is 6049 sent. HTTP/1.1 servers SHOULD NOT send Expires dates more than one 6050 year in the future. 6052 The presence of an Expires header field with a date value of some 6053 time in the future on a response that otherwise would by default be 6054 non-cacheable indicates that the response is cacheable, unless 6055 indicated otherwise by a Cache-Control header field (section 14.9). 6057 14.22 From 6059 The From request-header field, if given, SHOULD contain an Internet 6060 e-mail address for the human user who controls the requesting user 6061 agent. The address SHOULD be machine-usable, as defined by "mailbox" 6062 in RFC 822 [9] as updated by RFC 1123 [8]: 6064 From = "From" ":" mailbox 6066 An example is: 6068 From: webmaster@w3.org 6070 This header field MAY be used for logging purposes and as a means for 6071 identifying the source of invalid or unwanted requests. It SHOULD NOT 6072 be used as an insecure form of access protection. The interpretation 6073 of this field is that the request is being performed on behalf of the 6074 person given, who accepts responsibility for the method performed. In 6075 particular, robot agents SHOULD include this header so that the 6076 person responsible for running the robot can be contacted if problems 6077 occur on the receiving end. 6079 The Internet e-mail address in this field MAY be separate from the 6080 Internet host which issued the request. For example, when a request 6081 is passed through a proxy the original issuer's address SHOULD be 6082 used. 6084 The client SHOULD NOT send the From header field without the user's 6085 approval, as it might conflict with the user's privacy interests or 6086 their site's security policy. It is strongly recommended that the 6087 user be able to disable, enable, and modify the value of this field 6088 at any time prior to a request. 6090 14.23 Host 6092 The Host request-header field specifies the Internet host and port 6093 number of the resource being requested, as obtained from the original 6094 URI given by the user or referring resource (generally an HTTP URL, 6095 as described in section 3.2.2). The Host field value MUST represent 6096 the naming authority of the origin server or gateway given by the 6097 original URL. This allows the origin server or gateway to 6098 differentiate between internally-ambiguous URLs, such as the root "/" 6099 URL of a server for multiple host names on a single IP address. 6101 Host = "Host" ":" host [ ":" port ] ; Section 3.2.2 6103 A "host" without any trailing port information implies the default 6104 port for the service requested (e.g., "80" for an HTTP URL). For 6105 example, a request on the origin server for 6106 would properly include: 6108 GET /pub/WWW/ HTTP/1.1 6109 Host: www.w3.org 6111 A client MUST include a Host header field in all HTTP/1.1 request 6112 messages . If the requested URI does not include an Internet host 6113 name for the service being requested, then the Host header field MUST 6114 be given with an empty value. An HTTP/1.1 proxy MUST ensure that any 6115 request message it forwards does contain an appropriate Host header 6116 field that identifies the service being requested by the proxy. All 6117 Internet-based HTTP/1.1 servers MUST respond with a 400 (Bad Request) 6118 status code to any HTTP/1.1 request message which lacks a Host header 6119 field. 6121 See sections 5.2 and 19.6.1.1 for other requirements relating to 6122 Host. 6124 14.24 If-Match 6126 The If-Match request-header field is used with a method to make it 6127 conditional. A client that has one or more entities previously 6128 obtained from the resource can verify that one of those entities is 6129 current by including a list of their associated entity tags in the 6130 If-Match header field. Entity tags are defined in section 3.11. The 6131 purpose of this feature is to allow efficient updates of cached 6132 information with a minimum amount of transaction overhead. It is also 6133 used, on updating requests, to prevent inadvertent modification of 6134 the wrong version of a resource. As a special case, the value "*" 6135 matches any current entity of the resource. 6137 If-Match = "If-Match" ":" ( "*" | 1#entity-tag ) 6139 If any of the entity tags match the entity tag of the entity that 6140 would have been returned in the response to a similar GET request 6141 (without the If-Match header) on that resource, or if "*" is given 6142 and any current entity exists for that resource, then the server MAY 6143 perform the requested method as if the If-Match header field did not 6144 exist. 6146 A server MUST use the strong comparison function (see section 13.3.3) 6147 to compare the entity tags in If-Match. 6149 If none of the entity tags match, or if "*" is given and no current 6150 entity exists, the server MUST NOT perform the requested method, and 6151 MUST return a 412 (Precondition Failed) response. This behavior is 6152 most useful when the client wants to prevent an updating method, such 6153 as PUT, from modifying a resource that has changed since the client 6154 last retrieved it. 6156 If the request would, without the If-Match header field, result in 6157 anything other than a 2xx or 412 status, then the If-Match header 6158 MUST be ignored. 6160 The meaning of "If-Match: *" is that the method SHOULD be performed 6161 if the representation selected by the origin server (or by a cache, 6162 possibly using the Vary mechanism, see section 14.44) exists, and 6163 MUST NOT be performed if the representation does not exist. 6165 A request intended to update a resource (e.g., a PUT) MAY include an 6166 If-Match header field to signal that the request method MUST NOT be 6167 applied if the entity corresponding to the If-Match value (a single 6168 entity tag) is no longer a representation of that resource. This 6169 allows the user to indicate that they do not wish the request to be 6170 successful if the resource has been changed without their knowledge. 6171 Examples: 6173 If-Match: "xyzzy" 6174 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 6175 If-Match: * 6177 The result of a request having both an If-Match header field and 6178 either an If-None-Match or an If-Modified-Since header fields is 6179 undefined by this specification. 6181 14.25 If-Modified-Since 6183 The If-Modified-Since request-header field is used with a method to 6184 make it conditional: if the requested variant has not been modified 6185 since the time specified in this field, an entity will not be 6186 returned from the server; instead, a 304 (not modified) response will 6187 be returned without any message-body. 6189 If-Modified-Since = "If-Modified-Since" ":" HTTP-date 6191 An example of the field is: 6193 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 6195 A GET method with an If-Modified-Since header and no Range header 6196 requests that the identified entity be transferred only if it has 6197 been modified since the date given by the If-Modified-Since header. 6198 The algorithm for determining this includes the following cases: 6200 a) If the request would normally result in anything other than a 6201 200 (OK) status, or if the passed If-Modified-Since date is 6202 invalid, the response is exactly the same as for a normal GET. A 6203 date which is later than the server's current time is invalid. 6205 b) If the variant has been modified since the If-Modified-Since 6206 date, the response is exactly the same as for a normal GET. 6208 c) If the variant has not been modified since a valid If-Modified- 6209 Since date, the server SHOULD return a 304 (Not Modified) 6210 response. 6212 The purpose of this feature is to allow efficient updates of cached 6213 information with a minimum amount of transaction overhead. 6215 Note: The Range request-header field modifies the meaning of 6216 If-Modified-Since; see section 14.35 for full details. 6218 Note: If-Modified-Since times are interpreted by the server, 6219 whose clock might not be synchronized with the client. 6221 Note: When handling an If-Modified-Since header field, some 6222 servers will use an exact date comparison function, rather than 6223 a less-than function, for deciding whether to send a 304 (Not 6224 Modified) response. To get best results when sending an If- 6225 Modified-Since header field for cache validation, clients are 6226 advised to use the exact date string received in a previous 6227 Last-Modified header field whenever possible. 6229 Note: If a client uses an arbitrary date in the If-Modified- 6230 Since header instead of a date taken from the Last-Modified 6231 header for the same request, the client should be aware of the 6232 fact that this date is interpreted in the server's 6233 understanding of time. The client should consider 6234 unsynchronized clocks and rounding problems due to the 6235 different encodings of time between the client and server. This 6236 includes the possibility of race conditions if the document has 6237 changed between the time it was first requested and the If- 6238 Modified-Since date of a subsequent request, and the 6239 possibility of clock-skew-related problems if the If-Modified- 6240 Since date is derived from the client's clock without 6241 correction to the server's clock. Corrections for different 6242 time bases between client and server are at best approximate 6243 due to network latency. 6245 The result of a request having both an If-Modified-Since header field 6246 and either an If-Match or an If-Unmodified-Since header fields is 6247 undefined by this specification. 6249 14.26 If-None-Match 6251 The If-None-Match request-header field is used with a method to make 6252 it conditional. A client that has one or more entities previously 6253 obtained from the resource can verify that none of those entities is 6254 current by including a list of their associated entity tags in the 6255 If-None-Match header field. The purpose of this feature is to allow 6256 efficient updates of cached information with a minimum amount of 6257 transaction overhead. It is also used to prevent a method (e.g. PUT) 6258 from inadvertently modifying an existing resource when the client 6259 believes that the resource does not exist. 6261 As a special case, the value "*" matches any current entity of the 6262 resource. 6264 If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag ) 6266 If any of the entity tags match the entity tag of the entity that 6267 would have been returned in the response to a similar GET request 6268 (without the If-None-Match header) on that resource, or if "*" is 6269 given and any current entity exists for that resource, then the 6270 server MUST NOT perform the requested method, unless required to do 6271 so because the resource's modification date fails to match that 6272 supplied in an If-Modified-Since header field in the request. 6273 Instead, if the request method was GET or HEAD, the server SHOULD 6274 respond with a 304 (Not Modified) response, including the cache- 6275 related header fields (particularly ETag) of one of the entities that 6276 matched. For all other request methods, the server MUST respond with 6277 a status of 412 (Precondition Failed). 6279 See section 13.3.3 for rules on how to determine if two entities tags 6280 match. The weak comparison function can only be used with GET or HEAD 6281 requests. 6283 If none of the entity tags match, then the server MAY perform the 6284 requested method as if the If-None-Match header field did not exist, 6285 but MUST also ignore any If-Modified-Since header field(s) in the 6286 request. That is, if no entity tags match, then the server MUST NOT 6287 return a 304 (Not Modified) response. 6289 If the request would, without the If-None-Match header field, result 6290 in anything other than a 2xx or 304 status, then the If-None-Match 6291 header MUST be ignored. (See section 13.3.4 for a discussion of 6292 server behavior when both If-Modified-Since and If-None-Match appear 6293 in the same request.) 6295 The meaning of "If-None-Match: *" is that the method MUST NOT be 6296 performed if the representation selected by the origin server (or by 6297 a cache, possibly using the Vary mechanism, see section 14.44) 6298 exists, and SHOULD be performed if the representation does not exist. 6299 This feature is intended to be useful in preventing races between PUT 6300 operations. 6302 Examples: 6304 If-None-Match: "xyzzy" 6305 If-None-Match: W/"xyzzy" 6306 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 6307 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 6308 If-None-Match: * 6310 The result of a request having both an If-None-Match header field and 6311 either an If-Match or an If-Unmodified-Since header fields is 6312 undefined by this specification. 6314 14.27 If-Range 6316 If a client has a partial copy of an entity in its cache, and wishes 6317 to have an up-to-date copy of the entire entity in its cache, it 6318 could use the Range request-header with a conditional GET (using 6319 either or both of If-Unmodified-Since and If-Match.) However, if the 6320 condition fails because the entity has been modified, the client 6321 would then have to make a second request to obtain the entire current 6322 entity-body. 6324 The If-Range header allows a client to "short-circuit" the second 6325 request. Informally, its meaning is `if the entity is unchanged, send 6326 me the part(s) that I am missing; otherwise, send me the entire new 6327 entity.' 6329 If-Range = "If-Range" ":" ( entity-tag | HTTP-date ) 6331 If the client has no entity tag for an entity, but does have a Last- 6332 Modified date, it MAY use that date in an If-Range header. (The 6333 server can distinguish between a valid HTTP-date and any form of 6334 entity-tag by examining no more than two characters.) The If-Range 6335 header SHOULD only be used together with a Range header, and MUST be 6336 ignored if the request does not include a Range header, or if the 6337 server does not support the sub-range operation. 6339 If the entity tag given in the If-Range header matches the current 6340 entity tag for the entity, then the server SHOULD provide the 6341 specified sub-range of the entity using a 206 (Partial content) 6342 response. If the entity tag does not match, then the server SHOULD 6343 return the entire entity using a 200 (OK) response. 6345 14.28 If-Unmodified-Since 6347 The If-Unmodified-Since request-header field is used with a method to 6348 make it conditional. If the requested resource has not been modified 6349 since the time specified in this field, the server SHOULD perform the 6350 requested operation as if the If-Unmodified-Since header were not 6351 present. 6353 If the requested variant has been modified since the specified time, 6354 the server MUST NOT perform the requested operation, and MUST return 6355 a 412 (Precondition Failed). 6357 If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date 6359 An example of the field is: 6361 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 6363 If the request normally (i.e., without the If-Unmodified-Since 6364 header) would result in anything other than a 2xx or 412 status, the 6365 If-Unmodified-Since header SHOULD be ignored. 6367 If the specified date is invalid, the header is ignored. 6369 The result of a request having both an If-Unmodified-Since header 6370 field and either an If-None-Match or an If-Modified-Since header 6371 fields is undefined by this specification. 6373 14.29 Last-Modified 6375 The Last-Modified entity-header field indicates the date and time at 6376 which the origin server believes the variant was last modified. 6378 Last-Modified = "Last-Modified" ":" HTTP-date 6380 An example of its use is 6382 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 6384 The exact meaning of this header field depends on the implementation 6385 of the origin server and the nature of the original resource. For 6386 files, it may be just the file system last-modified time. For 6387 entities with dynamically included parts, it may be the most recent 6388 of the set of last-modify times for its component parts. For database 6389 gateways, it may be the last-update time stamp of the record. For 6390 virtual objects, it may be the last time the internal state changed. 6392 An origin server MUST NOT send a Last-Modified date which is later 6393 than the server's time of message origination. In such cases, where 6394 the resource's last modification would indicate some time in the 6395 future, the server MUST replace that date with the message 6396 origination date. 6398 An origin server SHOULD obtain the Last-Modified value of the entity 6399 as close as possible to the time that it generates the Date value of 6400 its response. This allows a recipient to make an accurate assessment 6401 of the entity's modification time, especially if the entity changes 6402 near the time that the response is generated. 6404 HTTP/1.1 servers SHOULD send Last-Modified whenever feasible. 6406 14.30 Location 6408 The Location response-header field is used to redirect the recipient 6409 to a location other than the Request-URI for completion of the 6410 request or identification of a new resource. For 201 (Created) 6411 responses, the Location is that of the new resource which was created 6412 by the request. For 3xx responses, the location SHOULD indicate the 6413 server's preferred URI for automatic redirection to the resource. The 6414 field value consists of a single absolute URI. 6416 Location = "Location" ":" absoluteURI 6418 An example is: 6420 Location: http://www.w3.org/pub/WWW/People.html 6422 Note: The Content-Location header field (section 14.14) differs 6423 from Location in that the Content-Location identifies the 6424 original location of the entity enclosed in the request. It is 6425 therefore possible for a response to contain header fields for 6426 both Location and Content-Location. Also see section 13.10 for 6427 cache requirements of some methods. 6429 14.31 Max-Forwards 6431 The Max-Forwards request-header field provides a mechanism with the 6432 TRACE (section 9.8) and OPTIONS (section 9.2) methods to limit the 6433 number of proxies or gateways that can forward the request to the 6434 next inbound server. This can be useful when the client is attempting 6435 to trace a request chain which appears to be failing or looping in 6436 mid-chain. 6438 Max-Forwards = "Max-Forwards" ":" 1*DIGIT 6440 The Max-Forwards value is a decimal integer indicating the remaining 6441 number of times this request message may be forwarded. 6443 Each proxy or gateway recipient of a TRACE or OPTIONS request 6444 containing a Max-Forwards header field MUST check and update its 6445 value prior to forwarding the request. If the received value is zero 6446 (0), the recipient MUST NOT forward the request; instead, it MUST 6447 respond as the final recipient. If the received Max-Forwards value is 6448 greater than zero, then the forwarded message MUST contain an updated 6449 Max-Forwards field with a value decremented by one (1). 6451 The Max-Forwards header field MAY be ignored for all other methods 6452 defined by this specification and for any extension methods for which 6453 it is not explicitly referred to as part of that method definition. 6455 14.32 Pragma 6457 The Pragma general-header field is used to include implementation- 6458 specific directives that might apply to any recipient along the 6459 request/response chain. All pragma directives specify optional 6460 behavior from the viewpoint of the protocol; however, some systems 6461 MAY require that behavior be consistent with the directives. 6463 Pragma = "Pragma" ":" 1#pragma-directive 6464 pragma-directive = "no-cache" | extension-pragma 6465 extension-pragma = token [ "=" ( token | quoted-string ) ] 6467 When the no-cache directive is present in a request message, an 6468 application SHOULD forward the request toward the origin server even 6469 if it has a cached copy of what is being requested. This pragma 6470 directive has the same semantics as the no-cache cache-directive (see 6471 section 14.9) and is defined here for backward compatibility with 6472 HTTP/1.0. Clients SHOULD include both header fields when a no-cache 6473 request is sent to a server not known to be HTTP/1.1 compliant. 6475 Pragma directives MUST be passed through by a proxy or gateway 6476 application, regardless of their significance to that application, 6477 since the directives might be applicable to all recipients along the 6478 request/response chain. It is not possible to specify a pragma for a 6479 specific recipient; however, any pragma directive not relevant to a 6480 recipient SHOULD be ignored by that recipient. 6482 HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had 6483 sent "Cache-Control: no-cache". No new Pragma directives will be 6484 defined in HTTP. 6486 14.33 Proxy-Authenticate 6488 The Proxy-Authenticate response-header field MUST be included as part 6489 of a 407 (Proxy Authentication Required) response. The field value 6490 consists of a challenge that indicates the authentication scheme and 6491 parameters applicable to the proxy for this Request-URI. 6493 Proxy-Authenticate = "Proxy-Authenticate" ":" 1#challenge 6495 The HTTP access authentication process is described in "HTTP 6496 Authentication: Basic and Digest Access Authentication" [43]. Unlike 6497 WWW-Authenticate, the Proxy-Authenticate header field applies only to 6498 the current connection and SHOULD NOT be passed on to downstream 6499 clients. However, an intermediate proxy might need to obtain its own 6500 credentials by requesting them from the downstream client, which in 6501 some circumstances will appear as if the proxy is forwarding the 6502 Proxy-Authenticate header field. 6504 14.34 Proxy-Authorization 6506 The Proxy-Authorization request-header field allows the client to 6507 identify itself (or its user) to a proxy which requires 6508 authentication. The Proxy-Authorization field value consists of 6509 credentials containing the authentication information of the user 6510 agent for the proxy and/or realm of the resource being requested. 6512 Proxy-Authorization = "Proxy-Authorization" ":" credentials 6514 The HTTP access authentication process is described in "HTTP 6515 Authentication: Basic and Digest Access Authentication" [43] . Unlike 6516 Authorization, the Proxy-Authorization header field applies only to 6517 the next outbound proxy that demanded authentication using the Proxy- 6518 Authenticate field. When multiple proxies are used in a chain, the 6519 Proxy-Authorization header field is consumed by the first outbound 6520 proxy that was expecting to receive credentials. A proxy MAY relay 6521 the credentials from the client request to the next proxy if that is 6522 the mechanism by which the proxies cooperatively authenticate a given 6523 request. 6525 14.35 Range 6527 14.35.1 Byte Ranges 6529 Since all HTTP entities are represented in HTTP messages as sequences 6530 of bytes, the concept of a byte range is meaningful for any HTTP 6531 entity. (However, not all clients and servers need to support byte- 6532 range operations.) 6534 Byte range specifications in HTTP apply to the sequence of bytes in 6535 the entity-body (not necessarily the same as the message-body). 6537 A byte range operation MAY specify a single range of bytes, or a set 6538 of ranges within a single entity. 6540 ranges-specifier = byte-ranges-specifier 6541 byte-ranges-specifier = bytes-unit "=" byte-range-set 6542 byte-range-set = 1#( byte-range-spec | suffix-byte-range-spec ) 6543 byte-range-spec = first-byte-pos "-" [last-byte-pos] 6544 first-byte-pos = 1*DIGIT 6545 last-byte-pos = 1*DIGIT 6547 The first-byte-pos value in a byte-range-spec gives the byte-offset 6548 of the first byte in a range. The last-byte-pos value gives the byte- 6549 offset of the last byte in the range; that is, the byte positions 6550 specified are inclusive. Byte offsets start at zero. 6552 If the last-byte-pos value is present, it MUST be greater than or 6553 equal to the first-byte-pos in that byte-range-spec, or the byte- 6554 range-spec is syntactically invalid. The recipient of a byte-range- 6555 set that includes one or more syntactically invalid byte-range-spec 6556 values MUST ignore the header field that includes that byte-range- 6557 set. 6559 If the last-byte-pos value is absent, or if the value is greater than 6560 or equal to the current length of the entity-body, last-byte-pos is 6561 taken to be equal to one less than the current length of the entity- 6562 body in bytes. 6564 By its choice of last-byte-pos, a client can limit the number of 6565 bytes retrieved without knowing the size of the entity. 6567 suffix-byte-range-spec = "-" suffix-length 6568 suffix-length = 1*DIGIT 6570 A suffix-byte-range-spec is used to specify the suffix of the entity- 6571 body, of a length given by the suffix-length value. (That is, this 6572 form specifies the last N bytes of an entity-body.) If the entity is 6573 shorter than the specified suffix-length, the entire entity-body is 6574 used. 6576 If a syntactically valid byte-range-set includes at least one byte- 6577 range-spec whose first-byte-pos is less than the current length of 6578 the entity-body, or at least one suffix-byte-range-spec with a non- 6579 zero suffix-length, then the byte-range-set is satisfiable. 6580 Otherwise, the byte-range-set is unsatisfiable. If the byte-range-set 6581 is unsatisfiable, the server SHOULD return a response with a status 6582 of 416 (Requested range not satisfiable). Otherwise, the server 6583 SHOULD return a response with a status of 206 (Partial Content) 6584 containing the satisfiable ranges of the entity-body. 6586 Examples of byte-ranges-specifier values (assuming an entity-body of 6587 length 10000): 6589 . The first 500 bytes (byte offsets 0-499, inclusive): 6590 bytes=0-499 6592 . The second 500 bytes (byte offsets 500-999, inclusive): 6593 bytes=500-999 6595 . The final 500 bytes (byte offsets 9500-9999, inclusive): 6596 bytes=-500 6598 . Or 6599 bytes=9500- 6601 . The first and last bytes only (bytes 0 and 9999): 6602 bytes=0-0,-1 6604 . Several legal but not canonical specifications of the second 6605 500 bytes (byte offsets 500-999, inclusive): 6606 bytes=500-600,601-999 6607 bytes=500-700,601-999 6609 14.35.2 Range Retrieval Requests 6611 HTTP retrieval requests using conditional or unconditional GET 6612 methods MAY request one or more sub-ranges of the entity, instead of 6613 the entire entity, using the Range request header, which applies to 6614 the entity returned as the result of the request: 6616 Range = "Range" ":" ranges-specifier 6618 A server MAY ignore the Range header. However, HTTP/1.1 origin 6619 servers and intermediate caches ought to support byte ranges when 6620 possible, since Range supports efficient recovery from partially 6621 failed transfers, and supports efficient partial retrieval of large 6622 entities. 6624 If the server supports the Range header and the specified range or 6625 ranges are appropriate for the entity: 6627 . The presence of a Range header in an unconditional GET modifies 6628 what is returned if the GET is otherwise successful. In other 6629 words, the response carries a status code of 206 (Partial 6630 Content) instead of 200 (OK). 6632 . The presence of a Range header in a conditional GET (a request 6633 using one or both of If-Modified-Since and If-None-Match, or 6634 one or both of If-Unmodified-Since and If-Match) modifies what 6635 is returned if the GET is otherwise successful and the 6636 condition is true. It does not affect the 304 (Not Modified) 6637 response returned if the conditional is false. 6639 In some cases, it might be more appropriate to use the If-Range 6640 header (see section 14.27) in addition to the Range header. 6642 If a proxy that supports ranges receives a Range request, forwards 6643 the request to an inbound server, and receives an entire entity in 6644 reply, it SHOULD only return the requested range to its client. It 6645 SHOULD store the entire received response in its cache if that is 6646 consistent with its cache allocation policies. 6648 14.36 Referer 6650 The Referer[sic] request-header field allows the client to specify, 6651 for the server's benefit, the address (URI) of the resource from 6652 which the Request-URI was obtained (the "referrer", although the 6653 header field is misspelled.) The Referer request-header allows a 6654 server to generate lists of back-links to resources for interest, 6655 logging, optimized caching, etc. It also allows obsolete or mistyped 6656 links to be traced for maintenance. The Referer field MUST NOT be 6657 sent if the Request-URI was obtained from a source that does not have 6658 its own URI, such as input from the user keyboard. 6660 Referer = "Referer" ":" ( absoluteURI | relativeURI ) 6662 Example: 6664 Referer: http://www.w3.org/hypertext/DataSources/Overview.html 6666 If the field value is a relative URI, it SHOULD be interpreted 6667 relative to the Request-URI. The URI MUST NOT include a fragment. See 6668 section 15.1.3 for security considerations. 6670 14.37 Retry-After 6672 The Retry-After response-header field can be used with a 503 (Service 6673 Unavailable) response to indicate how long the service is expected to 6674 be unavailable to the requesting client. This field MAY also be used 6675 with any 3xx (Redirection) response to indicate the minimum time the 6676 user-agent is asked wait before issuing the redirected request. The 6677 value of this field can be either an HTTP-date or an integer number 6678 of seconds (in decimal) after the time of the response. 6680 Retry-After = "Retry-After" ":" ( HTTP-date | delta-seconds ) 6682 Two examples of its use are 6684 Retry-After: Fri, 31 Dec 1999 23:59:59 GMT 6685 Retry-After: 120 6687 In the latter example, the delay is 2 minutes. 6689 14.38 Server 6691 The Server response-header field contains information about the 6692 software used by the origin server to handle the request. The field 6693 can contain multiple product tokens (section 3.8) and comments 6694 identifying the server and any significant subproducts. The product 6695 tokens are listed in order of their significance for identifying the 6696 application. 6698 Server = "Server" ":" 1*( product | comment ) 6700 Example: 6702 Server: CERN/3.0 libwww/2.17 6704 If the response is being forwarded through a proxy, the proxy 6705 application MUST NOT modify the Server response-header. Instead, it 6706 SHOULD include a Via field (as described in section 14.45). 6708 Note: Revealing the specific software version of the server 6709 might allow the server machine to become more vulnerable to 6710 attacks against software that is known to contain security 6711 holes. Server implementors are encouraged to make this field a 6712 configurable option. 6714 14.39 TE 6716 The TE request-header field indicates what extension transfer-codings 6717 it is willing to accept in the response and whether or not it is 6718 willing to accept trailer fields in a chunked transfer-coding. Its 6719 value may consist of the keyword "trailers" and/or a comma-separated 6720 list of extension transfer-coding names with optional accept 6721 parameters (as described in section 3.6). 6723 TE = "TE" ":" #( t-codings ) 6724 t-codings = "trailers" | ( transfer-extension [ accept-params ] ) 6726 The presence of the keyword "trailers" indicates that the client is 6727 willing to accept trailer fields in a chunked transfer-coding, as 6728 defined in section 3.6.1. This keyword is reserved for use with 6729 transfer-coding values even though it does not itself represent a 6730 transfer-coding. 6732 Examples of its use are: 6734 TE: deflate 6735 TE: 6736 TE: trailers, deflate;q=0.5 6738 The TE header field only applies to the immediate connection. 6739 Therefore, the keyword MUST be supplied within a Connection header 6740 field (section 14.10) whenever TE is present in an HTTP/1.1 message. 6742 A server tests whether a transfer-coding is acceptable, according to 6743 a TE field, using these rules: 6745 1. 6746 The "chunked" transfer-coding is always acceptable. If the 6747 keyword "trailers" is listed, the client indicates that it is 6748 willing to accept trailer fields in the chunked response on 6749 behalf of itself and any downstream clients. The implication is 6750 that, if given, the client is stating that either all downstream 6751 clients are willing to accept trailer fields in the forwarded 6752 response, or that it will attempt to buffer the response on 6753 behalf of downstream recipients. 6755 Note: HTTP/1.1 does not define any means to limit the size of a 6756 chunked response such that a client can be assured of buffering 6757 the entire response. 6759 2. If the transfer-coding being tested is one of the transfer- 6760 codings listed in the TE field, then it is acceptable unless it 6761 is accompanied by a qvalue of 0. (As defined in section 3.9, a 6762 qvalue of 0 means "not acceptable.") 6764 3. If multiple transfer-codings are acceptable, then the acceptable 6765 transfer-coding with the highest non-zero qvalue is preferred. 6766 The "chunked" transfer-coding always has a qvalue of 1. 6768 If the TE field-value is empty or if no TE field is present, the only 6769 transfer-coding is "chunked". A message with no transfer-coding is 6770 always acceptable. 6772 14.40 Trailer 6774 The Trailer general field value indicates that the given set of 6775 header fields is present in the trailer of a message encoded with 6776 chunked transfer-coding. 6778 Trailer = "Trailer" ":" 1#field-name 6780 An HTTP/1.1 message SHOULD include a Trailer header field in a 6781 message using chunked transfer-coding with a non-empty trailer. Doing 6782 so allows the recipient to know which header fields to expect in the 6783 trailer. 6785 If no Trailer header field is present, the trailer SHOULD NOT include 6786 any header fields. See section 3.6.1 for restrictions on the use of 6787 trailer fields in a "chunked" transfer-coding. 6789 Message header fields listed in the Trailer header field MUST NOT 6790 include the following header fields: 6792 . Transfer-Encoding 6794 . Content-Length 6796 . Trailer 6798 14.41 Transfer-Encoding 6800 The Transfer-Encoding general-header field indicates what (if any) 6801 type of transformation has been applied to the message body in order 6802 to safely transfer it between the sender and the recipient. This 6803 differs from the content-coding in that the transfer-coding is a 6804 property of the message, not of the entity. 6806 Transfer-Encoding = "Transfer-Encoding" ":" 1#transfer-coding 6808 Transfer-codings are defined in section 3.6. An example is: 6810 Transfer-Encoding: chunked 6812 If multiple encodings have been applied to an entity, the transfer- 6813 codings MUST be listed in the order in which they were applied. 6814 Additional information about the encoding parameters MAY be provided 6815 by other entity-header fields not defined by this specification. 6817 Many older HTTP/1.0 applications do not understand the Transfer- 6818 Encoding header. 6820 14.42 Upgrade 6822 The Upgrade general-header allows the client to specify what 6823 additional communication protocols it supports and would like to use 6824 if the server finds it appropriate to switch protocols. The server 6825 MUST use the Upgrade header field within a 101 (Switching Protocols) 6826 response to indicate which protocol(s) are being switched. 6828 Upgrade = "Upgrade" ":" 1#product 6830 For example, 6832 Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11 6834 The Upgrade header field is intended to provide a simple mechanism 6835 for transition from HTTP/1.1 to some other, incompatible protocol. It 6836 does so by allowing the client to advertise its desire to use another 6837 protocol, such as a later version of HTTP with a higher major version 6838 number, even though the current request has been made using HTTP/1.1. 6839 This eases the difficult transition between incompatible protocols by 6840 allowing the client to initiate a request in the more commonly 6841 supported protocol while indicating to the server that it would like 6842 to use a "better" protocol if available (where "better" is determined 6843 by the server, possibly according to the nature of the method and/or 6844 resource being requested). 6846 The Upgrade header field only applies to switching application-layer 6847 protocols upon the existing transport-layer connection. Upgrade 6848 cannot be used to insist on a protocol change; its acceptance and use 6849 by the server is optional. The capabilities and nature of the 6850 application-layer communication after the protocol change is entirely 6851 dependent upon the new protocol chosen, although the first action 6852 after changing the protocol MUST be a response to the initial HTTP 6853 request containing the Upgrade header field. 6855 The Upgrade header field only applies to the immediate connection. 6856 Therefore, the upgrade keyword MUST be supplied within a Connection 6857 header field (section 14.10) whenever Upgrade is present in an 6858 HTTP/1.1 message. 6860 The Upgrade header field cannot be used to indicate a switch to a 6861 protocol on a different connection. For that purpose, it is more 6862 appropriate to use a 301, 302, 303, or 305 redirection response. 6864 This specification only defines the protocol name "HTTP" for use by 6865 the family of Hypertext Transfer Protocols, as defined by the HTTP 6866 version rules of section 3.1 and future updates to this 6867 specification. Any token can be used as a protocol name; however, it 6868 will only be useful if both the client and server associate the name 6869 with the same protocol. 6871 14.43 User-Agent 6873 The User-Agent request-header field contains information about the 6874 user agent originating the request. This is for statistical purposes, 6875 the tracing of protocol violations, and automated recognition of user 6876 agents for the sake of tailoring responses to avoid particular user 6877 agent limitations. User agents SHOULD include this field with 6878 requests. The field can contain multiple product tokens (section 3.8) 6879 and comments identifying the agent and any subproducts which form a 6880 significant part of the user agent. By convention, the product tokens 6881 are listed in order of their significance for identifying the 6882 application. 6884 User-Agent = "User-Agent" ":" 1*( product | comment ) 6886 Example: 6888 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 6890 14.44 Vary 6892 The Vary field value indicates the set of request-header fields that 6893 fully determines, while the response is fresh, whether a cache is 6894 permitted to use the response to reply to a subsequent request 6895 without revalidation. For uncacheable or stale responses, the Vary 6896 field value advises the user agent about the criteria that were used 6897 to select the representation. A Vary field value of "*" implies that 6898 a cache cannot determine from the request headers of a subsequent 6899 request whether this response is the appropriate representation. See 6900 section 13.6 for use of the Vary header field by caches. 6902 Vary = "Vary" ":" ( "*" | 1#field-name ) 6904 An HTTP/1.1 server SHOULD include a Vary header field with any 6905 cacheable response that is subject to server-driven negotiation. 6906 Doing so allows a cache to properly interpret future requests on that 6907 resource and informs the user agent about the presence of negotiation 6908 on that resource. A server MAY include a Vary header field with a 6909 non-cacheable response that is subject to server-driven negotiation, 6910 since this might provide the user agent with useful information about 6911 the dimensions over which the response varies at the time of the 6912 response. 6914 A Vary field value consisting of a list of field-names signals that 6915 the representation selected for the response is based on a selection 6916 algorithm which considers ONLY the listed request-header field values 6917 in selecting the most appropriate representation. A cache MAY assume 6918 that the same selection will be made for future requests with the 6919 same values for the listed field names, for the duration of time for 6920 which the response is fresh. 6922 The field-names given are not limited to the set of standard request- 6923 header fields defined by this specification. Field names are case- 6924 insensitive. 6926 A Vary field value of "*" signals that unspecified parameters not 6927 limited to the request-headers (e.g., the network address of the 6928 client), play a role in the selection of the response representation. 6929 The "*" value MUST NOT be generated by a proxy server; it may only be 6930 generated by an origin server. 6932 14.45 Via 6934 The Via general-header field MUST be used by gateways and proxies to 6935 indicate the intermediate protocols and recipients between the user 6936 agent and the server on requests, and between the origin server and 6937 the client on responses. It is analogous to the "Received" field of 6938 RFC 822 [9] and is intended to be used for tracking message forwards, 6939 avoiding request loops, and identifying the protocol capabilities of 6940 all senders along the request/response chain. 6942 Via = "Via" ":" 1#( received-protocol received-by [ comment ] ) 6943 received-protocol = [ protocol-name "/" ] protocol-version 6944 protocol-name = token 6945 protocol-version = token 6946 received-by = ( host [ ":" port ] ) | pseudonym 6947 pseudonym = token 6949 The received-protocol indicates the protocol version of the message 6950 received by the server or client along each segment of the 6951 request/response chain. The received-protocol version is appended to 6952 the Via field value when the message is forwarded so that information 6953 about the protocol capabilities of upstream applications remains 6954 visible to all recipients. 6956 The protocol-name is optional if and only if it would be "HTTP". The 6957 received-by field is normally the host and optional port number of a 6958 recipient server or client that subsequently forwarded the message. 6959 However, if the real host is considered to be sensitive information, 6960 it MAY be replaced by a pseudonym. If the port is not given, it MAY 6961 be assumed to be the default port of the received-protocol. 6963 Multiple Via field values represents each proxy or gateway that has 6964 forwarded the message. Each recipient MUST append its information 6965 such that the end result is ordered according to the sequence of 6966 forwarding applications. 6968 Comments MAY be used in the Via header field to identify the software 6969 of the recipient proxy or gateway, analogous to the User-Agent and 6970 Server header fields. However, all comments in the Via field are 6971 optional and MAY be removed by any recipient prior to forwarding the 6972 message. 6974 For example, a request message could be sent from an HTTP/1.0 user 6975 agent to an internal proxy code-named "fred", which uses HTTP/1.1 to 6976 forward the request to a public proxy at nowhere.com, which completes 6977 the request by forwarding it to the origin server at www.ics.uci.edu. 6978 The request received by www.ics.uci.edu would then have the following 6979 Via header field: 6981 Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1) 6983 Proxies and gateways used as a portal through a network firewall 6984 SHOULD NOT, by default, forward the names and ports of hosts within 6985 the firewall region. This information SHOULD only be propagated if 6986 explicitly enabled. If not enabled, the received-by host of any host 6987 behind the firewall SHOULD be replaced by an appropriate pseudonym 6988 for that host. 6990 For organizations that have strong privacy requirements for hiding 6991 internal structures, a proxy MAY combine an ordered subsequence of 6992 Via header field entries with identical received-protocol values into 6993 a single such entry. For example, 6995 Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy 6997 could be collapsed to 6999 Via: 1.0 ricky, 1.1 mertz, 1.0 lucy 7001 Applications SHOULD NOT combine multiple entries unless they are all 7002 under the same organizational control and the hosts have already been 7003 replaced by pseudonyms. Applications MUST NOT combine entries which 7004 have different received-protocol values. 7006 14.46 Warning 7008 The Warning general-header field is used to carry additional 7009 information about the status or transformation of a message which 7010 might not be reflected in the message. This information is typically 7011 used to warn about a possible lack of semantic transparency from 7012 caching operations or transformations applied to the entity body of 7013 the message. 7015 Warning headers are sent with responses using: 7017 Warning = "Warning" ":" 1#warning-value 7019 warning-value = warn-code SP warn-agent SP warn-text 7020 [SP warn-date] 7022 warn-code = 3DIGIT 7023 warn-agent = ( host [ ":" port ] ) | pseudonym 7024 ; the name or pseudonym of the server adding 7025 ; the Warning header, for use in debugging 7026 warn-text = quoted-string 7027 warn-date = <"> HTTP-date <"> 7029 A response MAY carry more than one Warning header. 7031 The warn-text SHOULD be in a natural language and character set that 7032 is most likely to be intelligible to the human user receiving the 7033 response. This decision MAY be based on any available knowledge, such 7034 as the location of the cache or user, the Accept-Language field in a 7035 request, the Content-Language field in a response, etc. The default 7036 language is English and the default character set is ISO-8859-1. 7038 If a character set other than ISO-8859-1 is used, it MUST be encoded 7039 in the warn-text using the method described in RFC 2047 [14]. 7041 Warning headers can in general be applied to any message, however 7042 some specific warn-codes are specific to caches and can only be 7043 applied to response messages. New Warning headers SHOULD be added 7044 after any existing Warning headers. A cache MUST NOT delete any 7045 Warning header that it received with a message. However, if a cache 7046 successfully validates a cache entry, it SHOULD remove any Warning 7047 headers previously attached to that entry except as specified for 7048 specific Warning codes. It MUST then add any Warning headers received 7049 in the validating response. In other words, Warning headers are those 7050 that would be attached to the most recent relevant response. 7052 When multiple Warning headers are attached to a response, the user 7053 agent ought to inform the user of as many of them as possible, in the 7054 order that they appear in the response. If it is not possible to 7055 inform the user of all of the warnings, the user agent SHOULD follow 7056 these heuristics: 7058 . Warnings that appear early in the response take priority over 7059 those appearing later in the response. 7061 . Warnings in the user's preferred character set take priority 7062 over warnings in other character sets but with identical warn- 7063 codes and warn-agents. 7065 Systems that generate multiple Warning headers SHOULD order them with 7066 this user agent behavior in mind. 7068 Requirements for the behavior of caches with respect to Warnings are 7069 stated in section 13.1.2. 7071 This is a list of the currently-defined warn-codes, each with a 7072 recommended warn-text in English, and a description of its meaning. 7074 110 Response is stale 7075 MUST be included whenever the returned response is stale. 7077 111 Revalidation failed 7078 MUST be included if a cache returns a stale response because an 7079 attempt to revalidate the response failed, due to an inability to 7080 reach the server. 7082 112 Disconnected operation 7083 SHOULD be included if the cache is intentionally disconnected 7084 from the rest of the network for a period of time. 7086 113 Heuristic expiration 7087 MUST be included if the cache heuristically chose a freshness 7088 lifetime greater than 24 hours and the response's age is greater 7089 than 24 hours. 7091 199 Miscellaneous warning 7092 The warning text MAY include arbitrary information to be presented 7093 to a human user, or logged. A system receiving this warning MUST 7094 NOT take any automated action, besides presenting the warning to 7095 the user. 7097 214 Transformation applied 7098 MUST be added by an intermediate cache or proxy if it applies any 7099 transformation changing the content-coding (as specified in the 7100 Content-Encoding header) or media-type (as specified in the 7101 Content-Type header) of the response, or the entity-body of the 7102 response, unless this Warning code already appears in the 7103 response. 7105 299 Miscellaneous persistent warning 7106 The warning text MAY include arbitrary information to be presented 7107 to a human user, or logged. A system receiving this warning MUST 7108 NOT take any automated action. 7110 If an implementation sends a message with one or more Warning headers 7111 whose version is HTTP/1.0 or lower, then the sender MUST include in 7112 each warning-value a warn-date that matches the date in the response. 7114 If an implementation receives a message with a warning-value that 7115 includes a warn-date, and that warn-date is different from the Date 7116 value in the response, then that warning-value MUST be deleted from 7117 the message before storing, forwarding, or using it. (This prevents 7118 bad consequences of naive caching of Warning header fields.) If all 7119 of the warning-values are deleted for this reason, the Warning header 7120 MUST be deleted as well. 7122 14.47 WWW-Authenticate 7124 The WWW-Authenticate response-header field MUST be included in 401 7125 (Unauthorized) response messages. The field value consists of at 7126 least one challenge that indicates the authentication scheme(s) and 7127 parameters applicable to the Request-URI. 7129 WWW-Authenticate = "WWW-Authenticate" ":" 1#challenge 7131 The HTTP access authentication process is described in "HTTP 7132 Authentication: Basic and Digest Access Authentication" [43]. User 7133 agents are advised to take special care in parsing the WWW- 7134 Authenticate field value as it might contain more than one challenge, 7135 or if more than one WWW-Authenticate header field is provided, the 7136 contents of a challenge itself can contain a comma-separated list of 7137 authentication parameters. 7139 15 Security Considerations 7140 This section is meant to inform application developers, information 7141 providers, and users of the security limitations in HTTP/1.1 as 7142 described by this document. The discussion does not include 7143 definitive solutions to the problems revealed, though it does make 7144 some suggestions for reducing security risks. 7146 15.1 Personal Information 7148 HTTP clients are often privy to large amounts of personal information 7149 (e.g. the user's name, location, mail address, passwords, encryption 7150 keys, etc.), and SHOULD be very careful to prevent unintentional 7151 leakage of this information via the HTTP protocol to other sources. 7152 We very strongly recommend that a convenient interface be provided 7153 for the user to control dissemination of such information, and that 7154 designers and implementors be particularly careful in this area. 7155 History shows that errors in this area often create serious security 7156 and/or privacy problems and generate highly adverse publicity for the 7157 implementor's company. 7159 15.1.1 Abuse of Server Log Information 7161 A server is in the position to save personal data about a user's 7162 requests which might identify their reading patterns or subjects of 7163 interest. This information is clearly confidential in nature and its 7164 handling can be constrained by law in certain countries. People using 7165 the HTTP protocol to provide data are responsible for ensuring that 7166 such material is not distributed without the permission of any 7167 individuals that are identifiable by the published results. 7169 15.1.2 Transfer of Sensitive Information 7171 Like any generic data transfer protocol, HTTP cannot regulate the 7172 content of the data that is transferred, nor is there any a priori 7173 method of determining the sensitivity of any particular piece of 7174 information within the context of any given request. Therefore, 7175 applications SHOULD supply as much control over this information as 7176 possible to the provider of that information. Four header fields are 7177 worth special mention in this context: Server, Via, Referer and From. 7179 Revealing the specific software version of the server might allow the 7180 server machine to become more vulnerable to attacks against software 7181 that is known to contain security holes. Implementors SHOULD make the 7182 Server header field a configurable option. 7184 Proxies which serve as a portal through a network firewall SHOULD 7185 take special precautions regarding the transfer of header information 7186 that identifies the hosts behind the firewall. In particular, they 7187 SHOULD remove, or replace with sanitized versions, any Via fields 7188 generated behind the firewall. 7190 The Referer header allows reading patterns to be studied and reverse 7191 links drawn. Although it can be very useful, its power can be abused 7192 if user details are not separated from the information contained in 7193 the Referer. Even when the personal information has been removed, the 7194 Referer header might indicate a private document's URI whose 7195 publication would be inappropriate. 7197 The information sent in the From field might conflict with the user's 7198 privacy interests or their site's security policy, and hence it 7199 SHOULD NOT be transmitted without the user being able to disable, 7200 enable, and modify the contents of the field. The user MUST be able 7201 to set the contents of this field within a user preference or 7202 application defaults configuration. 7204 We suggest, though do not require, that a convenient toggle interface 7205 be provided for the user to enable or disable the sending of From and 7206 Referer information. 7208 The User-Agent (section 14.43) or Server (section 14.38) header 7209 fields can sometimes be used to determine that a specific client or 7210 server have a particular security hole which might be exploited. 7211 Unfortunately, this same information is often used for other valuable 7212 purposes for which HTTP currently has no better mechanism. 7214 15.1.3 Encoding Sensitive Information in URI's 7216 Because the source of a link might be private information or might 7217 reveal an otherwise private information source, it is strongly 7218 recommended that the user be able to select whether or not the 7219 Referer field is sent. For example, a browser client could have a 7220 toggle switch for browsing openly/anonymously, which would 7221 respectively enable/disable the sending of Referer and From 7222 information. 7224 Clients SHOULD NOT include a Referer header field in a (non-secure) 7225 HTTP request if the referring page was transferred with a secure 7226 protocol. 7228 Authors of services which use the HTTP protocol SHOULD NOT use GET 7229 based forms for the submission of sensitive data, because this will 7230 cause this data to be encoded in the Request-URI. Many existing 7231 servers, proxies, and user agents will log the request URI in some 7232 place where it might be visible to third parties. Servers can use 7233 POST-based form submission instead 7235 15.1.4 Privacy Issues Connected to Accept Headers 7237 Accept request-headers can reveal information about the user to all 7238 servers which are accessed. The Accept-Language header in particular 7239 can reveal information the user would consider to be of a private 7240 nature, because the understanding of particular languages is often 7241 strongly correlated to the membership of a particular ethnic group. 7242 User agents which offer the option to configure the contents of an 7243 Accept-Language header to be sent in every request are strongly 7244 encouraged to let the configuration process include a message which 7245 makes the user aware of the loss of privacy involved. 7247 An approach that limits the loss of privacy would be for a user agent 7248 to omit the sending of Accept-Language headers by default, and to ask 7249 the user whether or not to start sending Accept-Language headers to a 7250 server if it detects, by looking for any Vary response-header fields 7251 generated by the server, that such sending could improve the quality 7252 of service. 7254 Elaborate user-customized accept header fields sent in every request, 7255 in particular if these include quality values, can be used by servers 7256 as relatively reliable and long-lived user identifiers. Such user 7257 identifiers would allow content providers to do click-trail tracking, 7258 and would allow collaborating content providers to match cross-server 7259 click-trails or form submissions of individual users. Note that for 7260 many users not behind a proxy, the network address of the host 7261 running the user agent will also serve as a long-lived user 7262 identifier. In environments where proxies are used to enhance 7263 privacy, user agents ought to be conservative in offering accept 7264 header configuration options to end users. As an extreme privacy 7265 measure, proxies could filter the accept headers in relayed requests. 7266 General purpose user agents which provide a high degree of header 7267 configurability SHOULD warn users about the loss of privacy which can 7268 be involved. 7270 15.2 Attacks Based On File and Path Names 7272 Implementations of HTTP origin servers SHOULD be careful to restrict 7273 the documents returned by HTTP requests to be only those that were 7274 intended by the server administrators. If an HTTP server translates 7275 HTTP URIs directly into file system calls, the server MUST take 7276 special care not to serve files that were not intended to be 7277 delivered to HTTP clients. For example, UNIX, Microsoft Windows, and 7278 other operating systems use ".." as a path component to indicate a 7279 directory level above the current one. On such a system, an HTTP 7280 server MUST disallow any such construct in the Request-URI if it 7281 would otherwise allow access to a resource outside those intended to 7282 be accessible via the HTTP server. Similarly, files intended for 7283 reference only internally to the server (such as access control 7284 files, configuration files, and script code) MUST be protected from 7285 inappropriate retrieval, since they might contain sensitive 7286 information. Experience has shown that minor bugs in such HTTP server 7287 implementations have turned into security risks. 7289 15.3 DNS Spoofing 7291 Clients using HTTP rely heavily on the Domain Name Service, and are 7292 thus generally prone to security attacks based on the deliberate mis- 7293 association of IP addresses and DNS names. Clients need to be 7294 cautious in assuming the continuing validity of an IP number/DNS name 7295 association. 7297 In particular, HTTP clients SHOULD rely on their name resolver for 7298 confirmation of an IP number/DNS name association, rather than 7299 caching the result of previous host name lookups. Many platforms 7300 already can cache host name lookups locally when appropriate, and 7301 they SHOULD be configured to do so. It is proper for these lookups to 7302 be cached, however, only when the TTL (Time To Live) information 7303 reported by the name server makes it likely that the cached 7304 information will remain useful. 7306 If HTTP clients cache the results of host name lookups in order to 7307 achieve a performance improvement, they MUST observe the TTL 7308 information reported by DNS. 7310 If HTTP clients do not observe this rule, they could be spoofed when 7311 a previously-accessed server's IP address changes. As network 7312 renumbering is expected to become increasingly common [24], the 7313 possibility of this form of attack will grow. Observing this 7314 requirement thus reduces this potential security vulnerability. 7316 This requirement also improves the load-balancing behavior of clients 7317 for replicated servers using the same DNS name and reduces the 7318 likelihood of a user's experiencing failure in accessing sites which 7319 use that strategy. 7321 15.4 Location Headers and Spoofing 7323 If a single server supports multiple organizations that do not trust 7324 one another, then it MUST check the values of Location and Content- 7325 Location headers in responses that are generated under control of 7326 said organizations to make sure that they do not attempt to 7327 invalidate resources over which they have no authority. 7329 15.5 Content-Disposition Issues 7331 RFC 1806 [35], from which the often implemented Content-Disposition 7332 (see section 19.5.1) header in HTTP is derived, has a number of very 7333 serious security considerations. Content-Disposition is not part of 7334 the HTTP standard, but since it is widely implemented, we are 7335 documenting its use and risks for implementors. See RFC 2183 [49] 7336 (which updates RFC 1806) for details. 7338 15.6 Authentication Credentials and Idle Clients 7340 Existing HTTP clients and user agents typically retain authentication 7341 information indefinitely. HTTP/1.1. does not provide a method for a 7342 server to direct clients to discard these cached credentials. This is 7343 a significant defect that requires further extensions to HTTP. 7344 Circumstances under which credential caching can interfere with the 7345 application's security model include but are not limited to: 7347 . Clients which have been idle for an extended period following 7348 which the server might wish to cause the client to reprompt the 7349 user for credentials. 7351 . Applications which include a session termination indication 7352 (such as a `logout' or `commit' button on a page) after which 7353 the server side of the application `knows' that there is no 7354 further reason for the client to retain the credentials. 7356 This is currently under separate study. There are a number of work- 7357 arounds to parts of this problem, and we encourage the use of 7358 password protection in screen savers, idle time-outs, and other 7359 methods which mitigate the security problems inherent in this 7360 problem. In particular, user agents which cache credentials are 7361 encouraged to provide a readily accessible mechanism for discarding 7362 cached credentials under user control. 7364 15.7 Proxies and Caching 7366 By their very nature, HTTP proxies are men-in-the-middle, and 7367 represent an opportunity for man-in-the-middle attacks. Compromise of 7368 the systems on which the proxies run can result in serious security 7369 and privacy problems. Proxies have access to security-related 7370 information, personal information about individual users and 7371 organizations, and proprietary information belonging to users and 7372 content providers. A compromised proxy, or a proxy implemented or 7373 configured without regard to security and privacy considerations, 7374 might be used in the commission of a wide range of potential attacks. 7376 Proxy operators should protect the systems on which proxies run as 7377 they would protect any system that contains or transports sensitive 7378 information. In particular, log information gathered at proxies often 7379 contains highly sensitive personal information, and/or information 7380 about organizations. Log information should be carefully guarded, and 7381 appropriate guidelines for use developed and followed. (Section 7382 15.1.1). 7384 Caching proxies provide additional potential vulnerabilities, since 7385 the contents of the cache represent an attractive target for 7386 malicious exploitation. Because cache contents persist after an HTTP 7387 request is complete, an attack on the cache can reveal information 7388 long after a user believes that the information has been removed from 7389 the network. Therefore, cache contents should be protected as 7390 sensitive information. 7392 Proxy implementors should consider the privacy and security 7393 implications of their design and coding decisions, and of the 7394 configuration options they provide to proxy operators (especially the 7395 default configuration). 7397 Users of a proxy need to be aware that they are no trustworthier than 7398 the people who run the proxy; HTTP itself cannot solve this problem. 7400 The judicious use of cryptography, when appropriate, may suffice to 7401 protect against a broad range of security and privacy attacks. Such 7402 cryptography is beyond the scope of the HTTP/1.1 specification. 7404 15.7.1 Denial of Service Attacks on Proxies 7406 They exist. They are hard to defend against. Research continues. 7407 Beware. 7409 16 Acknowledgments 7411 This specification makes heavy use of the augmented BNF and generic 7412 constructs defined by David H. Crocker for RFC 822 [9]. Similarly, it 7413 reuses many of the definitions provided by Nathaniel Borenstein and 7414 Ned Freed for MIME [7]. We hope that their inclusion in this 7415 specification will help reduce past confusion over the relationship 7416 between HTTP and Internet mail message formats. 7418 The HTTP protocol has evolved considerably over the years. It has 7419 benefited from a large and active developer community--the many 7420 people who have participated on the www-talk mailing list--and it is 7421 that community which has been most responsible for the success of 7422 HTTP and of the World-Wide Web in general. Marc Andreessen, Robert 7423 Cailliau, Daniel W. Connolly, Bob Denny, John Franks, Jean-Francois 7424 Groff, Phillip M. Hallam-Baker, Hakon W. Lie, Ari Luotonen, Rob 7425 McCool, Lou Montulli, Dave Raggett, Tony Sanders, and Marc 7426 VanHeyningen deserve special recognition for their efforts in 7427 defining early aspects of the protocol. 7429 This document has benefited greatly from the comments of all those 7430 participating in the HTTP-WG. In addition to those already mentioned, 7431 the following individuals have contributed to this specification: 7433 Gary Adams Albert Lunde 7434 Harald Tveit Alvestrand John C. Mallery 7435 Keith Ball Jean-Philippe Martin-Flatin 7436 Brian Behlendorf Larry Masinter 7437 Paul Burchard Mitra 7438 Maurizio Codogno David Morris 7439 Mike Cowlishaw Gavin Nicol 7440 Roman Czyborra Bill Perry 7441 Michael A. Dolan Jeffrey Perry 7442 David J. Fiander Scott Powers 7443 Alan Freier Owen Rees 7444 Marc Hedlund Luigi Rizzo 7445 Greg Herlihy David Robinson 7446 Koen Holtman Marc Salomon 7447 Alex Hopmann Rich Salz 7448 Bob Jernigan Allan M. Schiffman 7449 Shel Kaphan Jim Seidman 7450 Rohit Khare Chuck Shotton 7451 John Klensin Eric W. Sink 7452 Martijn Koster Simon E. Spero 7453 Alexei Kosut Richard N. Taylor 7454 David M. Kristol Robert S. Thau 7455 Daniel LaLiberte Bill (BearHeart) Weinman 7456 Ben Laurie Francois Yergeau 7457 Paul J. Leach Mary Ellen Zurko 7458 Daniel DuBois Josh Cohen 7459 Ross Patterson 7461 Much of the content and presentation of the caching design is due to 7462 suggestions and comments from individuals including: Shel Kaphan, 7463 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 7465 Most of the specification of ranges is based on work originally done 7466 by Ari Luotonen and John Franks, with additional input from Steve 7467 Zilles. 7469 Thanks to the "cave men" of Palo Alto. You know who you are. 7471 Jim Gettys (the current editor of this document) wishes particularly 7472 to thank Roy Fielding, the previous editor of this document, along 7473 with John Klensin, Jeff Mogul, Paul Leach, Dave Kristol, Koen 7474 Holtman, John Franks, Josh Cohen, Alex Hopmann, Scott Lawrence, and 7475 Larry Masinter for their help. And thanks go particularly to Jeff 7476 Mogul and Scott Lawrence for performing the "MUST/MAY/SHOULD" audit. 7478 The Apache Group, Anselm Baird-Smith, author of Jigsaw, and Henrik 7479 Frystyk implemented RFC 2068 early, and we wish to thank them for the 7480 discovery of many of the problems that this document attempts to 7481 rectify. 7483 17 References 7485 [1]Alvestrand, H., "Tags for the Identification of Languages" RFC 7486 1766, UNINETT, March 1995. 7488 [2] Anklesaria, F., McCahill, M., Lindner, P., Johnson, D., Torrey, 7489 D., and B. Alberti. "The Internet Gopher Protocol (a distributed 7490 document search and retrieval protocol)", RFC 1436, University 7491 of Minnesota, March 1993. 7493 [3] Berners-Lee, T., "Universal Resource Identifiers in WWW," RFC 7494 1630, CERN, June 1994. 7496 [4] Berners-Lee, T., Masinter, L., and M. McCahill. "Uniform 7497 Resource Locators (URL)," RFC 1738, CERN, Xerox PARC, University 7498 of Minnesota, December 1994. 7500 [5] Berners-Lee, T. and D. Connolly. "Hypertext Markup Language - 7501 2.0," RFC 1866, MIT/LCS, November 1995. 7503 [6] Berners-Lee, T., Fielding, R. and H. Frystyk. "Hypertext 7504 Transfer Protocol -- HTTP/1.0," RFC 1945, MIT/LCS, UC Irvine, 7505 May 1996. 7507 [7] Freed, N., and N. Borenstein. "Multipurpose Internet Mail 7508 Extensions (MIME) Part One: Format of Internet Message Bodies." 7509 RFC 2045, Innosoft, First Virtual, November 1996. 7511 [8] Braden, R., "Requirements for Internet Hosts -- Communication 7512 Layers," STD 3, RFC 1123, IETF, October 1989. 7514 [9] D. H. Crocker, "Standard for The Format of ARPA Internet Text 7515 Messages," STD 11, RFC 822, UDEL, August 1982. 7517 [10]Davis, F., Kahle, B., Morris, H., Salem, J., Shen, T., Wang, R., 7518 Sui, J., and M. Grinbaum, "WAIS Interface Protocol Prototype 7519 Functional Specification." (v1.5), Thinking Machines 7520 Corporation, April 1990. 7522 [11]Fielding, R., "Relative Uniform Resource Locators," RFC 1808, UC 7523 Irvine, June 1995. 7525 [12]Horton, M., and R. Adams. "Standard for Interchange of USENET 7526 Messages," RFC 1036 (Obsoletes RFC 850), AT&T Bell Laboratories, 7527 Center for Seismic Studies, December 1987. 7529 [13]Kantor, B. and P. Lapsley. "Network News Transfer Protocol," RFC 7530 977, UC San Diego, UC Berkeley, February 1986. 7532 [14]Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part 7533 Three: Message Header Extensions for Non-ASCII Text", RFC 2047, 7534 University of Tennessee, November 1996. 7536 [15]Nebel, E., and L. Masinter. "Form-based File Upload in HTML," 7537 RFC 1867, Xerox Corporation, November 1995. 7539 [16]Postel, J., "Simple Mail Transfer Protocol," STD 10, RFC 821, 7540 USC/ISI, August 1982. 7542 [17]Postel, J., "Media Type Registration Procedure," RFC 1590, 7543 USC/ISI, November 1996. 7545 [18]Postel, J. and J. Reynolds. "File Transfer Protocol," STD 9, RFC 7546 959, USC/ISI, October 1985. 7548 [19]Reynolds, J. and J. Postel. "Assigned Numbers," STD 2, RFC 1700, 7549 USC/ISI, October 1994. 7551 [20]Sollins, K. and L. Masinter. "Functional Requirements for 7552 Uniform Resource Names," RFC 1737, MIT/LCS, Xerox Corporation, 7553 December 1994. 7555 [21]US-ASCII. Coded Character Set - 7-Bit American Standard Code for 7556 Information Interchange. Standard ANSI X3.4-1986, ANSI, 1986. 7558 [22]ISO-8859. International Standard -- Information Processing -- 7559 8-bit Single-Byte Coded Graphic Character Sets -- 7560 Part 1: Latin alphabet No. 1, ISO-8859-1:1987. 7561 Part 2: Latin alphabet No. 2, ISO-8859-2, 1987. 7562 Part 3: Latin alphabet No. 3, ISO-8859-3, 1988. 7563 Part 4: Latin alphabet No. 4, ISO-8859-4, 1988. 7564 Part 5: Latin/Cyrillic alphabet, ISO-8859-5, 1988. 7565 Part 6: Latin/Arabic alphabet, ISO-8859-6, 1987. 7566 Part 7: Latin/Greek alphabet, ISO-8859-7, 1987. 7567 Part 8: Latin/Hebrew alphabet, ISO-8859-8, 1988. 7568 Part 9: Latin alphabet No. 5, ISO-8859-9, 1990. 7570 [23]Meyers, J., and M. Rose. "The Content-MD5 Header Field," RFC 7571 1864, Carnegie Mellon, Dover Beach Consulting, October, 1995. 7573 [24]Carpenter, B. and Y. Rekhter. "Renumbering Needs Work," RFC 7574 1900, IAB, February 1996. 7576 [25]Deutsch, P., "GZIP file format specification version 4.3,." RFC 7577 1952, Aladdin Enterprises, May, 1996. 7579 [26]Venkata N. Padmanabhan, and Jeffrey C. Mogul. "Improving HTTP 7580 Latency", Computer Networks and ISDN Systems, v. 28, pp. 25-35, 7581 Dec. 1995. Slightly revised version of paper in Proc. 2nd 7582 International WWW Conference '94: Mosaic and the Web, Oct. 1994, 7583 which is available at 7584 http://www.ncsa.uiuc.edu/SDG/IT94/Proceedings/DDay/mogul/HTTPLat 7585 ency.html. 7587 [27]Joe Touch, John Heidemann, and Katia Obraczka. "Analysis of HTTP 7588 Performance", , 7589 ISI Research Report ISI/RR-98-463, (original report dated Aug. 7590 1996), USC/Information Sciences Institute, August 1998. 7592 [28]Mills, D., "Network Time Protocol (Version 3) Specification, 7593 Implementation and Analysis." RFC 1305, University of Delaware, 7594 March, 1992. 7596 [29]Deutsch, P., "DEFLATE Compressed Data Format Specification 7597 version 1.3." RFC 1951, Aladdin Enterprises, May 1996. 7599 [30]S. Spero, "Analysis of HTTP Performance Problems," 7600 http://sunsite.unc.edu/mdma-release/http-prob.html. 7602 [31]Deutsch, P. and J-L. Gailly. "ZLIB Compressed Data Format 7603 Specification version 3.3," RFC 1950, Aladdin Enterprises, Info- 7604 ZIP, May 1996. 7606 [32]Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P., 7607 Luotonen, A., Sink, E., and L. Stewart. "An Extension to HTTP: 7608 Digest Access Authentication," RFC 2069, January 1997. 7610 [33]Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Berners-Lee, 7611 T., "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, UC 7612 Irvine, Digital Equipment Corporation, M.I.T., January, 1997. 7614 [34]Bradner, S., "Key words for use in RFCs to Indicate Requirement 7615 Levels," RFC 2119, Harvard University, March 1997. 7617 [35]Troost, R., and Dorner, S., "Communicating Presentation 7618 Information in Internet Messages: The Content-Disposition 7619 Header," RFC 1806, New Century Systems, QUALCOMM, Inc., June 7620 1995. 7622 [36]Mogul, J.C., Fielding, R., Gettys, J, Frystyk, H., "Use and 7623 Interpretation of HTTP Version Numbers", RFC 2145, Digital 7624 Equipment Corporation, U.C. Irvine, M.I.T., May 1997.[jg639] 7626 [37]Palme, J, "Common Internet Message Headers," RFC 2076, Stockholm 7627 University, KTH, February, 1997[jg640]. 7629 [38]Yergeau, F., "UTF-8, a transformation format of Unicode and ISO- 7630 10646," RFC 2279 (obsoleted RFC 2044), Alis Technologies, 7631 January 1998. [jg641] 7633 [39]Nielsen, H.F., Gettys, J., Baird-Smith, A., Prud'hommeaux, E., 7634 Lie, H., and C. Lilley. "Network Performance Effects of 7635 HTTP/1.1, CSS1, and PNG," Proceedings of ACM SIGCOMM '97, Cannes 7636 France, September 1997.[jg642] 7638 [40]Freed, N., and N. Borenstein. "Multipurpose Internet Mail 7639 Extensions (MIME) Part Two: Media Types." RFC 2046, Innosoft, 7640 First Virtual, November 1996. [jg643] 7642 [41]Alvestrand, H. T., "IETF Policy on Character Sets and 7643 Languages," RFC 2277, BCP 18, UNINETT, January, 1998. [jg644] 7645 [42]Berners-Lee, T., Fielding, R., Masinter, L., "Uniform Resource 7646 Identifiers (URI): Generic Syntax and Semantics," RFC 2396, 7647 August, 1998.[jg645] 7649 [43]Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 7650 Leach, P., Luotonen, A., Sink, E., Stewart, L., "HTTP 7651 Authentication: Basic and Digest Access Authentication," Work in 7652 Progress, September, 1998.[jg646] 7654 [44]Luotonen, A., "Tunneling TCP based protocols through Web proxy 7655 servers," Work in Progress, February, 1998.[jg647] 7657 [45]Palme, J., Hopmann, A., "MIME E-mail Encapsulation of Aggregate 7658 Documents, such as HTML (MHTML)," RFC 2110, March 1997 7660 [46]Bradner, S., "The Internet Standards Process -- Revision 3," BCP 7661 9, RFC 2026, Harvard University, October, 1996. 7663 [47]Masinter, L., "Hyper Text Coffee Pot Control Protocol 7664 (HTCPCP/1.0)," RFC 2324, April, 1998. 7666 [48]Freed, N., Borenstein, N., "Multipurpose Internet Mail 7667 Extensions (MIME) Part Five: Conformance Criteria and Examples," 7668 RFC 2049, November, 1996. 7670 [49]Troost, R., Dorner, S., Moore, K., "Communicating Presentation 7671 Information in Internet Messages: The Content-Disposition Header 7672 Field," RFC 2183, August, 1997. 7674 18 Authors' Addresses 7676 Roy T. Fielding 7677 Department of Information and Computer Science 7678 University of California 7679 Irvine, CA 92697-3425, USA 7680 Fax: +1 (714) 824-1715 7681 Email: fielding@ics.uci.edu 7683 James Gettys 7684 World Wide Web Consortium 7685 MIT Laboratory for Computer Science 7686 545 Technology Square 7687 Cambridge, MA 02139, USA 7688 Fax: +1 (617) 258 8682 7689 Email: jg@w3.org 7691 Jeffrey C. Mogul 7692 Western Research Laboratory 7693 Compaq Computer Corporation 7694 250 University Avenue 7695 Palo Alto, California, 94305, USA 7696 Email: mogul@wrl.dec.com 7698 Henrik Frystyk Nielsen 7699 World Wide Web Consortium 7700 MIT Laboratory for Computer Science 7701 545 Technology Square 7702 Cambridge, MA 02139, USA 7703 Fax: +1 (617) 258 8682 7704 Email: frystyk@w3.org 7706 Larry Masinter 7707 Xerox PARC 7708 3333 Coyote Hill Road 7709 Palo Alto, CA 94034, USA 7710 Fax:+1 (415) 812-4333 7711 Email: masinter@parc.xerox.com 7713 Paul J. Leach 7714 Microsoft Corporation 7715 1 Microsoft Way 7716 Redmond, WA 98052, USA 7717 Email: paulle@microsoft.com 7719 Tim Berners-Lee 7720 Director, World Wide Web Consortium 7721 MIT Laboratory for Computer Science 7722 545 Technology Square 7723 Cambridge, MA 02139, USA 7724 Fax: +1 (617) 258 8682 7725 Email: timbl@w3.org 7727 19 Appendices 7729 19.1 Internet Media Type message/http and application/http 7731 In addition to defining the HTTP/1.1 protocol, this document serves 7732 as the specification for the Internet media type "message/http" and 7733 "application/http". The message/http type can be used to enclose a 7734 single HTTP request or response message, provided that it obeys the 7735 MIME restrictions for all "message" types regarding line length and 7736 encodings. The application/http type can be used to enclose a 7737 pipeline of one or more HTTP request or response messages (not 7738 intermixed). The following is to be registered with IANA [17]. 7740 Media Type name: message 7741 Media subtype name: http 7742 Required parameters: none 7743 Optional parameters: version, msgtype 7744 version: The HTTP-Version number of the enclosed message 7745 (e.g., "1.1"). If not present, the version can be 7746 determined from the first line of the body. 7747 msgtype: The message type -- "request" or "response". If not 7748 present, the type can be determined from the first 7749 line of the body. 7750 Encoding considerations: only "7bit", "8bit", or "binary" are 7751 permitted 7752 Security considerations: none 7754 Media Type name: application 7755 Media subtype name: http 7756 Required parameters: none 7757 Optional parameters: version, msgtype 7758 version: The HTTP-Version number of the enclosed messages 7759 (e.g., "1.1"). If not present, the version can be 7760 determined from the first line of the body. 7761 msgtype: The message type -- "request" or "response". If not 7762 present, the type can be determined from the first 7763 line of the body. 7764 Encoding considerations: HTTP messages enclosed by this type 7765 are in "binary" format; use of an appropriate 7766 Content-Transfer-Encoding is required when 7767 transmitted via E-mail. 7769 Security considerations: none 7771 19.2 Internet Media Type multipart/byteranges 7773 When an HTTP 206 (Partial Content) response message includes the 7774 content of multiple ranges (a response to a request for multiple non- 7775 overlapping ranges), these are transmitted as a multipart message- 7776 body. The media type for this purpose is called 7777 "multipart/byteranges". 7779 The multipart/byteranges media type includes two or more parts, each 7780 with its own Content-Type and Content-Range fields. The required 7781 boundary parameter specifies the boundary string used to separate 7782 each body-part. 7784 Media Type name: multipart 7785 Media subtype name: byteranges 7786 Required parameters: boundary 7787 Optional parameters: none 7788 Encoding considerations: only "7bit", "8bit", or "binary" are 7789 permitted 7790 Security considerations: none 7792 For example: 7794 HTTP/1.1 206 Partial Content 7795 Date: Wed, 15 Nov 1995 06:25:24 GMT 7796 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 7797 Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 7799 --THIS_STRING_SEPARATES 7800 Content-type: application/pdf 7801 Content-range: bytes 500-999/8000 7803 ...the first range... 7804 --THIS_STRING_SEPARATES 7805 Content-type: application/pdf 7806 Content-range: bytes 7000-7999/8000 7808 ...the second range 7809 --THIS_STRING_SEPARATES-- 7811 Notes: 7813 1) Additional CRLFs may precede the first boundary string in 7814 the entity. 7816 2) Although RFC 2046 [40] permits the boundary string to be 7817 quoted, some existing implementations handle a quoted boundary 7818 string incorrectly. 7820 3) A number of browsers and servers were coded to an early 7821 draft of the byteranges specification to use a media type of 7822 multipart/x-byteranges, which is almost, but not quite 7823 compatible with the version documented in HTTP/1.1. 7825 19.3 Tolerant Applications 7827 Although this document specifies the requirements for the generation 7828 of HTTP/1.1 messages, not all applications will be correct in their 7829 implementation. We therefore recommend that operational applications 7830 be tolerant of deviations whenever those deviations can be 7831 interpreted unambiguously. 7833 Clients SHOULD be tolerant in parsing the Status-Line and servers 7834 tolerant when parsing the Request-Line. In particular, they SHOULD 7835 accept any amount of SP or HT characters between fields, even though 7836 only a single SP is required. 7838 The line terminator for message-header fields is the sequence CRLF. 7839 However, we recommend that applications, when parsing such headers, 7840 recognize a single LF as a line terminator and ignore the leading CR. 7842 The character set of an entity-body SHOULD be labeled as the lowest 7843 common denominator of the character codes used within that body, with 7844 the exception that not labeling the entity is preferred over labeling 7845 the entity with the labels US-ASCII or ISO-8859-1. See section 3.7.1 7846 and 3.4.1. 7848 Additional rules for requirements on parsing and encoding of dates 7849 and other potential problems with date encodings include: 7851 . HTTP/1.1 clients and caches SHOULD assume that an RFC-850 date 7852 which appears to be more than 50 years in the future is in fact 7853 in the past (this helps solve the "year 2000" problem). 7855 . An HTTP/1.1 implementation MAY internally represent a parsed 7856 Expires date as earlier than the proper value, but MUST NOT 7857 internally represent a parsed Expires date as later than the 7858 proper value. 7860 . All expiration-related calculations MUST be done in GMT. The 7861 local time zone MUST NOT influence the calculation or 7862 comparison of an age or expiration time. 7864 . If an HTTP header incorrectly carries a date value with a time 7865 zone other than GMT, it MUST be converted into GMT using the 7866 most conservative possible conversion. 7868 19.4 Differences Between HTTP Entities and RFC 2045 Entities 7870 HTTP/1.1 uses many of the constructs defined for Internet Mail (RFC 7871 822 [9]) and the Multipurpose Internet Mail Extensions (MIME [7]) to 7872 allow entities to be transmitted in an open variety of 7873 representations and with extensible mechanisms. However, RFC 2045 7874 discusses mail, and HTTP has a few features that are different from 7875 those described in RFC 2045. These differences were carefully chosen 7876 to optimize performance over binary connections, to allow greater 7877 freedom in the use of new media types, to make date comparisons 7878 easier, and to acknowledge the practice of some early HTTP servers 7879 and clients. 7881 This appendix describes specific areas where HTTP differs from RFC 7882 2045. Proxies and gateways to strict MIME environments SHOULD be 7883 aware of these differences and provide the appropriate conversions 7884 where necessary. Proxies and gateways from MIME environments to HTTP 7885 also need to be aware of the differences because some conversions 7886 might be required. 7888 19.4.1 MIME-Version 7890 HTTP is not a MIME-compliant protocol. However, HTTP/1.1 messages MAY 7891 include a single MIME-Version general-header field to indicate what 7892 version of the MIME protocol was used to construct the message. Use 7893 of the MIME-Version header field indicates that the message is in 7894 full compliance with the MIME protocol (as defined in RFC 2045[7]). 7895 Proxies/gateways are responsible for ensuring full compliance (where 7896 possible) when exporting HTTP messages to strict MIME environments. 7897 MIME-Version = "MIME-Version" ":" 1*DIGIT "." 1*DIGIT 7899 MIME version "1.0" is the default for use in HTTP/1.1. However, 7900 HTTP/1.1 message parsing and semantics are defined by this document 7901 and not the MIME specification. 7903 19.4.2 Conversion to Canonical Form 7905 RFC 2045 [7] requires that an Internet mail entity be converted to 7906 canonical form prior to being transferred, as described in section 4 7907 of RFC 2049 [48]. Section 3.7.1 of this document describes the forms 7908 allowed for subtypes of the "text" media type when transmitted over 7909 HTTP. RFC 2046 requires that content with a type of "text" represent 7910 line breaks as CRLF and forbids the use of CR or LF outside of line 7911 break sequences. HTTP allows CRLF, bare CR, and bare LF to indicate a 7912 line break within text content when a message is transmitted over 7913 HTTP. 7915 Where it is possible, a proxy or gateway from HTTP to a strict MIME 7916 environment SHOULD translate all line breaks within the text media 7917 types described in section 3.7.1 of this document to the RFC 2049 7918 canonical form of CRLF. Note, however, that this might be complicated 7919 by the presence of a Content-Encoding and by the fact that HTTP 7920 allows the use of some character sets which do not use octets 13 and 7921 10 to represent CR and LF, as is the case for some multi-byte 7922 character sets. 7924 Implementors should note that conversion will break any cryptographic 7925 checksums applied to the original content unless the original content 7926 is already in canonical form. Therefore, the canonical form is 7927 recommended for any content that uses such checksums in HTTP. 7929 19.4.3 Conversion of Date Formats 7931 HTTP/1.1 uses a restricted set of date formats (section 3.3.1) to 7932 simplify the process of date comparison. Proxies and gateways from 7933 other protocols SHOULD ensure that any Date header field present in a 7934 message conforms to one of the HTTP/1.1 formats and rewrite the date 7935 if necessary. 7937 19.4.4 Introduction of Content-Encoding 7939 RFC 2045 does not include any concept equivalent to HTTP/1.1's 7940 Content-Encoding header field. Since this acts as a modifier on the 7941 media type, proxies and gateways from HTTP to MIME-compliant 7942 protocols MUST either change the value of the Content-Type header 7943 field or decode the entity-body before forwarding the message. (Some 7944 experimental applications of Content-Type for Internet mail have used 7945 a media-type parameter of ";conversions=" to perform 7946 a function equivalent to Content-Encoding. However, this parameter is 7947 not part of RFC 2045.) 7949 19.4.5 No Content-Transfer-Encoding 7951 HTTP does not use the Content-Transfer-Encoding (CTE) field of RFC 7952 2045. Proxies and gateways from MIME-compliant protocols to HTTP MUST 7953 remove any non-identity CTE ("quoted-printable" or "base64") encoding 7954 prior to delivering the response message to an HTTP client. 7956 Proxies and gateways from HTTP to MIME-compliant protocols are 7957 responsible for ensuring that the message is in the correct format 7958 and encoding for safe transport on that protocol, where "safe 7959 transport" is defined by the limitations of the protocol being used. 7960 Such a proxy or gateway SHOULD label the data with an appropriate 7961 Content-Transfer-Encoding if doing so will improve the likelihood of 7962 safe transport over the destination protocol. 7964 19.4.6 Introduction of Transfer-Encoding 7966 HTTP/1.1 introduces the Transfer-Encoding header field (section 7967 14.41). Proxies/gateways MUST remove any transfer-coding prior to 7968 forwarding a message via a MIME-compliant protocol. 7970 A process for decoding the "chunked" transfer-coding (section 3.6) 7971 can be represented in pseudo-code as: 7973 length := 0 7974 read chunk-size, chunk-extension (if any) and CRLF 7975 while (chunk-size > 0) { 7976 read chunk-data and CRLF 7977 append chunk-data to entity-body 7978 length := length + chunk-size 7979 read chunk-size and CRLF 7980 } 7981 read entity-header 7982 while (entity-header not empty) { 7983 append entity-header to existing header fields 7984 read entity-header 7985 } 7986 Content-Length := length 7987 Remove "chunked" from Transfer-Encoding 7989 19.4.7 MHTML and Line Length Limitations 7991 HTTP implementations which share code with MHTML [45] implementations 7992 need to be aware of MIME line length limitations. Since HTTP does not 7993 have this limitation, HTTP does not fold long lines. MHTML messages 7994 being transported by HTTP follow all conventions of MHTML, including 7995 line length limitations and folding, canonicalization, etc., since 7996 HTTP transports all message-bodies as payload (see section 3.7.2) and 7997 does not interpret the content or any MIME header lines that might be 7998 contained therein. 8000 19.5 Additional Features 8002 RFC 1945 and RFC 2068 document protocol elements used by some 8003 existing HTTP implementations, but not consistently and correctly 8004 across most HTTP/1.1 applications. Implementors are advised to be 8005 aware of these features, but cannot rely upon their presence in, or 8006 interoperability with, other HTTP/1.1 applications. Some of these 8007 describe proposed experimental features, and some describe features 8008 that experimental deployment found lacking that are now addressed in 8009 the base HTTP/1.1 specification. 8011 A number of other headers, such as Content-Disposition and Title, 8012 from SMTP and MIME are also often implemented (see RFC 2076 [37]). 8014 19.5.1 Content-Disposition 8016 The Content-Disposition response-header field has been proposed as a 8017 means for the origin server to suggest a default filename if the user 8018 requests that the content is saved to a file. This usage is derived 8019 from the definition of Content-Disposition in RFC 1806 [35]. 8021 content-disposition = "Content-Disposition" ":" 8022 disposition-type *( ";" disposition-parm ) 8023 disposition-type = "attachment" | disp-extension-token 8024 disposition-parm = filename-parm | disp-extension-parm 8025 filename-parm = "filename" "=" quoted-string 8026 disp-extension-token = token 8027 disp-extension-parm = token "=" ( token | quoted-string ) 8029 An example is 8031 Content-Disposition: attachment; filename="fname.ext" 8033 The receiving user agent SHOULD NOT respect any directory path 8034 information present in the filename-parm parameter, which is the only 8035 parameter believed to apply to HTTP implementations at this time. The 8036 filename SHOULD be treated as a terminal component only. 8038 If this header is used in a response with the application/octet- 8039 stream content-type, the implied suggestion is that the user agent 8040 should not display the response, but directly enter a `save response 8041 as...' dialog. 8043 See section 15.5 for Content-Disposition security issues. 8045 19.6 Compatibility with Previous Versions 8047 It is beyond the scope of a protocol specification to mandate 8048 compliance with previous versions. HTTP/1.1 was deliberately 8049 designed, however, to make supporting previous versions easy. It is 8050 worth noting that, at the time of composing this specification 8051 (1996), we would expect commercial HTTP/1.1 servers to: 8053 . recognize the format of the Request-Line for HTTP/0.9, 1.0, and 8054 1.1 requests; 8056 . understand any valid request in the format of HTTP/0.9, 1.0, or 8057 1.1; 8059 . respond appropriately with a message in the same major version 8060 used by the client. 8062 And we would expect HTTP/1.1 clients to: 8064 . recognize the format of the Status-Line for HTTP/1.0 and 1.1 8065 responses; 8067 . understand any valid response in the format of HTTP/0.9, 1.0, 8068 or 1.1. 8070 For most implementations of HTTP/1.0, each connection is established 8071 by the client prior to the request and closed by the server after 8072 sending the response. Some implementations implement the Keep-Alive 8073 version of persistent connections described in section 19.7.1 of RFC 8074 2068 [33]. 8076 19.6.1 Changes from HTTP/1.0 8078 This section summarizes major differences between versions HTTP/1.0 8079 and HTTP/1.1. 8081 19.6.1.1 Changes to Simplify Multi-homed Web Servers and Conserve IP 8082 Addresses 8084 The requirements that clients and servers support the Host request- 8085 header, report an error if the Host request-header (section 14.23) is 8086 missing from an HTTP/1.1 request, and accept absolute URIs (section 8087 5.1.2) are among the most important changes defined by this 8088 specification. 8090 Older HTTP/1.0 clients assumed a one-to-one relationship of IP 8091 addresses and servers; there was no other established mechanism for 8092 distinguishing the intended server of a request than the IP address 8093 to which that request was directed. The changes outlined above will 8094 allow the Internet, once older HTTP clients are no longer common, to 8095 support multiple Web sites from a single IP address, greatly 8096 simplifying large operational Web servers, where allocation of many 8097 IP addresses to a single host has created serious problems. The 8098 Internet will also be able to recover the IP addresses that have been 8099 allocated for the sole purpose of allowing special-purpose domain 8100 names to be used in root-level HTTP URLs. Given the rate of growth of 8101 the Web, and the number of servers already deployed, it is extremely 8102 important that all implementations of HTTP (including updates to 8103 existing HTTP/1.0 applications) correctly implement these 8104 requirements: 8106 . Both clients and servers MUST support the Host request-header. 8108 . A client that sends an HTTP/1.1 request MUST send a Host 8109 header. 8111 . Servers MUST report a 400 (Bad Request) error if an HTTP/1.1 8112 request does not include a Host request-header. 8114 . Servers MUST accept absolute URIs. 8116 19.6.2 Compatibility with HTTP/1.0 Persistent Connections 8118 Some clients and servers might wish to be compatible with some 8119 previous implementations of persistent connections in HTTP/1.0 8120 clients and servers. Persistent connections in HTTP/1.0 are 8121 explicitly negotiated as they are not the default behavior. HTTP/1.0 8122 experimental implementations of persistent connections are faulty, 8123 and the new facilities in HTTP/1.1 are designed to rectify these 8124 problems. The problem was that some existing 1.0 clients may be 8125 sending Keep-Alive to a proxy server that doesn't understand 8126 Connection, which would then erroneously forward it to the next 8127 inbound server, which would establish the Keep-Alive connection and 8128 result in a hung HTTP/1.0 proxy waiting for the close on the 8129 response. The result is that HTTP/1.0 clients must be prevented from 8130 using Keep-Alive when talking to proxies. 8132 However, talking to proxies is the most important use of persistent 8133 connections, so that prohibition is clearly unacceptable. Therefore, 8134 we need some other mechanism for indicating a persistent connection 8135 is desired, which is safe to use even when talking to an old proxy 8136 that ignores Connection. Persistent connections are the default for 8137 HTTP/1.1 messages; we introduce a new keyword (Connection: close) for 8138 declaring non-persistence. See section 14.10. 8140 The original HTTP/1.0 form of persistent connections (the Connection: 8141 Keep-Alive and Keep-Alive header) is documented in RFC 2068. [33] 8143 19.6.3 Changes from RFC 2068 8145 This specification has been carefully audited to correct and 8146 disambiguate key word usage; RFC 2068 had many problems in respect to 8147 the conventions laid out in RFC 2119 [34]. 8149 Clarified which error code should be used for inbound server failures 8150 (e.g. DNS failures). (Section 10.5.5) 8152 CREATE had a race that required an Etag be sent when a resource is 8153 first created. (Section 10.2.2). 8155 Content-Base was deleted from the specification: it was not 8156 implemented widely, and there is no simple, safe way to introduce it 8157 without a robust extension mechanism. In addition, it is used in a 8158 similar, but not identical fashion in MHTML [45]. 8160 Transfer-coding and message lengths all interact in ways that 8161 required fixing exactly when chunked encoding is used (to allow for 8162 transfer encoding that may not be self delimiting); it was important 8163 to straighten out exactly how message lengths are computed. (Sections 8164 3.6, 4.4, 7.2.2, 13.5.2, 14.13, 14.16) 8166 A content-coding of "identity" was introduced, to solve problems 8167 discovered in caching. (section 3.5) 8169 Quality Values of zero should indicate that "I don't want something" 8170 to allow clients to refuse a representation. (Section 3.9) 8172 The use and interpretation of HTTP version numbers has been clarified 8173 by RFC 2145. Require proxies to upgrade requests to highest protocol 8174 version they support to deal with problems discovered in HTTP/1.0 8175 implementations (Section 3.1) 8176 Charset wildcarding is introduced to avoid explosion of character set 8177 names in accept headers. (Section 14.2) 8179 A case was missed in the Cache-Control model of HTTP/1.1; s-maxage 8180 was introduced to add this missing case. (Sections 13.4, 14.8, 14.9, 8181 14.9.3) 8183 The Cache-Control: max-age directive was not properly defined for 8184 responses. (Section 14.9.3) 8186 There are situations where a server (especially a proxy) does not 8187 know the full length of a response but is capable of serving a 8188 byterange request. We therefore need a mechanism to allow byteranges 8189 with a content-range not indicating the full length of the message. 8190 (Section 14.16) 8192 Range request responses would become very verbose if all meta-data 8193 were always returned; by allowing the server to only send needed 8194 headers in a 206 response, this problem can be avoided. (Section 8195 10.2.7, 13.5.3, and 14.27) 8197 Fix problem with unsatisfiable range requests; there are two cases: 8198 syntactic problems, and range doesn't exist in the document. The 416 8199 status code was needed to resolve this ambiguity needed to indicate 8200 an error for a byte range request that falls outside of the actual 8201 contents of a document. (Section 10.4.17, 14.16) 8203 Rewrite of message transmission requirements to make it much harder 8204 for implementors to get it wrong, as the consequences of errors here 8205 can have significant impact on the Internet, and to deal with the 8206 following problems: 8208 1. Changing "HTTP/1.1 or later" to "HTTP/1.1", in contexts where 8209 this was incorrectly placing a requirement on the behavior of an 8210 implementation of a future version of HTTP/1.x 8212 2. Made it clear that user-agents should retry requests, not 8213 "clients" in general. 8215 3. Converted requirements for clients to ignore unexpected 100 8216 (Continue) responses, and for proxies to forward 100 responses, 8217 into a general requirement for 1xx responses. 8219 4. Modified some TCP-specific language, to make it clearer that 8220 non-TCP transports are possible for HTTP. 8222 5. Require that the origin server MUST NOT wait for the request 8223 body before it sends a required 100 (Continue) response. 8225 6. 8226 Allow, rather than require, a server to omit 100 (Continue) if 8227 it has already seen some of the request body. 8229 7. 8230 Allow servers to defend against denial-of-service attacks and 8231 broken clients. 8233 This change adds the Expect header and 417 status code. The message 8234 transmission requirements fixes are in sections 8.2, 10.4.18, 8235 8.1.2.2, 13.11, and 14.20. 8237 Proxies should be able to add Content-Length when appropriate. 8238 (Section 13.5.2) 8240 Clean up confusion between 403 and 404 responses. (Section 10.4.4, 8241 10.4.5, and 10.4.11) 8243 Warnings could be cached incorrectly, or not updated appropriately. 8244 (Section 13.1.2, 13.2.4, 13.5.2, 13.5.3, 14.9.3, and 14.46) Warning 8245 also needed to be a general header, as PUT or other methods may have 8246 need for it in requests. 8248 Transfer-coding had significant problems, particularly with 8249 interactions with chunked encoding. The solution is that transfer- 8250 codings become as full fledged as content-codings. This involves 8251 adding an IANA registry for transfer-codings (separate from content 8252 codings), a new header field (TE) and enabling trailer headers in the 8253 future. Transfer encoding is a major performance benefit, so it was 8254 worth fixing [39]. TE also solves another, obscure, downward 8255 interoperability problem that could have occurred due to interactions 8256 between authentication trailers, chunked encoding and HTTP/1.0 8257 clients.(Section 3.6, 3.6.1, and 14.39) 8259 The PATCH, LINK, UNLINK methods were defined but not commonly 8260 implemented in previous versions of this specification. See RFC 2068 8261 [33]. 8263 The Alternates, Content-Version, Derived-From, Link, URI, Public and 8264 Content-Base header fields were defined in previous versions of this 8265 specification, but not commonly implemented. See RFC 2068 [33]. 8267 19.7 Notes to the RFC Editor and IANA 8269 This section of the document should be DELETED! It calls for the RFC 8270 editor and IANA to take some actions before the draft becomes a Draft 8271 Standard. After those actions are taken, please delete this section 8272 of the specification. 8274 19.7.1 Transfer-coding Values 8276 This document defines a new class of registry for its transfer-coding 8277 values as part of the solution to solve problems discovered in RFC 8278 2068 with the caching of transfer encoded documents. Initially, the 8279 registry should contain the following tokens: "chunked" (section 8280 3.6.1), "gzip" (section 3.5), "compress" (section 3.5), and 8281 "deflate" (section 3.5) and the special keyword "trailers" (section 8282 14.39). The registry should note that "specifications of the 8283 transfer-coding algorithms needed to implement a new value should be 8284 publicly available and adequate for independent implementation, and 8285 conform to the purpose of content coding defined RFC XXXX." where RFC 8286 XXXX is the number assigned to this document. 8288 19.7.2 Definition of application/http 8290 Appendix 19.1 defines Internet Media Type application/http in 8291 addition to the Internet Media Type message/http defined by RFC 2068. 8293 19.7.3 Addition of "identity" content-coding to content-coding Registry 8295 The "identity" content coding is added to the content-coding registry 8296 by this document (section 3.5) to solve a problem discovered in RFC 8297 2068. 8299 20 Full Copyright Statement 8301 Copyright (C) The Internet Society (1998). All Rights Reserved. 8303 This document and translations of it may be copied and furnished to 8304 others, and derivative works that comment on or otherwise explain it 8305 or assist in its implementation may be prepared, copied, published 8306 and distributed, in whole or in part, without restriction of any 8307 kind, provided that the above copyright notice and this paragraph are 8308 included on all such copies and derivative works. However, this 8309 document itself may not be modified in any way, such as by removing 8310 the copyright notice or references to the Internet Society or other 8311 Internet organizations, except as needed for the purpose of 8312 developing Internet standards in which case the procedures for 8313 copyrights defined in the Internet Standards process must be 8314 followed, or as required to translate it into languages other than 8315 English. 8317 The limited permissions granted above are perpetual and will not be 8318 revoked by the Internet Society or its successors or assigns. 8320 This document and the information contained herein is provided on an 8321 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 8322 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 8323 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 8324 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 8325 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 8327 21 Index 8329 While some care was taken producing this index, there is no guarantee 8330 that all occurrences of an index term have been entered into the 8331 index. Bold face italic is used for the definition of a term. 8333 "literal", 14 411, 32, 38, 63 8334 #rule, 15 412, 38, 63, 118, 120, 122 8335 (rule1 rule2), 14 413, 38, 63 8336 *rule, 15 414, 19, 38, 63 8337 ; comment, 15 415, 38, 64, 108 8338 [rule], 15 416, 38, 64, 112, 113, 126, 157 8339 <">, 16 417, 38, 64, 115, 158 8340 100, 38, 44, 45, 46, 53, 90, 114, 4xx Client Error Status Codes, 60 8341 115 500, 38, 64, 65, 114 8342 101, 38, 53, 114, 131 501, 24, 34, 38, 51, 65 8343 1xx Informational Status Codes, 502, 38, 65 8344 53 503, 38, 65, 114, 128 8345 200, 38, 48, 50, 51, 52, 54, 55, 504, 38, 65, 104, 105 8346 56, 59, 84, 89, 104, 113, 119, 505, 38, 65 8347 122, 127 5xx Server Error Status Codes, 64 8348 201, 38, 50, 51, 54, 123 abs_path, 19, 34, 35 8349 202, 38, 52, 54, 55 absoluteURI, 19, 34, 35, 36, 109, 8350 203, 38, 55, 84 123, 128 8351 204, 31, 32, 38, 50, 51, 52, 55 Accept, 25, 36, 67, 71, 91, 92, 8352 205, 38, 55 94, 95, 138 8353 206, 38, 56, 84, 86, 89, 112, acceptable-ranges, 96 8354 122, 126, 127, 149, 157 Accept-Charset, 36, 67, 93, 94 8355 2xx, 121 Accept-Encoding, 22, 23, 36, 67, 8356 2xx Successful Status Codes, 54 94, 95 8357 300, 38, 57, 68, 84 accept-extension, 92 8358 301, 38, 51, 57, 84, 131 Accept-Language, 28, 36, 67, 95, 8359 302, 38, 57, 58, 59, 84, 131 96, 135, 138, 139 8360 303, 38, 50, 58, 131 accept-params, 92, 129 8361 304, 31, 32, 38, 58, 59, 70, 78, Accept-Ranges, 39, 96 8362 82, 86, 88, 104, 119, 120, 121, Access Authentication, 66 8363 127 Basic and Digest. See [43] 8364 305, 38, 59, 70, 131 Acknowledgements, 142 8365 306, 59 age, 11 8366 307, 38, 58, 60, 84 Age, 39, 74, 75, 76, 97 8367 3xx Redirection Status Codes, 56 age-value, 97 8368 400, 32, 36, 38, 39, 60, 117, 155 Allow, 34, 39, 48, 61, 97 8369 401, 38, 60, 62, 98, 136 ALPHA, 14, 16 8370 402, 38, 61 Alternates. See RFC 2068 8371 403, 38, 61, 158 ANSI X3.4-1986, 16, 144 8372 404, 38, 61, 63, 158 asctime-date, 20 8373 405, 34, 38, 61, 97 attribute, 23 8374 406, 38, 61, 62, 68, 92, 94 authority, 19, 34, 35 8375 407, 38, 62, 124 Authorization, 36, 60, 61, 84, 8376 408, 38, 62 98, 100, 125 8377 409, 38, 62 Backus-Naur Form, 14 8378 410, 38, 62, 63, 84 Basic Authentication. See [43] 8379 BCP 18, 146 cache-extension, 99 8380 BCP 9, 1, 146 extensions, 106 8381 byte-content-range-spec, 111, 112 max-age, 73, 76, 77, 84, 99, 8382 byte-range, 125 101, 102, 103, 104, 105, 116, 8383 byte-range-resp-spec, 111, 112 157 8384 byte-range-set, 125, 126 max-stale, 71, 72, 99, 102, 103, 8385 byte-range-spec, 64, 113, 125, 104 8386 126 min-fresh, 99, 102 8387 byte-ranges-specifier, 125 must-revalidate, 98, 99, 103, 8388 bytes, 96 104, 105 8389 bytes-unit, 29 no-cache, 70, 78, 99, 100, 102, 8390 cachable, 11 103, 104, 124 8391 cache, 11 no-store, 70, 99, 101 8392 Cache no-transform, 99, 105, 108 8393 cachability of responses, 83 only-if-cached, 99, 104 8394 calculating the age of a private, 84, 99, 100, 102, 106 8395 response, 74 proxy-revalidate, 84, 99, 105 8396 combining byte ranges, 87 public, 71, 84, 98, 99, 100, 8397 byte-range-spec, 64, 113, 125, 8398 combining headers, 86 101, 105 8399 combining negotiated responses, s-maxage, 76, 84, 98, 99, 102, 8400 87 157 8401 constructing responses, 84 cache-directive, 99, 106, 124 8402 correctness, 69 cache-request-directive, 70, 99 8403 disambiguating expiration Changes from HTTP/1.0. See RFC 8404 values, 77 1945 and RFC 2068 8405 disambiguating multiple Host requirement, 155 8406 responses, 77 CHAR, 16 8407 entity tags used as cache charset, 21, 93 8408 validators, 79 chunk, 24 8409 entry validation, 78 chunk-data, 24 8410 errors or incomplete responses, chunked, 129, 130 8411 89 Chunked-Body, 24 8412 expiration calculation, 76 chunk-extension, 24 8413 explicit expiration time, 73 chunk-ext-name, 24 8414 GET and HEAD cannot affect chunk-ext-val, 24 8415 caching, 89 chunk-size, 24 8416 heuristic expiration, 74 client, 10 8417 history list behavior, 91 codings, 94 8418 invalidation cannot be complete, comment, 17, 132, 133 8419 89 Compatibility 8420 Last-Modified values used as missing charset, 22 8421 validators, 79 multipart/x-byteranges, 150 8422 mechanisms, 71 Compatibility with previous HTTP 8423 replacement of cached responses, versions, 154 8424 90 CONNECT, 34, 35. See [44]. 8425 shared and non-shared, 88 connection, 9 8426 Warnings, 70 Connection, 33, 42, 43, 84, 85, 8427 weak and strong cache 106, 107, 129, 131, 156 8428 validators, 79 close, 42, 107, 156 8429 write-through mandatory, 90 Keep-Alive, 156. See RFC 2068 8430 Cache-Control, 33, 50, 56, 57, connection-token, 107 8431 59, 71, 72, 73, 76, 77, 78, 83, Content Codings 8432 84, 85, 89, 98, 99, 100, 102, compress, 22 8433 103, 104, 107, 116, 124 deflate, 23 8434 gzip, 22 Content-Transfer-Encoding, 152 8435 identity, 23 date formats, 152 8436 content negotiation, 10 MIME-Version, 151 8437 Content Negotiation, 66 Transfer-Encoding, 152 8438 Content-Base, 156. See RFC 2068 Digest Authentication, 85. 8439 content-cncoding, 108 [43] 8440 content-coding, 22, 23, 24, 26, DIGIT, 14, 15, 16, 18, 20, 28, 8441 66, 94, 95, 108, 130, 136, 158 123, 151 8442 identity, 156 disp-extension-token, 154 8443 new tokens SHOULD be registered disposition-parm, 154 8444 with IANA, 23 disposition-type, 154 8445 qvalues used with, 95 DNS, 139, 140, 156 8446 content-disposition, 154 HTTP applications MUST obey TTL 8447 Content-Disposition, 140, 146, information, 140 8448 153, 154 downstream, 12 8449 Content-Encoding, 22, 23, 39, 40, End-to-end headers, 84 8450 85, 107, 108, 110, 111, 136, entity, 9 8451 151, 152 Entity, 39 8452 Content-Language, 28, 39, 108, Entity body, 40 8453 109, 135 Entity Tags, 28, 79 8454 Content-Length, 31, 32, 33, 39, entity-body, 40 8455 44, 48, 50, 56, 63, 86, 89, 109, entity-header, 33, 37, 39 8456 112, 130, 153, 158 Entity-header fields, 39 8457 Content-Location, 39, 56, 59, 85, entity-length, 40, 86 8458 88, 90, 109, 110, 123, 140 entity-tag, 28, 120, 121 8459 Content-MD5, 39, 50, 85, 110, Etag, 156 8460 111, 145 ETag, 28, 39, 50, 54, 56, 59, 79, 8461 Content-Range, 56, 84, 111 85, 86, 88, 114, 115, 120 8462 content-range-spec, 111 Expect, 36, 44, 45, 46, 53, 64, 8463 Content-Transfer-Encoding, 24, 115, 158 8464 111, 152 expectation, 115 8465 Content-Type, 22, 25, 40, 48, 52, expectation-extension, 115 8466 54, 56, 57, 61, 62, 85, 107, expect-params, 115 8467 112, 113, 136, 149, 152 Expires, 40, 50, 56, 57, 59, 73, 8468 Content-Version. See RFC 2068 76, 84, 85, 101, 102, 105, 114, 8469 CR, 16, 26, 33, 37, 38, 150, 151, 115, 116, 150 8470 152 explicit expiration time, 11 8471 CRLF, 14, 16, 24, 26, 29, 30, 33, extension-code, 38 8472 37, 111, 150, 151 extension-header, 40 8473 ctext, 17 extension-pragma, 124 8474 CTL, 16 field-content, 30 8475 Date, 33, 56, 58, 59, 74, 77, 78, field-name, 30 8476 81, 83, 87, 88, 90, 102, 113, field-value, 30 8477 114, 116, 123, 136, 152 filename-parm, 154 8478 date1, 20 first-byte-pos, 64, 112, 113, 8479 date2, 20 125, 126 8480 date3, 20 first-hand, 11 8481 DELETE, 34, 47, 48, 52, 90 fresh, 12 8482 delta-seconds, 21, 128 freshness lifetime, 12 8483 Derived-From. See RFC 2068 freshness_lifetime, 76 8484 Differences between MIME and From, 36, 43, 116, 117, 137, 138 8485 HTTP, 151 gateway, 11 8486 canonical form, 151 General Header Fields, 33 8487 Content-Encoding, 152 general-header, 33, 37 8489 generic-message, 29 Larry Masinter, 147 8490 GET, 19, 34, 35, 47, 48, 49, 54, last-byte-pos, 112, 125, 126 8491 56, 57, 58, 59, 60, 63, 78, 80, last-chunk, 24 8492 81, 89, 90, 97, 109, 113, 118, Last-Modified, 12, 40, 50, 56, 8493 119, 120, 121, 127, 138 74, 77, 79, 80, 81, 82, 83, 85, 8494 HEAD, 31, 32, 34, 47, 48, 49, 50, 86, 114, 119, 121, 122, 123 8495 54, 56, 57, 58, 60, 61, 64, 89, LF, 16, 26, 33, 37, 38, 150, 151, 8496 90, 97, 109, 113, 120 152 8497 Headers lifetime, 12, 74, 76, 77, 97, 8498 end-to-end, 84, 85, 86, 107, 115 102, 136 8499 hop-by-hop, 12, Link. See RFC 2068 8500 non-modifiable headers, 85 LINK. See RFC 2068 8501 Henrik Frystyk Nielsen, 147 LOALPHA, 16 8502 heuristic expiration time, 11 Location, 39, 50, 54, 57, 58, 59, 8503 HEX, 16, 20, 24 60, 90, 123, 140 8504 Hop-by-hop headers, 84, 85 LWS, 14, 16, 30 8505 host, 19, 133, 134 Max-Forwards, 36, 49, 52, 123, 8506 Host, 35, 36, 47, 117, 155 124 8507 HT, 14, 16, 17, 30, 150 MAY, 9 8508 http_URL, 19 media type, 16, 22, 26, 32, 40, 8509 HTTP-date, 20, 113, 114, 116, 54, 57, 61, 66, 92, 93, 105, 8510 119, 121, 122, 128, 134 107, 109, 113, 148, 149, 150, 8511 HTTP-message, 29 151, 152 8512 HTTP-Version, 18, 33, 37 Media Types, 25 8513 IANA, 21, 22, 24, 26, 28, 92, 148 media-range, 91 8514 identity, 23, 94, 95, 108, 156 media-type, 25, 26, 107, 110, 136 8515 If-Match, 28, 36, 49, 82, 118, message, 9 8516 119, 120, 121, 127 Message Body, 31 8517 If-Modified-Since, 36, 49, 80, Message Headers, 30 8518 82, 119, 120, 121, 122, 127 Message Length, 31 8519 If-None-Match, 28, 36, 49, 82, Message Transmission 8520 88, 119, 120, 121, 122, 127 Requirements, 44 8521 If-Range, 28, 36, 49, 56, 64, 82, Message Types, 29 8522 113, 121, 122, 127 message-body, 29, 31, 33, 37, 40 8523 If-Unmodified-Since, 36, 49, 80, message-header, 29, 30, 40 8524 82, 120, 121, 122, 127 Method, 33, 34, 97 8525 If-Unmodified-Since, 122 Method Definitions, 47 8526 implied *LWS, 15 Methods 8527 inbound, 12 Idempotent, 48 8528 instance-length, 111, 112 Safe and Idempotent, 47 8529 ISO-10646, 146 MIME, 8, 9, 12, 21, 24, 26, 27, 8530 ISO-2022, 21 109, 110, 111, 142, 144, 146, 8531 ISO-3166, 28 151, 152, 153 8532 ISO-639, 28 multipart, 26 8533 ISO-8859, 145 MIME-Version, 151 8534 ISO-8859-1, 16, 22, 26, 93, 94, month, 21 8535 135, 150 multipart/byteranges, 27, 32, 56, 8536 James Gettys, 147 64, 112, 149 8537 Jeffrey C. Mogul, 147 multipart/x-byteranges, 150 8538 Keep-Alive, 43, 84, 154, 156. See MUST, 9 8539 RFC 2068 MUST NOT, 9 8540 Language Tags, 28 N rule, 15 8541 language-range, 95, 96 name, 14 8542 language-tag, 28, 95 non-shared cache, 88, 100, 106 8543 non-transparent proxy. See proxy: range-unit, 29, 96 8544 non-transparent Reason-Phrase, 37, 38 8545 OCTET, received-by, 133, 134 8546 opaque-tag, 28 received-protocol, 133, 134 8547 OPTIONAL, 9 RECOMMENDED, 9 8548 OPTIONS, 34, 48, 49, 123, 124 References, 143 8549 origin server, 10 Referer, 36, 127, 128, 137, 138 8550 other-range-unit, 29 rel_path, 19, 89 8551 outbound, 12 relativeURI, 19, 109, 128 8552 parameter, 23 representation,10 8553 PATCH. See RFC 2068 request, 9 8554 Paul J. Leach, 147 Request, 33 8555 Persistent Connections, 41 Request header fields, 36 8556 Overall Operation, 41 request-header, 33, 36 8557 Purpose, 41 Request-Line, 30, 33, 34, 50, 61, 8558 Use of Connection Header, 42 150, 154 8559 Pipelining, 42 Request-URI, 19, 33, 34, 35, 36, 8560 port, 19, 133, 134 38, 39, 48, 49, 50, 51, 52, 57, 8561 POST, 27, 30, 34, 45, 47, 50, 51, 59, 61, 63, 87, 88, 90, 97, 108, 8562 54, 57, 58, 63, 90, 114, 138 110, 123, 124, 127, 128, 136, 8563 Pragma, 33, 99, 103, 124 138, 139 8564 no-cache, 70, 78, 99, 124 REQUIRED, 9 8565 pragma-directive, 124 Requirements 8566 primary-tag, 28 compliance, 9 8567 product, 27, 132 key words, 9 8568 Product tokens, 27 resource, 9 8569 product-version, 27 response, 9 8570 protocol-name, 133 Response, 37 8571 protocol-version, 133 Response Header Fields, 39 8572 proxy, 10 response-header, 37, 39 8573 non-transparent, 10, 85, 105, Retry-After, 39, 63, 65, 128 8574 108 Revalidation 8575 transparent, 10, 40, 85 end-to-end, 103 8576 Proxy-Authenticate, 39, 62, 84, end-to-end reload, 103 8577 124, 125 end-to-end specific 8578 Proxy-Authorization, 36, 62, 85, revalidation, 103 8579 125 end-to-end unspecific 8580 pseudonym, 133, 134 revalidation, 104 8581 Public. See RFC 2068 RFC 1036, 20, 144 8582 public cache, 67, 68 RFC 1123, 20, 113, 116, 144 8583 PUT, 34, 45, 47, 48, 51, 52, 62, RFC 1305, 145 8584 90, 97, 114, 118, 121 RFC 1436, 143 8585 qdtext, 17 RFC 1590, 26, 144 8586 Quality Values, 27 RFC 1630, 143 8587 quoted-pair, 17 RFC 1700, 144 8588 quoted-string, 15, 17, 24, 28, RFC 1737, 144 8589 30, 92, 99, 115, 124, 134, 154 RFC 1738, 19, 143 8590 qvalue, 28, 92, 93, 94 RFC 1766, 28, 143 8591 Range, 29, 36, 40, 49, 51, 56, RFC 1806, 140, 146, 153 8592 64, 84, 85, 87, 112, 113, 119, RFC 1808, 19, 144 8593 121, 125, 127, 149 RFC 1864, 110, 111, 145 8594 Range Units, 29 RFC 1866, 143 8595 ranges-specifier, 111, 125, 126, RFC 1867, 27, 144 8596 127 RFC 1900, 19, 145 8598 RFC 1945, 8, 58, 144, 153 Referer header, 137, 138 8599 RFC 1950, 23, 145 sensitive headers, 137 8600 RFC 1951, 23, 145 Server header, 137 8601 RFC 1952, 145 Transfer of Sensitive 8602 RFC 2026, 146 Information, 137 8603 RFC 2044, 146 Via header, 137 8604 RFC 2045, 144, 151, 152 selecting request-headers, 87 8605 RFC 2046, 26, 146, 150, 151 semantically transparent, 12 8606 RFC 2047, 16, 135, 144 separators, 17 8607 RFC 2049, 147, 151 server, 10 8608 RFC 2068, 2, 18, 41, 43, 45, 58, Server, 27, 39, 128, 133, 137, 8609 59, 143, 146, 153, 155, 156 138 8610 changes from, 156 SHALL, 9 8611 RFC 2069, 145 SHALL NOT, 9 8612 RFC 2076, 146, 153 shared caches, 88, 101 8613 RFC 2110, 146 SHOULD, 9 8614 RFC 2119, 9, 146, 156 SHOULD NOT, 9 8615 RFC 2145, 17, 146, 156 SP, 14, 16, 17, 20, 30, 33, 37, 8616 RFC 2277, 146 111, 134, 150 8617 RFC 2279, 146 stale, 12 8618 RFC 2324, 147 start-line, 30 8619 RFC 2396, 19, 146 Status Code Definitions, 53 8620 RFC 821, 144 Status-Code, 37, 38, 53 8621 RFC 822, 14, 20, 29, 30, 113, Status-Line, 30, 37, 39, 53, 150, 8622 116, 133, 142, 144, 151 154 8623 RFC 850, 20, 144 strong entity tag, 29 8624 RFC 959, 144 strong validators, 80 8625 RFC 977, 144 subtag, 28 8626 rfc1123-date, 20 subtype, 25 8627 RFC-850, 150 suffix-byte-range-spec, 125, 126 8628 rfc850-date, 20 suffix-length, 126 8629 Roy T. Fielding, 147 T/TCP, 41 8630 rule1 | rule2, 14 t-codings, 129 8631 Safe and Idempotent Methods, 47 TE, 25, 36, 129, 130, 158 8632 Security Considerations, 137 TEXT, 16 8633 abuse of server logs, 137 Tim Berners-Lee, 148 8634 Accept header, 138 time, 20 8635 Accept headers can reveal ethnic token, 15, 17, 21, 22, 23, 24, 8636 information, 138 25, 27, 29, 30, 33, 34, 92, 99, 8637 attacks based on path names, 139 107, 115, 124, 131, 133, 154 8638 Authentication Credentials and Tolerant Applications, 150 8639 Idle Clients, 140 bad dates, 150 8640 be careful about personal should tolerate whitespace in 8641 information, 137 request and status lines, 150 8642 Content-Disposition Header, 140 tolerate LF and ignore CR in 8643 Content-Location header, 140 line terminators, 150 8644 encoding information in URI's, use lowest common denominator of 8645 138 character set, 150 8646 From header, 138 TRACE, 34, 48, 52, 54, 123, 124 8647 GET method, 138 trailer, 24 8648 Location header, 140 Trailer, 24, 33, 130 8649 Location headers and spoofing, trailers, 129 8650 140 Transfer Encoding 8651 Proxies and Caching, 141 chunked, 23 8653 transfer-coding validators, 12, 28, 71, 77, 78, 8654 chunked, 24 79, 80, 82, 83, 87 8655 deflate, 24 rules on use of, 81 8656 gzip, 24 value, 23 8657 identity, 24 variant, 10 8658 transfer-coding, 23, 24, 25, 31, Vary, 39, 56, 59, 67, 87, 118, 8659 32, 40, 110, 129, 130, 152, 153, 121, 132, 139 8660 156, 158 Via, 33, 52, 128, 133, 134, 137 8661 chunked, 23, 24, 32, 44, 129, warn-agent, 134 8662 130, 153, 158 warn-code, 86, 134 8663 chunked REQUIRED, 32 warn-codes, 70 8664 compress, 24, 158 warn-date, 134, 136 8665 identity, 32 Warning, 33, 70, 71, 72, 76, 83, 8666 trailers, 129 85, 86, 103, 134, 135, 136, 158 8667 Transfer-Encoding, 23, 31, 32, Warnings 8668 33, 40, 48, 85, 130, 131, 152, 110 Response is stale, 135 8669 153 111 Revalidation failed, 135 8670 transfer-extension, 23, 129 112 Disconnected operation, 135 8671 transfer-length, 40, 86 113 Heuristic expiration, 135 8672 transparent 199 Miscellaneous warning, 136 8673 proxy, 85 214 Transformation applied, 136 8674 transparent proxy. See proxy: 299 Miscellaneous persistent 8675 transparent warning, 136 8676 tunnel, 11 warning-value, 134, 136 8677 type, 25 warn-text, 134, 135 8678 UNLINK. See RFC 2068 weak, 28 8679 UPALPHA, 16 weak entity tag, 29 8680 Upgrade, 33, 53, 85, 131 weak validators, 80 8681 upstream, 12 weekday, 21 8682 URI. See RFC 2068 wkday, 21 8683 URI-reference, 19 WWW-Authenticate, 39, 60, 125, 8684 US-ASCII, 16, 21, 150 136 8685 user agent, 10 x-compress, 95 8686 User-Agent, 27, 36, 67, 132, 133, x-gzip, 95 8687 138