idnits 2.17.00 (12 Aug 2021) /tmp/idnits38777/draft-ietf-httpbis-p6-cache-21.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 (October 4, 2012) is 3515 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: draft-ietf-httpbis-p1-messaging has been published as RFC 7230 == Outdated reference: draft-ietf-httpbis-p2-semantics has been published as RFC 7231 == Outdated reference: draft-ietf-httpbis-p4-conditional has been published as RFC 7232 == Outdated reference: draft-ietf-httpbis-p5-range has been published as RFC 7233 == Outdated reference: draft-ietf-httpbis-p7-auth has been published as RFC 7235 -- 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) M. Nottingham, Ed. 5 Intended status: Standards Track Akamai 6 Expires: April 7, 2013 J. Reschke, Ed. 7 greenbytes 8 October 4, 2012 10 Hypertext Transfer Protocol (HTTP/1.1): Caching 11 draft-ietf-httpbis-p6-cache-21 13 Abstract 15 The Hypertext Transfer Protocol (HTTP) is an application-level 16 protocol for distributed, collaborative, hypertext information 17 systems. This document defines requirements on HTTP caches and the 18 associated header fields that control cache behavior or indicate 19 cacheable response messages. 21 Editorial Note (To be removed by RFC Editor) 23 Discussion of this draft takes place on the HTTPBIS working group 24 mailing list (ietf-http-wg@w3.org), which is archived at 25 . 27 The current issues list is at 28 and related 29 documents (including fancy diffs) can be found at 30 . 32 The changes in this draft are summarized in Appendix D.2. 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at http://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on April 7, 2013. 50 Copyright Notice 52 Copyright (c) 2012 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 This document may contain material from IETF Documents or IETF 66 Contributions published or made publicly available before November 67 10, 2008. The person(s) controlling the copyright in some of this 68 material may not have granted the IETF Trust the right to allow 69 modifications of such material outside the IETF Standards Process. 70 Without obtaining an adequate license from the person(s) controlling 71 the copyright in such materials, this document may not be modified 72 outside the IETF Standards Process, and derivative works of it may 73 not be created outside the IETF Standards Process, except to format 74 it for publication as an RFC or to translate it into languages other 75 than English. 77 Table of Contents 79 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 80 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 4 81 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 82 1.3. Conformance and Error Handling . . . . . . . . . . . . . . 6 83 1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 6 84 1.4.1. Delta Seconds . . . . . . . . . . . . . . . . . . . . 6 85 2. Overview of Cache Operation . . . . . . . . . . . . . . . . . 6 86 3. Storing Responses in Caches . . . . . . . . . . . . . . . . . 7 87 3.1. Storing Incomplete Responses . . . . . . . . . . . . . . . 8 88 3.2. Storing Responses to Authenticated Requests . . . . . . . 8 89 4. Constructing Responses from Caches . . . . . . . . . . . . . . 9 90 4.1. Freshness Model . . . . . . . . . . . . . . . . . . . . . 10 91 4.1.1. Calculating Freshness Lifetime . . . . . . . . . . . . 11 92 4.1.2. Calculating Heuristic Freshness . . . . . . . . . . . 12 93 4.1.3. Calculating Age . . . . . . . . . . . . . . . . . . . 12 94 4.1.4. Serving Stale Responses . . . . . . . . . . . . . . . 14 95 4.2. Validation Model . . . . . . . . . . . . . . . . . . . . . 15 96 4.2.1. Freshening Responses with 304 Not Modified . . . . . . 16 97 4.3. Using Negotiated Responses . . . . . . . . . . . . . . . . 16 98 4.4. Combining Partial Content . . . . . . . . . . . . . . . . 17 99 5. Updating Caches with HEAD Responses . . . . . . . . . . . . . 18 100 6. Request Methods that Invalidate . . . . . . . . . . . . . . . 18 101 7. Header Field Definitions . . . . . . . . . . . . . . . . . . . 19 102 7.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 103 7.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 20 104 7.2.1. Request Cache-Control Directives . . . . . . . . . . . 20 105 7.2.2. Response Cache-Control Directives . . . . . . . . . . 22 106 7.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 25 107 7.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 27 108 7.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 28 109 7.5. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 28 110 7.5.1. 110 Response is Stale . . . . . . . . . . . . . . . . 30 111 7.5.2. 111 Revalidation Failed . . . . . . . . . . . . . . . 30 112 7.5.3. 112 Disconnected Operation . . . . . . . . . . . . . . 30 113 7.5.4. 113 Heuristic Expiration . . . . . . . . . . . . . . . 30 114 7.5.5. 199 Miscellaneous Warning . . . . . . . . . . . . . . 30 115 7.5.6. 214 Transformation Applied . . . . . . . . . . . . . . 30 116 7.5.7. 299 Miscellaneous Persistent Warning . . . . . . . . . 31 117 7.5.8. Warn Code Extensions . . . . . . . . . . . . . . . . . 31 118 8. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 31 119 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 120 9.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 31 121 9.2. Warn Code Registry . . . . . . . . . . . . . . . . . . . . 32 122 9.3. Header Field Registration . . . . . . . . . . . . . . . . 33 123 10. Security Considerations . . . . . . . . . . . . . . . . . . . 33 124 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 34 125 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 126 12.1. Normative References . . . . . . . . . . . . . . . . . . . 34 127 12.2. Informative References . . . . . . . . . . . . . . . . . . 34 128 Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 35 129 Appendix B. Imported ABNF . . . . . . . . . . . . . . . . . . . . 35 130 Appendix C. Collected ABNF . . . . . . . . . . . . . . . . . . . 37 131 Appendix D. Change Log (to be removed by RFC Editor before 132 publication) . . . . . . . . . . . . . . . . . . . . 38 133 D.1. Since draft-ietf-httpbis-p6-cache-19 . . . . . . . . . . . 38 134 D.2. Since draft-ietf-httpbis-p6-cache-20 . . . . . . . . . . . 38 135 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 137 1. Introduction 139 HTTP is typically used for distributed information systems, where 140 performance can be improved by the use of response caches. This 141 document defines aspects of HTTP/1.1 related to caching and reusing 142 response messages. 144 1.1. Purpose 146 An HTTP cache is a local store of response messages and the subsystem 147 that controls its message storage, retrieval, and deletion. A cache 148 stores cacheable responses in order to reduce the response time and 149 network bandwidth consumption on future, equivalent requests. Any 150 client or server MAY employ a cache, though a cache cannot be used by 151 a server that is acting as a tunnel. 153 The goal of caching in HTTP/1.1 is to significantly improve 154 performance by reusing a prior response message to satisfy a current 155 request. A stored response is considered "fresh", as defined in 156 Section 4.1, if the response can be reused without "validation" 157 (checking with the origin server to see if the cached response 158 remains valid for this request). A fresh cache response can 159 therefore reduce both latency and network transfers each time it is 160 reused. When a cached response is not fresh, it might still be 161 reusable if it can be freshened by validation (Section 4.2) or if the 162 origin is unavailable. 164 1.2. Terminology 166 This specification uses a number of terms to refer to the roles 167 played by participants in, and objects of, HTTP caching. 169 cache 171 A conformant implementation of a HTTP cache. Note that this 172 implies an HTTP/1.1 cache; this specification does not define 173 conformance for HTTP/1.0 caches. 175 shared cache 177 A cache that stores responses to be reused by more than one user; 178 usually (but not always) deployed as part of an intermediary. 180 private cache 182 A cache that is dedicated to a single user. 184 cacheable 186 A response is cacheable if a cache is allowed to store a copy of 187 the response message for use in answering subsequent requests. 188 Even when a response is cacheable, there might be additional 189 constraints on whether a cache can use the stored copy to satisfy 190 a particular request. 192 explicit expiration time 194 The time at which the origin server intends that a representation 195 no longer be returned by a cache without further validation. 197 heuristic expiration time 199 An expiration time assigned by a cache when no explicit expiration 200 time is available. 202 age 204 The age of a response is the time since it was sent by, or 205 successfully validated with, the origin server. 207 first-hand 209 A response is first-hand if the freshness model is not in use; 210 i.e., its age is 0. 212 freshness lifetime 214 The length of time between the generation of a response and its 215 expiration time. 217 fresh 219 A response is fresh if its age has not yet exceeded its freshness 220 lifetime. 222 stale 224 A response is stale if its age has passed its freshness lifetime 225 (either explicit or heuristic). 227 validator 229 A protocol element (e.g., an entity-tag or a Last-Modified time) 230 that is used to find out whether a stored response is an 231 equivalent copy of a representation. See Section 2.1 of [Part4]. 233 strong validator 235 A validator that is defined by the origin server such that its 236 current value will change if the representation data changes; 237 i.e., an entity-tag that is not marked as weak (Section 2.3 of 238 [Part4]) or, if no entity-tag is provided, a Last-Modified value 239 that is strong in the sense defined by Section 2.2.2 of [Part4]. 241 1.3. Conformance and Error Handling 243 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 244 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 245 document are to be interpreted as described in [RFC2119]. 247 Conformance criteria and considerations regarding error handling are 248 defined in Section 2.5 of [Part1]. 250 1.4. Syntax Notation 252 This specification uses the Augmented Backus-Naur Form (ABNF) 253 notation of [RFC5234] with the list rule extension defined in Section 254 1.2 of [Part1]. Appendix B describes rules imported from other 255 documents. Appendix C shows the collected ABNF with the list rule 256 expanded. 258 1.4.1. Delta Seconds 260 The delta-seconds rule specifies a non-negative integer, representing 261 time in seconds. 263 delta-seconds = 1*DIGIT 265 If an implementation receives a delta-seconds value larger than the 266 largest positive integer it can represent, or if any of its 267 subsequent calculations overflows, it MUST consider the value to be 268 2147483648 (2^31). Recipients parsing a delta-seconds value MUST use 269 an arithmetic type of at least 31 bits of range, and senders MUST NOT 270 send delta-seconds with a value greater than 2147483648. 272 2. Overview of Cache Operation 274 Proper cache operation preserves the semantics of HTTP transfers 275 ([Part2]) while eliminating the transfer of information already held 276 in the cache. Although caching is an entirely OPTIONAL feature of 277 HTTP, we assume that reusing the cached response is desirable and 278 that such reuse is the default behavior when no requirement or 279 locally-desired configuration prevents it. Therefore, HTTP cache 280 requirements are focused on preventing a cache from either storing a 281 non-reusable response or reusing a stored response inappropriately. 283 Each cache entry consists of a cache key and one or more HTTP 284 responses corresponding to prior requests that used the same key. 285 The most common form of cache entry is a successful result of a 286 retrieval request: i.e., a 200 (OK) response containing a 287 representation of the resource identified by the request target. 288 However, it is also possible to cache negative results (e.g., 404 289 (Not Found), incomplete results (e.g., 206 (Partial Content)), and 290 responses to methods other than GET if the method's definition allows 291 such caching and defines something suitable for use as a cache key. 293 The default cache key consists of the request method and target URI. 294 However, since HTTP caches in common use today are typically limited 295 to caching responses to GET, many implementations simply decline 296 other methods and use only the URI as the key. 298 If a request target is subject to content negotiation, its cache 299 entry might consist of multiple stored responses, each differentiated 300 by a secondary key for the values of the original request's selecting 301 header fields (Section 4.3). 303 3. Storing Responses in Caches 305 A cache MUST NOT store a response to any request, unless: 307 o The request method is understood by the cache and defined as being 308 cacheable, and 310 o the response status code is understood by the cache, and 312 o the "no-store" cache directive (see Section 7.2) does not appear 313 in request or response header fields, and 315 o the "private" cache response directive (see Section 7.2.2.2) does 316 not appear in the response, if the cache is shared, and 318 o the Authorization header field (see Section 4.1 of [Part7]) does 319 not appear in the request, if the cache is shared, unless the 320 response explicitly allows it (see Section 3.2), and 322 o the response either: 324 * contains an Expires header field (see Section 7.3), or 326 * contains a max-age response cache directive (see 327 Section 7.2.2.7), or 329 * contains a s-maxage response cache directive and the cache is 330 shared, or 332 * contains a Cache Control Extension (see Section 7.2.3) that 333 allows it to be cached, or 335 * has a status code that can be served with heuristic freshness 336 (see Section 4.1.2). 338 Note that any of the requirements listed above can be overridden by a 339 cache-control extension; see Section 7.2.3. 341 In this context, a cache has "understood" a request method or a 342 response status code if it recognizes it and implements any cache- 343 specific behavior. 345 Note that, in normal operation, many caches will not store a response 346 that has neither a cache validator nor an explicit expiration time, 347 as such responses are not usually useful to store. However, caches 348 are not prohibited from storing such responses. 350 3.1. Storing Incomplete Responses 352 A response message is considered complete when all of the octets 353 indicated by the message framing ([Part1]) are received prior to the 354 connection being closed. If the request is GET, the response status 355 is 200 (OK), and the entire response header block has been received, 356 a cache MAY store an incomplete response message body if the cache 357 entry is recorded as incomplete. Likewise, a 206 (Partial Content) 358 response MAY be stored as if it were an incomplete 200 (OK) cache 359 entry. However, a cache MUST NOT store incomplete or partial content 360 responses if it does not support the Range and Content-Range header 361 fields or if it does not understand the range units used in those 362 fields. 364 A cache MAY complete a stored incomplete response by making a 365 subsequent range request ([Part5]) and combining the successful 366 response with the stored entry, as defined in Section 4.4. A cache 367 MUST NOT use an incomplete response to answer requests unless the 368 response has been made complete or the request is partial and 369 specifies a range that is wholly within the incomplete response. A 370 cache MUST NOT send a partial response to a client without explicitly 371 marking it as such using the 206 (Partial Content) status code. 373 3.2. Storing Responses to Authenticated Requests 375 A shared cache MUST NOT use a cached response to a request with an 376 Authorization header field (Section 4.1 of [Part7]) to satisfy any 377 subsequent request unless a cache directive that allows such 378 responses to be stored is present in the response. 380 In this specification, the following Cache-Control response 381 directives (Section 7.2.2) have such an effect: must-revalidate, 382 public, s-maxage. 384 Note that cached responses that contain the "must-revalidate" and/or 385 "s-maxage" response directives are not allowed to be served stale 386 (Section 4.1.4) by shared caches. In particular, a response with 387 either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to 388 satisfy a subsequent request without revalidating it on the origin 389 server. 391 4. Constructing Responses from Caches 393 For a presented request, a cache MUST NOT return a stored response, 394 unless: 396 o The presented effective request URI (Section 5.5 of [Part1]) and 397 that of the stored response match, and 399 o the request method associated with the stored response allows it 400 to be used for the presented request, and 402 o selecting header fields nominated by the stored response (if any) 403 match those presented (see Section 4.3), and 405 o the presented request does not contain the no-cache pragma 406 (Section 7.4), nor the no-cache cache directive (Section 7.2.1), 407 unless the stored response is successfully validated 408 (Section 4.2), and 410 o the stored response does not contain the no-cache cache directive 411 (Section 7.2.2.3), unless it is successfully validated 412 (Section 4.2), and 414 o the stored response is either: 416 * fresh (see Section 4.1), or 418 * allowed to be served stale (see Section 4.1.4), or 420 * successfully validated (see Section 4.2). 422 Note that any of the requirements listed above can be overridden by a 423 cache-control extension; see Section 7.2.3. 425 When a stored response is used to satisfy a request without 426 validation, a cache MUST include a single Age header field 427 (Section 7.1) in the response with a value equal to the stored 428 response's current_age; see Section 4.1.3. 430 A cache MUST write through requests with methods that are unsafe 431 (Section 5.2.1 of [Part2]) to the origin server; i.e., a cache is not 432 allowed to generate a reply to such a request before having forwarded 433 the request and having received a corresponding response. 435 Also, note that unsafe requests might invalidate already stored 436 responses; see Section 6. 438 When more than one suitable response is stored, a cache MUST use the 439 most recent response (as determined by the Date header field). It 440 can also forward a request with "Cache-Control: max-age=0" or "Cache- 441 Control: no-cache" to disambiguate which response to use. 443 A cache that does not have a clock available MUST NOT use stored 444 responses without revalidating them on every use. A cache, 445 especially a shared cache, SHOULD use a mechanism, such as NTP 446 [RFC1305], to synchronize its clock with a reliable external 447 standard. 449 4.1. Freshness Model 451 When a response is "fresh" in the cache, it can be used to satisfy 452 subsequent requests without contacting the origin server, thereby 453 improving efficiency. 455 The primary mechanism for determining freshness is for an origin 456 server to provide an explicit expiration time in the future, using 457 either the Expires header field (Section 7.3) or the max-age response 458 cache directive (Section 7.2.2.7). Generally, origin servers will 459 assign future explicit expiration times to responses in the belief 460 that the representation is not likely to change in a semantically 461 significant way before the expiration time is reached. 463 If an origin server wishes to force a cache to validate every 464 request, it can assign an explicit expiration time in the past to 465 indicate that the response is already stale. Compliant caches will 466 normally validate the cached response before reusing it for 467 subsequent requests (see Section 4.1.4). 469 Since origin servers do not always provide explicit expiration times, 470 a cache MAY assign a heuristic expiration time when an explicit time 471 is not specified, employing algorithms that use other header field 472 values (such as the Last-Modified time) to estimate a plausible 473 expiration time. This specification does not provide specific 474 algorithms, but does impose worst-case constraints on their results. 476 The calculation to determine if a response is fresh is: 478 response_is_fresh = (freshness_lifetime > current_age) 480 The freshness_lifetime is defined in Section 4.1.1; the current_age 481 is defined in Section 4.1.3. 483 Additionally, clients can influence freshness calculation -- either 484 constraining it relaxing it -- by using the max-age and min-fresh 485 request cache directives. See Section 7.2.1 for details. 487 Note that freshness applies only to cache operation; it cannot be 488 used to force a user agent to refresh its display or reload a 489 resource. See Section 8 for an explanation of the difference between 490 caches and history mechanisms. 492 4.1.1. Calculating Freshness Lifetime 494 A cache can calculate the freshness lifetime (denoted as 495 freshness_lifetime) of a response by using the first match of: 497 o If the cache is shared and the s-maxage response cache directive 498 (Section 7.2.2.8) is present, use its value, or 500 o If the max-age response cache directive (Section 7.2.2.7) is 501 present, use its value, or 503 o If the Expires response header field (Section 7.3) is present, use 504 its value minus the value of the Date response header field, or 506 o Otherwise, no explicit expiration time is present in the response. 507 A heuristic freshness lifetime might be applicable; see 508 Section 4.1.2. 510 Note that this calculation is not vulnerable to clock skew, since all 511 of the information comes from the origin server. 513 When there is more than one value present for a given directive 514 (e.g., two Expires header fields, multiple Cache-Control: max-age 515 directives), it is considered invalid. Caches are encouraged to 516 consider responses that have invalid freshness information to be 517 stale. 519 4.1.2. Calculating Heuristic Freshness 521 If no explicit expiration time is present in a stored response that 522 has a status code whose definition allows heuristic freshness to be 523 used (including the following in Section 7 of [Part2]: 200 (OK), 203 524 (Non-Authoritative Information), 206 (Partial Content), 300 (Multiple 525 Choices), 301 (Moved Permanently) and 410 (Gone)), a cache MAY 526 calculate a heuristic expiration time. A cache MUST NOT use 527 heuristics to determine freshness for responses with status codes 528 that do not explicitly allow it. 530 When a heuristic is used to calculate freshness lifetime, a cache 531 SHOULD attach a Warning header field with a 113 warn-code to the 532 response if its current_age is more than 24 hours and such a warning 533 is not already present. 535 Also, if the response has a Last-Modified header field (Section 2.2 536 of [Part4]), caches are encouraged to use a heuristic expiration 537 value that is no more than some fraction of the interval since that 538 time. A typical setting of this fraction might be 10%. 540 Note: Section 13.9 of [RFC2616] prohibited caches from calculating 541 heuristic freshness for URIs with query components (i.e., those 542 containing '?'). In practice, this has not been widely 543 implemented. Therefore, servers are encouraged to send explicit 544 directives (e.g., Cache-Control: no-cache) if they wish to 545 preclude caching. 547 4.1.3. Calculating Age 549 HTTP/1.1 uses the Age header field to convey the estimated age of the 550 response message when obtained from a cache. The Age field value is 551 the cache's estimate of the amount of time since the response was 552 generated or validated by the origin server. In essence, the Age 553 value is the sum of the time that the response has been resident in 554 each of the caches along the path from the origin server, plus the 555 amount of time it has been in transit along network paths. 557 The following data is used for the age calculation: 559 age_value 561 The term "age_value" denotes the value of the Age header field 562 (Section 7.1), in a form appropriate for arithmetic operation; or 563 0, if not available. 565 date_value 567 HTTP/1.1 requires origin servers to send a Date header field, if 568 possible, with every response, giving the time at which the 569 response was generated. The term "date_value" denotes the value 570 of the Date header field, in a form appropriate for arithmetic 571 operations. See Section 8.1.1.2 of [Part2] for the definition of 572 the Date header field, and for requirements regarding responses 573 without it. 575 now 577 The term "now" means "the current value of the clock at the host 578 performing the calculation". A cache SHOULD use NTP ([RFC1305]) 579 or some similar protocol to synchronize its clocks to a globally 580 accurate time standard. 582 request_time 584 The current value of the clock at the host at the time the request 585 resulting in the stored response was made. 587 response_time 589 The current value of the clock at the host at the time the 590 response was received. 592 A response's age can be calculated in two entirely independent ways: 594 1. the "apparent_age": response_time minus date_value, if the local 595 clock is reasonably well synchronized to the origin server's 596 clock. If the result is negative, the result is replaced by 597 zero. 599 2. the "corrected_age_value", if all of the caches along the 600 response path implement HTTP/1.1. A cache MUST interpret this 601 value relative to the time the request was initiated, not the 602 time that the response was received. 604 apparent_age = max(0, response_time - date_value); 606 response_delay = response_time - request_time; 607 corrected_age_value = age_value + response_delay; 609 These SHOULD be combined as 611 corrected_initial_age = max(apparent_age, corrected_age_value); 613 unless the cache is confident in the value of the Age header field 614 (e.g., because there are no HTTP/1.0 hops in the Via header field), 615 in which case the corrected_age_value MAY be used as the 616 corrected_initial_age. 618 The current_age of a stored response can then be calculated by adding 619 the amount of time (in seconds) since the stored response was last 620 validated by the origin server to the corrected_initial_age. 622 resident_time = now - response_time; 623 current_age = corrected_initial_age + resident_time; 625 Additionally, to avoid common problems in date parsing: 627 o Recipients SHOULD assume that an RFC-850 date which appears to be 628 more than 50 years in the future is in fact in the past (this 629 helps solve the "year 2000" problem). 631 o Although all date formats are specified to be case-sensitive, 632 recipients SHOULD match day, week and timezone names case- 633 insensitively. 635 o An implementation MAY internally represent a parsed Expires date 636 as earlier than the proper value, but MUST NOT internally 637 represent a parsed Expires date as later than the proper value. 639 o Recipients MUST perform all expiration-related calculations in 640 GMT. The local time zone MUST NOT influence the calculation or 641 comparison of an age or expiration time. 643 o Caches SHOULD consider dates with time zones other than "GMT" 644 invalid. 646 4.1.4. Serving Stale Responses 648 A "stale" response is one that either has explicit expiry information 649 or is allowed to have heuristic expiry calculated, but is not fresh 650 according to the calculations in Section 4.1. 652 A cache MUST NOT return a stale response if it is prohibited by an 653 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" 654 cache directive, a "must-revalidate" cache-response-directive, or an 655 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 656 see Section 7.2.2). 658 A cache MUST NOT return stale responses unless it is disconnected 659 (i.e., it cannot contact the origin server or otherwise find a 660 forward path) or doing so is explicitly allowed (e.g., by the max- 661 stale request directive; see Section 7.2.1). 663 A cache SHOULD append a Warning header field with the 110 warn-code 664 (see Section 7.5) to stale responses. Likewise, a cache SHOULD add 665 the 112 warn-code to stale responses if the cache is disconnected. 667 If a cache receives a first-hand response (either an entire response, 668 or a 304 (Not Modified) response) that it would normally forward to 669 the requesting client, and the received response is no longer fresh, 670 the cache can forward it to the requesting client without adding a 671 new Warning (but without removing any existing Warning header 672 fields). A cache shouldn't attempt to validate a response simply 673 because that response became stale in transit. 675 4.2. Validation Model 677 When a cache has one or more stored responses for a requested URI, 678 but cannot serve any of them (e.g., because they are not fresh, or 679 one cannot be selected; see Section 4.3), it can use the conditional 680 request mechanism [Part4] in the forwarded request to give the origin 681 server an opportunity to both select a valid stored response to be 682 used, and to update it. This process is known as "validating" or 683 "revalidating" the stored response. 685 When sending such a conditional request, a cache adds an If-Modified- 686 Since header field whose value is that of the Last-Modified header 687 field from the selected (see Section 4.3) stored response, if 688 available. 690 Additionally, a cache can add an If-None-Match header field whose 691 value is that of the ETag header field(s) from all responses stored 692 for the requested URI, if present. However, if any of the stored 693 responses contains only partial content, the cache shouldn't include 694 its entity-tag in the If-None-Match header field unless the request 695 is for a range that would be fully satisfied by that stored response. 697 Cache handling of a response to a conditional request is dependent 698 upon its status code: 700 o A 304 (Not Modified) response status code indicates that the 701 stored response can be updated and reused; see Section 4.2.1. 703 o A full response (i.e., one with a payload body) indicates that 704 none of the stored responses nominated in the conditional request 705 is suitable. Instead, the cache can use the full response to 706 satisfy the request and MAY replace the stored response(s). 708 o However, if a cache receives a 5xx (Server Error) response while 709 attempting to validate a response, it can either forward this 710 response to the requesting client, or act as if the server failed 711 to respond. In the latter case, it can return a previously stored 712 response (see Section 4.1.4). 714 4.2.1. Freshening Responses with 304 Not Modified 716 When a cache receives a 304 (Not Modified) response and already has 717 one or more stored 200 (OK) responses for the same cache key, the 718 cache needs to identify which of the stored responses are updated by 719 this new response and then update the stored response(s) with the new 720 information provided in the 304 response. 722 o If the new response contains a strong validator, then that strong 723 validator identifies the selected representation. All of the 724 stored responses with the same strong validator are selected. If 725 none of the stored responses contain the same strong validator, 726 then this new response corresponds to a new selected 727 representation and MUST NOT update the existing stored responses. 729 o If the new response contains a weak validator and that validator 730 corresponds to one of the cache's stored responses, then the most 731 recent of those matching stored responses is selected. 733 o If the new response does not include any form of validator, there 734 is only one stored response, and that stored response also lacks a 735 validator, then that stored response is selected. 737 If a stored response is selected for update, the cache MUST: 739 o delete any Warning header fields in the stored response with warn- 740 code 1xx (see Section 7.5); 742 o retain any Warning header fields in the stored response with warn- 743 code 2xx; and, 745 o use other header fields provided in the 304 (Not Modified) 746 response to replace all instances of the corresponding header 747 fields in the stored response. 749 4.3. Using Negotiated Responses 751 When a cache receives a request that can be satisfied by a stored 752 response that has a Vary header field (Section 8.2.1 of [Part2]), it 753 MUST NOT use that response unless all of the selecting header fields 754 nominated by the Vary header field match in both the original request 755 (i.e., that associated with the stored response), and the presented 756 request. 758 The selecting header fields from two requests are defined to match if 759 and only if those in the first request can be transformed to those in 760 the second request by applying any of the following: 762 o adding or removing whitespace, where allowed in the header field's 763 syntax 765 o combining multiple header fields with the same field name (see 766 Section 3.2 of [Part1]) 768 o normalizing both header field values in a way that is known to 769 have identical semantics, according to the header field's 770 specification (e.g., re-ordering field values when order is not 771 significant; case-normalization, where values are defined to be 772 case-insensitive) 774 If (after any normalization that might take place) a header field is 775 absent from a request, it can only match another request if it is 776 also absent there. 778 A Vary header field-value of "*" always fails to match, and 779 subsequent requests to that resource can only be properly interpreted 780 by the origin server. 782 The stored response with matching selecting header fields is known as 783 the selected response. 785 If multiple selected responses are available, the most recent 786 response (as determined by the Date header field) is used; see 787 Section 4. 789 If no selected response is available, the cache can forward the 790 presented request to the origin server in a conditional request; see 791 Section 4.2. 793 4.4. Combining Partial Content 795 A response might transfer only a partial representation if the 796 connection closed prematurely or if the request used one or more 797 Range specifiers ([Part5]). After several such transfers, a cache 798 might have received several ranges of the same representation. A 799 cache MAY combine these ranges into a single stored response, and 800 reuse that response to satisfy later requests, if they all share the 801 same strong validator and the cache complies with the client 802 requirements in Section 4.2 of [Part5]. 804 When combining the new response with one or more stored responses, a 805 cache MUST: 807 o delete any Warning header fields in the stored response with warn- 808 code 1xx (see Section 7.5); 810 o retain any Warning header fields in the stored response with warn- 811 code 2xx; and, 813 o use other header fields provided in the new response, aside from 814 Content-Range, to replace all instances of the corresponding 815 header fields in the stored response. 817 5. Updating Caches with HEAD Responses 819 A response to the HEAD method is identical to what an equivalent 820 request made with a GET would have been, except it lacks a body. 821 This property of HEAD responses is used to both invalidate and update 822 cached GET responses. 824 If one or more stored GET responses can be selected (as per 825 Section 4.3) for a HEAD request, and the Content-Length, ETag or 826 Last-Modified value of a HEAD response differs from that in a 827 selected GET response, the cache MUST consider that selected response 828 to be stale. 830 If the Content-Length, ETag and Last-Modified values of a HEAD 831 response (when present) are the same as that in a selected GET 832 response (as per Section 4.3), the cache SHOULD update the remaining 833 header fields in the stored response using the following rules: 835 o delete any Warning header fields in the stored response with warn- 836 code 1xx (see Section 7.5); 838 o retain any Warning header fields in the stored response with warn- 839 code 2xx; and, 841 o use other header fields provided in the response to replace all 842 instances of the corresponding header fields in the stored 843 response. 845 6. Request Methods that Invalidate 847 Because unsafe request methods (Section 5.2.1 of [Part2]) such as 848 PUT, POST or DELETE have the potential for changing state on the 849 origin server, intervening caches can use them to keep their contents 850 up-to-date. 852 A cache MUST invalidate the effective Request URI (Section 5.5 of 853 [Part1]) as well as the URI(s) in the Location and Content-Location 854 response header fields (if present) when a non-error response to a 855 request with an unsafe method is received. 857 However, a cache MUST NOT invalidate a URI from a Location or 858 Content-Location response header field if the host part of that URI 859 differs from the host part in the effective request URI (Section 5.5 860 of [Part1]). This helps prevent denial of service attacks. 862 A cache MUST invalidate the effective request URI (Section 5.5 of 863 [Part1]) when it receives a non-error response to a request with a 864 method whose safety is unknown. 866 Here, a "non-error response" is one with a 2xx (Successful) or 3xx 867 (Redirection) status code. "Invalidate" means that the cache will 868 either remove all stored responses related to the effective request 869 URI, or will mark these as "invalid" and in need of a mandatory 870 validation before they can be returned in response to a subsequent 871 request. 873 Note that this does not guarantee that all appropriate responses are 874 invalidated. For example, the request that caused the change at the 875 origin server might not have gone through the cache where a response 876 is stored. 878 7. Header Field Definitions 880 This section defines the syntax and semantics of HTTP/1.1 header 881 fields related to caching. 883 7.1. Age 885 The "Age" header field conveys the sender's estimate of the amount of 886 time since the response was generated or successfully validated at 887 the origin server. Age values are calculated as specified in 888 Section 4.1.3. 890 Age = delta-seconds 892 Age field-values are non-negative integers, representing time in 893 seconds (see Section 1.4.1). 895 The presence of an Age header field in a response implies that a 896 response is not first-hand. However, the converse is not true, since 897 HTTP/1.0 caches might not implement the Age header field. 899 7.2. Cache-Control 901 The "Cache-Control" header field is used to specify directives for 902 caches along the request/response chain. Such cache directives are 903 unidirectional in that the presence of a directive in a request does 904 not imply that the same directive is to be given in the response. 906 A cache MUST obey the requirements of the Cache-Control directives 907 defined in this section. See Section 7.2.3 for information about how 908 Cache-Control directives defined elsewhere are handled. 910 Note: HTTP/1.0 caches might not implement Cache-Control and might 911 only implement Pragma: no-cache (see Section 7.4). 913 A proxy, whether or not it implements a cache, MUST pass cache 914 directives through in forwarded messages, regardless of their 915 significance to that application, since the directives might be 916 applicable to all recipients along the request/response chain. It is 917 not possible to target a directive to a specific cache. 919 Cache directives are identified by a token, to be compared case- 920 insensitively, and have an optional argument, that can use both token 921 and quoted-string syntax. For the directives defined below that 922 define arguments, recipients ought to accept both forms, even if one 923 is documented to be preferred. For any directive not defined by this 924 specification, recipients MUST accept both forms. 926 Cache-Control = 1#cache-directive 928 cache-directive = token [ "=" ( token / quoted-string ) ] 930 For the cache directives defined below, no argument is defined (nor 931 allowed) otherwise stated otherwise. 933 7.2.1. Request Cache-Control Directives 935 7.2.1.1. no-cache 937 The "no-cache" request directive indicates that a cache MUST NOT use 938 a stored response to satisfy the request without successful 939 validation on the origin server. 941 7.2.1.2. no-store 943 The "no-store" request directive indicates that a cache MUST NOT 944 store any part of either this request or any response to it. This 945 directive applies to both private and shared caches. "MUST NOT 946 store" in this context means that the cache MUST NOT intentionally 947 store the information in non-volatile storage, and MUST make a best- 948 effort attempt to remove the information from volatile storage as 949 promptly as possible after forwarding it. 951 This directive is NOT a reliable or sufficient mechanism for ensuring 952 privacy. In particular, malicious or compromised caches might not 953 recognize or obey this directive, and communications networks might 954 be vulnerable to eavesdropping. 956 Note that if a request containing this directive is satisfied from a 957 cache, the no-store request directive does not apply to the already 958 stored response. 960 7.2.1.3. max-age 962 Argument syntax: 964 delta-seconds (see Section 1.4.1) 966 The "max-age" request directive indicates that the client is 967 unwilling to accept a response whose age is greater than the 968 specified number of seconds. Unless the max-stale request directive 969 is also present, the client is not willing to accept a stale 970 response. 972 Note: This directive uses the token form of the argument syntax; 973 e.g., 'max-age=5', not 'max-age="5"'. Senders SHOULD NOT use the 974 quoted-string form. 976 7.2.1.4. max-stale 978 Argument syntax: 980 delta-seconds (see Section 1.4.1) 982 The "max-stale" request directive indicates that the client is 983 willing to accept a response that has exceeded its expiration time. 984 If max-stale is assigned a value, then the client is willing to 985 accept a response that has exceeded its expiration time by no more 986 than the specified number of seconds. If no value is assigned to 987 max-stale, then the client is willing to accept a stale response of 988 any age. 990 Note: This directive uses the token form of the argument syntax; 991 e.g., 'max-stale=10', not 'max-stale="10"'. Senders SHOULD NOT use 992 the quoted-string form. 994 7.2.1.5. min-fresh 996 Argument syntax: 998 delta-seconds (see Section 1.4.1) 1000 The "min-fresh" request directive indicates that the client is 1001 willing to accept a response whose freshness lifetime is no less than 1002 its current age plus the specified time in seconds. That is, the 1003 client wants a response that will still be fresh for at least the 1004 specified number of seconds. 1006 Note: This directive uses the token form of the argument syntax; 1007 e.g., 'min-fresh=20', not 'min-fresh="20"'. Senders SHOULD NOT use 1008 the quoted-string form. 1010 7.2.1.6. no-transform 1012 The "no-transform" request directive indicates that an intermediary 1013 (whether or not it implements a cache) MUST NOT change the Content- 1014 Encoding, Content-Range or Content-Type request header fields, nor 1015 the request representation. 1017 7.2.1.7. only-if-cached 1019 The "only-if-cached" request directive indicates that the client only 1020 wishes to obtain a stored response. If it receives this directive, a 1021 cache SHOULD either respond using a stored response that is 1022 consistent with the other constraints of the request, or respond with 1023 a 504 (Gateway Timeout) status code. If a group of caches is being 1024 operated as a unified system with good internal connectivity, a 1025 member cache MAY forward such a request within that group of caches. 1027 7.2.2. Response Cache-Control Directives 1029 7.2.2.1. public 1031 The "public" response directive indicates that a response whose 1032 associated request contains an 'Authentication' header MAY be stored 1033 (see Section 3.2). 1035 7.2.2.2. private 1037 Argument syntax: 1039 #field-name 1041 The "private" response directive indicates that the response message 1042 is intended for a single user and MUST NOT be stored by a shared 1043 cache. A private cache MAY store the response. 1045 If the private response directive specifies one or more field-names, 1046 this requirement is limited to the field-values associated with the 1047 listed response header fields. That is, a shared cache MUST NOT 1048 store the specified field-names(s), whereas it MAY store the 1049 remainder of the response message. 1051 The field-names given are not limited to the set of standard header 1052 fields defined by this specification. Field names are case- 1053 insensitive. 1055 Note: This usage of the word "private" only controls where the 1056 response can be stored; it cannot ensure the privacy of the message 1057 content. Also, private response directives with field-names are 1058 often handled by implementations as if an unqualified private 1059 directive was received; i.e., the special handling for the qualified 1060 form is not widely implemented. 1062 Note: This directive uses the quoted-string form of the argument 1063 syntax. Senders SHOULD NOT use the token form (even if quoting 1064 appears not to be needed for single-entry lists). 1066 7.2.2.3. no-cache 1068 Argument syntax: 1070 #field-name 1072 The "no-cache" response directive indicates that the response MUST 1073 NOT be used to satisfy a subsequent request without successful 1074 validation on the origin server. This allows an origin server to 1075 prevent a cache from using it to satisfy a request without contacting 1076 it, even by caches that have been configured to return stale 1077 responses. 1079 If the no-cache response directive specifies one or more field-names, 1080 then a cache MAY use the response to satisfy a subsequent request, 1081 subject to any other restrictions on caching. However, any header 1082 fields in the response that have the field-name(s) listed MUST NOT be 1083 sent in the response to a subsequent request without successful 1084 revalidation with the origin server. This allows an origin server to 1085 prevent the re-use of certain header fields in a response, while 1086 still allowing caching of the rest of the response. 1088 The field-names given are not limited to the set of standard header 1089 fields defined by this specification. Field names are case- 1090 insensitive. 1092 Note: Many HTTP/1.0 caches will not recognize or obey this directive. 1093 Also, no-cache response directives with field-names are often handled 1094 by implementations as if an unqualified no-cache directive was 1095 received; i.e., the special handling for the qualified form is not 1096 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.4. no-store 1104 The "no-store" response directive indicates that a cache MUST NOT 1105 store any part of either the immediate request or response. This 1106 directive applies to both private and shared caches. "MUST NOT 1107 store" in this context means that the cache MUST NOT intentionally 1108 store the information in non-volatile storage, and MUST make a best- 1109 effort attempt to remove the information from volatile storage as 1110 promptly as possible after forwarding it. 1112 This directive is NOT a reliable or sufficient mechanism for ensuring 1113 privacy. In particular, malicious or compromised caches might not 1114 recognize or obey this directive, and communications networks might 1115 be vulnerable to eavesdropping. 1117 7.2.2.5. must-revalidate 1119 The "must-revalidate" response directive indicates that once it has 1120 become stale, a cache MUST NOT use the response to satisfy subsequent 1121 requests without successful validation on the origin server. 1123 The must-revalidate directive is necessary to support reliable 1124 operation for certain protocol features. In all circumstances a 1125 cache MUST obey the must-revalidate directive; in particular, if a 1126 cache cannot reach the origin server for any reason, it MUST generate 1127 a 504 (Gateway Timeout) response. 1129 The must-revalidate directive ought to be used by servers if and only 1130 if failure to validate a request on the representation could result 1131 in incorrect operation, such as a silently unexecuted financial 1132 transaction. 1134 7.2.2.6. proxy-revalidate 1136 The "proxy-revalidate" response directive has the same meaning as the 1137 must-revalidate response directive, except that it does not apply to 1138 private caches. 1140 7.2.2.7. max-age 1142 Argument syntax: 1144 delta-seconds (see Section 1.4.1) 1146 The "max-age" response directive indicates that the response is to be 1147 considered stale after its age is greater than the specified number 1148 of seconds. 1150 Note: This directive uses the token form of the argument syntax; 1151 e.g., 'max-age=5', not 'max-age="5"'. Senders SHOULD NOT use the 1152 quoted-string form. 1154 7.2.2.8. s-maxage 1156 Argument syntax: 1158 delta-seconds (see Section 1.4.1) 1160 The "s-maxage" response directive indicates that, in shared caches, 1161 the maximum age specified by this directive overrides the maximum age 1162 specified by either the max-age directive or the Expires header 1163 field. The s-maxage directive also implies the semantics of the 1164 proxy-revalidate response directive. 1166 Note: This directive uses the token form of the argument syntax; 1167 e.g., 's-maxage=10', not 's-maxage="10"'. Senders SHOULD NOT use the 1168 quoted-string form. 1170 7.2.2.9. no-transform 1172 The "no-transform" response directive indicates that an intermediary 1173 (regardless of whether it implements a cache) MUST NOT change the 1174 Content-Encoding, Content-Range or Content-Type response header 1175 fields, nor the response representation. 1177 7.2.3. Cache Control Extensions 1179 The Cache-Control header field can be extended through the use of one 1180 or more cache-extension tokens, each with an optional value. 1181 Informational extensions (those that do not require a change in cache 1182 behavior) can be added without changing the semantics of other 1183 directives. Behavioral extensions are designed to work by acting as 1184 modifiers to the existing base of cache directives. Both the new 1185 directive and the standard directive are supplied, such that 1186 applications that do not understand the new directive will default to 1187 the behavior specified by the standard directive, and those that 1188 understand the new directive will recognize it as modifying the 1189 requirements associated with the standard directive. In this way, 1190 extensions to the cache-control directives can be made without 1191 requiring changes to the base protocol. 1193 This extension mechanism depends on an HTTP cache obeying all of the 1194 cache-control directives defined for its native HTTP-version, obeying 1195 certain extensions, and ignoring all directives that it does not 1196 understand. 1198 For example, consider a hypothetical new response directive called 1199 "community" that acts as a modifier to the private directive. We 1200 define this new directive to mean that, in addition to any private 1201 cache, any cache that is shared only by members of the community 1202 named within its value is allowed to cache the response. An origin 1203 server wishing to allow the UCI community to use an otherwise private 1204 response in their shared cache(s) could do so by including 1206 Cache-Control: private, community="UCI" 1208 A cache seeing this header field will act correctly even if the cache 1209 does not understand the community cache-extension, since it will also 1210 see and understand the private directive and thus default to the safe 1211 behavior. 1213 A cache MUST ignore unrecognized cache directives; it is assumed that 1214 any cache directive likely to be unrecognized by an HTTP/1.1 cache 1215 will be combined with standard directives (or the response's default 1216 cacheability) such that the cache behavior will remain minimally 1217 correct even if the cache does not understand the extension(s). 1219 New extension directives ought to consider defining: 1221 o What it means for a directive to be specified multiple times, 1223 o When the directive does not take an argument, what it means when 1224 an argument is present, 1226 o When the directive requires an argument, what it means when it is 1227 missing. 1229 The HTTP Cache Directive Registry defines the name space for the 1230 cache directives. 1232 A registration MUST include the following fields: 1234 o Cache Directive Name 1236 o Pointer to specification text 1238 Values to be added to this name space require IETF Review (see 1239 [RFC5226], Section 4.1). 1241 The registry itself is maintained at 1242 . 1244 7.3. Expires 1246 The "Expires" header field gives the date/time after which the 1247 response is considered stale. See Section 4.1 for further discussion 1248 of the freshness model. 1250 The presence of an Expires field does not imply that the original 1251 resource will change or cease to exist at, before, or after that 1252 time. 1254 The field-value is an absolute date and time as defined by HTTP-date 1255 in Section 8.1.1.1 of [Part2]; a sender MUST use the rfc1123-date 1256 format. 1258 Expires = HTTP-date 1260 For example 1262 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1264 A cache MUST treat other invalid date formats, especially including 1265 the value "0", as in the past (i.e., "already expired"). 1267 Note: If a response includes a Cache-Control field with the max- 1268 age directive (see Section 7.2.2.7), that directive overrides the 1269 Expires field. Likewise, the s-maxage directive (Section 7.2.2.8) 1270 overrides the Expires header fieldin shared caches. 1272 Historically, HTTP required the Expires field-value to be no more 1273 than a year in the future. While longer freshness lifetimes are no 1274 longer prohibited, extremely large values have been demonstrated to 1275 cause problems (e.g., clock overflows due to use of 32-bit integers 1276 for time values), and many caches will evict a response far sooner 1277 than that. Therefore, senders ought not produce them. 1279 An origin server without a clock MUST NOT assign Expires values to a 1280 response unless these values were associated with the resource by a 1281 system or user with a reliable clock. It MAY assign an Expires value 1282 that is known, at or before server configuration time, to be in the 1283 past (this allows "pre-expiration" of responses without storing 1284 separate Expires values for each resource). 1286 7.4. Pragma 1288 The "Pragma" header field allows backwards compatibility with 1289 HTTP/1.0 caches, so that clients can specify a "no-cache" request 1290 that they will understand (as Cache-Control was not defined until 1291 HTTP/1.1). When the Cache-Control header field is also present and 1292 understood in a request, Pragma is ignored. 1294 In HTTP/1.0, Pragma was defined as an extensible field for 1295 implementation-specified directives for recipients. This 1296 specification deprecates such extensions to improve interoperability. 1298 Pragma = 1#pragma-directive 1299 pragma-directive = "no-cache" / extension-pragma 1300 extension-pragma = token [ "=" ( token / quoted-string ) ] 1302 When the Cache-Control header field is not present in a request, the 1303 no-cache request pragma-directive MUST have the same effect on caches 1304 as if "Cache-Control: no-cache" were present (see Section 7.2.1). 1306 When sending a no-cache request, a client ought to include both the 1307 pragma and cache-control directives, unless Cache-Control: no-cache 1308 is purposefully omitted to target other Cache-Control response 1309 directives at HTTP/1.1 caches. For example: 1311 GET / HTTP/1.1 1312 Host: www.example.com 1313 Cache-Control: max-age=30 1314 Pragma: no-cache 1316 will constrain HTTP/1.1 caches to serve a response no older than 30 1317 seconds, while precluding implementations that do not understand 1318 Cache-Control from serving a cached response. 1320 Note: Because the meaning of "Pragma: no-cache" in responses is 1321 not specified, it does not provide a reliable replacement for 1322 "Cache-Control: no-cache" in them. 1324 7.5. Warning 1326 The "Warning" header field is used to carry additional information 1327 about the status or transformation of a message that might not be 1328 reflected in the message. This information is typically used to warn 1329 about possible incorrectness introduced by caching operations or 1330 transformations applied to the payload of the message. 1332 Warnings can be used for other purposes, both cache-related and 1333 otherwise. The use of a warning, rather than an error status code, 1334 distinguishes these responses from true failures. 1336 Warning header fields can in general be applied to any message, 1337 however some warn-codes are specific to caches and can only be 1338 applied to response messages. 1340 Warning = 1#warning-value 1342 warning-value = warn-code SP warn-agent SP warn-text 1343 [SP warn-date] 1345 warn-code = 3DIGIT 1346 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1347 ; the name or pseudonym of the server adding 1348 ; the Warning header field, for use in debugging 1349 warn-text = quoted-string 1350 warn-date = DQUOTE HTTP-date DQUOTE 1352 Multiple warnings can be attached to a response (either by the origin 1353 server or by a cache), including multiple warnings with the same code 1354 number, only differing in warn-text. 1356 When this occurs, the user agent SHOULD inform the user of as many of 1357 them as possible, in the order that they appear in the response. 1359 Systems that generate multiple Warning header fields are encouraged 1360 to order them with this user agent behavior in mind. New Warning 1361 header fields are added after any existing Warning header fields. 1363 Warnings are assigned three digit warn-codes. The first digit 1364 indicates whether the Warning is required to be deleted from a stored 1365 response after validation: 1367 o 1xx Warnings describe the freshness or validation status of the 1368 response, and so MUST be deleted by a cache after validation. 1369 They can only be generated by a cache when validating a cached 1370 entry, and MUST NOT be generated in any other situation. 1372 o 2xx Warnings describe some aspect of the representation that is 1373 not rectified by a validation (for example, a lossy compression of 1374 the representation) and MUST NOT be deleted by a cache after 1375 validation, unless a full response is returned, in which case they 1376 MUST be. 1378 If an implementation sends a message with one or more Warning header 1379 fields to a receiver whose version is HTTP/1.0 or lower, then the 1380 sender MUST include in each warning-value a warn-date that matches 1381 the Date header field in the message. 1383 If a system receives a message with a warning-value that includes a 1384 warn-date, and that warn-date is different from the Date value in the 1385 response, then that warning-value MUST be deleted from the message 1386 before storing, forwarding, or using it. (preventing the consequences 1387 of naive caching of Warning header fields.) If all of the warning- 1388 values are deleted for this reason, the Warning header field MUST be 1389 deleted as well. 1391 The following warn-codes are defined by this specification, each with 1392 a recommended warn-text in English, and a description of its meaning. 1394 7.5.1. 110 Response is Stale 1396 A cache SHOULD include this whenever the returned response is stale. 1398 7.5.2. 111 Revalidation Failed 1400 A cache SHOULD include this when returning a stale response because 1401 an attempt to validate the response failed, due to an inability to 1402 reach the server. 1404 7.5.3. 112 Disconnected Operation 1406 A cache SHOULD include this if it is intentionally disconnected from 1407 the rest of the network for a period of time. 1409 7.5.4. 113 Heuristic Expiration 1411 A cache SHOULD include this if it heuristically chose a freshness 1412 lifetime greater than 24 hours and the response's age is greater than 1413 24 hours. 1415 7.5.5. 199 Miscellaneous Warning 1417 The warning text can include arbitrary information to be presented to 1418 a human user, or logged. A system receiving this warning MUST NOT 1419 take any automated action, besides presenting the warning to the 1420 user. 1422 7.5.6. 214 Transformation Applied 1424 MUST be added by a proxy if it applies any transformation to the 1425 representation, such as changing the content-coding, media-type, or 1426 modifying the representation data, unless this Warning code already 1427 appears in the response. 1429 7.5.7. 299 Miscellaneous Persistent Warning 1431 The warning text can include arbitrary information to be presented to 1432 a human user, or logged. A system receiving this warning MUST NOT 1433 take any automated action. 1435 7.5.8. Warn Code Extensions 1437 The HTTP Warn Code Registry defines the name space for warn codes. 1439 A registration MUST include the following fields: 1441 o Warn Code (3 digits) 1443 o Short Description 1445 o Pointer to specification text 1447 Values to be added to this name space require IETF Review (see 1448 [RFC5226], Section 4.1). 1450 The registry itself is maintained at 1451 . 1453 8. History Lists 1455 User agents often have history mechanisms, such as "Back" buttons and 1456 history lists, that can be used to redisplay a representation 1457 retrieved earlier in a session. 1459 The freshness model (Section 4.1) does not necessarily apply to 1460 history mechanisms. I.e., a history mechanism can display a previous 1461 representation even if it has expired. 1463 This does not prohibit the history mechanism from telling the user 1464 that a view might be stale, or from honoring cache directives (e.g., 1465 Cache-Control: no-store). 1467 9. IANA Considerations 1469 9.1. Cache Directive Registry 1471 The registration procedure for HTTP Cache Directives is defined by 1472 Section 7.2.3 of this document. 1474 The HTTP Cache Directive Registry shall be created at 1475 and be 1476 populated with the registrations below: 1478 +------------------------+----------------------------------+ 1479 | Cache Directive | Reference | 1480 +------------------------+----------------------------------+ 1481 | max-age | Section 7.2.1.3, Section 7.2.2.7 | 1482 | max-stale | Section 7.2.1.4 | 1483 | min-fresh | Section 7.2.1.5 | 1484 | must-revalidate | Section 7.2.2.5 | 1485 | no-cache | Section 7.2.1.1, Section 7.2.2.3 | 1486 | no-store | Section 7.2.1.2, Section 7.2.2.4 | 1487 | no-transform | Section 7.2.1.6, Section 7.2.2.9 | 1488 | only-if-cached | Section 7.2.1.7 | 1489 | private | Section 7.2.2.2 | 1490 | proxy-revalidate | Section 7.2.2.6 | 1491 | public | Section 7.2.2.1 | 1492 | s-maxage | Section 7.2.2.8 | 1493 | stale-if-error | [RFC5861], Section 4 | 1494 | stale-while-revalidate | [RFC5861], Section 3 | 1495 +------------------------+----------------------------------+ 1497 9.2. Warn Code Registry 1499 The registration procedure for HTTP Warn Codes is defined by 1500 Section 7.5.8 of this document. 1502 The HTTP Warn Code Registry shall be created at 1503 and be 1504 populated with the registrations below: 1506 +-----------+----------------------------------+---------------+ 1507 | Warn Code | Short Description | Reference | 1508 +-----------+----------------------------------+---------------+ 1509 | 110 | Response is Stale | Section 7.5.1 | 1510 | 111 | Revalidation Failed | Section 7.5.2 | 1511 | 112 | Disconnected Operation | Section 7.5.3 | 1512 | 113 | Heuristic Expiration | Section 7.5.4 | 1513 | 199 | Miscellaneous Warning | Section 7.5.5 | 1514 | 214 | Transformation Applied | Section 7.5.6 | 1515 | 299 | Miscellaneous Persistent Warning | Section 7.5.7 | 1516 +-----------+----------------------------------+---------------+ 1518 9.3. Header Field Registration 1520 The Message Header Field Registry located at shall be 1522 updated with the permanent registrations below (see [RFC3864]): 1524 +-------------------+----------+----------+-------------+ 1525 | Header Field Name | Protocol | Status | Reference | 1526 +-------------------+----------+----------+-------------+ 1527 | Age | http | standard | Section 7.1 | 1528 | Cache-Control | http | standard | Section 7.2 | 1529 | Expires | http | standard | Section 7.3 | 1530 | Pragma | http | standard | Section 7.4 | 1531 | Warning | http | standard | Section 7.5 | 1532 +-------------------+----------+----------+-------------+ 1534 The change controller is: "IETF (iesg@ietf.org) - Internet 1535 Engineering Task Force". 1537 10. Security Considerations 1539 Caches expose additional potential vulnerabilities, since the 1540 contents of the cache represent an attractive target for malicious 1541 exploitation. Because cache contents persist after an HTTP request 1542 is complete, an attack on the cache can reveal information long after 1543 a user believes that the information has been removed from the 1544 network. Therefore, cache contents need to be protected as sensitive 1545 information. 1547 Implementation flaws might allow attackers to insert content into a 1548 cache ("cache poisoning"), leading to compromise of clients that 1549 trust that content. Because of their nature, these attacks are 1550 difficult to mitigate. 1552 Likewise, implementation flaws (as well as misunderstanding of cache 1553 operation) might lead to caching of sensitive information (e.g., 1554 authentication credentials) that is thought to be private, exposing 1555 it to unauthorised parties. 1557 Note that the Set-Cookie response header [RFC6265] does not inhibit 1558 caching; a cacheable response with a Set-Cookie header can be (and 1559 often is) used to satisfy subsequent requests to caches. Servers who 1560 wish to control caching of these responses are encouraged to emit 1561 appropriate Cache-Control response headers. 1563 11. Acknowledgments 1565 See Section 9 of [Part1]. 1567 12. References 1569 12.1. Normative References 1571 [Part1] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1572 Protocol (HTTP/1.1): Message Syntax and Routing", 1573 draft-ietf-httpbis-p1-messaging-21 (work in progress), 1574 October 2012. 1576 [Part2] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1577 Protocol (HTTP/1.1): Semantics and Content", 1578 draft-ietf-httpbis-p2-semantics-21 (work in progress), 1579 October 2012. 1581 [Part4] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1582 Protocol (HTTP/1.1): Conditional Requests", 1583 draft-ietf-httpbis-p4-conditional-21 (work in progress), 1584 October 2012. 1586 [Part5] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 1587 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 1588 draft-ietf-httpbis-p5-range-21 (work in progress), 1589 October 2012. 1591 [Part7] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1592 Protocol (HTTP/1.1): Authentication", 1593 draft-ietf-httpbis-p7-auth-21 (work in progress), 1594 October 2012. 1596 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1597 Requirement Levels", BCP 14, RFC 2119, March 1997. 1599 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1600 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1602 12.2. Informative References 1604 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1605 Specification, Implementation", RFC 1305, March 1992. 1607 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1608 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1609 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1611 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1612 Procedures for Message Header Fields", BCP 90, RFC 3864, 1613 September 2004. 1615 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1616 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1617 May 2008. 1619 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1620 Content", RFC 5861, April 2010. 1622 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1623 April 2011. 1625 Appendix A. Changes from RFC 2616 1627 Make the specified age calculation algorithm less conservative. 1628 (Section 4.1.3) 1630 Remove requirement to consider "Content-Location" in successful 1631 responses in order to determine the appropriate response to use. 1632 (Section 4.2) 1634 Clarify denial of service attack avoidance requirement. (Section 6) 1636 Do not mention RFC 2047 encoding and multiple languages in "Warning" 1637 header fields anymore, as these aspects never were implemented. 1638 (Section 7.5) 1640 Introduce Cache Directive and Warn Code Registries. (Section 7.2.3 1641 and Section 7.5.8) 1643 Appendix B. Imported ABNF 1645 The following core rules are included by reference, as defined in 1646 Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), 1647 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 1648 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 1649 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII 1650 character). 1652 The rules below are defined in [Part1]: 1654 OWS = 1655 field-name = 1656 quoted-string = 1657 token = 1659 port = 1660 pseudonym = 1661 uri-host = 1663 The rules below are defined in other parts: 1665 HTTP-date = 1667 Appendix C. Collected ABNF 1669 Age = delta-seconds 1671 Cache-Control = *( "," OWS ) cache-directive *( OWS "," [ OWS 1672 cache-directive ] ) 1674 Expires = HTTP-date 1676 HTTP-date = 1678 OWS = 1680 Pragma = *( "," OWS ) pragma-directive *( OWS "," [ OWS 1681 pragma-directive ] ) 1683 Warning = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value ] 1684 ) 1686 cache-directive = token [ "=" ( token / quoted-string ) ] 1688 delta-seconds = 1*DIGIT 1690 extension-pragma = token [ "=" ( token / quoted-string ) ] 1692 field-name = 1694 port = 1695 pragma-directive = "no-cache" / extension-pragma 1696 pseudonym = 1698 quoted-string = 1700 token = 1702 uri-host = 1704 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1705 warn-code = 3DIGIT 1706 warn-date = DQUOTE HTTP-date DQUOTE 1707 warn-text = quoted-string 1708 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date 1709 ] 1711 Appendix D. Change Log (to be removed by RFC Editor before publication) 1713 Changes up to the first Working Group Last Call draft are summarized 1714 in . 1717 D.1. Since draft-ietf-httpbis-p6-cache-19 1719 Closed issues: 1721 o : "untangle 1722 Cache-Control ABNF" 1724 o : "Multiple 1725 values in Cache-Control header fields" 1727 o : "Case 1728 sensitivity of header fields in CC values" 1730 o : "Spurious 1731 'MAYs'" 1733 o : "enhance 1734 considerations for new cache control directives" 1736 o : "ABNF 1737 requirements for recipients" 1739 o : "note 1740 introduction of new IANA registries as normative changes" 1742 o : "broken prose 1743 in description of 'Vary'" 1745 D.2. Since draft-ietf-httpbis-p6-cache-20 1747 Closed issues: 1749 o : "'Most 1750 Conservative'" 1752 Other changes: 1754 o Conformance criteria and considerations regarding error handling 1755 are now defined in Part 1. 1757 o Move definition of "Vary" header field into Part 2. 1759 o Add security considerations with respect to cache poisoning and 1760 the "Set-Cookie" header field. 1762 Index 1764 1 1765 110 Response is Stale (warn code) 30 1766 111 Revalidation Failed (warn code) 30 1767 112 Disconnected Operation (warn code) 30 1768 113 Heuristic Expiration (warn code) 30 1769 199 Miscellaneous Warning (warn code) 30 1771 2 1772 214 Transformation Applied (warn code) 30 1773 299 Miscellaneous Persistent Warning (warn code) 31 1775 A 1776 age 5 1777 Age header field 19 1779 C 1780 cache 4 1781 cache entry 6 1782 cache key 6 1783 Cache-Control header field 20 1784 cacheable 4 1786 E 1787 Expires header field 27 1788 explicit expiration time 5 1790 F 1791 first-hand 5 1792 fresh 5 1793 freshness lifetime 5 1795 G 1796 Grammar 1797 Age 19 1798 Cache-Control 20 1799 cache-directive 20 1800 delta-seconds 6 1801 Expires 27 1802 extension-pragma 28 1803 Pragma 28 1804 pragma-directive 28 1805 warn-agent 29 1806 warn-code 29 1807 warn-date 29 1808 warn-text 29 1809 Warning 29 1810 warning-value 29 1812 H 1813 heuristic expiration time 5 1815 M 1816 max-age (cache directive) 21, 25 1817 max-stale (cache directive) 21 1818 min-fresh (cache directive) 22 1819 must-revalidate (cache directive) 24 1821 N 1822 no-cache (cache directive) 20, 23 1823 no-store (cache directive) 20, 24 1824 no-transform (cache directive) 22, 25 1826 O 1827 only-if-cached (cache directive) 22 1829 P 1830 Pragma header field 28 1831 private (cache directive) 22 1832 private cache 4 1833 proxy-revalidate (cache directive) 24 1834 public (cache directive) 22 1836 S 1837 s-maxage (cache directive) 25 1838 shared cache 4 1839 stale 5 1840 strong validator 6 1842 V 1843 validator 5 1844 strong 6 1846 W 1847 Warning header field 28 1849 Authors' Addresses 1851 Roy T. Fielding (editor) 1852 Adobe Systems Incorporated 1853 345 Park Ave 1854 San Jose, CA 95110 1855 USA 1857 EMail: fielding@gbiv.com 1858 URI: http://roy.gbiv.com/ 1860 Mark Nottingham (editor) 1861 Akamai 1863 EMail: mnot@mnot.net 1864 URI: http://www.mnot.net/ 1866 Julian F. Reschke (editor) 1867 greenbytes GmbH 1868 Hafenweg 16 1869 Muenster, NW 48155 1870 Germany 1872 EMail: julian.reschke@greenbytes.de 1873 URI: http://greenbytes.de/tech/webdav/