idnits 2.17.1 draft-gettys-http-v11-spec-rev-00.txt: -(1568): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2203): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2782): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(3401): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(3974): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(5311): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(5468): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(6233): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** 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: ---------------------------------------------------------------------------- ** 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? == There are 37 instances of lines with non-ascii characters in the document. == The page length should not exceed 58 lines per page, but there was 156 longer pages, the longest (page 141) being 67 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Authors' Addresses Section. ** There are 65 instances of too long lines in the document, the longest one being 4 characters in excess of 72. ** There are 4 instances of lines with control characters in the document. ** The abstract seems to contain references ([I25], [I36], [I39]), 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. -- The abstract seems to indicate that this document obsoletes RFC2616, but the header doesn't have an 'Obsoletes:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1222 has weird spacing: '... of the respo...' == Line 1514 has weird spacing: '...nations of to...' == Line 1697 has weird spacing: '... Method token...' == Line 2539 has weird spacing: '...request as da...' == Line 2935 has weird spacing: '...request metho...' == (5 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.) -- Couldn't find a document date in the document -- date freshness check skipped. -- 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: 'N34' is mentioned on line 381, but not defined == Missing Reference: 'CRLF' is mentioned on line 762, but not defined == Missing Reference: 'N14' is mentioned on line 768, but not defined == Missing Reference: 'RFC 2068' is mentioned on line 2983, but not defined ** Obsolete undefined reference: RFC 2068 (Obsoleted by RFC 2616) -- Looks like a reference, but probably isn't: '9' on line 7324 -- Looks like a reference, but probably isn't: '24' on line 7224 -- Looks like a reference, but probably isn't: '7' on line 7539 -- Looks like a reference, but probably isn't: '43' on line 8301 -- Looks like a reference, but probably isn't: '44' on line 8238 == Unused Reference: 'I5' is defined on line 7937, but no explicit reference was found in the text == Unused Reference: 'I26' is defined on line 8010, but no explicit reference was found in the text == Unused Reference: 'I35' is defined on line 8041, but no explicit reference was found in the text ** Obsolete normative reference: RFC 822 (ref. 'N3') (Obsoleted by RFC 2822) ** Obsolete normative reference: RFC 2048 (ref. 'N5') (Obsoleted by RFC 4288, RFC 4289) -- Possible downref: Non-RFC (?) normative reference: ref. 'N6' -- Possible downref: Non-RFC (?) normative reference: ref. 'N7' ** Obsolete normative reference: RFC 2396 (ref. 'N9') (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2617 (ref. 'N10') (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) -- Obsolete informational reference (is this intentional?): RFC 3066 (ref. 'I1') (Obsoleted by RFC 4646, RFC 4647) -- Obsolete informational reference (is this intentional?): RFC 1738 (ref. 'I4') (Obsoleted by RFC 4248, RFC 4266) -- Obsolete informational reference (is this intentional?): RFC 1866 (ref. 'I5') (Obsoleted by RFC 2854) -- Obsolete informational reference (is this intentional?): RFC 1808 (ref. 'I8') (Obsoleted by RFC 3986) -- Obsolete informational reference (is this intentional?): RFC 1036 (ref. 'I9') (Obsoleted by RFC 5536, RFC 5537) -- Obsolete informational reference (is this intentional?): RFC 977 (ref. 'I10') (Obsoleted by RFC 3977) -- Obsolete informational reference (is this intentional?): RFC 2388 (ref. 'I11') (Obsoleted by RFC 7578) -- Obsolete informational reference (is this intentional?): RFC 821 (ref. 'I12') (Obsoleted by RFC 2821) -- Obsolete informational reference (is this intentional?): RFC 1305 (ref. 'I21') (Obsoleted by RFC 5905) -- Obsolete informational reference (is this intentional?): RFC 2068 (ref. 'I25') (Obsoleted by RFC 2616) -- Obsolete informational reference (is this intentional?): RFC 1806 (ref. 'I27') (Obsoleted by RFC 2183) -- Obsolete informational reference (is this intentional?): RFC 2145 (ref. 'I28') (Obsoleted by RFC 7230) -- Obsolete informational reference (is this intentional?): RFC 2279 (ref. 'I30') (Obsoleted by RFC 3629) -- Obsolete informational reference (is this intentional?): RFC 2110 (ref. 'I34') (Obsoleted by RFC 2557) -- Obsolete informational reference (is this intentional?): RFC 2616 (ref. 'I39') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 11 errors (**), 0 flaws (~~), 18 warnings (==), 26 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT R. Fielding 2 Day Software 3 Obsoletes: 2616 J. Gettys 4 Category: Standards Track J. C. Mogul 5 Expires: June 2004 HP 6 H. Frystyk 7 Microsoft 8 L. Masinter 9 Adobe 10 P. Leach 11 Microsoft 12 T. Berners-Lee 13 W3C/MIT 14 December, 2003 16 Hypertext Transfer Protocol -- HTTP/1.1 18 Status of this Memo 20 This document is an Internet-Draft and is in full conformance with 21 all provisions of Section 10 of RFC2026. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF), its areas, and its working groups. Note that other 25 groups may also distribute working documents as Internet-Drafts. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or made obsolete by other documents at 29 any time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 Comments are welcome should be submitted to the mailing list ietf- 33 http-wg@w3.org 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/ietf/1id-abstracts.txt 38 The list of Internet-Draft Shadow Directories can be accessed at 39 http://www.ietf.org/shadow.html. 41 Copyright Notice 43 Copyright (C) The Internet Society (2003). All Rights Reserved. See 44 section 20 for the full copyright notice. 46 Abstract 48 The Hypertext Transfer Protocol (HTTP) is an application-level 49 protocol for distributed, collaborative, hypermedia information 50 systems. It is a generic, stateless, protocol which can be used for 51 many tasks beyond its use for hypertext, such as name servers and 52 distributed object management systems, through extension of its 53 request methods, error codes and headers [I36]. A feature of HTTP is 54 the typing and negotiation of data representation, allowing systems 55 to be built independently of the data being transferred. 57 HTTP has been in use by the World-Wide Web global information 58 initiative since 1990. This specification defines the protocol 59 referred to as "HTTP/1.1", and obsoletes RFC 2616 [I39], which 60 obsoleted RFC 2068 [I25]. 62 Table of Contents 64 HYPERTEXT TRANSFER PROTOCOL -- HTTP/1.1 1 65 Status of this Memo..............................................1 66 Copyright Notice.................................................1 67 Abstract.........................................................1 68 Table of Contents................................................3 69 1 Introduction..................................................8 70 1.1 Purpose...................................................8 71 1.2 Requirements..............................................8 72 1.3 Terminology...............................................9 73 1.4 Overall Operation........................................12 74 2 Notational Conventions and Generic Grammar...................14 75 2.1 Augmented BNF............................................14 76 2.2 Basic Rules..............................................15 77 3 Protocol Parameters..........................................17 78 3.1 HTTP Version.............................................17 79 3.2 Uniform Resource Identifiers.............................18 80 3.2.1 General Syntax......................................18 81 3.2.2 http URL............................................18 82 3.2.3 URI Comparison......................................19 83 3.3 Date/Time Formats........................................19 84 3.3.1 Full Date...........................................19 85 3.3.2 Delta Seconds.......................................20 86 3.4 Character Sets...........................................20 87 3.5 Content Codings..........................................22 88 3.6 Transfer Codings.........................................23 89 3.6.1 Chunked Transfer Coding.............................23 90 3.7 Media Types..............................................25 91 3.7.1 Canonicalization and Text Defaults..................25 92 3.7.2 Multipart Types.....................................26 93 3.8 Product Tokens...........................................26 94 3.9 Quality Values...........................................27 95 3.10 Language Tags...........................................27 96 3.11 Entity Tags.............................................28 97 3.12 Range Units.............................................28 98 4 HTTP Message.................................................29 99 4.1 Message Types............................................29 100 4.2 Message Headers..........................................29 101 4.3 Message Body.............................................30 102 4.4 Message Length...........................................31 103 4.5 General Header Fields....................................32 104 5 Request......................................................33 105 5.1 Request-Line.............................................33 106 5.1.1 Method..............................................33 107 5.1.2 Request-URI.........................................33 108 5.2 The Resource Identified by a Request.....................35 109 5.3 Request Header Fields....................................35 110 6 Response.....................................................36 111 6.1 Status-Line..............................................36 112 6.1.1 Status Code and Reason Phrase.......................36 113 6.2 Response Header Fields...................................38 114 7 Entity.......................................................38 115 7.1 Entity Header Fields.....................................39 116 7.2 Entity Body..............................................39 117 7.2.1 Type................................................39 118 7.2.2 Entity Length.......................................40 119 8 Connections..................................................40 120 8.1 Persistent Connections...................................40 121 8.1.1 Purpose.............................................40 122 8.1.2 Overall Operation...................................41 123 8.1.3 Proxy Servers.......................................42 124 8.1.4 Practical Considerations............................42 125 8.2 Message Transmission Requirements........................43 126 8.2.1 Persistent Connections and Flow Control.............43 127 8.2.2 Monitoring Connections for Error Status Messages....43 128 8.2.3 Use of the 100 (Continue) Status....................44 129 8.2.4 Client Behavior if Server Prematurely Closes Connection 130 45 131 9 Method Definitions...........................................46 132 9.1 Safe and Idempotent Methods..............................46 133 9.1.1 Safe Methods........................................46 134 9.1.2 Idempotent Methods..................................47 135 9.2 OPTIONS..................................................47 136 9.3 GET......................................................48 137 9.4 HEAD.....................................................49 138 9.5 POST.....................................................49 139 9.6 PUT......................................................50 140 9.7 DELETE...................................................51 141 9.8 TRACE....................................................51 142 9.9 CONNECT..................................................52 143 10 Status Code Definitions...................................52 144 10.1 Informational 1xx.......................................52 145 10.1.1 100 Continue.......................................52 146 10.1.2 101 Switching Protocols............................52 147 10.2 Successful 2xx..........................................53 148 10.2.1 200 OK.............................................53 149 10.2.2 201 Created........................................53 150 10.2.3 202 Accepted.......................................53 151 10.2.4 203 Non-Authoritative Information..................54 152 10.2.5 204 No Content.....................................54 153 10.2.6 205 Reset Content..................................54 154 10.2.7 206 Partial Content................................55 155 10.3 Redirection 3xx.........................................55 156 10.3.1 300 Multiple Choices...............................56 157 10.3.2 301 Moved Permanently..............................56 158 10.3.3 302 Found..........................................56 159 10.3.4 303 See Other......................................57 160 10.3.5 304 Not Modified...................................57 161 10.3.6 305 Use Proxy......................................58 162 10.3.7 306 (Unused).......................................58 163 10.3.8 307 Temporary Redirect.............................58 164 10.4 Client Error 4xx........................................59 165 10.4.1 400 Bad Request....................................59 166 10.4.2 401 Unauthorized...................................59 167 10.4.3 402 Payment Required...............................60 168 10.4.4 403 Forbidden......................................60 169 10.4.5 404 Not Found......................................60 170 10.4.6 405 Method Not Allowed.............................60 171 10.4.7 406 Not Acceptable.................................60 172 10.4.8 407 Proxy Authentication Required..................61 173 10.4.9 408 Request Timeout................................61 174 10.4.10 409 Conflict......................................61 175 10.4.11 410 Gone..........................................61 176 10.4.12 411 Length Required...............................62 177 10.4.13 412 Precondition Failed...........................62 178 10.4.14 413 Request Entity Too Large......................62 179 10.4.15 414 Request-URI Too Long..........................62 180 10.4.16 415 Unsupported Media Type........................63 181 10.4.17 416 Requested Range Not Satisfiable...............63 182 10.4.18 417 Expectation Failed............................63 183 10.5 Server Error 5xx........................................63 184 10.5.1 500 Internal Server Error..........................63 185 10.5.2 501 Not Implemented................................63 186 10.5.3 502 Bad Gateway....................................64 187 10.5.4 503 Service Unavailable............................64 188 10.5.5 504 Gateway Timeout................................64 189 10.5.6 505 HTTP Version Not Supported.....................64 190 11 Access Authentication.....................................64 191 12 Content Negotiation.......................................65 192 12.1 Server-driven Negotiation...............................65 193 12.2 Agent-driven Negotiation................................66 194 12.3 Transparent Negotiation.................................67 195 13 Caching in HTTP...........................................67 196 13.1.1 Cache Correctness..................................68 197 13.1.2 Warnings...........................................69 198 13.1.3 Cache-control Mechanisms...........................70 199 13.1.4 Explicit User Agent Warnings.......................70 200 13.1.5 Exceptions to the Rules and Warnings...............71 201 13.1.6 Client-controlled Behavior.........................71 202 13.2 Expiration Model........................................72 203 13.2.1 Server-Specified Expiration........................72 204 13.2.2 Heuristic Expiration...............................72 205 13.2.3 Age Calculations...................................73 206 13.2.4 Expiration Calculations............................75 207 13.2.5 Disambiguating Expiration Values...................75 208 13.2.6 Disambiguating Multiple Responses..................76 209 13.3 Validation Model........................................76 210 13.3.1 Last-Modified Dates................................77 211 13.3.2 Entity Tag Cache Validators........................77 212 13.3.3 Weak and Strong Validators.........................78 213 13.3.4 Rules for When to Use Entity Tags and Last-Modified 214 Dates 80 215 13.3.5 Non-validating Conditionals........................81 216 13.4 Response Cacheability...................................82 217 13.5 Constructing Responses From Caches......................82 218 13.5.1 End-to-end and Hop-by-hop Headers..................83 219 13.5.2 Non-modifiable Headers.............................83 220 13.5.3 Combining Headers..................................84 221 13.5.4 Combining Byte Ranges..............................85 222 13.6 Caching Negotiated Responses............................85 223 13.7 Shared and Non-Shared Caches............................87 224 13.8 Errors or Incomplete Response Cache Behavior............87 225 13.9 Side Effects of GET and HEAD............................87 226 13.10 Invalidation After Updates or Deletions................88 227 13.11 Write-Through Mandatory................................88 228 13.12 Cache Replacement......................................89 229 13.13 History Lists..........................................89 230 14 Header Field Definitions..................................89 231 14.1 Accept..................................................90 232 14.2 Accept-Charset..........................................91 233 14.3 Accept-Encoding.........................................92 234 14.4 Accept-Language.........................................93 235 14.5 Accept-Ranges...........................................94 236 14.6 Age.....................................................95 237 14.7 Allow...................................................95 238 14.8 Authorization...........................................96 239 14.9 Cache-Control...........................................96 240 14.9.1 What is Cacheable..................................98 241 14.9.2 What May be Stored by Caches.......................99 242 14.9.3 Modifications of the Basic Expiration Mechanism....99 243 14.9.4 Cache Revalidation and Reload Controls............101 244 14.9.5 No-Transform Directive............................103 245 14.9.6 Cache Control Extensions..........................104 246 14.10 Connection............................................104 247 14.11 Content-Encoding......................................105 248 14.12 Content-Language......................................106 249 14.13 Content-Length........................................107 250 14.14 Content-Location......................................107 251 14.15 Content-MD5...........................................108 252 14.16 Content-Range.........................................109 253 14.17 Content-Type..........................................111 254 14.18 Date..................................................111 255 14.18.1 Clockless Origin Server Operation................112 256 14.19 ETag..................................................112 257 14.20 Expect................................................113 258 14.21 Expires...............................................113 259 14.22 From..................................................114 260 14.23 Host..................................................115 261 14.24 If-Match..............................................115 262 14.25 If-Modified-Since.....................................116 263 14.26 If-None-Match.........................................118 264 14.27 If-Range..............................................119 265 14.28 If-Unmodified-Since...................................119 266 14.29 Last-Modified.........................................120 267 14.30 Location..............................................120 268 14.31 Max-Forwards..........................................121 269 14.32 Pragma................................................122 270 14.33 Proxy-Authenticate....................................122 271 14.34 Proxy-Authorization...................................123 272 14.35 Range.................................................123 273 14.35.1 Byte Ranges......................................123 274 14.35.2 Range Retrieval Requests.........................125 275 14.36 Referer...............................................125 276 14.37 Retry-After...........................................126 277 14.38 Server................................................126 278 14.39 TE....................................................126 279 14.40 Trailer...............................................128 280 14.41 Transfer-Encoding.....................................128 281 14.42 Upgrade...............................................128 282 14.43 User-Agent............................................129 283 14.44 Vary..................................................130 284 14.45 Via...................................................131 285 14.46 Warning...............................................132 286 14.47 WWW-Authenticate......................................134 287 15 Security Considerations..................................134 288 15.1 Personal Information...................................135 289 15.1.1 Abuse of Server Log Information...................135 290 15.1.2 Transfer of Sensitive Information.................135 291 15.1.3 Encoding Sensitive Information in URI's...........136 292 15.1.4 Privacy Issues Connected to Accept Headers........136 293 15.2 Attacks Based On File and Path Names...................137 294 15.3 DNS Spoofing...........................................137 295 15.4 Location Headers and Spoofing..........................138 296 15.5 Content-Disposition Issues.............................138 297 15.6 Authentication Credentials and Idle Clients............138 298 15.7 Proxies and Caching....................................139 299 15.7.1 Denial of Service Attacks on Proxies..............139 300 16 Acknowledgments..........................................140 301 17 Appendices...............................................141 302 17.1 IANA Considerations - Internet Media Type message/http and 303 application/http............................................141 304 17.2 IANA Considerations - Internet Media Type 305 multipart/byteranges........................................142 306 17.3 Tolerant Applications..................................143 307 17.4 Differences Between HTTP Entities and RFC 2045 Entities143 308 17.4.1 MIME-Version......................................144 309 17.4.2 Conversion to Canonical Form......................144 310 17.4.3 Conversion of Date Formats........................145 311 17.4.4 Introduction of Content-Encoding..................145 312 17.4.5 No Content-Transfer-Encoding......................145 313 17.4.6 Introduction of Transfer-Encoding.................145 314 17.4.7 MHTML and Line Length Limitations.................146 315 17.5 Additional Features....................................146 316 17.5.1 Content-Disposition...............................146 317 17.6 Compatibility with Previous Versions...................147 318 17.6.1 Changes from HTTP/1.0.............................147 319 17.6.2 Compatibility with HTTP/1.0 Persistent Connections148 320 17.6.3 Changes from RFC 2616.............................149 321 18 References...............................................150 322 18.1 Normative References...................................150 323 18.2 Informative References.................................151 324 19 Authors' Addresses.......................................154 325 20 Full Copyright Statement.................................156 326 20.1 Acknowledgement........................................156 327 21 Index....................................................157 328 1 Introduction 330 1.1 Purpose 332 The Hypertext Transfer Protocol (HTTP) is an application-level 333 protocol for distributed, collaborative, hypermedia information 334 systems. HTTP has been in use by the World-Wide Web global 335 information initiative since 1990. The first version of HTTP, 336 referred to as HTTP/0.9, was a simple protocol for raw data transfer 337 across the Internet. HTTP/1.0, as defined by RFC 1945 [I6], improved 338 the protocol by allowing messages to be in the format of MIME-like 339 messages, containing metainformation about the data transferred and 340 modifiers on the request/response semantics. However, HTTP/1.0 does 341 not sufficiently take into consideration the effects of hierarchical 342 proxies, caching, the need for persistent connections, or virtual 343 hosts. In addition, the proliferation of incompletely-implemented 344 applications calling themselves "HTTP/1.0" has necessitated a 345 protocol version change in order for two communicating applications 346 to determine each other's true capabilities. 348 This specification defines the protocol referred to as "HTTP/1.1". 349 This protocol includes more stringent requirements than HTTP/1.0 in 350 order to ensure reliable implementation of its features. 352 Practical information systems require more functionality than simple 353 retrieval, including search, front-end update, and annotation. HTTP 354 allows an open-ended set of methods and headers that indicate the 355 purpose of a request [I36]. It builds on the discipline of reference 356 provided by the Uniform Resource Identifier (URI) [I3], [N9], as a 357 location (URL) [I4] or name (URN) [I15], for indicating the resource 358 to which a method is to be applied. Messages are passed in a format 359 similar to that used by Internet mail [I9] as defined by the 360 Multipurpose Internet Mail Extensions (MIME) [N1]. 362 HTTP is also used as a generic protocol for communication between 363 user agents and proxies/gateways to other Internet systems, including 364 those supported by the SMTP [I12], NNTP [I10], FTP [I13], Gopher 365 [I2], and WAIS [I7] protocols. In this way, HTTP allows basic 366 hypermedia access to resources available from diverse applications. 368 1.2 Requirements 370 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 371 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 372 document are to be interpreted as described in RFC 2119 [N34]. 373 An implementation is not compliant if it fails to satisfy one or more 374 of the MUST or REQUIRED level requirements for the protocols it 375 implements. An implementation that satisfies all the MUST or REQUIRED 376 level and all the SHOULD level requirements for its protocols is said 377 to be "unconditionally compliant"; one that satisfies all the MUST 378 level requirements but not all the SHOULD level requirements for its 379 protocols is said to be "conditionally compliant." 380 1.3 Terminology 382 This specification uses a number of terms to refer to the roles 383 played by participants in, and objects of, the HTTP communication. 385 connection 386 A transport layer virtual circuit established between two programs 387 for the purpose of communication. 389 message 390 The basic unit of HTTP communication, consisting of a structured 391 sequence of octets matching the syntax defined in section 4 and 392 transmitted via the connection. 394 request 395 An HTTP request message, as defined in section 5. 397 response 398 An HTTP response message, as defined in section 6. 400 resource 401 A network data object or service that can be identified by a URI, as 403 defined in section 3.2. Resources may be available in multiple 404 representations (e.g. multiple languages, data formats, size, and 405 resolutions) or vary in other ways. 407 entity 408 The information transferred as the payload of a request or response. 409 An entity consists of metainformation in the form of entity-header 410 fields and content in the form of an entity-body, as described in 411 section 7. 413 representation 414 An entity included with a response that is subject to content 415 negotiation, as described in section 12. There may exist multiple 416 representations associated with a particular response status. 418 content negotiation 419 The mechanism for selecting the appropriate representation when 420 servicing a request, as described in section 12. The representation 421 of entities in any response can be negotiated (including error 422 responses). 424 variant 425 A resource may have one, or more than one, representation(s) 426 associated with it at any given instant. Each of these 427 representations is termed a "variant." Use of the term "variant" does 428 not necessarily imply that the resource is subject to content 429 negotiation. 431 client 432 A program that establishes connections for the purpose of sending 433 requests. 435 user agent 436 The client which initiates a request. These are often browsers, 437 editors, spiders (web-traversing robots), or other end user tools. 439 server 440 An application program that accepts connections in order to service 441 requests by sending back responses. Any given program may be capable 442 of being both a client and a server; our use of these terms refers 443 only to the role being performed by the program for a particular 444 connection, rather than to the program�s capabilities in general. 445 Likewise, any server may act as an origin server, proxy, gateway, or 446 tunnel, switching behavior based on the nature of each request. 448 origin server 449 The server on which a given resource resides or is to be created. 451 proxy 452 An intermediary program which acts as both a server and a client for 453 the purpose of making requests on behalf of other clients. Requests 454 are serviced internally or by passing them on, with possible 455 translation, to other servers. A proxy MUST implement both the client 456 and server requirements of this specification. A "transparent proxy" 457 is a proxy that does not modify the request or response beyond what 458 is required for proxy authentication and identification. A "non- 459 transparent proxy" is a proxy that modifies the request or response 460 in order to provide some added service to the user agent, such as 461 group annotation services, media type transformation, protocol 462 reduction, or anonymity filtering. Except where either transparent or 463 non-transparent behavior is explicitly stated, the HTTP proxy 464 requirements apply to both types of proxies. 466 gateway 467 A server which acts as an intermediary for some other server. Unlike 468 a proxy, a gateway receives requests as if it were the origin server 469 for the requested resource; the requesting client may not be aware 470 that it is communicating with a gateway. 472 tunnel 473 An intermediary program which is acting as a blind relay between two 474 connections. Once active, a tunnel is not considered a party to the 475 HTTP communication, though the tunnel may have been initiated by an 476 HTTP request. The tunnel ceases to exist when both ends of the 477 relayed connections are closed. 479 cache 480 A program's local store of response messages and the subsystem that 481 controls its message storage, retrieval, and deletion. A cache stores 482 cacheable responses in order to reduce the response time and network 483 bandwidth consumption on future, equivalent requests. Any client or 484 server may include a cache, though a cache cannot be used by a server 485 that is acting as a tunnel. 487 cacheable 488 A response is cacheable if a cache is allowed to store a copy of the 489 response message for use in answering subsequent requests. The rules 490 for determining the cacheability of HTTP responses are defined in 491 section 13. Even if a resource is cacheable, there may be additional 492 constraints on whether a cache can use the cached copy for a 493 particular request. 495 first-hand 496 A response is first-hand if it comes directly and without unnecessary 497 delay from the origin server, perhaps via one or more proxies. A 498 response is also first-hand if its validity has just been checked 499 directly with the origin server. 501 explicit expiration time 502 The time at which the origin server intends that an entity should no 503 longer be returned by a cache without further validation. 505 heuristic expiration time 506 An expiration time assigned by a cache when no explicit expiration 507 time is available. 509 age 510 The age of a response is the time since it was sent by, or 511 successfully validated with, the origin server. 513 freshness lifetime 514 The length of time between the generation of a response and its 515 expiration time. 517 fresh 518 A response is fresh if its age has not yet exceeded its freshness 519 lifetime. 521 stale 522 A response is stale if its age has passed its freshness lifetime. 524 semantically transparent 525 A cache behaves in a "semantically transparent" manner, with respect 526 to a particular response, when its use affects neither the requesting 527 client nor the origin server, except to improve performance. When a 528 cache is semantically transparent, the client receives exactly the 529 same response (except for hop-by-hop headers) that it would have 530 received had its request been handled directly by the origin server. 532 validator 533 A protocol element (e.g., an entity tag or a Last-Modified time) that 534 is used to find out whether a cache entry is an equivalent copy of an 535 entity. 537 upstream/downstream 538 Upstream and downstream describe the flow of a message: all messages 539 flow from upstream to downstream. 541 inbound/outbound 542 Inbound and outbound refer to the request and response paths for 543 messages: "inbound" means "traveling toward the origin server", and 544 "outbound" means "traveling toward the user agent" 546 1.4 Overall Operation 548 The HTTP protocol is a request/response protocol. A client sends a 549 request to the server in the form of a request method, URI, and 550 protocol version, followed by a MIME-like message containing request 551 modifiers, client information, and possible body content over a 552 connection with a server. The server responds with a status line, 553 including the message's protocol version and a success or error code, 554 followed by a MIME-like message containing server information, entity 555 metainformation, and possible entity-body content. The relationship 556 between HTTP and MIME is described in appendix 17.4. 558 Most HTTP communication is initiated by a user agent and consists of 559 a request to be applied to a resource on some origin server. In the 560 simplest case, this may be accomplished via a single connection (v) 561 between the user agent (UA) and the origin server (O). 563 request chain ------------------------> 564 UA -------------------v------------------- O 565 <----------------------- response chain 567 A more complicated situation occurs when one or more intermediaries 569 are present in the request/response chain. There are three common 570 forms of intermediary: proxy, gateway, and tunnel. A proxy is a 571 forwarding agent, receiving requests for a URI in its absolute form, 572 rewriting all or part of the message, and forwarding the reformatted 573 request toward the server identified by the URI. A gateway is a 574 receiving agent, acting as a layer above some other server(s) and, if 575 necessary, translating the requests to the underlying server's 576 protocol. A tunnel acts as a relay point between two connections 577 without changing the messages; tunnels are used when the 578 communication needs to pass through an intermediary (such as a 579 firewall) even when the intermediary cannot understand the contents 580 of the messages. 582 request chain --------------------------------------> 583 UA -----v----- A -----v----- B -----v----- C -----v----- O 584 <------------------------------------- response chain 586 The figure above shows three intermediaries (A, B, and C) between the 587 user agent and origin server. A request or response message that 588 travels the whole chain will pass through four separate connections. 590 This distinction is important because some HTTP communication options 591 may apply only to the connection with the nearest, non-tunnel 592 neighbor, only to the end-points of the chain, or to all connections 593 along the chain. Although the diagram is linear, each participant may 594 be engaged in multiple, simultaneous communications. For example, B 595 may be receiving requests from many clients other than A, and/or 596 forwarding requests to servers other than C, at the same time that it 597 is handling A's request. 599 Any party to the communication which is not acting as a tunnel may 600 employ an internal cache for handling requests. The effect of a cache 601 is that the request/response chain is shortened if one of the 602 participants along the chain has a cached response applicable to that 603 request. The following illustrates the resulting chain if B has a 604 cached copy of an earlier response from O (via C) for a request which 605 has not been cached by UA or A. 607 request chain ----------> 608 UA -----v----- A -----v----- B - - - - - - C - - - - - - O 609 <--------- response chain 611 Not all responses are usefully cacheable, and some requests may 612 contain modifiers which place special requirements on cache behavior. 613 HTTP requirements for cache behavior and cacheable responses are 614 defined in section 13. 616 In fact, there are a wide variety of architectures and configurations 617 of caches and proxies currently being experimented with or deployed 618 across the World Wide Web. These systems include national hierarchies 619 of proxy caches to save transoceanic bandwidth, systems that 620 broadcast or multicast cache entries, organizations that distribute 621 subsets of cached data via CD-ROM, and so on. HTTP systems are used 622 in corporate intranets over high-bandwidth links, and for access via 623 PDAs with low-power radio links and intermittent connectivity. The 624 goal of HTTP/1.1 is to support the wide diversity of configurations 625 already deployed while introducing protocol constructs that meet the 626 needs of those who build web applications that require high 627 reliability and, failing that, at least reliable indications of 628 failure. 630 HTTP communication usually takes place over TCP/IP connections. The 631 default port is TCP 80 [I14], but other ports can be used. This does 632 not preclude HTTP from being implemented on top of any other protocol 633 on the Internet, or on other networks. HTTP only presumes a reliable 634 transport; any protocol that provides such guarantees can be used; 635 the mapping of the HTTP/1.1 request and response structures onto the 636 transport data units of the protocol in question is outside the scope 637 of this specification. 639 In HTTP/1.0, most implementations used a new connection for each 640 request/response exchange. In HTTP/1.1, a connection may be used for 641 one or more request/response exchanges, although connections may be 642 closed for a variety of reasons (see section 8.1). 644 2 Notational Conventions and Generic Grammar 646 2.1 Augmented BNF 648 All of the mechanisms specified in this document are described in 649 both prose and an augmented Backus-Naur Form (BNF) similar to that 650 used by RFC 822 [I9]. Implementors will need to be familiar with the 651 notation in order to understand this specification. The augmented BNF 652 includes the following constructs: 654 name = definition 655 The name of a rule is simply the name itself (without any enclosing 656 "<" and ">") and is separated from its definition by the equal "=" 657 character. White space is only significant in that indentation of 658 continuation lines is used to indicate a rule definition that spans 659 more than one line. Certain basic rules are in uppercase, such as SP, 660 LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle brackets are used within 661 definitions whenever their presence will facilitate discerning the 662 use of rule names. 664 "literal" 665 Quotation marks surround literal text. Unless stated otherwise, the 666 text is case-insensitive. 668 rule1 | rule2 669 Elements separated by a bar ("|") are alternatives, e.g., "yes | no" 670 will accept yes or no. 672 (rule1 rule2) 673 Elements enclosed in parentheses are treated as a single element. 674 Thus, "(elem (foo | bar) elem)" allows the token sequences 675 "elem foo elem" and "elem bar elem". 677 *rule 678 The character "*" preceding an element indicates repetition. The full 679 form is "*element" indicating at least and at most 680 occurrences of element. Default values are 0 and infinity so that 681 "*(element)" allows any number, including zero; "1*element" requires 682 at least one; and "1*2element" allows one or two. 684 [rule] 685 Square brackets enclose optional elements; "[foo bar]" is equivalent 686 to "*1(foo bar)". 688 N rule 689 Specific repetition: "(element)" is equivalent to 690 "*(element)"; that is, exactly occurrences of (element). 691 Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three 692 alphabetic characters. 694 #rule 695 A construct "#" is defined, similar to "*", for defining lists of 696 elements. The full form is "#element" indicating at least 697 and at most elements, each separated by one or more commas (",") 698 and OPTIONAL linear white space (LWS). This makes the usual form of 699 lists very easy; a rule such as 701 ( *LWS element *( *LWS "," *LWS element )) 703 can be shown as 705 1#element 707 Wherever this construct is used, null elements are allowed, but do 708 not contribute to the count of elements present. That is, "(element), 709 , (element) " is permitted, but counts as only two elements. 710 Therefore, where at least one element is required, at least one non- 711 null element MUST be present. Default values are 0 and infinity so 712 that "#element" allows any number, including zero; "1#element" 713 requires at least one; and "1#2element" allows one or two. 715 ; comment 716 A semi-colon, set off some distance to the right of rule text, starts 717 a comment that continues to the end of line. This is a simple way of 718 including useful notes in parallel with the specifications. 720 implied *LWS 721 The grammar described by this specification is word-based. Except 722 where noted otherwise, linear white space (LWS) can be included 723 between any two adjacent words (token or quoted-string), and between 724 adjacent words and separators, without changing the interpretation of 725 a field. At least one delimiter (LWS and/or separators) MUST exist 726 between any two tokens (for the definition of "token" below), since 727 they would otherwise be interpreted as a single token. 729 2.2 Basic Rules 731 The following rules are used throughout this specification to 732 describe basic parsing constructs. The US-ASCII coded character set 733 is defined by ANSI X3.4-1986 [N6]. 735 OCTET = 736 CHAR = 737 UPALPHA = 738 LOALPHA = 739 ALPHA = UPALPHA | LOALPHA 740 DIGIT = 741 CTL = 743 CR = 744 LF = 745 SP = 746 HT = 747 <"> = 749 HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all 750 protocol elements except the entity-body (see appendix 17.3 for 751 tolerant applications). The end-of-line marker within an entity-body 752 is defined by its associated media type, as described in section 3.7. 754 CRLF = CR LF 756 HTTP/1.1 header field values can be folded onto multiple lines if the 757 continuation line begins with a space or horizontal tab. All linear 758 white space, including folding, has the same semantics as SP. A 759 recipient MAY replace any linear white space with a single SP before 760 interpreting the field value or forwarding the message downstream. 762 LWS = [CRLF] 1*( SP | HT ) 764 The TEXT rule is only used for descriptive field contents and values 765 that are not intended to be interpreted by the message parser. Words 766 of *TEXT MAY contain characters from character sets other than ISO- 767 8859-1 [N7] only when encoded according to the rules of RFC 2047 768 [N14]. 770 TEXT = 773 A CRLF is allowed in the definition of TEXT only as part of a header 774 field continuation. It is expected that the folding LWS will be 775 replaced with a single SP before interpretation of the TEXT value. 777 Hexadecimal numeric characters are used in several protocol elements. 779 HEX = "A" | "B" | "C" | "D" | "E" | "F" 780 | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT 782 Many HTTP/1.1 header field values consist of words separated by LWS 783 or special characters. These special characters MUST be in a quoted 784 string to be used within a parameter value (as defined in section 785 3.6). 787 token = 1* 788 separators = "(" | ")" | "<" | ">" | "@" 789 | "," | ";" | ":" | "\" | <"> 790 | "/" | "[" | "]" | "?" | "=" 791 | "{" | "}" | SP | HT 793 Comments can be included in some HTTP header fields by surrounding 794 the comment text with parentheses. Comments are only allowed in 795 fields containing "comment" as part of their field value definition. 797 In all other fields, parentheses are considered part of the field 798 value. 800 comment = "(" *( ctext | quoted-pair | comment ) ")" 801 ctext = 803 A string of text is parsed as a single word if it is quoted using 804 double-quote marks. 806 quoted-string = ( <"> *(qdtext | quoted-pair ) <"> ) 807 qdtext = > 809 The backslash character ("\") MAY be used as a single-character 810 quoting mechanism only within quoted-string and comment constructs. 812 quoted-pair = "\" CHAR 814 3 Protocol Parameters 816 3.1 HTTP Version 818 HTTP uses a "." numbering scheme to indicate versions 819 of the protocol. The protocol versioning policy is intended to allow 820 the sender to indicate the format of a message and its capacity for 821 understanding further HTTP communication, rather than the features 822 obtained via that communication. No change is made to the version 823 number for the addition of message components which do not affect 824 communication behavior or which only add to extensible field values. 826 The number is incremented when the changes made to the 827 protocol add features which do not change the general message parsing 828 algorithm, but which may add to the message semantics and imply 829 additional capabilities of the sender. The number is 830 incremented when the format of a message within the protocol is 831 changed. See RFC 2145 [I28] for a fuller explanation. 832 The version of an HTTP message is indicated by an HTTP-Version field 833 in the first line of the message. HTTP-Version is case-sensitive. 835 HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT 837 Note that the major and minor numbers MUST be treated as separate 838 integers and that each MAY be incremented higher than a single digit. 839 Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in turn is 840 lower than HTTP/12.3. Leading zeros MUST be ignored by recipients and 841 MUST NOT be sent. 843 An application that sends a request or response message that includes 844 HTTP-Version of "HTTP/1.1" MUST be at least conditionally compliant 845 with this specification. Applications that are at least conditionally 846 compliant with this specification SHOULD use an HTTP-Version of 847 "HTTP/1.1" in their messages, and MUST do so for any message that is 848 not compatible with HTTP/1.0. For more details on when to send 849 specific HTTP-Version values, see RFC 2145 [I28]. 851 The HTTP version of an application is the highest HTTP version for 852 which the application is at least conditionally compliant. 854 Proxy and gateway applications need to be careful when forwarding 855 messages in protocol versions different from that of the application. 856 Since the protocol version indicates the protocol capability of the 857 sender, a proxy/gateway MUST NOT send a message with a version 858 indicator which is greater than its actual version. If a higher 859 version request is received, the proxy/gateway MUST either downgrade 860 the request version, or respond with an error, or switch to tunnel 861 behavior. 863 Due to interoperability problems with HTTP/1.0 proxies discovered 864 since the publication of RFC 2068[I25], caching proxies MUST, 865 gateways MAY, and tunnels MUST NOT upgrade the request to the highest 866 version they support. The proxy/gateway's response to that request 867 MUST be in the same major version as the request. 869 Note: Converting between versions of HTTP may involve modification 870 of header fields required or forbidden by the versions involved. 872 3.2 Uniform Resource Identifiers 874 URIs have been known by many names: WWW addresses, Universal Document 875 Identifiers, Universal Resource Identifiers [I3], [N9], and finally 876 the combination of Uniform Resource Locators (URL) [I4] and Names 877 (URN) [I15]. As far as HTTP is concerned, Uniform Resource 878 Identifiers are simply formatted strings which identify--via name, 879 location, or any other characteristic--a resource. 881 3.2.1 General Syntax 883 URIs in HTTP can be represented in absolute form or relative to some 884 known base URI [I8], depending upon the context of their use. The two 885 forms are differentiated by the fact that absolute URIs always begin 886 with a scheme name followed by a colon. For definitive information on 887 URL syntax and semantics, see "Uniform Resource Identifiers (URI): 888 Generic Syntax and Semantics," RFC 2396 [N9] (which replaces RFCs 889 1738 [I4] and RFC 1808 [I8]). This specification adopts the 890 definitions of "URI-reference", "absoluteURI", "relativeURI", "port", 891 "host","abs_path", "rel_path", and "authority" from that 892 specification. 894 The HTTP protocol does not place any a priori limit on the length of 895 a URI. Servers MUST be able to handle the URI of any resource they 896 serve, and SHOULD be able to handle URIs of unbounded length if they 897 provide GET-based forms that could generate such URIs. A server 898 SHOULD return 414 (Request-URI Too Long) status if a URI is longer 899 than the server can handle (see section 10.4.15). 901 Note: Servers ought to be cautious about depending on URI lengths 902 above 255 bytes, because some older client or proxy implementations 903 might not properly support these lengths. 905 3.2.2 http URL 907 The "http" scheme is used to locate network resources via the HTTP 908 protocol. This section defines the scheme-specific syntax and 909 semantics for http URLs. 911 http_URL = "http:" "//" host [ ":" port ] [ abs_path [ "?" query ]] 913 If the port is empty or not given, port 80 is assumed. The semantics 914 are that the identified resource is located at the server listening 915 for TCP connections on that port of that host, and the Request-URI 916 for the resource is abs_path (section 5.1.2). The use of IP addresses 917 in URLs SHOULD be avoided whenever possible (see RFC 1900 [I17]). If 918 the abs_path is not present in the URL, it MUST be given as "/" when 919 used as a Request-URI for a resource (section 5.1.2). If a proxy 920 receives a host name which is not a fully qualified domain name, it 921 MAY add its domain to the host name it received. If a proxy receives 922 a fully qualified domain name, the proxy MUST NOT change the host 923 name. 925 3.2.3 URI Comparison 927 When comparing two URIs to decide if they match or not, a client 928 SHOULD use a case-sensitive octet-by-octet comparison of the entire 929 URIs, with these exceptions: 931 o A port that is empty or not given is equivalent to the default port 932 for that URI-reference; 933 o Comparisons of host names MUST be case-insensitive; 934 o Comparisons of scheme names MUST be case-insensitive; 935 o An empty abs_path is equivalent to an abs_path of "/". 937 Characters other than those in the "reserved" set (see RFC 2396 [N9]) 938 are equivalent to their ""%" HEX HEX" encoding. 940 For example, the following three URIs are equivalent: 942 http://abc.com:80/~smith/home.html 943 http://ABC.com/%7Esmith/home.html 944 http://ABC.com:/%7esmith/home.html 946 3.3 Date/Time Formats 948 3.3.1 Full Date 950 HTTP applications have historically allowed three different formats 951 for the representation of date/time stamps: 953 Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123 954 Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036 955 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format 957 The first format is preferred as an Internet standard and represents 958 a fixed-length subset of that defined by RFC 1123 [N2] (an update to 959 RFC 822 [I9]). The second format is in common use, but is based on 960 the obsolete RFC 850 [I9] date format and lacks a four-digit year. 962 HTTP/1.1 clients and servers that parse the date value MUST accept 963 all three formats (for compatibility with HTTP/1.0), though they MUST 964 only generate the RFC 1123 format for representing HTTP-date values 965 in header fields. See section 17.3 for further information. 967 Note: Recipients of date values are encouraged to be robust in 968 accepting date values that may have been sent by non-HTTP 969 applications, as is sometimes the case when retrieving or posting 970 messages via proxies/gateways to SMTP or NNTP. 972 All HTTP date/time stamps MUST be represented in Greenwich Mean Time 973 (GMT), without exception. For the purposes of HTTP, GMT is exactly 974 equal to UTC (Coordinated Universal Time). This is indicated in the 975 first two formats by the inclusion of "GMT" as the three-letter 976 abbreviation for time zone, and MUST be assumed when reading the 977 asctime format. HTTP-date is case sensitive and MUST NOT include 978 additional LWS beyond that specifically included as SP in the 979 grammar. 981 HTTP-date = rfc1123-date | rfc850-date | asctime-date 982 rfc1123-date = wkday "," SP date1 SP time SP "GMT" 983 rfc850-date = weekday "," SP date2 SP time SP "GMT" 984 asctime-date = wkday SP date3 SP time SP 4DIGIT 985 date1 = 2DIGIT SP month SP 4DIGIT 986 ; day month year (e.g., 02 Jun 1982) 987 date2 = 2DIGIT "-" month "-" 2DIGIT 988 ; day-month-year (e.g., 02-Jun-82) 989 date3 = month SP ( 2DIGIT | ( SP 1DIGIT )) 990 ; month day (e.g., Jun 2) 991 time = 2DIGIT ":" 2DIGIT ":" 2DIGIT 992 ; 00:00:00 - 23:59:59 993 wkday = "Mon" | "Tue" | "Wed" 994 | "Thu" | "Fri" | "Sat" | "Sun" 995 weekday = "Monday" | "Tuesday" | "Wednesday" 996 | "Thursday" | "Friday" | "Saturday" | "Sunday" 998 month = "Jan" | "Feb" | "Mar" | "Apr" 999 | "May" | "Jun" | "Jul" | "Aug" 1000 | "Sep" | "Oct" | "Nov" | "Dec" 1002 Note: HTTP requirements for the date/time stamp format apply only 1003 to their usage within the protocol stream. Clients and servers are 1004 not required to use these formats for user presentation, request 1005 logging, etc. 1007 3.3.2 Delta Seconds 1009 Some HTTP header fields allow a time value to be specified as an 1010 integer number of seconds, represented in decimal, after the time 1011 that the message was received. 1013 delta-seconds = 1*DIGIT 1015 3.4 Character Sets 1017 HTTP uses the same definition of the term "character set" as that 1018 described for MIME: 1020 The term "character set" is used in this document to refer to a 1021 method used with one or more tables to convert a sequence of octets 1022 into a sequence of characters. Note that unconditional conversion 1023 in the other direction is not required, in that not all characters 1024 may be available in a given character set and a character set may 1025 provide more than one sequence of octets to represent a particular 1026 character. This definition is intended to allow various kinds of 1027 character encoding, from simple single-table mappings such as US- 1028 ASCII to complex table switching methods such as those that use 1029 ISO-2022�s techniques. However, the definition associated with a 1030 MIME character set name MUST fully specify the mapping to be 1031 performed from octets to characters. In particular, use of external 1032 profiling information to determine the exact mapping is not 1033 permitted. 1035 Note: This use of the term "character set" is more commonly 1036 referred to as a "character encoding." However, since HTTP and MIME 1037 share the same registry, it is important that the terminology also 1038 be shared. 1040 HTTP character sets are identified by case-insensitive tokens. The 1041 complete set of tokens is defined by the IANA Character Set registry 1042 [I14]. 1044 charset = token 1046 Although HTTP allows an arbitrary token to be used as a charset 1047 value, any token that has a predefined value within the IANA 1048 Character Set registry MUST represent the character set defined by 1049 that registry. Applications SHOULD limit their use of character sets 1050 to those defined by the IANA registry. 1052 HTTP uses charset in two contexts: within an Accept-Charset request 1053 header (in which the charset value is an unquoted token) and as the 1054 value of a parameter in a Content-Type header (within a request or 1055 response), in which case the parameter value of the charset parameter 1056 may be quoted. 1058 Implementors should be aware of IETF character set requirements [I30] 1059 [I32]. 1061 Missing Charset 1063 Some HTTP/1.0 software has interpreted a Content-Type header without 1064 charset parameter incorrectly to mean "recipient should guess." 1065 Senders wishing to defeat this behavior MAY include a charset 1066 parameter even when the charset is ISO-8859-1 and SHOULD do so when 1067 it is known that it will not confuse the recipient. 1069 Unfortunately, some older HTTP/1.0 clients did not deal properly with 1070 an explicit charset parameter. HTTP/1.1 recipients MUST respect the 1071 charset label provided by the sender; and those user agents that have 1072 a provision to "guess" a charset MUST use the charset from the 1073 content-type field if they support that charset, rather than the 1074 recipient's preference, when initially displaying a document. See 1075 section 3.7.1. 1077 3.5 Content Codings 1079 Content coding values indicate an encoding transformation that has 1080 been or can be applied to an entity. Content codings are primarily 1081 used to allow a document to be compressed or otherwise usefully 1082 transformed without losing the identity of its underlying media type 1083 and without loss of information. Frequently, the entity is stored in 1084 coded form, transmitted directly, and only decoded by the recipient. 1086 content-coding = token 1088 All content-coding values are case-insensitive. HTTP/1.1 uses 1089 content-coding values in the Accept-Encoding (section 14.3) and 1090 Content-Encoding (section 14.11) header fields. Although the value 1091 describes the content-coding, what is more important is that it 1092 indicates what decoding mechanism will be required to remove the 1093 encoding. 1094 The Internet Assigned Numbers Authority (IANA) acts as a registry for 1095 content-coding value tokens. Initially, the registry contains the 1096 following tokens: 1098 gzip An encoding format produced by the file compression program "gzip" 1099 (GNU zip) as described in RFC 1952 [I18]. This format is a Lempel- 1100 Ziv coding (LZ77) with a 32 bit CRC. 1102 compress 1103 The encoding format produced by the common UNIX file compression 1104 program "compress". This format is an adaptive Lempel-Ziv-Welch 1105 coding (LZW). 1107 Use of program names for the identification of encoding formats is 1108 not desirable and is discouraged for future encodings. Their use 1109 here is representative of historical practice, not good design. For 1110 compatibility with previous implementations of HTTP, applications 1111 SHOULD consider "x-gzip" and "x-compress" to be equivalent to 1112 "gzip" and "compress" respectively. 1114 deflate 1115 The "zlib" format defined in RFC 1950 [I24] in combination with the 1116 "deflate" compression mechanism described in RFC 1951 [I22]. 1118 identity 1119 The default (identity) encoding; the use of no transformation 1120 whatsoever. This content-coding is used only in the Accept-Encoding 1121 header, and SHOULD NOT be used in the Content-Encoding header. 1123 New content-coding value tokens SHOULD be registered; to allow 1124 interoperability between clients and servers, specifications of the 1125 content coding algorithms needed to implement a new value SHOULD be 1126 publicly available and adequate for independent implementation, and 1127 conform to the purpose of content coding defined in this section. New 1128 registrations are reviewed and approved by the IESG according to 1129 these criteria. 1131 3.6 Transfer Codings 1133 Transfer-coding values are used to indicate an encoding 1134 transformation that has been, can be, or may need to be applied to an 1135 entity-body in order to ensure "safe transport" through the network. 1137 This differs from a content coding in that the transfer-coding is a 1138 property of the message, not of the original entity. 1140 transfer-coding = "chunked" | transfer-extension 1141 transfer-extension = token *( ";" parameter ) 1143 Parameters are in the form of attribute/value pairs. 1145 parameter = attribute "=" value 1146 attribute = token 1147 value = token | quoted-string 1149 All transfer-coding values are case-insensitive. HTTP/1.1 uses 1150 transfer-coding values in the TE header field (section 14.39) and in 1151 the Transfer-Encoding header field (section 14.41). 1153 Whenever a transfer-coding is applied to a message-body, the set of 1154 transfer-codings MUST include "chunked", unless the message is 1155 terminated by closing the connection. When the "chunked" transfer- 1156 coding is used, it MUST be the last transfer-coding applied to the 1157 message-body. The "chunked" transfer-coding MUST NOT be applied more 1158 than once to a message-body. These rules allow the recipient to 1159 determine the transfer-length of the message (section 4.4). 1161 Transfer-codings are analogous to the Content-Transfer-Encoding 1162 values of MIME [I7], which were designed to enable safe transport of 1163 binary data over a 7-bit transport service. However, safe transport 1164 has a different focus for an 8bit-clean transfer protocol. In HTTP, 1165 the only unsafe characteristic of message-bodies is the difficulty in 1166 determining the exact body length (section 7.2.2), or the desire to 1167 encrypt data over a shared transport. 1169 The Internet Assigned Numbers Authority (IANA) acts as a registry for 1170 transfer-coding value tokens. Initially, the registry contains the 1171 following tokens: "chunked" (section 3.6.1), "gzip" (section 3.5), 1172 "compress" (section 3.5), and "deflate" (section 3.5). 1174 New transfer-coding value tokens SHOULD be registered in the same way 1175 as new content-coding value tokens (section 3.5). 1177 A server which receives an entity-body with a transfer-coding it does 1178 not understand SHOULD return 501 (Unimplemented), and close the 1179 connection. A server MUST NOT send transfer-codings to an HTTP/1.0 1180 client. 1182 3.6.1 Chunked Transfer Coding 1184 The chunked encoding modifies the body of a message in order to 1185 transfer it as a series of chunks, each with its own size indicator, 1186 followed by an OPTIONAL trailer containing entity-header fields. This 1187 allows dynamically produced content to be transferred along with the 1189 information necessary for the recipient to verify that it has 1190 received the full message. 1192 Chunked-Body = *chunk 1193 last-chunk 1194 trailer 1195 CRLF 1196 chunk = chunk-size [ chunk-extension ] CRLF 1197 chunk-data CRLF 1198 chunk-size = 1*HEX 1199 last-chunk = 1*("0") [ chunk-extension ] CRLF 1201 chunk-extension= *( ";" chunk-ext-name [ "=" chunk-ext-val ] ) 1202 chunk-ext-name = token 1203 chunk-ext-val = token | quoted-string 1204 chunk-data = chunk-size(OCTET) 1205 trailer = *(entity-header CRLF) 1207 The chunk-size field is a string of hex digits indicating the size of 1208 the chunk-data in octets. The chunked encoding is ended by any chunk 1209 whose size is zero, followed by the trailer, which is terminated by 1210 an empty line. 1212 The trailer allows the sender to include additional HTTP header 1213 fields at the end of the message. The Trailer header field can be 1214 used to indicate which header fields are included in a trailer (see 1215 section 14.40). 1217 A server using chunked transfer-coding in a response MUST NOT use the 1218 trailer for any header fields unless at least one of the following is 1219 true: 1221 a) the request included a TE header field that indicates "trailers" 1222 is acceptable in the transfer-coding of the response, as described 1223 in section 14.39; or, 1225 b) the server is the origin server for the response, the trailer 1226 fields consist entirely of optional metadata, and the recipient 1227 could use the message (in a manner acceptable to the origin server) 1228 without receiving this metadata. In other words, the origin server 1229 is willing to accept the possibility that the trailer fields might 1230 be silently discarded along the path to the client. 1232 This requirement prevents an interoperability failure when the 1233 message is being received by an HTTP/1.1 (or later) proxy and 1234 forwarded to an HTTP/1.0 recipient. It avoids a situation where 1235 compliance with the protocol would have necessitated a possibly 1236 infinite buffer on the proxy. 1238 An example process for decoding a Chunked-Body is presented in 1239 appendix 17.4.6. 1241 All HTTP/1.1 applications MUST be able to receive and decode the 1242 "chunked" transfer-coding, and MUST ignore chunk-extension extensions 1243 they do not understand. 1245 3.7 Media Types 1247 HTTP uses Internet Media Types [N5] in the Content-Type (section 1248 14.17) and Accept (section 14.1) header fields in order to provide 1249 open and extensible data typing and type negotiation. 1251 media-type = type "/" subtype *( ";" parameter ) 1252 type = token 1253 subtype = token 1255 Parameters MAY follow the type/subtype in the form of attribute/value 1256 pairs (as defined in section 3.6). 1258 The type, subtype, and parameter attribute names are case- 1259 insensitive. Parameter values might or might not be case-sensitive, 1260 depending on the semantics of the parameter name. Linear white space 1261 (LWS) MUST NOT be used between the type and subtype, nor between an 1262 attribute and its value. The presence or absence of a parameter might 1263 be significant to the processing of a media-type, depending on its 1264 definition within the media type registry. 1266 Note that some older HTTP applications do not recognize media type 1267 parameters. When sending data to older HTTP applications, 1268 implementations SHOULD only use media type parameters when they are 1269 required by that type/subtype definition. 1271 Media-type values are registered with the Internet Assigned Number 1272 Authority (IANA [I14]). The media type registration process is 1273 outlined in RFC 2048 [N5]. Use of non-registered media types is 1274 discouraged. 1276 3.7.1 Canonicalization and Text Defaults 1278 Internet media types are registered with a canonical form. An entity- 1279 body transferred via HTTP messages MUST be represented in the 1280 appropriate canonical form prior to its transmission except for 1281 "text" types, as defined in the next paragraph. 1283 When in canonical form, media subtypes of the "text" type use CRLF as 1284 the text line break. HTTP relaxes this requirement and allows the 1285 transport of text media with plain CR or LF alone representing a line 1286 break when it is done consistently for an entire entity-body. HTTP 1287 applications MUST accept CRLF, bare CR, and bare LF as being 1288 representative of a line break in text media received via HTTP. In 1289 addition, if the text is represented in a character set that does not 1290 use octets 13 and 10 for CR and LF respectively, as is the case for 1291 some multi-byte character sets, HTTP allows the use of whatever octet 1292 sequences are defined by that character set to represent the 1293 equivalent of CR and LF for line breaks. This flexibility regarding 1294 line breaks applies only to text media in the entity-body; a bare CR 1295 or LF MUST NOT be substituted for CRLF within any of the HTTP control 1296 structures (such as header fields and multipart boundaries). 1297 If an entity-body is encoded with a content-coding, the underlying 1298 data MUST be in a form defined above prior to being encoded. 1299 The "charset" parameter is used with some media types to define the 1300 character set (section 3.4) of the data. When no explicit charset 1301 parameter is provided by the sender, media subtypes of the "text" 1302 type are defined to have a default charset value of "ISO-8859-1" when 1303 received via HTTP. Data in character sets other than "ISO-8859-1" or 1304 its subsets MUST be labeled with an appropriate charset value. See 1305 section 0 for compatibility problems. 1307 3.7.2 Multipart Types 1309 MIME provides for a number of "multipart" types -- encapsulations of 1310 one or more entities within a single message-body. All multipart 1311 types share a common syntax, as defined in section 5.1.1 of RFC 2046 1312 [N8], and MUST include a boundary parameter as part of the media type 1313 value. The message body is itself a protocol element and MUST 1314 therefore use only CRLF to represent line breaks between body-parts. 1316 Unlike in RFC 2046, the epilogue of any multipart message MUST be 1317 empty; HTTP applications MUST NOT transmit the epilogue (even if the 1318 original multipart contains an epilogue). These restrictions exist in 1319 order to preserve the self-delimiting nature of a multipart message- 1320 body, wherein the "end" of the message-body is indicated by the 1321 ending multipart boundary. 1323 In general, HTTP treats a multipart message-body no differently than 1324 any other media type: strictly as payload. The one exception is the 1325 "multipart/byteranges" type (appendix 17.2) when it appears in a 206 1326 (Partial Content) response, which will be interpreted by some HTTP 1327 caching mechanisms as described in sections 13.5.4 and 14.16. In all 1328 other cases, an HTTP user agent SHOULD follow the same or similar 1329 behavior as a MIME user agent would upon receipt of a multipart type. 1330 The MIME header fields within each body-part of a multipart message- 1331 body do not have any significance to HTTP beyond that defined by 1332 their MIME semantics. 1334 In general, an HTTP user agent SHOULD follow the same or similar 1335 behavior as a MIME user agent would upon receipt of a multipart type. 1336 If an application receives an unrecognized multipart subtype, the 1337 application MUST treat it as being equivalent to "multipart/mixed". 1339 Note: The "multipart/form-data" type has been specifically defined 1340 for carrying form data suitable for processing via the POST request 1341 method, as described in RFC 2388 [I11]. 1343 3.8 Product Tokens 1345 Product tokens are used to allow communicating applications to 1346 identify themselves by software name and version. Most fields using 1347 product tokens also allow sub-products which form a significant part 1348 of the application to be listed, separated by white space. By 1349 convention, the products are listed in order of their significance 1351 for identifying the application. 1353 product = token ["/" product-version] 1354 product-version = token 1356 Examples: 1358 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 1359 Server: Apache/0.8.4 1361 Product tokens SHOULD be short and to the point. They MUST NOT be 1362 used for advertising or other non-essential information. Although any 1363 token character MAY appear in a product-version, this token SHOULD 1364 only be used for a version identifier (i.e., successive versions of 1365 the same product SHOULD only differ in the product-version portion of 1366 the product value). 1368 3.9 Quality Values 1370 HTTP content negotiation (section 12) uses short "floating point" 1371 numbers to indicate the relative importance ("weight") of various 1372 negotiable parameters. A weight is normalized to a real number in 1373 the range 0 through 1, where 0 is the minimum and 1 the maximum 1374 value. If a parameter has a quality value of 0, then content with 1375 this parameter is "not acceptable" for the client. HTTP/1.1 1376 applications MUST NOT generate more than three digits after the 1377 decimal point. User configuration of these values SHOULD also be 1378 limited in this fashion. 1380 qvalue = ( "0" [ "." 0*3DIGIT ] ) 1381 | ( "1" [ "." 0*3("0") ] ) 1383 "Quality values" is a misnomer, since these values merely represent 1384 relative degradation in desired quality. 1386 3.10 Language Tags 1388 A language tag identifies a natural language spoken, written, or 1389 otherwise conveyed by human beings for communication of information 1390 to other human beings. Computer languages are explicitly excluded. 1391 HTTP uses language tags within the Accept-Language and Content- 1392 Language fields. 1394 The syntax and registry of HTTP language tags is the same as that 1395 defined by RFC 3066 [I1]. In summary, a language tag is composed of 1 1396 or more parts: A primary language tag and a possibly empty series of 1398 subtags: 1400 language-tag = primary-tag *( "-" subtag ) 1401 primary-tag = 1*8ALPHA 1402 subtag = 1*8(ALPHA / DIGIT) 1403 White space is not allowed within the tag and all tags are case- 1404 insensitive. The name space of language tags is administered by the 1405 IANA. Example tags include: 1407 en, en-US, en-cockney, i-cherokee, x-pig-latin 1409 where any two-letter primary-tag is an ISO-639 language abbreviation 1410 and any two-letter initial subtag is an ISO-3166 country code. (The 1411 last three tags above are not registered tags; all but the last are 1412 examples of tags which could be registered in future.) 1414 3.11 Entity Tags 1416 Entity tags are used for comparing two or more entities from the same 1417 requested resource. HTTP/1.1 uses entity tags in the ETag (section 1418 14.19), If-Match (section 14.24), If-None-Match (section 14.26), and 1419 If-Range (section 14.27) header fields. The definition of how they 1420 are used and compared as cache validators is in section 13.3.3. An 1421 entity tag consists of an opaque quoted string, possibly prefixed by 1422 a weakness indicator. 1424 entity-tag = [ weak ] opaque-tag 1425 weak = "W/" 1426 opaque-tag = quoted-string 1428 A "strong entity tag" MAY be shared by two entities of a resource 1429 only if they are equivalent by octet equality. 1431 A "weak entity tag," indicated by the "W/" prefix, MAY be shared by 1432 two entities of a resource only if the entities are equivalent and 1433 could be substituted for each other with no significant change in 1434 semantics. A weak entity tag can only be used for weak comparison. 1436 An entity tag MUST be unique across all versions of all entities 1437 associated with a particular resource. A given entity tag value MAY 1438 be used for entities obtained by requests on different URIs. The use 1439 of the same entity tag value in conjunction with entities obtained by 1440 requests on different URIs does not imply the equivalence of those 1441 entities. 1443 3.12 Range Units 1445 HTTP/1.1 allows a client to request that only part (a range of) the 1446 response entity be included within the response. HTTP/1.1 uses range 1447 units in the Range (section 14.35) and Content-Range (section 14.16) 1448 header fields. An entity can be broken down into subranges according 1449 to various structural units. 1451 range-unit = bytes-unit | other-range-unit 1452 bytes-unit = "bytes" 1453 other-range-unit = token 1455 The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1 1456 implementations MAY ignore ranges specified using other units. 1458 HTTP/1.1 has been designed to allow implementations of applications 1459 that do not depend on knowledge of ranges. 1461 4 HTTP Message 1463 4.1 Message Types 1465 HTTP messages consist of requests from client to server and responses 1466 from server to client. 1468 HTTP-message = Request | Response ; HTTP/1.1 messages 1470 Request (section 5) and Response (section 6) messages use the generic 1471 message format of RFC 822 [I9] for transferring entities (the payload 1472 of the message). Both types of message consist of a start-line, zero 1473 or more header fields (also known as "headers"), an empty line (i.e., 1474 a line with nothing preceding the CRLF) indicating the end of the 1475 header fields, and possibly a message-body. 1477 generic-message = start-line 1478 *(message-header CRLF) 1479 CRLF 1480 [ message-body ] 1481 start-line = Request-Line | Status-Line 1483 In the interest of robustness, servers SHOULD ignore any empty 1484 line(s) received where a Request-Line is expected. In other words, if 1485 the server is reading the protocol stream at the beginning of a 1486 message and receives a CRLF first, it should ignore the CRLF. 1488 Certain buggy HTTP/1.0 client implementations generate extra CRLF's 1489 after a POST request. To restate what is explicitly forbidden by the 1490 BNF, an HTTP/1.1 client MUST NOT preface or follow a request with an 1491 extra CRLF. 1493 4.2 Message Headers 1495 HTTP header fields, which include general-header (section 4.5), 1496 request-header (section 5.3), response-header (section 6.2), and 1497 entity-header (section 7.1) fields, follow the same generic format as 1498 that given in Section 3.1 of RFC 822 [I9]. Each header field consists 1499 of a name followed by a colon (":") and the field value. Field names 1500 are case-insensitive. The field value MAY be preceded by any amount 1501 of LWS, though a single SP is preferred. Header fields can be 1502 extended over multiple lines by preceding each extra line with at 1503 least one SP or HT. Applications ought to follow "common form", where 1504 one is known or indicated, when generating HTTP constructs, since 1505 there might exist some implementations that fail to accept anything 1507 beyond the common forms. 1509 message-header = field-name ":" [ field-value ] 1510 field-name = token 1511 field-value = *( field-content | LWS ) 1512 field-content = 1517 The field-content does not include any leading or trailing LWS: 1518 linear white space occurring before the first non-whitespace 1519 character of the field-value or after the last non-whitespace 1520 character of the field-value. Such leading or trailing LWS MAY be 1521 removed without changing the semantics of the field value. Any LWS 1522 that occurs between field-content MAY be replaced with a single SP 1523 before interpreting the field value or forwarding the message 1524 downstream. 1526 The order in which header fields with differing field names are 1527 received is not significant. However, it is "good practice" to send 1528 general-header fields first, followed by request-header or response- 1529 header fields, and ending with the entity-header fields. 1531 Multiple message-header fields with the same field-name MAY be 1532 present in a message if and only if the entire field-value for that 1533 header field is defined as a comma-separated list [i.e., #(values)]. 1534 It MUST be possible to combine the multiple header fields into one 1535 "field-name: field-value" pair, without changing the semantics of the 1536 message, by appending each subsequent field-value to the first, each 1537 separated by a comma. The order in which header fields with the same 1538 field-name are received is therefore significant to the 1539 interpretation of the combined field value, and thus a proxy MUST NOT 1540 change the order of these field values when a message is forwarded. 1542 All HTTP header field-names are registered according to the procedure 1543 in [I40]. 1545 4.3 Message Body 1547 The message-body (if any) of an HTTP message is used to carry the 1548 entity-body associated with the request or response. The message-body 1549 differs from the entity-body only when a transfer-coding has been 1550 applied, as indicated by the Transfer-Encoding header field (section 1551 14.41). 1553 message-body = entity-body 1554 | 1556 Transfer-Encoding MUST be used to indicate any transfer-codings 1557 applied by an application to ensure safe and proper transfer of the 1558 message. Transfer-Encoding is a property of the message, not of the 1559 entity, and thus MAY be added or removed by any application along the 1560 request/response chain. (However, section 3.6 places restrictions on 1561 when certain transfer-codings may be used.) 1563 The rules for when a message-body is allowed in a message differ for 1564 requests and responses. 1566 The presence of a message-body in a request is signaled by the 1567 inclusion of a Content-Length or Transfer-Encoding header field in 1568 the request�s message-headers. A message-body MUST NOT be included in 1569 a request if the specification of the request method (section 5.1.1) 1570 does not allow sending an entity-body in requests. A server SHOULD 1571 read and forward a message-body on any request; if the request method 1572 does not include defined semantics for an entity-body, then the 1573 message-body SHOULD be ignored when handling the request. 1575 For response messages, whether or not a message-body is included with 1576 a message is dependent on both the request method and the response 1577 status code (section 6.1.1). All responses to the HEAD request method 1578 MUST NOT include a message-body, even though the presence of entity- 1579 header fields might lead one to believe they do. All 1xx 1580 (informational), 204 (no content), and 304 (not modified) responses 1581 MUST NOT include a message-body. All other responses do include a 1582 message-body, although it MAY be of zero length. 1584 4.4 Message Length 1586 The transfer-length of a message is the length of the message-body as 1587 it appears in the message; that is, after any transfer-codings have 1588 been applied. When a message-body is included with a message, the 1589 transfer-length of that body is determined by one of the following 1590 (in order of precedence): 1592 1. Any response message which "MUST NOT" include a message-body (such 1593 as the 1xx, 204, and 304 responses and any response to a HEAD 1594 request) is always terminated by the first empty line after the 1595 header fields, regardless of the entity-header fields present in 1596 the message. 1598 2. If a Transfer-Encoding header field (section 14.41) is present then 1599 the transfer-length is defined by use of the "chunked" transfer- 1600 coding (section 3.6), unless the message is terminated by closing 1601 the connection. 1603 3. If a Content-Length header field (section 14.13) is present, its 1604 decimal value in OCTETs represents both the entity-length and the 1605 transfer-length. The Content-Length header field MUST NOT be sent 1606 if these two lengths are different (i.e., if a Transfer-Encoding 1607 header field is present). If a message is received with both a 1608 Transfer-Encoding header field and a Content-Length header field, 1609 the latter MUST be ignored. 1611 4. If the message uses the media type "multipart/byteranges", and the 1612 transfer-length is not otherwise specified, then this self- 1613 delimiting media type defines the transfer-length. This media type 1614 MUST NOT be used unless the sender knows that the recipient can 1615 parse it; the presence in a request of a Range header with multiple 1616 byte-range specifiers from a 1.1 client implies that the client can 1617 parse multipart/byteranges responses. 1619 A range header might be forwarded by a 1.0 proxy that does not 1620 understand multipart/byteranges; in this case the server MUST 1621 delimit the message using methods defined in items 1,3 or 5 of this 1622 section. 1624 5. By the server closing the connection. (Closing the connection 1625 cannot be used to indicate the end of a request body, since that 1626 would leave no possibility for the server to send back a response.) 1628 For compatibility with HTTP/1.0 applications, HTTP/1.1 requests 1629 containing a message-body MUST include a valid Content-Length header 1630 field unless the server is known to be HTTP/1.1 compliant. If a 1631 request contains a message-body and a Content-Length is not given, 1632 the server SHOULD respond with 400 (bad request) if it cannot 1633 determine the length of the message, or with 411 (length required) if 1634 it wishes to insist on receiving a valid Content-Length. 1636 All HTTP/1.1 applications that receive entities MUST accept the 1637 "chunked" transfer-coding (section 3.6), thus allowing this mechanism 1638 to be used for messages when the message length cannot be determined 1639 in advance. 1641 Messages MUST NOT include both a Content-Length header field and a 1642 transfer-coding. If the message does include a non-identity transfer- 1643 coding, the Content-Length MUST be ignored. 1645 When a Content-Length is given in a message where a message-body is 1646 allowed, its field value MUST exactly match the number of OCTETs in 1647 the message-body. HTTP/1.1 user agents MUST notify the user when an 1648 invalid length is received and detected. 1650 4.5 General Header Fields 1652 There are a few header fields which have general applicability for 1653 both request and response messages, but which do not apply to the 1654 entity being transferred. These header fields apply only to the 1655 message being transmitted. 1657 general-header = Cache-Control ; Section 14.9 1658 | Connection ; Section 14.10 1659 | Date ; Section 14.18 1660 | Pragma ; Section 14.32 1661 | Trailer ; Section 14.40 1662 | Transfer-Encoding ; Section 14.41 1663 | Upgrade ; Section 14.42 1664 | Via ; Section 14.45 1665 | Warning ; Section 14.46 1667 General-header field names can be extended reliably only in 1668 combination with a change in the protocol version. However, new or 1669 experimental header fields may be given the semantics of general 1670 header fields if all parties in the communication recognize them to 1671 be general-header fields. Unrecognized header fields are treated as 1672 entity-header fields. 1674 5 Request 1676 A request message from a client to a server includes, within the 1677 first line of that message, the method to be applied to the resource, 1678 the identifier of the resource, and the protocol version in use. 1680 Request = Request-Line ; Section 5.1 1681 *(( general-header ; Section 4.5 1682 | request-header ; Section 5.3 1683 | entity-header ) CRLF) ; Section 7.1 1684 CRLF 1685 [ message-body ] ; Section 4.3 1686 5.1 Request-Line 1688 The Request-Line begins with a method token, followed by the Request- 1689 URI and the protocol version, and ending with CRLF. The elements are 1690 separated by SP characters. No CR or LF is allowed except in the 1691 final CRLF sequence. 1693 Request-Line = Method SP Request-URI SP HTTP-Version CRLF 1695 5.1.1 Method 1697 The Method token indicates the method to be performed on the 1698 resource identified by the Request-URI. The method is case-sensitive. 1700 Method = "OPTIONS" ; Section 9.2 1701 | "GET" ; Section 9.3 1702 | "HEAD" ; Section 9.4 1703 | "POST" ; Section 9.5 1704 | "PUT" ; Section 9.6 1705 | "DELETE" ; Section 9.7 1706 | "TRACE" ; Section 9.8 1707 | "CONNECT" ; Section 9.9 1708 | extension-method 1709 extension-method = token 1711 The list of methods allowed by a resource can be specified in an 1712 Allow header field (section 14.7). The return code of the response 1713 always notifies the client whether a method is currently allowed on a 1714 resource, since the set of allowed methods can change dynamically. An 1715 origin server SHOULD return the status code 405 (Method Not Allowed) 1716 if the method is known by the origin server but not allowed for the 1717 requested resource, and 501 (Not Implemented) if the method is 1718 unrecognized or not implemented by the origin server. The methods GET 1719 and HEAD MUST be supported by all general-purpose servers. All other 1720 methods are OPTIONAL; however, if the above methods are implemented, 1721 they MUST be implemented with the same semantics as those specified 1722 in section 9. 1724 5.1.2 Request-URI 1726 The Request-URI is a Uniform Resource Identifier (section 3.2) and 1727 identifies the resource upon which to apply the request. 1729 Request-URI = "*" | absoluteURI 1730 | abs_path ["?" query ]| authority 1732 The four options for Request-URI are dependent on the nature of the 1733 request. The asterisk "*" means that the request does not apply to a 1734 particular resource, but to the server itself, and is only allowed 1735 when the method used does not necessarily apply to a resource. One 1736 example would be 1738 OPTIONS * HTTP/1.1 1740 The absoluteURI form is REQUIRED when the request is being made to a 1741 proxy. The proxy is requested to forward the request or service it 1742 from a valid cache, and return the response. Note that the proxy MAY 1743 forward the request on to another proxy or directly to the server 1744 specified by the absoluteURI. In order to avoid request loops, a 1745 proxy MUST be able to recognize all of its server names, including 1746 any aliases, local variations, and the numeric IP address. An example 1747 Request-Line would be: 1749 GET http://www.w3.org/pub/WWW/TheProject.html HTTP/1.1 1751 To allow for transition to absoluteURIs in all requests in future 1752 versions of HTTP, all HTTP/1.1 servers MUST accept the absoluteURI 1753 form in requests, even though HTTP/1.1 clients will only generate 1754 them in requests to proxies. 1756 The authority form is only used by the CONNECT method (section 9.9). 1758 The most common form of Request-URI is that used to identify a 1759 resource on an origin server or gateway. In this case the absolute 1760 path of the URI MUST be transmitted (see section 3.2.1, abs_path) as 1761 the Request-URI, and the network location of the URI (authority) MUST 1762 be transmitted in a Host header field. For example, a client wishing 1763 to retrieve the resource above directly from the origin server would 1764 create a TCP connection to port 80 of the host "www.w3.org" and send 1765 the lines: 1767 GET /pub/WWW/TheProject.html HTTP/1.1 1768 Host: www.w3.org 1770 followed by the remainder of the Request. Note that the absolute path 1771 cannot be empty; if none is present in the original URI, it MUST be 1772 given as "/" (the server root). 1774 The Request-URI is transmitted in the format specified in section 1775 3.2.1. If the Request-URI is encoded using the "% HEX HEX" encoding 1776 [N9], the origin server MUST decode the Request-URI in order to 1777 properly interpret the request. Servers SHOULD respond to invalid 1778 Request-URIs with an appropriate status code. 1780 A transparent proxy MUST NOT rewrite the "abs_path" part of the 1781 received Request-URI when forwarding it to the next inbound server, 1782 except as noted above to replace a null abs_path with "/". 1784 Note: The "no rewrite" rule prevents the proxy from changing the 1785 meaning of the request when the origin server is improperly using a 1786 non-reserved URI character for a reserved purpose. Implementors 1787 should be aware that some pre-HTTP/1.1 proxies have been known to 1788 rewrite the Request-URI. 1790 5.2 The Resource Identified by a Request 1792 The exact resource identified by an Internet request is determined by 1793 examining both the Request-URI and the Host header field. 1795 An origin server that does not allow resources to differ by the 1796 requested host MAY ignore the Host header field value when 1797 determining the resource identified by an HTTP/1.1 request. (But see 1798 section 17.6.1.1 for other requirements on Host support in HTTP/1.1.) 1799 An origin server that does differentiate resources based on the host 1800 requested (sometimes referred to as virtual hosts or vanity host 1801 names) MUST use the following rules for determining the requested 1802 resource on an HTTP/1.1 request: 1804 1. If Request-URI is an absoluteURI, the host is part of the Request- 1805 URI. Any Host header field value in the request MUST be ignored. 1807 2. If the Request-URI is not an absoluteURI, and the request includes 1808 a Host header field, the host is determined by the Host header 1809 field value. 1811 3. If the host as determined by rule 1 or 2 is not a valid host on 1812 the server, the response MUST be a 400 (Bad Request) error message. 1814 Recipients of an HTTP/1.0 request that lacks a Host header field MAY 1815 attempt to use heuristics (e.g., examination of the URI path for 1816 something unique to a particular host) in order to determine what 1817 exact resource is being requested. 1819 5.3 Request Header Fields 1821 The request-header fields allow the client to pass additional 1822 information about the request, and about the client itself, to the 1823 server. These fields act as request modifiers, with semantics 1824 equivalent to the parameters on a programming language method 1825 invocation. 1827 request-header = Accept ; Section 14.1 1828 | Accept-Charset ; Section 14.2 1829 | Accept-Encoding ; Section 14.3 1830 | Accept-Language ; Section 14.4 1831 | Authorization ; Section 14.8 1832 | Expect ; Section 14.20 1833 | From ; Section 14.22 1834 | Host ; Section 14.23 1835 | If-Match ; Section 14.24 1836 | If-Modified-Since ; Section 14.25 1837 | If-None-Match ; Section 14.26 1838 | If-Range ; Section 14.27 1839 | If-Unmodified-Since ; Section 14.28 1840 | Max-Forwards ; Section 14.31 1841 | Proxy-Authorization ; Section 14.34 1842 | Range ; Section 14.35 1843 | Referer ; Section 14.36 1844 | TE ; Section 14.39 1845 | User-Agent ; Section 14.43 1847 Request-header field names can be extended reliably only in 1848 combination with a change in the protocol version. However, new or 1849 experimental header fields MAY be given the semantics of request- 1850 header fields if all parties in the communication recognize them to 1851 be request-header fields. Unrecognized header fields are treated as 1852 entity-header fields. 1854 6 Response 1856 After receiving and interpreting a request message, a server responds 1857 with an HTTP response message. 1859 Response = Status-Line ; Section 6.1 1860 *(( general-header ; Section 4.5 1861 | response-header ; Section 6.2 1862 | entity-header ) CRLF) ; Section 7.1 1863 CRLF 1864 [ message-body ] ; Section 7.2 1865 6.1 Status-Line 1867 The first line of a Response message is the Status-Line, consisting 1868 of the protocol version followed by a numeric status code and its 1869 associated textual phrase, with each element separated by SP 1870 characters. No CR or LF is allowed except in the final CRLF sequence. 1872 Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF 1874 6.1.1 Status Code and Reason Phrase 1876 The Status-Code element is a 3-digit integer result code of the 1877 attempt to understand and satisfy the request. These codes are fully 1878 defined in section 10. The Reason-Phrase is intended to give a short 1879 textual description of the Status-Code. The Status-Code is intended 1880 for use by automata and the Reason-Phrase is intended for the human 1881 user. The client is not required to examine or display the Reason- 1882 Phrase. 1884 The first digit of the Status-Code defines the class of response. The 1885 last two digits do not have any categorization role. There are 5 1886 values for the first digit: 1888 o 1xx: Informational - Request received, continuing process 1889 o 2xx: Success - The action was successfully received, understood, 1890 and accepted 1891 o 3xx: Redirection - Further action must be taken in order to 1892 complete the request 1893 o 4xx: Client Error - The request contains bad syntax or cannot be 1894 fulfilled 1895 o 5xx: Server Error - The server failed to fulfill an apparently 1896 valid request 1897 The individual values of the numeric status codes defined for 1898 HTTP/1.1, and an example set of corresponding Reason-Phrase's, are 1899 presented below. The reason phrases listed here are only 1900 recommendations -- they MAY be replaced by local equivalents without 1901 affecting the protocol. 1903 Status-Code = 1904 "100" ; Section 10.1.1: Continue 1905 | "101" ; Section 10.1.2: Switching Protocols 1906 | "200" ; Section 10.2.1: OK 1907 | "201" ; Section 10.2.2: Created 1908 | "202" ; Section 10.2.3: Accepted 1909 | "203" ; Section 10.2.4: Non-Authoritative Information 1910 | "204" ; Section 10.2.5: No Content 1911 | "205" ; Section 10.2.6: Reset Content 1912 | "206" ; Section 10.2.7: Partial Content 1913 | "300" ; Section 10.3.1: Multiple Choices 1914 | "301" ; Section 10.3.2: Moved Permanently 1915 | "302" ; Section 10.3.3: Found 1916 | "303" ; Section 10.3.4: See Other 1917 | "304" ; Section 10.3.5: Not Modified 1918 | "305" ; Section 10.3.6: Use Proxy 1919 | "307" ; Section 10.3.8: Temporary Redirect 1920 | "400" ; Section 10.4.1: Bad Request 1921 | "401" ; Section 10.4.2: Unauthorized 1922 | "402" ; Section 10.4.3: Payment Required 1923 | "403" ; Section 10.4.4: Forbidden 1924 | "404" ; Section 10.4.5: Not Found 1925 | "405" ; Section 10.4.6: Method Not Allowed 1926 | "406" ; Section 10.4.7: Not Acceptable 1927 | "407" ; Section 10.4.8: Proxy Authentication Required 1928 | "408" ; Section 10.4.9: Request Time-out 1929 | "409" ; Section 10.4.10: Conflict 1930 | "410" ; Section 10.4.11: Gone 1931 | "411" ; Section 10.4.12: Length Required 1932 | "412" ; Section 10.4.13: Precondition Failed 1933 | "413" ; Section 10.4.14: Request Entity Too Large 1934 | "414" ; Section 10.4.15: Request-URI Too Large 1935 | "415" ; Section 10.4.16: Unsupported Media Type 1936 | "416" ; Section 10.4.17: Requested range not satisfiable 1937 | "417" ; Section 10.4.18: Expectation Failed 1938 | "500" ; Section 10.5.1: Internal Server Error 1939 | "501" ; Section 10.5.2: Not Implemented 1940 | "502" ; Section 10.5.3: Bad Gateway 1941 | "503" ; Section 10.5.4: Service Unavailable 1942 | "504" ; Section 10.5.5: Gateway Time-out 1943 | "505" ; Section 10.5.6: HTTP Version not supported 1944 | extension-code 1945 extension-code = 3DIGIT 1946 Reason-Phrase = * 1948 HTTP status codes are extensible. HTTP applications are not required 1949 to understand the meaning of all registered status codes, though such 1950 understanding is obviously desirable. However, applications MUST 1951 understand the class of any status code, as indicated by the first 1952 digit, and treat any unrecognized response as being equivalent to the 1953 x00 status code of that class, with the exception that an 1954 unrecognized response MUST NOT be cached. For example, if an 1955 unrecognized status code of 431 is received by the client, it can 1956 safely assume that there was something wrong with its request and 1957 treat the response as if it had received a 400 status code. In such 1958 cases, user agents SHOULD present to the user the entity returned 1959 with the response, since that entity is likely to include human- 1960 readable information which will explain the unusual status. 1962 6.2 Response Header Fields 1964 The response-header fields allow the server to pass additional 1965 information about the response which cannot be placed in the Status- 1966 Line. These header fields give information about the server and about 1967 further access to the resource identified by the Request-URI. 1969 response-header = Accept-Ranges ; Section 14.5 1970 | Age ; Section 14.6 1971 | ETag ; Section 14.19 1972 | Location ; Section 14.30 1973 | Proxy-Authenticate ; Section 14.33 1974 | Retry-After ; Section 14.37 1975 | Server ; Section 14.38 1976 | Vary ; Section 14.44 1977 | WWW-Authenticate ; Section 14.47 1979 Response-header field names can be extended reliably only in 1980 combination with a change in the protocol version. However, new or 1981 experimental header fields MAY be given the semantics of response- 1982 header fields if all parties in the communication recognize them to 1983 be response-header fields. Unrecognized header fields are treated as 1984 entity-header fields. 1986 7 Entity 1988 Request and Response messages MAY transfer an entity if not otherwise 1989 restricted by the request method or response status code. An entity 1990 consists of entity-header fields and an entity-body, although some 1991 responses will only include the entity-headers. 1993 In this section, both sender and recipient refer to either the client 1994 or the server, depending on who sends and who receives the entity. 1996 7.1 Entity Header Fields 1998 Entity-header fields define metainformation about the entity-body or, 1999 if no body is present, about the resource identified by the request. 2000 Some of this metainformation is OPTIONAL; some might be REQUIRED by 2001 portions of this specification. 2003 entity-header = Allow ; Section 14.7 2004 | Content-Encoding ; Section 14.11 2005 | Content-Language ; Section 14.12 2006 | Content-Length ; Section 14.13 2007 | Content-Location ; Section 14.14 2008 | Content-MD5 ; Section 14.15 2009 | Content-Range ; Section 14.16 2010 | Content-Type ; Section 14.17 2011 | Expires ; Section 14.21 2012 | Last-Modified ; Section 14.29 2013 | extension-header 2014 extension-header = message-header 2016 The extension-header mechanism allows additional entity-header fields 2017 to be defined without changing the protocol, but these fields cannot 2018 be assumed to be recognizable by the recipient. Unrecognized header 2019 fields SHOULD be ignored by the recipient and MUST be forwarded by 2020 transparent proxies. 2022 7.2 Entity Body 2024 The entity-body (if any) sent with an HTTP request or response is in 2025 a format and encoding defined by the entity-header fields. 2027 entity-body = *OCTET 2029 An entity-body is only present in a message when a message-body is 2030 present, as described in section 4.3. The entity-body is obtained 2031 from the message-body by decoding any Transfer-Encoding that might 2032 have been applied to ensure safe and proper transfer of the message. 2034 7.2.1 Type 2036 When an entity-body is included with a message, the data type of that 2037 body is determined via the header fields Content-Type and Content- 2038 Encoding. These define a two-layer, ordered encoding model: 2040 entity-body := Content-Encoding( Content-Type( data ) ) 2042 Content-Type specifies the media type of the underlying data. 2043 Content-Encoding may be used to indicate any additional content 2044 codings applied to the data, usually for the purpose of data 2045 compression, that are a property of the requested resource. There is 2046 no default encoding. 2048 Any HTTP/1.1 message containing an entity-body SHOULD include a 2049 Content-Type header field defining the media type of that body. If 2050 and only if the media type is not given by a Content-Type field, the 2051 recipient MAY attempt to guess the media type via inspection of its 2052 content and/or the name extension(s) of the URI used to identify the 2053 resource. If the media type remains unknown, the recipient SHOULD 2054 treat it as type "application/octet-stream". 2056 7.2.2 Entity Length 2058 The entity-length of a message is the length of the message-body 2059 before any transfer-codings have been applied. Section 4.4 defines 2060 how the transfer-length of a message-body is determined. 2062 8 Connections 2064 8.1 Persistent Connections 2066 8.1.1 Purpose 2068 Prior to persistent connections, a separate TCP connection was 2069 established to fetch each URL, increasing the load on HTTP servers 2070 and causing congestion on the Internet. The use of inline images and 2071 other associated data often require a client to make multiple 2072 requests of the same server in a short amount of time. Analysis of 2073 these performance problems and results from a prototype 2074 implementation are available [I19] [I23]. Implementation experience 2075 and measurements of actual HTTP/1.1 (RFC 2068) implementations show 2076 good results [I31]. Alternatives have also been explored, for 2077 example, T/TCP [I20]. 2079 Persistent HTTP connections have a number of advantages: 2081 o By opening and closing fewer TCP connections, CPU time is saved in 2082 routers and hosts (clients, servers, proxies, gateways, tunnels, or 2083 caches), and memory used for TCP protocol control blocks can be 2084 saved in hosts. 2085 o HTTP requests and responses can be pipelined on a connection. 2086 Pipelining allows a client to make multiple requests without 2087 waiting for each response, allowing a single TCP connection to be 2088 used much more efficiently, with much lower elapsed time. 2089 o Network congestion is reduced by reducing the number of packets 2090 caused by TCP opens, and by allowing TCP sufficient time to 2091 determine the congestion state of the network. 2092 o Latency on subsequent requests is reduced since there is no time 2093 spent in TCP�s connection opening handshake. 2094 o HTTP can evolve more gracefully, since errors can be reported 2095 without the penalty of closing the TCP connection. Clients using 2096 future versions of HTTP might optimistically try a new feature, but 2097 if communicating with an older server, retry with old semantics 2098 after an error is reported. 2100 HTTP implementations SHOULD implement persistent connections. 2102 8.1.2 Overall Operation 2104 A significant difference between HTTP/1.1 and earlier versions of 2105 HTTP is that persistent connections are the default behavior of any 2106 HTTP connection. That is, unless otherwise indicated, the client 2107 SHOULD assume that the server will maintain a persistent connection, 2108 even after error responses from the server. 2110 Persistent connections provide a mechanism by which a client and a 2111 server can signal the close of a TCP connection. This signaling takes 2112 place using the Connection header field (section 14.10). Once a close 2113 has been signaled, the client MUST NOT send any more requests on that 2114 connection. 2116 8.1.2.1 Negotiation 2118 An HTTP/1.1 server MAY assume that a HTTP/1.1 client intends to 2119 maintain a persistent connection unless a Connection header including 2120 the connection-token "close" was sent in the request. If the server 2121 chooses to close the connection immediately after sending the 2122 response, it SHOULD send a Connection header including the 2123 connection-token close. 2125 An HTTP/1.1 client MAY expect a connection to remain open, but would 2126 decide to keep it open based on whether the response from a server 2127 contains a Connection header with the connection-token close. In case 2128 the client does not want to maintain a connection for more than that 2130 request, it SHOULD send a Connection header including the connection- 2131 token close. 2133 If either the client or the server sends the close token in the 2134 Connection header, that request becomes the last one for the 2135 connection. 2137 Clients and servers SHOULD NOT assume that a persistent connection is 2138 maintained for HTTP versions less than 1.1 unless it is explicitly 2139 signaled. See section 17.6.2 for more information on backward 2140 compatibility with HTTP/1.0 clients. 2142 In order to remain persistent, all messages on the connection MUST 2143 have a self-defined message length (i.e., one not defined by closure 2144 of the connection), as described in section 4.4. 2146 8.1.2.2 Pipelining 2147 A client that supports persistent connections MAY "pipeline" its 2148 requests (i.e., send multiple requests without waiting for each 2149 response). A server MUST send its responses to those requests in the 2150 same order that the requests were received. 2152 Clients which assume persistent connections and pipeline immediately 2153 after connection establishment SHOULD be prepared to retry their 2154 connection if the first pipelined attempt fails. If a client does 2155 such a retry, it MUST NOT pipeline before it knows the connection is 2156 persistent. Clients MUST also be prepared to resend their requests if 2157 the server closes the connection before sending all of the 2158 corresponding responses. 2160 Clients SHOULD NOT pipeline requests using non-idempotent methods or 2161 non-idempotent sequences of methods (see section 9.1.2). Otherwise, a 2162 premature termination of the transport connection could lead to 2163 indeterminate results. A client wishing to send a non-idempotent 2164 request SHOULD wait to send that request until it has received the 2165 response status for the previous request. 2167 8.1.3 Proxy Servers 2169 It is especially important that proxies correctly implement the 2170 properties of the Connection header field as specified in section 2171 14.10. 2173 The proxy server MUST signal persistent connections separately with 2174 its clients and the origin servers (or other proxy servers) that it 2175 connects to. Each persistent connection applies to only one transport 2176 link. 2178 A proxy server MUST NOT establish a HTTP/1.1 persistent connection 2179 with an HTTP/1.0 client (but see RFC 2068 [I25] for information and 2180 discussion of the problems with the Keep-Alive header implemented by 2181 many HTTP/1.0 clients). 2183 8.1.4 Practical Considerations 2185 Servers will usually have some time-out value beyond which they will 2186 no longer maintain an inactive connection. Proxy servers might make 2187 this a higher value since it is likely that the client will be making 2188 more connections through the same server. The use of persistent 2189 connections places no requirements on the length (or existence) of 2190 this time-out for either the client or the server. 2192 When a client or server wishes to time-out it SHOULD issue a graceful 2193 close on the transport connection. Clients and servers SHOULD both 2194 constantly watch for the other side of the transport close, and 2195 respond to it as appropriate. If a client or server does not detect 2197 the other side's close promptly it could cause unnecessary resource 2198 drain on the network. 2200 A client, server, or proxy MAY close the transport connection at any 2201 time. For example, a client might have started to send a new request 2202 at the same time that the server has decided to close the "idle" 2203 connection. From the server�s point of view, the connection is being 2204 closed while it was idle, but from the client's point of view, a 2205 request is in progress. 2207 This means that clients, servers, and proxies MUST be able to recover 2208 from asynchronous close events. Client software SHOULD reopen the 2209 transport connection and retransmit the aborted sequence of requests 2210 without user interaction so long as the request sequence is 2211 idempotent (see section 9.1.2). Non-idempotent methods or sequences 2212 MUST NOT be automatically retried, although user agents MAY offer a 2213 human operator the choice of retrying the request(s). Confirmation by 2214 user-agent software with semantic understanding of the application 2215 MAY substitute for user confirmation. The automatic retry SHOULD NOT 2216 be repeated if the second sequence of requests fails. 2218 Servers SHOULD always respond to at least one request per connection, 2219 if at all possible. Servers SHOULD NOT close a connection in the 2220 middle of transmitting a response, unless a network or client failure 2221 is suspected. 2223 Clients that use persistent connections SHOULD limit the number of 2224 simultaneous connections that they maintain to a given server. A 2225 single-user client SHOULD NOT maintain more than 2 connections with 2226 any server or proxy. A proxy SHOULD use up to 2*N connections to 2227 another server or proxy, where N is the number of simultaneously 2228 active users. These guidelines are intended to improve HTTP response 2229 times and avoid congestion. 2231 8.2 Message Transmission Requirements 2233 8.2.1 Persistent Connections and Flow Control 2235 HTTP/1.1 servers SHOULD maintain persistent connections and use TCP's 2236 flow control mechanisms to resolve temporary overloads, rather than 2237 terminating connections with the expectation that clients will retry. 2238 The latter technique can exacerbate network congestion. 2240 8.2.2 Monitoring Connections for Error Status Messages 2242 An HTTP/1.1 (or later) client sending a message-body SHOULD monitor 2243 the network connection for an error status while it is transmitting 2244 the request. If the client sees an error status, it SHOULD 2245 immediately cease transmitting the body. If the body is being sent 2246 using a "chunked" encoding (section 3.6), a zero length chunk and 2247 empty trailer MAY be used to prematurely mark the end of the message. 2248 If the body was preceded by a Content-Length header, the client MUST 2249 close the connection. 2251 8.2.3 Use of the 100 (Continue) Status 2253 The purpose of the 100 (Continue) status (see section 10.1.1) is to 2254 allow a client that is sending a request message with a request body 2255 to determine if the origin server is willing to accept the request 2256 (based on the request headers) before the client sends the request 2257 body. In some cases, it might either be inappropriate or highly 2258 inefficient for the client to send the body if the server will reject 2259 the message without looking at the body. 2261 Requirements for HTTP/1.1 clients: 2262 o If a client will wait for a 100 (Continue) response before sending 2263 the request body, it MUST send an Expect request-header field 2264 (section 14.20) with the "100-continue" expectation. 2265 o A client MUST NOT send an Expect request-header field (section 2266 14.20) with the "100-continue" expectation if it does not intend to 2267 send a request body. 2269 Because of the presence of older implementations, the protocol allows 2270 ambiguous situations in which a client may send "Expect: 100- 2271 continue" without receiving either a 417 (Expectation Failed) status 2272 or a 100 (Continue) status. Therefore, when a client sends this 2273 header field to an origin server (possibly via a proxy) from which it 2274 has never seen a 100 (Continue) status, the client SHOULD NOT wait 2275 for an indefinite period before sending the request body. 2277 Requirements for HTTP/1.1 origin servers: 2279 o Upon receiving a request which includes an Expect request-header 2280 field with the "100-continue" expectation, an origin server MUST 2281 either respond with 100 (Continue) status and continue to read from 2282 the input stream, or respond with a final status code. The origin 2283 server MUST NOT wait for the request body before sending the 100 2284 (Continue) response. If it responds with a final status code, it 2285 MAY close the transport connection or it MAY continue to read and 2286 discard the rest of the request. It MUST NOT perform the requested 2287 method if it returns a final status code. 2289 o An origin server SHOULD NOT send a 100 (Continue) response if the 2290 request message does not include an Expect request-header field 2291 with the "100-continue" expectation, and MUST NOT send a 100 2292 (Continue) response if such a request comes from an HTTP/1.0 (or 2293 earlier) client. There is an exception to this rule: for 2294 compatibility with RFC 2068, a server MAY send a 100 (Continue) 2295 status in response to an HTTP/1.1 PUT or POST request that does not 2296 include an Expect request-header field with the "100-continue" 2297 expectation. This exception, the purpose of which is to minimize 2298 any client processing delays associated with an undeclared wait for 2299 100 (Continue) status, applies only to HTTP/1.1 requests, and not 2300 to requests with any other HTTP-version value. 2302 o An origin server MAY omit a 100 (Continue) response if it has 2303 already received some or all of the request body for the 2304 corresponding request. 2306 o An origin server that sends a 100 (Continue) response MUST 2307 ultimately send a final status code, once the request body is 2308 received and processed, unless it terminates the transport 2309 connection prematurely. 2311 o If an origin server receives a request that does not include an 2312 Expect request-header field with the "100-continue" expectation, 2313 the request includes a request body, and the server responds with a 2314 final status code before reading the entire request body from the 2315 transport connection, then the server SHOULD NOT close the 2316 transport connection until it has read the entire request, or until 2317 the client closes the connection. Otherwise, the client might not 2318 reliably receive the response message. However, this requirement is 2319 not be construed as preventing a server from defending itself 2320 against denial-of-service attacks, or from badly broken client 2321 implementations. 2323 Requirements for HTTP/1.1 proxies: 2325 o If a proxy receives a request that includes an Expect request- 2326 header field with the "100-continue" expectation, and the proxy 2327 either knows that the next-hop server complies with HTTP/1.1 or 2328 higher, or does not know the HTTP version of the next-hop server, 2329 it MUST forward the request, including the Expect header field. 2331 o If the proxy knows that the version of the next-hop server is 2332 HTTP/1.0 or lower, it MUST NOT forward the request, and it MUST 2333 respond with a 417 (Expectation Failed) status. 2335 o Proxies SHOULD maintain a cache recording the HTTP version numbers 2336 received from recently-referenced next-hop servers. 2338 o A proxy MUST NOT forward a 100 (Continue) response if the request 2339 message was received from an HTTP/1.0 (or earlier) client and did 2340 not include an Expect request-header field with the "100-continue" 2341 expectation. This requirement overrides the general rule for 2342 forwarding of 1xx responses (see section 10.1). 2344 8.2.4 Client Behavior if Server Prematurely Closes Connection 2346 If an HTTP/1.1 client sends a request which includes a request body, 2347 but which does not include an Expect request-header field with the 2348 "100-continue" expectation, and if the client is not directly 2349 connected to an HTTP/1.1 origin server, and if the client sees the 2350 connection close before receiving any status from the server, the 2351 client SHOULD retry the request. If the client does retry this 2352 request, it MAY use the following "binary exponential backoff" 2353 algorithm to be assured of obtaining a reliable response: 2355 1. Initiate a new connection to the server 2357 2. Transmit the request-headers 2359 3. Initialize a variable R to the estimated round-trip time to the 2360 server (e.g., based on the time it took to establish the 2361 connection), or to a constant value of 5 seconds if the round-trip 2362 time is not available. 2364 4. Compute T = R * (2**N), where N is the number of previous retries 2365 of this request. 2367 5. Wait either for an error response from the server, or for T seconds 2368 (whichever comes first) 2370 6. If no error response is received, after T seconds transmit the body 2371 of the request. 2373 7. If client sees that the connection is closed prematurely, repeat 2374 from step 1 until the request is accepted, an error response is 2375 received, or the user becomes impatient and terminates the retry 2376 process. 2378 If at any point an error status is received, the client 2380 o SHOULD NOT continue and 2381 o SHOULD close the connection if it has not completed sending the 2382 request message. 2384 9 Method Definitions 2386 The set of common methods for HTTP/1.1 is defined below. Although 2387 this set can be expanded, additional methods cannot be assumed to 2388 share the same semantics for separately extended clients and servers. 2390 The Host request-header field (section 14.23) MUST accompany all 2391 HTTP/1.1 requests. 2393 9.1 Safe and Idempotent Methods 2395 9.1.1 Safe Methods 2397 Implementors should be aware that the software represents the user in 2398 their interactions over the Internet, and should be careful to allow 2399 the user to be aware of any actions they might take which may have an 2400 unexpected significance to themselves or others. 2402 In particular, the convention has been established that the GET and 2403 HEAD methods SHOULD NOT have the significance of taking an action 2404 other than retrieval. These methods ought to be considered "safe". 2406 This allows user agents to represent other methods, such as POST, PUT 2407 and DELETE, in a special way, so that the user is made aware of the 2408 fact that a possibly unsafe action is being requested. 2410 Naturally, it is not possible to ensure that the server does not 2411 generate side-effects as a result of performing a GET request; in 2412 fact, some dynamic resources consider that a feature. The important 2413 distinction here is that the user did not request the side-effects, 2414 so therefore cannot be held accountable for them. 2416 9.1.2 Idempotent Methods 2418 Methods can also have the property of "idempotence" in that (aside 2419 from error or expiration issues) the side-effects of N > 0 identical 2420 requests is the same as for a single request. The methods GET, HEAD, 2421 PUT and DELETE share this property. Also, the methods OPTIONS and 2422 TRACE SHOULD NOT have side effects, and so are inherently idempotent. 2424 However, it is possible that a sequence of several requests is non- 2425 idempotent, even if all of the methods executed in that sequence are 2426 idempotent. (A sequence is idempotent if a single execution of the 2427 entire sequence always yields a result that is not changed by a 2428 reexecution of all, or part, of that sequence.) For example, a 2429 sequence is non-idempotent if its result depends on a value that is 2430 later modified in the same sequence. 2432 A sequence that never has side effects is idempotent, by definition 2433 (provided that no concurrent operations are being executed on the 2434 same set of resources). 2436 9.2 OPTIONS 2438 The OPTIONS method represents a request for information about the 2439 communication options available on the request/response chain 2440 identified by the Request-URI. This method allows the client to 2441 determine the options and/or requirements associated with a resource, 2442 or the capabilities of a server, without implying a resource action 2443 or initiating a resource retrieval. 2445 Responses to this method are not cacheable. 2447 If the OPTIONS request includes an entity-body (as indicated by the 2448 presence of Content-Length or Transfer-Encoding), then the media type 2449 MUST be indicated by a Content-Type field. Although this 2450 specification does not define any use for such a body, future 2451 extensions to HTTP might use the OPTIONS body to make more detailed 2452 queries on the server. A server that does not support such an 2453 extension MAY discard the request body. 2455 If the Request-URI is an asterisk ("*"), the OPTIONS request is 2456 intended to apply to the server in general rather than to a specific 2457 resource. Since a server's communication options typically depend on 2458 the resource, the "*" request is only useful as a "ping" or "no-op" 2459 type of method. For example, this can be used to test a proxy for 2460 OPTIONS method support (or lack thereof). 2462 If the Request-URI is not an asterisk, the OPTIONS request applies 2463 only to the options that are available when communicating with that 2464 resource. 2466 A 200 response SHOULD include any header fields that indicate 2467 optional features implemented by the server and applicable to that 2468 resource (e.g., Allow), possibly including extensions not defined by 2469 this specification. The response body, if any, SHOULD also include 2470 information about the communication options. The format for such a 2471 body is not defined by this specification, but might be defined by 2472 future extensions to HTTP. Content negotiation MAY be used to select 2473 the appropriate response format. If no response body is included, the 2474 response MUST include a Content-Length field with a field-value of 2475 "0". 2477 The Max-Forwards request-header field MAY be used to target a 2478 specific proxy in the request chain. When a proxy receives an OPTIONS 2479 request on an absoluteURI for which request forwarding is permitted, 2480 the proxy MUST check for a Max-Forwards field. If the Max-Forwards 2481 field-value is zero ("0"), the proxy MUST NOT forward the message; 2482 instead, the proxy SHOULD respond with its own communication options. 2483 If the Max-Forwards field-value is an integer greater than zero, the 2484 proxy MUST decrement the field-value when it forwards the request. If 2485 no Max-Forwards field is present in the request, then the forwarded 2486 request MUST NOT include a Max-Forwards field. 2488 9.3 GET 2490 The GET method means retrieve whatever information (in the form of an 2491 entity) is identified by the Request-URI. If the Request-URI refers 2492 to a data-producing process, it is the produced data which shall be 2493 returned as the entity in the response and not the source text of the 2494 process, unless that text happens to be the output of the process. 2496 The semantics of the GET method change to a "conditional GET" if the 2497 request message includes an If-Modified-Since, If-Unmodified-Since, 2498 If-Match, If-None-Match, or If-Range header field. A conditional GET 2499 method requests that the entity be transferred only under the 2500 circumstances described by the conditional header field(s). The 2501 conditional GET method is intended to reduce unnecessary network 2502 usage by allowing cached entities to be refreshed without requiring 2503 multiple requests or transferring data already held by the client. 2505 The semantics of the GET method change to a "partial GET" if the 2506 request message includes a Range header field. A partial GET requests 2507 that only part of the entity be transferred, as described in section 2508 14.35. The partial GET method is intended to reduce unnecessary 2509 network usage by allowing partially-retrieved entities to be 2510 completed without transferring data already held by the client. 2512 The response to a GET request is cacheable if and only if it meets 2513 the requirements for HTTP caching described in section 13. 2515 See section 15.1.3 for security considerations when used for forms. 2517 9.4 HEAD 2519 The HEAD method is identical to GET except that the server MUST NOT 2520 return a message-body in the response. The metainformation contained 2521 in the HTTP headers in response to a HEAD request SHOULD be identical 2522 to the information sent in response to a GET request. This method can 2523 be used for obtaining metainformation about the entity implied by the 2524 request without transferring the entity-body itself. This method is 2525 often used for testing hypertext links for validity, accessibility, 2526 and recent modification. 2528 The response to a HEAD request MAY be cacheable in the sense that the 2529 information contained in the response MAY be used to update a 2530 previously cached entity from that resource. If the new field values 2531 indicate that the cached entity differs from the current entity (as 2532 would be indicated by a change in Content-Length, Content-MD5, ETag 2533 or Last-Modified), then the cache MUST treat the cache entry as 2534 stale. 2536 9.5 POST 2538 The POST method is used to request that the origin server accept the 2539 entity enclosed in the request as data to be processed by the 2540 resource identified by the Request-URI in the Request-Line. POST is 2541 designed to allow a uniform method to cover the following functions: 2543 o Annotation of existing resources; 2544 o Posting a message to a bulletin board, newsgroup, mailing list, or 2545 similar group of articles; 2546 o Providing a block of data, such as the result of submitting a form, 2547 to a data-handling process; 2548 o Extending a database through an append operation. 2550 The actual function performed by the POST method is determined by the 2551 server and is usually dependent on the Request-URI. 2553 The action performed by the POST method might not result in a 2554 resource that can be identified by a URI. In this case, either 200 2555 (OK) or 204 (No Content) is the appropriate response status, 2556 depending on whether or not the response includes an entity that 2557 describes the result. 2559 If a resource has been created on the origin server, the response 2560 SHOULD be 201 (Created) and contain an entity which describes the 2561 status of the request and refers to the new resource, and a Location 2562 header (see section 14.30). 2564 Responses to this method are not cacheable, unless the response 2565 includes appropriate Cache-Control or Expires header fields. However, 2566 the 303 (See Other) response can be used to direct the user agent to 2567 retrieve a cacheable resource. 2569 POST requests MUST obey the message transmission requirements set out 2570 in section 8.2. 2572 See section 15.1.3 for security considerations. 2574 9.6 PUT 2576 The PUT method requests that the enclosed entity be stored under the 2577 supplied Request-URI. If the Request-URI refers to an already 2578 existing resource, the enclosed entity SHOULD be considered as a 2579 modified version of the one residing on the origin server. If the 2580 Request-URI does not point to an existing resource, and that URI is 2581 capable of being defined as a new resource by the requesting user 2582 agent, the origin server can create the resource with that URI. If a 2583 new resource is created, the origin server MUST inform the user agent 2584 via the 201 (Created) response. If an existing resource is modified, 2585 either the 200 (OK) or 204 (No Content) response codes SHOULD be sent 2586 to indicate successful completion of the request. If the resource 2587 could not be created or modified with the Request-URI, an appropriate 2588 error response SHOULD be given that reflects the nature of the 2589 problem. The recipient of the entity MUST NOT ignore any Content-* 2590 (e.g. Content-Range) headers that it does not understand or implement 2591 and MUST return a 501 (Not Implemented) response in such cases. 2593 If the request passes through a cache and the Request-URI identifies 2594 one or more currently cached entities, those entries SHOULD be 2595 treated as stale. Responses to this method are not cacheable. 2597 The fundamental difference between the POST and PUT requests is 2598 reflected in the different meaning of the Request-URI. The URI in a 2599 POST request identifies the resource that will handle the enclosed 2600 entity. That resource might be a data-accepting process, a gateway to 2601 some other protocol, or a separate entity that accepts annotations. 2603 In contrast, the URI in a PUT request identifies the entity enclosed 2604 with the request -- the user agent knows what URI is intended and the 2605 server MUST NOT attempt to apply the request to some other resource. 2607 If the server desires that the request be applied to a different URI, 2608 it MUST send a 301 (Moved Permanently) response; the user agent MAY 2609 then make its own decision regarding whether or not to redirect the 2610 request. 2612 A single resource MAY be identified by many different URIs. For 2613 example, an article might have a URI for identifying "the current 2614 version" which is separate from the URI identifying each particular 2615 version. In this case, a PUT request on a general URI might result in 2616 several other URIs being defined by the origin server. 2618 HTTP/1.1 does not define how a PUT method affects the state of an 2619 origin server. 2621 PUT requests MUST obey the message transmission requirements set out 2622 in section 8.2. 2624 Unless otherwise specified for a particular entity-header, the 2625 entity-headers in the PUT request SHOULD be applied to the resource 2626 created or modified by the PUT. 2628 9.7 DELETE 2630 The DELETE method requests that the origin server delete the resource 2631 identified by the Request-URI. This method MAY be overridden by human 2632 intervention (or other means) on the origin server. The client cannot 2633 be guaranteed that the operation has been carried out, even if the 2634 status code returned from the origin server indicates that the action 2635 has been completed successfully. However, the server SHOULD NOT 2636 indicate success unless, at the time the response is given, it 2637 intends to delete the resource or move it to an inaccessible 2638 location. 2640 A successful response SHOULD be 200 (OK) if the response includes an 2641 entity describing the status, 202 (Accepted) if the action has not 2642 yet been enacted, or 204 (No Content) if the action has been enacted 2643 but the response does not include an entity. 2645 If the request passes through a cache and the Request-URI identifies 2646 one or more currently cached entities, those entries SHOULD be 2647 treated as stale. Responses to this method are not cacheable. 2649 9.8 TRACE 2651 The TRACE method is used to invoke a remote, application-layer loop- 2652 back of the request message. The final recipient of the request 2653 SHOULD reflect the message received back to the client as the entity- 2654 body of a 200 (OK) response. The final recipient is either the origin 2655 server or the first proxy or gateway to receive a Max-Forwards value 2656 of zero (0) in the request (see section 14.31). A TRACE request MUST 2657 NOT include an entity. 2659 TRACE allows the client to see what is being received at the other 2660 end of the request chain and use that data for testing or diagnostic 2661 information. The value of the Via header field (section 14.45) is of 2662 particular interest, since it acts as a trace of the request chain. 2663 Use of the Max-Forwards header field allows the client to limit the 2664 length of the request chain, which is useful for testing a chain of 2665 proxies forwarding messages in an infinite loop. 2667 If the request is valid, the response SHOULD contain the entire 2668 request message in the entity-body, with a Content-Type of 2669 "message/http". Responses to this method MUST NOT be cached. 2671 9.9 CONNECT 2673 This specification reserves the method name CONNECT for use with a 2674 proxy that can dynamically switch to being a tunnel (e.g. SSL 2675 tunneling [I33]). 2677 10 Status Code Definitions 2679 Each Status-Code is described below, including a description of which 2680 method(s) it can follow and any metainformation required in the 2681 response. 2683 10.1 Informational 1xx 2685 This class of status code indicates a provisional response, 2686 consisting only of the Status-Line and optional headers, and is 2687 terminated by an empty line. There are no required headers for this 2688 class of status code. Since HTTP/1.0 did not define any 1xx status 2689 codes, servers MUST NOT send a 1xx response to an HTTP/1.0 client 2690 except under experimental conditions. 2692 A client MUST be prepared to accept one or more 1xx status responses 2693 prior to a regular response, even if the client does not expect a 100 2694 (Continue) status message. Unexpected 1xx status responses MAY be 2695 ignored by a user agent. 2697 Proxies MUST forward 1xx responses, unless the connection between the 2698 proxy and its client has been closed, or unless the proxy itself 2699 requested the generation of the 1xx response. (For example, if a 2700 proxy adds a "Expect: 100-continue" field when it forwards a request, 2701 then it need not forward the corresponding 100 (Continue) 2702 response(s).) 2704 10.1.1 100 Continue 2706 The client SHOULD continue with its request. This interim response is 2707 used to inform the client that the initial part of the request has 2708 been received and has not yet been rejected by the server. The client 2709 SHOULD continue by sending the remainder of the request or, if the 2710 request has already been completed, ignore this response. The server 2712 MUST send a final response after the request has been completed. See 2713 section 8.2.3 for detailed discussion of the use and handling of this 2714 status code. 2716 10.1.2 101 Switching Protocols 2718 The server understands and is willing to comply with the client's 2719 request, via the Upgrade message header field (section 14.42), for a 2720 change in the application protocol being used on this connection. The 2721 server will switch protocols to those defined by the response�s 2722 Upgrade header field immediately after the empty line which 2723 terminates the 101 response. 2725 The protocol SHOULD be switched only when it is advantageous to do 2726 so. For example, switching to a newer version of HTTP is advantageous 2727 over older versions, and switching to a real-time, synchronous 2728 protocol might be advantageous when delivering resources that use 2729 such features. 2731 10.2 Successful 2xx 2733 This class of status code indicates that the client's request was 2734 successfully received, understood, and accepted. 2736 10.2.1 200 OK 2738 The request has succeeded. The information returned with the response 2739 is dependent on the method used in the request, for example: 2741 GET an entity corresponding to the requested resource is sent in the 2742 response; 2744 HEAD the entity-header fields corresponding to the requested resource 2745 are sent in the response without any message-body; 2747 POST an entity describing or containing the result of the action; 2749 TRACE an entity containing the request message as received by the end 2750 server. 2752 10.2.2 201 Created 2754 The request has been fulfilled and resulted in a new resource being 2755 created. The newly created resource can be referenced by the URI(s) 2756 returned in the entity of the response, with the most specific URI 2757 for the resource given by a Location header field. The response 2758 SHOULD include an entity containing a list of resource 2759 characteristics and location(s) from which the user or user agent can 2760 choose the one most appropriate. The entity format is specified by 2761 the media type given in the Content-Type header field. The origin 2762 server MUST create the resource before returning the 201 status code. 2763 If the action cannot be carried out immediately, the server SHOULD 2764 respond with 202 (Accepted) response instead. 2766 A 201 response MAY contain an ETag response header field indicating 2767 the current value of the entity tag for the requested variant just 2768 created, see section 14.19. 2770 10.2.3 202 Accepted 2772 The request has been accepted for processing, but the processing has 2773 not been completed. The request might or might not eventually be 2774 acted upon, as it might be disallowed when processing actually takes 2775 place. There is no facility for re-sending a status code from an 2776 asynchronous operation such as this. 2777 The 202 response is intentionally non-committal. Its purpose is to 2778 allow a server to accept a request for some other process (perhaps a 2779 batch-oriented process that is only run once per day) without 2780 requiring that the user agent's connection to the server persist 2781 until the process is completed. The entity returned with this 2782 response SHOULD include an indication of the request�s current status 2783 and either a pointer to a status monitor or some estimate of when the 2784 user can expect the request to be fulfilled. 2786 10.2.4 203 Non-Authoritative Information 2788 The returned metainformation in the entity-header is not the 2789 definitive set as available from the origin server, but is gathered 2790 from a local or a third-party copy. The set presented MAY be a subset 2791 or superset of the original version. For example, including local 2792 annotation information about the resource might result in a superset 2793 of the metainformation known by the origin server. Use of this 2794 response code is not required and is only appropriate when the 2795 response would otherwise be 200 (OK). 2797 10.2.5 204 No Content 2799 The server has fulfilled the request but does not need to return an 2800 entity-body, and might want to return updated metainformation. The 2801 response MAY include new or updated metainformation in the form of 2802 entity-headers, which if present SHOULD be associated with the 2803 requested variant. 2805 If the client is a user agent, it SHOULD NOT change its document view 2806 from that which caused the request to be sent. This response is 2807 primarily intended to allow input for actions to take place without 2808 causing a change to the user agent�s active document view, although 2809 any new or updated metainformation SHOULD be applied to the document 2810 currently in the user agent�s active view. 2812 The 204 response MUST NOT include a message-body, and thus is always 2813 terminated by the first empty line after the header fields. 2815 10.2.6 205 Reset Content 2817 The server has fulfilled the request and the user agent SHOULD reset 2818 the document view which caused the request to be sent. This response 2819 is primarily intended to allow input for actions to take place via 2820 user input, followed by a clearing of the form in which the input is 2821 given so that the user can easily initiate another input action. The 2822 response MUST NOT include an entity. 2824 10.2.7 206 Partial Content 2826 The server has fulfilled the partial GET request for the resource. 2828 The request MUST have included a Range header field (section 14.35) 2829 indicating the desired range, and MAY have included an If-Range 2830 header field (section 14.27) to make the request conditional. 2832 The response MUST include the following header fields: 2834 o Either a Content-Range header field (section 14.16) indicating the 2835 range included with this response, or a multipart/byteranges 2836 Content-Type including Content-Range fields for each part. If a 2837 Content-Length header field is present in the response, its value 2838 MUST match the actual number of OCTETs transmitted in the message- 2839 body. 2840 o Date 2841 o ETag and/or Content-Location, if the header would have been sent in 2842 a 200 response to the same request 2843 o Expires, Cache-Control, and/or Vary, if the field-value might 2844 differ from that sent in any previous response for the same variant 2846 If the 206 response is the result of an If-Range request that used a 2847 strong cache validator (see section 13.3.3), the response SHOULD NOT 2848 include other entity-headers. If the response is the result of an If- 2849 Range request that used a weak validator, the response MUST NOT 2850 include other entity-headers; this prevents inconsistencies between 2851 cached entity-bodies and updated headers. Otherwise, the response 2852 MUST include all of the entity-headers that would have been returned 2853 with a 200 (OK) response to the same request. 2855 A cache MUST NOT combine a 206 response with other previously cached 2856 content if the ETag or Last-Modified headers do not match exactly, 2857 see 13.5.4. 2859 A cache that does not support the Range and Content-Range headers 2860 MUST NOT cache 206 (Partial) responses. 2862 10.3 Redirection 3xx 2864 This class of status code indicates that further action needs to be 2865 taken by the user agent in order to fulfill the request. The action 2866 required MAY be carried out by the user agent without interaction 2867 with the user if and only if the method used in the second request is 2868 GET or HEAD. A client SHOULD detect infinite redirection loops, since 2869 such loops generate network traffic for each redirection. 2871 Note: previous versions of this specification recommended a maximum 2872 of five redirections. Content developers should be aware that there 2873 might be clients that implement such a fixed limitation. 2875 10.3.1 300 Multiple Choices 2877 The requested resource corresponds to any one of a set of 2878 representations, each with its own specific location, and agent- 2879 driven negotiation information (section 12) is being provided so that 2880 the user (or user agent) can select a preferred representation and 2881 redirect its request to that location. 2883 Unless it was a HEAD request, the response SHOULD include an entity 2884 containing a list of resource characteristics and location(s) from 2885 which the user or user agent can choose the one most appropriate. The 2886 entity format is specified by the media type given in the Content- 2887 Type header field. Depending upon the format and the capabilities of 2888 the user agent, selection of the most appropriate choice MAY be 2889 performed automatically. However, this specification does not define 2890 any standard for such automatic selection. 2892 If the server has a preferred choice of representation, it SHOULD 2893 include the specific URI for that representation in the Location 2894 field; user agents MAY use the Location field value for automatic 2895 redirection. This response is cacheable unless indicated otherwise. 2897 10.3.2 301 Moved Permanently 2899 The requested resource has been assigned a new permanent URI and any 2900 future references to this resource SHOULD use one of the returned 2901 URIs. Clients with link editing capabilities ought to automatically 2902 re-link references to the Request-URI to one or more of the new 2903 references returned by the server, where possible. This response is 2904 cacheable unless indicated otherwise. 2906 The new permanent URI SHOULD be given by the Location field in the 2907 response. Unless the request method was HEAD, the entity of the 2908 response SHOULD contain a short hypertext note with a hyperlink to 2909 the new URI(s). 2911 If the 301 status code is received in response to a request method 2912 that is known to be "safe", as defined in section 9.1.1, then the 2913 request MAY be automatically redirected by the user agent without 2914 confirmation. Otherwise, the user agent MUST NOT automatically 2915 redirect the request unless it can be confirmed by the user, since 2916 this might change the conditions under which the request was issued. 2918 Note: When automatically redirecting a POST request after receiving 2919 a 301 status code, some existing HTTP/1.0 user agents will 2920 erroneously change it into a GET request. 2922 10.3.3 302 Found 2924 The requested resource resides temporarily under a different URI. 2925 Since the redirection might be altered on occasion, the client SHOULD 2926 continue to use the Request-URI for future requests. This response 2927 is only cacheable if indicated by a Cache-Control or Expires header 2928 field. 2930 The temporary URI SHOULD be given by the Location field in the 2931 response. Unless the request method was HEAD, the entity of the 2932 response SHOULD contain a short hypertext note with a hyperlink to 2933 the new URI(s). 2935 If the 302 status code is received in response to a request method 2936 that is known to be "safe", as defined in section 9.1.1, then the 2937 request MAY be automatically redirected by the user agent without 2938 confirmation. Otherwise, the user agent MUST NOT automatically 2939 redirect the request unless it can be confirmed by the user, since 2940 this might change the conditions under which the request was issued. 2942 Note: RFC 1945 and RFC 2068 specify that the client is not allowed 2943 to change the method on the redirected request. However, most 2944 existing user agent implementations treat 302 as if it were a 303 2945 response, performing a GET on the Location field-value regardless 2946 of the original request method. The status codes 303 and 307 have 2947 been added for servers that wish to make unambiguously clear which 2948 kind of reaction is expected of the client. 2950 10.3.4 303 See Other 2952 The response to the request can be found under a different URI and 2953 SHOULD be retrieved using a GET method on that resource. This method 2954 exists primarily to allow the output of a POST-activated script to 2955 redirect the user agent to a selected resource. The new URI is not a 2956 substitute reference for the originally requested resource. The 303 2957 response MUST NOT be cached, but the response to the second 2958 (redirected) request might be cacheable. 2960 The different URI SHOULD be given by the Location field in the 2961 response. Unless the request method was HEAD, the entity of the 2962 response SHOULD contain a short hypertext note with a hyperlink to 2963 the new URI(s). 2965 Note: Many pre-HTTP/1.1 user agents do not understand the 303 2966 status. When interoperability with such clients is a concern, the 2967 302 status code may be used instead, since most user agents react 2968 to a 302 response as described here for 303. 2970 10.3.5 304 Not Modified 2972 If the client has performed a conditional GET request and access is 2973 allowed, but the document has not been modified, the server SHOULD 2974 respond with this status code. The 304 response MUST NOT contain a 2975 message-body, and thus is always terminated by the first empty line 2976 after the header fields. 2978 The response MUST include the following header fields: 2980 o Date, unless its omission is required by section 14.18.1 2981 If a clockless origin server obeys these rules, and proxies and 2982 clients add their own Date to any response received without one (as 2983 already specified by [RFC 2068], section 14.19), caches will operate 2984 correctly. 2985 o ETag and/or Content-Location, if the header would have been sent in 2986 a 200 response to the same request 2987 o Expires, Cache-Control, and/or Vary, if the field-value might 2988 differ from that sent in any previous response for the same variant 2989 If the conditional GET used a strong cache validator (see section 2990 13.3.3), the response SHOULD NOT include other entity-headers. 2991 Otherwise (i.e., the conditional GET used a weak validator), the 2992 response MUST NOT include other entity-headers; this prevents 2993 inconsistencies between cached entity-bodies and updated headers. 2995 If a 304 response indicates an entity not currently cached, then the 2996 cache MUST disregard the response and repeat the request without the 2997 conditional. 2999 If a cache uses a received 304 response to update a cache entry, the 3000 cache MUST update the entry to reflect any new field values given in 3001 the response. 3003 10.3.6 305 Use Proxy 3005 The requested resource MUST be accessed through the proxy given by 3006 the Location field. The Location field gives the URI of the proxy. 3008 The recipient is expected to repeat this single request via the 3009 proxy. 305 responses MUST only be generated by origin servers. 3011 Note: RFC 2068 was not clear that 305 was intended to redirect a 3012 single request, and to be generated by origin servers only. Not 3013 observing these limitations has significant security consequences. 3015 10.3.7 306 (Unused) 3017 The 306 status code was used in a previous version of the 3018 specification, is no longer used, and the code is reserved. 3020 10.3.8 307 Temporary Redirect 3022 The requested resource resides temporarily under a different URI. 3023 Since the redirection MAY be altered on occasion, the client SHOULD 3024 continue to use the Request-URI for future requests. This response 3025 is only cacheable if indicated by a Cache-Control or Expires header 3026 field. 3028 The temporary URI SHOULD be given by the Location field in the 3029 response. Unless the request method was HEAD, the entity of the 3030 response SHOULD contain a short hypertext note with a hyperlink to 3031 the new URI(s) , since many pre-HTTP/1.1 user agents do not 3032 understand the 307 status. Therefore, the note SHOULD contain the 3033 information necessary for a user to repeat the original request on 3034 the new URI. 3036 If the 307 status code is received in response to a request method 3037 that is known to be "safe", as defined in section 9.1.1, then the 3038 request MAY be automatically redirected by the user agent without 3039 confirmation. Otherwise, the user agent MUST NOT automatically 3040 redirect the request unless it can be confirmed by the user, since 3041 this might change the conditions under which the request was issued. 3043 10.4 Client Error 4xx 3045 The 4xx class of status code is intended for cases in which the 3046 client seems to have erred. Except when responding to a HEAD request, 3047 the server SHOULD include an entity containing an explanation of the 3048 error situation, and whether it is a temporary or permanent 3049 condition. These status codes are applicable to any request method. 3051 User agents SHOULD display any included entity to the user. 3053 If the client is sending data, a server implementation using TCP 3054 SHOULD be careful to ensure that the client acknowledges receipt of 3055 the packet(s) containing the response, before the server closes the 3056 input connection. If the client continues sending data to the server 3057 after the close, the server's TCP stack will send a reset packet to 3058 the client, which may erase the client's unacknowledged input buffers 3059 before they can be read and interpreted by the HTTP application. 3061 10.4.1 400 Bad Request 3063 The request could not be understood by the server due to malformed 3064 syntax. The client SHOULD NOT repeat the request without 3065 modifications. 3067 10.4.2 401 Unauthorized 3069 The request requires user authentication. The response MUST include a 3070 WWW-Authenticate header field (section 14.47) containing a challenge 3071 applicable to the requested resource. The client MAY repeat the 3072 request with a suitable Authorization header field (section 14.8). If 3073 the request already included Authorization credentials, then the 401 3074 response indicates that authorization has been refused for those 3075 credentials. If the 401 response contains the same challenge as the 3076 prior response, and the user agent has already attempted 3077 authentication at least once, then the user SHOULD be presented the 3078 entity that was given in the response, since that entity might 3079 include relevant diagnostic information. HTTP access authentication 3080 is explained in "HTTP Authentication: Basic and Digest Access 3081 Authentication" [N10]. 3083 10.4.3 402 Payment Required 3085 This code is reserved for future use. 3087 10.4.4 403 Forbidden 3089 The server understood the request, but is refusing to fulfill it. 3090 Authorization will not help and the request SHOULD NOT be repeated. 3092 If the request method was not HEAD and the server wishes to make 3093 public why the request has not been fulfilled, it SHOULD describe the 3094 reason for the refusal in the entity. If the server does not wish to 3095 make this information available to the client, the status code 404 3096 (Not Found) can be used instead. 3098 10.4.5 404 Not Found 3100 The server has not found anything matching the Request-URI. No 3101 indication is given of whether the condition is temporary or 3102 permanent. The 410 (Gone) status code SHOULD be used if the server 3103 knows, through some internally configurable mechanism, that an old 3104 resource is permanently unavailable and has no forwarding address. 3105 This status code is commonly used when the server does not wish to 3106 reveal exactly why the request has been refused, or when no other 3107 response is applicable. 3109 10.4.6 405 Method Not Allowed 3111 The method specified in the Request-Line is not allowed for the 3112 resource identified by the Request-URI. The response MUST include an 3113 Allow header containing a list of valid methods for the requested 3114 resource. 3116 10.4.7 406 Not Acceptable 3118 The resource identified by the request is only capable of generating 3119 response entities which have content characteristics not acceptable 3120 according to the accept headers sent in the request. 3122 Unless it was a HEAD request, the response SHOULD include an entity 3123 containing a list of available entity characteristics and location(s) 3124 from which the user or user agent can choose the one most 3125 appropriate. The entity format is specified by the media type given 3126 in the Content-Type header field. Depending upon the format and the 3127 capabilities of the user agent, selection of the most appropriate 3128 choice MAY be performed automatically. However, this specification 3129 does not define any standard for such automatic selection. 3131 Note: HTTP/1.1 servers are allowed to return responses which are 3132 not acceptable according to the accept headers sent in the request. 3134 In some cases, this may even be preferable to sending a 406 3135 response. User agents are encouraged to inspect the headers of an 3136 incoming response to determine if it is acceptable. 3138 If the response could be unacceptable, a user agent SHOULD 3139 temporarily stop receipt of more data and query the user for a 3140 decision on further actions. 3142 10.4.8 407 Proxy Authentication Required 3144 This code is similar to 401 (Unauthorized), but indicates that the 3145 client must first authenticate itself with the proxy. The proxy MUST 3146 return a Proxy-Authenticate header field (section 14.33) containing a 3147 challenge applicable to the proxy for the requested resource. The 3148 client MAY repeat the request with a suitable Proxy-Authorization 3149 header field (section 14.34). HTTP access authentication is explained 3150 in "HTTP Authentication: Basic and Digest Access Authentication" 3151 [N10]. 3153 10.4.9 408 Request Timeout 3155 The client did not produce a request within the time that the server 3156 was prepared to wait. The client MAY repeat the request without 3157 modifications at any later time. 3159 10.4.10 409 Conflict 3161 The request could not be completed due to a conflict with the current 3162 state of the resource. This code is only allowed in situations where 3163 it is expected that the user might be able to resolve the conflict 3164 and resubmit the request. The response body SHOULD include enough 3165 information for the user to recognize the source of the conflict. 3166 Ideally, the response entity would include enough information for the 3167 user or user agent to fix the problem; however, that might not be 3168 possible and is not required. 3170 Conflicts are most likely to occur in response to a PUT request. For 3171 example, if versioning were being used and the entity being PUT 3172 included changes to a resource which conflict with those made by an 3173 earlier (third-party) request, the server might use the 409 response 3174 to indicate that it can�t complete the request. In this case, the 3175 response entity would likely contain a list of the differences 3176 between the two versions in a format defined by the response Content- 3177 Type. 3179 10.4.11 410 Gone 3181 The requested resource is no longer available at the server and no 3182 forwarding address is known. This condition is expected to be 3183 considered permanent. Clients with link editing capabilities SHOULD 3184 delete references to the Request-URI after user approval. If the 3185 server does not know, or has no facility to determine, whether or not 3186 the condition is permanent, the status code 404 (Not Found) SHOULD be 3187 used instead. This response is cacheable unless indicated otherwise. 3189 The 410 response is primarily intended to assist the task of web 3190 maintenance by notifying the recipient that the resource is 3191 intentionally unavailable and that the server owners desire that 3192 remote links to that resource be removed. Such an event is common for 3193 limited-time, promotional services and for resources belonging to 3194 individuals no longer working at the server�s site. It is not 3195 necessary to mark all permanently unavailable resources as "gone" or 3196 to keep the mark for any length of time -- that is left to the 3197 discretion of the server owner. 3199 10.4.12 411 Length Required 3201 The server refuses to accept the request without a defined Content- 3202 Length. The client MAY repeat the request if it adds a valid Content- 3203 Length header field containing the length of the message-body in the 3204 request message. 3206 10.4.13 412 Precondition Failed 3208 The precondition given in one or more of the request-header fields 3209 evaluated to false when it was tested on the server. This response 3210 code allows the client to place preconditions on the current resource 3211 metainformation (header field data) and thus prevent the requested 3212 method from being applied to a resource other than the one intended. 3214 10.4.14 413 Request Entity Too Large 3216 The server is refusing to process a request because the request 3217 entity is larger than the server is willing or able to process. The 3218 server MAY close the connection to prevent the client from continuing 3219 the request. 3221 If the condition is temporary, the server SHOULD include a Retry- 3222 After header field to indicate that it is temporary and after what 3223 time the client MAY try again. 3225 10.4.15 414 Request-URI Too Long 3227 The server is refusing to service the request because the Request-URI 3228 is longer than the server is willing to interpret. This rare 3229 condition is only likely to occur when a client has improperly 3230 converted a POST request to a GET request with long query 3231 information, when the client has descended into a URI "black hole" of 3232 redirection (e.g., a redirected URI prefix that points to a suffix of 3233 itself), or when the server is under attack by a client attempting to 3234 exploit security holes present in some servers using fixed-length 3235 buffers for reading or manipulating the Request-URI. 3237 10.4.16 415 Unsupported Media Type 3239 The server is refusing to service the request because the entity of 3240 the request is in a format not supported by the requested resource 3241 for the requested method. 3243 10.4.17 416 Requested Range Not Satisfiable 3245 A server SHOULD return a response with this status code if a request 3246 included a Range request-header field (section 14.35) , and none of 3247 the range-specifier values in this field overlap the current extent 3248 of the selected resource, and the request did not include an If-Range 3249 request-header field. (For byte-ranges, this means that the first- 3250 byte-pos of all of the byte-range-spec values were greater than the 3251 current length of the selected resource.) 3253 When this status code is returned for a byte-range request, the 3254 response SHOULD include a Content-Range entity-header field 3255 specifying the current length of the selected resource (see section 3256 14.16). This response MUST NOT use the multipart/byteranges content- 3257 type. 3259 10.4.18 417 Expectation Failed 3261 The expectation given in an Expect request-header field (see section 3262 14.20) could not be met by this server, or, if the server is a proxy, 3263 the server has unambiguous evidence that the request could not be met 3264 by the next-hop server. 3266 10.5 Server Error 5xx 3268 Response status codes beginning with the digit "5" indicate cases in 3269 which the server is aware that it has erred or is incapable of 3270 performing the request. Except when responding to a HEAD request, the 3271 server SHOULD include an entity containing an explanation of the 3272 error situation, and whether it is a temporary or permanent 3273 condition. User agents SHOULD display any included entity to the 3274 user. These response codes are applicable to any request method. 3276 10.5.1 500 Internal Server Error 3278 The server encountered an unexpected condition which prevented it 3279 from fulfilling the request. 3281 10.5.2 501 Not Implemented 3283 The server does not support the functionality required to fulfill the 3284 request. This is the appropriate response when the server does not 3285 recognize the request method and is not capable of supporting it for 3286 any resource. 3288 10.5.3 502 Bad Gateway 3290 The server, while acting as a gateway or proxy, received an invalid 3291 response from the upstream server it accessed in attempting to 3292 fulfill the request. 3294 10.5.4 503 Service Unavailable 3296 The server is currently unable to handle the request due to a 3297 temporary overloading or maintenance of the server. The implication 3298 is that this is a temporary condition which will be alleviated after 3299 some delay. If known, the length of the delay MAY be indicated in a 3300 Retry-After header. If no Retry-After is given, the client SHOULD 3301 handle the response as it would for a 500 response. 3303 Note: The existence of the 503 status code does not imply that a 3304 server must use it when becoming overloaded. Some servers may wish 3305 to simply refuse the connection. 3307 10.5.5 504 Gateway Timeout 3309 The server, while acting as a gateway or proxy, did not receive a 3310 timely response from the upstream server specified by the URI (e.g. 3311 HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed 3312 to access in attempting to complete the request. 3314 Note: Note to implementors: some deployed proxies are known to 3315 return 400 or 500 when DNS lookups time out. 3317 10.5.6 505 HTTP Version Not Supported 3319 The server does not support, or refuses to support, the HTTP protocol 3320 version that was used in the request message. The server is 3321 indicating that it is unable or unwilling to complete the request 3322 using the same major version as the client, as described in section 3323 3.1, other than with this error message. The response SHOULD contain 3324 an entity describing why that version is not supported and what other 3325 protocols are supported by that server. 3327 11 Access Authentication 3329 HTTP provides several OPTIONAL challenge-response authentication 3330 mechanisms which can be used by a server to challenge a client 3331 request and by a client to provide authentication information. The 3332 general framework for access authentication, and the specification of 3333 "basic" and "digest" authentication, are specified in "HTTP 3334 Authentication: Basic and Digest Access Authentication" [N10]. This 3335 specification adopts the definitions of "challenge" and "credentials" 3336 from that specification. 3338 12 Content Negotiation 3340 Most HTTP responses include an entity which contains information for 3341 interpretation by a human user. Naturally, it is desirable to supply 3342 the user with the "best available" entity corresponding to the 3343 request. Unfortunately for servers and caches, not all users have the 3344 same preferences for what is "best," and not all user agents are 3345 equally capable of rendering all entity types. For that reason, HTTP 3346 has provisions for several mechanisms for "content negotiation" -- 3347 the process of selecting the best representation for a given response 3348 when there are multiple representations available. 3350 Note: This is not called "format negotiation" because the alternate 3351 representations may be of the same media type, but use different 3352 capabilities of that type, be in different languages, etc. 3354 Any response containing an entity-body MAY be subject to negotiation, 3355 including error responses. 3357 There are two kinds of content negotiation which are possible in 3358 HTTP: server-driven and agent-driven negotiation. These two kinds of 3359 negotiation are orthogonal and thus may be used separately or in 3360 combination. One method of combination, referred to as transparent 3361 negotiation, occurs when a cache uses the agent-driven negotiation 3362 information provided by the origin server in order to provide server- 3363 driven negotiation for subsequent requests. 3365 12.1 Server-driven Negotiation 3367 If the selection of the best representation for a response is made by 3368 an algorithm located at the server, it is called server-driven 3369 negotiation. Selection is based on the available representations of 3370 the response (the dimensions over which it can vary; e.g. language, 3371 content-coding, etc.) and the contents of particular header fields in 3372 the request message or on other information pertaining to the request 3373 (such as the network address of the client). 3375 Server-driven negotiation is advantageous when the algorithm for 3376 selecting from among the available representations is difficult to 3377 describe to the user agent, or when the server desires to send its 3378 "best guess" to the client along with the first response (hoping to 3379 avoid the round-trip delay of a subsequent request if the "best 3380 guess" is good enough for the user). In order to improve the server's 3381 guess, the user agent MAY include request header fields (Accept, 3382 Accept-Language, Accept-Encoding, etc.) which describe its 3383 preferences for such a response. 3385 Server-driven negotiation has disadvantages: 3387 1. It is impossible for the server to accurately determine what might 3388 be "best" for any given user, since that would require complete 3389 knowledge of both the capabilities of the user agent and the 3390 intended use for the response (e.g., does the user want to view it 3391 on screen or print it on paper?). 3393 2. Having the user agent describe its capabilities in every request 3394 can be both very inefficient (given that only a small percentage of 3395 responses have multiple representations) and a potential violation 3396 of the user's privacy. 3398 3. It complicates the implementation of an origin server and the 3399 algorithms for generating responses to a request. 3401 4. It may limit a public cache�s ability to use the same response for 3402 multiple user�s requests. 3404 HTTP/1.1 includes the following request-header fields for enabling 3405 server-driven negotiation through description of user agent 3406 capabilities and user preferences: Accept (section 14.1), Accept- 3407 Charset (section 14.2), Accept-Encoding (section 14.3), Accept- 3408 Language (section 14.4), and User-Agent (section 14.43). However, an 3409 origin server is not limited to these dimensions and MAY vary the 3410 response based on any aspect of the request, including information 3411 outside the request-header fields or within extension header fields 3412 not defined by this specification. 3414 The Vary header field can be used to express the parameters the 3415 server uses to select a representation that is subject to server- 3416 driven negotiation. See section 13.6 for use of the Vary header field 3417 by caches and section 14.44 for use of the Vary header field by 3418 servers. 3420 12.2 Agent-driven Negotiation 3422 With agent-driven negotiation, selection of the best representation 3423 for a response is performed by the user agent after receiving an 3424 initial response from the origin server. Selection is based on a list 3425 of the available representations of the response included within the 3426 header fields or entity-body of the initial response, with each 3427 representation identified by its own URI. Selection from among the 3428 representations may be performed automatically (if the user agent is 3429 capable of doing so) or manually by the user selecting from a 3430 generated (possibly hypertext) menu. 3432 Agent-driven negotiation is advantageous when the response would vary 3433 over commonly-used dimensions (such as type, language, or encoding), 3434 when the origin server is unable to determine a user agent's 3435 capabilities from examining the request, and generally when public 3436 caches are used to distribute server load and reduce network usage. 3438 Agent-driven negotiation suffers from the disadvantage of needing a 3439 second request to obtain the best alternate representation. This 3440 second request is only efficient when caching is used. In addition, 3441 this specification does not define any mechanism for supporting 3442 automatic selection, though it also does not prevent any such 3443 mechanism from being developed as an extension and used within 3444 HTTP/1.1. 3446 HTTP/1.1 defines the 300 (Multiple Choices) and 406 (Not Acceptable) 3447 status codes for enabling agent-driven negotiation when the server is 3448 unwilling or unable to provide a varying response using server-driven 3449 negotiation. 3451 12.3 Transparent Negotiation 3453 Transparent negotiation is a combination of both server-driven and 3454 agent-driven negotiation. When a cache is supplied with a form of the 3455 list of available representations of the response (as in agent-driven 3456 negotiation) and the dimensions of variance are completely understood 3457 by the cache, then the cache becomes capable of performing server- 3458 driven negotiation on behalf of the origin server for subsequent 3459 requests on that resource. 3461 Transparent negotiation has the advantage of distributing the 3462 negotiation work that would otherwise be required of the origin 3463 server and also removing the second request delay of agent-driven 3464 negotiation when the cache is able to correctly guess the right 3465 response. 3467 This specification does not define any mechanism for transparent 3468 negotiation, though it also does not prevent any such mechanism from 3469 being developed as an extension that could be used within HTTP/1.1. 3471 13 Caching in HTTP 3473 HTTP is typically used for distributed information systems, where 3474 performance can be improved by the use of response caches. The 3475 HTTP/1.1 protocol includes a number of elements intended to make 3476 caching work as well as possible. Because these elements are 3477 inextricable from other aspects of the protocol, and because they 3478 interact with each other, it is useful to describe the basic caching 3479 design of HTTP separately from the detailed descriptions of methods, 3480 headers, response codes, etc. 3482 Caching would be useless if it did not significantly improve 3483 performance. The goal of caching in HTTP/1.1 is to eliminate the need 3484 to send requests in many cases, and to eliminate the need to send 3485 full responses in many other cases. The former reduces the number of 3486 network round-trips required for many operations; we use an 3487 "expiration" mechanism for this purpose (see section 13.2). The 3488 latter reduces network bandwidth requirements; we use a "validation" 3489 mechanism for this purpose (see section 13.3). 3491 Requirements for performance, availability, and disconnected 3492 operation require us to be able to relax the goal of semantic 3493 transparency. The HTTP/1.1 protocol allows origin servers, caches, 3494 and clients to explicitly reduce transparency when necessary. 3495 However, because non-transparent operation may confuse non-expert 3496 users, and might be incompatible with certain server applications 3497 (such as those for ordering merchandise), the protocol requires that 3498 transparency be relaxed 3500 o only by an explicit protocol-level request when relaxed by client 3501 or origin server 3502 o only with an explicit warning to the end user when relaxed by cache 3503 or client 3505 Therefore, the HTTP/1.1 protocol provides these important elements: 3507 1. Protocol features that provide full semantic transparency when this 3508 is required by all parties. 3510 2. Protocol features that allow an origin server or user agent to 3511 explicitly request and control non-transparent operation. 3513 3. Protocol features that allow a cache to attach warnings to 3514 responses that do not preserve the requested approximation of 3515 semantic transparency. 3517 A basic principle is that it must be possible for the clients to 3518 detect any potential relaxation of semantic transparency. 3520 Note: The server, cache, or client implementor might be faced with 3521 design decisions not explicitly discussed in this specification. If 3522 a decision might affect semantic transparency, the implementor 3523 ought to err on the side of maintaining transparency unless a 3524 careful and complete analysis shows significant benefits in 3525 breaking transparency. 3527 13.1.1 Cache Correctness 3529 A correct cache MUST respond to a request with the most up-to-date 3530 response held by the cache that is appropriate to the request (see 3531 sections 13.2.5, 13.2.6, and 13.12) which meets one of the following 3532 conditions: 3534 1. It has been checked for equivalence with what the origin server 3535 would have returned by revalidating the response with the origin 3536 server (section 13.3); 3538 2. It is "fresh enough" (see section 13.2). In the default case, this 3539 means it meets the least restrictive freshness requirement of the 3540 client, origin server, and cache (see section 14.9); if the origin 3541 server so specifies, it is the freshness requirement of the origin 3542 server alone. 3544 If a stored response is not "fresh enough" by the most restrictive 3545 freshness requirement of both the client and the origin server, in 3546 carefully considered circumstances the cache MAY still return the 3547 response with the appropriate Warning header (see section 13.1.5 3548 and 14.46), unless such a response is prohibited (e.g., by a "no- 3549 store" cache-directive, or by a "no-cache" cache-request-directive; 3550 see section 14.9). 3552 3. It is an appropriate 304 (Not Modified), 305 (Proxy Redirect), or 3553 error (4xx or 5xx) response message. 3555 If the cache can not communicate with the origin server, then a 3556 correct cache SHOULD respond as above if the response can be 3557 correctly served from the cache; if not it MUST return an error or 3558 warning indicating that there was a communication failure. 3560 If a cache receives a response (either an entire response, or a 304 3561 (Not Modified) response) that it would normally forward to the 3562 requesting client, and the received response is no longer fresh, the 3563 cache SHOULD forward it to the requesting client without adding a new 3564 Warning (but without removing any existing Warning headers). A cache 3566 SHOULD NOT attempt to revalidate a response simply because that 3567 response became stale in transit; this might lead to an infinite 3568 loop. A user agent that receives a stale response without a Warning 3569 MAY display a warning indication to the user. 3571 13.1.2 Warnings 3573 Whenever a cache returns a response that is neither first-hand nor 3574 "fresh enough" (in the sense of condition 2 in section 13.1.1), it 3575 MUST attach a warning to that effect, using a Warning general-header. 3576 The Warning header and the currently defined warnings are described 3577 in section 14.46. The warning allows clients to take appropriate 3578 action. 3580 Warnings MAY be used for other purposes, both cache-related and 3581 otherwise. The use of a warning, rather than an error status code, 3582 distinguish these responses from true failures. 3584 Warnings are assigned three digit warn-codes. The first digit 3585 indicates whether the Warning MUST or MUST NOT be deleted from a 3586 stored cache entry after a successful revalidation: 3588 1xx Warnings that describe the freshness or revalidation status of the 3589 response, and so MUST be deleted after a successful revalidation. 3591 1XX warn-codes MAY be generated by a cache only when validating a 3592 cached entry. It MUST NOT be generated by clients. 3594 2xx Warnings that describe some aspect of the entity body or entity 3595 headers that is not rectified by a revalidation (for example, a lossy 3596 compression of the entity bodies) and which MUST NOT be deleted after 3597 a successful revalidation. 3599 See section 14.46 for the definitions of the codes themselves. 3601 HTTP/1.0 caches will cache all Warnings in responses, without 3602 deleting the ones in the first category. Warnings in responses that 3603 are passed to HTTP/1.0 caches carry an extra warning-date field, 3604 which prevents a future HTTP/1.1 recipient from believing an 3605 erroneously cached Warning. 3607 Warnings also carry a warning text. The text MAY be in any 3608 appropriate natural language (perhaps based on the client's Accept 3609 headers), and include an OPTIONAL indication of what character set is 3610 used. 3612 Multiple warnings MAY be attached to a response (either by the origin 3613 server or by a cache), including multiple warnings with the same code 3614 number. For example, a server might provide the same warning with 3615 texts in both English and Basque. 3617 When multiple warnings are attached to a response, it might not be 3618 practical or reasonable to display all of them to the user. This 3619 version of HTTP does not specify strict priority rules for deciding 3620 which warnings to display and in what order, but does suggest some 3621 heuristics. 3623 13.1.3 Cache-control Mechanisms 3625 The basic cache mechanisms in HTTP/1.1 (server-specified expiration 3626 times and validators) are implicit directives to caches. In some 3627 cases, a server or client might need to provide explicit directives 3628 to the HTTP caches. We use the Cache-Control header for this purpose. 3630 The Cache-Control header allows a client or server to transmit a 3631 variety of directives in either requests or responses. These 3632 directives typically override the default caching algorithms. As a 3633 general rule, if there is any apparent conflict between header 3634 values, the most restrictive interpretation is applied (that is, the 3635 one that is most likely to preserve semantic transparency). However, 3636 in some cases, cache-control directives are explicitly specified as 3637 weakening the approximation of semantic transparency (for example, 3638 "max-stale" or "public"). 3640 The cache-control directives are described in detail in section 14.9. 3642 13.1.4 Explicit User Agent Warnings 3644 Many user agents make it possible for users to override the basic 3645 caching mechanisms. For example, the user agent might allow the user 3646 to specify that cached entities (even explicitly stale ones) are 3647 never validated. Or the user agent might habitually add "Cache- 3648 Control: max-stale=3600" to every request. The user agent SHOULD NOT 3649 default to either non-transparent behavior, or behavior that results 3650 in abnormally ineffective caching, but MAY be explicitly configured 3651 to do so by an explicit action of the user. 3653 If the user has overridden the basic caching mechanisms, the user 3654 agent SHOULD explicitly indicate to the user whenever this results in 3655 the display of information that might not meet the server�s 3656 transparency requirements (in particular, if the displayed entity is 3658 known to be stale). Since the protocol normally allows the user agent 3659 to determine if responses are stale or not, this indication need only 3660 be displayed when this actually happens. The indication need not be a 3661 dialog box; it could be an icon (for example, a picture of a rotting 3662 fish) or some other indicator. 3664 If the user has overridden the caching mechanisms in a way that would 3665 abnormally reduce the effectiveness of caches, the user agent SHOULD 3666 continually indicate this state to the user (for example, by a 3667 display of a picture of currency in flames) so that the user does not 3668 inadvertently consume excess resources or suffer from excessive 3669 latency. 3671 13.1.5 Exceptions to the Rules and Warnings 3673 In some cases, the operator of a cache MAY choose to configure it to 3674 return stale responses even when not requested by clients. This 3675 decision ought not be made lightly, but may be necessary for reasons 3676 of availability or performance, especially when the cache is poorly 3677 connected to the origin server. Whenever a cache returns a stale 3678 response, it MUST mark it as such (using a Warning header) enabling 3679 the client software to alert the user that there might be a potential 3680 problem. 3682 It also allows the user agent to take steps to obtain a first-hand or 3683 fresh response. For this reason, a cache SHOULD NOT return a stale 3684 response if the client explicitly requests a first-hand or fresh one, 3685 unless it is impossible to comply for technical or policy reasons. 3687 13.1.6 Client-controlled Behavior 3689 While the origin server (and to a lesser extent, intermediate caches, 3690 by their contribution to the age of a response) are the primary 3691 source of expiration information, in some cases the client might need 3692 to control a cache's decision about whether to return a cached 3693 response without validating it. Clients do this using several 3694 directives of the Cache-Control header. 3696 A client's request MAY specify the maximum age it is willing to 3697 accept of an unvalidated response; specifying a value of zero forces 3698 the cache(s) to revalidate all responses. A client MAY also specify 3699 the minimum time remaining before a response expires. Both of these 3700 options increase constraints on the behavior of caches, and so cannot 3701 further relax the cache's approximation of semantic transparency. 3703 A client MAY also specify that it will accept stale responses, up to 3704 some maximum amount of staleness. This loosens the constraints on the 3705 caches, and so might violate the origin server's specified 3706 constraints on semantic transparency, but might be necessary to 3707 support disconnected operation, or high availability in the face of 3708 poor connectivity. 3710 13.2 Expiration Model 3712 13.2.1 Server-Specified Expiration 3714 HTTP caching works best when caches can entirely avoid making 3715 requests to the origin server. The primary mechanism for avoiding 3716 requests is for an origin server to provide an explicit expiration 3717 time in the future, indicating that a response MAY be used to satisfy 3718 subsequent requests. In other words, a cache can return a fresh 3719 response without first contacting the server. 3721 Our expectation is that servers will assign future explicit 3722 expiration times to responses in the belief that the entity is not 3723 likely to change, in a semantically significant way, before the 3724 expiration time is reached. This normally preserves semantic 3725 transparency, as long as the server's expiration times are carefully 3726 chosen. 3728 The expiration mechanism applies only to responses taken from a cache 3729 and not to first-hand responses forwarded immediately to the 3730 requesting client. 3732 If an origin server wishes to force a semantically transparent cache 3733 to validate every request, it MAY assign an explicit expiration time 3734 in the past. This means that the response is always stale, and so the 3735 cache SHOULD validate it before using it for subsequent requests. See 3736 section 14.9.4 for a more restrictive way to force revalidation. 3738 If an origin server wishes to force any HTTP/1.1 cache, no matter how 3739 it is configured, to validate every request, it SHOULD use the "must- 3740 revalidate" cache-control directive (see section 14.9). 3742 Servers specify explicit expiration times using either the Expires 3743 header, or the max-age directive of the Cache-Control header. 3745 An expiration time cannot be used to force a user agent to refresh 3746 its display or reload a resource; its semantics apply only to caching 3747 mechanisms, and such mechanisms need only check a resource's 3748 expiration status when a new request for that resource is initiated. 3750 See section 13.13 for an explanation of the difference between caches 3751 and history mechanisms. 3753 13.2.2 Heuristic Expiration 3755 Since origin servers do not always provide explicit expiration times, 3756 HTTP caches typically assign heuristic expiration times, employing 3757 algorithms that use other header values (such as the Last-Modified 3758 time) to estimate a plausible expiration time. The HTTP/1.1 3759 specification does not provide specific algorithms, but does impose 3760 worst-case constraints on their results. Since heuristic expiration 3761 times might compromise semantic transparency, they ought to used 3762 cautiously, and we encourage origin servers to provide explicit 3763 expiration times as much as possible. 3765 13.2.3 Age Calculations 3767 In order to know if a cached entry is fresh, a cache needs to know if 3768 its age exceeds its freshness lifetime. We discuss how to calculate 3769 the latter in section 13.2.4; this section describes how to calculate 3770 the age of a response or cache entry. 3772 In this discussion, we use the term "now" to mean "the current value 3773 of the clock at the host performing the calculation." Hosts that use 3774 HTTP, but especially hosts running origin servers and caches, SHOULD 3775 use NTP [I21] or some similar protocol to synchronize their clocks to 3776 a globally accurate time standard. 3778 HTTP/1.1 requires origin servers to send a Date header, if possible, 3779 with every response, giving the time at which the response was 3780 generated (see section 14.18). We use the term "date_value" to denote 3781 the value of the Date header, in a form appropriate for arithmetic 3782 operations. 3784 HTTP/1.1 uses the Age response-header to convey the estimated age of 3785 the response message when obtained from a cache. The Age field value 3786 is the cache's estimate of the amount of time since the response was 3787 generated or revalidated by the origin server. 3789 In essence, the Age value is the sum of the time that the response 3790 has been resident in each of the caches along the path from the 3791 origin server, plus the amount of time it has been in transit along 3792 network paths. 3794 We use the term "age_value" to denote the value of the Age header, in 3795 a form appropriate for arithmetic operations. 3797 A response's age can be calculated in two entirely independent ways: 3799 1. now minus date_value, if the local clock is reasonably well 3800 synchronized to the origin server's clock. If the result is 3801 negative, the result is replaced by zero. 3803 2. age_value, if all of the caches along the response path implement 3804 HTTP/1.1. 3806 Given that we have two independent ways to compute the age of a 3807 response when it is received, we can combine these as 3809 corrected_received_age = max(now - date_value, age_value) 3811 and as long as we have either nearly synchronized clocks or all- 3812 HTTP/1.1 paths, one gets a reliable (conservative) result. 3814 Because of network-imposed delays, some significant interval might 3815 pass between the time that a server generates a response and the time 3816 it is received at the next outbound cache or client. If uncorrected, 3817 this delay could result in improperly low ages. 3819 Because the request that resulted in the returned Age value must have 3820 been initiated prior to that Age value�s generation, we can correct 3821 for delays imposed by the network by recording the time at which the 3822 request was initiated. Then, when an Age value is received, it MUST 3823 be interpreted relative to the time the request was initiated, not 3824 the time that the response was received. This algorithm results in 3825 conservative behavior no matter how much delay is experienced. So, we 3826 compute: 3828 corrected_initial_age = corrected_received_age 3829 + (now - request_time) 3831 where "request_time" is the time (according to the local clock) when 3832 the request that elicited this response was sent. 3834 Summary of age calculation algorithm, when a cache receives a 3835 response: 3837 /* 3838 * age_value 3839 * is the value of Age: header received by the cache with 3840 * this response. 3841 * date_value 3842 * is the value of the origin server's Date: header 3843 * request_time 3844 * is the (local) time when the cache made the request 3845 * that resulted in this cached response 3846 * response_time 3847 * is the (local) time when the cache received the 3848 * response 3849 * now 3850 * is the current (local) time 3851 */ 3852 apparent_age = max(0, response_time - date_value); 3853 corrected_received_age = max(apparent_age, age_value); 3854 response_delay = response_time - request_time; 3855 corrected_initial_age = corrected_received_age + 3856 response_delay; 3857 resident_time = now - response_time; 3858 current_age = corrected_initial_age + resident_time; 3860 The current_age of a cache entry is calculated by adding the amount 3861 of time (in seconds) since the cache entry was last validated by the 3862 origin server to the corrected_initial_age. When a response is 3863 generated from a cache entry, the cache MUST include a single Age 3864 header field in the response with a value equal to the cache entry's 3865 current_age. 3867 The presence of an Age header field in a response implies that a 3868 response is not first-hand. However, the converse is not true, since 3869 the lack of an Age header field in a response does not imply that the 3870 response is first-hand unless all caches along the request path are 3871 compliant with HTTP/1.1 (i.e., older HTTP caches did not implement 3872 the Age header field). 3874 13.2.4 Expiration Calculations 3876 In order to decide whether a response is fresh or stale, we need to 3877 compare its freshness lifetime to its age. The age is calculated as 3878 described in section 13.2.3; this section describes how to calculate 3879 the freshness lifetime, and to determine if a response has expired. 3880 In the discussion below, the values can be represented in any form 3881 appropriate for arithmetic operations. 3883 We use the term "expires_value" to denote the value of the Expires 3884 header. We use the term "max_age_value" to denote an appropriate 3885 value of the number of seconds carried by the "max-age" directive of 3886 the Cache-Control header in a response (see section 14.9.3). 3888 The max-age directive takes priority over Expires, so if max-age is 3889 present in a response, the calculation is simply: 3891 freshness_lifetime = max_age_value 3893 Otherwise, if Expires is present in the response, the calculation is: 3895 freshness_lifetime = expires_value - date_value 3897 Note that neither of these calculations is vulnerable to clock skew, 3898 since all of the information comes from the origin server. 3900 If none of Expires, Cache-Control: max-age, or Cache-Control: s- 3901 maxage (see section 14.9.3) appears in the response, and the response 3902 does not include other restrictions on caching, the cache MAY compute 3903 a freshness lifetime using a heuristic. The cache MUST attach Warning 3904 113 to any response whose age is more than 24 hours if such warning 3905 has not already been added. 3907 Also, if the response does have a Last-Modified time, the heuristic 3908 expiration value SHOULD be no more than some fraction of the interval 3909 since that time. A typical setting of this fraction might be 10%. 3911 The calculation to determine if a response has expired is quite 3912 simple: 3914 response_is_fresh = (freshness_lifetime > current_age) 3916 13.2.5 Disambiguating Expiration Values 3918 Because expiration values are assigned optimistically, it is possible 3919 for two caches to contain fresh values for the same resource that are 3920 different. 3922 If a client performing a retrieval receives a non-first-hand response 3923 for a request that was already fresh in its own cache, and the Date 3924 header in its existing cache entry is newer than the Date on the new 3925 response, then the client MAY ignore the response. If so, it MAY 3926 retry the request with a "Cache-Control: max-age=0" directive (see 3927 section 14.9), to force a check with the origin server. 3929 If a cache has two fresh responses for the same representation with 3930 different validators, it MUST use the one with the more recent Date 3931 header. This situation might arise because the cache is pooling 3932 responses from other caches, or because a client has asked for a 3933 reload or a revalidation of an apparently fresh cache entry. 3935 13.2.6 Disambiguating Multiple Responses 3937 Because a client might be receiving responses via multiple paths, so 3938 that some responses flow through one set of caches and other 3939 responses flow through a different set of caches, a client might 3940 receive responses in an order different from that in which the origin 3941 server sent them. We would like the client to use the most recently 3942 generated response, even if older responses are still apparently 3943 fresh. 3945 Neither the entity tag nor the expiration value can impose an 3946 ordering on responses, since it is possible that a later response 3947 intentionally carries an earlier expiration time. The Date values are 3948 ordered to a granularity of one second. 3950 When a client tries to revalidate a cache entry, and the response it 3951 receives contains a Date header that appears to be older than the one 3952 for the existing entry, then the client SHOULD repeat the request 3953 unconditionally, and include 3955 Cache-Control: max-age=0 3957 to force any intermediate caches to validate their copies directly 3958 with the origin server, or 3960 Cache-Control: no-cache 3962 to force any intermediate caches to obtain a new copy from the origin 3963 server. 3965 If the Date values are equal, then the client MAY use either response 3966 (or MAY, if it is being extremely prudent, request a new response). 3967 Servers MUST NOT depend on clients being able to choose 3968 deterministically between responses generated during the same second, 3969 if their expiration times overlap. 3971 13.3 Validation Model 3973 When a cache has a stale entry that it would like to use as a 3974 response to a client�s request, it first has to check with the origin 3975 server (or possibly an intermediate cache with a fresh response) to 3976 see if its cached entry is still usable. We call this "validating" 3977 the cache entry. Since we do not want to have to pay the overhead of 3978 retransmitting the full response if the cached entry is good, and we 3979 do not want to pay the overhead of an extra round trip if the cached 3980 entry is invalid, the HTTP/1.1 protocol supports the use of 3981 conditional methods. 3983 The key protocol features for supporting conditional methods are 3984 those concerned with "cache validators." When an origin server 3985 generates a full response, it attaches some sort of validator to it, 3986 which is kept with the cache entry. When a client (user agent or 3987 proxy cache) makes a conditional request for a resource for which it 3988 has a cache entry, it includes the associated validator in the 3989 request. 3991 The server then checks that validator against the current validator 3992 for the entity, and, if they match (see section 13.3.3), it responds 3993 with a special status code (usually, 304 (Not Modified)) and no 3994 entity-body. Otherwise, it returns a full response (including entity- 3995 body). Thus, we avoid transmitting the full response if the validator 3996 matches, and we avoid an extra round trip if it does not match. 3998 In HTTP/1.1, a conditional request looks exactly the same as a normal 3999 request for the same resource, except that it carries a special 4000 header (which includes the validator) that implicitly turns the 4001 method (usually, GET) into a conditional. 4003 The protocol includes both positive and negative senses of cache- 4004 validating conditions. That is, it is possible to request either that 4005 a method be performed if and only if a validator matches or if and 4006 only if no validators match. 4008 Note: a response that lacks a validator may still be cached, and 4009 served from cache until it expires, unless this is explicitly 4010 prohibited by a cache-control directive. However, a cache cannot do 4011 a conditional retrieval if it does not have a validator for the 4012 entity, which means it will not be refreshable after it expires. 4014 13.3.1 Last-Modified Dates 4016 The Last-Modified entity-header field value is often used as a cache 4017 validator. In simple terms, a cache entry is considered to be valid 4018 if the entity has not been modified since the Last-Modified value. 4020 13.3.2 Entity Tag Cache Validators 4022 The ETag response-header field value, an entity tag, provides for an 4023 "opaque" cache validator. This might allow more reliable validation 4024 in situations where it is inconvenient to store modification dates, 4025 where the one-second resolution of HTTP date values is not 4026 sufficient, or where the origin server wishes to avoid certain 4027 paradoxes that might arise from the use of modification dates. 4029 Entity Tags are described in section 3.11. The headers used with 4030 entity tags are described in sections 14.19, 14.24, 14.26 and 14.44. 4032 13.3.3 Weak and Strong Validators 4034 Since both origin servers and caches will compare two validators to 4036 decide if they represent the same or different entities, one normally 4037 would expect that if the entity (the entity-body or any entity- 4038 headers) changes in any way, then the associated validator would 4039 change as well. If this is true, then we call this validator a 4040 "strong validator." 4042 However, there might be cases when a server prefers to change the 4043 validator only on semantically significant changes, and not when 4044 insignificant aspects of the entity change. A validator that does not 4045 always change when the resource changes is a "weak validator." 4047 Entity tags are normally "strong validators," but the protocol 4048 provides a mechanism to tag an entity tag as "weak." One can think of 4049 a strong validator as one that changes whenever the bits of an entity 4050 changes, while a weak value changes whenever the meaning of an entity 4051 changes. Alternatively, one can think of a strong validator as part 4052 of an identifier for a specific entity, while a weak validator is 4053 part of an identifier for a set of semantically equivalent entities. 4055 Note: One example of a strong validator is an integer that is 4056 incremented in stable storage every time an entity is changed. 4057 An entity's modification time, if represented with one-second 4058 resolution, could be a weak validator, since it is possible that 4059 the resource might be modified twice during a single second. 4061 Support for weak validators is optional. However, weak validators 4062 allow for more efficient caching of equivalent objects; for 4063 example, a hit counter on a site is probably good enough if it is 4064 updated every few days or weeks, and any value during that period 4065 is likely "good enough" to be equivalent. 4067 A "use" of a validator is either when a client generates a request 4068 and includes the validator in a validating header field, or when a 4069 server compares two validators. 4071 Strong validators are usable in any context. Weak validators are only 4072 usable in contexts that do not depend on exact equality of an entity. 4073 For example, either kind is usable for a conditional GET of a full 4074 entity. However, only a strong validator is usable for a sub-range 4075 retrieval, since otherwise the client might end up with an internally 4076 inconsistent entity. 4078 Clients MAY issue simple (non-subrange) GET requests with either weak 4079 validators or strong validators. Clients MUST NOT use weak validators 4080 in other forms of request. 4082 The only function that the HTTP/1.1 protocol defines on validators is 4083 comparison. There are two validator comparison functions, depending 4084 on whether the comparison context allows the use of weak validators 4085 or not: 4087 o The strong comparison function: in order to be considered equal, 4088 both validators MUST be identical in every way, and both MUST NOT 4089 be weak. 4090 o The weak comparison function: in order to be considered equal, both 4091 validators MUST be identical in every way, but either or both of 4092 them MAY be tagged as "weak" without affecting the result. 4093 An entity tag is strong unless it is explicitly tagged as weak. 4094 Section 3.11 gives the syntax for entity tags. 4096 A Last-Modified time, when used as a validator in a request, is 4097 implicitly weak unless it is possible to deduce that it is strong, 4098 using the following rules: 4100 o The validator is being compared by an origin server to the actual 4101 current validator for the entity and, 4102 o That origin server reliably knows that the associated entity did 4103 not change twice during the second covered by the presented 4104 validator. 4105 or 4106 o The validator is about to be used by a client in an If-Modified- 4107 Since or If-Unmodified-Since header, because the client has a cache 4108 entry for the associated entity, and 4109 o That cache entry includes a Date value, which gives the time when 4110 the origin server sent the original response, and 4111 o The presented Last-Modified time is at least 60 seconds before the 4112 Date value. 4113 or 4114 o The validator is being compared by an intermediate cache to the 4115 validator stored in its cache entry for the entity, and 4116 o That cache entry includes a Date value, which gives the time when 4117 the origin server sent the original response, and 4118 o The presented Last-Modified time is at least 60 seconds before the 4119 Date value. 4120 This method relies on the fact that if two different responses were 4121 sent by the origin server during the same second, but both had the 4122 same Last-Modified time, then at least one of those responses would 4123 have a Date value equal to its Last-Modified time. The arbitrary 60- 4124 second limit guards against the possibility that the Date and Last- 4125 Modified values are generated from different clocks, or at somewhat 4126 different times during the preparation of the response. An 4127 implementation MAY use a value larger than 60 seconds, if it is 4128 believed that 60 seconds is too short. 4130 If a client wishes to perform a sub-range retrieval on a value for 4131 which it has only a Last-Modified time and no opaque validator, it 4132 MAY do this only if the Last-Modified time is strong in the sense 4133 described here. 4135 A cache or origin server receiving a conditional request, other than 4136 a full-body GET request, MUST use the strong comparison function to 4137 evaluate the condition. 4139 These rules allow HTTP/1.1 caches and clients to safely perform sub- 4140 range retrievals on values that have been obtained from HTTP/1.0 4141 servers. 4143 13.3.4 Rules for When to Use Entity Tags and Last-Modified Dates 4145 We adopt a set of rules and recommendations for origin servers, 4146 clients, and caches regarding when various validator types ought to 4147 be used, and for what purposes. 4149 HTTP/1.1 origin servers: 4151 o SHOULD send an entity tag validator unless it is not feasible to 4152 generate one. 4153 o MAY send a weak entity tag instead of a strong entity tag, if 4154 performance considerations support the use of weak entity tags, or 4155 if it is unfeasible to send a strong entity tag. 4156 o SHOULD send a Last-Modified value if it is feasible to send one, 4157 unless the risk of a breakdown in semantic transparency that could 4158 result from using this date in an If-Modified-Since header would 4159 lead to serious problems. 4161 In other words, the preferred behavior for an HTTP/1.1 origin server 4162 is to send both a strong entity tag and a Last-Modified value. 4163 In order to be legal, a strong entity tag MUST change whenever the 4164 associated entity value changes in any way. A weak entity tag SHOULD 4165 change whenever the associated entity changes in a semantically 4166 significant way. 4168 Note: in order to provide semantically transparent caching, an 4169 origin server must avoid reusing a specific strong entity tag value 4171 for two different entities, or reusing a specific weak entity tag 4172 value for two semantically different entities. Cache entries might 4173 persist for arbitrarily long periods, regardless of expiration 4174 times, so it might be inappropriate to expect that a cache will 4175 never again attempt to validate an entry using a validator that it 4176 obtained at some point in the past. 4178 HTTP/1.1 clients: 4180 o If an entity tag has been provided by the origin server, MUST use 4181 that entity tag in any cache-conditional request (using If-Match or 4182 If-None-Match). 4184 o If only a Last-Modified value has been provided by the origin 4185 server, SHOULD use that value in non-subrange cache-conditional 4186 requests (using If-Modified-Since). 4187 o If only a Last-Modified value has been provided by an HTTP/1.0 4188 origin server, MAY use that value in subrange cache-conditional 4189 requests (using If-Unmodified-Since:). The user agent SHOULD 4190 provide a way to disable this, in case of difficulty. 4191 o If both an entity tag and a Last-Modified value have been provided 4192 by the origin server, SHOULD use both validators in cache- 4193 conditional requests. This allows both HTTP/1.0 and HTTP/1.1 caches 4194 to respond appropriately. 4196 An HTTP/1.1 origin server, upon receiving a conditional request that 4197 includes both a Last-Modified date (e.g., in an If-Modified-Since or 4198 If-Unmodified-Since header field) and one or more entity tags (e.g., 4199 in an If-Match, If-None-Match, or If-Range header field) as cache 4200 validators, MUST NOT return a response status of 304 (Not Modified) 4201 unless doing so is consistent with all of the conditional header 4202 fields in the request. 4204 An HTTP/1.1 caching proxy, upon receiving a conditional request that 4205 includes both a Last-Modified date and one or more entity tags as 4206 cache validators, MUST NOT return a locally cached response to the 4207 client unless that cached response is consistent with all of the 4208 conditional header fields in the request. 4210 Note: The general principle behind these rules is that HTTP/1.1 4211 servers and clients should transmit as much non-redundant 4212 information as is available in their responses and requests. 4213 HTTP/1.1 systems receiving this information will make the most 4214 conservative assumptions about the validators they receive. 4216 HTTP/1.0 clients and caches will ignore entity tags. Generally, 4217 last-modified values received or used by these systems will support 4218 transparent and efficient caching, and so HTTP/1.1 origin servers 4219 should provide Last-Modified values. In those rare cases where the 4220 use of a Last-Modified value as a validator by an HTTP/1.0 system 4221 could result in a serious problem, then HTTP/1.1 origin servers 4222 should not provide one. 4224 13.3.5 Non-validating Conditionals 4226 The principle behind entity tags is that only the service author 4227 knows the semantics of a resource well enough to select an 4228 appropriate cache validation mechanism, and the specification of any 4229 validator comparison function more complex than byte-equality would 4230 open up a can of worms. Thus, comparisons of any other headers 4231 (except Last-Modified, for compatibility with HTTP/1.0) are never 4232 used for purposes of validating a cache entry. 4234 13.4 Response Cacheability 4236 Unless specifically constrained by a cache-control (section 14.9) 4237 directive, a caching system MAY always store a successful response 4238 (see section 13.8) as a cache entry, MAY return it without validation 4239 if it is fresh, and MAY return it after successful validation. If 4240 there is neither a cache validator nor an explicit expiration time 4241 associated with a response, we do not expect it to be cached, but 4242 certain caches MAY violate this expectation (for example, when little 4243 or no network connectivity is available). A client can usually detect 4244 that such a response was taken from a cache by comparing the Date 4245 header to the current time. 4247 Note: some HTTP/1.0 caches are known to violate this expectation 4248 without providing any Warning. 4250 However, in some cases it might be inappropriate for a cache to 4251 retain an entity, or to return it in response to a subsequent 4252 request. This might be because absolute semantic transparency is 4253 deemed necessary by the service author, or because of security or 4254 privacy considerations. Certain cache-control directives are 4255 therefore provided so that the server can indicate that certain 4256 resource entities, or portions thereof, are not to be cached 4257 regardless of other considerations. 4259 Note that section 14.8 normally prevents a shared cache from saving 4260 and returning a response to a previous request if that request 4261 included an Authorization header. 4263 A response received with a status code of 200, 203, 206, 300, 301 or 4264 410 MAY be stored by a cache and used in reply to a subsequent 4265 request, subject to the expiration mechanism, unless a cache-control 4266 directive prohibits caching. However, a cache that does not support 4267 the Range and Content-Range headers MUST NOT cache 206 (Partial 4268 Content) responses. 4270 A response received with any other status code (e.g. status codes 302 4271 and 307) MUST NOT be returned in a reply to a subsequent request 4272 unless there are cache-control directives or another header(s) that 4273 explicitly allow it. For example, these include the following: an 4274 Expires header (section 14.21); a "max-age", "s-maxage", "must- 4275 revalidate", "proxy-revalidate", "public" or "private" cache-control 4276 directive (section 14.9). 4278 13.5 Constructing Responses From Caches 4280 The purpose of an HTTP cache is to store information received in 4281 response to requests for use in responding to future requests. In 4282 many cases, a cache simply returns the appropriate parts of a 4283 response to the requester. However, if the cache holds a cache entry 4284 based on a previous response, it might have to combine parts of a new 4285 response with what is held in the cache entry. 4287 13.5.1 End-to-end and Hop-by-hop Headers 4289 For the purpose of defining the behavior of caches and non-caching 4290 proxies, we divide HTTP headers into two categories: 4292 o End-to-end headers, which are transmitted to the ultimate 4293 recipient of a request or response. End-to-end headers in responses 4294 MUST be stored as part of a cache entry and MUST be transmitted in 4295 any response formed from a cache entry. 4296 o Hop-by-hop headers, which are meaningful only for a single 4297 transport-level connection, and are not stored by caches or 4298 forwarded by proxies. 4300 The following HTTP/1.1 headers are hop-by-hop headers: 4302 o Connection 4303 o Keep-Alive 4304 o Proxy-Authenticate 4305 o Proxy-Authorization 4306 o TE 4307 o Trailer 4308 o Transfer-Encoding 4309 o Upgrade 4311 All other headers defined by HTTP/1.1 are end-to-end headers. 4313 Other hop-by-hop headers MUST be listed in a Connection header, 4314 (section 14.10) to be introduced into HTTP/1.1 (or later). 4316 13.5.2 Non-modifiable Headers 4318 Some features of the HTTP/1.1 protocol, such as Digest 4319 Authentication, depend on the value of certain end-to-end headers. A 4320 transparent proxy SHOULD NOT modify an end-to-end header unless the 4321 definition of that header requires or specifically allows that. 4322 A transparent proxy MUST NOT modify any of the following fields in a 4323 request or response, and it MUST NOT add any of these fields if not 4324 already present: 4326 o Content-Location 4327 o Content-MD5 4328 o ETag 4329 o Last-Modified 4331 A transparent proxy MUST NOT modify any of the following fields in a 4332 response: 4334 o Expires 4336 but it MAY add any of these fields if not already present. If an Expires 4337 header is added, it MUST be given a field-value identical to that of the 4338 Date header in that response. 4340 A proxy MUST NOT modify or add any of the following fields in a 4341 message that contains the no-transform cache-control directive, or in 4342 any request: 4344 o Content-Encoding 4345 o Content-Range 4346 o Content-Type 4348 A non-transparent proxy MAY modify or add these fields to a message 4349 that does not include no-transform, but if it does so, it MUST add a 4350 Warning 214 (Transformation applied) if one does not already appear 4351 in the message (see section 14.46). 4353 Warning: unnecessary modification of end-to-end headers might cause 4354 authentication failures if stronger authentication mechanisms are 4355 introduced in later versions of HTTP. Such authentication 4356 mechanisms MAY rely on the values of header fields not listed here. 4358 The Content-Length field of a request or response is added or deleted 4359 according to the rules in section 4.4. A transparent proxy MUST 4360 preserve the entity-length (section 7.2.2) of the entity-body, 4361 although it MAY change the transfer-length (section 4.4). 4363 13.5.3 Combining Headers 4365 When a cache makes a validating request to a server, and the server 4366 provides a 304 (Not Modified) response or a 206 (Partial Content) 4367 response, the cache then constructs a response to send to the 4368 requesting client. 4370 If the status code is 304 (Not Modified), the cache uses the entity- 4371 body stored in the cache entry as the entity-body of this outgoing 4372 response. If the status code is 206 (Partial Content) and the ETag or 4373 Last-Modified headers match exactly, the cache MAY combine the 4374 contents stored in the cache entry with the new contents received in 4375 the response and use the result as the entity-body of this outgoing 4376 response, (see 13.5.4). 4378 The end-to-end headers stored in the cache entry are used for the 4379 constructed response, except that 4380 o any stored Warning headers with warn-code 1xx (see section 14.46) 4381 MUST be deleted from the cache entry and the forwarded response. 4382 o any stored Warning headers with warn-code 2xx MUST be retained in 4383 the cache entry and the forwarded response. 4385 o any end-to-end headers provided in the 304 or 206 response MUST 4386 replace the corresponding headers from the cache entry. 4388 Unless the cache decides to remove the cache entry, it MUST also 4389 replace the end-to-end headers stored with the cache entry with 4390 corresponding headers received in the incoming response, except for 4391 Warning headers as described immediately above. If a header field- 4392 name in the incoming response matches more than one header in the 4393 cache entry, all such old headers MUST be replaced. 4395 In other words, the set of end-to-end headers received in the 4396 incoming response overrides all corresponding end-to-end headers 4397 stored with the cache entry (except for stored Warning headers with 4398 warn-code 1xx, which are deleted even if not overridden). 4400 Note: this rule allows an origin server to use a 304 (Not Modified) 4401 or a 206 (Partial Content) response to update any header associated 4402 with a previous response for the same entity or sub-ranges thereof, 4403 although it might not always be meaningful or correct to do so. 4404 This rule does not allow an origin server to use a 304 (Not 4405 Modified) or a 206 (Partial Content) response to entirely delete a 4406 header that it had provided with a previous response. 4408 13.5.4 Combining Byte Ranges 4410 A response might transfer only a subrange of the bytes of an entity- 4411 body, either because the request included one or more Range 4412 specifications, or because a connection was broken prematurely. After 4413 several such transfers, a cache might have received several ranges of 4414 the same entity-body. 4416 If a cache has a stored non-empty set of subranges for an entity, and 4417 an incoming response transfers another subrange, the cache MAY 4418 combine the new subrange with the existing set if both the following 4419 conditions are met: 4421 o Both the incoming response and the cache entry have a cache 4422 validator. 4423 o The two cache validators match using the strong comparison function 4424 (see section 13.3.3). 4426 If either requirement is not met, the cache MUST use only the most 4427 recent partial response (based on the Date values transmitted with 4428 every response, and using the incoming response if these values are 4429 equal or missing), and MUST discard the other partial information. 4431 13.6 Caching Negotiated Responses 4433 Use of server-driven content negotiation (section 12.1), as indicated 4434 by the presence of a Vary header field in a response, alters the 4435 conditions and procedure by which a cache can use the response for 4436 subsequent requests. See section 14.44 for use of the Vary header 4437 field by servers. 4439 A server SHOULD use the Vary header field to inform a cache of what 4440 request-header fields were used to select among multiple 4441 representations of a cacheable response subject to server-driven 4442 negotiation. The set of header fields named by the Vary field value 4443 is known as the "selecting" request-headers. 4445 When the cache receives a subsequent request whose Request-URI 4446 specifies one or more cache entries including a Vary header field, 4447 the cache MUST NOT use such a cache entry to construct a response to 4448 the new request unless all of the selecting request-headers present 4449 in the new request match the corresponding stored request-headers in 4450 the original request. 4452 The selecting request-headers from two requests are defined to match 4453 if and only if the selecting request-headers in the first request can 4454 be transformed to the selecting request-headers in the second request 4455 by adding or removing linear white space (LWS) at places where this 4456 is allowed by the corresponding BNF, and/or combining multiple 4457 message-header fields with the same field name following the rules 4458 about message headers in section 4.2. 4460 A Vary header field-value of "*" always fails to match and subsequent 4461 requests on that resource can only be properly interpreted by the 4462 origin server. 4464 If the selecting request header fields for the cached entry do not 4465 match the selecting request header fields of the new request, then 4466 the cache MUST NOT use a cached entry to satisfy the request unless 4467 it first relays the new request to the origin server in a conditional 4468 request and the server responds with 304 (Not Modified), including an 4469 entity tag or Content-Location that indicates the entity to be used. 4471 If an entity tag was assigned to a cached representation, the 4472 forwarded request SHOULD be conditional and include the entity tags 4473 in an If-None-Match header field from all its cache entries for the 4474 resource. This conveys to the server the set of entities currently 4475 held by the cache, so that if any one of these entities matches the 4476 requested entity, the server can use the ETag header field in its 304 4477 (Not Modified) response to tell the cache which entry is appropriate. 4478 If the entity-tag of the new response matches that of an existing 4479 entry, the new response SHOULD be used to update the header fields of 4480 the existing entry, and the result MUST be returned to the client. 4482 If any of the existing cache entries contains only partial content 4483 for the associated entity, its entity-tag SHOULD NOT be included in 4484 the If-None-Match header field unless the request is for a range that 4485 would be fully satisfied by that entry. 4487 If a cache receives a successful response whose Content-Location 4488 field matches that of an existing cache entry for the same Request- 4489 URI, whose entity-tag differs from that of the existing entry, and 4490 whose Date is more recent than that of the existing entry, the 4491 existing entry SHOULD NOT be returned in response to future requests 4492 and SHOULD be deleted from the cache. 4494 13.7 Shared and Non-Shared Caches 4496 For reasons of security and privacy, it is necessary to make a 4497 distinction between "shared" and "non-shared" caches. A non-shared 4498 cache is one that is accessible only to a single user. Accessibility 4499 in this case SHOULD be enforced by appropriate security mechanisms. 4500 All other caches are considered to be "shared." Other sections of 4501 this specification place certain constraints on the operation of 4502 shared caches in order to prevent loss of privacy or failure of 4503 access controls. 4505 13.8 Errors or Incomplete Response Cache Behavior 4507 A cache that receives an incomplete response (for example, with fewer 4508 bytes of data than specified in a Content-Length header) MAY store 4509 the response. However, the cache MUST treat this as a partial 4510 response. Partial responses MAY be combined as described in section 4511 13.5.4; the result might be a full response or might still be 4512 partial. A cache MUST NOT return a partial response to a client 4513 without explicitly marking it as such, using the 206 (Partial 4514 Content) status code. A cache MUST NOT return a partial response 4515 using a status code of 200 (OK). 4517 If a cache receives a 5xx response while attempting to revalidate an 4518 entry, it MAY either forward this response to the requesting client, 4519 or act as if the server failed to respond. In the latter case, it MAY 4520 return a previously received response unless the cached entry 4521 includes the "must-revalidate" cache-control directive (see section 4522 14.9). 4524 13.9 Side Effects of GET and HEAD 4526 Unless the origin server explicitly prohibits the caching of their 4527 responses, the application of GET and HEAD methods to any resources 4528 SHOULD NOT have side effects that would lead to erroneous behavior if 4529 these responses are taken from a cache. They MAY still have side 4530 effects, but a cache is not required to consider such side effects in 4531 its caching decisions. Caches are always expected to observe an 4532 origin server�s explicit restrictions on caching. 4534 We note one exception to this rule: since some applications have 4535 traditionally used GETs and HEADs with query URLs (those containing a 4536 "?" in the rel_path part) to perform operations with significant side 4537 effects, caches MUST NOT treat responses to such URIs as fresh unless 4538 the server provides an explicit expiration time. This specifically 4539 means that responses from HTTP/1.0 servers for such URIs SHOULD NOT 4540 be taken from a cache. See section 9.1.1 for related information. 4542 13.10 Invalidation After Updates or Deletions 4544 The effect of certain methods performed on a resource at the origin 4545 server might cause one or more existing cache entries to become non- 4546 transparently invalid. That is, although they might continue to be 4547 "fresh," they do not accurately reflect what the origin server would 4548 return for a new request on that resource. 4550 There is no way for the HTTP protocol to guarantee that all such 4551 cache entries are marked invalid. For example, the request that 4552 caused the change at the origin server might not have gone through 4553 the proxy where a cache entry is stored. However, several rules help 4554 reduce the likelihood of erroneous behavior. 4556 In this section, the phrase "invalidate an entity" means that the 4557 cache will either remove all instances of that entity from its 4558 storage, or will mark these as "invalid" and in need of a mandatory 4559 revalidation before they can be returned in response to a subsequent 4560 request. 4562 Some HTTP methods MUST cause a cache to invalidate an entity. This is 4563 either the entity referred to by the Request-URI, or by the Location 4564 or Content-Location headers (if present). These methods are: 4566 o PUT 4567 o DELETE 4568 o POST 4570 An invalidation based on the URI in a Location or Content-Location 4571 header MUST NOT be performed if the host part of that URI differs 4572 from the host part in the Request-URI. This helps prevent denial of 4573 service attacks. 4575 A cache that passes through requests for methods it does not 4576 understand SHOULD invalidate any entities referred to by the Request- 4577 URI. 4579 13.11 Write-Through Mandatory 4581 All methods that might be expected to cause modifications to the 4582 origin server's resources MUST be written through to the origin 4583 server. This currently includes all methods except for GET and HEAD. 4585 A cache MUST NOT reply to such a request from a client before having 4586 transmitted the request to the inbound server, and having received a 4587 corresponding response from the inbound server. This does not prevent 4588 a proxy cache from sending a 100 (Continue) response before the 4589 inbound server has sent its final reply. 4591 The alternative (known as "write-back" or "copy-back" caching) is not 4592 allowed in HTTP/1.1, due to the difficulty of providing consistent 4593 updates and the problems arising from server, cache, or network 4594 failure prior to write-back. 4596 13.12 Cache Replacement 4598 If a new cacheable (see sections 14.9.2, 13.2.5, 13.2.6 and 13.8) 4599 response is received from a resource while any existing responses for 4600 the same resource are cached, the cache SHOULD use the new response 4601 to reply to the current request. It MAY insert it into cache storage 4602 and MAY, if it meets all other requirements, use it to respond to any 4603 future requests that would previously have caused the old response to 4604 be returned. If it inserts the new response into cache storage the 4605 rules in section 13.5.3 apply. 4607 Note: a new response that has an older Date header value than 4608 existing cached responses is not cacheable. 4610 13.13 History Lists 4612 User agents often have history mechanisms, such as "Back" buttons and 4613 history lists, which can be used to redisplay an entity retrieved 4614 earlier in a session. 4616 History mechanisms and caches are different. In particular history 4617 mechanisms SHOULD NOT try to show a semantically transparent view of 4618 the current state of a resource. Rather, a history mechanism is meant 4619 to show exactly what the user saw at the time when the resource was 4620 retrieved. 4622 By default, an expiration time does not apply to history mechanisms. 4624 If the entity is still in storage, a history mechanism SHOULD display 4625 it even if the entity has expired, unless the user has specifically 4626 configured the agent to refresh expired history documents. 4628 This is not to be construed to prohibit the history mechanism from 4629 telling the user that a view might be stale. 4631 Note: if history list mechanisms unnecessarily prevent users from 4632 viewing stale resources, this will tend to force service authors to 4633 avoid using HTTP expiration controls and cache controls when they 4634 would otherwise like to. Service authors may consider it important 4635 that users not be presented with error messages or warning messages 4636 when they use navigation controls (such as BACK) to view previously 4637 fetched resources. Even though sometimes such resources ought not 4638 to cached, or ought to expire quickly, user interface 4639 considerations may force service authors to resort to other means 4640 of preventing caching (e.g. "once-only" URLs) in order not to 4641 suffer the effects of improperly functioning history mechanisms. 4643 14 Header Field Definitions 4645 This section defines the syntax and semantics of all standard 4646 HTTP/1.1 header fields. For entity-header fields, both sender and 4647 recipient refer to either the client or the server, depending on who 4648 sends and who receives the entity. 4650 14.1 Accept 4652 The Accept request-header field can be used to specify certain media 4653 types which are acceptable for the response. Accept headers can be 4654 used to indicate that the request is specifically limited to a small 4655 set of desired types, as in the case of a request for an in-line 4656 image. 4658 Accept = "Accept" ":" 4659 #( media-range [ accept-params ] ) 4661 media-range = ( "*/*" 4662 | ( type "/" "*" ) 4663 | ( type "/" subtype ) 4664 ) *( ";" parameter ) 4665 accept-params = ";" "q" "=" qvalue *( accept-extension ) 4667 accept-extension = ";" token [ "=" ( token | quoted-string ) ] 4669 The asterisk "*" character is used to group media types into ranges, 4670 with "*/*" indicating all media types and "type/*" indicating all 4671 subtypes of that type. The media-range MAY include media type 4672 parameters that are applicable to that range. 4674 Each media-range MAY be followed by one or more accept-params, 4675 beginning with the "q" parameter for indicating a relative quality 4676 factor. The first "q" parameter (if any) separates the media-range 4677 parameter(s) from the accept-params. Quality factors allow the user 4678 or user agent to indicate the relative degree of preference for that 4679 media-range, using the qvalue scale from 0 to 1 (section 3.9). The 4680 default value is q=1. 4682 Note: Use of the "q" parameter name to separate media type 4683 parameters from Accept extension parameters is due to historical 4684 practice. Although this prevents any media type parameter named "q" 4685 from being used with a media range, such an event is believed to be 4686 unlikely given the lack of any "q" parameters in the IANA media 4687 type registry and the rare usage of any media type parameters in 4688 Accept. Future media types are discouraged from registering any 4689 parameter named "q". 4691 The example 4693 Accept: audio/*; q=0.2, audio/basic 4695 SHOULD be interpreted as "I prefer audio/basic, but send me any audio 4696 type if it is the best available after an 80% mark-down in quality." 4698 If no Accept header field is present, then it is assumed that the 4699 client accepts all media types. If an Accept header field is present, 4700 and if the server cannot send a response which is acceptable 4701 according to the combined Accept field value, then the server SHOULD 4702 send a 406 (not acceptable) response. 4704 A more elaborate example is 4706 Accept: text/plain; q=0.5, text/html, 4707 text/x-dvi; q=0.8, text/x-c 4709 Verbally, this would be interpreted as "text/html and text/x-c are 4710 the preferred media types, but if they do not exist, then send the 4711 text/x-dvi entity, and if that does not exist, send the text/plain 4712 entity." 4714 Media ranges can be overridden by more specific media ranges or 4715 specific media types. If more than one media range applies to a given 4716 type, the most specific reference has precedence. For example, 4718 Accept: text/*, text/html, text/html;level=1, */* 4720 have the following precedence: 4722 1) text/html;level=1 4723 2) text/html 4724 3) text/* 4725 4) */* 4727 The media type quality factor associated with a given type is 4728 determined by finding the media range with the highest precedence 4729 which matches that type. For example, 4731 Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1, 4732 text/html;level=2;q=0.4, */*;q=0.5 4734 would cause the following values to be associated: 4736 text/html;level=1 = 1 4737 text/html = 0.7 4738 text/plain = 0.3 4739 image/jpeg = 0.5 4740 text/html;level=2 = 0.4 4741 text/html;level=3 = 0.7 4743 Note: A user agent might be provided with a default set of quality 4744 values for certain media ranges. However, unless the user agent is 4745 a closed system which cannot interact with other rendering agents, 4746 this default set ought to be configurable by the user. 4748 14.2 Accept-Charset 4750 The Accept-Charset request-header field can be used to indicate what 4751 character sets are acceptable for the response. This field allows 4752 clients capable of understanding more comprehensive or special- 4753 purpose character sets to signal that capability to a server which is 4754 capable of representing documents in those character sets. 4756 Accept-Charset = "Accept-Charset" ":" 4757 1#( ( charset | "*" )[ ";" "q" "=" qvalue ] ) 4758 Character set values are described in section 3.4. Each charset MAY 4759 be given an associated quality value which represents the user�s 4760 preference for that charset. The default value is q=1. An example is 4762 Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 4764 The special value "*", if present in the Accept-Charset field, 4765 matches every character set (including ISO-8859-1) which is not 4766 mentioned elsewhere in the Accept-Charset field. If no "*" is present 4767 in an Accept-Charset field, then all character sets not explicitly 4768 mentioned get a quality value of 0, except for ISO-8859-1, which gets 4769 a quality value of 1 if not explicitly mentioned. 4771 If no Accept-Charset header is present, the default is that any 4772 character set is acceptable. If an Accept-Charset header is present, 4773 and if the server cannot send a response which is acceptable 4774 according to the Accept-Charset header, then the server SHOULD send 4775 an error response with the 406 (not acceptable) status code, though 4776 the sending of an unacceptable response is also allowed. 4778 14.3 Accept-Encoding 4780 The Accept-Encoding request-header field is similar to Accept, but 4781 restricts the content-codings (section 3.5) that are acceptable in 4782 the response. 4784 Accept-Encoding = "Accept-Encoding" ":" 4785 1#( codings [ ";" "q" "=" qvalue ] ) 4786 codings = ( content-coding | "*" ) 4788 Examples of its use are: 4790 Accept-Encoding: compress, gzip 4791 Accept-Encoding: 4792 Accept-Encoding: * 4793 Accept-Encoding: compress;q=0.5, gzip;q=1.0 4794 Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 4796 A server tests whether a content-coding is acceptable, according to 4797 an Accept-Encoding field, using these rules: 4799 1. If the content-coding is one of the content-codings listed in 4800 the Accept-Encoding field, then it is acceptable, unless it is 4801 accompanied by a qvalue of 0. (As defined in section 3.9, a qvalue 4802 of 0 means "not acceptable.") 4803 2. The special "*" symbol in an Accept-Encoding field matches any 4804 available content-coding not explicitly listed in the header field. 4805 3. If multiple content-codings are acceptable, then the acceptable 4806 content-coding with the highest non-zero qvalue is preferred. 4807 4. The "identity" content-coding is always acceptable, unless 4808 specifically refused because the Accept-Encoding field includes 4809 "identity;q=0", or because the field includes "*;q=0" and does not 4810 explicitly include the "identity" content-coding. If the Accept- 4811 Encoding field-value is empty, then only the "identity" encoding is 4812 acceptable. 4814 If an Accept-Encoding field is present in a request, and if the 4815 server cannot send a response which is acceptable according to the 4816 Accept-Encoding header, then the server SHOULD send an error response 4817 with the 406 (Not Acceptable) status code. 4819 If no Accept-Encoding field is present in a request, the server MAY 4820 assume that the client will accept any content coding. In this case, 4821 if "identity" is one of the available content-codings, then the 4822 server SHOULD use the "identity" content-coding, unless it has 4823 additional information that a different content-coding is meaningful 4824 to the client. 4826 Note: If the request does not include an Accept-Encoding field, and 4827 if the "identity" content-coding is unavailable, then content- 4828 codings commonly understood by HTTP/1.0 clients (i.e., "gzip" and 4829 "compress") are preferred; some older clients improperly display 4830 messages sent with other content-codings. The server might also 4831 make this decision based on information about the particular user- 4832 agent or client. 4834 Note: Most HTTP/1.0 applications do not recognize or obey qvalues 4835 associated with content-codings. This means that qvalues will not 4836 work and are not permitted with x-gzip or x-compress. 4838 14.4 Accept-Language 4840 The Accept-Language request-header field is similar to Accept, but 4841 restricts the set of natural languages that are preferred as a 4842 response to the request. Language tags are defined in section 3.10. 4844 Accept-Language = "Accept-Language" ":" 4845 1#( language-range [ ";" "q" "=" qvalue ] ) 4846 language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" ) 4848 Each language-range MAY be given an associated quality value which 4849 represents an estimate of the user's preference for the languages 4850 specified by that range. The quality value defaults to "q=1". For 4851 example, 4853 Accept-Language: da, en-gb;q=0.8, en;q=0.7 4855 would mean: "I prefer Danish, but will accept British English and 4856 other types of English." A language-range matches a language-tag if 4857 it exactly equals the tag, or if it exactly equals a prefix of the 4858 tag such that the first tag character following the prefix is "-". 4859 The special range "*", if present in the Accept-Language field, 4860 matches every tag not matched by any other range present in the 4861 Accept-Language field. 4863 Note: This use of a prefix matching rule does not imply that 4864 language tags are assigned to languages in such a way that it is 4865 always true that if a user understands a language with a certain 4866 tag, then this user will also understand all languages with tags 4867 for which this tag is a prefix. The prefix rule simply allows the 4868 use of prefix tags if this is the case. 4870 The language quality factor assigned to a language-tag by the Accept- 4871 Language field is the quality value of the longest language-range in 4872 the field that matches the language-tag. If no language-range in the 4873 field matches the tag, the language quality factor assigned is 0. If 4874 no Accept-Language header is present in the request, the server 4875 SHOULD assume that all languages are equally acceptable. If an 4876 Accept-Language header is present, then all languages which are 4877 assigned a quality factor greater than 0 are acceptable. 4879 It might be contrary to the privacy expectations of the user to send 4880 an Accept-Language header with the complete linguistic preferences of 4881 the user in every request. For a discussion of this issue, see 4882 section 15.1.4. 4884 As intelligibility is highly dependent on the individual user, it is 4885 recommended that client applications make the choice of linguistic 4886 preference available to the user. If the choice is not made 4887 available, then the Accept-Language header field MUST NOT be given in 4888 the request. 4890 Note: When making the choice of linguistic preference available to 4891 the user, we remind implementors of the fact that users are not 4892 familiar with the details of language matching as described above, 4893 and should provide appropriate guidance. As an example, users might 4894 assume that on selecting "en-gb", they will be served any kind of 4895 English document if British English is not available. A user agent 4896 might suggest in such a case to add "en" to get the best matching 4897 behavior. 4899 14.5 Accept-Ranges 4901 The Accept-Ranges response-header field allows the server to indicate 4902 its acceptance of range requests for a resource: 4904 Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges 4906 acceptable-ranges = 1#range-unit | "none" 4908 Origin servers that accept byte-range requests MAY send 4910 Accept-Ranges: bytes 4912 but are not required to do so. Clients MAY generate byte-range 4913 requests without having received this header for the resource 4914 involved. Range units are defined in section 3.12. 4916 Servers that do not accept any kind of range request for a resource 4917 MAY send 4919 Accept-Ranges: none 4921 to advise the client not to attempt a range request. 4923 14.6 Age 4925 The Age response-header field conveys the sender's estimate of the 4926 amount of time since the response (or its revalidation) was generated 4927 at the origin server. A cached response is "fresh" if its age does 4928 not exceed its freshness lifetime. Age values are calculated as 4929 specified in section 13.2.3. 4931 Age = "Age" ":" age-value 4932 age-value = delta-seconds 4934 Age values are non-negative decimal integers, representing time in 4935 seconds. 4937 If a cache receives a value larger than the largest positive integer 4938 it can represent, or if any of its age calculations overflows, it 4939 MUST transmit an Age header with a value of 2147483648 (2^31). An 4940 HTTP/1.1 server that includes a cache MUST include an Age header 4941 field in every response generated from its own cache. Caches SHOULD 4942 use an arithmetic type of at least 31 bits of range. 4944 14.7 Allow 4946 The Allow entity-header field lists the set of methods supported by 4947 the resource identified by the Request-URI. The purpose of this field 4948 is strictly to inform the recipient of valid methods associated with 4949 the resource. An Allow header field MUST be present in a 405 (Method 4950 Not Allowed) response. 4952 Allow = "Allow" ":" #Method 4954 Example of use: 4956 Allow: GET, HEAD, PUT 4958 This field cannot prevent a client from trying other methods. 4959 However, the indications given by the Allow header field value SHOULD 4960 be followed. The actual set of allowed methods is defined by the 4961 origin server at the time of each request. 4963 The Allow header field MAY be provided with a PUT request to 4964 recommend the methods to be supported by the new or modified 4965 resource. The server is not required to support these methods and 4966 SHOULD include an Allow header in the response giving the actual 4967 supported methods. 4969 A proxy MUST NOT modify the Allow header field even if it does not 4970 understand all the methods specified, since the user agent might have 4971 other means of communicating with the origin server. 4973 14.8 Authorization 4975 A user agent that wishes to authenticate itself with a server-- 4976 usually, but not necessarily, after receiving a 401 response--does so 4977 by including an Authorization request-header field with the request. 4979 The Authorization field value consists of credentials containing the 4980 authentication information of the user agent for the realm of the 4981 resource being requested. 4983 Authorization = "Authorization" ":" credentials 4985 HTTP access authentication is described in "HTTP Authentication: 4986 Basic and Digest Access Authentication" [N10]. If a request is 4987 authenticated and a realm specified, the same credentials SHOULD be 4988 valid for all other requests within this realm (assuming that the 4989 authentication scheme itself does not require otherwise, such as 4990 credentials that vary according to a challenge value or using 4991 synchronized clocks). 4993 When a shared cache (see section 13.7) receives a request containing 4995 an Authorization field, it MUST NOT return the corresponding response 4996 as a reply to any other request, unless one of the following specific 4997 exceptions holds: 4999 1. If the response includes the "s-maxage" cache-control directive, 5000 the cache MAY use that response in replying to a subsequent 5001 request. But (if the specified maximum age has passed) a proxy 5002 cache MUST first revalidate it with the origin server, using the 5003 request-headers from the new request to allow the origin server to 5004 authenticate the new request. (This is the defined behavior for s- 5005 maxage.) If the response includes "s-maxage=0", the proxy MUST 5006 always revalidate it before re-using it. 5008 2. If the response includes the "must-revalidate" cache-control 5009 directive, the cache MAY use that response in replying to a 5010 subsequent request. But if the response is stale, all caches MUST 5011 first revalidate it with the origin server, using the request- 5012 headers from the new request to allow the origin server to 5013 authenticate the new request. 5015 3. If the response includes the "public" cache-control directive, it 5016 MAY be returned in reply to any subsequent request. 5018 14.9 Cache-Control 5020 The Cache-Control general-header field is used to specify directives 5021 that MUST be obeyed by all caching mechanisms along the 5022 request/response chain. The directives specify behavior intended to 5023 prevent caches from adversely interfering with the request or 5024 response. These directives typically override the default caching 5025 algorithms. Cache directives are unidirectional in that the presence 5026 of a directive in a request does not imply that the same directive is 5027 to be given in the response. 5029 Note that HTTP/1.0 caches might not implement Cache-Control and 5030 might only implement Pragma: no-cache (see section 14.32). 5032 Cache directives MUST be passed through by a proxy or gateway 5033 application, regardless of their significance to that application, 5034 since the directives might be applicable to all recipients along the 5035 request/response chain. It is not possible to specify a cache- 5036 directive for a specific cache. 5038 Cache-Control = "Cache-Control" ":" 1#cache-directive 5039 cache-directive = cache-request-directive 5040 | cache-response-directive 5041 cache-request-directive = 5042 "no-cache" ; Section 14.9.1 5043 | "no-store" ; Section 14.9.2 5044 | "max-age" "=" delta-seconds ; Section 14.9.3, 5045 ; Section 14.9.4 5046 | "max-stale" [ "=" delta-seconds ] ; Section 14.9.3 5047 | "min-fresh" "=" delta-seconds ; Section 14.9.3 5048 | "no-transform" ; Section 14.9.5 5049 | "only-if-cached" ; Section 14.9.4 5050 | cache-extension ; Section 14.9.6 5051 cache-response-directive = 5052 "public" ; Section 14.9.1 5053 | "private" [ "=" <"> 1#field-name <"> ] ; Section 14.9.1 5054 | "no-cache" [ "=" <"> 1#field-name <"> ]; Section 14.9.1 5055 | "no-store" ; Section 14.9.2 5056 | "no-transform" ; Section 14.9.5 5057 | "must-revalidate" ; Section 14.9.4 5058 | "proxy-revalidate" ; Section 14.9.4 5059 | "max-age" "=" delta-seconds ; Section 14.9.3 5060 | "s-maxage" "=" delta-seconds ; Section 14.9.3 5061 | cache-extension ; Section 14.9.6 5062 cache-extension = token [ "=" ( token | quoted-string ) ] 5064 When a directive appears without any 1#field-name parameter, the 5065 directive applies to the entire request or response. When such a 5066 directive appears with a 1#field-name parameter, it applies only to 5068 the named field or fields, and not to the rest of the request or 5069 response. This mechanism supports extensibility; implementations of 5070 future versions of the HTTP protocol might apply these directives to 5071 header fields not defined in HTTP/1.1. 5073 The cache-control directives can be broken down into these general 5074 categories: 5076 o Restrictions on what are cacheable; these may only be imposed by 5077 the origin server. 5079 o Restrictions on what may be stored by a cache; these may be imposed 5080 by either the origin server or the user agent. 5081 o Modifications of the basic expiration mechanism; these may be 5082 imposed by either the origin server or the user agent. 5083 o Controls over cache revalidation and reload; these may only be 5084 imposed by a user agent. 5085 o Control over transformation of entities. 5086 o Extensions to the caching system. 5088 14.9.1 What is Cacheable 5090 By default, a response is cacheable if the requirements of the 5091 request method, request header fields, and the response status 5092 indicate that it is cacheable. Section 13.4 summarizes these defaults 5093 for cacheability. The following Cache-Control response directives 5094 allow an origin server to override the default cacheability of a 5095 response: 5097 public 5098 Indicates that the response MAY be cached by any cache, even if it 5099 would normally be non-cacheable or cacheable only within a non-shared 5100 cache. (See also Authorization, section 14.8, for additional 5101 details.) 5103 private 5104 Indicates that all or part of the response message is intended for a 5105 single user and MUST NOT be cached by a shared cache. This allows an 5106 origin server to state that the specified parts of the response are 5107 intended for only one user and are not a valid response for requests 5108 by other users. A private (non-shared) cache MAY cache the response. 5110 Note: This usage of the word private only controls where the 5111 response may be cached, and cannot ensure the privacy of the 5112 message content. 5114 no-cache 5115 If the no-cache directive does not specify a field-name, then a 5116 cache MUST NOT use the response to satisfy a subsequent request 5117 without successful revalidation with the origin server. This allows 5118 an origin server to prevent caching even by caches that have been 5119 configured to return stale responses to client requests. 5121 If the no-cache directive does specify one or more field-names, then 5122 a cache MAY use the response to satisfy a subsequent request, subject 5123 to any other restrictions on caching. However, the specified field- 5124 name(s) MUST NOT be sent in the response to a subsequent request 5125 without successful revalidation with the origin server. This allows 5126 an origin server to prevent the re-use of certain header fields in a 5127 response, while still allowing caching of the rest of the response. 5129 Note: Most HTTP/1.0 caches will not recognize or obey this 5130 directive. 5132 14.9.2 What May be Stored by Caches 5134 no-store 5135 The purpose of the no-store directive is to prevent the inadvertent 5136 release or retention of sensitive information (for example, on backup 5137 tapes). The no-store directive applies to the entire message, and MAY 5138 be sent either in a response or in a request. If sent in a request, a 5139 cache MUST NOT store any part of either this request or any response 5140 to it. If sent in a response, a cache MUST NOT store any part of 5141 either this response or the request that elicited it. This directive 5142 applies to both non-shared and shared caches. "MUST NOT store" in 5143 this context means that the cache MUST NOT intentionally store the 5144 information in non-volatile storage, and MUST make a best-effort 5145 attempt to remove the information from volatile storage as promptly 5146 as possible after forwarding it. 5148 Even when this directive is associated with a response, users might 5149 explicitly store such a response outside of the caching system (e.g., 5150 with a "Save As" dialog). History buffers MAY store such responses as 5151 part of their normal operation. 5153 The purpose of this directive is to meet the stated requirements of 5154 certain users and service authors who are concerned about accidental 5155 releases of information via unanticipated accesses to cache data 5156 structures. While the use of this directive might improve privacy in 5157 some cases, we caution that it is NOT in any way a reliable or 5158 sufficient mechanism for ensuring privacy. In particular, malicious 5159 or compromised caches might not recognize or obey this directive, and 5160 communications networks might be vulnerable to eavesdropping. 5162 14.9.3 Modifications of the Basic Expiration Mechanism 5164 The expiration time of an entity MAY be specified by the origin 5165 server using the Expires header (see section 14.21). Alternatively, 5166 it MAY be specified using the max-age directive in a response. When 5167 the max-age cache-control directive is present in a cached response, 5168 the response is stale if its current age is greater than the age 5169 value given (in seconds) at the time of a new request for that 5170 resource. The max-age directive on a response implies that the 5171 response is cacheable (i.e., "public") unless some other, more 5172 restrictive cache directive is also present. 5174 If a response includes both an Expires header and a max-age 5175 directive, the max-age directive overrides the Expires header, even 5176 if the Expires header is more restrictive. This rule allows an origin 5177 server to provide, for a given response, a longer expiration time to 5178 an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This might be 5179 useful if certain HTTP/1.0 caches improperly calculate ages or 5180 expiration times, perhaps due to desynchronized clocks. 5182 Many HTTP/1.0 cache implementations will treat an Expires value that 5183 is less than or equal to the response Date value as being equivalent 5184 to the Cache-Control response directive "no-cache". If an HTTP/1.1 5185 cache receives such a response, and the response does not include a 5186 Cache-Control header field, it SHOULD consider the response to be 5187 non-cacheable in order to retain compatibility with HTTP/1.0 servers. 5189 Note: An origin server might wish to use a relatively new HTTP 5190 cache control feature, such as the "private" directive, on a 5191 network including older caches that do not understand that feature. 5193 The origin server will need to combine the new feature with an 5194 Expires field whose value is less than or equal to the Date value. 5195 This will prevent older caches from improperly caching the 5196 response. 5198 s-maxage 5199 If a response includes an s-maxage directive, then for a shared cache 5200 (but not for a private cache), the maximum age specified by this 5201 directive overrides the maximum age specified by either the max-age 5202 directive or the Expires header. The s-maxage directive also implies 5203 the semantics of the proxy-revalidate directive (see section 14.9.4), 5204 i.e., that the shared cache must not use the entry after it becomes 5205 stale to respond to a subsequent request without first revalidating 5206 it with the origin server. The s-maxage directive is always ignored 5207 by a private cache. 5209 Note that most older caches, not compliant with this specification, 5210 do not implement any cache-control directives. An origin server 5211 wishing to use a cache-control directive that restricts, but does not 5212 prevent, caching by an HTTP/1.1-compliant cache MAY exploit the 5213 requirement that the max-age directive overrides the Expires header, 5214 and the fact that pre-HTTP/1.1-compliant caches do not observe the 5215 max-age directive. 5217 Other directives allow a user agent to modify the basic expiration 5218 mechanism. These directives MAY be specified on a request: 5220 max-age 5221 Indicates that the client is willing to accept a response whose age 5222 is no greater than the specified time in seconds. Unless max-stale 5223 directive is also included, the client is not willing to accept a 5224 stale response. 5226 min-fresh 5227 Indicates that the client is willing to accept a response whose 5228 freshness lifetime is no less than its current age plus the specified 5229 time in seconds. That is, the client wants a response that will still 5230 be fresh for at least the specified number of seconds. 5232 max-stale 5233 Indicates that the client is willing to accept a response that has 5234 exceeded its expiration time. If max-stale is assigned a value, then 5235 the client is willing to accept a response that has exceeded its 5236 expiration time by no more than the specified number of seconds. If 5237 no value is assigned to max-stale, then the client is willing to 5238 accept a stale response of any age. 5240 If a cache returns a stale response, either because of a max-stale 5241 directive on a request, or because the cache is configured to 5242 override the expiration time of a response, the cache MUST attach a 5243 Warning header to the stale response, using Warning 110 (Response is 5244 stale). 5246 A cache MAY be configured to return stale responses without 5247 validation, but only if this does not conflict with any "MUST" -level 5248 requirements concerning cache validation (e.g., a "must-revalidate" 5249 cache-control directive). 5251 If both the new request and the cached entry include "max-age" 5252 directives, then the lesser of the two values is used for determining 5253 the freshness of the cached entry for that request. 5255 14.9.4 Cache Revalidation and Reload Controls 5257 Sometimes a user agent might want or need to insist that a cache 5258 revalidate its cache entry with the origin server (and not just with 5259 the next cache along the path to the origin server), or to reload its 5260 cache entry from the origin server. End-to-end revalidation might be 5261 necessary if either the cache or the origin server has overestimated 5262 the expiration time of the cached response. End-to-end reload may be 5263 necessary if the cache entry has become corrupted for some reason. 5265 End-to-end revalidation may be requested either when the client does 5266 not have its own local cached copy, in which case we call it 5267 "unspecified end-to-end revalidation", or when the client does have a 5268 local cached copy, in which case we call it "specific end-to-end 5269 revalidation." 5271 The client can specify these three kinds of action using Cache- 5272 Control request directives: 5274 End-to-end reload 5275 The request includes a "no-cache" cache-control directive or, for 5276 compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field names 5277 MUST NOT be included with the no-cache directive in a request. The 5278 server MUST NOT use a cached copy when responding to such a request. 5280 Specific end-to-end revalidation 5281 The request includes a "max-age=0" cache-control directive, which 5282 forces each cache along the path to the origin server to revalidate 5283 its own entry, if any, with the next cache or server. The initial 5284 request includes a cache-validating conditional with the client�s 5285 current validator. 5287 Unspecified end-to-end revalidation 5288 The request includes "max-age=0" cache-control directive, which 5289 forces each cache along the path to the origin server to revalidate 5290 its own entry, if any, with the next cache or server. The initial 5291 request does not include a cache-validating conditional; the first 5292 cache along the path (if any) that holds a cache entry for this 5293 resource includes a cache-validating conditional with its current 5294 validator. 5296 max-age 5297 When an intermediate cache is forced, by means of a max-age=0 5298 directive, to revalidate its own cache entry, and the client has 5299 supplied its own validator in the request, the supplied validator 5300 might differ from the validator currently stored with the cache 5301 entry. In this case, the cache MAY use either validator in making its 5302 own request without affecting semantic transparency. 5304 However, the choice of validator might affect performance. The best 5305 approach is for the intermediate cache to use its own validator when 5306 making its request. If the server replies with 304 (Not Modified), 5307 then the cache can return its now validated copy to the client with a 5308 200 (OK) response. If the server replies with a new entity and cache 5309 validator, however, the intermediate cache can compare the returned 5310 validator with the one provided in the client�s request, using the 5311 strong comparison function. If the client�s validator is equal to the 5312 origin server�s, then the intermediate cache simply returns 304 (Not 5313 Modified). Otherwise, it returns the new entity with a 200 (OK) 5314 response. 5316 If a request includes the no-cache directive, it SHOULD NOT include 5317 min-fresh, max-stale, or max-age. 5319 only-if-cached 5320 In some cases, such as times of extremely poor network connectivity, 5321 a client may want a cache to return only those responses that it 5322 currently has stored, and not to reload or revalidate with the origin 5323 server. To do this, the client may include the only-if-cached 5324 directive in a request. If it receives this directive, a cache SHOULD 5325 either respond using a cached entry that is consistent with the other 5326 constraints of the request, or respond with a 504 (Gateway Timeout) 5327 status. However, if a group of caches is being operated as a unified 5328 system with good internal connectivity, such a request MAY be 5329 forwarded within that group of caches. 5331 must-revalidate 5332 Because a cache MAY be configured to ignore a server�s specified 5333 expiration time, and because a client request MAY include a max-stale 5334 directive (which has a similar effect), the protocol also includes a 5335 mechanism for the origin server to require revalidation of a cache 5336 entry on any subsequent use. When the must-revalidate directive is 5337 present in a response received by a cache, that cache MUST NOT use 5338 the entry after it becomes stale to respond to a subsequent request 5339 without first revalidating it with the origin server. (I.e., the 5340 cache MUST do an end-to-end revalidation every time, if, based solely 5341 on the origin server�s Expires or max-age value, the cached response 5342 is stale.) 5344 The must-revalidate directive is necessary to support reliable 5345 operation for certain protocol features. In all circumstances an 5346 HTTP/1.1 cache MUST obey the must-revalidate directive; in 5347 particular, if the cache cannot reach the origin server for any 5348 reason, it MUST generate a 504 (Gateway Timeout) response. 5350 Servers SHOULD send the must-revalidate directive if and only if 5351 failure to revalidate a request on the entity could result in 5352 incorrect operation, such as a silently unexecuted financial 5353 transaction. Recipients MUST NOT take any automated action that 5354 violates this directive, and MUST NOT automatically provide an 5355 unvalidated copy of the entity if revalidation fails. 5357 Although this is not recommended, user agents operating under severe 5358 connectivity constraints MAY violate this directive but, if so, MUST 5359 explicitly warn the user that an unvalidated response has been 5360 provided. The warning MUST be provided on each unvalidated access, 5361 and SHOULD require explicit user confirmation. 5363 proxy-revalidate 5364 The proxy-revalidate directive has the same meaning as the must- 5365 revalidate directive, except that it does not apply to non-shared 5366 user agent caches. It can be used on a response to an authenticated 5367 request to permit the user�s cache to store and later return the 5368 response without needing to revalidate it (since it has already been 5369 authenticated once by that user), while still requiring proxies that 5370 service many users to revalidate each time (in order to make sure 5371 that each user has been authenticated). Note that such authenticated 5372 responses also need the public cache control directive in order to 5373 allow them to be cached at all. 5375 14.9.5 No-Transform Directive 5377 no-transform 5378 Implementors of intermediate caches (proxies) have found it useful to 5379 convert the media type of certain entity bodies. A non-transparent 5380 proxy might, for example, convert between image formats in order to 5381 save cache space or to reduce the amount of traffic on a slow link. 5383 Serious operational problems occur, however, when these 5384 transformations are applied to entity bodies intended for certain 5385 kinds of applications. For example, applications for medical imaging, 5386 scientific data analysis and those using end-to-end authentication, 5387 all depend on receiving an entity body that is bit for bit identical 5388 to the original entity-body. 5390 Therefore, if a message includes the no-transform directive, an 5391 intermediate cache or proxy MUST NOT change those headers that are 5392 listed in section 13.5.2 as being subject to the no-transform 5393 directive. This implies that the cache or proxy MUST NOT change any 5394 aspect of the entity-body that is specified by these headers, 5395 including the value of the entity-body itself. 5397 14.9.6 Cache Control Extensions 5399 The Cache-Control header field can be extended through the use of one 5400 or more cache-extension tokens, each with an optional assigned value. 5401 Informational extensions (those which do not require a change in 5402 cache behavior) MAY be added without changing the semantics of other 5403 directives. Behavioral extensions are designed to work by acting as 5404 modifiers to the existing base of cache directives. Both the new 5405 directive and the standard directive are supplied, such that 5406 applications which do not understand the new directive will default 5407 to the behavior specified by the standard directive, and those that 5408 understand the new directive will recognize it as modifying the 5409 requirements associated with the standard directive. In this way, 5410 extensions to the cache-control directives can be made without 5411 requiring changes to the base protocol. 5413 This extension mechanism depends on an HTTP cache obeying all of the 5414 cache-control directives defined for its native HTTP-version, obeying 5415 certain extensions, and ignoring all directives that it does not 5416 understand. 5418 For example, consider a hypothetical new response directive called 5419 community which acts as a modifier to the private directive. We 5420 define this new directive to mean that, in addition to any non-shared 5421 cache, any cache which is shared only by members of the community 5422 named within its value may cache the response. An origin server 5423 wishing to allow the UCI community to use an otherwise private 5424 response in their shared cache(s) could do so by including 5426 Cache-Control: private, community="UCI" 5428 A cache seeing this header field will act correctly even if the cache 5429 does not understand the community cache-extension, since it will also 5430 see and understand the private directive and thus default to the safe 5431 behavior. 5433 Unrecognized cache-directives MUST be ignored; it is assumed that any 5434 cache-directive likely to be unrecognized by an HTTP/1.1 cache will 5435 be combined with standard directives (or the response�s default 5436 cacheability) such that the cache behavior will remain minimally 5437 correct even if the cache does not understand the extension(s). 5439 14.10 Connection 5441 The Connection general-header field allows the sender to specify 5442 options that are desired for that particular connection and MUST NOT 5443 be communicated by proxies over further connections. 5445 The Connection header has the following grammar: 5447 Connection = "Connection" ":" 1#(connection-token) 5448 connection-token = token 5449 HTTP/1.1 proxies MUST parse the Connection header field before a 5450 message is forwarded and, for each connection-token in this field, 5451 remove any header field(s) from the message with the same name as the 5452 connection-token. Connection options are signaled by the presence of 5453 a connection-token in the Connection header field, not by any 5454 corresponding additional header field(s), since the additional header 5455 field may not be sent if there are no parameters associated with that 5456 connection option. 5458 Message headers listed in the Connection header MUST NOT include end- 5459 to-end headers, such as Cache-Control. 5461 HTTP/1.1 defines the "close" connection option for the sender to 5462 signal that the connection will be closed after completion of the 5463 response. For example, 5465 Connection: close 5467 in either the request or the response header fields indicates that 5468 the connection SHOULD NOT be considered �persistent� (section 8.1) 5469 after the current request/response is complete. 5471 HTTP/1.1 applications that do not support persistent connections MUST 5472 include the "close" connection option in every request message. 5474 An HTTP/1.1 server that does not support persistent connections MUST 5475 include the "close" connection option in every response message that 5476 does not have a 1xx (informational) status code. 5478 A system receiving an HTTP/1.0 (or lower-version) message that 5479 includes a Connection header MUST, for each connection-token in this 5480 field, remove and ignore any header field(s) from the message with 5482 the same name as the connection-token. This protects against mistaken 5483 forwarding of such header fields by pre-HTTP/1.1 proxies. See section 5484 17.6.2. 5486 14.11 Content-Encoding 5488 The Content-Encoding entity-header field is used as a modifier to the 5489 media-type. When present, its value indicates what additional content 5490 codings have been applied to the entity-body, and thus what decoding 5492 mechanisms must be applied in order to obtain the media-type 5493 referenced by the Content-Type header field. Content-Encoding is 5494 primarily used to allow a document to be compressed without losing 5495 the identity of its underlying media type. 5497 Content-Encoding = "Content-Encoding" ":" 1#content-coding 5499 Content codings are defined in section 3.5. An example of its use is 5501 Content-Encoding: gzip 5503 The content-coding is a characteristic of the entity identified by 5504 the Request-URI. Typically, the entity-body is stored with this 5505 encoding and is only decoded before rendering or analogous usage. 5506 However, a non-transparent proxy MAY modify the content-coding if the 5507 new coding is known to be acceptable to the recipient, unless the 5508 "no-transform" cache-control directive is present in the message. 5510 If the content-coding of an entity is not "identity", then the 5511 response MUST include a Content-Encoding entity-header (section 5512 14.11) that lists the non-identity content-coding(s) used. 5514 If the content-coding of an entity in a request message is not 5515 acceptable to the origin server, the server SHOULD respond with a 5516 status code of 415 (Unsupported Media Type). 5518 If multiple encodings have been applied to an entity, the content 5519 codings MUST be listed in the order in which they were applied. 5520 Additional information about the encoding parameters MAY be provided 5521 by other entity-header fields not defined by this specification. 5523 14.12 Content-Language 5525 The Content-Language entity-header field describes the natural 5526 language(s) of the intended audience for the enclosed entity. Note 5527 that this might not be equivalent to all the languages used within 5528 the entity-body. 5530 Content-Language = "Content-Language" ":" 1#language-tag 5532 Language tags are defined in section 3.10. The primary purpose of 5533 Content-Language is to allow a user to identify and differentiate 5534 entities according to the user's own preferred language. Thus, if the 5535 body content is intended only for a Danish-literate audience, the 5536 appropriate field is 5538 Content-Language: da 5540 If no Content-Language is specified, the default is that the content 5541 is intended for all language audiences. This might mean that the 5542 sender does not consider it to be specific to any natural language, 5543 or that the sender does not know for which language it is intended. 5545 Multiple languages MAY be listed for content that is intended for 5546 multiple audiences. For example, a rendition of the "Treaty of 5547 Waitangi," presented simultaneously in the original Maori and English 5548 versions, would call for 5550 Content-Language: mi, en 5552 However, just because multiple languages are present within an entity 5553 does not mean that it is intended for multiple linguistic audiences. 5554 An example would be a beginner's language primer, such as "A First 5555 Lesson in Latin," which is clearly intended to be used by an English- 5556 literate audience. In this case, the Content-Language would properly 5557 only include "en". 5559 Content-Language MAY be applied to any media type -- it is not 5560 limited to textual documents. 5562 14.13 Content-Length 5564 The Content-Length entity-header field indicates the size of the 5565 entity-body, in decimal number of OCTETs, sent to the recipient or, 5566 in the case of the HEAD method, the size of the entity-body that 5567 would have been sent had the request been a GET. 5569 Content-Length = "Content-Length" ":" 1*DIGIT 5571 An example is 5573 Content-Length: 3495 5575 Applications SHOULD use this field to indicate the transfer-length of 5576 the message-body, unless this is prohibited by the rules in section 5577 4.4. 5579 Any Content-Length greater than or equal to zero is a valid value. 5580 Section 4.4 describes how to determine the length of a message-body 5581 if a Content-Length is not given. 5583 Note that the meaning of this field is significantly different from 5584 the corresponding definition in MIME, where it is an optional field 5585 used within the "message/external-body" content-type. In HTTP, it 5586 SHOULD be sent whenever the message;s length can be determined prior 5587 to being transferred, unless this is prohibited by the rules in 5588 section 4.4. 5590 14.14 Content-Location 5592 The Content-Location entity-header field MAY be used to supply the 5593 resource location for the entity enclosed in the message when that 5594 entity is accessible from a location separate from the requested 5595 resource's URI. A server SHOULD provide a Content-Location for the 5596 variant corresponding to the response entity; especially in the case 5597 where a resource has multiple entities associated with it, and those 5598 entities actually have separate locations by which they might be 5599 individually accessed, the server SHOULD provide a Content-Location 5600 for the particular variant which is returned. 5602 Content-Location = "Content-Location" ":" 5603 ( absoluteURI | relativeURI ) 5605 The value of Content-Location also defines the base URI for the 5606 entity. 5608 The Content-Location value is not a replacement for the original 5609 requested URI; it is only a statement of the location of the resource 5610 corresponding to this particular entity at the time of the request. 5612 Future requests MAY specify the Content-Location URI as the request- 5613 URI if the desire is to identify the source of that particular 5614 entity. 5616 A cache cannot assume that an entity with a Content-Location 5617 different from the URI used to retrieve it can be used to respond to 5619 later requests on that Content-Location URI. However, the Content- 5620 Location can be used to differentiate between multiple entities 5621 retrieved from a single requested resource, as described in section 5622 13.6. 5624 If the Content-Location is a relative URI, the relative URI is 5625 interpreted relative to the Request-URI. 5627 The meaning of the Content-Location header in PUT or POST requests is 5628 undefined; servers are free to ignore it in those cases. 5630 14.15 Content-MD5 5632 The Content-MD5 entity-header field, as defined in RFC 1864 [I16], is 5633 an MD5 digest of the entity-body for the purpose of providing an end- 5634 to-end message integrity check (MIC) of the entity-body. (Note: a MIC 5635 is good for detecting accidental modification of the entity-body in 5636 transit, but is not proof against malicious attacks.) 5638 Content-MD5 = "Content-MD5" ":" md5-digest 5639 md5-digest = 5641 The Content-MD5 header field MAY be generated by an origin server or 5642 client to function as an integrity check of the entity-body. Only 5643 origin servers or clients MAY generate the Content-MD5 header field; 5644 proxies and gateways MUST NOT generate it, as this would defeat its 5645 value as an end-to-end integrity check. Any recipient of the entity- 5646 body, including gateways and proxies, MAY check that the digest value 5647 in this header field matches that of the entity-body as received. 5649 The MD5 digest is computed based on the content of the entity-body, 5650 including any content-coding that has been applied, but not including 5651 any transfer-encoding applied to the message-body. If the message is 5652 received with a transfer-encoding, that encoding MUST be removed 5653 prior to checking the Content-MD5 value against the received entity. 5655 This has the result that the digest is computed on the octets of the 5656 entity-body exactly as, and in the order that, they would be sent if 5657 no transfer-encoding were being applied. 5659 HTTP extends RFC 1864 to permit the digest to be computed for MIME 5661 composite media-types (e.g., multipart/* and message/rfc822), but 5662 this does not change how the digest is computed as defined in the 5663 preceding paragraph. 5665 There are several consequences of this. The entity-body for composite 5666 types MAY contain many body-parts, each with its own MIME and HTTP 5667 headers (including Content-MD5, Content-Transfer-Encoding, and 5668 Content-Encoding headers). If a body-part has a Content-Transfer- 5669 Encoding or Content-Encoding header, it is assumed that the content 5670 of the body-part has had the encoding applied, and the body-part is 5671 included in the Content-MD5 digest as is -- i.e., after the 5672 application. The Transfer-Encoding header field is not allowed within 5673 body-parts. 5675 Conversion of all line breaks to CRLF MUST NOT be done before 5676 computing or checking the digest: the line break convention used in 5677 the text actually transmitted MUST be left unaltered when computing 5678 the digest. 5680 Note: while the definition of Content-MD5 is exactly the same for 5681 HTTP as in RFC 1864 for MIME entity-bodies, there are several ways 5682 in which the application of Content-MD5 to HTTP entity-bodies 5683 differs from its application to MIME entity-bodies. One is that 5684 HTTP, unlike MIME, does not use Content-Transfer-Encoding, and does 5685 use Transfer-Encoding and Content-Encoding. Another is that HTTP 5686 more frequently uses binary content types than MIME, so it is worth 5687 noting that, in such cases, the byte order used to compute the 5688 digest is the transmission byte order defined for the type. Lastly, 5690 HTTP allows transmission of text types with any of several line 5691 break conventions and not just the canonical form using CRLF. 5693 14.16 Content-Range 5695 The Content-Range entity-header is sent with a partial entity-body to 5696 specify where in the full entity-body the partial body should be 5697 applied. Range units are defined in section 3.12. 5699 Content-Range = "Content-Range" ":" content-range-spec 5700 content-range-spec = byte-content-range-spec 5701 byte-content-range-spec = bytes-unit SP 5702 byte-range-resp-spec "/" 5703 ( instance-length | "*" ) 5705 byte-range-resp-spec = (first-byte-pos "-" last-byte-pos) 5707 | "*" 5708 instance-length = 1*DIGIT 5710 The header SHOULD indicate the total length of the full entity-body, 5711 unless this length is unknown or difficult to determine. The asterisk 5712 "*" character means that the instance-length is unknown at the time 5713 when the response was generated. 5715 Unlike byte-ranges-specifier values (see section 14.35.1), a byte- 5716 range-resp-spec MUST only specify one range, and MUST contain 5717 absolute byte positions for both the first and last byte of the 5718 range. 5720 A byte-content-range-spec with a byte-range-resp-spec whose last- 5721 byte-pos value is less than its first-byte-pos value, or whose 5722 instance-length value is less than or equal to its last-byte-pos 5723 value, is invalid. The recipient of an invalid byte-content-range- 5724 spec MUST ignore it and any content transferred along with it. 5726 A server sending a response with status code 416 (Requested range not 5727 satisfiable) SHOULD include a Content-Range field with a byte-range- 5728 resp-spec of "*". The instance-length specifies the current length of 5729 the selected resource. A response with status code 206 (Partial 5730 Content) MUST NOT include a Content-Range field with a byte-range- 5731 resp-spec of "*". 5733 Examples of byte-content-range-spec values, assuming that the entity 5734 contains a total of 1234 bytes: 5736 o The first 500 bytes: 5737 bytes 0-499/1234 5738 o The second 500 bytes: 5739 bytes 500-999/1234 5740 o All except for the first 500 bytes: 5741 bytes 500-1233/1234 5742 o The last 500 bytes: 5743 bytes 734-1233/1234 5745 When an HTTP message includes the content of a single range (for 5746 example, a response to a request for a single range, or to a request 5747 for a set of ranges that overlap without any holes), this content is 5748 transmitted with a Content-Range header, and a Content-Length header 5749 showing the number of bytes actually transferred. For example, 5751 HTTP/1.1 206 Partial content 5752 Date: Wed, 15 Nov 1995 06:25:24 GMT 5753 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 5754 Content-Range: bytes 21010-47021/47022 5755 Content-Length: 26012 5756 Content-Type: image/gif 5758 When an HTTP message includes the content of multiple ranges (for 5759 example, a response to a request for multiple non-overlapping 5760 ranges), these are transmitted as a multipart message. The multipart 5761 media type used for this purpose is "multipart/byteranges" as defined 5762 in appendix 17.2. See appendix 17.6.3 for a compatibility issue. 5764 A response to a request for a single range MUST NOT be sent using the 5765 multipart/byteranges media type. A response to a request for 5766 multiple ranges, whose result is a single range, MAY be sent as a 5767 multipart/byteranges media type with one part. A client that cannot 5768 decode a multipart/byteranges message MUST NOT ask for multiple byte- 5769 ranges in a single request. 5771 When a client requests multiple byte-ranges in one request, the 5772 server SHOULD return them in the order that they appeared in the 5773 request. 5775 If the server ignores a byte-range-spec because it is syntactically 5776 invalid, the server SHOULD treat the request as if the invalid Range 5777 header field did not exist. (Normally, this means return a 200 5778 response containing the full entity). 5780 If the server receives a request (other than one including an If- 5781 Range request-header field) with an unsatisfiable Range request- 5782 header field (that is, all of whose byte-range-spec values have a 5783 first-byte-pos value greater than the current length of the selected 5784 resource), it SHOULD return a response code of 416 (Requested range 5785 not satisfiable) (section 10.4.17). 5787 Note: clients cannot depend on servers to send a 416 (Requested 5788 range not satisfiable) response instead of a 200 (OK) response for 5789 an unsatisfiable Range request-header, since not all servers 5790 implement this request-header. 5792 14.17 Content-Type 5794 The Content-Type entity-header field indicates the media type of the 5795 entity-body sent to the recipient or, in the case of the HEAD method, 5796 the media type that would have been sent had the request been a GET. 5798 Content-Type = "Content-Type" ":" media-type 5800 Media types are defined in section 3.7. An example of the field is 5802 Content-Type: text/html; charset=ISO-8859-4 5804 Further discussion of methods for identifying the media type of an 5805 entity is provided in section 7.2.1. 5807 14.18 Date 5809 The Date general-header field represents the date and time at which 5810 the message was originated, having the same semantics as orig-date in 5811 RFC 822. The field value is an HTTP-date, as described in section 5812 3.3.1; it MUST be sent in RFC 1123 [N2]-date format. 5814 Date = "Date" ":" HTTP-date 5816 An example is 5818 Date: Tue, 15 Nov 1994 08:12:31 GMT 5820 Origin servers MUST include a Date header field in all responses, 5821 except in these cases: 5823 1. If the response status code is 100 (Continue) or 101 (Switching 5824 Protocols), the response MAY include a Date header field, at the 5825 server's option. 5827 2. If the response status code conveys a server error, e.g. 500 5828 (Internal Server Error) or 503 (Service Unavailable), and it is 5829 inconvenient or impossible to generate a valid Date. 5831 3. If the server does not have a clock that can provide a reasonable 5832 approximation of the current time, its responses MUST NOT include a 5833 Date header field. In this case, the rules in section 14.18.1 MUST 5834 be followed. 5836 A received message that does not have a Date header field MUST be 5837 assigned one by the recipient if the message will be cached by that 5838 recipient or gatewayed via a protocol which requires a Date. An HTTP 5839 implementation without a clock MUST NOT cache responses without 5840 revalidating them on every use. An HTTP cache, especially a shared 5841 cache, SHOULD use a mechanism, such as NTP [I21], to synchronize its 5842 clock with a reliable external standard. 5844 Clients SHOULD only send a Date header field in messages that include 5845 an entity-body, as in the case of the PUT and POST requests, and even 5846 then it is optional. A client without a clock MUST NOT send a Date 5847 header field in a request. 5849 The HTTP-date sent in a Date header SHOULD NOT represent a date and 5850 time subsequent to the generation of the message. It SHOULD represent 5851 the best available approximation of the date and time of message 5852 generation, unless the implementation has no means of generating a 5853 reasonably accurate date and time. In theory, the date ought to 5854 represent the moment just before the entity is generated. In 5855 practice, the date can be generated at any time during the message 5856 origination without affecting its semantic value. 5858 14.18.1 Clockless Origin Server Operation 5860 Some origin server implementations might not have a clock available. 5861 An origin server without a clock MUST NOT assign Expires or Last- 5862 Modified values to a response, unless these values were associated 5863 with the resource by a system or user with a reliable clock. It MAY 5864 assign an Expires value that is known, at or before server 5865 configuration time, to be in the past (this allows "pre-expiration" 5866 of responses without storing separate Expires values for each 5867 resource). 5869 14.19 ETag 5871 The ETag response-header field provides the current value of the 5872 entity tag for the requested variant. The headers used with entity 5873 tags are described in sections 14.24, 14.26 and 14.44. The entity tag 5874 MAY be used for comparison with other entities from the same resource 5875 (see section 13.3.3). 5877 ETag = "ETag" ":" entity-tag 5879 Examples: 5881 ETag: "xyzzy" 5882 ETag: W/"xyzzy" 5883 ETag: "" 5884 14.20 Expect 5886 The Expect request-header field is used to indicate that particular 5887 server behaviors are required by the client. 5889 Expect = "Expect" ":" 1#expectation 5890 expectation = "100-continue" | expectation-extension 5891 expectation-extension = token [ "=" ( token | quoted-string ) 5892 *expect-params ] 5893 expect-params = ";" token [ "=" ( token | quoted-string ) ] 5895 A server that does not understand or is unable to comply with any of 5896 the expectation values in the Expect field of a request MUST respond 5897 with appropriate error status. The server MUST respond with a 417 5898 (Expectation Failed) status if any of the expectations cannot be met 5899 or, if there are other problems with the request, some other 4xx 5900 status. 5902 This header field is defined with extensible syntax to allow for 5903 future extensions. If a server receives a request containing an 5904 Expect field that includes an expectation-extension that it does not 5905 support, it MUST respond with a 417 (Expectation Failed) status. 5907 Comparison of expectation values is case-insensitive for unquoted 5908 tokens (including the 100-continue token), and is case-sensitive for 5909 quoted-string expectation-extensions. 5911 The Expect mechanism is hop-by-hop: that is, an HTTP/1.1 proxy MUST 5912 return a 417 (Expectation Failed) status if it receives a request 5913 with an expectation that it cannot meet. However, the Expect request- 5914 header itself is end-to-end; it MUST be forwarded if the request is 5915 forwarded. 5917 Many older HTTP/1.0 and HTTP/1.1 applications do not understand the 5918 Expect header. 5920 See section 8.2.3 for the use of the 100 (continue) status. 5922 14.21 Expires 5924 The Expires entity-header field gives the date/time after which the 5925 response is considered stale. A stale cache entry may not normally be 5926 returned by a cache (either a proxy cache or a user agent cache) 5927 unless it is first validated with the origin server (or with an 5928 intermediate cache that has a fresh copy of the entity). See section 5929 13.2 for further discussion of the expiration model. 5931 The presence of an Expires field does not imply that the original 5932 resource will change or cease to exist at, before, or after that 5933 time. 5935 The format is an absolute date and time as defined by HTTP-date in 5936 section 3.3.1; it MUST be in RFC 1123 date format: 5938 Expires = "Expires" ":" HTTP-date 5940 An example of its use is 5942 Expires: Thu, 01 Dec 1994 16:00:00 GMT 5944 Note: if a response includes a Cache-Control field with the max-age 5945 directive (see section 14.9.3), that directive overrides the 5946 Expires field. 5948 HTTP/1.1 clients and caches MUST treat other invalid date formats, 5949 especially including the value "0", as in the past (i.e., "already 5950 expired"). 5952 To mark a response as "already expired," an origin server sends an 5953 Expires date that is equal to the Date header value. (See the rules 5954 for expiration calculations in section 13.2.4.) 5956 To mark a response as "never expires," an origin server sends an 5957 Expires date approximately one year from the time the response is 5958 sent. HTTP/1.1 servers SHOULD NOT send Expires dates more than one 5959 year in the future. 5961 The presence of an Expires header field with a date value of some 5962 time in the future on a response that otherwise would by default be 5963 non-cacheable indicates that the response is cacheable, unless 5964 indicated otherwise by a Cache-Control header field (section 14.9). 5966 14.22 From 5968 The From request-header field, if given, SHOULD contain an Internet 5969 e-mail address for the human user who controls the requesting user 5970 agent. The address SHOULD be machine-usable, as defined by "mailbox" 5971 in RFC 822 [N3] as updated by RFC 1123 [N2]: 5973 From = "From" ":" mailbox 5975 An example is: 5977 From: webmaster@w3.org 5979 This header field MAY be used for logging purposes and as a means for 5980 identifying the source of invalid or unwanted requests. It SHOULD NOT 5981 be used as an insecure form of access protection. The interpretation 5983 of this field is that the request is being performed on behalf of the 5984 person given, who accepts responsibility for the method performed. In 5985 particular, robot agents SHOULD include this header so that the 5986 person responsible for running the robot can be contacted if problems 5987 occur on the receiving end. 5989 The Internet e-mail address in this field MAY be separate from the 5990 Internet host which issued the request. For example, when a request 5991 is passed through a proxy the original issuer�s address SHOULD be 5992 used. 5994 The client SHOULD NOT send the From header field without the user�s 5995 approval, as it might conflict with the user's privacy interests or 5996 their site's security policy. It is strongly recommended that the 5997 user be able to disable, enable, and modify the value of this field 5998 at any time prior to a request. 6000 14.23 Host 6002 The Host request-header field specifies the Internet host and port 6003 number of the resource being requested, as obtained from the original 6004 URI given by the user or referring resource (generally an HTTP URL, 6005 as described in section 3.2.2). The Host field value MUST represent 6006 the naming authority of the origin server or gateway given by the 6007 original URL. This allows the origin server or gateway to 6008 differentiate between internally-ambiguous URLs, such as the root "/" 6009 URL of a server for multiple host names on a single IP address. 6011 Host = "Host" ":" host [ ":" port ] ; Section 3.2.2 6013 A "host" without any trailing port information implies the default 6014 port for the service requested (e.g., "80" for an HTTP URL). For 6015 example, a request on the origin server for 6016 would properly include: 6018 GET /pub/WWW/ HTTP/1.1 6019 Host: www.w3.org 6021 A client MUST include a Host header field in all HTTP/1.1 request 6022 messages . If the requested URI does not include an Internet host 6023 name for the service being requested, then the Host header field MUST 6024 be given with an empty value. An HTTP/1.1 proxy MUST ensure that any 6025 request message it forwards does contain an appropriate Host header 6026 field that identifies the service being requested by the proxy. All 6027 Internet-based HTTP/1.1 servers MUST respond with a 400 (Bad Request) 6028 status code to any HTTP/1.1 request message which lacks a Host header 6029 field. 6031 See sections 5.2 and 17.6.1.1 for other requirements relating to 6032 Host. 6034 14.24 If-Match 6036 The If-Match request-header field is used with a method to make it 6037 conditional. A client that has one or more entities previously 6038 obtained from the resource can verify that one of those entities is 6039 current by including a list of their associated entity tags in the 6040 If-Match header field. Entity tags are defined in section 3.11. The 6041 purpose of this feature is to allow efficient updates of cached 6042 information with a minimum amount of transaction overhead. It is also 6043 used, on updating requests, to prevent inadvertent modification of 6044 the wrong version of a resource. As a special case, the value "*" 6045 matches any current entity of the resource. 6047 If-Match = "If-Match" ":" ( "*" | 1#entity-tag ) 6048 If any of the entity tags match the entity tag of the entity that 6049 would have been returned in the response to a similar GET request 6050 (without the If-Match header) on that resource, or if "*" is given 6051 and any current entity exists for that resource, then the server MAY 6052 perform the requested method as if the If-Match header field did not 6053 exist. 6055 A server MUST use the strong comparison function (see section 13.3.3) 6056 to compare the entity tags in If-Match. 6058 If none of the entity tags match, or if "*" is given and no current 6059 entity exists, the server MUST NOT perform the requested method, and 6060 MUST return a 412 (Precondition Failed) response. This behavior is 6061 most useful when the client wants to prevent an updating method, such 6062 as PUT, from modifying a resource that has changed since the client 6063 last retrieved it. 6065 If the request would, without the If-Match header field, result in 6066 anything other than a 2xx or 412 status, then the If-Match header 6067 MUST be ignored. 6069 The meaning of "If-Match: *" is that the method SHOULD be performed 6070 if the representation selected by the origin server (or by a cache, 6071 possibly using the Vary mechanism, see section 14.44) exists, and 6072 MUST NOT be performed if the representation does not exist. 6074 A request intended to update a resource (e.g., a PUT) MAY include an 6075 If-Match header field to signal that the request method MUST NOT be 6076 applied if the entity corresponding to the If-Match value (a single 6077 entity tag) is no longer a representation of that resource. This 6078 allows the user to indicate that they do not wish the request to be 6079 successful if the resource has been changed without their knowledge. 6081 Examples: 6083 If-Match: "xyzzy" 6084 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 6085 If-Match: * 6087 The result of a request having both an If-Match header field and 6088 either an If-None-Match or an If-Modified-Since header fields is 6089 undefined by this specification. 6091 14.25 If-Modified-Since 6093 The If-Modified-Since request-header field is used with a method to 6094 make it conditional: if the requested variant has not been modified 6095 since the time specified in this field, an entity will not be 6096 returned from the server; instead, a 304 (not modified) response will 6097 be returned without any message-body. 6099 If-Modified-Since = "If-Modified-Since" ":" HTTP-date 6101 An example of the field is: 6103 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 6105 A GET method with an If-Modified-Since header and no Range header 6106 requests that the identified entity be transferred only if it has 6107 been modified since the date given by the If-Modified-Since header. 6109 The algorithm for determining this includes the following cases: 6111 a) If the request would normally result in anything other than a 200 6112 (OK) status, or if the passed If-Modified-Since date is invalid, the 6113 response is exactly the same as for a normal GET. A date which is 6114 later than the server's current time is invalid. 6116 b) If the variant has been modified since the If-Modified-Since date, 6117 the response is exactly the same as for a normal GET. 6119 c) If the variant has not been modified since a valid If-Modified-Since 6120 date, the server SHOULD return a 304 (Not Modified) response. 6122 The purpose of this feature is to allow efficient updates of cached 6123 information with a minimum amount of transaction overhead. 6125 Note: The Range request-header field modifies the meaning of If- 6126 Modified-Since; see section 14.35 for full details. 6128 Note: If-Modified-Since times are interpreted by the server, whose 6129 clock might not be synchronized with the client. 6131 Note: When handling an If-Modified-Since header field, some servers 6132 will use an exact date comparison function, rather than a less-than 6133 function, for deciding whether to send a 304 (Not Modified) 6134 response. To get best results when sending an If-Modified-Since 6135 header field for cache validation, clients are advised to use the 6136 exact date string received in a previous Last-Modified header field 6137 whenever possible. 6139 Note: If a client uses an arbitrary date in the If-Modified-Since 6140 header instead of a date taken from the Last-Modified header for 6141 the same request, the client should be aware of the fact that this 6142 date is interpreted in the server's understanding of time. The 6143 client should consider unsynchronized clocks and rounding problems 6144 due to the different encodings of time between the client and 6145 server. This includes the possibility of race conditions if the 6146 document has changed between the time it was first requested and 6147 the If-Modified-Since date of a subsequent request, and the 6148 possibility of clock-skew-related problems if the If-Modified-Since 6149 date is derived from the client's clock without correction to the 6150 server's clock. Corrections for different time bases between client 6151 and server are at best approximate due to network latency. 6153 The result of a request having both an If-Modified-Since header field 6154 and either an If-Match or an If-Unmodified-Since header fields is 6155 undefined by this specification. 6157 14.26 If-None-Match 6159 The If-None-Match request-header field is used with a method to make 6160 it conditional. A client that has one or more entities previously 6161 obtained from the resource can verify that none of those entities is 6162 current by including a list of their associated entity tags in the 6163 If-None-Match header field. The purpose of this feature is to allow 6164 efficient updates of cached information with a minimum amount of 6165 transaction overhead. It is also used to prevent a method (e.g. PUT) 6166 from inadvertently modifying an existing resource when the client 6167 believes that the resource does not exist. 6169 As a special case, the value "*" matches any current entity of the 6170 resource. 6172 If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag ) 6174 If any of the entity tags match the entity tag of the entity that 6175 would have been returned in the response to a similar GET request 6176 (without the If-None-Match header) on that resource, or if "*" is 6177 given and any current entity exists for that resource, then the 6178 server MUST NOT perform the requested method, unless required to do 6179 so because the resource's modification date fails to match that 6180 supplied in an If-Modified-Since header field in the request. 6181 Instead, if the request method was GET or HEAD, the server SHOULD 6182 respond with a 304 (Not Modified) response, including the cache- 6183 related header fields (particularly ETag) of one of the entities that 6184 matched. For all other request methods, the server MUST respond with 6185 a status of 412 (Precondition Failed). 6187 See section 13.3.3 for rules on how to determine if two entities tags 6188 match. The weak comparison function can only be used with GET or HEAD 6189 requests. 6191 If none of the entity tags match, then the server MAY perform the 6192 requested method as if the If-None-Match header field did not exist, 6193 but MUST also ignore any If-Modified-Since header field(s) in the 6194 request. That is, if no entity tags match, then the server MUST NOT 6195 return a 304 (Not Modified) response. 6197 If the request would, without the If-None-Match header field, result 6198 in anything other than a 2xx or 304 status, then the If-None-Match 6199 header MUST be ignored. (See section 13.3.4 for a discussion of 6200 server behavior when both If-Modified-Since and If-None-Match appear 6201 in the same request.) 6203 The meaning of "If-None-Match: *" is that the method MUST NOT be 6204 performed if the representation selected by the origin server (or by 6205 a cache, possibly using the Vary mechanism, see section 14.44) 6206 exists, and SHOULD be performed if the representation does not exist. 6207 This feature is intended to be useful in preventing races between PUT 6208 operations. 6210 Examples: 6212 If-None-Match: "xyzzy" 6213 If-None-Match: W/"xyzzy" 6214 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 6215 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 6216 If-None-Match: * 6218 The result of a request having both an If-None-Match header field and 6219 either an If-Match or an If-Unmodified-Since header fields is 6220 undefined by this specification. 6222 14.27 If-Range 6224 If a client has a partial copy of an entity in its cache, and wishes 6225 to have an up-to-date copy of the entire entity in its cache, it 6226 could use the Range request-header with a conditional GET (using 6227 either or both of If-Unmodified-Since and If-Match.) However, if the 6228 condition fails because the entity has been modified, the client 6229 would then have to make a second request to obtain the entire current 6230 entity-body. 6232 The If-Range header allows a client to "short-circuit" the second 6233 request. Informally, its meaning is �if the entity is unchanged, send 6234 me the part(s) that I am missing; otherwise, send me the entire new 6236 entity. 6238 If-Range = "If-Range" ":" ( entity-tag | HTTP-date ) 6240 If the client has no entity tag for an entity, but does have a Last- 6241 Modified date, it MAY use that date in an If-Range header. (The 6242 server can distinguish between a valid HTTP-date and any form of 6243 entity-tag by examining no more than two characters.) The If-Range 6244 header SHOULD only be used together with a Range header, and MUST be 6245 ignored if the request does not include a Range header, or if the 6246 server does not support the sub-range operation. 6248 If the entity tag given in the If-Range header matches the current 6249 entity tag for the entity, then the server SHOULD provide the 6250 specified sub-range of the entity using a 206 (Partial content) 6251 response. If the entity tag does not match, then the server SHOULD 6252 return the entire entity using a 200 (OK) response. 6254 14.28 If-Unmodified-Since 6256 The If-Unmodified-Since request-header field is used with a method to 6257 make it conditional. If the requested resource has not been modified 6258 since the time specified in this field, the server SHOULD perform the 6259 requested operation as if the If-Unmodified-Since header were not 6260 present. 6262 If the requested variant has been modified since the specified time, 6263 the server MUST NOT perform the requested operation, and MUST return 6264 a 412 (Precondition Failed). 6266 If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date 6268 An example of the field is: 6270 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 6272 If the request normally (i.e., without the If-Unmodified-Since 6273 header) would result in anything other than a 2xx or 412 status, the 6274 If-Unmodified-Since header SHOULD be ignored. 6276 If the specified date is invalid, the header is ignored. 6278 The result of a request having both an If-Unmodified-Since header 6279 field and either an If-None-Match or an If-Modified-Since header 6280 fields is undefined by this specification. 6282 14.29 Last-Modified 6284 The Last-Modified entity-header field indicates the date and time at 6285 which the origin server believes the variant was last modified. 6287 Last-Modified = "Last-Modified" ":" HTTP-date 6289 An example of its use is 6291 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 6293 The exact meaning of this header field depends on the implementation 6294 of the origin server and the nature of the original resource. For 6295 files, it may be just the file system last-modified time. For 6296 entities with dynamically included parts, it may be the most recent 6297 of the set of last-modify times for its component parts. For database 6298 gateways, it may be the last-update time stamp of the record. For 6299 virtual objects, it may be the last time the internal state changed. 6301 An origin server MUST NOT send a Last-Modified date which is later 6302 than the server's time of message origination. In such cases, where 6303 the resource's last modification would indicate some time in the 6304 future, the server MUST replace that date with the message 6305 origination date. 6307 An origin server SHOULD obtain the Last-Modified value of the entity 6308 as close as possible to the time that it generates the Date value of 6309 its response. This allows a recipient to make an accurate assessment 6310 of the entity's modification time, especially if the entity changes 6311 near the time that the response is generated. 6313 HTTP/1.1 servers SHOULD send Last-Modified whenever feasible. 6315 14.30 Location 6317 The Location response-header field is used to redirect the recipient 6318 to a location other than the Request-URI for completion of the 6319 request or identification of a new resource. For 201 (Created) 6320 responses, the Location is that of the new resource which was created 6321 by the request. For 3xx responses, the location SHOULD indicate the 6322 server's preferred URI for automatic redirection to the resource. The 6323 field value consists of a single absolute URI. 6325 Location = "Location" ":" absoluteURI [ "#" fragment ] 6327 An example is: 6329 Location: http://www.w3.org/pub/WWW/People.html 6331 Note: The Content-Location header field (section 14.14) differs 6332 from Location in that the Content-Location identifies the original 6333 location of the entity enclosed in the request. It is therefore 6334 possible for a response to contain header fields for both Location 6335 and Content-Location. Also see section 13.10 for cache requirements 6336 of some methods. 6338 There are circumstances in which a fragment identifier in a Location 6339 URL would not be appropriate: 6341 o With a 201 Created response, because in this usage the Location 6342 header specifies the URL for the entire created resource. 6344 o With a 300 Multiple Choices, since the choice decision is 6345 intended to be made on resource characteristics and not fragment 6347 characteristics. 6349 o With 305 Use Proxy. 6351 14.31 Max-Forwards 6353 The Max-Forwards request-header field provides a mechanism with the 6354 TRACE (section 9.8) and OPTIONS (section 9.2) methods to limit the 6355 number of proxies or gateways that can forward the request to the 6356 next inbound server. This can be useful when the client is attempting 6357 to trace a request chain which appears to be failing or looping in 6358 mid-chain. 6360 Max-Forwards = "Max-Forwards" ":" 1*DIGIT 6362 The Max-Forwards value is a decimal integer indicating the remaining 6363 number of times this request message may be forwarded. 6365 Each proxy or gateway recipient of a TRACE or OPTIONS request 6366 containing a Max-Forwards header field MUST check and update its 6367 value prior to forwarding the request. If the received value is zero 6368 (0), the recipient MUST NOT forward the request; instead, it MUST 6369 respond as the final recipient. If the received Max-Forwards value is 6370 greater than zero, then the forwarded message MUST contain an updated 6371 Max-Forwards field with a value decremented by one (1). 6373 The Max-Forwards header field MAY be ignored for all other methods 6374 defined by this specification and for any extension methods for which 6375 it is not explicitly referred to as part of that method definition. 6377 14.32 Pragma 6379 The Pragma general-header field is used to include implementation- 6380 specific directives that might apply to any recipient along the 6381 request/response chain. All pragma directives specify optional 6382 behavior from the viewpoint of the protocol; however, some systems 6383 MAY require that behavior be consistent with the directives. 6385 Pragma = "Pragma" ":" 1#pragma-directive 6386 pragma-directive = "no-cache" | extension-pragma 6387 extension-pragma = token [ "=" ( token | quoted-string ) ] 6389 When the no-cache directive is present in a request message, an 6390 application SHOULD forward the request toward the origin server even 6391 if it has a cached copy of what is being requested. This pragma 6392 directive has the same semantics as the no-cache cache-directive (see 6393 section 14.9) and is defined here for backward compatibility with 6394 HTTP/1.0. Clients SHOULD include both header fields when a no-cache 6395 request is sent to a server not known to be HTTP/1.1 compliant. 6397 Pragma directives MUST be passed through by a proxy or gateway 6398 application, regardless of their significance to that application, 6399 since the directives might be applicable to all recipients along the 6400 request/response chain. It is not possible to specify a pragma for a 6401 specific recipient; however, any pragma directive not relevant to a 6402 recipient SHOULD be ignored by that recipient. 6404 HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had 6405 sent "Cache-Control: no-cache". No new Pragma directives will be 6406 defined in HTTP. 6408 Note: because the meaning of "Pragma: no-cache" as a response 6409 header field is not actually specified, it does not provide a 6410 reliable replacement for "Cache-Control: no-cache" in a response. 6412 14.33 Proxy-Authenticate 6414 The Proxy-Authenticate response-header field MUST be included as part 6415 of a 407 (Proxy Authentication Required) response. The field value 6416 consists of a challenge that indicates the authentication scheme and 6417 parameters applicable to the proxy for this Request-URI. 6419 Proxy-Authenticate = "Proxy-Authenticate" ":" 1#challenge 6421 The HTTP access authentication process is described in "HTTP 6422 Authentication: Basic and Digest Access Authentication" [N10]. Unlike 6423 WWW-Authenticate, the Proxy-Authenticate header field applies only to 6424 the current connection and SHOULD NOT be passed on to downstream 6425 clients. However, an intermediate proxy might need to obtain its own 6426 credentials by requesting them from the downstream client, which in 6427 some circumstances will appear as if the proxy is forwarding the 6428 Proxy-Authenticate header field. 6430 14.34 Proxy-Authorization 6432 The Proxy-Authorization request-header field allows the client to 6433 identify itself (or its user) to a proxy which requires 6434 authentication. The Proxy-Authorization field value consists of 6435 credentials containing the authentication information of the user 6436 agent for the proxy and/or realm of the resource being requested. 6438 Proxy-Authorization = "Proxy-Authorization" ":" credentials 6440 The HTTP access authentication process is described in "HTTP 6441 Authentication: Basic and Digest Access Authentication" [N10] . 6442 Unlike Authorization, the Proxy-Authorization header field applies 6443 only to the next outbound proxy that demanded authentication using 6444 the Proxy-Authenticate field. When multiple proxies are used in a 6445 chain, the Proxy-Authorization header field is consumed by the first 6446 outbound proxy that was expecting to receive credentials. A proxy MAY 6447 relay the credentials from the client request to the next proxy if 6448 that is the mechanism by which the proxies cooperatively authenticate 6449 a given request. 6451 14.35 Range 6453 14.35.1 Byte Ranges 6455 Since all HTTP entities are represented in HTTP messages as sequences 6456 of bytes, the concept of a byte range is meaningful for any HTTP 6457 entity. (However, not all clients and servers need to support byte- 6458 range operations.) 6460 Byte range specifications in HTTP apply to the sequence of bytes in 6461 the entity-body (not necessarily the same as the message-body). 6463 A byte range operation MAY specify a single range of bytes, or a set 6464 of ranges within a single entity. 6466 ranges-specifier = byte-ranges-specifier 6467 byte-ranges-specifier = bytes-unit "=" byte-range-set 6468 byte-range-set = 1#( byte-range-spec | suffix-byte-range-spec ) 6469 byte-range-spec = first-byte-pos "-" [last-byte-pos] 6470 first-byte-pos = 1*DIGIT 6471 last-byte-pos = 1*DIGIT 6473 The first-byte-pos value in a byte-range-spec gives the byte-offset 6474 of the first byte in a range. The last-byte-pos value gives the byte- 6475 offset of the last byte in the range; that is, the byte positions 6476 specified are inclusive. Byte offsets start at zero. 6478 If the last-byte-pos value is present, it MUST be greater than or 6479 equal to the first-byte-pos in that byte-range-spec, or the byte- 6480 range-spec is syntactically invalid. The recipient of a byte-range- 6481 set that includes one or more syntactically invalid byte-range-spec 6482 values MUST ignore the header field that includes that byte-range- 6483 set. 6485 If the last-byte-pos value is absent, or if the value is greater than 6486 or equal to the current length of the entity-body, last-byte-pos is 6487 taken to be equal to one less than the current length of the entity- 6488 body in bytes. 6490 By its choice of last-byte-pos, a client can limit the number of 6491 bytes retrieved without knowing the size of the entity. 6493 suffix-byte-range-spec = "-" suffix-length 6494 suffix-length = 1*DIGIT 6496 A suffix-byte-range-spec is used to specify the suffix of the entity- 6497 body, of a length given by the suffix-length value. (That is, this 6498 form specifies the last N bytes of an entity-body.) If the entity is 6499 shorter than the specified suffix-length, the entire entity-body is 6500 used. 6502 If a syntactically valid byte-range-set includes at least one byte- 6503 range-spec whose first-byte-pos is less than the current length of 6504 the entity-body, or at least one suffix-byte-range-spec with a non- 6505 zero suffix-length, then the byte-range-set is satisfiable. 6506 Otherwise, the byte-range-set is unsatisfiable. If the byte-range-set 6507 is unsatisfiable, the server SHOULD return a response with a status 6508 of 416 (Requested range not satisfiable). Otherwise, the server 6509 SHOULD return a response with a status of 206 (Partial Content) 6510 containing the satisfiable ranges of the entity-body. 6512 Examples of byte-ranges-specifier values (assuming an entity-body of 6514 length 10000): 6516 o The first 500 bytes (byte offsets 0-499, inclusive): 6517 bytes=0-499 6518 o The second 500 bytes (byte offsets 500-999, inclusive): 6519 bytes=500-999 6520 o The final 500 bytes (byte offsets 9500-9999, inclusive): 6521 bytes=-500 6522 o Or 6523 bytes=9500- 6524 o The first and last bytes only (bytes 0 and 9999): 6525 bytes=0-0,-1 6526 o Several legal but not canonical specifications of the second 500 6527 bytes (byte offsets 500-999, inclusive): 6528 bytes=500-600,601-999 6529 bytes=500-700,601-999 6530 14.35.2 Range Retrieval Requests 6532 HTTP retrieval requests using conditional or unconditional GET 6533 methods MAY request one or more sub-ranges of the entity, instead of 6534 the entire entity, using the Range request header, which applies to 6535 the entity returned as the result of the request: 6537 Range = "Range" ":" ranges-specifier 6539 A server MAY ignore the Range header. However, HTTP/1.1 origin 6540 servers and intermediate caches ought to support byte ranges when 6541 possible, since Range supports efficient recovery from partially 6542 failed transfers, and supports efficient partial retrieval of large 6543 entities. 6545 If the server supports the Range header and the specified range or 6546 ranges are appropriate for the entity: 6548 o The presence of a Range header in an unconditional GET modifies 6549 what is returned if the GET is otherwise successful. In other 6550 words, the response carries a status code of 206 (Partial Content) 6551 instead of 200 (OK). 6552 o The presence of a Range header in a conditional GET (a request 6553 using one or both of If-Modified-Since and If-None-Match, or one or 6554 both of If-Unmodified-Since and If-Match) modifies what is returned 6555 if the GET is otherwise successful and the condition is true. It 6556 does not affect the 304 (Not Modified) response returned if the 6557 conditional is false. 6558 In some cases, it might be more appropriate to use the If-Range 6559 header (see section 14.27) in addition to the Range header. 6561 If a proxy that supports ranges receives a Range request, forwards 6562 the request to an inbound server, and receives an entire entity in 6563 reply, it SHOULD only return the requested range to its client. It 6564 SHOULD store the entire received response in its cache if that is 6565 consistent with its cache allocation policies. 6567 14.36 Referer 6569 The Referer[sic] request-header field allows the client to specify, 6570 for the server's benefit, the address (URI) of the resource from 6571 which the Request-URI was obtained (the "referrer", although the 6572 header field is misspelled.) The Referer request-header allows a 6573 server to generate lists of back-links to resources for interest, 6574 logging, optimized caching, etc. It also allows obsolete or mistyped 6575 links to be traced for maintenance. The Referer field MUST NOT be 6576 sent if the Request-URI was obtained from a source that does not have 6577 its own URI, such as input from the user keyboard. 6579 Referer = "Referer" ":" ( absoluteURI | relativeURI ) 6581 Example: 6583 Referer: http://www.w3.org/hypertext/DataSources/Overview.html 6584 If the field value is a relative URI, it SHOULD be interpreted 6585 relative to the Request-URI. The URI MUST NOT include a fragment. See 6586 section 15.1.3 for security considerations. 6588 14.37 Retry-After 6590 The Retry-After response-header field can be used with a 503 (Service 6591 Unavailable) response to indicate how long the service is expected to 6592 be unavailable to the requesting client. This field MAY also be used 6593 with any 3xx (Redirection) response to indicate the minimum time the 6594 user-agent is asked wait before issuing the redirected request. The 6595 value of this field can be either an HTTP-date or an integer number 6596 of seconds (in decimal) after the time of the response. 6598 Retry-After = "Retry-After" ":" ( HTTP-date | delta-seconds ) 6600 Two examples of its use are 6602 Retry-After: Fri, 31 Dec 1999 23:59:59 GMT 6603 Retry-After: 120 6605 In the latter example, the delay is 2 minutes. 6607 14.38 Server 6609 The Server response-header field contains information about the 6610 software used by the origin server to handle the request. The field 6611 can contain multiple product tokens (section 3.8) and comments 6612 identifying the server and any significant subproducts. The product 6613 tokens are listed in order of their significance for identifying the 6614 application. 6616 Server = "Server" ":" 1*( product | comment ) 6618 Example: 6620 Server: CERN/3.0 libwww/2.17 6622 If the response is being forwarded through a proxy, the proxy 6623 application MUST NOT modify the Server response-header. Instead, it 6624 MUST include a Via field (as described in section 14.45). 6626 Note: Revealing the specific software version of the server might 6627 allow the server machine to become more vulnerable to attacks 6628 against software that is known to contain security holes. Server 6629 implementors are encouraged to make this field a configurable 6630 option. 6632 14.39 TE 6634 The TE request-header field indicates what extension transfer-codings 6635 it is willing to accept in the response and whether or not it is 6636 willing to accept trailer fields in a chunked transfer-coding. Its 6637 value may consist of the keyword "trailers" and/or a comma-separated 6638 list of extension transfer-coding names with optional accept 6639 parameters (as described in section 3.6). 6641 TE = "TE" ":" #( t-codings ) 6642 t-codings = "trailers" | ( transfer-extension [ accept-params ] ) 6644 The presence of the keyword "trailers" indicates that the client is 6645 willing to accept trailer fields in a chunked transfer-coding, as 6646 defined in section 3.6.1. This keyword is reserved for use with 6647 transfer-coding values even though it does not itself represent a 6648 transfer-coding. 6650 Examples of its use are: 6652 TE: deflate 6653 TE: 6654 TE: trailers, deflate;q=0.5 6656 The TE header field only applies to the immediate connection. 6657 Therefore, the keyword MUST be supplied within a Connection header 6658 field (section 14.10) whenever TE is present in an HTTP/1.1 message. 6660 A server tests whether a transfer-coding is acceptable, according to 6661 a TE field, using these rules: 6663 1.The "chunked" transfer-coding is always acceptable. If the keyword 6664 "trailers" is listed, the client indicates that it is willing to 6665 accept trailer fields in the chunked response on behalf of itself 6666 and any downstream clients. The implication is that, if given, the 6667 client is stating that either all downstream clients are willing to 6668 accept trailer fields in the forwarded response, or that it will 6669 attempt to buffer the response on behalf of downstream recipients. 6671 Note: HTTP/1.1 does not define any means to limit the size of a 6672 chunked response such that a client can be assured of buffering the 6673 entire response. 6675 2.If the transfer-coding being tested is one of the transfer-codings 6676 listed in the TE field, then it is acceptable unless it is 6677 accompanied by a qvalue of 0. (As defined in section 3.9, a qvalue 6678 of 0 means "not acceptable.") 6680 3.If multiple transfer-codings are acceptable, then the acceptable 6681 transfer-coding with the highest non-zero qvalue is preferred. The 6682 "chunked" transfer-coding always has a qvalue of 1. 6684 If the TE field-value is empty or if no TE field is present, the only 6685 transfer-coding is "chunked". A message with no transfer-coding is 6686 always acceptable. 6688 14.40 Trailer 6690 The Trailer general field value indicates that the given set of 6691 header fields is present in the trailer of a message encoded with 6692 chunked transfer-coding. 6694 Trailer = "Trailer" ":" 1#field-name 6696 An HTTP/1.1 message SHOULD include a Trailer header field in a 6697 message using chunked transfer-coding with a non-empty trailer. Doing 6698 so allows the recipient to know which header fields to expect in the 6699 trailer. 6701 If no Trailer header field is present, the trailer SHOULD NOT include 6702 any header fields. See section 3.6.1 for restrictions on the use of 6703 trailer fields in a "chunked" transfer-coding. 6705 Message header fields listed in the Trailer header field MUST NOT 6706 include the following header fields: 6708 o Transfer-Encoding 6709 o Content-Length 6710 o Trailer 6712 14.41 Transfer-Encoding 6714 The Transfer-Encoding general-header field indicates what (if any) 6715 type of transformation has been applied to the message body in order 6716 to safely transfer it between the sender and the recipient. This 6717 differs from the content-coding in that the transfer-coding is a 6718 property of the message, not of the entity. 6720 Transfer-Encoding = "Transfer-Encoding" ":" 1#transfer-coding 6722 Transfer-codings are defined in section 3.6. An example is: 6724 Transfer-Encoding: chunked 6726 If multiple encodings have been applied to an entity, the transfer- 6727 codings MUST be listed in the order in which they were applied. 6728 Additional information about the encoding parameters MAY be provided 6729 by other entity-header fields not defined by this specification. 6730 Many older HTTP/1.0 applications do not understand the Transfer- 6731 Encoding header. 6733 14.42 Upgrade 6735 The Upgrade general-header allows the client to specify what 6736 additional communication protocols it supports and would like to use 6737 if the server finds it appropriate to switch protocols. The server 6738 MUST use the Upgrade header field within a 101 (Switching Protocols) 6739 response to indicate which protocol(s) are being switched. 6741 Upgrade = "Upgrade" ":" 1#product 6743 For example, 6745 Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11 6747 The Upgrade header field is intended to provide a simple mechanism 6748 for transition from HTTP/1.1 to some other, incompatible protocol. It 6749 does so by allowing the client to advertise its desire to use another 6750 protocol, such as a later version of HTTP with a higher major version 6751 number, even though the current request has been made using HTTP/1.1. 6752 This eases the difficult transition between incompatible protocols by 6753 allowing the client to initiate a request in the more commonly 6754 supported protocol while indicating to the server that it would like 6755 to use a "better" protocol if available (where "better" is determined 6756 by the server, possibly according to the nature of the method and/or 6757 resource being requested). 6759 The Upgrade header field only applies to switching application-layer 6760 protocols upon the existing transport-layer connection. Upgrade 6761 cannot be used to insist on a protocol change; its acceptance and use 6762 by the server is optional. The capabilities and nature of the 6763 application-layer communication after the protocol change is entirely 6764 dependent upon the new protocol chosen, although the first action 6765 after changing the protocol MUST be a response to the initial HTTP 6766 request containing the Upgrade header field. 6768 The Upgrade header field only applies to the immediate connection. 6769 Therefore, the upgrade keyword MUST be supplied within a Connection 6770 header field (section 14.10) whenever Upgrade is present in an 6771 HTTP/1.1 message. 6773 The Upgrade header field cannot be used to indicate a switch to a 6774 protocol on a different connection. For that purpose, it is more 6775 appropriate to use a 301, 302, 303, or 305 redirection response. 6777 This specification only defines the protocol name "HTTP" for use by 6778 the family of Hypertext Transfer Protocols, as defined by the HTTP 6779 version rules of section 3.1 and future updates to this 6780 specification. Any token can be used as a protocol name; however, it 6781 will only be useful if both the client and server associate the name 6782 with the same protocol. 6784 14.43 User-Agent 6786 The User-Agent request-header field contains information about the 6787 user agent originating the request. This is for statistical purposes, 6788 the tracing of protocol violations, and automated recognition of user 6789 agents for the sake of tailoring responses to avoid particular user 6790 agent limitations. User agents SHOULD include this field with 6791 requests. The field can contain multiple product tokens (section 3.8) 6792 and comments identifying the agent and any subproducts which form a 6793 significant part of the user agent. By convention, the product tokens 6794 are listed in order of their significance for identifying the 6795 application. 6797 User-Agent = "User-Agent" ":" 1*( product | comment ) 6799 Example: 6801 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 6802 14.44 Vary 6804 The Vary field value indicates the set of request-header fields that 6805 fully determines, while the response is fresh, whether a cache is 6806 permitted to use the response to reply to a subsequent request 6807 without revalidation. For uncacheable or stale responses, the Vary 6808 field value advises the user agent about the criteria that were used 6809 to select the representation. A Vary field value of "*" implies that 6810 a cache cannot determine from the request headers of a subsequent 6811 request whether this response is the appropriate representation. See 6812 section 13.6 for use of the Vary header field by caches. 6814 Vary = "Vary" ":" ( "*" | 1#field-name ) 6816 An HTTP/1.1 server SHOULD include a Vary header field with any 6817 cacheable response that is subject to server-driven negotiation. 6818 Doing so allows a cache to properly interpret future requests on that 6819 resource and informs the user agent about the presence of negotiation 6820 on that resource. A server MAY include a Vary header field with a 6821 non-cacheable response that is subject to server-driven negotiation, 6822 since this might provide the user agent with useful information about 6823 the dimensions over which the response varies at the time of the 6824 response. 6826 A Vary field value consisting of a list of field-names signals that 6827 the representation selected for the response is based on a selection 6828 algorithm which considers ONLY the listed request-header field values 6829 in selecting the most appropriate representation. A cache MAY assume 6830 that the same selection will be made for future requests with the 6831 same values for the listed field names, for the duration of time for 6832 which the response is fresh. 6834 The field-names given are not limited to the set of standard request- 6835 header fields defined by this specification. Field names are case- 6836 insensitive. 6838 A Vary field value of "*" signals that unspecified parameters not 6839 limited to the request-headers (e.g., the network address of the 6840 client), play a role in the selection of the response representation. 6841 The "*" value MUST NOT be generated by a proxy server; it may only be 6842 generated by an origin server. 6844 14.45 Via 6846 The Via general-header field MUST be used by gateways and proxies to 6847 indicate the intermediate protocols and recipients between the user 6848 agent and the server on requests, and between the origin server and 6849 the client on responses. It is analogous to the "Received" field of 6850 RFC 822 [9] and is intended to be used for tracking message forwards, 6851 avoiding request loops, and identifying the protocol capabilities of 6852 all senders along the request/response chain. 6854 Via = "Via" ":" 1#( received-protocol received-by [ comment ] ) 6855 received-protocol = [ protocol-name "/" ] protocol-version 6857 protocol-name = token 6858 protocol-version = token 6859 received-by = ( host [ ":" port ] ) | pseudonym 6860 pseudonym = token 6862 The received-protocol indicates the protocol version of the message 6863 received by the server or client along each segment of the 6864 request/response chain. The received-protocol version is appended to 6865 the Via field value when the message is forwarded so that information 6866 about the protocol capabilities of upstream applications remains 6867 visible to all recipients. 6869 The protocol-name is optional if and only if it would be "HTTP". The 6870 received-by field is normally the host and optional port number of a 6871 recipient server or client that subsequently forwarded the message. 6872 However, if the real host is considered to be sensitive information, 6873 it MAY be replaced by a pseudonym. If the port is not given, it MAY 6874 be assumed to be the default port of the received-protocol. 6876 Multiple Via field values represents each proxy or gateway that has 6877 forwarded the message. Each recipient MUST append its information 6878 such that the end result is ordered according to the sequence of 6879 forwarding applications. 6881 Comments MAY be used in the Via header field to identify the software 6882 of the recipient proxy or gateway, analogous to the User-Agent and 6883 Server header fields. However, all comments in the Via field are 6884 optional and MAY be removed by any recipient prior to forwarding the 6885 message. 6887 For example, a request message could be sent from an HTTP/1.0 user 6888 agent to an internal proxy code-named "fred", which uses HTTP/1.1 to 6889 forward the request to a public proxy at nowhere.com, which completes 6890 the request by forwarding it to the origin server at www.ics.uci.edu. 6891 The request received by www.ics.uci.edu would then have the following 6892 Via header field: 6894 Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1) 6896 Proxies and gateways used as a portal through a network firewall 6897 SHOULD NOT, by default, forward the names and ports of hosts within 6898 the firewall region. This information SHOULD only be propagated if 6899 explicitly enabled. If not enabled, the received-by host of any host 6900 behind the firewall SHOULD be replaced by an appropriate pseudonym 6901 for that host. 6903 For organizations that have strong privacy requirements for hiding 6904 internal structures, a proxy MAY combine an ordered subsequence of 6905 Via header field entries with identical received-protocol values into 6906 a single such entry. For example, 6908 Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy 6909 could be collapsed to 6911 Via: 1.0 ricky, 1.1 mertz, 1.0 lucy 6913 Applications SHOULD NOT combine multiple entries unless they are all 6914 under the same organizational control and the hosts have already been 6915 replaced by pseudonyms. Applications MUST NOT combine entries which 6916 have different received-protocol values. 6918 14.46 Warning 6920 The Warning general-header field is used to carry additional 6921 information about the status or transformation of a message which 6922 might not be reflected in the message. This information is typically 6923 used to warn about a possible lack of semantic transparency from 6924 caching operations or transformations applied to the entity body of 6925 the message. 6927 Warning headers are sent with responses using: 6929 Warning = "Warning" ":" 1#warning-value 6930 warning-value = warn-code SP warn-agent SP warn-text 6931 [SP warn-date] 6933 warn-code = 3DIGIT 6934 warn-agent = ( host [ ":" port ] ) | pseudonym 6935 ; the name or pseudonym of the server adding 6937 ; the Warning header, for use in debugging 6938 warn-text = quoted-string 6939 warn-date = <"> HTTP-date <"> 6941 A response MAY carry more than one Warning header. 6943 The warn-text SHOULD be in a natural language and character set that 6944 is most likely to be intelligible to the human user receiving the 6945 response. This decision MAY be based on any available knowledge, such 6946 as the location of the cache or user, the Accept-Language field in a 6947 request, the Content-Language field in a response, etc. The default 6948 language is English and the default character set is ISO-8859-1. 6950 If a character set other than ISO-8859-1 is used, it MUST be encoded 6951 in the warn-text using the method described in RFC 2047 [N4]. 6953 Warning headers can in general be applied to any message, however 6954 some specific warn-codes are specific to caches and can only be 6955 applied to response messages. New Warning headers SHOULD be added 6956 after any existing Warning headers. A cache MUST NOT delete any 6957 Warning header that it received with a message. However, if a cache 6958 successfully validates a cache entry, it SHOULD remove any Warning 6959 headers previously attached to that entry except as specified for 6960 specific Warning codes. It MUST then add any Warning headers received 6961 in the validating response. In other words, Warning headers are those 6962 that would be attached to the most recent relevant response. 6964 When multiple Warning headers are attached to a response, the user 6965 agent ought to inform the user of as many of them as possible, in the 6966 order that they appear in the response. If it is not possible to 6967 inform the user of all of the warnings, the user agent SHOULD follow 6968 these heuristics: 6970 o Warnings that appear early in the response take priority over those 6971 appearing later in the response. 6972 o Warnings in the user's preferred character set take priority over 6973 warnings in other character sets but with identical warn-codes and 6974 warn-agents. 6976 Systems that generate multiple Warning headers SHOULD order them with 6977 this user agent behavior in mind. 6979 Requirements for the behavior of caches with respect to Warnings are 6980 stated in section 13.1.2. 6982 This is a list of the currently-defined warn-codes, each with a 6983 recommended warn-text in English, and a description of its meaning. 6985 110 Response is stale 6986 MUST be included whenever the returned response is stale. 6988 111 Revalidation failed 6989 MUST be included if a cache returns a stale response because an 6990 attempt to revalidate the response failed, due to an inability to 6991 reach the server. 6993 112 Disconnected operation 6994 SHOULD be included if the cache is intentionally disconnected from 6995 the rest of the network for a period of time. 6997 113 Heuristic expiration 6998 MUST be included if the cache heuristically chose a freshness 6999 lifetime greater than 24 hours and the response'ss age is greater than 7000 24 hours. 7002 199 Miscellaneous warning 7003 The warning text MAY include arbitrary information to be presented to 7004 a human user, or logged. A system receiving this warning MUST NOT 7005 take any automated action, besides presenting the warning to the 7006 user. 7008 214 Transformation applied 7009 MUST be added by an intermediate cache or proxy if it applies any 7010 transformation changing the content-coding (as specified in the 7011 Content-Encoding header) or media-type (as specified in the Content- 7012 Type header) of the response, or the entity-body of the response, 7013 unless this Warning code already appears in the response. 7015 299 Miscellaneous persistent warning 7016 The warning text MAY include arbitrary information to be presented to 7017 a human user, or logged. A system receiving this warning MUST NOT 7018 take any automated action. 7020 If an implementation sends a message with one or more Warning headers 7021 whose version is HTTP/1.0 or lower, then the sender MUST include in 7022 each warning-value a warn-date that matches the date in the response. 7024 If an implementation receives a message with a warning-value that 7025 includes a warn-date, and that warn-date is different from the Date 7026 value in the response, then that warning-value MUST be deleted from 7027 the message before storing, forwarding, or using it. (This prevents 7028 bad consequences of naive caching of Warning header fields.) If all 7029 of the warning-values are deleted for this reason, the Warning header 7030 MUST be deleted as well. 7032 14.47 WWW-Authenticate 7034 The WWW-Authenticate response-header field MUST be included in 401 7035 (Unauthorized) response messages. The field value consists of at 7036 least one challenge that indicates the authentication scheme(s) and 7037 parameters applicable to the Request-URI. 7039 WWW-Authenticate = "WWW-Authenticate" ":" 1#challenge 7041 The HTTP access authentication process is described in "HTTP 7042 Authentication: Basic and Digest Access Authentication" [N10]. User 7043 agents are advised to take special care in parsing the WWW- 7044 Authenticate field value as it might contain more than one challenge, 7045 or if more than one WWW-Authenticate header field is provided, the 7046 contents of a challenge itself can contain a comma-separated list of 7047 authentication parameters. 7049 15 Security Considerations 7051 This section is meant to inform application developers, information 7052 providers, and users of the security limitations in HTTP/1.1 as 7053 described by this document. The discussion does not include 7054 definitive solutions to the problems revealed, though it does make 7055 some suggestions for reducing security risks. 7057 15.1 Personal Information 7059 HTTP clients are often privy to large amounts of personal information 7060 (e.g. the user's name, location, mail address, passwords, encryption 7061 keys, etc.), and SHOULD be very careful to prevent unintentional 7062 leakage of this information via the HTTP protocol to other sources. 7064 We very strongly recommend that a convenient interface be provided 7065 for the user to control dissemination of such information, and that 7066 designers and implementors be particularly careful in this area. 7067 History shows that errors in this area often create serious security 7068 and/or privacy problems and generate highly adverse publicity for the 7069 implementor's company. 7071 15.1.1 Abuse of Server Log Information 7073 A server is in the position to save personal data about a user's 7074 requests which might identify their reading patterns or subjects of 7075 interest. This information is clearly confidential in nature and its 7076 handling can be constrained by law in certain countries. People using 7077 the HTTP protocol to provide data are responsible for ensuring that 7078 such material is not distributed without the permission of any 7079 individuals that are identifiable by the published results. 7081 15.1.2 Transfer of Sensitive Information 7083 Like any generic data transfer protocol, HTTP cannot regulate the 7084 content of the data that is transferred, nor is there any a priori 7085 method of determining the sensitivity of any particular piece of 7086 information within the context of any given request. Therefore, 7087 applications SHOULD supply as much control over this information as 7088 possible to the provider of that information. Four header fields are 7089 worth special mention in this context: Server, Via, Referer and From. 7091 Revealing the specific software version of the server might allow the 7092 server machine to become more vulnerable to attacks against software 7093 that is known to contain security holes. Implementors SHOULD make the 7094 Server header field a configurable option. 7096 Proxies which serve as a portal through a network firewall SHOULD 7097 take special precautions regarding the transfer of header information 7098 that identifies the hosts behind the firewall. In particular, they 7099 SHOULD remove, or replace with sanitized versions, any Via fields 7100 generated behind the firewall. 7102 The Referer header allows reading patterns to be studied and reverse 7103 links drawn. Although it can be very useful, its power can be abused 7104 if user details are not separated from the information contained in 7105 the Referer. Even when the personal information has been removed, the 7106 Referer header might indicate a private document's URI whose 7107 publication would be inappropriate. 7109 The information sent in the From field might conflict with the user's 7110 privacy interests or their site's security policy, and hence it 7111 SHOULD NOT be transmitted without the user being able to disable, 7112 enable, and modify the contents of the field. The user MUST be able 7113 to set the contents of this field within a user preference or 7114 application defaults configuration. 7116 We suggest, though do not require, that a convenient toggle interface 7117 be provided for the user to enable or disable the sending of From and 7118 Referer information. 7120 The User-Agent (section 14.43) or Server (section 14.38) header 7121 fields can sometimes be used to determine that a specific client or 7122 server have a particular security hole which might be exploited. 7123 Unfortunately, this same information is often used for other valuable 7124 purposes for which HTTP currently has no better mechanism. 7126 15.1.3 Encoding Sensitive Information in URI�s 7128 Because the source of a link might be private information or might 7129 reveal an otherwise private information source, it is strongly 7130 recommended that the user be able to select whether or not the 7131 Referer field is sent. For example, a browser client could have a 7132 toggle switch for browsing openly/anonymously, which would 7133 respectively enable/disable the sending of Referer and From 7134 information. 7136 Clients SHOULD NOT include a Referer header field in a (non-secure) 7137 HTTP request if the referring page was transferred with a secure 7138 protocol. 7140 Authors of services which use the HTTP protocol SHOULD NOT use GET 7141 based forms for the submission of sensitive data, because this will 7142 cause this data to be encoded in the Request-URI. Many existing 7143 servers, proxies, and user agents will log the request URI in some 7144 place where it might be visible to third parties. Servers can use 7145 POST-based form submission instead 7147 15.1.4 Privacy Issues Connected to Accept Headers 7149 Accept request-headers can reveal information about the user to all 7150 servers which are accessed. The Accept-Language header in particular 7151 can reveal information the user would consider to be of a private 7152 nature, because the understanding of particular languages is often 7153 strongly correlated to the membership of a particular ethnic group. 7154 User agents which offer the option to configure the contents of an 7155 Accept-Language header to be sent in every request are strongly 7156 encouraged to let the configuration process include a message which 7157 makes the user aware of the loss of privacy involved. 7159 An approach that limits the loss of privacy would be for a user agent 7160 to omit the sending of Accept-Language headers by default, and to ask 7161 the user whether or not to start sending Accept-Language headers to a 7162 server if it detects, by looking for any Vary response-header fields 7163 generated by the server, that such sending could improve the quality 7164 of service. 7166 Elaborate user-customized accept header fields sent in every request, 7167 in particular if these include quality values, can be used by servers 7168 as relatively reliable and long-lived user identifiers. Such user 7169 identifiers would allow content providers to do click-trail tracking, 7170 and would allow collaborating content providers to match cross-server 7171 click-trails or form submissions of individual users. Note that for 7172 many users not behind a proxy, the network address of the host 7173 running the user agent will also serve as a long-lived user 7174 identifier. In environments where proxies are used to enhance 7175 privacy, user agents ought to be conservative in offering accept 7176 header configuration options to end users. As an extreme privacy 7177 measure, proxies could filter the accept headers in relayed requests. 7178 General purpose user agents which provide a high degree of header 7179 configurability SHOULD warn users about the loss of privacy which can 7180 be involved. 7182 15.2 Attacks Based On File and Path Names 7184 Implementations of HTTP origin servers SHOULD be careful to restrict 7185 the documents returned by HTTP requests to be only those that were 7186 intended by the server administrators. If an HTTP server translates 7187 HTTP URIs directly into file system calls, the server MUST take 7188 special care not to serve files that were not intended to be 7189 delivered to HTTP clients. For example, UNIX, Microsoft Windows, and 7190 other operating systems use ".." as a path component to indicate a 7191 directory level above the current one. On such a system, an HTTP 7192 server MUST disallow any such construct in the Request-URI if it 7193 would otherwise allow access to a resource outside those intended to 7194 be accessible via the HTTP server. Similarly, files intended for 7195 reference only internally to the server (such as access control 7196 files, configuration files, and script code) MUST be protected from 7197 inappropriate retrieval, since they might contain sensitive 7198 information. Experience has shown that minor bugs in such HTTP server 7199 implementations have turned into security risks. 7201 15.3 DNS Spoofing 7203 Clients using HTTP rely heavily on the Domain Name Service, and are 7204 thus generally prone to security attacks based on the deliberate mis- 7205 association of IP addresses and DNS names. Clients need to be 7206 cautious in assuming the continuing validity of an IP number/DNS name 7207 association. 7209 In particular, HTTP clients SHOULD rely on their name resolver for 7210 confirmation of an IP number/DNS name association, rather than 7211 caching the result of previous host name lookups. Many platforms 7212 already can cache host name lookups locally when appropriate, and 7213 they SHOULD be configured to do so. It is proper for these lookups to 7214 be cached, however, only when the TTL (Time To Live) information 7215 reported by the name server makes it likely that the cached 7216 information will remain useful. 7218 If HTTP clients cache the results of host name lookups in order to 7219 achieve a performance improvement, they MUST observe the TTL 7220 information reported by DNS. 7222 If HTTP clients do not observe this rule, they could be spoofed when 7223 a previously-accessed server's IP address changes. As network 7224 renumbering is expected to become increasingly common [24], the 7225 possibility of this form of attack will grow. Observing this 7226 requirement thus reduces this potential security vulnerability. 7228 This requirement also improves the load-balancing behavior of clients 7229 for replicated servers using the same DNS name and reduces the 7230 likelihood of a user's experiencing failure in accessing sites which 7231 use that strategy. 7233 15.4 Location Headers and Spoofing 7235 If a single server supports multiple organizations that do not trust 7236 one another, then it MUST check the values of Location and Content- 7237 Location headers in responses that are generated under control of 7238 said organizations to make sure that they do not attempt to 7239 invalidate resources over which they have no authority. 7241 15.5 Content-Disposition Issues 7243 RFC 1806 [I27], from which the often implemented Content-Disposition 7244 (see section 17.5.1) header in HTTP is derived, has a number of very 7245 serious security considerations. Content-Disposition is not part of 7246 the HTTP standard, but since it is widely implemented, we are 7247 documenting its use and risks for implementors. See RFC 2183 [I38] 7248 (which updates RFC 1806) for details. 7250 15.6 Authentication Credentials and Idle Clients 7252 Existing HTTP clients and user agents typically retain authentication 7253 information indefinitely. HTTP/1.1. does not provide a method for a 7254 server to direct clients to discard these cached credentials. This is 7255 a significant defect that requires further extensions to HTTP. 7256 Circumstances under which credential caching can interfere with the 7257 application's security model include but are not limited to: 7259 Clients which have been idle for an extended period following which 7260 the server might wish to cause the client to reprompt the user for 7261 credentials. 7263 . Applications which include a session termination indication (such as 7264 a logout or commit button on a page) after which the server side 7265 of the application knows that there is no further reason for the 7266 client to retain the credentials. 7268 This is currently under separate study. There are a number of work- 7269 arounds to parts of this problem, and we encourage the use of 7270 password protection in screen savers, idle time-outs, and other 7271 methods which mitigate the security problems inherent in this 7272 problem. In particular, user agents which cache credentials are 7273 encouraged to provide a readily accessible mechanism for discarding 7274 cached credentials under user control. 7276 15.7 Proxies and Caching 7278 By their very nature, HTTP proxies are men-in-the-middle, and 7279 represent an opportunity for man-in-the-middle attacks. Compromise of 7280 the systems on which the proxies run can result in serious security 7281 and privacy problems. Proxies have access to security-related 7282 information, personal information about individual users and 7283 organizations, and proprietary information belonging to users and 7284 content providers. A compromised proxy, or a proxy implemented or 7285 configured without regard to security and privacy considerations, 7286 might be used in the commission of a wide range of potential attacks. 7288 Proxy operators should protect the systems on which proxies run as 7289 they would protect any system that contains or transports sensitive 7290 information. In particular, log information gathered at proxies often 7291 contains highly sensitive personal information, and/or information 7292 about organizations. Log information should be carefully guarded, and 7293 appropriate guidelines for use developed and followed. (Section 7294 15.1.1). 7296 Caching proxies provide additional potential vulnerabilities, since 7297 the contents of the cache represent an attractive target for 7298 malicious exploitation. Because cache contents persist after an HTTP 7299 request is complete, an attack on the cache can reveal information 7300 long after a user believes that the information has been removed from 7301 the network. Therefore, cache contents should be protected as 7302 sensitive information. 7304 Proxy implementors should consider the privacy and security 7305 implications of their design and coding decisions, and of the 7306 configuration options they provide to proxy operators (especially the 7307 default configuration). 7309 Users of a proxy need to be aware that they are no trustworthier than 7310 the people who run the proxy; HTTP itself cannot solve this problem. 7312 The judicious use of cryptography, when appropriate, may suffice to 7313 protect against a broad range of security and privacy attacks. Such 7314 cryptography is beyond the scope of the HTTP/1.1 specification. 7316 15.7.1 Denial of Service Attacks on Proxies 7318 They exist. They are hard to defend against. Research continues. 7319 Beware. 7321 16 Acknowledgments 7323 This specification makes heavy use of the augmented BNF and generic 7324 constructs defined by David H. Crocker for RFC 822 [9]. Similarly, it 7325 reuses many of the definitions provided by Nathaniel Borenstein and 7326 Ned Freed for MIME [7]. We hope that their inclusion in this 7327 specification will help reduce past confusion over the relationship 7328 between HTTP and Internet mail message formats. 7330 The HTTP protocol has evolved considerably over the years. It has 7331 benefited from a large and active developer community--the many 7332 people who have participated on the www-talk mailing list--and it is 7333 that community which has been most responsible for the success of 7334 HTTP and of the World-Wide Web in general. Marc Andreessen, Robert 7336 Cailliau, Daniel W. Connolly, Bob Denny, John Franks, Jean-Francois 7337 Groff, Phillip M. Hallam-Baker, Hakon W. Lie, Ari Luotonen, Rob 7338 McCool, Lou Montulli, Dave Raggett, Tony Sanders, and Marc 7339 VanHeyningen deserve special recognition for their efforts in 7340 defining early aspects of the protocol. 7342 This document has benefited greatly from the comments of all those 7343 participating in the HTTP-WG. In addition to those already mentioned, 7344 the following individuals have contributed to this specification: 7346 Gary Adams Ross Patterson 7347 Harald Tveit Alvestrand Albert Lunde 7348 Keith Ball John C. Mallery 7349 Brian Behlendorf Jean-Philippe Martin-Flatin 7350 Paul Burchard Mitra 7351 Maurizio Codogno David Morris 7352 Mike Cowlishaw Gavin Nicol 7353 Roman Czyborra Bill Perry 7354 Michael A. Dolan Jeffrey Perry 7355 David J. Fiander Scott Powers 7356 Alan Freier Owen Rees 7357 Marc Hedlund Luigi Rizzo 7358 Greg Herlihy David Robinson 7359 Koen Holtman Marc Salomon 7360 Alex Hopmann Rich Salz 7361 Bob Jernigan Allan M. Schiffman 7362 Shel Kaphan Jim Seidman 7363 Rohit Khare Chuck Shotton 7364 John Klensin Eric W. Sink 7365 Martijn Koster Simon E. Spero 7366 Alexei Kosut Richard N. Taylor 7367 David M. Kristol Robert S. Thau 7368 Daniel LaLiberte Bill (BearHeart) Weinman 7369 Ben Laurie Francois Yergeau 7370 Paul J. Leach Mary Ellen Zurko 7371 Daniel DuBois Josh Cohen 7373 Much of the content and presentation of the caching design is due to 7374 suggestions and comments from individuals including: Shel Kaphan, 7375 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 7377 Most of the specification of ranges is based on work originally done 7378 by Ari Luotonen and John Franks, with additional input from Steve 7379 Zilles. 7381 Thanks to the "cave men" of Palo Alto. You know who you are. 7383 Jim Gettys (the current editor of this document) wishes particularly 7384 to thank Roy Fielding, the previous editor of this document, along 7385 with John Klensin, Jeff Mogul, Paul Leach, Dave Kristol, Koen 7386 Holtman, John Franks, Josh Cohen, Alex Hopmann, Scott Lawrence, and 7387 Larry Masinter for their help. And thanks go particularly to Jeff 7388 Mogul and Scott Lawrence for performing the "MUST/MAY/SHOULD" audit. 7390 The Apache Group, Anselm Baird-Smith, author of Jigsaw, and Henrik 7391 Frystyk implemented RFC 2068 early, and we wish to thank them for the 7392 discovery of many of the problems that this document attempts to 7393 rectify. 7395 17 Appendices 7397 17.1 IANA Considerations - Internet Media Type message/http and 7398 application/http 7400 The message/http type can be used to enclose a single HTTP request or 7401 response message, provided that it obeys the MIME restrictions for 7403 all "message" types regarding line length and encodings. The 7404 application/http type can be used to enclose a pipeline of one or 7405 more HTTP request or response messages (not intermixed). The 7406 following is to be registered with IANA [N5]. 7408 Media Type name: message 7409 Media subtype name: http 7410 Required parameters: none 7411 Optional parameters: version, msgtype 7412 version: The HTTP-Version number of the enclosed message 7413 (e.g., "1.1"). If not present, the version can be 7415 determined from the first line of the body. 7416 msgtype: The message type -- "request" or "response". If not 7417 present, the type can be determined from the first 7419 line of the body. 7420 Encoding considerations: only "7bit", "8bit", or "binary" are 7421 permitted 7422 Security considerations: none 7424 Media Type name: application 7425 Media subtype name: http 7426 Required parameters: none 7427 Optional parameters: version, msgtype 7428 version: The HTTP-Version number of the enclosed messages 7429 (e.g., "1.1"). If not present, the version can be 7431 determined from the first line of the body. 7432 msgtype: The message type -- "request" or "response". If not 7434 present, the type can be determined from the first 7435 line of the body. 7436 Encoding considerations: HTTP messages enclosed by this type 7438 are in "binary" format; use of an appropriate 7439 Content-Transfer-Encoding is required when 7440 transmitted via E-mail. 7441 Security considerations: none 7443 17.2 IANA Considerations - Internet Media Type multipart/byteranges 7445 When an HTTP 206 (Partial Content) response message includes the 7446 content of multiple ranges (a response to a request for multiple non- 7447 overlapping ranges), these are transmitted as a multipart message- 7448 body. The media type for this purpose is called 7449 "multipart/byteranges". 7451 The multipart/byteranges media type includes two or more parts, each 7452 with its own Content-Type and Content-Range fields. The required 7453 boundary parameter specifies the boundary string used to separate 7454 each body-part. 7456 Media Type name: multipart 7457 Media subtype name: byteranges 7458 Required parameters: boundary 7459 Optional parameters: none 7460 Encoding considerations: only "7bit", "8bit", or "binary" are 7461 permitted 7462 Security considerations: none 7464 For example: 7466 HTTP/1.1 206 Partial Content 7467 Date: Wed, 15 Nov 1995 06:25:24 GMT 7468 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 7469 Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 7471 --THIS_STRING_SEPARATES 7472 Content-type: application/pdf 7473 Content-range: bytes 500-999/8000 7475 ...the first range... 7476 --THIS_STRING_SEPARATES 7477 Content-type: application/pdf 7478 Content-range: bytes 7000-7999/8000 7480 ...the second range 7481 --THIS_STRING_SEPARATES-- 7483 Notes: 7485 1) Additional CRLFs may precede the first boundary string in the 7486 entity. 7488 2) Although RFC 2046 [N8] permits the boundary string to be quoted, 7489 some existing implementations handle a quoted boundary string 7490 incorrectly. 7492 3) A number of browsers and servers were coded to an early draft of 7493 the byteranges specification to use a media type of multipart/x- 7494 byteranges, which is almost, but not quite compatible with the 7495 version documented in HTTP/1.1. 7497 17.3 Tolerant Applications 7499 Although this document specifies the requirements for the generation 7500 of HTTP/1.1 messages, not all applications will be correct in their 7501 implementation. We therefore recommend that operational applications 7502 be tolerant of deviations whenever those deviations can be 7503 interpreted unambiguously. 7505 Clients SHOULD be tolerant in parsing the Status-Line and servers 7506 tolerant when parsing the Request-Line. In particular, they SHOULD 7507 accept any amount of SP or HT characters between fields, even though 7508 only a single SP is required. 7510 The line terminator for message-header fields is the sequence CRLF. 7511 However, we recommend that applications, when parsing such headers, 7512 recognize a single LF as a line terminator and ignore the leading CR. 7513 The character set of an entity-body SHOULD be labeled as the lowest 7514 common denominator of the character codes used within that body, with 7515 the exception that not labeling the entity is preferred over labeling 7516 the entity with the labels US-ASCII or ISO-8859-1. See section 3.7.1 7517 and 0. 7519 Additional rules for requirements on parsing and encoding of dates 7520 and other potential problems with date encodings include: 7522 o HTTP/1.1 clients and caches SHOULD assume that an RFC-850 date 7523 which appears to be more than 50 years in the future is in fact in 7524 the past (this helps solve the "year 2000" problem). 7525 o An HTTP/1.1 implementation MAY internally represent a parsed 7526 Expires date as earlier than the proper value, but MUST NOT 7527 internally represent a parsed Expires date as later than the proper 7528 value. 7529 o All expiration-related calculations MUST be done in GMT. The local 7530 time zone MUST NOT influence the calculation or comparison of an 7531 age or expiration time. 7532 o If an HTTP header incorrectly carries a date value with a time zone 7533 other than GMT, it MUST be converted into GMT using the most 7534 conservative possible conversion. 7536 17.4 Differences Between HTTP Entities and RFC 2045 Entities 7538 HTTP/1.1 uses many of the constructs defined for Internet Mail (RFC 7539 822 [N3]) and the Multipurpose Internet Mail Extensions (MIME [7]) to 7540 allow entities to be transmitted in an open variety of 7541 representations and with extensible mechanisms. However, RFC 2045 7542 discusses mail, and HTTP has a few features that are different from 7543 those described in RFC 2045. These differences were carefully chosen 7544 to optimize performance over binary connections, to allow greater 7545 freedom in the use of new media types, to make date comparisons 7546 easier, and to acknowledge the practice of some early HTTP servers 7547 and clients. 7549 This appendix describes specific areas where HTTP differs from RFC 7550 2045. Proxies and gateways to strict MIME environments SHOULD be 7551 aware of these differences and provide the appropriate conversions 7552 where necessary. Proxies and gateways from MIME environments to HTTP 7553 also need to be aware of the differences because some conversions 7554 might be required. 7556 17.4.1 MIME-Version 7558 HTTP is not a MIME-compliant protocol. However, HTTP/1.1 messages MAY 7559 include a single MIME-Version general-header field to indicate what 7560 version of the MIME protocol was used to construct the message. Use 7561 of the MIME-Version header field indicates that the message is in 7562 full compliance with the MIME protocol (as defined in RFC 2045[N1]). 7564 Proxies/gateways are responsible for ensuring full compliance (where 7565 possible) when exporting HTTP messages to strict MIME environments. 7567 MIME-Version = "MIME-Version" ":" 1*DIGIT "." 1*DIGIT 7569 MIME version "1.0" is the default for use in HTTP/1.1. However, 7570 HTTP/1.1 message parsing and semantics are defined by this document 7571 and not the MIME specification. 7573 17.4.2 Conversion to Canonical Form 7575 RFC 2045 [N1] requires that an Internet mail entity be converted to 7576 canonical form prior to being transferred, as described in section 4 7577 of RFC 2049 [I37]. Section 3.7.1 of this document describes the forms 7578 allowed for subtypes of the "text" media type when transmitted over 7579 HTTP. RFC 2046 requires that content with a type of "text" represent 7580 line breaks as CRLF and forbids the use of CR or LF outside of line 7581 break sequences. HTTP allows CRLF, bare CR, and bare LF to indicate a 7582 line break within text content when a message is transmitted over 7583 HTTP. 7585 Where it is possible, a proxy or gateway from HTTP to a strict MIME 7586 environment SHOULD translate all line breaks within the text media 7587 types described in section 3.7.1 of this document to the RFC 2049 7588 canonical form of CRLF. Note, however, that this might be complicated 7589 by the presence of a Content-Encoding and by the fact that HTTP 7590 allows the use of some character sets which do not use octets 13 and 7592 10 to represent CR and LF, as is the case for some multi-byte 7593 character sets. 7595 Implementors should note that conversion will break any cryptographic 7596 checksums applied to the original content unless the original content 7597 is already in canonical form. Therefore, the canonical form is 7598 recommended for any content that uses such checksums in HTTP. 7600 17.4.3 Conversion of Date Formats 7602 HTTP/1.1 uses a restricted set of date formats (section 3.3.1) to 7603 simplify the process of date comparison. Proxies and gateways from 7604 other protocols SHOULD ensure that any Date header field present in a 7605 message conforms to one of the HTTP/1.1 formats and rewrite the date 7606 if necessary. 7608 17.4.4 Introduction of Content-Encoding 7610 RFC 2045 does not include any concept equivalent to HTTP/1.1�s 7611 Content-Encoding header field. Since this acts as a modifier on the 7612 media type, proxies and gateways from HTTP to MIME-compliant 7613 protocols MUST either change the value of the Content-Type header 7614 field or decode the entity-body before forwarding the message. (Some 7615 experimental applications of Content-Type for Internet mail have used 7616 a media-type parameter of ";conversions=" to perform 7617 a function equivalent to Content-Encoding. However, this parameter is 7618 not part of RFC 2045.) 7620 17.4.5 No Content-Transfer-Encoding 7622 HTTP does not use the Content-Transfer-Encoding (CTE) field of RFC 7623 2045. Proxies and gateways from MIME-compliant protocols to HTTP MUST 7624 remove any CTE encoding prior to delivering the response message to 7625 an HTTP client. 7627 Proxies and gateways from HTTP to MIME-compliant protocols are 7628 responsible for ensuring that the message is in the correct format 7629 and encoding for safe transport on that protocol, where "safe 7630 transport" is defined by the limitations of the protocol being used. 7632 Such a proxy or gateway SHOULD label the data with an appropriate 7633 Content-Transfer-Encoding if doing so will improve the likelihood of 7634 safe transport over the destination protocol. 7636 17.4.6 Introduction of Transfer-Encoding 7638 HTTP/1.1 introduces the Transfer-Encoding header field (section 7639 14.41). Proxies/gateways MUST remove any transfer-coding prior to 7640 forwarding a message via a MIME-compliant protocol. 7642 A process for decoding the "chunked" transfer-coding (section 3.6) 7643 can be represented in pseudo-code as: 7645 length := 0 7646 read chunk-size, chunk-extension (if any) and CRLF 7647 while (chunk-size > 0) { 7648 read chunk-data and CRLF 7649 append chunk-data to entity-body 7650 length := length + chunk-size 7651 read chunk-size and CRLF 7652 } 7653 read entity-header 7654 while (entity-header not empty) { 7655 append entity-header to existing header fields 7656 read entity-header 7657 } 7658 Content-Length := length 7659 Remove "chunked" from Transfer-Encoding 7661 17.4.7 MHTML and Line Length Limitations 7663 HTTP implementations which share code with MHTML [I34] 7664 implementations need to be aware of MIME line length limitations. 7665 Since HTTP does not have this limitation, HTTP does not fold long 7666 lines. MHTML messages being transported by HTTP follow all 7667 conventions of MHTML, including line length limitations and folding, 7668 canonicalization, etc., since HTTP transports all message-bodies as 7669 payload (see section 3.7.2) and does not interpret the content or any 7670 MIME header lines that might be contained therein. 7672 17.5 Additional Features 7674 RFC 1945 and RFC 2068 document protocol elements used by some 7675 existing HTTP implementations, but not consistently and correctly 7676 across most HTTP/1.1 applications. Implementors are advised to be 7677 aware of these features, but cannot rely upon their presence in, or 7678 interoperability with, other HTTP/1.1 applications. Some of these 7679 describe proposed experimental features, and some describe features 7680 that experimental deployment found lacking that are now addressed in 7681 the base HTTP/1.1 specification. 7683 A number of other headers, such as Content-Disposition and Title, 7684 from SMTP and MIME are also often implemented (see RFC 2076 [I29]). 7686 17.5.1 Content-Disposition 7688 The Content-Disposition response-header field has been proposed as a 7689 means for the origin server to suggest a default filename if the user 7690 requests that the content is saved to a file. This usage is derived 7691 from the definition of Content-Disposition in RFC 1806 [I27]. 7693 content-disposition = "Content-Disposition" ":" 7694 disposition-type *( ";" disposition-parm ) 7695 disposition-type = "attachment" | disp-extension-token 7696 disposition-parm = filename-parm | disp-extension-parm 7697 filename-parm = "filename" "=" quoted-string 7698 disp-extension-token = token 7699 disp-extension-parm = token "=" ( token | quoted-string ) 7701 An example is 7703 Content-Disposition: attachment; filename="fname.ext" 7705 The receiving user agent SHOULD NOT respect any directory path 7706 information present in the filename-parm parameter, which is the only 7707 parameter believed to apply to HTTP implementations at this time. The 7708 filename SHOULD be treated as a terminal component only. 7710 If this header is used in a response with the application/octet- 7711 stream content-type, the implied suggestion is that the user agent 7713 should not display the response, but directly enter a "save response 7714 as..." dialog. 7716 See section 15.5 for Content-Disposition security issues. 7718 17.6 Compatibility with Previous Versions 7720 It is beyond the scope of a protocol specification to mandate 7721 compliance with previous versions. HTTP/1.1 was deliberately 7722 designed, however, to make supporting previous versions easy. It is 7723 worth noting that, at the time of composing this specification 7724 (1996), we would expect commercial HTTP/1.1 servers to: 7725 o recognize the format of the Request-Line for HTTP/0.9, 1.0, and 1.1 7726 requests; 7727 o understand any valid request in the format of HTTP/0.9, 1.0, or 7728 1.1; 7729 o respond appropriately with a message in the same major version used 7730 by the client. 7731 And we would expect HTTP/1.1 clients to: 7732 o recognize the format of the Status-Line for HTTP/1.0 and 1.1 7733 responses; 7734 o understand any valid response in the format of HTTP/0.9, 1.0, or 7735 1.1. 7736 For most implementations of HTTP/1.0, each connection is established 7737 by the client prior to the request and closed by the server after 7738 sending the response. Some implementations implement the Keep-Alive 7739 version of persistent connections described in section 19.7.1 of RFC 7740 2068 [I25]. 7742 17.6.1 Changes from HTTP/1.0 7744 This section summarizes major differences between versions HTTP/1.0 7745 and HTTP/1.1. 7747 17.6.1.1 Changes to Simplify Multi-homed Web Servers and Conserve IP 7748 Addresses 7750 The requirements that clients and servers support the Host request- 7751 header, report an error if the Host request-header (section 14.23) is 7752 missing from an HTTP/1.1 request, and accept absolute URIs (section 7753 5.1.2) are among the most important changes defined by this 7754 specification. 7756 Older HTTP/1.0 clients assumed a one-to-one relationship of IP 7757 addresses and servers; there was no other established mechanism for 7758 distinguishing the intended server of a request than the IP address 7759 to which that request was directed. The changes outlined above will 7760 allow the Internet, once older HTTP clients are no longer common, to 7761 support multiple Web sites from a single IP address, greatly 7762 simplifying large operational Web servers, where allocation of many 7763 IP addresses to a single host has created serious problems. The 7764 Internet will also be able to recover the IP addresses that have been 7765 allocated for the sole purpose of allowing special-purpose domain 7766 names to be used in root-level HTTP URLs. Given the rate of growth of 7767 the Web, and the number of servers already deployed, it is extremely 7768 important that all implementations of HTTP (including updates to 7769 existing HTTP/1.0 applications) correctly implement these 7770 requirements: 7772 o Both clients and servers MUST support the Host request-header. 7773 o A client that sends an HTTP/1.1 request MUST send a Host header. 7774 o Servers MUST report a 400 (Bad Request) error if an HTTP/1.1 7775 request does not include a Host request-header. 7776 o Servers MUST accept absolute URIs. 7778 17.6.2 Compatibility with HTTP/1.0 Persistent Connections 7780 Some clients and servers might wish to be compatible with some 7781 previous implementations of persistent connections in HTTP/1.0 7782 clients and servers. Persistent connections in HTTP/1.0 are 7783 explicitly negotiated as they are not the default behavior. HTTP/1.0 7784 experimental implementations of persistent connections are faulty, 7785 and the new facilities in HTTP/1.1 are designed to rectify these 7786 problems. The problem was that some existing 1.0 clients may be 7787 sending Keep-Alive to a proxy server that doesn�t understand 7788 Connection, which would then erroneously forward it to the next 7789 inbound server, which would establish the Keep-Alive connection and 7790 result in a hung HTTP/1.0 proxy waiting for the close on the 7791 response. The result is that HTTP/1.0 clients must be prevented from 7792 using Keep-Alive when talking to proxies. 7794 However, talking to proxies is the most important use of persistent 7795 connections, so that prohibition is clearly unacceptable. Therefore, 7796 we need some other mechanism for indicating a persistent connection 7797 is desired, which is safe to use even when talking to an old proxy 7798 that ignores Connection. Persistent connections are the default for 7799 HTTP/1.1 messages; we introduce a new keyword (Connection: close) for 7800 declaring non-persistence. See section 14.10. 7802 The original HTTP/1.0 form of persistent connections (the Connection: 7803 Keep-Alive and Keep-Alive header) is documented in RFC 2068. [I25] 7805 17.6.3 Changes from RFC 2616 7807 Section 3.1: Clarify that HTTP-Version is case sensitive. 7809 Section 3.2.3: Eliminate overlooked reference to "unsafe" characters. 7811 Section 3.4: Clarify contexts that charset is used in. 7813 Section 3.6: Remove reference to non-existant identity transfer- 7814 coding value tokens. 7816 Section 3.6.1: Clarification that the chunk length does not include 7818 the count of the octets in the chunk header and trailer. 7820 Section 3.7: Fix reference to media type registration procedure. 7821 Update reference for multipart/form-data (RFC 2388) 7823 Section 3.10: Update reference from RFC 1766 to RFC 3066. Fix BNF 7824 inconsistency with that document. 7826 Section 4.4: Remove reference to non-existant identity transfer- 7827 coding value tokens. 7829 Section 5.1.2: Fix BNF to add query, as RFC 2396 doesn't define it. 7831 Section 9.4: Clarify definition of POST. 7833 Section 10.3.2, 10.3.3, 10.3.8: failed to consider that there are 7834 many other request methods that are safe to automatically redirect, 7835 and further that the user agent is able to make that determination 7836 based on the request method semantics. In particular, the OPTIONS 7837 method is always safe to automatically redirect. Unfortunately, the 7838 paragraph was written long before there was OPTIONS, and was never 7839 updated to reflect the extensibility of methods. The same problem 7840 paragraph is found in sections 10.3.3 and 10.3.8. 7842 Section 13.5.1: Fix misspelled header. 7844 Section 13.10: Clarify denial of service attack avoidance 7845 requirement. 7847 Section 14.10: Clarify exactly when close connection options must be 7848 sent. 7850 Section 14.38: In the description of the Server header, the Via field 7851 was described as a SHOULD. The requirement was and is stated 7852 correctly in the description of the Via header, [section 14.45]. 7854 Section 14.31: Correct syntax of Location header to allow fragment, 7855 as referred symbol wasn�t what was expected, and add some 7856 clarifications as to when it would not be appropriate. 7858 Section 17: Update to RFC3066, BCP 47; Update to RFC2388; Update to 7859 RFC3232; add ISO-8859 �10 through �16, -12 doesn�t exist, 7860 apparently; Update to RFC 2617; Add RFC 2616 draft standard 7861 reference. 7863 Section 19.4.5: Remove reference to non-existant identity transfer- 7864 coding value tokens. 7866 18 References 7868 18.1 Normative References 7870 [N1] Freed, N., and N. Borenstein. "Multipurpose Internet Mail 7871 Extensions (MIME) Part One: Format of Internet Message Bodies." RFC 7872 2045, November 1996. 7874 [N2] Braden, R., "Requirements for Internet Hosts -- Communication 7875 Layers," STD 3, RFC 1123, October 1989. 7877 [N3] D. H. Crocker, "Standard for The Format of ARPA Internet Text 7878 Messages," STD 11, RFC 822, August 1982. 7880 [N4] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part 7881 Three: Message Header Extensions for Non-ASCII Text", RFC 2047, 7882 November 1996. 7884 [N5] Freed, N., Klensin, J., and Postel, J., "Mulitpurpose Internet Mail 7885 Extensions (MIME) Part Four: Registration Procedure", RFC 2048, 7886 November 1996. 7888 [N6] US-ASCII. Coded Character Set - 7-Bit American Standard Code for 7890 Information Interchange. Standard ANSI X3.4-1986, ANSI, 1986. 7892 [N7] ISO-8859. International Standard -- Information Processing -- 7893 8-bit Single-Byte Coded Graphic Character Sets -- 7894 Part 1: Latin alphabet No. 1, ISO-8859-1:1987. 7895 Part 2: Latin alphabet No. 2, ISO-8859-2, 1987. 7896 Part 3: Latin alphabet No. 3, ISO-8859-3, 1988. 7897 Part 4: Latin alphabet No. 4, ISO-8859-4, 1988. 7898 Part 5: Latin/Cyrillic alphabet, ISO-8859-5, 1988. 7899 Part 6: Latin/Arabic alphabet, ISO-8859-6, 1987. 7900 Part 7: Latin/Greek alphabet, ISO-8859-7, 1987. 7901 Part 8: Latin/Hebrew alphabet, ISO-8859-8, 1988. 7902 Part 9: Latin alphabet No. 5, ISO-8859-9, 1990. 7903 Part 10: Latin alphabet No. 6, ISO-8859-10, 1998. 7904 Part 11: Latin/Thai alphabet, ISO-8859-11, 2001. 7906 Part 13: Latin alphabet No. 7, ISO-8859-13, 1998. 7907 Part 14: Latin alphabet No. 8 (Celtic), ISO-8859-14, 1998. 7908 Part 15: Latin alphabet No. 9, ISO-8859-15, 1999. 7909 Part 16: Latin alphabet No. 10, ISO-8859-16, 2001. 7911 [N8] Freed, N., and N. Borenstein. "Multipurpose Internet Mail 7912 Extensions (MIME) Part Two: Media Types." RFC 2046, November 1996. 7914 [N9] Berners-Lee, T., Fielding, R., and L. Masinter,"Uniform Resource 7915 Identifiers (URI): Generic Syntax and Semantics," RFC 2396, August 7916 1998. 7918 [N10] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, 7919 P., Luotonen, A., Sink, E., and L. Stewart, "HTTP Authentication: 7920 Basic and Digest Access Authentication," RFC 2617, June 1999. 7922 18.2 Informative References 7924 [I1] Alvestrand, H., "Tags for the Identification of Languages", RFC 7925 3066, BCP 47, January 2001. 7927 [I2] Anklesaria, F., McCahill, M., Lindner, P., Johnson, D., Torrey, D., 7928 and B. Alberti. "The Internet Gopher Protocol (a distributed document 7929 search and retrieval protocol)", RFC 1436, March 1993. 7931 [I3] Berners-Lee, T., "Universal Resource Identifiers in WWW," RFC 1630, 7932 June 1994. 7934 [I4] Berners-Lee, T., Masinter, L., and M. McCahill. "Uniform Resource 7935 Locators (URL)," RFC 1738, December 1994. 7937 [I5] Berners-Lee, T. and D. Connolly. "Hypertext Markup Language - 2.0," 7938 RFC 1866, November 1995. 7940 [I6] Berners-Lee, T., Fielding, R. and H. Frystyk. "Hypertext Transfer 7941 Protocol -- HTTP/1.0," RFC 1945, May 1996. 7943 [I7] Davis, F., Kahle, B., Morris, H., Salem, J., Shen, T., Wang, R., 7944 Sui, J., and M. Grinbaum, "WAIS Interface Protocol Prototype 7945 Functional Specification." (v1.5), Thinking Machines Corporation, 7946 April 1990. 7948 [I8] Fielding, R., "Relative Uniform Resource Locators," RFC 1808, June 7949 1995. 7951 [I9] Horton, M., and R. Adams. "Standard for Interchange of USENET 7952 Messages," RFC 1036, December 1987. 7954 [I10] Kantor, B. and P. Lapsley. "Network News Transfer Protocol," RFC 7955 977, February 1986. 7957 [I11] L. Masinter. " Returning Values from Forms: multipart/form-data," 7958 RFC 2388, August 1998. 7960 [I12] Postel, J., "Simple Mail Transfer Protocol," STD 10, RFC 821, 7961 August 1982. 7963 [I13] Postel, J. and J. Reynolds. "File Transfer Protocol," STD 9, RFC 7964 959, October 1985. 7966 [I14] Reynolds, J. "Assigned Numbers : RFC 1700 is Replaced by an On- 7967 line Database," RFC 3232, January 2002. 7969 [I15] Sollins, K. and L. Masinter. "Functional Requirements for Uniform 7970 Resource Names," RFC 1737, December 1994. 7972 [I16] Meyers, J., and M. Rose. "The Content-MD5 Header Field," RFC 1864, 7973 October 1995. 7975 [I17] Carpenter, B. and Y. Rekhter. "Renumbering Needs Work," RFC 1900, 7976 February 1996. 7978 [I18] Deutsch, P., "GZIP file format specification version 4.3,." RFC 7979 1952, May 1996. 7981 [I19] Venkata N. Padmanabhan, and Jeffrey C. Mogul. "Improving HTTP 7982 Latency", Computer Networks and ISDN Systems, v. 28, pp. 25-35, Dec. 7983 1995. Slightly revised version of paper in Proc. 2nd International 7984 WWW Conference '94: Mosaic and the Web, Oct. 1994, which is available 7985 at 7986 http://www.ncsa.uiuc.edu/SDG/IT94/Proceedings/DDay/mogul/HTTPLatency. 7987 html. 7989 [I20] Joe Touch, John Heidemann, and Katia Obraczka. "Analysis of HTTP 7990 Performance", , ISI 7991 Research Report ISI/RR-98-463, (original report dated Aug. 1996), 7992 USC/Information Sciences Institute, August 1998. 7994 [I21] Mills, D., "Network Time Protocol (Version 3) Specification, 7995 Implementation and Analysis." RFC 1305, March 1992. 7997 [I22] Deutsch, P., "DEFLATE Compressed Data Format Specification version 7998 1.3." RFC 1951, May 1996. 8000 [I23] S. Spero, "Analysis of HTTP Performance Problems," 8001 http://sunsite.unc.edu/mdma-release/http-prob.html. 8003 [I24] Deutsch, P. and J. Gailly. "ZLIB Compressed Data Format 8004 Specification version 3.3," RFC 1950, May 1996. 8006 [I25] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., and T. Berners- 8007 Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, January 8008 1997. 8010 [I26] Bradner, S., "Key words for use in RFCs to Indicate Requirement 8012 Levels," RFC 2119, March 1997. 8014 [I27] Troost, R., and Dorner, S., "Communicating Presentation 8015 Information in Internet Messages: The Content-Disposition Header," 8016 RFC 1806, June 1995. 8018 [I28] Mogul, J.C., Fielding, R., Gettys, J., and H. Frystyk,., "Use and 8019 Interpretation of HTTP Version Numbers", RFC 2145, May 1997. 8021 [I29] Palme, J, "Common Internet Message Headers," RFC 2076, February 8022 1997. 8024 [I30] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO- 8025 10646," RFC 2279, January 1998. 8027 [I31] Nielsen, H.F., Gettys, J., Baird-Smith, A., Prud�hommeaux, E., 8028 Lie, H., and C. Lilley. "Network Performance Effects of HTTP/1.1, 8029 CSS1, and PNG," Proceedings of ACM SIGCOMM '97, Cannes France, 8030 September 1997. 8032 [I32] Alvestrand, H. T., "IETF Policy on Character Sets and Languages," 8033 RFC 2277, BCP 18, January 1998. 8035 [I33] Luotonen, A., "Tunneling TCP based protocols through Web proxy 8036 servers," Work in Progress. 8038 [I34] Palme, J., and A. Hopmann, "MIME E-mail Encapsulation of Aggregate 8039 Documents, such as HTML (MHTML)," RFC 2110, March 1997 8041 [I35] Bradner, S., "The Internet Standards Process -- Revision 3," BCP 8042 9, RFC 2026, Harvard University, October 1996. 8044 [I36] Masinter, L., "Hyper Text Coffee Pot Control Protocol 8045 (HTCPCP/1.0)," RFC 2324, April 1998. 8047 [I37] Freed, N., and N. Borenstein, "Multipurpose Internet Mail 8048 Extensions (MIME) Part Five: Conformance Criteria and Examples," RFC 8049 2049, November 1996. 8051 [I38] Troost, R., Dorner, S., and K. Moore, "Communicating Presentation 8052 Information in Internet Messages: The Content-Disposition Header 8053 Field," RFC 2183, August 1997. 8055 [I39] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., and T. Berners- 8056 Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June, 1999. 8058 [I40] Klyne, G., Nottingham, M. and Mogul, J., "Registration procedures 8059 for message header fields", Work-in-progress. 8061 19 Authors� Addresses 8063 Roy T. Fielding 8064 Chief Scientist 8065 Day Software 8066 5251 California Avenue 8067 Suite 110, 8068 Irvine, CA 92612-3074, USA 8070 EMail: roy.fielding@day.com 8072 James Gettys 8073 HP Labs, Cambridge Research Laboratory 8074 Hewlett-Packard Company 8075 One Cambridge Center 8076 Cambride, MA 02138 8078 EMail: Jim.Gettys@hp.com 8080 Jeffrey C. Mogul 8081 HP Labs, Large Scale Systems Group 8082 Hewlett-Packard Company 8083 1501 Page Mill Road, MS 1177 8084 Palo Alto, California, 94304, USA 8086 EMail: JeffMogul@acm.org 8088 Henrik Frystyk Nielsen 8089 Microsoft Corporation 8090 1 Microsoft Way 8091 Redmond, WA 98052, USA 8093 EMail: henrikn@microsoft.com 8095 Larry Masinter 8096 Adobe Systems, Incorporated. 8097 345 Park Ave 8098 San Jose, CA 95110, USA 8100 EMail: LMM2acm.org 8101 URI: http://larry.masinter.net 8103 Paul J. Leach 8104 Microsoft Corporation 8105 1 Microsoft Way 8106 Redmond, WA 98052, USA 8108 EMail: paulle@microsoft.com 8109 Tim Berners-Lee 8110 Director, World Wide Web Consortium 8111 MIT Laboratory for Computer Science 8112 545 Technology Square 8113 Cambridge, MA 02139, USA 8115 Fax: +1 (617) 258 8682 8116 EMail: timbl@w3.org 8117 20 Full Copyright Statement 8119 Copyright (C) The Internet Society (2003). All Rights Reserved. 8121 This document and translations of it may be copied and furnished to 8122 others, and derivative works that comment on or otherwise explain it 8123 or assist in its implementation may be prepared, copied, published 8124 and distributed, in whole or in part, without restriction of any 8125 kind, provided that the above copyright notice and this paragraph are 8126 included on all such copies and derivative works. However, this 8127 document itself may not be modified in any way, such as by removing 8128 the copyright notice or references to the Internet Society or other 8129 Internet organizations, except as needed for the purpose of 8130 developing Internet standards in which case the procedures for 8131 copyrights defined in the Internet Standards process must be 8132 followed, or as required to translate it into languages other than 8133 English. 8135 The limited permissions granted above are perpetual and will not be 8136 revoked by the Internet Society or its successors or assigns. 8138 This document and the information contained herein is provided on an 8139 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 8140 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 8141 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 8142 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 8143 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 8145 20.1 Acknowledgement 8147 Funding for the RFC Editor function is currently provided by the 8148 Internet Society. 8150 21 Index 8152 While some care was taken producing this index, there is no guarantee 8153 that all occurrences of an index term have been entered into the 8154 index. Bold face italic is used for the definition of a term. 8156 "literal", 14 414, 18, 36, 60 8157 #rule, 14 415, 36, 61, 102 8158 (rule1 rule2), 14 416, 36, 61, 106, 107, 120 8159 *rule, 14 417, 36, 61, 109 8160 ; comment, 14 4xx Client Error Status Codes, 57 8161 [rule], 14 500, 36, 61, 62, 108 8162 <">, 15 501, 23, 32, 36, 48, 61 8163 100, 36, 42, 43, 44, 50, 51, 85, 502, 36, 62 8164 108, 109 503, 36, 62, 108, 122 8165 101, 36, 51, 108, 124 504, 36, 62, 99 8166 1xx Informational Status Codes, 505, 36, 62 8167 50 5xx Server Error Status Codes, 61 8168 200, 36, 46, 48, 49, 50, 51, 52, abs_path, 18, 33 8169 53, 56, 79, 84, 98, 107, 113, absoluteURI, 18, 32, 33, 34, 104, 8170 115, 121 117, 121 8171 201, 36, 48, 52, 117 Accept, 24, 34, 63, 64, 67, 87, 8172 202, 36, 49, 52 89, 90, 132 8173 203, 36, 52, 79 acceptable-ranges, 91 8174 204, 30, 36, 48, 49, 52, 53 Accept-Charset, 20, 34, 64, 88, 8175 205, 36, 53 89 8176 206, 36, 53, 79, 81, 82, 84, 106, Accept-Encoding, 21, 22, 34, 63, 8177 115, 120, 121, 137 64, 89, 90 8178 2xx, 114 accept-extension, 87 8179 2xx Successful Status Codes, 51 Accept-Language, 26, 34, 63, 64, 8180 300, 36, 54, 64, 79 90, 91, 128, 132 8181 301, 36, 49, 54, 55, 79, 125 accept-params, 87, 123 8182 302, 36, 55, 57, 79, 125 Accept-Ranges, 37, 91 8183 303, 36, 48, 55, 125 Access Authentication, 62 8184 304, 30, 36, 56, 66, 67, 74, 78, Basic and Digest. See [43] 8185 81, 82, 83, 98, 113, 114, 121 Acknowledgements, 135 8186 305, 36, 56, 66, 125 age, 11 8187 306, 56 Age, 37, 70, 71, 72, 92 8188 307, 36, 55, 57, 79 age-value, 92 8189 3xx Redirection Status Codes, 54 Allow, 32, 38, 46, 58, 92 8190 400, 31, 34, 36, 37, 57, 111, 143 ALPHA, 13, 15 8191 401, 36, 57, 59, 92, 130 ANSI X3.4-1986, 15, 145 8192 402, 36, 58 asctime-date, 19 8193 403, 36, 58 attribute, 22 8194 404, 36, 58, 60 authority, 18, 33 8195 405, 32, 36, 58, 92 Authorization, 34, 57, 58, 79, 8196 406, 36, 58, 59, 64, 87, 89, 90 92, 93, 95, 119 8197 407, 36, 59, 118 Backus-Naur Form, 13 8198 408, 36, 59 Basic Authentication. See [43] 8199 409, 36, 59 BCP 18, 148 8200 410, 36, 59, 60, 79 BCP 9, 148 8201 411, 31, 36, 60 byte-content-range-spec, 105, 106 8202 412, 36, 60, 112, 114, 116 byte-range, 119 8203 413, 36, 60 byte-range-resp-spec, 106 8204 byte-range-set, 119, 120 must-revalidate, 93, 94, 97, 99 8205 byte-range-spec, 61, 107, 119, no-cache, 66, 74, 94, 95, 96, 8206 120 98, 99, 118 8207 byte-ranges-specifier, 119 no-store, 66, 94, 95 8208 bytes, 91 no-transform, 94, 100, 102 8209 bytes-unit, 28 only-if-cached, 94, 99 8210 cachable, 10 private, 79, 94, 95, 96, 101 8211 cache, 10 proxy-revalidate, 79, 94, 100 8212 Cache public, 68, 79, 93, 94, 95, 96, 8213 cachability of responses, 79 100 8214 calculating the age of a s-maxage, 73, 79, 93, 94, 97 8215 response, 70 cache-directive, 94, 101, 118 8216 combining byte ranges, 82 cache-request-directive, 66, 94 8217 combining headers, 81 Changes from HTTP/1.0. See RFC 8218 combining negotiated responses, 1945 and RFC 2068 8219 83 Host requirement, 143 8220 constructing responses, 80 CHAR, 15 8221 correctness, 66 charset, 20, 88 8222 disambiguating expiration chunk, 23 8223 values, 73 chunk-data, 23 8224 disambiguating multiple chunked, 123, 124 8225 responses, 73 Chunked-Body, 23 8226 entity tags used as cache chunk-extension, 23 8227 validators, 75 chunk-ext-name, 23 8228 entry validation, 74 chunk-ext-val, 23 8229 errors or incomplete responses, chunk-size, 23 8230 84 client, 9 8231 expiration calculation, 72 codings, 89 8232 explicit expiration time, 69 comment, 16, 125, 127 8233 GET and HEAD cannot affect Compatibility 8234 caching, 84 missing charset, 21 8235 heuristic expiration, 70 multipart/x-byteranges, 138 8236 history list behavior, 86 Compatibility with previous HTTP 8237 invalidation cannot be complete, versions, 142 8238 85 CONNECT, 32, 33. See [44]. 8239 Last-Modified values used as connection, 8 8240 validators, 75 Connection, 31, 40, 41, 80, 101, 8241 mechanisms, 68 102, 123, 125, 143, 144 8242 replacement of cached responses, close, 40, 101, 102, 144 8243 86 Keep-Alive, 144. See RFC 2068 8244 shared and non-shared, 84 connection-token, 101, 102 8245 Warnings, 67 Content Codings 8246 weak and strong cache compress, 21 8247 validators, 75 deflate, 21 8248 write-through mandatory, 85 gzip, 21 8249 Cache-Control, 31, 48, 53, 55, identity, 22 8250 56, 57, 68, 69, 70, 72, 73, 74, content negotiation, 9 8251 79, 81, 84, 93, 94, 95, 96, 97, Content Negotiation, 63 8252 98, 101, 110, 118 content-cncoding, 102 8253 cache-extension, 94 content-coding, 21, 22, 23, 25, 8254 extensions, 100 63, 89, 90, 102, 124, 129 8255 max-age, 70, 72, 73, 74, 79, 94, new tokens SHOULD be registered 8256 96, 97, 98, 99, 110 with IANA, 22 8257 max-stale, 68, 94, 97, 99 qvalues used with, 90 8258 min-fresh, 94, 97 content-disposition, 142 8259 Content-Disposition, 134, 141, Entity body, 38 8260 142, 148 Entity Tags, 27, 75 8261 Content-Encoding, 21, 22, 38, 81, entity-body, 38 8262 102, 105, 129, 140 entity-header, 32, 35, 38 8263 Content-Language, 26, 38, 102, Entity-header fields, 37 8264 103, 128 entity-length, 39, 81 8265 Content-Length, 30, 31, 38, 42, entity-tag, 27, 114, 115 8266 46, 47, 53, 60, 81, 84, 103, ETag, 27, 37, 47, 52, 53, 56, 75, 8267 106, 124, 141 81, 83, 109, 114 8268 Content-Location, 38, 53, 56, 81, Expect, 34, 42, 43, 44, 50, 61, 8269 83, 85, 104, 117, 133 109 8270 Content-MD5, 38, 47, 81, 104, expectation, 109 8271 105, 147 expectation-extension, 109 8272 Content-Range, 53, 79, 105 expect-params, 109 8273 content-range-spec, 105 Expires, 38, 48, 53, 55, 56, 57, 8274 Content-Transfer-Encoding, 22, 70, 72, 73, 79, 81, 96, 97, 99, 8275 105, 140 108, 110, 139 8276 Content-Type, 20, 21, 24, 38, 46, explicit expiration time, 11 8277 50, 52, 53, 54, 58, 59, 81, 102, extension-code, 36 8278 106, 107, 129, 137, 140 extension-header, 38 8279 CR, 15, 25, 32, 35, 36, 138, 140 extension-pragma, 118 8280 CRLF, 13, 15, 23, 24, 25, 28, 32, field-content, 29 8281 35, 105, 138, 140 field-name, 29 8282 ctext, 16 field-value, 29 8283 CTL, 15 filename-parm, 142 8284 Date, 31, 53, 56, 70, 73, 74, 76, first-byte-pos, 61, 106, 107, 8285 77, 79, 82, 84, 86, 96, 107, 119, 120 8286 108, 110, 116, 130, 140 first-hand, 10 8287 date1, 19 fresh, 11 8288 date2, 19 freshness lifetime, 11 8289 date3, 19 freshness_lifetime, 72 8290 DELETE, 32, 45, 49, 85 From, 34, 41, 110, 111, 131, 132 8291 delta-seconds, 20, 122 gateway, 10 8292 Differences between MIME and General Header Fields, 31 8293 HTTP, 139 general-header, 31, 32, 35 8294 canonical form, 139 generic-message, 28 8295 Content-Encoding, 140 GET, 18, 32, 33, 45, 47, 51, 53, 8296 Content-Transfer-Encoding, 140 54, 55, 56, 57, 60, 74, 76, 77, 8297 date formats, 140 84, 85, 92, 103, 107, 112, 113, 8298 MIME-Version, 139 114, 115, 121, 132 8299 Transfer-Encoding, 141 HEAD, 30, 32, 45, 47, 51, 54, 55, 8300 Digest Authentication, 80. See 57, 58, 61, 84, 85, 92, 103, 8301 [43] 107, 114 8302 DIGIT, 13, 14, 15, 17, 19, 26, Headers 8303 117, 139 end-to-end, 80, 81, 82, 101, 109 8304 disp-extension-token, 142 hop-by-hop, 11, 80 8305 disposition-parm, 142 non-modifiable headers, 80 8306 disposition-type, 142 Henrik Frystyk Nielsen, 149 8307 DNS, 133 heuristic expiration time, 11 8308 HTTP applications MUST obey TTL HEX, 16, 18, 23 8309 information, 133 Hop-by-hop headers, 80 8310 downstream, 11 host, 18, 127, 128 8311 End-to-end headers, 80 Host, 33, 34, 45, 111, 143 8312 entity, 9 HT, 13, 15, 16, 28, 138 8313 Entity, 37 http_URL, 18 8314 HTTP-date, 19, 107, 108, 110, Media Types, 24 8315 113, 115, 116, 122, 128 media-range, 87 8316 HTTP-message, 28 media-type, 24, 102, 105, 129 8317 HTTP-Version, 17, 32, 35 message, 9 8318 IANA, 20, 21, 22, 24, 27, 87, 136 Message Body, 29 8319 identity, 22, 89, 90, 102 Message Headers, 28 8320 If-Match, 27, 34, 47, 78, 112, Message Length, 30 8321 114, 115, 121 Message Transmission 8322 If-Modified-Since, 34, 47, 76, Requirements, 42 8323 77, 78, 112, 113, 114, 115, 116, Message Types, 28 8324 121 message-body, 28, 29, 32, 35, 39 8325 If-None-Match, 27, 34, 47, 78, message-header, 28, 29, 38 8326 83, 112, 114, 115, 116, 121 Method, 32, 92 8327 If-Range, 27, 34, 47, 53, 61, 78, Method Definitions, 45 8328 107, 115, 121 Methods 8329 If-Unmodified-Since, 34, 47, 76, Idempotent, 45 8330 78, 114, 115, 116, 121 Safe and Idempotent, 45 8331 If-Unmodified-Since, 116 MIME, 8, 12, 20, 22, 25, 103, 8332 implied *LWS, 14 105, 135, 139, 140, 141, 145, 8333 inbound, 11 146 8334 instance-length, 106 multipart, 25 8335 ISO-10646, 148 MIME-Version, 139 8336 ISO-2022, 20 month, 19 8337 ISO-3166, 27 multipart/byteranges, 25, 30, 53, 8338 ISO-639, 27 61, 107, 137 8339 ISO-8859, 145 multipart/x-byteranges, 138 8340 ISO-8859-1, 15, 21, 25, 89, 128, MUST, 8 8341 138 MUST NOT, 8 8342 James Gettys, 149 N rule, 14 8343 Jeffrey C. Mogul, 149 name, 13 8344 Keep-Alive, 41, 80, 142, 143, non-shared cache, 84, 95, 101 8345 144. See RFC 2068 non-transparent proxy. See proxy: 8346 Language Tags, 26 non-transparent 8347 language-range, 90, 91 OCTET, 15, 38 8348 language-tag, 27, 90 opaque-tag, 27 8349 Larry Masinter, 149 OPTIONAL, 8 8350 last-byte-pos, 106, 119, 120 OPTIONS, 32, 33, 45, 46, 117, 118 8351 last-chunk, 23 origin server, 10 8352 Last-Modified, 11, 38, 47, 53, other-range-unit, 28 8353 70, 73, 75, 76, 77, 78, 79, 81, outbound, 11 8354 108, 113, 115, 116, 117 parameter, 22 8355 LF, 15, 25, 32, 35, 36, 138, 140 Paul J. Leach, 149 8356 lifetime, 11, 70, 72, 73, 92, 97, Persistent Connections, 39 8357 129 Overall Operation, 39 8358 LOALPHA, 15 Purpose, 39 8359 Location, 37, 48, 51, 54, 55, 56, Use of Connection Header, 40 8360 57, 85, 117, 133 Pipelining, 40 8361 LWS, 13, 15, 29 port, 18, 127, 128 8362 Max-Forwards, 35, 46, 50, 117, POST, 26, 28, 32, 43, 45, 47, 48, 8363 118 49, 51, 55, 60, 85, 108, 132 8364 MAY, 8 Pragma, 31, 93, 98, 118 8365 media type, 15, 21, 24, 25, 30, no-cache, 66, 74, 93, 118 8366 38, 52, 54, 58, 63, 87, 88, 100, pragma-directive, 118 8367 102, 103, 107, 137, 138, 139, primary-tag, 27 8368 140 product, 26, 125 8369 Product tokens, 26 response, 9 8370 product-version, 26 Response, 35 8371 protocol-name, 127 Response Header Fields, 37 8372 protocol-version, 127 response-header, 35, 37 8373 proxy, 10 Retry-After, 37, 60, 62, 122 8374 non-transparent, 10, 81, 100, Revalidation 8375 102 end-to-end, 98 8376 transparent, 10, 38, 80 end-to-end reload, 98 8377 Proxy-Authenticate, 37, 59, 80, end-to-end specific 8378 118, 119 revalidation, 98 8379 Proxy-Authorization, 35, 59, 80, end-to-end unspecific 8380 119 revalidation, 98 8381 pseudonym, 127, 128 RFC 1036, 19, 146 8382 public cache, 64 RFC 1123, 19, 107, 110, 145 8383 PUT, 32, 43, 45, 48, 49, 59, 85, RFC 1305, 147 8384 92, 108, 112, 115 RFC 1436, 146 8385 qdtext, 16 , 24 8386 Quality Values, 26 RFC 1630, 146 8387 query, 18 RFC 1737, 147 8388 quoted-pair, 16 RFC 1738, 17, 146 8389 quoted-string, 15, 16, 23, 27, , 27, 146 8390 29, 87, 94, 109, 118, 128, 142 RFC 1806, 134, 142, 148 8391 qvalue, 26, 87, 88, 89 RFC 1808, 17, 146 8392 Range, 27, 35, 38, 47, 48, 53, RFC 1864, 104, 105, 147 8393 61, 79, 81, 82, 106, 107, 113, RFC 1866, 146 8394 115, 119, 121, 137 RFC 1867, 147 8395 Range Units, 27 RFC 1900, 18, 147 8396 ranges-specifier, 106, 119, 120, RFC 1945, 8, 55, 141, 146 8397 121 RFC 1950, 21, 147 8398 range-unit, 28, 91 RFC 1951, 21, 147 8399 Reason-Phrase, 35, 36 RFC 1952, 147 8400 received-by, 127 RFC 2026, 148 8401 received-protocol, 127, 128 RFC 2045, 139, 140, 145 8402 RECOMMENDED, 8 RFC 2046, 25, 138, 139, 146 8403 References, 146 RFC 2047, 15, 128, 145 8404 Referer, 35, 121, 131, 132 RFC 2048, 145 8405 rel_path, 18, 84 RFC 2049, 139, 140, 148 8406 relativeURI, 18, 104, 121 RFC 2068, 2, 17, 39, 41, 43, 55, 8407 representation, 9 56, 136, 141, 142, 144, 148 8408 request, 9 RFC 2076, 141, 148 8409 Request, 32 RFC 2110, 148 8410 Request header fields, 34 RFC 2119, 8, 148 8411 request-header, 32, 34 RFC 2145, 16, 148 8412 Request-Line, 28, 32, 33, 48, 58, RFC 2277, 148 8413 138, 142 RFC 2279, 148 8414 Request-URI, 18, 32, 33, 34, 36, RFC 2324, 148 8415 37, 46, 47, 48, 49, 54, 55, 57, RFC 2388, 26 8416 58, 59, 60, 83, 85, 92, 102, RFC 2396, 17, 146 8417 104, 117, 118, 121, 122, 130, RFC 2616, 148 8418 132, 133 RFC 3066, 27 8419 REQUIRED, 8 RFC 3232, 147 8420 Requirements RFC 821, 147 8421 compliance, 8 RFC 822, 13, 19, 28, 107, 110, 8422 key words, 8 126, 135, 139, 145 8423 resource, 9 RFC 850, 19 8424 RFC 959, 147 subtype, 24 8425 RFC 977, 146 suffix-byte-range-spec, 119, 120 8426 rfc1123-date, 19 suffix-length, 120 8427 RFC-850, 138 T/TCP, 39 8428 rfc850-date, 19 t-codings, 123 8429 Roy T. Fielding, 149 TE, 23, 35, 80, 122, 123 8430 rule1 | rule2, 14 TEXT, 15 8431 Safe and Idempotent Methods, 45 Tim Berners-Lee, 149 8432 Security Considerations, 130 time, 19 8433 abuse of server logs, 130 token, 14, 15, 16, 20, 21, 22, 8434 Accept header, 132 23, 24, 26, 28, 29, 32, 87, 94, 8435 Accept headers can reveal ethnic 101, 109, 118, 125, 127, 142 8436 information, 132 Tolerant Applications, 138 8437 attacks based on path names, 132 bad dates, 138 8438 Authentication Credentials and should tolerate whitespace in 8439 Idle Clients, 134 request and status lines, 138 8440 be careful about personal tolerate LF and ignore CR in 8441 information, 130 line terminators, 138 8442 Content-Disposition Header, 134 use lowest common denominator of 8443 Content-Location header, 133 character set, 138 8444 encoding information in URI's, TRACE, 32, 45, 50, 51, 117, 118 8445 131 trailer, 23 8446 From header, 131, 132 Trailer, 23, 31, 124 8447 GET method, 132 trailers, 122, 123 8448 Location header, 133 Trailers, 80 8449 Location headers and spoofing, Transfer Encoding 8450 133 chunked, 22 8451 Proxies and Caching, 134 transfer-coding 8452 Referer header, 131, 132 chunked, 22 8453 sensitive headers, 130 deflate, 22 8454 Server header, 131 gzip, 22 8455 Transfer of Sensitive , 22 8456 Information, 131 transfer-coding, 22, 23, 29, 30, 8457 Via header, 131 31, 39, 105, 122, 123, 124, 141 8458 selecting request-headers, 83 chunked, 22, 23, 30, 42, 123, 8459 semantically transparent, 11 124, 141 8460 separators, 16 chunked REQUIRED, 31 8461 server, 9 compress, 22 8462 Server, 26, 37, 122, 127, 131 , 30 8463 SHALL, 8 trailers, 123 8464 SHALL NOT, 8 Transfer-Encoding, 22, 29, 30, 8465 shared caches, 84, 96 31, 38, 46, 80, 124, 141 8466 SHOULD, 8 transfer-extension, 22, 123 8467 SHOULD NOT, 8 transfer-length, 39, 81 8468 SP, 13, 15, 16, 19, 28, 29, 32, transparent 8469 35, 105, 128, 138 proxy, 81 8470 stale, 11 transparent proxy. See proxy: 8471 start-line, 28 transparent 8472 Status Code Definitions, 50 tunnel, 10 8473 Status-Code, 35, 36, 50 type, 24 8474 Status-Line, 28, 35, 37, 50, 138, UPALPHA, 15 8475 142 Upgrade, 31, 51, 80, 124, 125 8476 strong entity tag, 27 upstream, 11 8477 strong validators, 76 URI-reference, 18 8478 subtag, 27 US-ASCII, 15, 20, 138 8479 user agent, 9 111 Revalidation failed, 129 8480 User-Agent, 26, 35, 64, 125, 126, 112 Disconnected operation, 129 8481 127, 131 113 Heuristic expiration, 129 8482 validators, 11, 27, 68, 73, 74, 199 Miscellaneous warning, 129 8483 75, 76, 78, 82 214 Transformation applied, 129 8484 rules on use of, 77 299 Miscellaneous persistent 8485 value, 22 warning, 129 8486 variant, 9 warning-value, 128, 129, 130 8487 Vary, 37, 53, 56, 64, 83, 112, warn-text, 128, 129 8488 115, 126, 132 weak, 27 8489 Via, 31, 50, 122, 126, 127, 131 weak entity tag, 27 8490 warn-agent, 128 weak validators, 75, 76 8491 warn-code, 82, 128 weekday, 19 8492 warn-codes, 67 wkday, 19 8493 warn-date, 128, 129, 130 WWW-Authenticate, 37, 57, 119, 8494 Warning, 31, 66, 67, 69, 73, 79, 130 8495 81, 82, 97, 128, 129, 130 x-compress, 90 8496 Warnings x-gzip, 90 8497 110 Response is stale, 129