idnits 2.17.00 (12 Aug 2021) /tmp/idnits40692/draft-ietf-httpbis-p6-cache-23.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 : ---------------------------------------------------------------------------- == There are 2 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. -- 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 15, 2013) is 3231 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 (~~), 7 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: January 16, 2014 J. Reschke, Ed. 7 greenbytes 8 July 15, 2013 10 Hypertext Transfer Protocol (HTTP/1.1): Caching 11 draft-ietf-httpbis-p6-cache-23 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.4. 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 January 16, 2014. 50 Copyright Notice 52 Copyright (c) 2013 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. Conformance and Error Handling . . . . . . . . . . . . . . 4 81 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 4 82 1.2.1. Delta Seconds . . . . . . . . . . . . . . . . . . . . 5 83 2. Overview of Cache Operation . . . . . . . . . . . . . . . . . 5 84 3. Storing Responses in Caches . . . . . . . . . . . . . . . . . 6 85 3.1. Storing Incomplete Responses . . . . . . . . . . . . . . . 7 86 3.2. Storing Responses to Authenticated Requests . . . . . . . 7 87 3.3. Combining Partial Content . . . . . . . . . . . . . . . . 7 88 4. Constructing Responses from Caches . . . . . . . . . . . . . . 8 89 4.1. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 9 90 4.1.1. Calculating Freshness Lifetime . . . . . . . . . . . . 11 91 4.1.2. Calculating Heuristic Freshness . . . . . . . . . . . 11 92 4.1.3. Calculating Age . . . . . . . . . . . . . . . . . . . 12 93 4.1.4. Serving Stale Responses . . . . . . . . . . . . . . . 13 94 4.2. Validation . . . . . . . . . . . . . . . . . . . . . . . . 14 95 4.2.1. Freshening Stored Responses upon Validation . . . . . 15 97 4.3. Calculating Secondary Keys with Vary . . . . . . . . . . . 16 98 5. Updating Caches with HEAD Responses . . . . . . . . . . . . . 17 99 6. Request Methods that Invalidate . . . . . . . . . . . . . . . 17 100 7. Header Field Definitions . . . . . . . . . . . . . . . . . . . 18 101 7.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 102 7.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 18 103 7.2.1. Request Cache-Control Directives . . . . . . . . . . . 19 104 7.2.2. Response Cache-Control Directives . . . . . . . . . . 21 105 7.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 24 106 7.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 25 107 7.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 26 108 7.5. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 27 109 7.5.1. 110 Response is Stale . . . . . . . . . . . . . . . . 28 110 7.5.2. 111 Revalidation Failed . . . . . . . . . . . . . . . 28 111 7.5.3. 112 Disconnected Operation . . . . . . . . . . . . . . 28 112 7.5.4. 113 Heuristic Expiration . . . . . . . . . . . . . . . 29 113 7.5.5. 199 Miscellaneous Warning . . . . . . . . . . . . . . 29 114 7.5.6. 214 Transformation Applied . . . . . . . . . . . . . . 29 115 7.5.7. 299 Miscellaneous Persistent Warning . . . . . . . . . 29 116 7.5.8. Warn Code Extensions . . . . . . . . . . . . . . . . . 29 117 8. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 29 118 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 119 9.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 30 120 9.1.1. Procedure . . . . . . . . . . . . . . . . . . . . . . 30 121 9.1.2. Considerations for New Cache Control Directives . . . 30 122 9.1.3. Registrations . . . . . . . . . . . . . . . . . . . . 30 123 9.2. Warn Code Registry . . . . . . . . . . . . . . . . . . . . 31 124 9.2.1. Procedure . . . . . . . . . . . . . . . . . . . . . . 31 125 9.2.2. Registrations . . . . . . . . . . . . . . . . . . . . 31 126 9.3. Header Field Registration . . . . . . . . . . . . . . . . 32 127 10. Security Considerations . . . . . . . . . . . . . . . . . . . 32 128 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 33 129 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 33 130 12.1. Normative References . . . . . . . . . . . . . . . . . . . 33 131 12.2. Informative References . . . . . . . . . . . . . . . . . . 34 132 Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 34 133 Appendix B. Imported ABNF . . . . . . . . . . . . . . . . . . . . 36 134 Appendix C. Collected ABNF . . . . . . . . . . . . . . . . . . . 36 135 Appendix D. Change Log (to be removed by RFC Editor before 136 publication) . . . . . . . . . . . . . . . . . . . . 37 137 D.1. Since draft-ietf-httpbis-p6-cache-19 . . . . . . . . . . . 38 138 D.2. Since draft-ietf-httpbis-p6-cache-20 . . . . . . . . . . . 38 139 D.3. Since draft-ietf-httpbis-p6-cache-21 . . . . . . . . . . . 39 140 D.4. Since draft-ietf-httpbis-p6-cache-22 . . . . . . . . . . . 39 141 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 143 1. Introduction 145 HTTP is typically used for distributed information systems, where 146 performance can be improved by the use of response caches. This 147 document defines aspects of HTTP/1.1 related to caching and reusing 148 response messages. 150 An HTTP cache is a local store of response messages and the subsystem 151 that controls storage, retrieval, and deletion of messages in it. A 152 cache stores cacheable responses in order to reduce the response time 153 and network bandwidth consumption on future, equivalent requests. 154 Any client or server MAY employ a cache, though a cache cannot be 155 used by a server that is acting as a tunnel. 157 A shared cache is a cache that stores responses to be reused by more 158 than one user; shared caches are usually (but not always) deployed as 159 a part of an intermediary. A private cache, in contrast, is 160 dedicated to a single user. 162 The goal of caching in HTTP/1.1 is to significantly improve 163 performance by reusing a prior response message to satisfy a current 164 request. A stored response is considered "fresh", as defined in 165 Section 4.1, if the response can be reused without "validation" 166 (checking with the origin server to see if the cached response 167 remains valid for this request). A fresh response can therefore 168 reduce both latency and network overhead each time it is reused. 169 When a cached response is not fresh, it might still be reusable if it 170 can be freshened by validation (Section 4.2) or if the origin is 171 unavailable (Section 4.1.4). 173 1.1. Conformance and Error Handling 175 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 176 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 177 document are to be interpreted as described in [RFC2119]. 179 Conformance criteria and considerations regarding error handling are 180 defined in Section 2.5 of [Part1]. 182 1.2. Syntax Notation 184 This specification uses the Augmented Backus-Naur Form (ABNF) 185 notation of [RFC5234] with the list rule extension defined in Section 186 1.2 of [Part1]. Appendix B describes rules imported from other 187 documents. Appendix C shows the collected ABNF with the list rule 188 expanded. 190 1.2.1. Delta Seconds 192 The delta-seconds rule specifies a non-negative integer, representing 193 time in seconds. 195 delta-seconds = 1*DIGIT 197 If a cache receives a delta-seconds value larger than the largest 198 positive integer it can represent, or if any of its subsequent 199 calculations overflows, it MUST consider the value to be 2147483648 200 (2^31). Recipients parsing a delta-seconds value MUST use an 201 arithmetic type of at least 31 bits of range, and senders MUST NOT 202 generate delta-seconds with a value greater than 2147483648. 204 2. Overview of Cache Operation 206 Proper cache operation preserves the semantics of HTTP transfers 207 ([Part2]) while eliminating the transfer of information already held 208 in the cache. Although caching is an entirely OPTIONAL feature of 209 HTTP, we assume that reusing the cached response is desirable and 210 that such reuse is the default behavior when no requirement or local 211 configuration prevents it. Therefore, HTTP cache requirements are 212 focused on preventing a cache from either storing a non-reusable 213 response or reusing a stored response inappropriately, rather than 214 mandating that caches always store and reuse particular responses. 216 Each cache entry consists of a cache key and one or more HTTP 217 responses corresponding to prior requests that used the same key. 218 The most common form of cache entry is a successful result of a 219 retrieval request: i.e., a 200 (OK) response to a GET request, which 220 contains a representation of the resource identified by the request 221 target (Section 4.3.1 of [Part2]). However, it is also possible to 222 cache permanent redirects, negative results (e.g., 404 (Not Found)), 223 incomplete results (e.g., 206 (Partial Content)), and responses to 224 methods other than GET if the method's definition allows such caching 225 and defines something suitable for use as a cache key. 227 The primary cache key consists of the request method and target URI. 228 However, since HTTP caches in common use today are typically limited 229 to caching responses to GET, many caches simply decline other methods 230 and use only the URI as the primary cache key. 232 If a request target is subject to content negotiation, its cache 233 entry might consist of multiple stored responses, each differentiated 234 by a secondary key for the values of the original request's selecting 235 header fields (Section 4.3). 237 3. Storing Responses in Caches 239 A cache MUST NOT store a response to any request, unless: 241 o The request method is understood by the cache and defined as being 242 cacheable, and 244 o the response status code is understood by the cache, and 246 o the "no-store" cache directive (see Section 7.2) does not appear 247 in request or response header fields, and 249 o the "private" cache response directive (see Section 7.2.2.6) does 250 not appear in the response, if the cache is shared, and 252 o the Authorization header field (see Section 4.1 of [Part7]) does 253 not appear in the request, if the cache is shared, unless the 254 response explicitly allows it (see Section 3.2), and 256 o the response either: 258 * contains an Expires header field (see Section 7.3), or 260 * contains a max-age response cache directive (see 261 Section 7.2.2.8), or 263 * contains a s-maxage response cache directive (see 264 Section 7.2.2.9) and the cache is shared, or 266 * contains a Cache Control Extension (see Section 7.2.3) that 267 allows it to be cached, or 269 * has a status code that is defined as cacheable (see 270 Section 4.1.2), or 272 * contains a public response cache directive (see 273 Section 7.2.2.5). 275 Note that any of the requirements listed above can be overridden by a 276 cache-control extension; see Section 7.2.3. 278 In this context, a cache has "understood" a request method or a 279 response status code if it recognizes it and implements all specified 280 caching-related behavior. 282 Note that, in normal operation, some caches will not store a response 283 that has neither a cache validator nor an explicit expiration time, 284 as such responses are not usually useful to store. However, caches 285 are not prohibited from storing such responses. 287 3.1. Storing Incomplete Responses 289 A response message is considered complete when all of the octets 290 indicated by the message framing ([Part1]) are received prior to the 291 connection being closed. If the request is GET, the response status 292 is 200 (OK), and the entire response header block has been received, 293 a cache MAY store an incomplete response message body if the cache 294 entry is recorded as incomplete. Likewise, a 206 (Partial Content) 295 response MAY be stored as if it were an incomplete 200 (OK) cache 296 entry. However, a cache MUST NOT store incomplete or partial content 297 responses if it does not support the Range and Content-Range header 298 fields or if it does not understand the range units used in those 299 fields. 301 A cache MAY complete a stored incomplete response by making a 302 subsequent range request ([Part5]) and combining the successful 303 response with the stored entry, as defined in Section 3.3. A cache 304 MUST NOT use an incomplete response to answer requests unless the 305 response has been made complete or the request is partial and 306 specifies a range that is wholly within the incomplete response. A 307 cache MUST NOT send a partial response to a client without explicitly 308 marking it as such using the 206 (Partial Content) status code. 310 3.2. Storing Responses to Authenticated Requests 312 A shared cache MUST NOT use a cached response to a request with an 313 Authorization header field (Section 4.1 of [Part7]) to satisfy any 314 subsequent request unless a cache directive that allows such 315 responses to be stored is present in the response. 317 In this specification, the following Cache-Control response 318 directives (Section 7.2.2) have such an effect: must-revalidate, 319 public, s-maxage. 321 Note that cached responses that contain the "must-revalidate" and/or 322 "s-maxage" response directives are not allowed to be served stale 323 (Section 4.1.4) by shared caches. In particular, a response with 324 either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to 325 satisfy a subsequent request without revalidating it on the origin 326 server. 328 3.3. Combining Partial Content 330 A response might transfer only a partial representation if the 331 connection closed prematurely or if the request used one or more 332 Range specifiers ([Part5]). After several such transfers, a cache 333 might have received several ranges of the same representation. A 334 cache MAY combine these ranges into a single stored response, and 335 reuse that response to satisfy later requests, if they all share the 336 same strong validator and the cache complies with the client 337 requirements in Section 4.3 of [Part5]. 339 When combining the new response with one or more stored responses, a 340 cache MUST: 342 o delete any Warning header fields in the stored response with warn- 343 code 1xx (see Section 7.5); 345 o retain any Warning header fields in the stored response with warn- 346 code 2xx; and, 348 o use other header fields provided in the new response, aside from 349 Content-Range, to replace all instances of the corresponding 350 header fields in the stored response. 352 4. Constructing Responses from Caches 354 When presented with a request, a cache MUST NOT reuse a stored 355 response, unless: 357 o The presented effective request URI (Section 5.5 of [Part1]) and 358 that of the stored response match, and 360 o the request method associated with the stored response allows it 361 to be used for the presented request, and 363 o selecting header fields nominated by the stored response (if any) 364 match those presented (see Section 4.3), and 366 o the presented request does not contain the no-cache pragma 367 (Section 7.4), nor the no-cache cache directive (Section 7.2.1), 368 unless the stored response is successfully validated 369 (Section 4.2), and 371 o the stored response does not contain the no-cache cache directive 372 (Section 7.2.2.2), unless it is successfully validated 373 (Section 4.2), and 375 o the stored response is either: 377 * fresh (see Section 4.1), or 379 * allowed to be served stale (see Section 4.1.4), or 380 * successfully validated (see Section 4.2). 382 Note that any of the requirements listed above can be overridden by a 383 cache-control extension; see Section 7.2.3. 385 When a stored response is used to satisfy a request without 386 validation, a cache MUST generate an Age header field (Section 7.1), 387 replacing any present in the response with a value equal to the 388 stored response's current_age; see Section 4.1.3. 390 A cache MUST write through requests with methods that are unsafe 391 (Section 4.2.1 of [Part2]) to the origin server; i.e., a cache is not 392 allowed to generate a reply to such a request before having forwarded 393 the request and having received a corresponding response. 395 Also, note that unsafe requests might invalidate already stored 396 responses; see Section 6. 398 When more than one suitable response is stored, a cache MUST use the 399 most recent response (as determined by the Date header field). It 400 can also forward the request with "Cache-Control: max-age=0" or 401 "Cache-Control: no-cache" to disambiguate which response to use. 403 A cache that does not have a clock available MUST NOT use stored 404 responses without revalidating them upon every use. 406 4.1. Freshness 408 A fresh response is one whose age has not yet exceeded its freshness 409 lifetime. Conversely, a stale response is one where it has. 411 A response's freshness lifetime is the length of time between its 412 generation by the origin server and its expiration time. An explicit 413 expiration time is the time at which the origin server intends that a 414 stored response can no longer be used by a cache without further 415 validation, whereas a heuristic expiration time is assigned by a 416 cache when no explicit expiriation time is available. 418 A response's age is the time that has passed since it was generated 419 by, or successfully validated with, the origin server. 421 When a response is "fresh" in the cache, it can be used to satisfy 422 subsequent requests without contacting the origin server, thereby 423 improving efficiency. 425 The primary mechanism for determining freshness is for an origin 426 server to provide an explicit expiration time in the future, using 427 either the Expires header field (Section 7.3) or the max-age response 428 cache directive (Section 7.2.2.8). Generally, origin servers will 429 assign future explicit expiration times to responses in the belief 430 that the representation is not likely to change in a semantically 431 significant way before the expiration time is reached. 433 If an origin server wishes to force a cache to validate every 434 request, it can assign an explicit expiration time in the past to 435 indicate that the response is already stale. Compliant caches will 436 normally validate a stale cached response before reusing it for 437 subsequent requests (see Section 4.1.4). 439 Since origin servers do not always provide explicit expiration times, 440 caches are also allowed to use a heuristic to determine an expiration 441 time under certain circumstances (see Section 4.1.2). 443 The calculation to determine if a response is fresh is: 445 response_is_fresh = (freshness_lifetime > current_age) 447 freshness_lifetime is defined in Section 4.1.1; current_age is 448 defined in Section 4.1.3. 450 Clients can send the max-age or min-fresh cache directives in a 451 request to constrain or relax freshness calculations for the 452 corresponding response (Section 7.2.1). 454 When calculating freshness, to avoid common problems in date parsing: 456 o Although all date formats are specified to be case-sensitive, 457 cache recipients SHOULD match day, week and timezone names case- 458 insensitively. 460 o If a cache recipient's internal implementation of time has less 461 resolution than the value of an HTTP-date, the recipient MUST 462 internally represent a parsed Expires date as the nearest time 463 equal to or earlier than the received value. 465 o Cache recipients MUST NOT allow local time zones to influence the 466 calculation or comparison of an age or expiration time. 468 o Cache recipients SHOULD consider a date with a zone abbreviation 469 other than "GMT" to be invalid for calculating expiration. 471 Note that freshness applies only to cache operation; it cannot be 472 used to force a user agent to refresh its display or reload a 473 resource. See Section 8 for an explanation of the difference between 474 caches and history mechanisms. 476 4.1.1. Calculating Freshness Lifetime 478 A cache can calculate the freshness lifetime (denoted as 479 freshness_lifetime) of a response by using the first match of: 481 o If the cache is shared and the s-maxage response cache directive 482 (Section 7.2.2.9) is present, use its value, or 484 o If the max-age response cache directive (Section 7.2.2.8) is 485 present, use its value, or 487 o If the Expires response header field (Section 7.3) is present, use 488 its value minus the value of the Date response header field, or 490 o Otherwise, no explicit expiration time is present in the response. 491 A heuristic freshness lifetime might be applicable; see 492 Section 4.1.2. 494 Note that this calculation is not vulnerable to clock skew, since all 495 of the information comes from the origin server. 497 When there is more than one value present for a given directive 498 (e.g., two Expires header fields, multiple Cache-Control: max-age 499 directives), the directive's value is considered invalid. Caches are 500 encouraged to consider responses that have invalid freshness 501 information to be stale. 503 4.1.2. Calculating Heuristic Freshness 505 Since origin servers do not always provide explicit expiration times, 506 a cache MAY assign a heuristic expiration time when an explicit time 507 is not specified, employing algorithms that use other header field 508 values (such as the Last-Modified time) to estimate a plausible 509 expiration time. This specification does not provide specific 510 algorithms, but does impose worst-case constraints on their results. 512 A cache MUST NOT use heuristics to determine freshness when an 513 explicit expiration time is present in the stored response. Because 514 of the requirements in Section 3, this means that, effectively, 515 heuristics can only be used on responses without explicit freshness 516 whose status codes are defined as cacheable, and responses without 517 explicit freshness that have been marked as explicitly cacheable 518 (e.g., with a "public" response cache directive). 520 If the response has a Last-Modified header field (Section 2.2 of 521 [Part4]), caches are encouraged to use a heuristic expiration value 522 that is no more than some fraction of the interval since that time. 523 A typical setting of this fraction might be 10%. 525 When a heuristic is used to calculate freshness lifetime, a cache 526 SHOULD attach a Warning header field with a 113 warn-code to the 527 response if its current_age is more than 24 hours and such a warning 528 is not already present. 530 Note: Section 13.9 of [RFC2616] prohibited caches from calculating 531 heuristic freshness for URIs with query components (i.e., those 532 containing '?'). In practice, this has not been widely 533 implemented. Therefore, origin servers are encouraged to send 534 explicit directives (e.g., Cache-Control: no-cache) if they wish 535 to preclude caching. 537 4.1.3. Calculating Age 539 The Age header field is used to convey an estimated age of the 540 response message when obtained from a cache. The Age field value is 541 the cache's estimate of the number of seconds since the response was 542 generated or validated by the origin server. In essence, the Age 543 value is the sum of the time that the response has been resident in 544 each of the caches along the path from the origin server, plus the 545 amount of time it has been in transit along network paths. 547 The following data is used for the age calculation: 549 age_value 551 The term "age_value" denotes the value of the Age header field 552 (Section 7.1), in a form appropriate for arithmetic operation; or 553 0, if not available. 555 date_value 557 The term "date_value" denotes the value of the Date header field, 558 in a form appropriate for arithmetic operations. See Section 559 7.1.1.2 of [Part2] for the definition of the Date header field, 560 and for requirements regarding responses without it. 562 now 564 The term "now" means "the current value of the clock at the host 565 performing the calculation". A host ought to use NTP ([RFC1305]) 566 or some similar protocol to synchronize its clocks to Coordinated 567 Universal Time. 569 request_time 571 The current value of the clock at the host at the time the request 572 resulting in the stored response was made. 574 response_time 576 The current value of the clock at the host at the time the 577 response was received. 579 A response's age can be calculated in two entirely independent ways: 581 1. the "apparent_age": response_time minus date_value, if the local 582 clock is reasonably well synchronized to the origin server's 583 clock. If the result is negative, the result is replaced by 584 zero. 586 2. the "corrected_age_value", if all of the caches along the 587 response path implement HTTP/1.1. A cache MUST interpret this 588 value relative to the time the request was initiated, not the 589 time that the response was received. 591 apparent_age = max(0, response_time - date_value); 593 response_delay = response_time - request_time; 594 corrected_age_value = age_value + response_delay; 596 These are combined as 598 corrected_initial_age = max(apparent_age, corrected_age_value); 600 unless the cache is confident in the value of the Age header field 601 (e.g., because there are no HTTP/1.0 hops in the Via header field), 602 in which case the corrected_age_value MAY be used as the 603 corrected_initial_age. 605 The current_age of a stored response can then be calculated by adding 606 the amount of time (in seconds) since the stored response was last 607 validated by the origin server to the corrected_initial_age. 609 resident_time = now - response_time; 610 current_age = corrected_initial_age + resident_time; 612 4.1.4. Serving Stale Responses 614 A "stale" response is one that either has explicit expiry information 615 or is allowed to have heuristic expiry calculated, but is not fresh 616 according to the calculations in Section 4.1. 618 A cache MUST NOT generate a stale response if it is prohibited by an 619 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" 620 cache directive, a "must-revalidate" cache-response-directive, or an 621 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 622 see Section 7.2.2). 624 A cache MUST NOT send stale responses unless it is disconnected 625 (i.e., it cannot contact the origin server or otherwise find a 626 forward path) or doing so is explicitly allowed (e.g., by the max- 627 stale request directive; see Section 7.2.1). 629 A cache SHOULD append a Warning header field with the 110 warn-code 630 (see Section 7.5) to stale responses. Likewise, a cache SHOULD add 631 the 112 warn-code to stale responses if the cache is disconnected. 633 Note that if a cache receives a first-hand response (one where the 634 freshness model is not in use; i.e., its age is 0, whether it is an 635 entire response, or a 304 (Not Modified) response) that it would 636 normally forward to the requesting client, and the received response 637 is no longer fresh, the cache MAY forward it to the requesting client 638 without adding a new Warning (but without removing any existing 639 Warning header fields). A cache ought not attempt to validate a 640 response simply because that response became stale in transit. 642 4.2. Validation 644 When a cache has one or more stored responses for a requested URI, 645 but cannot serve any of them (e.g., because they are not fresh, or 646 one cannot be selected; see Section 4.3), it can use the conditional 647 request mechanism [Part4] in the forwarded request to give the origin 648 server an opportunity to both select a valid stored response to be 649 used, and to update it. This process is known as "validating" or 650 "revalidating" the stored response. 652 When sending such a conditional request, a cache adds a validator (or 653 more than one), that is used to find out whether a stored response is 654 an equivalent copy of a current representation of the resource. 656 One such validator is the If-Modified-Since header field, whose value 657 is that of the Last-Modified header field from the selected (see 658 Section 4.3) stored response, if available. 660 Another is the If-None-Match header field, whose value is that of the 661 ETag header field(s) from relevant responses stored for the primary 662 cache key, if present. However, if any of the stored responses 663 contains only partial content, the cache ought not include its 664 entity-tag in the If-None-Match header field unless the request is 665 for a range that would be fully satisfied by that stored response. 667 Cache handling of a response to a conditional request is dependent 668 upon its status code: 670 o A 304 (Not Modified) response status code indicates that the 671 stored response can be updated and reused; see Section 4.2.1. 673 o A full response (i.e., one with a payload body) indicates that 674 none of the stored responses nominated in the conditional request 675 is suitable. Instead, the cache can use the full response to 676 satisfy the request and MAY replace the stored response(s). 678 o However, if a cache receives a 5xx (Server Error) response while 679 attempting to validate a response, it can either forward this 680 response to the requesting client, or act as if the server failed 681 to respond. In the latter case, it can send a previously stored 682 response (see Section 4.1.4). 684 4.2.1. Freshening Stored Responses upon Validation 686 When a cache receives a 304 (Not Modified) response and already has 687 one or more stored 200 (OK) responses for the same cache key, the 688 cache needs to identify which of the stored responses are updated by 689 this new response and then update the stored response(s) with the new 690 information provided in the 304 response. 692 The stored response to update is identified by using the first match 693 (if any) of: 695 o If the new response contains a strong validator (see Section 2.1 696 of [Part4]), then that strong validator identifies the selected 697 representation for update. All of the stored responses with the 698 same strong validator are selected. If none of the stored 699 responses contain the same strong validator, then the cache MUST 700 NOT use the new response to update any stored responses. 702 o If the new response contains a weak validator and that validator 703 corresponds to one of the cache's stored responses, then the most 704 recent of those matching stored responses is selected for update. 706 o If the new response does not include any form of validator (such 707 as in the case where a client generates an If-Modified-Since 708 request from a source other than the Last-Modified response header 709 field), and there is only one stored response, and that stored 710 response also lacks a validator, then that stored response is 711 selected for update. 713 If a stored response is selected for update, the cache MUST: 715 o delete any Warning header fields in the stored response with warn- 716 code 1xx (see Section 7.5); 718 o retain any Warning header fields in the stored response with warn- 719 code 2xx; and, 721 o use other header fields provided in the 304 (Not Modified) 722 response to replace all instances of the corresponding header 723 fields in the stored response. 725 4.3. Calculating Secondary Keys with Vary 727 When a cache receives a request that can be satisfied by a stored 728 response that has a Vary header field (Section 7.1.4 of [Part2]), it 729 MUST NOT use that response unless all of the selecting header fields 730 nominated by the Vary header field match in both the original request 731 (i.e., that associated with the stored response), and the presented 732 request. 734 The selecting header fields from two requests are defined to match if 735 and only if those in the first request can be transformed to those in 736 the second request by applying any of the following: 738 o adding or removing whitespace, where allowed in the header field's 739 syntax 741 o combining multiple header fields with the same field name (see 742 Section 3.2 of [Part1]) 744 o normalizing both header field values in a way that is known to 745 have identical semantics, according to the header field's 746 specification (e.g., re-ordering field values when order is not 747 significant; case-normalization, where values are defined to be 748 case-insensitive) 750 If (after any normalization that might take place) a header field is 751 absent from a request, it can only match another request if it is 752 also absent there. 754 A Vary header field-value of "*" always fails to match. 756 The stored response with matching selecting header fields is known as 757 the selected response. 759 If multiple selected responses are available (potentially including 760 responses without a Vary header field), the cache will need to choose 761 one to use. When a selecting header field has a known mechanism for 762 doing so (e.g., qvalues on Accept and similar request header fields), 763 that mechanism MAY be used to select preferred responses; of the 764 remainder, the most recent response (as determined by the Date header 765 field) is used, as per Section 4. 767 If no selected response is available, the cache cannot satisfy the 768 presented request. Typically, it is forwarded to the origin server 769 in a (possibly conditional; see Section 4.2) request. 771 5. Updating Caches with HEAD Responses 773 A response to the HEAD method is identical to what an equivalent 774 request made with a GET would have been, except it lacks a body. 775 This property of HEAD responses is used to both invalidate and update 776 cached GET responses. 778 If one or more stored GET responses can be selected (as per 779 Section 4.3) for a HEAD request, and the Content-Length, ETag or 780 Last-Modified value of a HEAD response differs from that in a 781 selected GET response, the cache MUST consider that selected response 782 to be stale. 784 If the Content-Length, ETag and Last-Modified values of a HEAD 785 response (when present) are the same as that in a selected GET 786 response (as per Section 4.3), the cache SHOULD update the remaining 787 header fields in the stored response using the following rules: 789 o delete any Warning header fields in the stored response with warn- 790 code 1xx (see Section 7.5); 792 o retain any Warning header fields in the stored response with warn- 793 code 2xx; and, 795 o use other header fields provided in the response to replace all 796 instances of the corresponding header fields in the stored 797 response. 799 6. Request Methods that Invalidate 801 Because unsafe request methods (Section 4.2.1 of [Part2]) such as 802 PUT, POST or DELETE have the potential for changing state on the 803 origin server, intervening caches can use them to keep their contents 804 up-to-date. 806 A cache MUST invalidate the effective Request URI (Section 5.5 of 807 [Part1]) as well as the URI(s) in the Location and Content-Location 808 response header fields (if present) when a non-error response to a 809 request with an unsafe method is received. 811 However, a cache MUST NOT invalidate a URI from a Location or 812 Content-Location response header field if the host part of that URI 813 differs from the host part in the effective request URI (Section 5.5 814 of [Part1]). This helps prevent denial of service attacks. 816 A cache MUST invalidate the effective request URI (Section 5.5 of 817 [Part1]) when it receives a non-error response to a request with a 818 method whose safety is unknown. 820 Here, a "non-error response" is one with a 2xx (Successful) or 3xx 821 (Redirection) status code. "Invalidate" means that the cache will 822 either remove all stored responses related to the effective request 823 URI, or will mark these as "invalid" and in need of a mandatory 824 validation before they can be sent in response to a subsequent 825 request. 827 Note that this does not guarantee that all appropriate responses are 828 invalidated. For example, a state-changing request might invalidate 829 responses in the caches it travels through, but relevant responses 830 still might be stored in other caches that it has not. 832 7. Header Field Definitions 834 This section defines the syntax and semantics of HTTP/1.1 header 835 fields related to caching. 837 7.1. Age 839 The "Age" header field conveys the sender's estimate of the amount of 840 time since the response was generated or successfully validated at 841 the origin server. Age values are calculated as specified in 842 Section 4.1.3. 844 Age = delta-seconds 846 Age field-values are non-negative integers, representing time in 847 seconds (see Section 1.2.1). 849 The presence of an Age header field in a response implies that a 850 response is not first-hand. However, the converse is not true, since 851 HTTP/1.0 caches might not implement the Age header field. 853 7.2. Cache-Control 855 The "Cache-Control" header field is used to specify directives for 856 caches along the request/response chain. Such cache directives are 857 unidirectional in that the presence of a directive in a request does 858 not imply that the same directive is to be given in the response. 860 A cache MUST obey the requirements of the Cache-Control directives 861 defined in this section. See Section 7.2.3 for information about how 862 Cache-Control directives defined elsewhere are handled. 864 Note: Some HTTP/1.0 caches might not implement Cache-Control. 866 A proxy, whether or not it implements a cache, MUST pass cache 867 directives through in forwarded messages, regardless of their 868 significance to that application, since the directives might be 869 applicable to all recipients along the request/response chain. It is 870 not possible to target a directive to a specific cache. 872 Cache directives are identified by a token, to be compared case- 873 insensitively, and have an optional argument, that can use both token 874 and quoted-string syntax. For the directives defined below that 875 define arguments, recipients ought to accept both forms, even if one 876 is documented to be preferred. For any directive not defined by this 877 specification, recipients MUST accept both forms. 879 Cache-Control = 1#cache-directive 881 cache-directive = token [ "=" ( token / quoted-string ) ] 883 For the cache directives defined below, no argument is defined (nor 884 allowed) unless stated otherwise. 886 7.2.1. Request Cache-Control Directives 888 7.2.1.1. max-age 890 Argument syntax: 892 delta-seconds (see Section 1.2.1) 894 The "max-age" request directive indicates that the client is 895 unwilling to accept a response whose age is greater than the 896 specified number of seconds. Unless the max-stale request directive 897 is also present, the client is not willing to accept a stale 898 response. 900 Note: This directive uses the token form of the argument syntax; 901 e.g., 'max-age=5', not 'max-age="5"'. Senders SHOULD NOT use the 902 quoted-string form. 904 7.2.1.2. max-stale 906 Argument syntax: 908 delta-seconds (see Section 1.2.1) 910 The "max-stale" request directive indicates that the client is 911 willing to accept a response that has exceeded its freshness 912 lifetime. If max-stale is assigned a value, then the client is 913 willing to accept a response that has exceeded its freshness lifetime 914 by no more than the specified number of seconds. If no value is 915 assigned to max-stale, then the client is willing to accept a stale 916 response of any age. 918 Note: This directive uses the token form of the argument syntax; 919 e.g., 'max-stale=10', not 'max-stale="10"'. Senders SHOULD NOT use 920 the quoted-string form. 922 7.2.1.3. min-fresh 924 Argument syntax: 926 delta-seconds (see Section 1.2.1) 928 The "min-fresh" request directive indicates that the client is 929 willing to accept a response whose freshness lifetime is no less than 930 its current age plus the specified time in seconds. That is, the 931 client wants a response that will still be fresh for at least the 932 specified number of seconds. 934 Note: This directive uses the token form of the argument syntax; 935 e.g., 'min-fresh=20', not 'min-fresh="20"'. Senders SHOULD NOT use 936 the quoted-string form. 938 7.2.1.4. no-cache 940 The "no-cache" request directive indicates that a cache MUST NOT use 941 a stored response to satisfy the request without successful 942 validation on the origin server. 944 7.2.1.5. no-store 946 The "no-store" request directive indicates that a cache MUST NOT 947 store any part of either this request or any response to it. This 948 directive applies to both private and shared caches. "MUST NOT 949 store" in this context means that the cache MUST NOT intentionally 950 store the information in non-volatile storage, and MUST make a best- 951 effort attempt to remove the information from volatile storage as 952 promptly as possible after forwarding it. 954 This directive is NOT a reliable or sufficient mechanism for ensuring 955 privacy. In particular, malicious or compromised caches might not 956 recognize or obey this directive, and communications networks might 957 be vulnerable to eavesdropping. 959 Note that if a request containing this directive is satisfied from a 960 cache, the no-store request directive does not apply to the already 961 stored response. 963 7.2.1.6. no-transform 965 The "no-transform" request directive indicates that an intermediary 966 (whether or not it implements a cache) MUST NOT transform the 967 payload, as defined in Section 5.7.2 of [Part1]. 969 7.2.1.7. only-if-cached 971 The "only-if-cached" request directive indicates that the client only 972 wishes to obtain a stored response. If it receives this directive, a 973 cache SHOULD either respond using a stored response that is 974 consistent with the other constraints of the request, or respond with 975 a 504 (Gateway Timeout) status code. If a group of caches is being 976 operated as a unified system with good internal connectivity, a 977 member cache MAY forward such a request within that group of caches. 979 7.2.2. Response Cache-Control Directives 981 7.2.2.1. must-revalidate 983 The "must-revalidate" response directive indicates that once it has 984 become stale, a cache MUST NOT use the response to satisfy subsequent 985 requests without successful validation on the origin server. 987 The must-revalidate directive is necessary to support reliable 988 operation for certain protocol features. In all circumstances a 989 cache MUST obey the must-revalidate directive; in particular, if a 990 cache cannot reach the origin server for any reason, it MUST generate 991 a 504 (Gateway Timeout) response. 993 The must-revalidate directive ought to be used by servers if and only 994 if failure to validate a request on the representation could result 995 in incorrect operation, such as a silently unexecuted financial 996 transaction. 998 7.2.2.2. no-cache 1000 Argument syntax: 1002 #field-name 1004 The "no-cache" response directive indicates that the response MUST 1005 NOT be used to satisfy a subsequent request without successful 1006 validation on the origin server. This allows an origin server to 1007 prevent a cache from using it to satisfy a request without contacting 1008 it, even by caches that have been configured to send stale responses. 1010 If the no-cache response directive specifies one or more field-names, 1011 then a cache MAY use the response to satisfy a subsequent request, 1012 subject to any other restrictions on caching. However, any header 1013 fields in the response that have the field-name(s) listed MUST NOT be 1014 sent in the response to a subsequent request without successful 1015 revalidation with the origin server. This allows an origin server to 1016 prevent the re-use of certain header fields in a response, while 1017 still allowing caching of the rest of the response. 1019 The field-names given are not limited to the set of header fields 1020 defined by this specification. Field names are case-insensitive. 1022 Note: Although it has been back-ported to many implementations, some 1023 HTTP/1.0 caches will not recognize or obey this directive. Also, no- 1024 cache response directives with field-names are often handled by 1025 caches as if an unqualified no-cache directive was received; i.e., 1026 the special handling for the qualified form is not widely 1027 implemented. 1029 Note: This directive uses the quoted-string form of the argument 1030 syntax. Senders SHOULD NOT use the token form (even if quoting 1031 appears not to be needed for single-entry lists). 1033 7.2.2.3. no-store 1035 The "no-store" response directive indicates that a cache MUST NOT 1036 store any part of either the immediate request or response. This 1037 directive applies to both private and shared caches. "MUST NOT 1038 store" in this context means that the cache MUST NOT intentionally 1039 store the information in non-volatile storage, and MUST make a best- 1040 effort attempt to remove the information from volatile storage as 1041 promptly as possible after forwarding it. 1043 This directive is NOT a reliable or sufficient mechanism for ensuring 1044 privacy. In particular, malicious or compromised caches might not 1045 recognize or obey this directive, and communications networks might 1046 be vulnerable to eavesdropping. 1048 7.2.2.4. no-transform 1050 The "no-transform" response directive indicates that an intermediary 1051 (regardless of whether it implements a cache) MUST NOT transform the 1052 payload, as defined in Section 5.7.2 of [Part1]. 1054 7.2.2.5. public 1056 The "public" response directive indicates that any cache MAY store 1057 the response, even if the response would normally be non-cacheable or 1058 cacheable only within a non-shared cache. (See Section 3.2 for 1059 additional details related to the use of public in response to a 1060 request containing Authorization, and Section 3 for details of how 1061 public affects responses that would normally not be stored, due to 1062 their status codes not being defined as cacheable.) 1064 7.2.2.6. private 1066 Argument syntax: 1068 #field-name 1070 The "private" response directive indicates that the response message 1071 is intended for a single user and MUST NOT be stored by a shared 1072 cache. A private cache MAY store the response and reuse it for later 1073 requests, even if the response would normally be non-cacheable. 1075 If the private response directive specifies one or more field-names, 1076 this requirement is limited to the field-values associated with the 1077 listed response header fields. That is, a shared cache MUST NOT 1078 store the specified field-names(s), whereas it MAY store the 1079 remainder of the response message. 1081 The field-names given are not limited to the set of header fields 1082 defined by this specification. Field names are case-insensitive. 1084 Note: This usage of the word "private" only controls where the 1085 response can be stored; it cannot ensure the privacy of the message 1086 content. Also, private response directives with field-names are 1087 often handled by caches as if an unqualified private directive was 1088 received; i.e., the special handling for the qualified form is not 1089 widely implemented. 1091 Note: This directive uses the quoted-string form of the argument 1092 syntax. Senders SHOULD NOT use the token form (even if quoting 1093 appears not to be needed for single-entry lists). 1095 7.2.2.7. proxy-revalidate 1097 The "proxy-revalidate" response directive has the same meaning as the 1098 must-revalidate response directive, except that it does not apply to 1099 private caches. 1101 7.2.2.8. max-age 1103 Argument syntax: 1105 delta-seconds (see Section 1.2.1) 1107 The "max-age" response directive indicates that the response is to be 1108 considered stale after its age is greater than the specified number 1109 of seconds. 1111 Note: This directive uses the token form of the argument syntax; 1112 e.g., 'max-age=5', not 'max-age="5"'. Senders SHOULD NOT use the 1113 quoted-string form. 1115 7.2.2.9. s-maxage 1117 Argument syntax: 1119 delta-seconds (see Section 1.2.1) 1121 The "s-maxage" response directive indicates that, in shared caches, 1122 the maximum age specified by this directive overrides the maximum age 1123 specified by either the max-age directive or the Expires header 1124 field. The s-maxage directive also implies the semantics of the 1125 proxy-revalidate response directive. 1127 Note: This directive uses the token form of the argument syntax; 1128 e.g., 's-maxage=10', not 's-maxage="10"'. Senders SHOULD NOT use the 1129 quoted-string form. 1131 7.2.3. Cache Control Extensions 1133 The Cache-Control header field can be extended through the use of one 1134 or more cache-extension tokens, each with an optional value. 1136 Informational extensions (those that do not require a change in cache 1137 behavior) can be added without changing the semantics of other 1138 directives. Behavioral extensions are designed to work by acting as 1139 modifiers to the existing base of cache directives. 1141 Both the new directive and the standard directive are supplied, such 1142 that applications that do not understand the new directive will 1143 default to the behavior specified by the standard directive, and 1144 those that understand the new directive will recognize it as 1145 modifying the requirements associated with the standard directive. 1146 In this way, extensions to the cache-control directives can be made 1147 without requiring changes to the base protocol. 1149 This extension mechanism depends on an HTTP cache obeying all of the 1150 cache-control directives defined for its native HTTP-version, obeying 1151 certain extensions, and ignoring all directives that it does not 1152 understand. 1154 For example, consider a hypothetical new response directive called 1155 "community" that acts as a modifier to the private directive. We 1156 define this new directive to mean that, in addition to any private 1157 cache, any cache that is shared only by members of the community 1158 named within its value is allowed to cache the response. An origin 1159 server wishing to allow the UCI community to use an otherwise private 1160 response in their shared cache(s) could do so by including 1162 Cache-Control: private, community="UCI" 1164 A cache seeing this header field will act correctly even if the cache 1165 does not understand the community cache-extension, since it will also 1166 see and understand the private directive and thus default to the safe 1167 behavior. 1169 A cache MUST ignore unrecognized cache directives; it is assumed that 1170 any cache directive likely to be unrecognized by an HTTP/1.1 cache 1171 will be combined with standard directives (or the response's default 1172 cacheability) such that the cache behavior will remain minimally 1173 correct even if the cache does not understand the extension(s). 1175 7.3. Expires 1177 The "Expires" header field gives the date/time after which the 1178 response is considered stale. See Section 4.1 for further discussion 1179 of the freshness model. 1181 The presence of an Expires field does not imply that the original 1182 resource will change or cease to exist at, before, or after that 1183 time. 1185 The Expires value is an HTTP-date timestamp, as defined in Section 1186 7.1.1.1 of [Part2]. 1188 Expires = HTTP-date 1190 For example 1192 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1194 A cache recipient MUST interpret invalid date formats, especially the 1195 value "0", as representing a time in the past (i.e., "already 1196 expired"). 1198 If a response includes a Cache-Control field with the max-age 1199 directive (Section 7.2.2.8), a recipient MUST ignore the Expires 1200 field. Likewise, if a response includes the s-maxage directive 1201 (Section 7.2.2.9), a shared cache recipient MUST ignore the Expires 1202 field. In both these cases, the value in Expires is only intended 1203 for recipients that have not yet implemented the Cache-Control field. 1205 An origin server without a clock MUST NOT generate an Expires field 1206 unless its value represents a fixed time in the past (always expired) 1207 or its value has been associated with the resource by a system or 1208 user with a reliable clock. 1210 Historically, HTTP required the Expires field-value to be no more 1211 than a year in the future. While longer freshness lifetimes are no 1212 longer prohibited, extremely large values have been demonstrated to 1213 cause problems (e.g., clock overflows due to use of 32-bit integers 1214 for time values), and many caches will evict a response far sooner 1215 than that. 1217 7.4. Pragma 1219 The "Pragma" header field allows backwards compatibility with 1220 HTTP/1.0 caches, so that clients can specify a "no-cache" request 1221 that they will understand (as Cache-Control was not defined until 1222 HTTP/1.1). When the Cache-Control header field is also present and 1223 understood in a request, Pragma is ignored. 1225 In HTTP/1.0, Pragma was defined as an extensible field for 1226 implementation-specified directives for recipients. This 1227 specification deprecates such extensions to improve interoperability. 1229 Pragma = 1#pragma-directive 1230 pragma-directive = "no-cache" / extension-pragma 1231 extension-pragma = token [ "=" ( token / quoted-string ) ] 1233 When the Cache-Control header field is not present in a request, 1234 caches MUST consider the no-cache request pragma-directive as having 1235 the same effect as if "Cache-Control: no-cache" were present (see 1236 Section 7.2.1). 1238 When sending a no-cache request, a client ought to include both the 1239 pragma and cache-control directives, unless Cache-Control: no-cache 1240 is purposefully omitted to target other Cache-Control response 1241 directives at HTTP/1.1 caches. For example: 1243 GET / HTTP/1.1 1244 Host: www.example.com 1245 Cache-Control: max-age=30 1246 Pragma: no-cache 1248 will constrain HTTP/1.1 caches to serve a response no older than 30 1249 seconds, while precluding implementations that do not understand 1250 Cache-Control from serving a cached response. 1252 Note: Because the meaning of "Pragma: no-cache" in responses is 1253 not specified, it does not provide a reliable replacement for 1254 "Cache-Control: no-cache" in them. 1256 7.5. Warning 1258 The "Warning" header field is used to carry additional information 1259 about the status or transformation of a message that might not be 1260 reflected in the message. This information is typically used to warn 1261 about possible incorrectness introduced by caching operations or 1262 transformations applied to the payload of the message. 1264 Warnings can be used for other purposes, both cache-related and 1265 otherwise. The use of a warning, rather than an error status code, 1266 distinguishes these responses from true failures. 1268 Warning header fields can in general be applied to any message, 1269 however some warn-codes are specific to caches and can only be 1270 applied to response messages. 1272 Warning = 1#warning-value 1274 warning-value = warn-code SP warn-agent SP warn-text 1275 [SP warn-date] 1277 warn-code = 3DIGIT 1278 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1279 ; the name or pseudonym of the server adding 1280 ; the Warning header field, for use in debugging 1281 warn-text = quoted-string 1282 warn-date = DQUOTE HTTP-date DQUOTE 1284 Multiple warnings can be attached to a response (either by the origin 1285 server or by a cache), including multiple warnings with the same code 1286 number, only differing in warn-text. 1288 When this occurs, the user agent SHOULD inform the user of as many of 1289 them as possible, in the order that they appear in the response. 1291 Systems that generate multiple Warning header fields are encouraged 1292 to order them with this user agent behavior in mind. New Warning 1293 header fields are added after any existing Warning header fields. 1295 Warnings are assigned three digit warn-codes. The first digit 1296 indicates whether the Warning is required to be deleted from a stored 1297 response after validation: 1299 o 1xx Warnings describe the freshness or validation status of the 1300 response, and so MUST be deleted by a cache after validation. 1301 They can only be generated by a cache when validating a cached 1302 entry, and MUST NOT be generated in any other situation. 1304 o 2xx Warnings describe some aspect of the representation that is 1305 not rectified by a validation (for example, a lossy compression of 1306 the representation) and MUST NOT be deleted by a cache after 1307 validation, unless a full response is sent, in which case they 1308 MUST be. 1310 If an implementation sends a message with one or more Warning header 1311 fields to a receiver whose version is HTTP/1.0 or lower, then the 1312 sender MUST include in each warning-value a warn-date that matches 1313 the Date header field in the message. 1315 If a system receives a message with a warning-value that includes a 1316 warn-date, and that warn-date is different from the Date value in the 1317 response, then that warning-value MUST be deleted from the message 1318 before storing, forwarding, or using it. (preventing the consequences 1319 of naive caching of Warning header fields.) If all of the warning- 1320 values are deleted for this reason, the Warning header field MUST be 1321 deleted as well. 1323 The following warn-codes are defined by this specification, each with 1324 a recommended warn-text in English, and a description of its meaning. 1326 7.5.1. 110 Response is Stale 1328 A cache SHOULD generate this whenever the sent response is stale. 1330 7.5.2. 111 Revalidation Failed 1332 A cache SHOULD generate this when sending a stale response because an 1333 attempt to validate the response failed, due to an inability to reach 1334 the server. 1336 7.5.3. 112 Disconnected Operation 1338 A cache SHOULD generate this if it is intentionally disconnected from 1339 the rest of the network for a period of time. 1341 7.5.4. 113 Heuristic Expiration 1343 A cache SHOULD generate this if it heuristically chose a freshness 1344 lifetime greater than 24 hours and the response's age is greater than 1345 24 hours. 1347 7.5.5. 199 Miscellaneous Warning 1349 The warning text can include arbitrary information to be presented to 1350 a human user, or logged. A system receiving this warning MUST NOT 1351 take any automated action, besides presenting the warning to the 1352 user. 1354 7.5.6. 214 Transformation Applied 1356 MUST be added by a proxy if it applies any transformation to the 1357 representation, such as changing the content-coding, media-type, or 1358 modifying the representation data, unless this Warning code already 1359 appears in the response. 1361 7.5.7. 299 Miscellaneous Persistent Warning 1363 The warning text can include arbitrary information to be presented to 1364 a human user, or logged. A system receiving this warning MUST NOT 1365 take any automated action. 1367 7.5.8. Warn Code Extensions 1369 Extension warn codes can be defined; see Section 9.2.1 for details. 1371 8. History Lists 1373 User agents often have history mechanisms, such as "Back" buttons and 1374 history lists, that can be used to redisplay a representation 1375 retrieved earlier in a session. 1377 The freshness model (Section 4.1) does not necessarily apply to 1378 history mechanisms. I.e., a history mechanism can display a previous 1379 representation even if it has expired. 1381 This does not prohibit the history mechanism from telling the user 1382 that a view might be stale, or from honoring cache directives (e.g., 1383 Cache-Control: no-store). 1385 9. IANA Considerations 1386 9.1. Cache Directive Registry 1388 The HTTP Cache Directive Registry defines the name space for the 1389 cache directives. It will be created and maintained at 1390 . 1392 9.1.1. Procedure 1394 A registration MUST include the following fields: 1396 o Cache Directive Name 1398 o Pointer to specification text 1400 Values to be added to this name space require IETF Review (see 1401 [RFC5226], Section 4.1). 1403 9.1.2. Considerations for New Cache Control Directives 1405 New extension directives ought to consider defining: 1407 o What it means for a directive to be specified multiple times, 1409 o When the directive does not take an argument, what it means when 1410 an argument is present, 1412 o When the directive requires an argument, what it means when it is 1413 missing, 1415 o Whether the directive is specific to requests, responses, or able 1416 to be used in either. 1418 See also Section 7.2.3. 1420 9.1.3. Registrations 1422 The HTTP Cache Directive Registry shall be populated with the 1423 registrations below: 1425 +------------------------+----------------------------------+ 1426 | Cache Directive | Reference | 1427 +------------------------+----------------------------------+ 1428 | max-age | Section 7.2.1.1, Section 7.2.2.8 | 1429 | max-stale | Section 7.2.1.2 | 1430 | min-fresh | Section 7.2.1.3 | 1431 | must-revalidate | Section 7.2.2.1 | 1432 | no-cache | Section 7.2.1.4, Section 7.2.2.2 | 1433 | no-store | Section 7.2.1.5, Section 7.2.2.3 | 1434 | no-transform | Section 7.2.1.6, Section 7.2.2.4 | 1435 | only-if-cached | Section 7.2.1.7 | 1436 | private | Section 7.2.2.6 | 1437 | proxy-revalidate | Section 7.2.2.7 | 1438 | public | Section 7.2.2.5 | 1439 | s-maxage | Section 7.2.2.9 | 1440 | stale-if-error | [RFC5861], Section 4 | 1441 | stale-while-revalidate | [RFC5861], Section 3 | 1442 +------------------------+----------------------------------+ 1444 9.2. Warn Code Registry 1446 The HTTP Warn Code Registry defines the name space for warn codes. 1447 It will be created and maintained at 1448 . 1450 9.2.1. Procedure 1452 A registration MUST include the following fields: 1454 o Warn Code (3 digits) 1456 o Short Description 1458 o Pointer to specification text 1460 Values to be added to this name space require IETF Review (see 1461 [RFC5226], Section 4.1). 1463 9.2.2. Registrations 1465 The HTTP Warn Code Registry shall be populated with the registrations 1466 below: 1468 +-----------+----------------------------------+---------------+ 1469 | Warn Code | Short Description | Reference | 1470 +-----------+----------------------------------+---------------+ 1471 | 110 | Response is Stale | Section 7.5.1 | 1472 | 111 | Revalidation Failed | Section 7.5.2 | 1473 | 112 | Disconnected Operation | Section 7.5.3 | 1474 | 113 | Heuristic Expiration | Section 7.5.4 | 1475 | 199 | Miscellaneous Warning | Section 7.5.5 | 1476 | 214 | Transformation Applied | Section 7.5.6 | 1477 | 299 | Miscellaneous Persistent Warning | Section 7.5.7 | 1478 +-----------+----------------------------------+---------------+ 1480 9.3. Header Field Registration 1482 HTTP header fields are registered within the Message Header Field 1483 Registry maintained at . 1486 This document defines the following HTTP header fields, so their 1487 associated registry entries shall be updated according to the 1488 permanent registrations below (see [BCP90]): 1490 +-------------------+----------+----------+-------------+ 1491 | Header Field Name | Protocol | Status | Reference | 1492 +-------------------+----------+----------+-------------+ 1493 | Age | http | standard | Section 7.1 | 1494 | Cache-Control | http | standard | Section 7.2 | 1495 | Expires | http | standard | Section 7.3 | 1496 | Pragma | http | standard | Section 7.4 | 1497 | Warning | http | standard | Section 7.5 | 1498 +-------------------+----------+----------+-------------+ 1500 The change controller is: "IETF (iesg@ietf.org) - Internet 1501 Engineering Task Force". 1503 10. Security Considerations 1505 This section is meant to inform developers, information providers, 1506 and users of known security concerns specific to HTTP/1.1 caching. 1507 More general security considerations are addressed in HTTP messaging 1508 [Part1] and semantics [Part2]. 1510 Caches expose additional potential vulnerabilities, since the 1511 contents of the cache represent an attractive target for malicious 1512 exploitation. Because cache contents persist after an HTTP request 1513 is complete, an attack on the cache can reveal information long after 1514 a user believes that the information has been removed from the 1515 network. Therefore, cache contents need to be protected as sensitive 1516 information. 1518 Furthermore, the very use of a cache can bring about privacy 1519 concerns. For example, if two users share a cache, and the first one 1520 browses to a site, the second may be able to detect that the other 1521 has been to that site, because the resources from it load more 1522 quickly, thanks to the cache. 1524 Implementation flaws might allow attackers to insert content into a 1525 cache ("cache poisoning"), leading to compromise of clients that 1526 trust that content. Because of their nature, these attacks are 1527 difficult to mitigate. 1529 Likewise, implementation flaws (as well as misunderstanding of cache 1530 operation) might lead to caching of sensitive information (e.g., 1531 authentication credentials) that is thought to be private, exposing 1532 it to unauthorized parties. 1534 Note that the Set-Cookie response header field [RFC6265] does not 1535 inhibit caching; a cacheable response with a Set-Cookie header field 1536 can be (and often is) used to satisfy subsequent requests to caches. 1537 Servers who wish to control caching of these responses are encouraged 1538 to emit appropriate Cache-Control response header fields. 1540 11. Acknowledgments 1542 See Section 9 of [Part1]. 1544 12. References 1546 12.1. Normative References 1548 [Part1] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1549 Protocol (HTTP/1.1): Message Syntax and Routing", 1550 draft-ietf-httpbis-p1-messaging-23 (work in progress), 1551 July 2013. 1553 [Part2] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1554 Protocol (HTTP/1.1): Semantics and Content", 1555 draft-ietf-httpbis-p2-semantics-23 (work in progress), 1556 July 2013. 1558 [Part4] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1559 Protocol (HTTP/1.1): Conditional Requests", 1560 draft-ietf-httpbis-p4-conditional-23 (work in progress), 1561 July 2013. 1563 [Part5] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 1564 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 1565 draft-ietf-httpbis-p5-range-23 (work in progress), 1566 July 2013. 1568 [Part7] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1569 Protocol (HTTP/1.1): Authentication", 1570 draft-ietf-httpbis-p7-auth-23 (work in progress), 1571 July 2013. 1573 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1574 Requirement Levels", BCP 14, RFC 2119, March 1997. 1576 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1577 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1579 12.2. Informative References 1581 [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1582 Procedures for Message Header Fields", BCP 90, RFC 3864, 1583 September 2004. 1585 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1586 Specification, Implementation", RFC 1305, March 1992. 1588 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1589 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1590 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1592 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1593 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1594 May 2008. 1596 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1597 Content", RFC 5861, April 2010. 1599 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1600 April 2011. 1602 Appendix A. Changes from RFC 2616 1604 Caching-related text has been substantially rewritten for clarity. 1606 The algorithm for calculating age is now less conservative. 1607 (Section 4.1.3) 1609 Caches are now required to handle dates with timezones as if they're 1610 invalid, because it's not possible to accurately guess. 1611 (Section 4.1.3) 1612 The Content-Location response header field is no longer used to 1613 determine the appropriate response to use when validating. 1614 (Section 4.2) 1616 The algorithm for selecting a cached negotiated response to use has 1617 been clarified in several ways. In particular, it now explicitly 1618 allows header-specific canonicalization when processing selecting 1619 header fields. (Section 4.3) 1621 Requirements regarding denial of service attack avoidance when 1622 performing invalidation have been clarified. (Section 6) 1624 Cache invalidation only occurs when a successful response is 1625 received. (Section 6) 1627 The conditions under which an authenticated response can be cached 1628 have been clarified. (Section 3.2) 1630 The one-year limit on Expires header field values has been removed; 1631 instead, the reasoning for using a sensible value is given. 1632 (Section 7.3) 1634 The Pragma header field is now only defined for backwards 1635 compatibility; future pragmas are deprecated. (Section 7.4) 1637 Cache directives are explicitly defined to be case-insensitive. 1638 (Section 7.2) 1640 Handling of multiple instances of cache directives when only one is 1641 expected is now defined. (Section 7.2) 1643 The qualified forms of the private and no-cache cache directives are 1644 noted to not be widely implemented; e.g., "private=foo" is 1645 interpreted by many caches as simply "private". Additionally, the 1646 meaning of the qualified form of no-cache has been clarified. 1647 (Section 7.2.2) 1649 The "no-store" cache request directive doesn't apply to responses; 1650 i.e., a cache can satisfy a request with no-store on it, and does not 1651 invalidate it. (Section 7.2.1.5) 1653 The "no-cache" response cache directive's meaning has been clarified. 1654 (Section 7.2.2.2) 1656 New status codes can now define that caches are allowed to use 1657 heuristic freshness with them. (Section 4.1.2) 1659 Caches are now allow to calculate heuristic freshness for URLs with 1660 query components. (Section 4.1.2) 1662 Some requirements regarding production of the Warning header fields 1663 have been relaxed, as it is not widely implemented. Furthermore, the 1664 Warning header field no longer uses RFC 2047 encoding, nor allows 1665 multiple languages, as these aspects were not implemented. 1666 (Section 7.5) 1668 This specification introduces the Cache Directive and Warn Code 1669 Registries, and defines considerations for new cache directives. 1670 (Section 7.2.3 and Section 7.5.8) 1672 Appendix B. Imported ABNF 1674 The following core rules are included by reference, as defined in 1675 Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), 1676 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 1677 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 1678 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII 1679 character). 1681 The rules below are defined in [Part1]: 1683 OWS = 1684 field-name = 1685 quoted-string = 1686 token = 1688 port = 1689 pseudonym = 1690 uri-host = 1692 The rules below are defined in other parts: 1694 HTTP-date = 1696 Appendix C. Collected ABNF 1698 In the collected ABNF below, list rules are expanded as per Section 1699 1.2 of [Part1]. 1701 Age = delta-seconds 1703 Cache-Control = *( "," OWS ) cache-directive *( OWS "," [ OWS 1704 cache-directive ] ) 1706 Expires = HTTP-date 1708 HTTP-date = 1710 OWS = 1712 Pragma = *( "," OWS ) pragma-directive *( OWS "," [ OWS 1713 pragma-directive ] ) 1715 Warning = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value ] 1716 ) 1718 cache-directive = token [ "=" ( token / quoted-string ) ] 1720 delta-seconds = 1*DIGIT 1722 extension-pragma = token [ "=" ( token / quoted-string ) ] 1724 field-name = 1726 port = 1727 pragma-directive = "no-cache" / extension-pragma 1728 pseudonym = 1730 quoted-string = 1732 token = 1734 uri-host = 1736 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1737 warn-code = 3DIGIT 1738 warn-date = DQUOTE HTTP-date DQUOTE 1739 warn-text = quoted-string 1740 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date 1741 ] 1743 Appendix D. Change Log (to be removed by RFC Editor before publication) 1745 Changes up to the first Working Group Last Call draft are summarized 1746 in . 1749 D.1. Since draft-ietf-httpbis-p6-cache-19 1751 Closed issues: 1753 o : "untangle 1754 Cache-Control ABNF" 1756 o : "Multiple 1757 values in Cache-Control header fields" 1759 o : "Case 1760 sensitivity of header fields in CC values" 1762 o : "Spurious 1763 'MAYs'" 1765 o : "enhance 1766 considerations for new cache control directives" 1768 o : "ABNF 1769 requirements for recipients" 1771 o : "note 1772 introduction of new IANA registries as normative changes" 1774 o : "broken prose 1775 in description of 'Vary'" 1777 D.2. Since draft-ietf-httpbis-p6-cache-20 1779 Closed issues: 1781 o : "'Most 1782 Conservative'" 1784 Other changes: 1786 o Conformance criteria and considerations regarding error handling 1787 are now defined in Part 1. 1789 o Move definition of "Vary" header field into Part 2. 1791 o Add security considerations with respect to cache poisoning and 1792 the "Set-Cookie" header field. 1794 D.3. Since draft-ietf-httpbis-p6-cache-21 1796 Closed issues: 1798 o : "Allowing 1799 heuristic caching for new status codes" 1801 o : "304 without 1802 validator" 1804 o : "No-Transform" 1806 o : "Revert prior 1807 change to the meaning of the public cache response directive. 1809 D.4. Since draft-ietf-httpbis-p6-cache-22 1811 Closed issues: 1813 o : "explain list 1814 expansion in ABNF appendices" 1816 o : "Returning the 1817 freshest response" 1819 o : "placement of 1820 extension point considerations" 1822 o : "Editorial 1823 notes for p6" 1825 o : "Vary and 1826 future requests" 1828 Index 1830 1 1831 110 Response is Stale (warn code) 28 1832 111 Revalidation Failed (warn code) 28 1833 112 Disconnected Operation (warn code) 28 1834 113 Heuristic Expiration (warn code) 29 1835 199 Miscellaneous Warning (warn code) 29 1837 2 1838 214 Transformation Applied (warn code) 29 1839 299 Miscellaneous Persistent Warning (warn code) 29 1841 A 1842 age 9 1843 Age header field 18 1845 C 1846 cache 4 1847 cache entry 5 1848 cache key 5 1849 Cache-Control header field 18 1851 E 1852 Expires header field 25 1853 explicit expiration time 9 1855 F 1856 first-hand 14 1857 fresh 9 1858 freshness lifetime 9 1860 G 1861 Grammar 1862 Age 18 1863 Cache-Control 19 1864 cache-directive 19 1865 delta-seconds 5 1866 Expires 25 1867 extension-pragma 26 1868 Pragma 26 1869 pragma-directive 26 1870 warn-agent 27 1871 warn-code 27 1872 warn-date 27 1873 warn-text 27 1874 Warning 27 1875 warning-value 27 1877 H 1878 heuristic expiration time 9 1880 M 1881 max-age (cache directive) 19, 24 1882 max-stale (cache directive) 19 1883 min-fresh (cache directive) 20 1884 must-revalidate (cache directive) 21 1886 N 1887 no-cache (cache directive) 20-21 1888 no-store (cache directive) 20, 22 1889 no-transform (cache directive) 21-22 1891 O 1892 only-if-cached (cache directive) 21 1894 P 1895 Pragma header field 26 1896 private (cache directive) 23 1897 private cache 4 1898 proxy-revalidate (cache directive) 23 1899 public (cache directive) 23 1901 S 1902 s-maxage (cache directive) 24 1903 shared cache 4 1904 stale 9 1905 strong validator 15 1907 V 1908 validator 14 1910 W 1911 Warning header field 27 1913 Authors' Addresses 1915 Roy T. Fielding (editor) 1916 Adobe Systems Incorporated 1917 345 Park Ave 1918 San Jose, CA 95110 1919 USA 1921 EMail: fielding@gbiv.com 1922 URI: http://roy.gbiv.com/ 1924 Mark Nottingham (editor) 1925 Akamai 1927 EMail: mnot@mnot.net 1928 URI: http://www.mnot.net/ 1929 Julian F. Reschke (editor) 1930 greenbytes GmbH 1931 Hafenweg 16 1932 Muenster, NW 48155 1933 Germany 1935 EMail: julian.reschke@greenbytes.de 1936 URI: http://greenbytes.de/tech/webdav/