idnits 2.17.1 draft-ietf-httpbis-p6-cache-20.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC2616, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 16, 2012) is 4301 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) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-20 -- 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) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis Working Group R. Fielding, Ed. 3 Internet-Draft Adobe 4 Obsoletes: 2616 (if approved) Y. Lafon, Ed. 5 Intended status: Standards Track W3C 6 Expires: January 17, 2013 M. Nottingham, Ed. 7 Rackspace 8 J. Reschke, Ed. 9 greenbytes 10 July 16, 2012 12 HTTP/1.1, part 6: Caching 13 draft-ietf-httpbis-p6-cache-20 15 Abstract 17 The Hypertext Transfer Protocol (HTTP) is an application-level 18 protocol for distributed, collaborative, hypertext information 19 systems. This document defines requirements on HTTP caches and the 20 associated header fields that control cache behavior or indicate 21 cacheable response messages. 23 Editorial Note (To be removed by RFC Editor) 25 Discussion of this draft takes place on the HTTPBIS working group 26 mailing list (ietf-http-wg@w3.org), which is archived at 27 . 29 The current issues list is at 30 and related 31 documents (including fancy diffs) can be found at 32 . 34 The changes in this draft are summarized in Appendix D.1. 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at http://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on January 17, 2013. 53 Copyright Notice 55 Copyright (c) 2012 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (http://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 This document may contain material from IETF Documents or IETF 69 Contributions published or made publicly available before November 70 10, 2008. The person(s) controlling the copyright in some of this 71 material may not have granted the IETF Trust the right to allow 72 modifications of such material outside the IETF Standards Process. 73 Without obtaining an adequate license from the person(s) controlling 74 the copyright in such materials, this document may not be modified 75 outside the IETF Standards Process, and derivative works of it may 76 not be created outside the IETF Standards Process, except to format 77 it for publication as an RFC or to translate it into languages other 78 than English. 80 Table of Contents 82 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 83 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 4 84 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 85 1.3. Conformance and Error Handling . . . . . . . . . . . . . . 6 86 1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 87 1.4.1. Delta Seconds . . . . . . . . . . . . . . . . . . . . 7 88 2. Overview of Cache Operation . . . . . . . . . . . . . . . . . 7 89 3. Storing Responses in Caches . . . . . . . . . . . . . . . . . 8 90 3.1. Storing Incomplete Responses . . . . . . . . . . . . . . . 9 91 3.2. Storing Responses to Authenticated Requests . . . . . . . 9 92 4. Constructing Responses from Caches . . . . . . . . . . . . . . 10 93 4.1. Freshness Model . . . . . . . . . . . . . . . . . . . . . 11 94 4.1.1. Calculating Freshness Lifetime . . . . . . . . . . . . 12 95 4.1.2. Calculating Heuristic Freshness . . . . . . . . . . . 12 96 4.1.3. Calculating Age . . . . . . . . . . . . . . . . . . . 13 97 4.1.4. Serving Stale Responses . . . . . . . . . . . . . . . 15 98 4.2. Validation Model . . . . . . . . . . . . . . . . . . . . . 16 99 4.2.1. Freshening Responses with 304 Not Modified . . . . . . 16 100 4.3. Using Negotiated Responses . . . . . . . . . . . . . . . . 17 101 4.4. Combining Partial Content . . . . . . . . . . . . . . . . 18 102 5. Updating Caches with HEAD Responses . . . . . . . . . . . . . 19 103 6. Request Methods that Invalidate . . . . . . . . . . . . . . . 19 104 7. Header Field Definitions . . . . . . . . . . . . . . . . . . . 20 105 7.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 106 7.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 20 107 7.2.1. Request Cache-Control Directives . . . . . . . . . . . 21 108 7.2.2. Response Cache-Control Directives . . . . . . . . . . 23 109 7.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 26 110 7.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 28 111 7.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 28 112 7.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 113 7.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 30 114 7.6.1. 110 Response is Stale . . . . . . . . . . . . . . . . 31 115 7.6.2. 111 Revalidation Failed . . . . . . . . . . . . . . . 32 116 7.6.3. 112 Disconnected Operation . . . . . . . . . . . . . . 32 117 7.6.4. 113 Heuristic Expiration . . . . . . . . . . . . . . . 32 118 7.6.5. 199 Miscellaneous Warning . . . . . . . . . . . . . . 32 119 7.6.6. 214 Transformation Applied . . . . . . . . . . . . . . 32 120 7.6.7. 299 Miscellaneous Persistent Warning . . . . . . . . . 32 121 7.6.8. Warn Code Extensions . . . . . . . . . . . . . . . . . 32 122 8. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 33 123 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 124 9.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 33 125 9.2. Warn Code Registry . . . . . . . . . . . . . . . . . . . . 34 126 9.3. Header Field Registration . . . . . . . . . . . . . . . . 34 127 10. Security Considerations . . . . . . . . . . . . . . . . . . . 35 128 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 35 129 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 35 130 12.1. Normative References . . . . . . . . . . . . . . . . . . . 35 131 12.2. Informative References . . . . . . . . . . . . . . . . . . 36 132 Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 36 133 Appendix B. Imported ABNF . . . . . . . . . . . . . . . . . . . . 37 134 Appendix C. Collected ABNF . . . . . . . . . . . . . . . . . . . 38 135 Appendix D. Change Log (to be removed by RFC Editor before 136 publication) . . . . . . . . . . . . . . . . . . . . 39 137 D.1. Since draft-ietf-httpbis-p6-cache-19 . . . . . . . . . . . 39 138 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 140 1. Introduction 142 HTTP is typically used for distributed information systems, where 143 performance can be improved by the use of response caches. This 144 document defines aspects of HTTP/1.1 related to caching and reusing 145 response messages. 147 1.1. Purpose 149 An HTTP cache is a local store of response messages and the subsystem 150 that controls its message storage, retrieval, and deletion. A cache 151 stores cacheable responses in order to reduce the response time and 152 network bandwidth consumption on future, equivalent requests. Any 153 client or server MAY employ a cache, though a cache cannot be used by 154 a server that is acting as a tunnel. 156 The goal of caching in HTTP/1.1 is to significantly improve 157 performance by reusing a prior response message to satisfy a current 158 request. A stored response is considered "fresh", as defined in 159 Section 4.1, if the response can be reused without "validation" 160 (checking with the origin server to see if the cached response 161 remains valid for this request). A fresh cache response can 162 therefore reduce both latency and network transfers each time it is 163 reused. When a cached response is not fresh, it might still be 164 reusable if it can be freshened by validation (Section 4.2) or if the 165 origin is unavailable. 167 1.2. Terminology 169 This specification uses a number of terms to refer to the roles 170 played by participants in, and objects of, HTTP caching. 172 cache 174 A conformant implementation of a HTTP cache. Note that this 175 implies an HTTP/1.1 cache; this specification does not define 176 conformance for HTTP/1.0 caches. 178 shared cache 180 A cache that stores responses to be reused by more than one user; 181 usually (but not always) deployed as part of an intermediary. 183 private cache 185 A cache that is dedicated to a single user. 187 cacheable 189 A response is cacheable if a cache is allowed to store a copy of 190 the response message for use in answering subsequent requests. 191 Even when a response is cacheable, there might be additional 192 constraints on whether a cache can use the stored copy to satisfy 193 a particular request. 195 explicit expiration time 197 The time at which the origin server intends that a representation 198 no longer be returned by a cache without further validation. 200 heuristic expiration time 202 An expiration time assigned by a cache when no explicit expiration 203 time is available. 205 age 207 The age of a response is the time since it was sent by, or 208 successfully validated with, the origin server. 210 first-hand 212 A response is first-hand if the freshness model is not in use; 213 i.e., its age is 0. 215 freshness lifetime 217 The length of time between the generation of a response and its 218 expiration time. 220 fresh 222 A response is fresh if its age has not yet exceeded its freshness 223 lifetime. 225 stale 227 A response is stale if its age has passed its freshness lifetime 228 (either explicit or heuristic). 230 validator 232 A protocol element (e.g., an entity-tag or a Last-Modified time) 233 that is used to find out whether a stored response is an 234 equivalent copy of a representation. See Section 2.1 of [Part4]. 236 strong validator 238 A validator that is defined by the origin server such that its 239 current value will change if the representation body changes; 240 i.e., an entity-tag that is not marked as weak (Section 2.3 of 241 [Part4]) or, if no entity-tag is provided, a Last-Modified value 242 that is strong in the sense defined by Section 2.2.2 of [Part4]. 244 1.3. Conformance and Error Handling 246 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 247 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 248 document are to be interpreted as described in [RFC2119]. 250 This specification targets conformance criteria according to the role 251 of a participant in HTTP communication. Hence, HTTP requirements are 252 placed on senders, recipients, clients, servers, user agents, 253 intermediaries, origin servers, proxies, gateways, or caches, 254 depending on what behavior is being constrained by the requirement. 255 See Section 2 of [Part1] for definitions of these terms. 257 The verb "generate" is used instead of "send" where a requirement 258 differentiates between creating a protocol element and merely 259 forwarding a received element downstream. 261 An implementation is considered conformant if it complies with all of 262 the requirements associated with the roles it partakes in HTTP. Note 263 that SHOULD-level requirements are relevant here, unless one of the 264 documented exceptions is applicable. 266 This document also uses ABNF to define valid protocol elements 267 (Section 1.4). In addition to the prose requirements placed upon 268 them, senders MUST NOT generate protocol elements that do not match 269 the grammar defined by the ABNF rules for those protocol elements 270 that are applicable to the sender's role. If a received protocol 271 element is processed, the recipient MUST be able to parse any value 272 that would match the ABNF rules for that protocol element, excluding 273 only those rules not applicable to the recipient's role. 275 Unless noted otherwise, a recipient MAY attempt to recover a usable 276 protocol element from an invalid construct. HTTP does not define 277 specific error handling mechanisms except when they have a direct 278 impact on security, since different applications of the protocol 279 require different error handling strategies. For example, a Web 280 browser might wish to transparently recover from a response where the 281 Location header field doesn't parse according to the ABNF, whereas a 282 systems control client might consider any form of error recovery to 283 be dangerous. 285 1.4. Syntax Notation 287 This specification uses the Augmented Backus-Naur Form (ABNF) 288 notation of [RFC5234] with the list rule extension defined in Section 289 1.2 of [Part1]. Appendix B describes rules imported from other 290 documents. Appendix C shows the collected ABNF with the list rule 291 expanded. 293 1.4.1. Delta Seconds 295 The delta-seconds rule specifies a non-negative integer, representing 296 time in seconds. 298 delta-seconds = 1*DIGIT 300 If an implementation receives a delta-seconds value larger than the 301 largest positive integer it can represent, or if any of its 302 subsequent calculations overflows, it MUST consider the value to be 303 2147483648 (2^31). Recipients parsing a delta-seconds value MUST use 304 an arithmetic type of at least 31 bits of range, and senders MUST NOT 305 send delta-seconds with a value greater than 2147483648. 307 2. Overview of Cache Operation 309 Proper cache operation preserves the semantics of HTTP transfers 310 ([Part2]) while eliminating the transfer of information already held 311 in the cache. Although caching is an entirely OPTIONAL feature of 312 HTTP, we assume that reusing the cached response is desirable and 313 that such reuse is the default behavior when no requirement or 314 locally-desired configuration prevents it. Therefore, HTTP cache 315 requirements are focused on preventing a cache from either storing a 316 non-reusable response or reusing a stored response inappropriately. 318 Each cache entry consists of a cache key and one or more HTTP 319 responses corresponding to prior requests that used the same key. 320 The most common form of cache entry is a successful result of a 321 retrieval request: i.e., a 200 (OK) response containing a 322 representation of the resource identified by the request target. 323 However, it is also possible to cache negative results (e.g., 404 324 (Not Found), incomplete results (e.g., 206 (Partial Content)), and 325 responses to methods other than GET if the method's definition allows 326 such caching and defines something suitable for use as a cache key. 328 The default cache key consists of the request method and target URI. 329 However, since HTTP caches in common use today are typically limited 330 to caching responses to GET, many implementations simply decline 331 other methods and use only the URI as the key. 333 If a request target is subject to content negotiation, its cache 334 entry might consist of multiple stored responses, each differentiated 335 by a secondary key for the values of the original request's selecting 336 header fields (Section 4.3). 338 3. Storing Responses in Caches 340 A cache MUST NOT store a response to any request, unless: 342 o The request method is understood by the cache and defined as being 343 cacheable, and 345 o the response status code is understood by the cache, and 347 o the "no-store" cache directive (see Section 7.2) does not appear 348 in request or response header fields, and 350 o the "private" cache response directive (see Section 7.2.2.2) does 351 not appear in the response, if the cache is shared, and 353 o the Authorization header field (see Section 4.1 of [Part7]) does 354 not appear in the request, if the cache is shared, unless the 355 response explicitly allows it (see Section 3.2), and 357 o the response either: 359 * contains an Expires header field (see Section 7.3), or 361 * contains a max-age response cache directive (see 362 Section 7.2.2.7), or 364 * contains a s-maxage response cache directive and the cache is 365 shared, or 367 * contains a Cache Control Extension (see Section 7.2.3) that 368 allows it to be cached, or 370 * has a status code that can be served with heuristic freshness 371 (see Section 4.1.2). 373 Note that any of the requirements listed above can be overridden by a 374 cache-control extension; see Section 7.2.3. 376 In this context, a cache has "understood" a request method or a 377 response status code if it recognizes it and implements any cache- 378 specific behavior. 380 Note that, in normal operation, many caches will not store a response 381 that has neither a cache validator nor an explicit expiration time, 382 as such responses are not usually useful to store. However, caches 383 are not prohibited from storing such responses. 385 3.1. Storing Incomplete Responses 387 A response message is considered complete when all of the octets 388 indicated by the message framing ([Part1]) are received prior to the 389 connection being closed. If the request is GET, the response status 390 is 200 (OK), and the entire response header block has been received, 391 a cache MAY store an incomplete response message body if the cache 392 entry is recorded as incomplete. Likewise, a 206 (Partial Content) 393 response MAY be stored as if it were an incomplete 200 (OK) cache 394 entry. However, a cache MUST NOT store incomplete or partial content 395 responses if it does not support the Range and Content-Range header 396 fields or if it does not understand the range units used in those 397 fields. 399 A cache MAY complete a stored incomplete response by making a 400 subsequent range request ([Part5]) and combining the successful 401 response with the stored entry, as defined in Section 4.4. A cache 402 MUST NOT use an incomplete response to answer requests unless the 403 response has been made complete or the request is partial and 404 specifies a range that is wholly within the incomplete response. A 405 cache MUST NOT send a partial response to a client without explicitly 406 marking it as such using the 206 (Partial Content) status code. 408 3.2. Storing Responses to Authenticated Requests 410 A shared cache MUST NOT use a cached response to a request with an 411 Authorization header field (Section 4.1 of [Part7]) to satisfy any 412 subsequent request unless a cache directive that allows such 413 responses to be stored is present in the response. 415 In this specification, the following Cache-Control response 416 directives (Section 7.2.2) have such an effect: must-revalidate, 417 public, s-maxage. 419 Note that cached responses that contain the "must-revalidate" and/or 420 "s-maxage" response directives are not allowed to be served stale 421 (Section 4.1.4) by shared caches. In particular, a response with 422 either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to 423 satisfy a subsequent request without revalidating it on the origin 424 server. 426 4. Constructing Responses from Caches 428 For a presented request, a cache MUST NOT return a stored response, 429 unless: 431 o The presented effective request URI (Section 5.5 of [Part1]) and 432 that of the stored response match, and 434 o the request method associated with the stored response allows it 435 to be used for the presented request, and 437 o selecting header fields nominated by the stored response (if any) 438 match those presented (see Section 4.3), and 440 o the presented request does not contain the no-cache pragma 441 (Section 7.4), nor the no-cache cache directive (Section 7.2.1), 442 unless the stored response is successfully validated 443 (Section 4.2), and 445 o the stored response does not contain the no-cache cache directive 446 (Section 7.2.2.3), unless it is successfully validated 447 (Section 4.2), and 449 o the stored response is either: 451 * fresh (see Section 4.1), or 453 * allowed to be served stale (see Section 4.1.4), or 455 * successfully validated (see Section 4.2). 457 Note that any of the requirements listed above can be overridden by a 458 cache-control extension; see Section 7.2.3. 460 When a stored response is used to satisfy a request without 461 validation, a cache MUST include a single Age header field 462 (Section 7.1) in the response with a value equal to the stored 463 response's current_age; see Section 4.1.3. 465 A cache MUST write through requests with methods that are unsafe 466 (Section 2.1.1 of [Part2]) to the origin server; i.e., a cache is not 467 allowed to generate a reply to such a request before having forwarded 468 the request and having received a corresponding response. 470 Also, note that unsafe requests might invalidate already stored 471 responses; see Section 6. 473 When more than one suitable response is stored, a cache MUST use the 474 most recent response (as determined by the Date header field). It 475 can also forward a request with "Cache-Control: max-age=0" or "Cache- 476 Control: no-cache" to disambiguate which response to use. 478 A cache that does not have a clock available MUST NOT use stored 479 responses without revalidating them on every use. A cache, 480 especially a shared cache, SHOULD use a mechanism, such as NTP 481 [RFC1305], to synchronize its clock with a reliable external 482 standard. 484 4.1. Freshness Model 486 When a response is "fresh" in the cache, it can be used to satisfy 487 subsequent requests without contacting the origin server, thereby 488 improving efficiency. 490 The primary mechanism for determining freshness is for an origin 491 server to provide an explicit expiration time in the future, using 492 either the Expires header field (Section 7.3) or the max-age response 493 cache directive (Section 7.2.2.7). Generally, origin servers will 494 assign future explicit expiration times to responses in the belief 495 that the representation is not likely to change in a semantically 496 significant way before the expiration time is reached. 498 If an origin server wishes to force a cache to validate every 499 request, it can assign an explicit expiration time in the past to 500 indicate that the response is already stale. Compliant caches will 501 normally validate the cached response before reusing it for 502 subsequent requests (see Section 4.1.4). 504 Since origin servers do not always provide explicit expiration times, 505 a cache MAY assign a heuristic expiration time when an explicit time 506 is not specified, employing algorithms that use other header field 507 values (such as the Last-Modified time) to estimate a plausible 508 expiration time. This specification does not provide specific 509 algorithms, but does impose worst-case constraints on their results. 511 The calculation to determine if a response is fresh is: 513 response_is_fresh = (freshness_lifetime > current_age) 515 The freshness_lifetime is defined in Section 4.1.1; the current_age 516 is defined in Section 4.1.3. 518 Additionally, clients can influence freshness calculation -- either 519 constraining it relaxing it -- by using the max-age and min-fresh 520 request cache directives. See Section 7.2.1 for details. 522 Note that freshness applies only to cache operation; it cannot be 523 used to force a user agent to refresh its display or reload a 524 resource. See Section 8 for an explanation of the difference between 525 caches and history mechanisms. 527 4.1.1. Calculating Freshness Lifetime 529 A cache can calculate the freshness lifetime (denoted as 530 freshness_lifetime) of a response by using the first match of: 532 o If the cache is shared and the s-maxage response cache directive 533 (Section 7.2.2.8) is present, use its value, or 535 o If the max-age response cache directive (Section 7.2.2.7) is 536 present, use its value, or 538 o If the Expires response header field (Section 7.3) is present, use 539 its value minus the value of the Date response header field, or 541 o Otherwise, no explicit expiration time is present in the response. 542 A heuristic freshness lifetime might be applicable; see 543 Section 4.1.2. 545 Note that this calculation is not vulnerable to clock skew, since all 546 of the information comes from the origin server. 548 When there is more than one value present for a given directive 549 (e.g., two Expires header fields, multiple Cache-Control: max-age 550 directives), it is considered invalid. Caches are encouraged to 551 consider responses that have invalid freshness information to be 552 stale. 554 4.1.2. Calculating Heuristic Freshness 556 If no explicit expiration time is present in a stored response that 557 has a status code whose definition allows heuristic freshness to be 558 used (including the following in Section 4 of [Part2]: 200 (OK), 203 559 (Non-Authoritative Information), 206 (Partial Content), 300 (Multiple 560 Choices), 301 (Moved Permanently) and 410 (Gone)), a cache MAY 561 calculate a heuristic expiration time. A cache MUST NOT use 562 heuristics to determine freshness for responses with status codes 563 that do not explicitly allow it. 565 When a heuristic is used to calculate freshness lifetime, a cache 566 SHOULD attach a Warning header field with a 113 warn-code to the 567 response if its current_age is more than 24 hours and such a warning 568 is not already present. 570 Also, if the response has a Last-Modified header field (Section 2.2 571 of [Part4]), caches are encouraged to use a heuristic expiration 572 value that is no more than some fraction of the interval since that 573 time. A typical setting of this fraction might be 10%. 575 Note: Section 13.9 of [RFC2616] prohibited caches from calculating 576 heuristic freshness for URIs with query components (i.e., those 577 containing '?'). In practice, this has not been widely 578 implemented. Therefore, servers are encouraged to send explicit 579 directives (e.g., Cache-Control: no-cache) if they wish to 580 preclude caching. 582 4.1.3. Calculating Age 584 HTTP/1.1 uses the Age header field to convey the estimated age of the 585 response message when obtained from a cache. The Age field value is 586 the cache's estimate of the amount of time since the response was 587 generated or validated by the origin server. In essence, the Age 588 value is the sum of the time that the response has been resident in 589 each of the caches along the path from the origin server, plus the 590 amount of time it has been in transit along network paths. 592 The following data is used for the age calculation: 594 age_value 596 The term "age_value" denotes the value of the Age header field 597 (Section 7.1), in a form appropriate for arithmetic operation; or 598 0, if not available. 600 date_value 602 HTTP/1.1 requires origin servers to send a Date header field, if 603 possible, with every response, giving the time at which the 604 response was generated. The term "date_value" denotes the value 605 of the Date header field, in a form appropriate for arithmetic 606 operations. See Section 9.10 of [Part2] for the definition of the 607 Date header field, and for requirements regarding responses 608 without it. 610 now 612 The term "now" means "the current value of the clock at the host 613 performing the calculation". A cache SHOULD use NTP ([RFC1305]) 614 or some similar protocol to synchronize its clocks to a globally 615 accurate time standard. 617 request_time 619 The current value of the clock at the host at the time the request 620 resulting in the stored response was made. 622 response_time 624 The current value of the clock at the host at the time the 625 response was received. 627 A response's age can be calculated in two entirely independent ways: 629 1. the "apparent_age": response_time minus date_value, if the local 630 clock is reasonably well synchronized to the origin server's 631 clock. If the result is negative, the result is replaced by 632 zero. 634 2. the "corrected_age_value", if all of the caches along the 635 response path implement HTTP/1.1. A cache MUST interpret this 636 value relative to the time the request was initiated, not the 637 time that the response was received. 639 apparent_age = max(0, response_time - date_value); 641 response_delay = response_time - request_time; 642 corrected_age_value = age_value + response_delay; 644 These SHOULD be combined as 646 corrected_initial_age = max(apparent_age, corrected_age_value); 648 unless the cache is confident in the value of the Age header field 649 (e.g., because there are no HTTP/1.0 hops in the Via header field), 650 in which case the corrected_age_value MAY be used as the 651 corrected_initial_age. 653 The current_age of a stored response can then be calculated by adding 654 the amount of time (in seconds) since the stored response was last 655 validated by the origin server to the corrected_initial_age. 657 resident_time = now - response_time; 658 current_age = corrected_initial_age + resident_time; 660 Additionally, to avoid common problems in date parsing: 662 o HTTP/1.1 clients and caches SHOULD assume that an RFC-850 date 663 which appears to be more than 50 years in the future is in fact in 664 the past (this helps solve the "year 2000" problem). 666 o Although all date formats are specified to be case-sensitive, 667 recipients SHOULD match day, week and timezone names case- 668 insensitively. 670 o An HTTP/1.1 implementation MAY internally represent a parsed 671 Expires date as earlier than the proper value, but MUST NOT 672 internally represent a parsed Expires date as later than the 673 proper value. 675 o All expiration-related calculations MUST be done in GMT. The 676 local time zone MUST NOT influence the calculation or comparison 677 of an age or expiration time. 679 o If an HTTP header field incorrectly carries a date value with a 680 time zone other than GMT, it MUST be converted into GMT using the 681 most conservative possible conversion. 683 4.1.4. Serving Stale Responses 685 A "stale" response is one that either has explicit expiry information 686 or is allowed to have heuristic expiry calculated, but is not fresh 687 according to the calculations in Section 4.1. 689 A cache MUST NOT return a stale response if it is prohibited by an 690 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" 691 cache directive, a "must-revalidate" cache-response-directive, or an 692 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 693 see Section 7.2.2). 695 A cache MUST NOT return stale responses unless it is disconnected 696 (i.e., it cannot contact the origin server or otherwise find a 697 forward path) or doing so is explicitly allowed (e.g., by the max- 698 stale request directive; see Section 7.2.1). 700 A cache SHOULD append a Warning header field with the 110 warn-code 701 (see Section 7.6) to stale responses. Likewise, a cache SHOULD add 702 the 112 warn-code to stale responses if the cache is disconnected. 704 If a cache receives a first-hand response (either an entire response, 705 or a 304 (Not Modified) response) that it would normally forward to 706 the requesting client, and the received response is no longer fresh, 707 the cache can forward it to the requesting client without adding a 708 new Warning (but without removing any existing Warning header 709 fields). A cache shouldn't attempt to validate a response simply 710 because that response became stale in transit. 712 4.2. Validation Model 714 When a cache has one or more stored responses for a requested URI, 715 but cannot serve any of them (e.g., because they are not fresh, or 716 one cannot be selected; see Section 4.3), it can use the conditional 717 request mechanism [Part4] in the forwarded request to give the origin 718 server an opportunity to both select a valid stored response to be 719 used, and to update it. This process is known as "validating" or 720 "revalidating" the stored response. 722 When sending such a conditional request, a cache adds an If-Modified- 723 Since header field whose value is that of the Last-Modified header 724 field from the selected (see Section 4.3) stored response, if 725 available. 727 Additionally, a cache can add an If-None-Match header field whose 728 value is that of the ETag header field(s) from all responses stored 729 for the requested URI, if present. However, if any of the stored 730 responses contains only partial content, the cache shouldn't include 731 its entity-tag in the If-None-Match header field unless the request 732 is for a range that would be fully satisfied by that stored response. 734 Cache handling of a response to a conditional request is dependent 735 upon its status code: 737 o A 304 (Not Modified) response status code indicates that the 738 stored response can be updated and reused; see Section 4.2.1. 740 o A full response (i.e., one with a response body) indicates that 741 none of the stored responses nominated in the conditional request 742 is suitable. Instead, the cache can use the full response to 743 satisfy the request and MAY replace the stored response(s). 745 o However, if a cache receives a 5xx (Server Error) response while 746 attempting to validate a response, it can either forward this 747 response to the requesting client, or act as if the server failed 748 to respond. In the latter case, it can return a previously stored 749 response (see Section 4.1.4). 751 4.2.1. Freshening Responses with 304 Not Modified 753 When a cache receives a 304 (Not Modified) response and already has 754 one or more stored 200 (OK) responses for the same cache key, the 755 cache needs to identify which of the stored responses are updated by 756 this new response and then update the stored response(s) with the new 757 information provided in the 304 response. 759 o If the new response contains a strong validator, then that strong 760 validator identifies the selected representation. All of the 761 stored responses with the same strong validator are selected. If 762 none of the stored responses contain the same strong validator, 763 then this new response corresponds to a new selected 764 representation and MUST NOT update the existing stored responses. 766 o If the new response contains a weak validator and that validator 767 corresponds to one of the cache's stored responses, then the most 768 recent of those matching stored responses is selected. 770 o If the new response does not include any form of validator, there 771 is only one stored response, and that stored response also lacks a 772 validator, then that stored response is selected. 774 If a stored response is selected for update, the cache MUST: 776 o delete any Warning header fields in the stored response with warn- 777 code 1xx (see Section 7.6); 779 o retain any Warning header fields in the stored response with warn- 780 code 2xx; and, 782 o use other header fields provided in the 304 (Not Modified) 783 response to replace all instances of the corresponding header 784 fields in the stored response. 786 4.3. Using Negotiated Responses 788 When a cache receives a request that can be satisfied by a stored 789 response that has a Vary header field (Section 7.5), it MUST NOT use 790 that response unless all of the selecting header fields nominated by 791 the Vary header field match in both the original request (i.e., that 792 associated with the stored response), and the presented request. 794 The selecting header fields from two requests are defined to match if 795 and only if those in the first request can be transformed to those in 796 the second request by applying any of the following: 798 o adding or removing whitespace, where allowed in the header field's 799 syntax 801 o combining multiple header fields with the same field name (see 802 Section 3.2 of [Part1]) 804 o normalizing both header field values in a way that is known to 805 have identical semantics, according to the header field's 806 specification (e.g., re-ordering field values when order is not 807 significant; case-normalization, where values are defined to be 808 case-insensitive) 810 If (after any normalization that might take place) a header field is 811 absent from a request, it can only match another request if it is 812 also absent there. 814 A Vary header field-value of "*" always fails to match, and 815 subsequent requests to that resource can only be properly interpreted 816 by the origin server. 818 The stored response with matching selecting header fields is known as 819 the selected response. 821 If multiple selected responses are available, the most recent 822 response (as determined by the Date header field) is used; see 823 Section 4. 825 If no selected response is available, the cache can forward the 826 presented request to the origin server in a conditional request; see 827 Section 4.2. 829 4.4. Combining Partial Content 831 A response might transfer only a partial representation if the 832 connection closed prematurely or if the request used one or more 833 Range specifiers ([Part5]). After several such transfers, a cache 834 might have received several ranges of the same representation. A 835 cache MAY combine these ranges into a single stored response, and 836 reuse that response to satisfy later requests, if they all share the 837 same strong validator and the cache complies with the client 838 requirements in Section 4.2 of [Part5]. 840 When combining the new response with one or more stored responses, a 841 cache MUST: 843 o delete any Warning header fields in the stored response with warn- 844 code 1xx (see Section 7.6); 846 o retain any Warning header fields in the stored response with warn- 847 code 2xx; and, 849 o use other header fields provided in the new response, aside from 850 Content-Range, to replace all instances of the corresponding 851 header fields in the stored response. 853 5. Updating Caches with HEAD Responses 855 A response to the HEAD method is identical to what an equivalent 856 request made with a GET would have been, except it lacks a body. 857 This property of HEAD responses is used to both invalidate and update 858 cached GET responses. 860 If one or more stored GET responses can be selected (as per 861 Section 4.3) for a HEAD request, and the Content-Length, ETag or 862 Last-Modified value of a HEAD response differs from that in a 863 selected GET response, the cache MUST consider that selected response 864 to be stale. 866 If the Content-Length, ETag and Last-Modified values of a HEAD 867 response (when present) are the same as that in a selected GET 868 response (as per Section 4.3), the cache SHOULD update the remaining 869 header fields in the stored response using the following rules: 871 o delete any Warning header fields in the stored response with warn- 872 code 1xx (see Section 7.6); 874 o retain any Warning header fields in the stored response with warn- 875 code 2xx; and, 877 o use other header fields provided in the response to replace all 878 instances of the corresponding header fields in the stored 879 response. 881 6. Request Methods that Invalidate 883 Because unsafe request methods (Section 2.1.1 of [Part2]) such as 884 PUT, POST or DELETE have the potential for changing state on the 885 origin server, intervening caches can use them to keep their contents 886 up-to-date. 888 A cache MUST invalidate the effective Request URI (Section 5.5 of 889 [Part1]) as well as the URI(s) in the Location and Content-Location 890 response header fields (if present) when a non-error response to a 891 request with an unsafe method is received. 893 However, a cache MUST NOT invalidate a URI from a Location or 894 Content-Location response header field if the host part of that URI 895 differs from the host part in the effective request URI (Section 5.5 896 of [Part1]). This helps prevent denial of service attacks. 898 A cache MUST invalidate the effective request URI (Section 5.5 of 899 [Part1]) when it receives a non-error response to a request with a 900 method whose safety is unknown. 902 Here, a "non-error response" is one with a 2xx (Successful) or 3xx 903 (Redirection) status code. "Invalidate" means that the cache will 904 either remove all stored responses related to the effective request 905 URI, or will mark these as "invalid" and in need of a mandatory 906 validation before they can be returned in response to a subsequent 907 request. 909 Note that this does not guarantee that all appropriate responses are 910 invalidated. For example, the request that caused the change at the 911 origin server might not have gone through the cache where a response 912 is stored. 914 7. Header Field Definitions 916 This section defines the syntax and semantics of HTTP/1.1 header 917 fields related to caching. 919 7.1. Age 921 The "Age" header field conveys the sender's estimate of the amount of 922 time since the response was generated or successfully validated at 923 the origin server. Age values are calculated as specified in 924 Section 4.1.3. 926 Age = delta-seconds 928 Age field-values are non-negative integers, representing time in 929 seconds (see Section 1.4.1). 931 The presence of an Age header field in a response implies that a 932 response is not first-hand. However, the converse is not true, since 933 HTTP/1.0 caches might not implement the Age header field. 935 7.2. Cache-Control 937 The "Cache-Control" header field is used to specify directives for 938 caches along the request/response chain. Such cache directives are 939 unidirectional in that the presence of a directive in a request does 940 not imply that the same directive is to be given in the response. 942 A cache MUST obey the requirements of the Cache-Control directives 943 defined in this section. See Section 7.2.3 for information about how 944 Cache-Control directives defined elsewhere are handled. 946 Note: HTTP/1.0 caches might not implement Cache-Control and might 947 only implement Pragma: no-cache (see Section 7.4). 949 A proxy, whether or not it implements a cache, MUST pass cache 950 directives through in forwarded messages, regardless of their 951 significance to that application, since the directives might be 952 applicable to all recipients along the request/response chain. It is 953 not possible to target a directive to a specific cache. 955 Cache directives are identified by a token, to be compared case- 956 insensitively, and have an optional argument, that can use both token 957 and quoted-string syntax. For the directives defined below that 958 define arguments, recipients ought to accept both forms, even if one 959 is documented to be preferred. For any directive not defined by this 960 specification, recipients MUST accept both forms. 962 Cache-Control = 1#cache-directive 964 cache-directive = token [ "=" ( token / quoted-string ) ] 966 For the cache directives defined below, no argument is defined (nor 967 allowed) otherwise stated otherwise. 969 7.2.1. Request Cache-Control Directives 971 7.2.1.1. no-cache 973 The "no-cache" request directive indicates that a cache MUST NOT use 974 a stored response to satisfy the request without successful 975 validation on the origin server. 977 7.2.1.2. no-store 979 The "no-store" request directive indicates that a cache MUST NOT 980 store any part of either this request or any response to it. This 981 directive applies to both private and shared caches. "MUST NOT 982 store" in this context means that the cache MUST NOT intentionally 983 store the information in non-volatile storage, and MUST make a best- 984 effort attempt to remove the information from volatile storage as 985 promptly as possible after forwarding it. 987 This directive is NOT a reliable or sufficient mechanism for ensuring 988 privacy. In particular, malicious or compromised caches might not 989 recognize or obey this directive, and communications networks might 990 be vulnerable to eavesdropping. 992 Note that if a request containing this directive is satisfied from a 993 cache, the no-store request directive does not apply to the already 994 stored response. 996 7.2.1.3. max-age 998 Argument syntax: 1000 delta-seconds (see Section 1.4.1) 1002 The "max-age" request directive indicates that the client is 1003 unwilling to accept a response whose age is greater than the 1004 specified number of seconds. Unless the max-stale request directive 1005 is also present, the client is not willing to accept a stale 1006 response. 1008 Note: This directive uses the token form of the argument syntax; 1009 e.g., 'max-age=5', not 'max-age="5"'. Senders SHOULD NOT use the 1010 quoted-string form. 1012 7.2.1.4. max-stale 1014 Argument syntax: 1016 delta-seconds (see Section 1.4.1) 1018 The "max-stale" request directive indicates that the client is 1019 willing to accept a response that has exceeded its expiration time. 1020 If max-stale is assigned a value, then the client is willing to 1021 accept a response that has exceeded its expiration time by no more 1022 than the specified number of seconds. If no value is assigned to 1023 max-stale, then the client is willing to accept a stale response of 1024 any age. 1026 Note: This directive uses the token form of the argument syntax; 1027 e.g., 'max-stale=10', not 'max-stale="10"'. Senders SHOULD NOT use 1028 the quoted-string form. 1030 7.2.1.5. min-fresh 1032 Argument syntax: 1034 delta-seconds (see Section 1.4.1) 1036 The "min-fresh" request directive indicates that the client is 1037 willing to accept a response whose freshness lifetime is no less than 1038 its current age plus the specified time in seconds. That is, the 1039 client wants a response that will still be fresh for at least the 1040 specified number of seconds. 1042 Note: This directive uses the token form of the argument syntax; 1043 e.g., 'min-fresh=20', not 'min-fresh="20"'. Senders SHOULD NOT use 1044 the quoted-string form. 1046 7.2.1.6. no-transform 1048 The "no-transform" request directive indicates that an intermediary 1049 (whether or not it implements a cache) MUST NOT change the Content- 1050 Encoding, Content-Range or Content-Type request header fields, nor 1051 the request representation. 1053 7.2.1.7. only-if-cached 1055 The "only-if-cached" request directive indicates that the client only 1056 wishes to obtain a stored response. If it receives this directive, a 1057 cache SHOULD either respond using a stored response that is 1058 consistent with the other constraints of the request, or respond with 1059 a 504 (Gateway Timeout) status code. If a group of caches is being 1060 operated as a unified system with good internal connectivity, a 1061 member cache MAY forward such a request within that group of caches. 1063 7.2.2. Response Cache-Control Directives 1065 7.2.2.1. public 1067 The "public" response directive indicates that a response whose 1068 associated request contains an 'Authentication' header MAY be stored 1069 (see Section 3.2). 1071 7.2.2.2. private 1073 Argument syntax: 1075 #field-name 1077 The "private" response directive indicates that the response message 1078 is intended for a single user and MUST NOT be stored by a shared 1079 cache. A private cache MAY store the response. 1081 If the private response directive specifies one or more field-names, 1082 this requirement is limited to the field-values associated with the 1083 listed response header fields. That is, a shared cache MUST NOT 1084 store the specified field-names(s), whereas it MAY store the 1085 remainder of the response message. 1087 The field-names given are not limited to the set of standard header 1088 fields defined by this specification. Field names are case- 1089 insensitive. 1091 Note: This usage of the word "private" only controls where the 1092 response can be stored; it cannot ensure the privacy of the message 1093 content. Also, private response directives with field-names are 1094 often handled by implementations as if an unqualified private 1095 directive was received; i.e., the special handling for the qualified 1096 form is not widely implemented. 1098 Note: This directive uses the quoted-string form of the argument 1099 syntax. Senders SHOULD NOT use the token form (even if quoting 1100 appears not to be needed for single-entry lists). 1102 7.2.2.3. no-cache 1104 Argument syntax: 1106 #field-name 1108 The "no-cache" response directive indicates that the response MUST 1109 NOT be used to satisfy a subsequent request without successful 1110 validation on the origin server. This allows an origin server to 1111 prevent a cache from using it to satisfy a request without contacting 1112 it, even by caches that have been configured to return stale 1113 responses. 1115 If the no-cache response directive specifies one or more field-names, 1116 then a cache MAY use the response to satisfy a subsequent request, 1117 subject to any other restrictions on caching. However, any header 1118 fields in the response that have the field-name(s) listed MUST NOT be 1119 sent in the response to a subsequent request without successful 1120 revalidation with the origin server. This allows an origin server to 1121 prevent the re-use of certain header fields in a response, while 1122 still allowing caching of the rest of the response. 1124 The field-names given are not limited to the set of standard header 1125 fields defined by this specification. Field names are case- 1126 insensitive. 1128 Note: Many HTTP/1.0 caches will not recognize or obey this directive. 1129 Also, no-cache response directives with field-names are often handled 1130 by implementations as if an unqualified no-cache directive was 1131 received; i.e., the special handling for the qualified form is not 1132 widely implemented. 1134 Note: This directive uses the quoted-string form of the argument 1135 syntax. Senders SHOULD NOT use the token form (even if quoting 1136 appears not to be needed for single-entry lists). 1138 7.2.2.4. no-store 1140 The "no-store" response directive indicates that a cache MUST NOT 1141 store any part of either the immediate request or response. This 1142 directive applies to both private and shared caches. "MUST NOT 1143 store" in this context means that the cache MUST NOT intentionally 1144 store the information in non-volatile storage, and MUST make a best- 1145 effort attempt to remove the information from volatile storage as 1146 promptly as possible after forwarding it. 1148 This directive is NOT a reliable or sufficient mechanism for ensuring 1149 privacy. In particular, malicious or compromised caches might not 1150 recognize or obey this directive, and communications networks might 1151 be vulnerable to eavesdropping. 1153 7.2.2.5. must-revalidate 1155 The "must-revalidate" response directive indicates that once it has 1156 become stale, a cache MUST NOT use the response to satisfy subsequent 1157 requests without successful validation on the origin server. 1159 The must-revalidate directive is necessary to support reliable 1160 operation for certain protocol features. In all circumstances a 1161 cache MUST obey the must-revalidate directive; in particular, if a 1162 cache cannot reach the origin server for any reason, it MUST generate 1163 a 504 (Gateway Timeout) response. 1165 The must-revalidate directive ought to be used by servers if and only 1166 if failure to validate a request on the representation could result 1167 in incorrect operation, such as a silently unexecuted financial 1168 transaction. 1170 7.2.2.6. proxy-revalidate 1172 The "proxy-revalidate" response directive has the same meaning as the 1173 must-revalidate response directive, except that it does not apply to 1174 private caches. 1176 7.2.2.7. max-age 1178 Argument syntax: 1180 delta-seconds (see Section 1.4.1) 1182 The "max-age" response directive indicates that the response is to be 1183 considered stale after its age is greater than the specified number 1184 of seconds. 1186 Note: This directive uses the token form of the argument syntax; 1187 e.g., 'max-age=5', not 'max-age="5"'. Senders SHOULD NOT use the 1188 quoted-string form. 1190 7.2.2.8. s-maxage 1192 Argument syntax: 1194 delta-seconds (see Section 1.4.1) 1196 The "s-maxage" response directive indicates that, in shared caches, 1197 the maximum age specified by this directive overrides the maximum age 1198 specified by either the max-age directive or the Expires header 1199 field. The s-maxage directive also implies the semantics of the 1200 proxy-revalidate response directive. 1202 Note: This directive uses the token form of the argument syntax; 1203 e.g., 's-maxage=10', not 's-maxage="10"'. Senders SHOULD NOT use the 1204 quoted-string form. 1206 7.2.2.9. no-transform 1208 The "no-transform" response directive indicates that an intermediary 1209 (regardless of whether it implements a cache) MUST NOT change the 1210 Content-Encoding, Content-Range or Content-Type response header 1211 fields, nor the response representation. 1213 7.2.3. Cache Control Extensions 1215 The Cache-Control header field can be extended through the use of one 1216 or more cache-extension tokens, each with an optional value. 1217 Informational extensions (those that do not require a change in cache 1218 behavior) can be added without changing the semantics of other 1219 directives. Behavioral extensions are designed to work by acting as 1220 modifiers to the existing base of cache directives. Both the new 1221 directive and the standard directive are supplied, such that 1222 applications that do not understand the new directive will default to 1223 the behavior specified by the standard directive, and those that 1224 understand the new directive will recognize it as modifying the 1225 requirements associated with the standard directive. In this way, 1226 extensions to the cache-control directives can be made without 1227 requiring changes to the base protocol. 1229 This extension mechanism depends on an HTTP cache obeying all of the 1230 cache-control directives defined for its native HTTP-version, obeying 1231 certain extensions, and ignoring all directives that it does not 1232 understand. 1234 For example, consider a hypothetical new response directive called 1235 "community" that acts as a modifier to the private directive. We 1236 define this new directive to mean that, in addition to any private 1237 cache, any cache that is shared only by members of the community 1238 named within its value is allowed to cache the response. An origin 1239 server wishing to allow the UCI community to use an otherwise private 1240 response in their shared cache(s) could do so by including 1242 Cache-Control: private, community="UCI" 1244 A cache seeing this header field will act correctly even if the cache 1245 does not understand the community cache-extension, since it will also 1246 see and understand the private directive and thus default to the safe 1247 behavior. 1249 A cache MUST ignore unrecognized cache directives; it is assumed that 1250 any cache directive likely to be unrecognized by an HTTP/1.1 cache 1251 will be combined with standard directives (or the response's default 1252 cacheability) such that the cache behavior will remain minimally 1253 correct even if the cache does not understand the extension(s). 1255 New extension directives ought to consider defining: 1257 o What it means for a directive to be specified multiple times, 1259 o When the directive does not take an argument, what it means when 1260 an argument is present, 1262 o When the directive requires an argument, what it means when it is 1263 missing. 1265 The HTTP Cache Directive Registry defines the name space for the 1266 cache directives. 1268 A registration MUST include the following fields: 1270 o Cache Directive Name 1272 o Pointer to specification text 1274 Values to be added to this name space require IETF Review (see 1275 [RFC5226], Section 4.1). 1277 The registry itself is maintained at 1278 . 1280 7.3. Expires 1282 The "Expires" header field gives the date/time after which the 1283 response is considered stale. See Section 4.1 for further discussion 1284 of the freshness model. 1286 The presence of an Expires field does not imply that the original 1287 resource will change or cease to exist at, before, or after that 1288 time. 1290 The field-value is an absolute date and time as defined by HTTP-date 1291 in Section 5.1 of [Part2]; a sender MUST use the rfc1123-date format. 1293 Expires = HTTP-date 1295 For example 1297 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1299 A cache MUST treat other invalid date formats, especially including 1300 the value "0", as in the past (i.e., "already expired"). 1302 Note: If a response includes a Cache-Control field with the max- 1303 age directive (see Section 7.2.2.7), that directive overrides the 1304 Expires field. Likewise, the s-maxage directive (Section 7.2.2.8) 1305 overrides the Expires header fieldin shared caches. 1307 Historically, HTTP required the Expires field-value to be no more 1308 than a year in the future. While longer freshness lifetimes are no 1309 longer prohibited, extremely large values have been demonstrated to 1310 cause problems (e.g., clock overflows due to use of 32-bit integers 1311 for time values), and many caches will evict a response far sooner 1312 than that. Therefore, senders ought not produce them. 1314 An origin server without a clock MUST NOT assign Expires values to a 1315 response unless these values were associated with the resource by a 1316 system or user with a reliable clock. It MAY assign an Expires value 1317 that is known, at or before server configuration time, to be in the 1318 past (this allows "pre-expiration" of responses without storing 1319 separate Expires values for each resource). 1321 7.4. Pragma 1323 The "Pragma" header field allows backwards compatibility with 1324 HTTP/1.0 caches, so that clients can specify a "no-cache" request 1325 that they will understand (as Cache-Control was not defined until 1326 HTTP/1.1). When the Cache-Control header field is also present and 1327 understood in a request, Pragma is ignored. 1329 In HTTP/1.0, Pragma was defined as an extensible field for 1330 implementation-specified directives for recipients. This 1331 specification deprecates such extensions to improve interoperability. 1333 Pragma = 1#pragma-directive 1334 pragma-directive = "no-cache" / extension-pragma 1335 extension-pragma = token [ "=" ( token / quoted-string ) ] 1337 When the Cache-Control header field is not present in a request, the 1338 no-cache request pragma-directive MUST have the same effect on caches 1339 as if "Cache-Control: no-cache" were present (see Section 7.2.1). 1341 When sending a no-cache request, a client ought to include both the 1342 pragma and cache-control directives, unless Cache-Control: no-cache 1343 is purposefully omitted to target other Cache-Control response 1344 directives at HTTP/1.1 caches. For example: 1346 GET / HTTP/1.1 1347 Host: www.example.com 1348 Cache-Control: max-age=30 1349 Pragma: no-cache 1351 will constrain HTTP/1.1 caches to serve a response no older than 30 1352 seconds, while precluding implementations that do not understand 1353 Cache-Control from serving a cached response. 1355 Note: Because the meaning of "Pragma: no-cache" in responses is 1356 not specified, it does not provide a reliable replacement for 1357 "Cache-Control: no-cache" in them. 1359 7.5. Vary 1361 The "Vary" header field conveys the set of header fields that were 1362 used to select the representation. 1364 Caches use this information, in part, to determine whether a stored 1365 response can be used to satisfy a given request; see Section 4.3. 1367 In uncacheable or stale responses, the Vary field value advises the 1368 user agent about the criteria that were used to select the 1369 representation. 1371 Vary = "*" / 1#field-name 1373 The set of header fields named by the Vary field value is known as 1374 the selecting header fields. 1376 A server SHOULD include a Vary header field with any cacheable 1377 response that is subject to server-driven negotiation. Doing so 1378 allows a cache to properly interpret future requests on that resource 1379 and informs the user agent about the presence of negotiation on that 1380 resource. A server MAY include a Vary header field with a non- 1381 cacheable response that is subject to server-driven negotiation, 1382 since this might provide the user agent with useful information about 1383 the dimensions over which the response varies at the time of the 1384 response. 1386 A Vary field value of "*" signals that unspecified parameters not 1387 limited to the header fields (e.g., the network address of the 1388 client), play a role in the selection of the response representation; 1389 therefore, a cache cannot determine whether this response is 1390 appropriate. A proxy MUST NOT generate the "*" value. 1392 The field-names given are not limited to the set of standard header 1393 fields defined by this specification. Field names are case- 1394 insensitive. 1396 7.6. Warning 1398 The "Warning" header field is used to carry additional information 1399 about the status or transformation of a message that might not be 1400 reflected in the message. This information is typically used to warn 1401 about possible incorrectness introduced by caching operations or 1402 transformations applied to the payload of the message. 1404 Warnings can be used for other purposes, both cache-related and 1405 otherwise. The use of a warning, rather than an error status code, 1406 distinguishes these responses from true failures. 1408 Warning header fields can in general be applied to any message, 1409 however some warn-codes are specific to caches and can only be 1410 applied to response messages. 1412 Warning = 1#warning-value 1414 warning-value = warn-code SP warn-agent SP warn-text 1415 [SP warn-date] 1417 warn-code = 3DIGIT 1418 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1419 ; the name or pseudonym of the server adding 1420 ; the Warning header field, for use in debugging 1421 warn-text = quoted-string 1422 warn-date = DQUOTE HTTP-date DQUOTE 1424 Multiple warnings can be attached to a response (either by the origin 1425 server or by a cache), including multiple warnings with the same code 1426 number, only differing in warn-text. 1428 When this occurs, the user agent SHOULD inform the user of as many of 1429 them as possible, in the order that they appear in the response. 1431 Systems that generate multiple Warning header fields are encouraged 1432 to order them with this user agent behavior in mind. New Warning 1433 header fields are added after any existing Warning header fields. 1435 Warnings are assigned three digit warn-codes. The first digit 1436 indicates whether the Warning is required to be deleted from a stored 1437 response after validation: 1439 o 1xx Warnings describe the freshness or validation status of the 1440 response, and so MUST be deleted by a cache after validation. 1441 They can only be generated by a cache when validating a cached 1442 entry, and MUST NOT be generated in any other situation. 1444 o 2xx Warnings describe some aspect of the representation that is 1445 not rectified by a validation (for example, a lossy compression of 1446 the representation) and MUST NOT be deleted by a cache after 1447 validation, unless a full response is returned, in which case they 1448 MUST be. 1450 If an implementation sends a message with one or more Warning header 1451 fields to a receiver whose version is HTTP/1.0 or lower, then the 1452 sender MUST include in each warning-value a warn-date that matches 1453 the Date header field in the message. 1455 If a system receives a message with a warning-value that includes a 1456 warn-date, and that warn-date is different from the Date value in the 1457 response, then that warning-value MUST be deleted from the message 1458 before storing, forwarding, or using it. (preventing the consequences 1459 of naive caching of Warning header fields.) If all of the warning- 1460 values are deleted for this reason, the Warning header field MUST be 1461 deleted as well. 1463 The following warn-codes are defined by this specification, each with 1464 a recommended warn-text in English, and a description of its meaning. 1466 7.6.1. 110 Response is Stale 1468 A cache SHOULD include this whenever the returned response is stale. 1470 7.6.2. 111 Revalidation Failed 1472 A cache SHOULD include this when returning a stale response because 1473 an attempt to validate the response failed, due to an inability to 1474 reach the server. 1476 7.6.3. 112 Disconnected Operation 1478 A cache SHOULD include this if it is intentionally disconnected from 1479 the rest of the network for a period of time. 1481 7.6.4. 113 Heuristic Expiration 1483 A cache SHOULD include this if it heuristically chose a freshness 1484 lifetime greater than 24 hours and the response's age is greater than 1485 24 hours. 1487 7.6.5. 199 Miscellaneous Warning 1489 The warning text can include arbitrary information to be presented to 1490 a human user, or logged. A system receiving this warning MUST NOT 1491 take any automated action, besides presenting the warning to the 1492 user. 1494 7.6.6. 214 Transformation Applied 1496 MUST be added by a proxy if it applies any transformation to the 1497 representation, such as changing the content-coding, media-type, or 1498 modifying the representation data, unless this Warning code already 1499 appears in the response. 1501 7.6.7. 299 Miscellaneous Persistent Warning 1503 The warning text can include arbitrary information to be presented to 1504 a human user, or logged. A system receiving this warning MUST NOT 1505 take any automated action. 1507 7.6.8. Warn Code Extensions 1509 The HTTP Warn Code Registry defines the name space for warn codes. 1511 A registration MUST include the following fields: 1513 o Warn Code (3 digits) 1515 o Short Description 1516 o Pointer to specification text 1518 Values to be added to this name space require IETF Review (see 1519 [RFC5226], Section 4.1). 1521 The registry itself is maintained at 1522 . 1524 8. History Lists 1526 User agents often have history mechanisms, such as "Back" buttons and 1527 history lists, that can be used to redisplay a representation 1528 retrieved earlier in a session. 1530 The freshness model (Section 4.1) does not necessarily apply to 1531 history mechanisms. I.e., a history mechanism can display a previous 1532 representation even if it has expired. 1534 This does not prohibit the history mechanism from telling the user 1535 that a view might be stale, or from honoring cache directives (e.g., 1536 Cache-Control: no-store). 1538 9. IANA Considerations 1540 9.1. Cache Directive Registry 1542 The registration procedure for HTTP Cache Directives is defined by 1543 Section 7.2.3 of this document. 1545 The HTTP Cache Directive Registry shall be created at 1546 and be 1547 populated with the registrations below: 1549 +------------------------+----------------------------------+ 1550 | Cache Directive | Reference | 1551 +------------------------+----------------------------------+ 1552 | max-age | Section 7.2.1.3, Section 7.2.2.7 | 1553 | max-stale | Section 7.2.1.4 | 1554 | min-fresh | Section 7.2.1.5 | 1555 | must-revalidate | Section 7.2.2.5 | 1556 | no-cache | Section 7.2.1.1, Section 7.2.2.3 | 1557 | no-store | Section 7.2.1.2, Section 7.2.2.4 | 1558 | no-transform | Section 7.2.1.6, Section 7.2.2.9 | 1559 | only-if-cached | Section 7.2.1.7 | 1560 | private | Section 7.2.2.2 | 1561 | proxy-revalidate | Section 7.2.2.6 | 1562 | public | Section 7.2.2.1 | 1563 | s-maxage | Section 7.2.2.8 | 1564 | stale-if-error | [RFC5861], Section 4 | 1565 | stale-while-revalidate | [RFC5861], Section 3 | 1566 +------------------------+----------------------------------+ 1568 9.2. Warn Code Registry 1570 The registration procedure for HTTP Warn Codes is defined by 1571 Section 7.6.8 of this document. 1573 The HTTP Warn Code Registry shall be created at 1574 and be 1575 populated with the registrations below: 1577 +-----------+----------------------------------+---------------+ 1578 | Warn Code | Short Description | Reference | 1579 +-----------+----------------------------------+---------------+ 1580 | 110 | Response is Stale | Section 7.6.1 | 1581 | 111 | Revalidation Failed | Section 7.6.2 | 1582 | 112 | Disconnected Operation | Section 7.6.3 | 1583 | 113 | Heuristic Expiration | Section 7.6.4 | 1584 | 199 | Miscellaneous Warning | Section 7.6.5 | 1585 | 214 | Transformation Applied | Section 7.6.6 | 1586 | 299 | Miscellaneous Persistent Warning | Section 7.6.7 | 1587 +-----------+----------------------------------+---------------+ 1589 9.3. Header Field Registration 1591 The Message Header Field Registry located at shall be 1593 updated with the permanent registrations below (see [RFC3864]): 1595 +-------------------+----------+----------+-------------+ 1596 | Header Field Name | Protocol | Status | Reference | 1597 +-------------------+----------+----------+-------------+ 1598 | Age | http | standard | Section 7.1 | 1599 | Cache-Control | http | standard | Section 7.2 | 1600 | Expires | http | standard | Section 7.3 | 1601 | Pragma | http | standard | Section 7.4 | 1602 | Vary | http | standard | Section 7.5 | 1603 | Warning | http | standard | Section 7.6 | 1604 +-------------------+----------+----------+-------------+ 1606 The change controller is: "IETF (iesg@ietf.org) - Internet 1607 Engineering Task Force". 1609 10. Security Considerations 1611 Caches expose additional potential vulnerabilities, since the 1612 contents of the cache represent an attractive target for malicious 1613 exploitation. Because cache contents persist after an HTTP request 1614 is complete, an attack on the cache can reveal information long after 1615 a user believes that the information has been removed from the 1616 network. Therefore, cache contents need to be protected as sensitive 1617 information. 1619 11. Acknowledgments 1621 See Section 9 of [Part1]. 1623 12. References 1625 12.1. Normative References 1627 [Part1] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 1628 "HTTP/1.1, part 1: Message Routing and Syntax"", 1629 draft-ietf-httpbis-p1-messaging-20 (work in progress), 1630 July 2012. 1632 [Part2] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 1633 "HTTP/1.1, part 2: Semantics and Payloads", 1634 draft-ietf-httpbis-p2-semantics-20 (work in progress), 1635 July 2012. 1637 [Part4] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 1638 "HTTP/1.1, part 4: Conditional Requests", 1639 draft-ietf-httpbis-p4-conditional-20 (work in progress), 1640 July 2012. 1642 [Part5] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 1643 "HTTP/1.1, part 5: Range Requests", 1644 draft-ietf-httpbis-p5-range-20 (work in progress), 1645 July 2012. 1647 [Part7] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 1648 "HTTP/1.1, part 7: Authentication", 1649 draft-ietf-httpbis-p7-auth-20 (work in progress), 1650 July 2012. 1652 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1653 Requirement Levels", BCP 14, RFC 2119, March 1997. 1655 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1656 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1658 12.2. Informative References 1660 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1661 Specification, Implementation", RFC 1305, March 1992. 1663 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1664 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1665 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1667 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1668 Procedures for Message Header Fields", BCP 90, RFC 3864, 1669 September 2004. 1671 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1672 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1673 May 2008. 1675 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1676 Content", RFC 5861, April 2010. 1678 Appendix A. Changes from RFC 2616 1680 Make the specified age calculation algorithm less conservative. 1681 (Section 4.1.3) 1683 Remove requirement to consider Content-Location in successful 1684 responses in order to determine the appropriate response to use. 1685 (Section 4.2) 1687 Clarify denial of service attack avoidance requirement. (Section 6) 1689 Change ABNF productions for header fields to only define the field 1690 value. (Section 7) 1691 Do not mention RFC 2047 encoding and multiple languages in Warning 1692 header fields anymore, as these aspects never were implemented. 1693 (Section 7.6) 1695 Introduce Cache Directive and Warn Code Registries. (Section 7.2.3 1696 and Section 7.6.8) 1698 Appendix B. Imported ABNF 1700 The following core rules are included by reference, as defined in 1701 Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), 1702 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 1703 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 1704 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII 1705 character). 1707 The rules below are defined in [Part1]: 1709 OWS = 1710 field-name = 1711 quoted-string = 1712 token = 1714 port = 1715 pseudonym = 1716 uri-host = 1718 The rules below are defined in other parts: 1720 HTTP-date = 1722 Appendix C. Collected ABNF 1724 Age = delta-seconds 1726 Cache-Control = *( "," OWS ) cache-directive *( OWS "," [ OWS 1727 cache-directive ] ) 1729 Expires = HTTP-date 1731 HTTP-date = 1733 OWS = 1735 Pragma = *( "," OWS ) pragma-directive *( OWS "," [ OWS 1736 pragma-directive ] ) 1738 Vary = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name ] 1739 ) ) 1741 Warning = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value ] 1742 ) 1744 cache-directive = token [ "=" ( token / quoted-string ) ] 1746 delta-seconds = 1*DIGIT 1748 extension-pragma = token [ "=" ( token / quoted-string ) ] 1750 field-name = 1752 port = 1753 pragma-directive = "no-cache" / extension-pragma 1754 pseudonym = 1756 quoted-string = 1758 token = 1760 uri-host = 1762 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1763 warn-code = 3DIGIT 1764 warn-date = DQUOTE HTTP-date DQUOTE 1765 warn-text = quoted-string 1766 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date 1767 ] 1769 Appendix D. Change Log (to be removed by RFC Editor before publication) 1771 Changes up to the first Working Group Last Call draft are summarized 1772 in . 1775 D.1. Since draft-ietf-httpbis-p6-cache-19 1777 Closed issues: 1779 o : "untangle 1780 Cache-Control ABNF" 1782 o : "Multiple 1783 values in Cache-Control header fields" 1785 o : "Case 1786 sensitivity of header fields in CC values" 1788 o : "Spurious 1789 'MAYs'" 1791 o : "enhance 1792 considerations for new cache control directives" 1794 o : "ABNF 1795 requirements for recipients" 1797 o : "note 1798 introduction of new IANA registries as normative changes" 1800 Index 1802 1 1803 110 Response is Stale (warn code) 31 1804 111 Revalidation Failed (warn code) 32 1805 112 Disconnected Operation (warn code) 32 1806 113 Heuristic Expiration (warn code) 32 1807 199 Miscellaneous Warning (warn code) 32 1809 2 1810 214 Transformation Applied (warn code) 32 1811 299 Miscellaneous Persistent Warning (warn code) 32 1813 A 1814 age 5 1815 Age header field 20 1817 C 1818 cache 4 1819 Cache Directives 1820 max-age 22, 25 1821 max-stale 22 1822 min-fresh 22 1823 must-revalidate 25 1824 no-cache 21, 24 1825 no-store 21, 25 1826 no-transform 23, 26 1827 only-if-cached 23 1828 private 23 1829 proxy-revalidate 25 1830 public 23 1831 s-maxage 26 1832 cache entry 7 1833 cache key 7 1834 Cache-Control header field 20 1835 cacheable 4 1837 E 1838 Expires header field 28 1839 explicit expiration time 5 1841 F 1842 first-hand 5 1843 fresh 5 1844 freshness lifetime 5 1846 G 1847 Grammar 1848 Age 20 1849 Cache-Control 21 1850 cache-directive 21 1851 delta-seconds 7 1852 Expires 28 1853 extension-pragma 29 1854 Pragma 29 1855 pragma-directive 29 1856 Vary 29 1857 warn-agent 30 1858 warn-code 30 1859 warn-date 30 1860 warn-text 30 1861 Warning 30 1862 warning-value 30 1864 H 1865 Header Fields 1866 Age 20 1867 Cache-Control 20 1868 Expires 28 1869 Pragma 28 1870 Vary 29 1871 Warning 30 1872 heuristic expiration time 5 1874 M 1875 max-age 1876 Cache Directive 22, 25 1877 max-stale 1878 Cache Directive 22 1879 min-fresh 1880 Cache Directive 22 1881 must-revalidate 1882 Cache Directive 25 1884 N 1885 no-cache 1886 Cache Directive 21, 24 1887 no-store 1888 Cache Directive 21, 25 1889 no-transform 1890 Cache Directive 23, 26 1892 O 1893 only-if-cached 1894 Cache Directive 23 1896 P 1897 Pragma header field 28 1898 private 1899 Cache Directive 23 1900 private cache 4 1901 proxy-revalidate 1902 Cache Directive 25 1903 public 1904 Cache Directive 23 1906 S 1907 s-maxage 1908 Cache Directive 26 1909 shared cache 4 1910 stale 5 1911 strong validator 6 1913 V 1914 validator 5 1915 strong 6 1916 Vary header field 29 1918 W 1919 Warn Codes 1920 110 Response is Stale 31 1921 111 Revalidation Failed 32 1922 112 Disconnected Operation 32 1923 113 Heuristic Expiration 32 1924 199 Miscellaneous Warning 32 1925 214 Transformation Applied 32 1926 299 Miscellaneous Persistent Warning 32 1927 Warning header field 30 1929 Authors' Addresses 1931 Roy T. Fielding (editor) 1932 Adobe Systems Incorporated 1933 345 Park Ave 1934 San Jose, CA 95110 1935 USA 1937 EMail: fielding@gbiv.com 1938 URI: http://roy.gbiv.com/ 1940 Yves Lafon (editor) 1941 World Wide Web Consortium 1942 W3C / ERCIM 1943 2004, rte des Lucioles 1944 Sophia-Antipolis, AM 06902 1945 France 1947 EMail: ylafon@w3.org 1948 URI: http://www.raubacapeu.net/people/yves/ 1950 Mark Nottingham (editor) 1951 Rackspace 1953 EMail: mnot@mnot.net 1954 URI: http://www.mnot.net/ 1955 Julian F. Reschke (editor) 1956 greenbytes GmbH 1957 Hafenweg 16 1958 Muenster, NW 48155 1959 Germany 1961 EMail: julian.reschke@greenbytes.de 1962 URI: http://greenbytes.de/tech/webdav/