idnits 2.17.1 draft-ietf-httpbis-p6-cache-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 30. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 2292. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2303. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2310. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2316. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 24, 2008) is 5905 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-8859-1' == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-02 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-02 == Outdated reference: A later version (-20) exists of draft-ietf-httpbis-p3-payload-02 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-02 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-02 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-02 -- Obsolete informational reference (is this intentional?): RFC 1305 (Obsoleted by RFC 5905) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Fielding, Ed. 3 Internet-Draft Day Software 4 Obsoletes: 2616 (if approved) J. Gettys 5 Intended status: Standards Track One Laptop per Child 6 Expires: August 27, 2008 J. Mogul 7 HP 8 H. Frystyk 9 Microsoft 10 L. Masinter 11 Adobe Systems 12 P. Leach 13 Microsoft 14 T. Berners-Lee 15 W3C/MIT 16 Y. Lafon, Ed. 17 W3C 18 J. Reschke, Ed. 19 greenbytes 20 February 24, 2008 22 HTTP/1.1, part 6: Caching 23 draft-ietf-httpbis-p6-cache-02 25 Status of this Memo 27 By submitting this Internet-Draft, each author represents that any 28 applicable patent or other IPR claims of which he or she is aware 29 have been or will be disclosed, and any of which he or she becomes 30 aware will be disclosed, in accordance with Section 6 of BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF), its areas, and its working groups. Note that 34 other groups may also distribute working documents as Internet- 35 Drafts. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 The list of current Internet-Drafts can be accessed at 43 http://www.ietf.org/ietf/1id-abstracts.txt. 45 The list of Internet-Draft Shadow Directories can be accessed at 46 http://www.ietf.org/shadow.html. 48 This Internet-Draft will expire on August 27, 2008. 50 Copyright Notice 52 Copyright (C) The IETF Trust (2008). 54 Abstract 56 The Hypertext Transfer Protocol (HTTP) is an application-level 57 protocol for distributed, collaborative, hypermedia information 58 systems. HTTP has been in use by the World Wide Web global 59 information initiative since 1990. This document is Part 6 of the 60 seven-part specification that defines the protocol referred to as 61 "HTTP/1.1" and, taken together, obsoletes RFC 2616. Part 6 defines 62 requirements on HTTP caches and the associated header fields that 63 control cache behavior or indicate cacheable response messages. 65 Editorial Note (To be removed by RFC Editor) 67 Discussion of this draft should take place on the HTTPBIS working 68 group mailing list (ietf-http-wg@w3.org). The current issues list is 69 at and related 70 documents (including fancy diffs) can be found at 71 . 73 This draft incorporates those issue resolutions that were either 74 collected in the original RFC2616 errata list 75 (), or which were agreed upon on the 76 mailing list between October 2006 and November 2007 (as published in 77 "draft-lafon-rfc2616bis-03"). 79 Table of Contents 81 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 82 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 83 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 84 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 7 85 2. Notational Conventions and Generic Grammar . . . . . . . . . . 8 86 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 87 3.1. Cache Correctness . . . . . . . . . . . . . . . . . . . . 8 88 3.2. Warnings . . . . . . . . . . . . . . . . . . . . . . . . . 9 89 3.3. Cache-control Mechanisms . . . . . . . . . . . . . . . . . 10 90 3.4. Explicit User Agent Warnings . . . . . . . . . . . . . . . 10 91 3.5. Exceptions to the Rules and Warnings . . . . . . . . . . . 11 92 3.6. Client-controlled Behavior . . . . . . . . . . . . . . . . 11 93 4. Expiration Model . . . . . . . . . . . . . . . . . . . . . . . 12 94 4.1. Server-Specified Expiration . . . . . . . . . . . . . . . 12 95 4.2. Heuristic Expiration . . . . . . . . . . . . . . . . . . . 13 96 4.3. Age Calculations . . . . . . . . . . . . . . . . . . . . . 13 97 4.4. Expiration Calculations . . . . . . . . . . . . . . . . . 15 98 4.5. Disambiguating Expiration Values . . . . . . . . . . . . . 16 99 4.6. Disambiguating Multiple Responses . . . . . . . . . . . . 17 100 5. Validation Model . . . . . . . . . . . . . . . . . . . . . . . 17 101 6. Response Cacheability . . . . . . . . . . . . . . . . . . . . 18 102 7. Constructing Responses From Caches . . . . . . . . . . . . . . 19 103 7.1. End-to-end and Hop-by-hop Headers . . . . . . . . . . . . 19 104 7.2. Non-modifiable Headers . . . . . . . . . . . . . . . . . . 20 105 7.3. Combining Headers . . . . . . . . . . . . . . . . . . . . 21 106 8. Caching Negotiated Responses . . . . . . . . . . . . . . . . . 22 107 9. Shared and Non-Shared Caches . . . . . . . . . . . . . . . . . 23 108 10. Errors or Incomplete Response Cache Behavior . . . . . . . . . 24 109 11. Side Effects of GET and HEAD . . . . . . . . . . . . . . . . . 24 110 12. Invalidation After Updates or Deletions . . . . . . . . . . . 24 111 13. Write-Through Mandatory . . . . . . . . . . . . . . . . . . . 25 112 14. Cache Replacement . . . . . . . . . . . . . . . . . . . . . . 26 113 15. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 26 114 16. Header Field Definitions . . . . . . . . . . . . . . . . . . . 27 115 16.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 116 16.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 27 117 16.2.1. What is Cacheable . . . . . . . . . . . . . . . . . . 29 118 16.2.2. What May be Stored by Caches . . . . . . . . . . . . 30 119 16.2.3. Modifications of the Basic Expiration Mechanism . . . 31 120 16.2.4. Cache Revalidation and Reload Controls . . . . . . . 33 121 16.2.5. No-Transform Directive . . . . . . . . . . . . . . . 35 122 16.2.6. Cache Control Extensions . . . . . . . . . . . . . . 36 123 16.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 37 124 16.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 38 125 16.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 126 16.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 39 128 17. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 129 18. Security Considerations . . . . . . . . . . . . . . . . . . . 42 130 19. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 42 131 20. References . . . . . . . . . . . . . . . . . . . . . . . . . . 42 132 20.1. Normative References . . . . . . . . . . . . . . . . . . . 42 133 20.2. Informative References . . . . . . . . . . . . . . . . . . 44 134 Appendix A. Compatibility with Previous Versions . . . . . . . . 44 135 A.1. Changes from RFC 2068 . . . . . . . . . . . . . . . . . . 44 136 A.2. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 44 137 Appendix B. Change Log (to be removed by RFC Editor before 138 publication) . . . . . . . . . . . . . . . . . . . . 44 139 B.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 45 140 B.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 45 141 B.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 45 142 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 143 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 48 144 Intellectual Property and Copyright Statements . . . . . . . . . . 51 146 1. Introduction 148 HTTP is typically used for distributed information systems, where 149 performance can be improved by the use of response caches, and 150 includes a number of elements intended to make caching work as well 151 as possible. Because these elements interact with each other, it is 152 useful to describe the caching design of HTTP separately. This 153 document defines aspects of HTTP/1.1 related to caching and reusing 154 response messages. 156 1.1. Purpose 158 An HTTP cache is a local store of response messages and the subsystem 159 that controls its message storage, retrieval, and deletion. A cache 160 stores cacheable responses in order to reduce the response time and 161 network bandwidth consumption on future, equivalent requests. Any 162 client or server may include a cache, though a cache cannot be used 163 by a server that is acting as a tunnel. 165 Caching would be useless if it did not significantly improve 166 performance. The goal of caching in HTTP/1.1 is to reuse a prior 167 response message to satisfy a current request. In some cases, the 168 existing response can be reused without the need for a network 169 request, reducing latency and network round-trips; we use an 170 "expiration" mechanism for this purpose (see Section 4). Even when a 171 new request is required, it is often possible to reuse all or parts 172 of the payload of a prior response to satisfy the request, thereby 173 reducing network bandwidth usage; we use a "validation" mechanism for 174 this purpose (see Section 5). 176 A cache behaves in a "semantically transparent" manner, with respect 177 to a particular response, when its use affects neither the requesting 178 client nor the origin server, except to improve performance. When a 179 cache is semantically transparent, the client receives exactly the 180 same response status and payload that it would have received had its 181 request been handled directly by the origin server. 183 In an ideal world, all interactions with an HTTP cache would be 184 semantically transparent. However, for some resources, semantic 185 transparency is not always necessary and can be effectively traded 186 for the sake of bandwidth scaling, disconnected operation, and high 187 availability. HTTP/1.1 allows origin servers, caches, and clients to 188 explicitly reduce transparency when necessary. However, because non- 189 transparent operation may confuse non-expert users and might be 190 incompatible with certain server applications (such as those for 191 ordering merchandise), the protocol requires that transparency be 192 relaxed 193 o only by an explicit protocol-level request when relaxed by client 194 or origin server 196 o only with an explicit warning to the end user when relaxed by 197 cache or client 199 Therefore, HTTP/1.1 provides these important elements: 201 1. Protocol features that provide full semantic transparency when 202 this is required by all parties. 204 2. Protocol features that allow an origin server or user agent to 205 explicitly request and control non-transparent operation. 207 3. Protocol features that allow a cache to attach warnings to 208 responses that do not preserve the requested approximation of 209 semantic transparency. 211 A basic principle is that it must be possible for the clients to 212 detect any potential relaxation of semantic transparency. 214 Note: The server, cache, or client implementor might be faced with 215 design decisions not explicitly discussed in this specification. 216 If a decision might affect semantic transparency, the implementor 217 ought to err on the side of maintaining transparency unless a 218 careful and complete analysis shows significant benefits in 219 breaking transparency. 221 1.2. Terminology 223 This specification uses a number of terms to refer to the roles 224 played by participants in, and objects of, HTTP caching. 226 cacheable 228 A response is cacheable if a cache is allowed to store a copy of 229 the response message for use in answering subsequent requests. 230 Even when a response is cacheable, there may be additional 231 constraints on whether a cache can use the cached copy for a 232 particular request. 234 first-hand 236 A response is first-hand if it comes directly and without 237 unnecessary delay from the origin server, perhaps via one or more 238 proxies. A response is also first-hand if its validity has just 239 been checked directly with the origin server. 241 explicit expiration time 243 The time at which the origin server intends that an entity should 244 no longer be returned by a cache without further validation. 246 heuristic expiration time 248 An expiration time assigned by a cache when no explicit expiration 249 time is available. 251 age 253 The age of a response is the time since it was sent by, or 254 successfully validated with, the origin server. 256 freshness lifetime 258 The length of time between the generation of a response and its 259 expiration time. 261 fresh 263 A response is fresh if its age has not yet exceeded its freshness 264 lifetime. 266 stale 268 A response is stale if its age has passed its freshness lifetime. 270 validator 272 A protocol element (e.g., an entity tag or a Last-Modified time) 273 that is used to find out whether a cache entry is an equivalent 274 copy of an entity. 276 1.3. Requirements 278 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 279 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 280 document are to be interpreted as described in [RFC2119]. 282 An implementation is not compliant if it fails to satisfy one or more 283 of the MUST or REQUIRED level requirements for the protocols it 284 implements. An implementation that satisfies all the MUST or 285 REQUIRED level and all the SHOULD level requirements for its 286 protocols is said to be "unconditionally compliant"; one that 287 satisfies all the MUST level requirements but not all the SHOULD 288 level requirements for its protocols is said to be "conditionally 289 compliant." 291 2. Notational Conventions and Generic Grammar 293 This specification uses the ABNF syntax defined in Section 2.1 of 294 [Part1] and the core rules defined in Section 2.2 of [Part1]: 295 [[abnf.dep: ABNF syntax and basic rules will be adopted from RFC 296 5234, see .]] 298 DIGIT = 299 DQUOTE = 300 SP = 302 quoted-string = 303 token = 305 The ABNF rules below are defined in other parts: 307 field-name = 308 HTTP-date = 309 port = 310 pseudonym = 311 uri-host = 313 3. Overview 315 3.1. Cache Correctness 317 A correct cache MUST respond to a request with the most up-to-date 318 response held by the cache that is appropriate to the request (see 319 Sections 4.5, 4.6, and 14) which meets one of the following 320 conditions: 322 1. It has been checked for equivalence with what the origin server 323 would have returned by revalidating the response with the origin 324 server (Section 5); 326 2. It is "fresh enough" (see Section 4). In the default case, this 327 means it meets the least restrictive freshness requirement of the 328 client, origin server, and cache (see Section 16.2); if the 329 origin server so specifies, it is the freshness requirement of 330 the origin server alone. If a stored response is not "fresh 331 enough" by the most restrictive freshness requirement of both the 332 client and the origin server, in carefully considered 333 circumstances the cache MAY still return the response with the 334 appropriate Warning header (see Sections 3.5 and 16.6), unless 335 such a response is prohibited (e.g., by a "no-store" cache- 336 directive, or by a "no-cache" cache-request-directive; see 337 Section 16.2). 339 3. It is an appropriate 304 (Not Modified), 305 (Use Proxy), or 340 error (4xx or 5xx) response message. 342 If the cache can not communicate with the origin server, then a 343 correct cache SHOULD respond as above if the response can be 344 correctly served from the cache; if not it MUST return an error or 345 warning indicating that there was a communication failure. 347 If a cache receives a response (either an entire response, or a 304 348 (Not Modified) response) that it would normally forward to the 349 requesting client, and the received response is no longer fresh, the 350 cache SHOULD forward it to the requesting client without adding a new 351 Warning (but without removing any existing Warning headers). A cache 352 SHOULD NOT attempt to revalidate a response simply because that 353 response became stale in transit; this might lead to an infinite 354 loop. A user agent that receives a stale response without a Warning 355 MAY display a warning indication to the user. 357 3.2. Warnings 359 Whenever a cache returns a response that is neither first-hand nor 360 "fresh enough" (in the sense of condition 2 in Section 3.1), it MUST 361 attach a warning to that effect, using a Warning general-header. The 362 Warning header and the currently defined warnings are described in 363 Section 16.6. The warning allows clients to take appropriate action. 365 Warnings MAY be used for other purposes, both cache-related and 366 otherwise. The use of a warning, rather than an error status code, 367 distinguish these responses from true failures. 369 Warnings are assigned three digit warn-codes. The first digit 370 indicates whether the Warning MUST or MUST NOT be deleted from a 371 stored cache entry after a successful revalidation: 373 1xx Warnings that describe the freshness or revalidation status of 374 the response, and so MUST be deleted after a successful 375 revalidation. 1xx warn-codes MAY be generated by a cache only when 376 validating a cached entry. It MUST NOT be generated by clients. 378 2xx Warnings that describe some aspect of the entity body or entity 379 headers that is not rectified by a revalidation (for example, a 380 lossy compression of the entity bodies) and which MUST NOT be 381 deleted after a successful revalidation. 383 See Section 16.6 for the definitions of the codes themselves. 385 HTTP/1.0 caches will cache all Warnings in responses, without 386 deleting the ones in the first category. Warnings in responses that 387 are passed to HTTP/1.0 caches carry an extra warning-date field, 388 which prevents a future HTTP/1.1 recipient from believing an 389 erroneously cached Warning. 391 Warnings also carry a warning text. The text MAY be in any 392 appropriate natural language (perhaps based on the client's Accept 393 headers), and include an OPTIONAL indication of what character set is 394 used. 396 Multiple warnings MAY be attached to a response (either by the origin 397 server or by a cache), including multiple warnings with the same code 398 number. For example, a server might provide the same warning with 399 texts in both English and Basque. 401 When multiple warnings are attached to a response, it might not be 402 practical or reasonable to display all of them to the user. This 403 version of HTTP does not specify strict priority rules for deciding 404 which warnings to display and in what order, but does suggest some 405 heuristics. 407 3.3. Cache-control Mechanisms 409 The basic cache mechanisms in HTTP/1.1 (server-specified expiration 410 times and validators) are implicit directives to caches. In some 411 cases, a server or client might need to provide explicit directives 412 to the HTTP caches. We use the Cache-Control header for this 413 purpose. 415 The Cache-Control header allows a client or server to transmit a 416 variety of directives in either requests or responses. These 417 directives typically override the default caching algorithms. As a 418 general rule, if there is any apparent conflict between header 419 values, the most restrictive interpretation is applied (that is, the 420 one that is most likely to preserve semantic transparency). However, 421 in some cases, cache-control directives are explicitly specified as 422 weakening the approximation of semantic transparency (for example, 423 "max-stale" or "public"). 425 The cache-control directives are described in detail in Section 16.2. 427 3.4. Explicit User Agent Warnings 429 Many user agents make it possible for users to override the basic 430 caching mechanisms. For example, the user agent might allow the user 431 to specify that cached entities (even explicitly stale ones) are 432 never validated. Or the user agent might habitually add "Cache- 433 Control: max-stale=3600" to every request. The user agent SHOULD NOT 434 default to either non-transparent behavior, or behavior that results 435 in abnormally ineffective caching, but MAY be explicitly configured 436 to do so by an explicit action of the user. 438 If the user has overridden the basic caching mechanisms, the user 439 agent SHOULD explicitly indicate to the user whenever this results in 440 the display of information that might not meet the server's 441 transparency requirements (in particular, if the displayed entity is 442 known to be stale). Since the protocol normally allows the user 443 agent to determine if responses are stale or not, this indication 444 need only be displayed when this actually happens. The indication 445 need not be a dialog box; it could be an icon (for example, a picture 446 of a rotting fish) or some other indicator. 448 If the user has overridden the caching mechanisms in a way that would 449 abnormally reduce the effectiveness of caches, the user agent SHOULD 450 continually indicate this state to the user (for example, by a 451 display of a picture of currency in flames) so that the user does not 452 inadvertently consume excess resources or suffer from excessive 453 latency. 455 3.5. Exceptions to the Rules and Warnings 457 In some cases, the operator of a cache MAY choose to configure it to 458 return stale responses even when not requested by clients. This 459 decision ought not be made lightly, but may be necessary for reasons 460 of availability or performance, especially when the cache is poorly 461 connected to the origin server. Whenever a cache returns a stale 462 response, it MUST mark it as such (using a Warning header) enabling 463 the client software to alert the user that there might be a potential 464 problem. 466 It also allows the user agent to take steps to obtain a first-hand or 467 fresh response. For this reason, a cache SHOULD NOT return a stale 468 response if the client explicitly requests a first-hand or fresh one, 469 unless it is impossible to comply for technical or policy reasons. 471 3.6. Client-controlled Behavior 473 While the origin server (and to a lesser extent, intermediate caches, 474 by their contribution to the age of a response) are the primary 475 source of expiration information, in some cases the client might need 476 to control a cache's decision about whether to return a cached 477 response without validating it. Clients do this using several 478 directives of the Cache-Control header. 480 A client's request MAY specify the maximum age it is willing to 481 accept of an unvalidated response; specifying a value of zero forces 482 the cache(s) to revalidate all responses. A client MAY also specify 483 the minimum time remaining before a response expires. Both of these 484 options increase constraints on the behavior of caches, and so cannot 485 further relax the cache's approximation of semantic transparency. 487 A client MAY also specify that it will accept stale responses, up to 488 some maximum amount of staleness. This loosens the constraints on 489 the caches, and so might violate the origin server's specified 490 constraints on semantic transparency, but might be necessary to 491 support disconnected operation, or high availability in the face of 492 poor connectivity. 494 4. Expiration Model 496 4.1. Server-Specified Expiration 498 HTTP caching works best when caches can entirely avoid making 499 requests to the origin server. The primary mechanism for avoiding 500 requests is for an origin server to provide an explicit expiration 501 time in the future, indicating that a response MAY be used to satisfy 502 subsequent requests. In other words, a cache can return a fresh 503 response without first contacting the server. 505 Our expectation is that servers will assign future explicit 506 expiration times to responses in the belief that the entity is not 507 likely to change, in a semantically significant way, before the 508 expiration time is reached. This normally preserves semantic 509 transparency, as long as the server's expiration times are carefully 510 chosen. 512 The expiration mechanism applies only to responses taken from a cache 513 and not to first-hand responses forwarded immediately to the 514 requesting client. 516 If an origin server wishes to force a semantically transparent cache 517 to validate every request, it MAY assign an explicit expiration time 518 in the past. This means that the response is always stale, and so 519 the cache SHOULD validate it before using it for subsequent requests. 520 See Section 16.2.4 for a more restrictive way to force revalidation. 522 If an origin server wishes to force any HTTP/1.1 cache, no matter how 523 it is configured, to validate every request, it SHOULD use the "must- 524 revalidate" cache-control directive (see Section 16.2). 526 Servers specify explicit expiration times using either the Expires 527 header, or the max-age directive of the Cache-Control header. 529 An expiration time cannot be used to force a user agent to refresh 530 its display or reload a resource; its semantics apply only to caching 531 mechanisms, and such mechanisms need only check a resource's 532 expiration status when a new request for that resource is initiated. 533 See Section 15 for an explanation of the difference between caches 534 and history mechanisms. 536 4.2. Heuristic Expiration 538 Since origin servers do not always provide explicit expiration times, 539 HTTP caches typically assign heuristic expiration times, employing 540 algorithms that use other header values (such as the Last-Modified 541 time) to estimate a plausible expiration time. The HTTP/1.1 542 specification does not provide specific algorithms, but does impose 543 worst-case constraints on their results. Since heuristic expiration 544 times might compromise semantic transparency, they ought to be used 545 cautiously, and we encourage origin servers to provide explicit 546 expiration times as much as possible. 548 4.3. Age Calculations 550 In order to know if a cached entry is fresh, a cache needs to know if 551 its age exceeds its freshness lifetime. We discuss how to calculate 552 the latter in Section 4.4; this section describes how to calculate 553 the age of a response or cache entry. 555 In this discussion, we use the term "now" to mean "the current value 556 of the clock at the host performing the calculation." Hosts that use 557 HTTP, but especially hosts running origin servers and caches, SHOULD 558 use NTP [RFC1305] or some similar protocol to synchronize their 559 clocks to a globally accurate time standard. 561 HTTP/1.1 requires origin servers to send a Date header, if possible, 562 with every response, giving the time at which the response was 563 generated (see Section 8.3 of [Part1]). We use the term "date_value" 564 to denote the value of the Date header, in a form appropriate for 565 arithmetic operations. 567 HTTP/1.1 uses the Age response-header to convey the estimated age of 568 the response message when obtained from a cache. The Age field value 569 is the cache's estimate of the amount of time since the response was 570 generated or revalidated by the origin server. 572 In essence, the Age value is the sum of the time that the response 573 has been resident in each of the caches along the path from the 574 origin server, plus the amount of time it has been in transit along 575 network paths. 577 We use the term "age_value" to denote the value of the Age header, in 578 a form appropriate for arithmetic operations. 580 A response's age can be calculated in two entirely independent ways: 582 1. now minus date_value, if the local clock is reasonably well 583 synchronized to the origin server's clock. If the result is 584 negative, the result is replaced by zero. 586 2. age_value, if all of the caches along the response path implement 587 HTTP/1.1. 589 Given that we have two independent ways to compute the age of a 590 response when it is received, we can combine these as 592 corrected_received_age = max(now - date_value, age_value) 594 and as long as we have either nearly synchronized clocks or all- 595 HTTP/1.1 paths, one gets a reliable (conservative) result. 597 Because of network-imposed delays, some significant interval might 598 pass between the time that a server generates a response and the time 599 it is received at the next outbound cache or client. If uncorrected, 600 this delay could result in improperly low ages. 602 Because the request that resulted in the returned Age value must have 603 been initiated prior to that Age value's generation, we can correct 604 for delays imposed by the network by recording the time at which the 605 request was initiated. Then, when an Age value is received, it MUST 606 be interpreted relative to the time the request was initiated, not 607 the time that the response was received. This algorithm results in 608 conservative behavior no matter how much delay is experienced. So, 609 we compute: 611 corrected_initial_age = corrected_received_age 612 + (now - request_time) 614 where "request_time" is the time (according to the local clock) when 615 the request that elicited this response was sent. 617 Summary of age calculation algorithm, when a cache receives a 618 response: 620 /* 621 * age_value 622 * is the value of Age: header received by the cache with 623 * this response. 624 * date_value 625 * is the value of the origin server's Date: header 626 * request_time 627 * is the (local) time when the cache made the request 628 * that resulted in this cached response 629 * response_time 630 * is the (local) time when the cache received the 631 * response 632 * now 633 * is the current (local) time 634 */ 636 apparent_age = max(0, response_time - date_value); 637 corrected_received_age = max(apparent_age, age_value); 638 response_delay = response_time - request_time; 639 corrected_initial_age = corrected_received_age + response_delay; 640 resident_time = now - response_time; 641 current_age = corrected_initial_age + resident_time; 643 The current_age of a cache entry is calculated by adding the amount 644 of time (in seconds) since the cache entry was last validated by the 645 origin server to the corrected_initial_age. When a response is 646 generated from a cache entry, the cache MUST include a single Age 647 header field in the response with a value equal to the cache entry's 648 current_age. 650 The presence of an Age header field in a response implies that a 651 response is not first-hand. However, the converse is not true, since 652 the lack of an Age header field in a response does not imply that the 653 response is first-hand unless all caches along the request path are 654 compliant with HTTP/1.1 (i.e., older HTTP caches did not implement 655 the Age header field). 657 4.4. Expiration Calculations 659 In order to decide whether a response is fresh or stale, we need to 660 compare its freshness lifetime to its age. The age is calculated as 661 described in Section 4.3; this section describes how to calculate the 662 freshness lifetime, and to determine if a response has expired. In 663 the discussion below, the values can be represented in any form 664 appropriate for arithmetic operations. 666 We use the term "expires_value" to denote the value of the Expires 667 header. We use the term "max_age_value" to denote an appropriate 668 value of the number of seconds carried by the "max-age" directive of 669 the Cache-Control header in a response (see Section 16.2.3). 671 The max-age directive takes priority over Expires, so if max-age is 672 present in a response, the calculation is simply: 674 freshness_lifetime = max_age_value 676 Otherwise, if Expires is present in the response, the calculation is: 678 freshness_lifetime = expires_value - date_value 680 Note that neither of these calculations is vulnerable to clock skew, 681 since all of the information comes from the origin server. 683 If none of Expires, Cache-Control: max-age, or Cache-Control: 684 s-maxage (see Section 16.2.3) appears in the response, and the 685 response does not include other restrictions on caching, the cache 686 MAY compute a freshness lifetime using a heuristic. The cache MUST 687 attach Warning 113 to any response whose age is more than 24 hours if 688 such warning has not already been added. 690 Also, if the response does have a Last-Modified time, the heuristic 691 expiration value SHOULD be no more than some fraction of the interval 692 since that time. A typical setting of this fraction might be 10%. 694 The calculation to determine if a response has expired is quite 695 simple: 697 response_is_fresh = (freshness_lifetime > current_age) 699 4.5. Disambiguating Expiration Values 701 Because expiration values are assigned optimistically, it is possible 702 for two caches to contain fresh values for the same resource that are 703 different. 705 If a client performing a retrieval receives a non-first-hand response 706 for a request that was already fresh in its own cache, and the Date 707 header in its existing cache entry is newer than the Date on the new 708 response, then the client MAY ignore the response. If so, it MAY 709 retry the request with a "Cache-Control: max-age=0" directive (see 710 Section 16.2), to force a check with the origin server. 712 If a cache has two fresh responses for the same representation with 713 different validators, it MUST use the one with the more recent Date 714 header. This situation might arise because the cache is pooling 715 responses from other caches, or because a client has asked for a 716 reload or a revalidation of an apparently fresh cache entry. 718 4.6. Disambiguating Multiple Responses 720 Because a client might be receiving responses via multiple paths, so 721 that some responses flow through one set of caches and other 722 responses flow through a different set of caches, a client might 723 receive responses in an order different from that in which the origin 724 server sent them. We would like the client to use the most recently 725 generated response, even if older responses are still apparently 726 fresh. 728 Neither the entity tag nor the expiration value can impose an 729 ordering on responses, since it is possible that a later response 730 intentionally carries an earlier expiration time. The Date values 731 are ordered to a granularity of one second. 733 When a client tries to revalidate a cache entry, and the response it 734 receives contains a Date header that appears to be older than the one 735 for the existing entry, then the client SHOULD repeat the request 736 unconditionally, and include 738 Cache-Control: max-age=0 740 to force any intermediate caches to validate their copies directly 741 with the origin server, or 743 Cache-Control: no-cache 745 to force any intermediate caches to obtain a new copy from the origin 746 server. 748 If the Date values are equal, then the client MAY use either response 749 (or MAY, if it is being extremely prudent, request a new response). 750 Servers MUST NOT depend on clients being able to choose 751 deterministically between responses generated during the same second, 752 if their expiration times overlap. 754 5. Validation Model 756 When a cache has a stale entry that it would like to use as a 757 response to a client's request, it first has to check with the origin 758 server (or possibly an intermediate cache with a fresh response) to 759 see if its cached entry is still usable. We call this "validating" 760 the cache entry. 762 HTTP's conditional request mechanism, defined in [Part4], is used to 763 avoid retransmitting the response payload when the cached entry is 764 valid. When a cached response includes one or more "cache 765 validators," such as the field values of an ETag or Last-Modified 766 header field, then a validating GET request SHOULD be made 767 conditional to those field values. The server checks the conditional 768 request's validator against the current state of the requested 769 resource and, if they match, the server responds with a 304 (Not 770 Modified) status code to indicate that the cached response can be 771 refreshed and reused without retransmitting the response payload. If 772 the validator does not match the current state of the requested 773 resource, then the server returns a full response, including payload, 774 so that the request can be satisfied and the cache entry supplanted 775 without the need for an additional network round-trip. 777 6. Response Cacheability 779 Unless specifically constrained by a cache-control (Section 16.2) 780 directive, a caching system MAY always store a successful response 781 (see Section 10) as a cache entry, MAY return it without validation 782 if it is fresh, and MAY return it after successful validation. If 783 there is neither a cache validator nor an explicit expiration time 784 associated with a response, we do not expect it to be cached, but 785 certain caches MAY violate this expectation (for example, when little 786 or no network connectivity is available). A client can usually 787 detect that such a response was taken from a cache by comparing the 788 Date header to the current time. 790 Note: some HTTP/1.0 caches are known to violate this expectation 791 without providing any Warning. 793 However, in some cases it might be inappropriate for a cache to 794 retain an entity, or to return it in response to a subsequent 795 request. This might be because absolute semantic transparency is 796 deemed necessary by the service author, or because of security or 797 privacy considerations. Certain cache-control directives are 798 therefore provided so that the server can indicate that certain 799 resource entities, or portions thereof, are not to be cached 800 regardless of other considerations. 802 Note that Section 4.1 of [Part7] normally prevents a shared cache 803 from saving and returning a response to a previous request if that 804 request included an Authorization header. 806 A response received with a status code of 200, 203, 206, 300, 301 or 807 410 MAY be stored by a cache and used in reply to a subsequent 808 request, subject to the expiration mechanism, unless a cache-control 809 directive prohibits caching. However, a cache that does not support 810 the Range and Content-Range headers MUST NOT cache 206 (Partial 811 Content) responses. 813 A response received with any other status code (e.g. status codes 302 814 and 307) MUST NOT be returned in a reply to a subsequent request 815 unless there are cache-control directives or another header(s) that 816 explicitly allow it. For example, these include the following: an 817 Expires header (Section 16.3); a "max-age", "s-maxage", "must- 818 revalidate", "proxy-revalidate", "public" or "private" cache-control 819 directive (Section 16.2). 821 7. Constructing Responses From Caches 823 The purpose of an HTTP cache is to store information received in 824 response to requests for use in responding to future requests. In 825 many cases, a cache simply returns the appropriate parts of a 826 response to the requester. However, if the cache holds a cache entry 827 based on a previous response, it might have to combine parts of a new 828 response with what is held in the cache entry. 830 7.1. End-to-end and Hop-by-hop Headers 832 For the purpose of defining the behavior of caches and non-caching 833 proxies, we divide HTTP headers into two categories: 835 o End-to-end headers, which are transmitted to the ultimate 836 recipient of a request or response. End-to-end headers in 837 responses MUST be stored as part of a cache entry and MUST be 838 transmitted in any response formed from a cache entry. 840 o Hop-by-hop headers, which are meaningful only for a single 841 transport-level connection, and are not stored by caches or 842 forwarded by proxies. 844 The following HTTP/1.1 headers are hop-by-hop headers: 846 o Connection 848 o Keep-Alive 850 o Proxy-Authenticate 852 o Proxy-Authorization 854 o TE 855 o Trailer 857 o Transfer-Encoding 859 o Upgrade 861 All other headers defined by HTTP/1.1 are end-to-end headers. 863 Other hop-by-hop headers MUST be listed in a Connection header 864 (Section 8.1 of [Part1]). 866 7.2. Non-modifiable Headers 868 Some features of HTTP/1.1, such as Digest Authentication, depend on 869 the value of certain end-to-end headers. A transparent proxy SHOULD 870 NOT modify an end-to-end header unless the definition of that header 871 requires or specifically allows that. 873 A transparent proxy MUST NOT modify any of the following fields in a 874 request or response, and it MUST NOT add any of these fields if not 875 already present: 877 o Content-Location 879 o Content-MD5 881 o ETag 883 o Last-Modified 885 A transparent proxy MUST NOT modify any of the following fields in a 886 response: 888 o Expires 890 but it MAY add any of these fields if not already present. If an 891 Expires header is added, it MUST be given a field-value identical to 892 that of the Date header in that response. 894 A proxy MUST NOT modify or add any of the following fields in a 895 message that contains the no-transform cache-control directive, or in 896 any request: 898 o Content-Encoding 900 o Content-Range 901 o Content-Type 903 A non-transparent proxy MAY modify or add these fields to a message 904 that does not include no-transform, but if it does so, it MUST add a 905 Warning 214 (Transformation applied) if one does not already appear 906 in the message (see Section 16.6). 908 Warning: unnecessary modification of end-to-end headers might 909 cause authentication failures if stronger authentication 910 mechanisms are introduced in later versions of HTTP. Such 911 authentication mechanisms MAY rely on the values of header fields 912 not listed here. 914 The Content-Length field of a request or response is added or deleted 915 according to the rules in Section 4.4 of [Part1]. A transparent 916 proxy MUST preserve the entity-length (Section 4.2.2 of [Part3]) of 917 the entity-body, although it MAY change the transfer-length (Section 918 4.4 of [Part1]). 920 7.3. Combining Headers 922 When a cache makes a validating request to a server, and the server 923 provides a 304 (Not Modified) response or a 206 (Partial Content) 924 response, the cache then constructs a response to send to the 925 requesting client. 927 If the status code is 304 (Not Modified), the cache uses the entity- 928 body stored in the cache entry as the entity-body of this outgoing 929 response. If the status code is 206 (Partial Content) and the ETag 930 or Last-Modified headers match exactly, the cache MAY combine the 931 contents stored in the cache entry with the new contents received in 932 the response and use the result as the entity-body of this outgoing 933 response, (see Section 5 of [Part5]). 935 The end-to-end headers stored in the cache entry are used for the 936 constructed response, except that 938 o any stored Warning headers with warn-code 1xx (see Section 16.6) 939 MUST be deleted from the cache entry and the forwarded response. 941 o any stored Warning headers with warn-code 2xx MUST be retained in 942 the cache entry and the forwarded response. 944 o any end-to-end headers provided in the 304 or 206 response MUST 945 replace the corresponding headers from the cache entry. 947 Unless the cache decides to remove the cache entry, it MUST also 948 replace the end-to-end headers stored with the cache entry with 949 corresponding headers received in the incoming response, except for 950 Warning headers as described immediately above. If a header field- 951 name in the incoming response matches more than one header in the 952 cache entry, all such old headers MUST be replaced. 954 In other words, the set of end-to-end headers received in the 955 incoming response overrides all corresponding end-to-end headers 956 stored with the cache entry (except for stored Warning headers with 957 warn-code 1xx, which are deleted even if not overridden). 959 Note: this rule allows an origin server to use a 304 (Not 960 Modified) or a 206 (Partial Content) response to update any header 961 associated with a previous response for the same entity or sub- 962 ranges thereof, although it might not always be meaningful or 963 correct to do so. This rule does not allow an origin server to 964 use a 304 (Not Modified) or a 206 (Partial Content) response to 965 entirely delete a header that it had provided with a previous 966 response. 968 8. Caching Negotiated Responses 970 Use of server-driven content negotiation (Section 5.1 of [Part3]), as 971 indicated by the presence of a Vary header field in a response, 972 alters the conditions and procedure by which a cache can use the 973 response for subsequent requests. See Section 16.5 for use of the 974 Vary header field by servers. 976 A server SHOULD use the Vary header field to inform a cache of what 977 request-header fields were used to select among multiple 978 representations of a cacheable response subject to server-driven 979 negotiation. The set of header fields named by the Vary field value 980 is known as the "selecting" request-headers. 982 When the cache receives a subsequent request whose Request-URI 983 specifies one or more cache entries including a Vary header field, 984 the cache MUST NOT use such a cache entry to construct a response to 985 the new request unless all of the selecting request-headers present 986 in the new request match the corresponding stored request-headers in 987 the original request. 989 The selecting request-headers from two requests are defined to match 990 if and only if the selecting request-headers in the first request can 991 be transformed to the selecting request-headers in the second request 992 by adding or removing linear white space (LWS) at places where this 993 is allowed by the corresponding BNF, and/or combining multiple 994 message-header fields with the same field name following the rules 995 about message headers in Section 4.2 of [Part1]. 997 A Vary header field-value of "*" always fails to match and subsequent 998 requests on that resource can only be properly interpreted by the 999 origin server. 1001 If the selecting request header fields for the cached entry do not 1002 match the selecting request header fields of the new request, then 1003 the cache MUST NOT use a cached entry to satisfy the request unless 1004 it first relays the new request to the origin server in a conditional 1005 request and the server responds with 304 (Not Modified), including an 1006 entity tag or Content-Location that indicates the entity to be used. 1008 If an entity tag was assigned to a cached representation, the 1009 forwarded request SHOULD be conditional and include the entity tags 1010 in an If-None-Match header field from all its cache entries for the 1011 resource. This conveys to the server the set of entities currently 1012 held by the cache, so that if any one of these entities matches the 1013 requested entity, the server can use the ETag header field in its 304 1014 (Not Modified) response to tell the cache which entry is appropriate. 1015 If the entity-tag of the new response matches that of an existing 1016 entry, the new response SHOULD be used to update the header fields of 1017 the existing entry, and the result MUST be returned to the client. 1019 If any of the existing cache entries contains only partial content 1020 for the associated entity, its entity-tag SHOULD NOT be included in 1021 the If-None-Match header field unless the request is for a range that 1022 would be fully satisfied by that entry. 1024 If a cache receives a successful response whose Content-Location 1025 field matches that of an existing cache entry for the same Request- 1026 URI, whose entity-tag differs from that of the existing entry, and 1027 whose Date is more recent than that of the existing entry, the 1028 existing entry SHOULD NOT be returned in response to future requests 1029 and SHOULD be deleted from the cache. 1031 9. Shared and Non-Shared Caches 1033 For reasons of security and privacy, it is necessary to make a 1034 distinction between "shared" and "non-shared" caches. A non-shared 1035 cache is one that is accessible only to a single user. Accessibility 1036 in this case SHOULD be enforced by appropriate security mechanisms. 1037 All other caches are considered to be "shared." Other sections of 1038 this specification place certain constraints on the operation of 1039 shared caches in order to prevent loss of privacy or failure of 1040 access controls. 1042 10. Errors or Incomplete Response Cache Behavior 1044 A cache that receives an incomplete response (for example, with fewer 1045 bytes of data than specified in a Content-Length header) MAY store 1046 the response. However, the cache MUST treat this as a partial 1047 response. Partial responses MAY be combined as described in Section 1048 5 of [Part5]; the result might be a full response or might still be 1049 partial. A cache MUST NOT return a partial response to a client 1050 without explicitly marking it as such, using the 206 (Partial 1051 Content) status code. A cache MUST NOT return a partial response 1052 using a status code of 200 (OK). 1054 If a cache receives a 5xx response while attempting to revalidate an 1055 entry, it MAY either forward this response to the requesting client, 1056 or act as if the server failed to respond. In the latter case, it 1057 MAY return a previously received response unless the cached entry 1058 includes the "must-revalidate" cache-control directive (see 1059 Section 16.2). 1061 11. Side Effects of GET and HEAD 1063 Unless the origin server explicitly prohibits the caching of their 1064 responses, the application of GET and HEAD methods to any resources 1065 SHOULD NOT have side effects that would lead to erroneous behavior if 1066 these responses are taken from a cache. They MAY still have side 1067 effects, but a cache is not required to consider such side effects in 1068 its caching decisions. Caches are always expected to observe an 1069 origin server's explicit restrictions on caching. 1071 We note one exception to this rule: since some applications have 1072 traditionally used GET and HEAD requests with URLs containing a query 1073 part to perform operations with significant side effects, caches MUST 1074 NOT treat responses to such URIs as fresh unless the server provides 1075 an explicit expiration time. This specifically means that responses 1076 from HTTP/1.0 servers for such URIs SHOULD NOT be taken from a cache. 1077 See Section 8.1.1 of [Part2] for related information. 1079 12. Invalidation After Updates or Deletions 1081 The effect of certain methods performed on a resource at the origin 1082 server might cause one or more existing cache entries to become non- 1083 transparently invalid. That is, although they might continue to be 1084 "fresh," they do not accurately reflect what the origin server would 1085 return for a new request on that resource. 1087 There is no way for HTTP to guarantee that all such cache entries are 1088 marked invalid. For example, the request that caused the change at 1089 the origin server might not have gone through the proxy where a cache 1090 entry is stored. However, several rules help reduce the likelihood 1091 of erroneous behavior. 1093 In this section, the phrase "invalidate an entity" means that the 1094 cache will either remove all instances of that entity from its 1095 storage, or will mark these as "invalid" and in need of a mandatory 1096 revalidation before they can be returned in response to a subsequent 1097 request. 1099 Some HTTP methods MUST cause a cache to invalidate an entity. This 1100 is either the entity referred to by the Request-URI, or by the 1101 Location or Content-Location headers (if present). These methods 1102 are: 1104 o PUT 1106 o DELETE 1108 o POST 1110 An invalidation based on the URI in a Location or Content-Location 1111 header MUST NOT be performed if the host part of that URI differs 1112 from the host part in the Request-URI. This helps prevent denial of 1113 service attacks. 1115 A cache that passes through requests for methods it does not 1116 understand SHOULD invalidate any entities referred to by the Request- 1117 URI. 1119 13. Write-Through Mandatory 1121 All methods that might be expected to cause modifications to the 1122 origin server's resources MUST be written through to the origin 1123 server. This currently includes all methods except for GET and HEAD. 1124 A cache MUST NOT reply to such a request from a client before having 1125 transmitted the request to the inbound server, and having received a 1126 corresponding response from the inbound server. This does not 1127 prevent a proxy cache from sending a 100 (Continue) response before 1128 the inbound server has sent its final reply. 1130 The alternative (known as "write-back" or "copy-back" caching) is not 1131 allowed in HTTP/1.1, due to the difficulty of providing consistent 1132 updates and the problems arising from server, cache, or network 1133 failure prior to write-back. 1135 14. Cache Replacement 1137 If a new cacheable (see Sections 16.2.2, 4.5, 4.6 and 10) response is 1138 received from a resource while any existing responses for the same 1139 resource are cached, the cache SHOULD use the new response to reply 1140 to the current request. It MAY insert it into cache storage and MAY, 1141 if it meets all other requirements, use it to respond to any future 1142 requests that would previously have caused the old response to be 1143 returned. If it inserts the new response into cache storage the 1144 rules in Section 7.3 apply. 1146 Note: a new response that has an older Date header value than 1147 existing cached responses is not cacheable. 1149 15. History Lists 1151 User agents often have history mechanisms, such as "Back" buttons and 1152 history lists, which can be used to redisplay an entity retrieved 1153 earlier in a session. 1155 History mechanisms and caches are different. In particular history 1156 mechanisms SHOULD NOT try to show a semantically transparent view of 1157 the current state of a resource. Rather, a history mechanism is 1158 meant to show exactly what the user saw at the time when the resource 1159 was retrieved. 1161 By default, an expiration time does not apply to history mechanisms. 1162 If the entity is still in storage, a history mechanism SHOULD display 1163 it even if the entity has expired, unless the user has specifically 1164 configured the agent to refresh expired history documents. 1166 This is not to be construed to prohibit the history mechanism from 1167 telling the user that a view might be stale. 1169 Note: if history list mechanisms unnecessarily prevent users from 1170 viewing stale resources, this will tend to force service authors 1171 to avoid using HTTP expiration controls and cache controls when 1172 they would otherwise like to. Service authors may consider it 1173 important that users not be presented with error messages or 1174 warning messages when they use navigation controls (such as BACK) 1175 to view previously fetched resources. Even though sometimes such 1176 resources ought not be cached, or ought to expire quickly, user 1177 interface considerations may force service authors to resort to 1178 other means of preventing caching (e.g. "once-only" URLs) in order 1179 not to suffer the effects of improperly functioning history 1180 mechanisms. 1182 16. Header Field Definitions 1184 This section defines the syntax and semantics of HTTP/1.1 header 1185 fields related to caching. 1187 For entity-header fields, both sender and recipient refer to either 1188 the client or the server, depending on who sends and who receives the 1189 entity. 1191 16.1. Age 1193 The Age response-header field conveys the sender's estimate of the 1194 amount of time since the response (or its revalidation) was generated 1195 at the origin server. A cached response is "fresh" if its age does 1196 not exceed its freshness lifetime. Age values are calculated as 1197 specified in Section 4.3. 1199 Age = "Age" ":" age-value 1200 age-value = delta-seconds 1202 Age values are non-negative decimal integers, representing time in 1203 seconds. 1205 delta-seconds = 1*DIGIT 1207 If a cache receives a value larger than the largest positive integer 1208 it can represent, or if any of its age calculations overflows, it 1209 MUST transmit an Age header with a value of 2147483648 (2^31). An 1210 HTTP/1.1 server that includes a cache MUST include an Age header 1211 field in every response generated from its own cache. Caches SHOULD 1212 use an arithmetic type of at least 31 bits of range. 1214 16.2. Cache-Control 1216 The Cache-Control general-header field is used to specify directives 1217 that MUST be obeyed by all caching mechanisms along the request/ 1218 response chain. The directives specify behavior intended to prevent 1219 caches from adversely interfering with the request or response. 1220 These directives typically override the default caching algorithms. 1221 Cache directives are unidirectional in that the presence of a 1222 directive in a request does not imply that the same directive is to 1223 be given in the response. 1225 Note that HTTP/1.0 caches might not implement Cache-Control and 1226 might only implement Pragma: no-cache (see Section 16.4). 1228 Cache directives MUST be passed through by a proxy or gateway 1229 application, regardless of their significance to that application, 1230 since the directives might be applicable to all recipients along the 1231 request/response chain. It is not possible to specify a cache- 1232 directive for a specific cache. 1234 Cache-Control = "Cache-Control" ":" 1#cache-directive 1236 cache-directive = cache-request-directive 1237 | cache-response-directive 1239 cache-request-directive = 1240 "no-cache" ; Section 16.2.1 1241 | "no-store" ; Section 16.2.2 1242 | "max-age" "=" delta-seconds ; Section 16.2.3, 16.2.4 1243 | "max-stale" [ "=" delta-seconds ] ; Section 16.2.3 1244 | "min-fresh" "=" delta-seconds ; Section 16.2.3 1245 | "no-transform" ; Section 16.2.5 1246 | "only-if-cached" ; Section 16.2.4 1247 | cache-extension ; Section 16.2.6 1249 cache-response-directive = 1250 "public" ; Section 16.2.1 1251 | "private" [ "=" DQUOTE 1#field-name DQUOTE ] ; Section 16.2.1 1252 | "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] ; Section 16.2.1 1253 | "no-store" ; Section 16.2.2 1254 | "no-transform" ; Section 16.2.5 1255 | "must-revalidate" ; Section 16.2.4 1256 | "proxy-revalidate" ; Section 16.2.4 1257 | "max-age" "=" delta-seconds ; Section 16.2.3 1258 | "s-maxage" "=" delta-seconds ; Section 16.2.3 1259 | cache-extension ; Section 16.2.6 1261 cache-extension = token [ "=" ( token | quoted-string ) ] 1263 When a directive appears without any 1#field-name parameter, the 1264 directive applies to the entire request or response. When such a 1265 directive appears with a 1#field-name parameter, it applies only to 1266 the named field or fields, and not to the rest of the request or 1267 response. This mechanism supports extensibility; implementations of 1268 future versions of HTTP might apply these directives to header fields 1269 not defined in HTTP/1.1. 1271 The cache-control directives can be broken down into these general 1272 categories: 1274 o Restrictions on what are cacheable; these may only be imposed by 1275 the origin server. 1277 o Restrictions on what may be stored by a cache; these may be 1278 imposed by either the origin server or the user agent. 1280 o Modifications of the basic expiration mechanism; these may be 1281 imposed by either the origin server or the user agent. 1283 o Controls over cache revalidation and reload; these may only be 1284 imposed by a user agent. 1286 o Control over transformation of entities. 1288 o Extensions to the caching system. 1290 16.2.1. What is Cacheable 1292 By default, a response is cacheable if the requirements of the 1293 request method, request header fields, and the response status 1294 indicate that it is cacheable. Section 6 summarizes these defaults 1295 for cacheability. The following Cache-Control response directives 1296 allow an origin server to override the default cacheability of a 1297 response: 1299 public 1301 Indicates that the response MAY be cached by any cache, even if it 1302 would normally be non-cacheable or cacheable only within a non- 1303 shared cache. (See also Authorization, Section 4.1 of [Part7], 1304 for additional details.) 1306 private 1308 Indicates that all or part of the response message is intended for 1309 a single user and MUST NOT be cached by a shared cache. This 1310 allows an origin server to state that the specified parts of the 1311 response are intended for only one user and are not a valid 1312 response for requests by other users. A private (non-shared) 1313 cache MAY cache the response. 1315 Note: This usage of the word private only controls where the 1316 response may be cached, and cannot ensure the privacy of the 1317 message content. 1319 no-cache 1321 If the no-cache directive does not specify a field-name, then a 1322 cache MUST NOT use the response to satisfy a subsequent request 1323 without successful revalidation with the origin server. This 1324 allows an origin server to prevent caching even by caches that 1325 have been configured to return stale responses to client requests. 1327 If the no-cache directive does specify one or more field-names, 1328 then a cache MAY use the response to satisfy a subsequent request, 1329 subject to any other restrictions on caching. However, the 1330 specified field-name(s) MUST NOT be sent in the response to a 1331 subsequent request without successful revalidation with the origin 1332 server. This allows an origin server to prevent the re-use of 1333 certain header fields in a response, while still allowing caching 1334 of the rest of the response. 1336 Note: Most HTTP/1.0 caches will not recognize or obey this 1337 directive. 1339 16.2.2. What May be Stored by Caches 1341 no-store 1343 The purpose of the no-store directive is to prevent the 1344 inadvertent release or retention of sensitive information (for 1345 example, on backup tapes). The no-store directive applies to the 1346 entire message, and MAY be sent either in a response or in a 1347 request. If sent in a request, a cache MUST NOT store any part of 1348 either this request or any response to it. If sent in a response, 1349 a cache MUST NOT store any part of either this response or the 1350 request that elicited it. This directive applies to both non- 1351 shared and shared caches. "MUST NOT store" in this context means 1352 that the cache MUST NOT intentionally store the information in 1353 non-volatile storage, and MUST make a best-effort attempt to 1354 remove the information from volatile storage as promptly as 1355 possible after forwarding it. 1357 Even when this directive is associated with a response, users 1358 might explicitly store such a response outside of the caching 1359 system (e.g., with a "Save As" dialog). History buffers MAY store 1360 such responses as part of their normal operation. 1362 The purpose of this directive is to meet the stated requirements 1363 of certain users and service authors who are concerned about 1364 accidental releases of information via unanticipated accesses to 1365 cache data structures. While the use of this directive might 1366 improve privacy in some cases, we caution that it is NOT in any 1367 way a reliable or sufficient mechanism for ensuring privacy. In 1368 particular, malicious or compromised caches might not recognize or 1369 obey this directive, and communications networks might be 1370 vulnerable to eavesdropping. 1372 16.2.3. Modifications of the Basic Expiration Mechanism 1374 The expiration time of an entity MAY be specified by the origin 1375 server using the Expires header (see Section 16.3). Alternatively, 1376 it MAY be specified using the max-age directive in a response. When 1377 the max-age cache-control directive is present in a cached response, 1378 the response is stale if its current age is greater than the age 1379 value given (in seconds) at the time of a new request for that 1380 resource. The max-age directive on a response implies that the 1381 response is cacheable (i.e., "public") unless some other, more 1382 restrictive cache directive is also present. 1384 If a response includes both an Expires header and a max-age 1385 directive, the max-age directive overrides the Expires header, even 1386 if the Expires header is more restrictive. This rule allows an 1387 origin server to provide, for a given response, a longer expiration 1388 time to an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This 1389 might be useful if certain HTTP/1.0 caches improperly calculate ages 1390 or expiration times, perhaps due to desynchronized clocks. 1392 Many HTTP/1.0 cache implementations will treat an Expires value that 1393 is less than or equal to the response Date value as being equivalent 1394 to the Cache-Control response directive "no-cache". If an HTTP/1.1 1395 cache receives such a response, and the response does not include a 1396 Cache-Control header field, it SHOULD consider the response to be 1397 non-cacheable in order to retain compatibility with HTTP/1.0 servers. 1399 Note: An origin server might wish to use a relatively new HTTP 1400 cache control feature, such as the "private" directive, on a 1401 network including older caches that do not understand that 1402 feature. The origin server will need to combine the new feature 1403 with an Expires field whose value is less than or equal to the 1404 Date value. This will prevent older caches from improperly 1405 caching the response. 1407 s-maxage 1409 If a response includes an s-maxage directive, then for a shared 1410 cache (but not for a private cache), the maximum age specified by 1411 this directive overrides the maximum age specified by either the 1412 max-age directive or the Expires header. The s-maxage directive 1413 also implies the semantics of the proxy-revalidate directive (see 1414 Section 16.2.4), i.e., that the shared cache must not use the 1415 entry after it becomes stale to respond to a subsequent request 1416 without first revalidating it with the origin server. The 1417 s-maxage directive is always ignored by a private cache. 1419 Note that most older caches, not compliant with this specification, 1420 do not implement any cache-control directives. An origin server 1421 wishing to use a cache-control directive that restricts, but does not 1422 prevent, caching by an HTTP/1.1-compliant cache MAY exploit the 1423 requirement that the max-age directive overrides the Expires header, 1424 and the fact that pre-HTTP/1.1-compliant caches do not observe the 1425 max-age directive. 1427 Other directives allow a user agent to modify the basic expiration 1428 mechanism. These directives MAY be specified on a request: 1430 max-age 1432 Indicates that the client is willing to accept a response whose 1433 age is no greater than the specified time in seconds. Unless max- 1434 stale directive is also included, the client is not willing to 1435 accept a stale response. 1437 min-fresh 1439 Indicates that the client is willing to accept a response whose 1440 freshness lifetime is no less than its current age plus the 1441 specified time in seconds. That is, the client wants a response 1442 that will still be fresh for at least the specified number of 1443 seconds. 1445 max-stale 1447 Indicates that the client is willing to accept a response that has 1448 exceeded its expiration time. If max-stale is assigned a value, 1449 then the client is willing to accept a response that has exceeded 1450 its expiration time by no more than the specified number of 1451 seconds. If no value is assigned to max-stale, then the client is 1452 willing to accept a stale response of any age. 1454 If a cache returns a stale response, either because of a max-stale 1455 directive on a request, or because the cache is configured to 1456 override the expiration time of a response, the cache MUST attach a 1457 Warning header to the stale response, using Warning 110 (Response is 1458 stale). 1460 A cache MAY be configured to return stale responses without 1461 validation, but only if this does not conflict with any "MUST"-level 1462 requirements concerning cache validation (e.g., a "must-revalidate" 1463 cache-control directive). 1465 If both the new request and the cached entry include "max-age" 1466 directives, then the lesser of the two values is used for determining 1467 the freshness of the cached entry for that request. 1469 16.2.4. Cache Revalidation and Reload Controls 1471 Sometimes a user agent might want or need to insist that a cache 1472 revalidate its cache entry with the origin server (and not just with 1473 the next cache along the path to the origin server), or to reload its 1474 cache entry from the origin server. End-to-end revalidation might be 1475 necessary if either the cache or the origin server has overestimated 1476 the expiration time of the cached response. End-to-end reload may be 1477 necessary if the cache entry has become corrupted for some reason. 1479 End-to-end revalidation may be requested either when the client does 1480 not have its own local cached copy, in which case we call it 1481 "unspecified end-to-end revalidation", or when the client does have a 1482 local cached copy, in which case we call it "specific end-to-end 1483 revalidation." 1485 The client can specify these three kinds of action using Cache- 1486 Control request directives: 1488 End-to-end reload 1490 The request includes a "no-cache" cache-control directive or, for 1491 compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field 1492 names MUST NOT be included with the no-cache directive in a 1493 request. The server MUST NOT use a cached copy when responding to 1494 such a request. 1496 Specific end-to-end revalidation 1498 The request includes a "max-age=0" cache-control directive, which 1499 forces each cache along the path to the origin server to 1500 revalidate its own entry, if any, with the next cache or server. 1501 The initial request includes a cache-validating conditional with 1502 the client's current validator. 1504 Unspecified end-to-end revalidation 1506 The request includes "max-age=0" cache-control directive, which 1507 forces each cache along the path to the origin server to 1508 revalidate its own entry, if any, with the next cache or server. 1509 The initial request does not include a cache-validating 1510 conditional; the first cache along the path (if any) that holds a 1511 cache entry for this resource includes a cache-validating 1512 conditional with its current validator. 1514 max-age 1515 When an intermediate cache is forced, by means of a max-age=0 1516 directive, to revalidate its own cache entry, and the client has 1517 supplied its own validator in the request, the supplied validator 1518 might differ from the validator currently stored with the cache 1519 entry. In this case, the cache MAY use either validator in making 1520 its own request without affecting semantic transparency. 1522 However, the choice of validator might affect performance. The 1523 best approach is for the intermediate cache to use its own 1524 validator when making its request. If the server replies with 304 1525 (Not Modified), then the cache can return its now validated copy 1526 to the client with a 200 (OK) response. If the server replies 1527 with a new entity and cache validator, however, the intermediate 1528 cache can compare the returned validator with the one provided in 1529 the client's request, using the strong comparison function. If 1530 the client's validator is equal to the origin server's, then the 1531 intermediate cache simply returns 304 (Not Modified). Otherwise, 1532 it returns the new entity with a 200 (OK) response. 1534 If a request includes the no-cache directive, it SHOULD NOT 1535 include min-fresh, max-stale, or max-age. 1537 only-if-cached 1539 In some cases, such as times of extremely poor network 1540 connectivity, a client may want a cache to return only those 1541 responses that it currently has stored, and not to reload or 1542 revalidate with the origin server. To do this, the client may 1543 include the only-if-cached directive in a request. If it receives 1544 this directive, a cache SHOULD either respond using a cached entry 1545 that is consistent with the other constraints of the request, or 1546 respond with a 504 (Gateway Timeout) status. However, if a group 1547 of caches is being operated as a unified system with good internal 1548 connectivity, such a request MAY be forwarded within that group of 1549 caches. 1551 must-revalidate 1553 Because a cache MAY be configured to ignore a server's specified 1554 expiration time, and because a client request MAY include a max- 1555 stale directive (which has a similar effect), the protocol also 1556 includes a mechanism for the origin server to require revalidation 1557 of a cache entry on any subsequent use. When the must-revalidate 1558 directive is present in a response received by a cache, that cache 1559 MUST NOT use the entry after it becomes stale to respond to a 1560 subsequent request without first revalidating it with the origin 1561 server. (I.e., the cache MUST do an end-to-end revalidation every 1562 time, if, based solely on the origin server's Expires or max-age 1563 value, the cached response is stale.) 1565 The must-revalidate directive is necessary to support reliable 1566 operation for certain protocol features. In all circumstances an 1567 HTTP/1.1 cache MUST obey the must-revalidate directive; in 1568 particular, if the cache cannot reach the origin server for any 1569 reason, it MUST generate a 504 (Gateway Timeout) response. 1571 Servers SHOULD send the must-revalidate directive if and only if 1572 failure to revalidate a request on the entity could result in 1573 incorrect operation, such as a silently unexecuted financial 1574 transaction. Recipients MUST NOT take any automated action that 1575 violates this directive, and MUST NOT automatically provide an 1576 unvalidated copy of the entity if revalidation fails. 1578 Although this is not recommended, user agents operating under 1579 severe connectivity constraints MAY violate this directive but, if 1580 so, MUST explicitly warn the user that an unvalidated response has 1581 been provided. The warning MUST be provided on each unvalidated 1582 access, and SHOULD require explicit user confirmation. 1584 proxy-revalidate 1586 The proxy-revalidate directive has the same meaning as the must- 1587 revalidate directive, except that it does not apply to non-shared 1588 user agent caches. It can be used on a response to an 1589 authenticated request to permit the user's cache to store and 1590 later return the response without needing to revalidate it (since 1591 it has already been authenticated once by that user), while still 1592 requiring proxies that service many users to revalidate each time 1593 (in order to make sure that each user has been authenticated). 1594 Note that such authenticated responses also need the public cache 1595 control directive in order to allow them to be cached at all. 1597 16.2.5. No-Transform Directive 1599 no-transform 1601 Implementors of intermediate caches (proxies) have found it useful 1602 to convert the media type of certain entity bodies. A non- 1603 transparent proxy might, for example, convert between image 1604 formats in order to save cache space or to reduce the amount of 1605 traffic on a slow link. 1607 Serious operational problems occur, however, when these 1608 transformations are applied to entity bodies intended for certain 1609 kinds of applications. For example, applications for medical 1610 imaging, scientific data analysis and those using end-to-end 1611 authentication, all depend on receiving an entity body that is bit 1612 for bit identical to the original entity-body. 1614 Therefore, if a message includes the no-transform directive, an 1615 intermediate cache or proxy MUST NOT change those headers that are 1616 listed in Section 7.2 as being subject to the no-transform 1617 directive. This implies that the cache or proxy MUST NOT change 1618 any aspect of the entity-body that is specified by these headers, 1619 including the value of the entity-body itself. 1621 16.2.6. Cache Control Extensions 1623 The Cache-Control header field can be extended through the use of one 1624 or more cache-extension tokens, each with an optional assigned value. 1625 Informational extensions (those which do not require a change in 1626 cache behavior) MAY be added without changing the semantics of other 1627 directives. Behavioral extensions are designed to work by acting as 1628 modifiers to the existing base of cache directives. Both the new 1629 directive and the standard directive are supplied, such that 1630 applications which do not understand the new directive will default 1631 to the behavior specified by the standard directive, and those that 1632 understand the new directive will recognize it as modifying the 1633 requirements associated with the standard directive. In this way, 1634 extensions to the cache-control directives can be made without 1635 requiring changes to the base protocol. 1637 This extension mechanism depends on an HTTP cache obeying all of the 1638 cache-control directives defined for its native HTTP-version, obeying 1639 certain extensions, and ignoring all directives that it does not 1640 understand. 1642 For example, consider a hypothetical new response directive called 1643 community which acts as a modifier to the private directive. We 1644 define this new directive to mean that, in addition to any non-shared 1645 cache, any cache which is shared only by members of the community 1646 named within its value may cache the response. An origin server 1647 wishing to allow the UCI community to use an otherwise private 1648 response in their shared cache(s) could do so by including 1650 Cache-Control: private, community="UCI" 1652 A cache seeing this header field will act correctly even if the cache 1653 does not understand the community cache-extension, since it will also 1654 see and understand the private directive and thus default to the safe 1655 behavior. 1657 Unrecognized cache-directives MUST be ignored; it is assumed that any 1658 cache-directive likely to be unrecognized by an HTTP/1.1 cache will 1659 be combined with standard directives (or the response's default 1660 cacheability) such that the cache behavior will remain minimally 1661 correct even if the cache does not understand the extension(s). 1663 16.3. Expires 1665 The Expires entity-header field gives the date/time after which the 1666 response is considered stale. A stale cache entry may not normally 1667 be returned by a cache (either a proxy cache or a user agent cache) 1668 unless it is first validated with the origin server (or with an 1669 intermediate cache that has a fresh copy of the entity). See 1670 Section 4 for further discussion of the expiration model. 1672 The presence of an Expires field does not imply that the original 1673 resource will change or cease to exist at, before, or after that 1674 time. 1676 The format is an absolute date and time as defined by HTTP-date in 1677 Section 3.3.1 of [Part1]; it MUST be sent in rfc1123-date format. 1679 Expires = "Expires" ":" HTTP-date 1681 An example of its use is 1683 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1685 Note: if a response includes a Cache-Control field with the max- 1686 age directive (see Section 16.2.3), that directive overrides the 1687 Expires field. 1689 HTTP/1.1 clients and caches MUST treat other invalid date formats, 1690 especially including the value "0", as in the past (i.e., "already 1691 expired"). 1693 To mark a response as "already expired," an origin server sends an 1694 Expires date that is equal to the Date header value. (See the rules 1695 for expiration calculations in Section 4.4.) 1697 To mark a response as "never expires," an origin server sends an 1698 Expires date approximately one year from the time the response is 1699 sent. HTTP/1.1 servers SHOULD NOT send Expires dates more than one 1700 year in the future. 1702 The presence of an Expires header field with a date value of some 1703 time in the future on a response that otherwise would by default be 1704 non-cacheable indicates that the response is cacheable, unless 1705 indicated otherwise by a Cache-Control header field (Section 16.2). 1707 16.4. Pragma 1709 The Pragma general-header field is used to include implementation- 1710 specific directives that might apply to any recipient along the 1711 request/response chain. All pragma directives specify optional 1712 behavior from the viewpoint of the protocol; however, some systems 1713 MAY require that behavior be consistent with the directives. 1715 Pragma = "Pragma" ":" 1#pragma-directive 1716 pragma-directive = "no-cache" | extension-pragma 1717 extension-pragma = token [ "=" ( token | quoted-string ) ] 1719 When the no-cache directive is present in a request message, an 1720 application SHOULD forward the request toward the origin server even 1721 if it has a cached copy of what is being requested. This pragma 1722 directive has the same semantics as the no-cache cache-directive (see 1723 Section 16.2) and is defined here for backward compatibility with 1724 HTTP/1.0. Clients SHOULD include both header fields when a no-cache 1725 request is sent to a server not known to be HTTP/1.1 compliant. 1727 Pragma directives MUST be passed through by a proxy or gateway 1728 application, regardless of their significance to that application, 1729 since the directives might be applicable to all recipients along the 1730 request/response chain. It is not possible to specify a pragma for a 1731 specific recipient; however, any pragma directive not relevant to a 1732 recipient SHOULD be ignored by that recipient. 1734 HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had 1735 sent "Cache-Control: no-cache". No new Pragma directives will be 1736 defined in HTTP. 1738 Note: because the meaning of "Pragma: no-cache" as a response- 1739 header field is not actually specified, it does not provide a 1740 reliable replacement for "Cache-Control: no-cache" in a response. 1742 16.5. Vary 1744 The Vary field value indicates the set of request-header fields that 1745 fully determines, while the response is fresh, whether a cache is 1746 permitted to use the response to reply to a subsequent request 1747 without revalidation. For uncacheable or stale responses, the Vary 1748 field value advises the user agent about the criteria that were used 1749 to select the representation. A Vary field value of "*" implies that 1750 a cache cannot determine from the request headers of a subsequent 1751 request whether this response is the appropriate representation. See 1752 Section 8 for use of the Vary header field by caches. 1754 Vary = "Vary" ":" ( "*" | 1#field-name ) 1756 An HTTP/1.1 server SHOULD include a Vary header field with any 1757 cacheable response that is subject to server-driven negotiation. 1758 Doing so allows a cache to properly interpret future requests on that 1759 resource and informs the user agent about the presence of negotiation 1760 on that resource. A server MAY include a Vary header field with a 1761 non-cacheable response that is subject to server-driven negotiation, 1762 since this might provide the user agent with useful information about 1763 the dimensions over which the response varies at the time of the 1764 response. 1766 A Vary field value consisting of a list of field-names signals that 1767 the representation selected for the response is based on a selection 1768 algorithm which considers ONLY the listed request-header field values 1769 in selecting the most appropriate representation. A cache MAY assume 1770 that the same selection will be made for future requests with the 1771 same values for the listed field names, for the duration of time for 1772 which the response is fresh. 1774 The field-names given are not limited to the set of standard request- 1775 header fields defined by this specification. Field names are case- 1776 insensitive. 1778 A Vary field value of "*" signals that unspecified parameters not 1779 limited to the request-headers (e.g., the network address of the 1780 client), play a role in the selection of the response representation. 1781 The "*" value MUST NOT be generated by a proxy server; it may only be 1782 generated by an origin server. 1784 16.6. Warning 1786 The Warning general-header field is used to carry additional 1787 information about the status or transformation of a message which 1788 might not be reflected in the message. This information is typically 1789 used to warn about a possible lack of semantic transparency from 1790 caching operations or transformations applied to the entity body of 1791 the message. 1793 Warning headers are sent with responses using: 1795 Warning = "Warning" ":" 1#warning-value 1797 warning-value = warn-code SP warn-agent SP warn-text 1798 [SP warn-date] 1800 warn-code = 3DIGIT 1801 warn-agent = ( uri-host [ ":" port ] ) | pseudonym 1802 ; the name or pseudonym of the server adding 1803 ; the Warning header, for use in debugging 1804 warn-text = quoted-string 1805 warn-date = DQUOTE HTTP-date DQUOTE 1807 A response MAY carry more than one Warning header. 1809 The warn-text SHOULD be in a natural language and character set that 1810 is most likely to be intelligible to the human user receiving the 1811 response. This decision MAY be based on any available knowledge, 1812 such as the location of the cache or user, the Accept-Language field 1813 in a request, the Content-Language field in a response, etc. The 1814 default language is English and the default character set is ISO- 1815 8859-1 ([ISO-8859-1]). 1817 If a character set other than ISO-8859-1 is used, it MUST be encoded 1818 in the warn-text using the method described in [RFC2047]. 1820 Warning headers can in general be applied to any message, however 1821 some specific warn-codes are specific to caches and can only be 1822 applied to response messages. New Warning headers SHOULD be added 1823 after any existing Warning headers. A cache MUST NOT delete any 1824 Warning header that it received with a message. However, if a cache 1825 successfully validates a cache entry, it SHOULD remove any Warning 1826 headers previously attached to that entry except as specified for 1827 specific Warning codes. It MUST then add any Warning headers 1828 received in the validating response. In other words, Warning headers 1829 are those that would be attached to the most recent relevant 1830 response. 1832 When multiple Warning headers are attached to a response, the user 1833 agent ought to inform the user of as many of them as possible, in the 1834 order that they appear in the response. If it is not possible to 1835 inform the user of all of the warnings, the user agent SHOULD follow 1836 these heuristics: 1838 o Warnings that appear early in the response take priority over 1839 those appearing later in the response. 1841 o Warnings in the user's preferred character set take priority over 1842 warnings in other character sets but with identical warn-codes and 1843 warn-agents. 1845 Systems that generate multiple Warning headers SHOULD order them with 1846 this user agent behavior in mind. 1848 Requirements for the behavior of caches with respect to Warnings are 1849 stated in Section 3.2. 1851 This is a list of the currently-defined warn-codes, each with a 1852 recommended warn-text in English, and a description of its meaning. 1854 110 Response is stale 1856 MUST be included whenever the returned response is stale. 1858 111 Revalidation failed 1860 MUST be included if a cache returns a stale response because an 1861 attempt to revalidate the response failed, due to an inability to 1862 reach the server. 1864 112 Disconnected operation 1866 SHOULD be included if the cache is intentionally disconnected from 1867 the rest of the network for a period of time. 1869 113 Heuristic expiration 1871 MUST be included if the cache heuristically chose a freshness 1872 lifetime greater than 24 hours and the response's age is greater 1873 than 24 hours. 1875 199 Miscellaneous warning 1877 The warning text MAY include arbitrary information to be presented 1878 to a human user, or logged. A system receiving this warning MUST 1879 NOT take any automated action, besides presenting the warning to 1880 the user. 1882 214 Transformation applied 1884 MUST be added by an intermediate cache or proxy if it applies any 1885 transformation changing the content-coding (as specified in the 1886 Content-Encoding header) or media-type (as specified in the 1887 Content-Type header) of the response, or the entity-body of the 1888 response, unless this Warning code already appears in the 1889 response. 1891 299 Miscellaneous persistent warning 1893 The warning text MAY include arbitrary information to be presented 1894 to a human user, or logged. A system receiving this warning MUST 1895 NOT take any automated action. 1897 If an implementation sends a message with one or more Warning headers 1898 whose version is HTTP/1.0 or lower, then the sender MUST include in 1899 each warning-value a warn-date that matches the date in the response. 1901 If an implementation receives a message with a warning-value that 1902 includes a warn-date, and that warn-date is different from the Date 1903 value in the response, then that warning-value MUST be deleted from 1904 the message before storing, forwarding, or using it. (This prevents 1905 bad consequences of naive caching of Warning header fields.) If all 1906 of the warning-values are deleted for this reason, the Warning header 1907 MUST be deleted as well. 1909 17. IANA Considerations 1911 [[anchor1: TBD.]] 1913 18. Security Considerations 1915 Caching proxies provide additional potential vulnerabilities, since 1916 the contents of the cache represent an attractive target for 1917 malicious exploitation. Because cache contents persist after an HTTP 1918 request is complete, an attack on the cache can reveal information 1919 long after a user believes that the information has been removed from 1920 the network. Therefore, cache contents should be protected as 1921 sensitive information. 1923 19. Acknowledgments 1925 Much of the content and presentation of the caching design is due to 1926 suggestions and comments from individuals including: Shel Kaphan, 1927 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 1929 20. References 1931 20.1. Normative References 1933 [ISO-8859-1] 1934 International Organization for Standardization, 1935 "Information technology -- 8-bit single-byte coded graphic 1936 character sets -- Part 1: Latin alphabet No. 1", ISO/ 1937 IEC 8859-1:1998, 1998. 1939 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1940 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1941 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 1942 and Message Parsing", draft-ietf-httpbis-p1-messaging-02 1943 (work in progress), February 2008. 1945 [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1946 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1947 and J. Reschke, Ed., "HTTP/1.1, part 2: Message 1948 Semantics", draft-ietf-httpbis-p2-semantics-02 (work in 1949 progress), February 2008. 1951 [Part3] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1952 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1953 and J. Reschke, Ed., "HTTP/1.1, part 3: Message Payload 1954 and Content Negotiation", draft-ietf-httpbis-p3-payload-02 1955 (work in progress), February 2008. 1957 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1958 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1959 and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional 1960 Requests", draft-ietf-httpbis-p4-conditional-02 (work in 1961 progress), February 2008. 1963 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1964 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1965 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 1966 Partial Responses", draft-ietf-httpbis-p5-range-02 (work 1967 in progress), February 2008. 1969 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1970 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1971 and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", 1972 draft-ietf-httpbis-p7-auth-02 (work in progress), 1973 February 2008. 1975 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 1976 Part Three: Message Header Extensions for Non-ASCII Text", 1977 RFC 2047, November 1996. 1979 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1980 Requirement Levels", BCP 14, RFC 2119, March 1997. 1982 20.2. Informative References 1984 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1985 Specification, Implementation", RFC 1305, March 1992. 1987 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1988 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1989 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1991 Appendix A. Compatibility with Previous Versions 1993 A.1. Changes from RFC 2068 1995 A case was missed in the Cache-Control model of HTTP/1.1; s-maxage 1996 was introduced to add this missing case. (Sections 6, 16.2, 16.2.3) 1998 Transfer-coding and message lengths all interact in ways that 1999 required fixing exactly when chunked encoding is used (to allow for 2000 transfer encoding that may not be self delimiting); it was important 2001 to straighten out exactly how message lengths are computed. 2002 (Section 7.2, see also [Part1], [Part3] and [Part5]) 2004 Proxies should be able to add Content-Length when appropriate. 2005 (Section 7.2) 2007 Range request responses would become very verbose if all meta-data 2008 were always returned; by allowing the server to only send needed 2009 headers in a 206 response, this problem can be avoided. 2010 (Section 7.3) 2012 The Cache-Control: max-age directive was not properly defined for 2013 responses. (Section 16.2.3) 2015 Warnings could be cached incorrectly, or not updated appropriately. 2016 (Section 3.2, 4.4, 7.2, 7.3, 16.2.3, and 16.6) Warning also needed to 2017 be a general header, as PUT or other methods may have need for it in 2018 requests. 2020 A.2. Changes from RFC 2616 2022 Clarify denial of service attack avoidance requirement. (Section 12) 2024 Appendix B. Change Log (to be removed by RFC Editor before publication) 2025 B.1. Since RFC2616 2027 Extracted relevant partitions from [RFC2616]. 2029 B.2. Since draft-ietf-httpbis-p6-cache-00 2031 Closed issues: 2033 o : "Trailer" 2034 () 2036 o : 2037 "Invalidation after Update or Delete" 2038 () 2040 o : "Normative 2041 and Informative references" 2043 o : "Date 2044 reference typo" 2046 o : 2047 "Connection header text" 2049 o : 2050 "Informative references" 2052 o : 2053 "ISO-8859-1 Reference" 2055 o : "Normative 2056 up-to-date references" 2058 o : "typo in 2059 13.2.2" 2061 Other changes: 2063 o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress 2064 on ) 2066 B.3. Since draft-ietf-httpbis-p6-cache-01 2068 Closed issues: 2070 o : "rel_path 2071 not used" 2073 Other changes: 2075 o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work 2076 in progress on 2077 ) 2079 o Add explicit references to BNF syntax and rules imported from 2080 other parts of the specification. 2082 Index 2084 A 2085 age 7 2086 Age header 27 2088 C 2089 cache 5 2090 Cache Directives 2091 max-age 32 2092 max-age 33 2093 max-stale 32 2094 min-fresh 32 2095 must-revalidate 34 2096 no-cache 29 2097 no-store 30 2098 no-transform 35 2099 only-if-cached 34 2100 private 29 2101 proxy-revalidate 35 2102 public 29 2103 s-maxage 31 2104 Cache-Control header 27 2105 cacheable 6 2107 E 2108 Expires header 37 2109 explicit expiration time 7 2111 F 2112 first-hand 6 2113 fresh 7 2114 freshness lifetime 7 2116 G 2117 Grammar 2118 Age 27 2119 age-value 27 2120 Cache-Control 28 2121 cache-directive 28 2122 cache-extension 28 2123 cache-request-directive 28 2124 cache-response-directive 28 2125 delta-seconds 27 2126 Expires 37 2127 extension-pragma 38 2128 Pragma 38 2129 pragma-directive 38 2130 Vary 38 2131 warn-agent 40 2132 warn-code 40 2133 warn-date 40 2134 warn-text 40 2135 Warning 40 2136 warning-value 40 2138 H 2139 Headers 2140 Age 27 2141 Cache-Control 27 2142 Expires 37 2143 Pragma 38 2144 Vary 38 2145 Warning 39 2146 heuristic expiration time 7 2148 M 2149 max-age 2150 Cache Directive 32 2151 Cache Directive 33 2152 max-stale 2153 Cache Directive 32 2154 min-fresh 2155 Cache Directive 32 2156 must-revalidate 2157 Cache Directive 34 2159 N 2160 no-cache 2161 Cache Directive 29 2162 no-store 2163 Cache Directive 30 2164 no-transform 2165 Cache Directive 35 2167 O 2168 only-if-cached 2169 Cache Directive 34 2171 P 2172 Pragma header 38 2173 private 2174 Cache Directive 29 2175 proxy-revalidate 2176 Cache Directive 35 2177 public 2178 Cache Directive 29 2180 S 2181 s-maxage 2182 Cache Directive 31 2183 semantically transparent 5 2184 stale 7 2186 V 2187 validator 7 2188 Vary header 38 2190 W 2191 Warning header 39 2193 Authors' Addresses 2195 Roy T. Fielding (editor) 2196 Day Software 2197 23 Corporate Plaza DR, Suite 280 2198 Newport Beach, CA 92660 2199 USA 2201 Phone: +1-949-706-5300 2202 Fax: +1-949-706-5305 2203 Email: fielding@gbiv.com 2204 URI: http://roy.gbiv.com/ 2205 Jim Gettys 2206 One Laptop per Child 2207 21 Oak Knoll Road 2208 Carlisle, MA 01741 2209 USA 2211 Email: jg@laptop.org 2212 URI: http://www.laptop.org/ 2214 Jeffrey C. Mogul 2215 Hewlett-Packard Company 2216 HP Labs, Large Scale Systems Group 2217 1501 Page Mill Road, MS 1177 2218 Palo Alto, CA 94304 2219 USA 2221 Email: JeffMogul@acm.org 2223 Henrik Frystyk Nielsen 2224 Microsoft Corporation 2225 1 Microsoft Way 2226 Redmond, WA 98052 2227 USA 2229 Email: henrikn@microsoft.com 2231 Larry Masinter 2232 Adobe Systems, Incorporated 2233 345 Park Ave 2234 San Jose, CA 95110 2235 USA 2237 Email: LMM@acm.org 2238 URI: http://larry.masinter.net/ 2240 Paul J. Leach 2241 Microsoft Corporation 2242 1 Microsoft Way 2243 Redmond, WA 98052 2245 Email: paulle@microsoft.com 2246 Tim Berners-Lee 2247 World Wide Web Consortium 2248 MIT Computer Science and Artificial Intelligence Laboratory 2249 The Stata Center, Building 32 2250 32 Vassar Street 2251 Cambridge, MA 02139 2252 USA 2254 Email: timbl@w3.org 2255 URI: http://www.w3.org/People/Berners-Lee/ 2257 Yves Lafon (editor) 2258 World Wide Web Consortium 2259 W3C / ERCIM 2260 2004, rte des Lucioles 2261 Sophia-Antipolis, AM 06902 2262 France 2264 Email: ylafon@w3.org 2265 URI: http://www.raubacapeu.net/people/yves/ 2267 Julian F. Reschke (editor) 2268 greenbytes GmbH 2269 Hafenweg 16 2270 Muenster, NW 48155 2271 Germany 2273 Phone: +49 251 2807760 2274 Fax: +49 251 2807761 2275 Email: julian.reschke@greenbytes.de 2276 URI: http://greenbytes.de/tech/webdav/ 2278 Full Copyright Statement 2280 Copyright (C) The IETF Trust (2008). 2282 This document is subject to the rights, licenses and restrictions 2283 contained in BCP 78, and except as set forth therein, the authors 2284 retain all their rights. 2286 This document and the information contained herein are provided on an 2287 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2288 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 2289 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 2290 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 2291 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2292 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2294 Intellectual Property 2296 The IETF takes no position regarding the validity or scope of any 2297 Intellectual Property Rights or other rights that might be claimed to 2298 pertain to the implementation or use of the technology described in 2299 this document or the extent to which any license under such rights 2300 might or might not be available; nor does it represent that it has 2301 made any independent effort to identify any such rights. Information 2302 on the procedures with respect to rights in RFC documents can be 2303 found in BCP 78 and BCP 79. 2305 Copies of IPR disclosures made to the IETF Secretariat and any 2306 assurances of licenses to be made available, or the result of an 2307 attempt made to obtain a general license or permission for the use of 2308 such proprietary rights by implementers or users of this 2309 specification can be obtained from the IETF on-line IPR repository at 2310 http://www.ietf.org/ipr. 2312 The IETF invites any interested party to bring to its attention any 2313 copyrights, patents or patent applications, or other proprietary 2314 rights that may cover technology that may be required to implement 2315 this standard. Please address the information to the IETF at 2316 ietf-ipr@ietf.org. 2318 Acknowledgment 2320 Funding for the RFC Editor function is provided by the IETF 2321 Administrative Support Activity (IASA).