idnits 2.17.1 draft-ietf-httpbis-p6-cache-13.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 : ---------------------------------------------------------------------------- No issues found here. 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 (March 14, 2011) is 4785 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-13 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-13 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-13 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-13 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-13 -- 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 (==), 5 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) J. Gettys 5 Intended status: Standards Track Alcatel-Lucent 6 Expires: September 15, 2011 J. Mogul 7 HP 8 H. Frystyk 9 Microsoft 10 L. Masinter 11 Adobe 12 P. Leach 13 Microsoft 14 T. Berners-Lee 15 W3C/MIT 16 Y. Lafon, Ed. 17 W3C 18 M. Nottingham, Ed. 20 J. Reschke, Ed. 21 greenbytes 22 March 14, 2011 24 HTTP/1.1, part 6: Caching 25 draft-ietf-httpbis-p6-cache-13 27 Abstract 29 The Hypertext Transfer Protocol (HTTP) is an application-level 30 protocol for distributed, collaborative, hypermedia information 31 systems. This document is Part 6 of the seven-part specification 32 that defines the protocol referred to as "HTTP/1.1" and, taken 33 together, obsoletes RFC 2616. Part 6 defines requirements on HTTP 34 caches and the associated header fields that control cache behavior 35 or indicate cacheable response messages. 37 Editorial Note (To be removed by RFC Editor) 39 Discussion of this draft should take place on the HTTPBIS working 40 group mailing list (ietf-http-wg@w3.org). The current issues list is 41 at and related 42 documents (including fancy diffs) can be found at 43 . 45 The changes in this draft are summarized in Appendix C.14. 47 Status of This Memo 48 This Internet-Draft is submitted in full conformance with the 49 provisions of BCP 78 and BCP 79. 51 Internet-Drafts are working documents of the Internet Engineering 52 Task Force (IETF). Note that other groups may also distribute 53 working documents as Internet-Drafts. The list of current Internet- 54 Drafts is at http://datatracker.ietf.org/drafts/current/. 56 Internet-Drafts are draft documents valid for a maximum of six months 57 and may be updated, replaced, or obsoleted by other documents at any 58 time. It is inappropriate to use Internet-Drafts as reference 59 material or to cite them other than as "work in progress." 61 This Internet-Draft will expire on September 15, 2011. 63 Copyright Notice 65 Copyright (c) 2011 IETF Trust and the persons identified as the 66 document authors. All rights reserved. 68 This document is subject to BCP 78 and the IETF Trust's Legal 69 Provisions Relating to IETF Documents 70 (http://trustee.ietf.org/license-info) in effect on the date of 71 publication of this document. Please review these documents 72 carefully, as they describe your rights and restrictions with respect 73 to this document. Code Components extracted from this document must 74 include Simplified BSD License text as described in Section 4.e of 75 the Trust Legal Provisions and are provided without warranty as 76 described in the Simplified BSD License. 78 This document may contain material from IETF Documents or IETF 79 Contributions published or made publicly available before November 80 10, 2008. The person(s) controlling the copyright in some of this 81 material may not have granted the IETF Trust the right to allow 82 modifications of such material outside the IETF Standards Process. 83 Without obtaining an adequate license from the person(s) controlling 84 the copyright in such materials, this document may not be modified 85 outside the IETF Standards Process, and derivative works of it may 86 not be created outside the IETF Standards Process, except to format 87 it for publication as an RFC or to translate it into languages other 88 than English. 90 Table of Contents 92 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 93 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 94 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 95 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 7 96 1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 97 1.4.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 7 98 1.4.2. ABNF Rules defined in other Parts of the 99 Specification . . . . . . . . . . . . . . . . . . . . 7 100 2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 8 101 2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 8 102 2.1.1. Storing Partial and Incomplete Responses . . . . . . . 9 103 2.2. Constructing Responses from Caches . . . . . . . . . . . . 9 104 2.3. Freshness Model . . . . . . . . . . . . . . . . . . . . . 10 105 2.3.1. Calculating Freshness Lifetime . . . . . . . . . . . . 11 106 2.3.2. Calculating Age . . . . . . . . . . . . . . . . . . . 12 107 2.3.3. Serving Stale Responses . . . . . . . . . . . . . . . 13 108 2.4. Validation Model . . . . . . . . . . . . . . . . . . . . . 14 109 2.5. Request Methods that Invalidate . . . . . . . . . . . . . 15 110 2.6. Shared Caching of Authenticated Responses . . . . . . . . 15 111 2.7. Caching Negotiated Responses . . . . . . . . . . . . . . . 16 112 2.8. Combining Responses . . . . . . . . . . . . . . . . . . . 17 113 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 17 114 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 115 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 18 116 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 19 117 3.2.2. Response Cache-Control Directives . . . . . . . . . . 21 118 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 23 119 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 24 120 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 25 121 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 122 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 26 123 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 29 124 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 125 5.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 29 126 5.2. Header Field Registration . . . . . . . . . . . . . . . . 30 127 6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 128 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 31 129 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 130 8.1. Normative References . . . . . . . . . . . . . . . . . . . 31 131 8.2. Informative References . . . . . . . . . . . . . . . . . . 32 132 Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 32 133 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 32 134 Appendix C. Change Log (to be removed by RFC Editor before 135 publication) . . . . . . . . . . . . . . . . . . . . 34 136 C.1. Since RFC 2616 . . . . . . . . . . . . . . . . . . . . . . 34 137 C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 34 138 C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 35 139 C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 35 140 C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 35 141 C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 35 142 C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 36 143 C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 36 144 C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 36 145 C.10. Since draft-ietf-httpbis-p6-cache-08 . . . . . . . . . . . 37 146 C.11. Since draft-ietf-httpbis-p6-cache-09 . . . . . . . . . . . 37 147 C.12. Since draft-ietf-httpbis-p6-cache-10 . . . . . . . . . . . 38 148 C.13. Since draft-ietf-httpbis-p6-cache-11 . . . . . . . . . . . 38 149 C.14. Since draft-ietf-httpbis-p6-cache-12 . . . . . . . . . . . 38 150 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 152 1. Introduction 154 HTTP is typically used for distributed information systems, where 155 performance can be improved by the use of response caches. This 156 document defines aspects of HTTP/1.1 related to caching and reusing 157 response messages. 159 1.1. Purpose 161 An HTTP cache is a local store of response messages and the subsystem 162 that controls its message storage, retrieval, and deletion. A cache 163 stores cacheable responses in order to reduce the response time and 164 network bandwidth consumption on future, equivalent requests. Any 165 client or server MAY employ a cache, though a cache cannot be used by 166 a server that is acting as a tunnel. 168 Caching would be useless if it did not significantly improve 169 performance. The goal of caching in HTTP/1.1 is to reuse a prior 170 response message to satisfy a current request. In some cases, a 171 stored response can be reused without the need for a network request, 172 reducing latency and network round-trips; a "freshness" mechanism is 173 used for this purpose (see Section 2.3). Even when a new request is 174 required, it is often possible to reuse all or parts of the payload 175 of a prior response to satisfy the request, thereby reducing network 176 bandwidth usage; a "validation" mechanism is used for this purpose 177 (see Section 2.4). 179 1.2. Terminology 181 This specification uses a number of terms to refer to the roles 182 played by participants in, and objects of, HTTP caching. 184 cache 186 A conformant implementation of a HTTP cache. Note that this 187 implies an HTTP/1.1 cache; this specification does not define 188 conformance for HTTP/1.0 caches. 190 shared cache 192 A cache that is accessible to more than one user; usually (but not 193 always) deployed as part of an intermediary. 195 private cache 197 A cache that is dedicated to a single user. 199 cacheable 201 A response is cacheable if a cache is allowed to store a copy of 202 the response message for use in answering subsequent requests. 203 Even when a response is cacheable, there might be additional 204 constraints on whether a cache can use the stored copy to satisfy 205 a particular request. 207 explicit expiration time 209 The time at which the origin server intends that a representation 210 no longer be returned by a cache without further validation. 212 heuristic expiration time 214 An expiration time assigned by a cache when no explicit expiration 215 time is available. 217 age 219 The age of a response is the time since it was sent by, or 220 successfully validated with, the origin server. 222 first-hand 224 A response is first-hand if the freshness model is not in use; 225 i.e., its age is 0. 227 freshness lifetime 229 The length of time between the generation of a response and its 230 expiration time. 232 fresh 234 A response is fresh if its age has not yet exceeded its freshness 235 lifetime. 237 stale 239 A response is stale if its age has passed its freshness lifetime 240 (either explicit or heuristic). 242 validator 244 A protocol element (e.g., an entity-tag or a Last-Modified time) 245 that is used to find out whether a stored response is an 246 equivalent copy of a representation. 248 1.3. Requirements 250 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 251 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 252 document are to be interpreted as described in [RFC2119]. 254 An implementation is not compliant if it fails to satisfy one or more 255 of the "MUST" or "REQUIRED" level requirements for the protocols it 256 implements. An implementation that satisfies all the "MUST" or 257 "REQUIRED" level and all the "SHOULD" level requirements for its 258 protocols is said to be "unconditionally compliant"; one that 259 satisfies all the "MUST" level requirements but not all the "SHOULD" 260 level requirements for its protocols is said to be "conditionally 261 compliant". 263 1.4. Syntax Notation 265 This specification uses the ABNF syntax defined in Section 1.2 of 266 [Part1] (which extends the syntax defined in [RFC5234] with a list 267 rule). Appendix B shows the collected ABNF, with the list rule 268 expanded. 270 The following core rules are included by reference, as defined in 271 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 272 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 273 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 274 sequence of data), SP (space), VCHAR (any visible USASCII character), 275 and WSP (whitespace). 277 1.4.1. Core Rules 279 The core rules below are defined in Section 1.2.2 of [Part1]: 281 quoted-string = 282 token = 283 OWS = 285 1.4.2. ABNF Rules defined in other Parts of the Specification 287 The ABNF rules below are defined in other parts: 289 field-name = 290 HTTP-date = 291 port = 292 pseudonym = 293 uri-host = 295 2. Cache Operation 297 2.1. Response Cacheability 299 A cache MUST NOT store a response to any request, unless: 301 o The request method is understood by the cache and defined as being 302 cacheable, and 304 o the response status code is understood by the cache, and 306 o the "no-store" cache directive (see Section 3.2) does not appear 307 in request or response header fields, and 309 o the "private" cache response directive (see Section 3.2.2 does not 310 appear in the response, if the cache is shared, and 312 o the "Authorization" header field (see Section 4.1 of [Part7]) does 313 not appear in the request, if the cache is shared, unless the 314 response explicitly allows it (see Section 2.6), and 316 o the response either: 318 * contains an Expires header field (see Section 3.3), or 320 * contains a max-age response cache directive (see 321 Section 3.2.2), or 323 * contains a s-maxage response cache directive and the cache is 324 shared, or 326 * contains a Cache Control Extension (see Section 3.2.3) that 327 allows it to be cached, or 329 * has a status code that can be served with heuristic freshness 330 (see Section 2.3.1.1). 332 In this context, a cache has "understood" a request method or a 333 response status code if it recognises it and implements any cache- 334 specific behaviour. In particular, 206 Partial Content responses 335 cannot be cached by an implementation that does not handle partial 336 content (see Section 2.1.1). 338 Note that in normal operation, most caches will not store a response 339 that has neither a cache validator nor an explicit expiration time, 340 as such responses are not usually useful to store. However, caches 341 are not prohibited from storing such responses. 343 2.1.1. Storing Partial and Incomplete Responses 345 A cache that receives an incomplete response (for example, with fewer 346 bytes of data than specified in a Content-Length header field) can 347 store the response, but MUST treat it as a partial response [Part5]. 348 Partial responses can be combined as described in Section 4 of 349 [Part5]; the result might be a full response or might still be 350 partial. A cache MUST NOT return a partial response to a client 351 without explicitly marking it as such using the 206 (Partial Content) 352 status code. 354 A cache that does not support the Range and Content-Range header 355 fields MUST NOT store incomplete or partial responses. 357 2.2. Constructing Responses from Caches 359 For a presented request, a cache MUST NOT return a stored response, 360 unless: 362 o The presented effective request URI (Section 4.3 of [Part1]) and 363 that of the stored response match, and 365 o the request method associated with the stored response allows it 366 to be used for the presented request, and 368 o selecting header fields nominated by the stored response (if any) 369 match those presented (see Section 2.7), and 371 o the presented request and stored response are free from directives 372 that would prevent its use (see Section 3.2 and Section 3.4), and 374 o the stored response is either: 376 * fresh (see Section 2.3), or 378 * allowed to be served stale (see Section 2.3.3), or 380 * successfully validated (see Section 2.4). 382 When a stored response is used to satisfy a request without 383 validation, a cache MUST include a single Age header field 384 (Section 3.1) in the response with a value equal to the stored 385 response's current_age; see Section 2.3.2. 387 A cache MUST write through requests with methods that are unsafe 388 (Section 7.1.1 of [Part2]) to the origin server; i.e., a cache must 389 not generate a reply to such a request before having forwarded the 390 request and having received a corresponding response. 392 Also, note that unsafe requests might invalidate already stored 393 responses; see Section 2.5. 395 A cache MUST use the most recent response (as determined by the Date 396 header field) when more than one suitable response is stored. It can 397 also forward a request with "Cache-Control: max-age=0" or "Cache- 398 Control: no-cache" to disambiguate which response to use. 400 A cache that does not have a clock available MUST NOT used stored 401 responses without revalidating them on every use. A cache, 402 especially a shared cache, SHOULD use a mechanism, such as NTP 403 [RFC1305], to synchronize its clock with a reliable external 404 standard. 406 2.3. Freshness Model 408 When a response is "fresh" in the cache, it can be used to satisfy 409 subsequent requests without contacting the origin server, thereby 410 improving efficiency. 412 The primary mechanism for determining freshness is for an origin 413 server to provide an explicit expiration time in the future, using 414 either the Expires header field (Section 3.3) or the max-age response 415 cache directive (Section 3.2.2). Generally, origin servers will 416 assign future explicit expiration times to responses in the belief 417 that the representation is not likely to change in a semantically 418 significant way before the expiration time is reached. 420 If an origin server wishes to force a cache to validate every 421 request, it can assign an explicit expiration time in the past to 422 indicate that the response is already stale. Compliant caches will 423 normally validate the cached response before reusing it for 424 subsequent requests (see Section 2.3.3). 426 Since origin servers do not always provide explicit expiration times, 427 a cache MAY assign a heuristic expiration time when an explicit time 428 is not specified, employing algorithms that use other header field 429 values (such as the Last-Modified time) to estimate a plausible 430 expiration time. This specification does not provide specific 431 algorithms, but does impose worst-case constraints on their results. 433 The calculation to determine if a response is fresh is: 435 response_is_fresh = (freshness_lifetime > current_age) 437 The freshness_lifetime is defined in Section 2.3.1; the current_age 438 is defined in Section 2.3.2. 440 Additionally, clients might need to influence freshness calculation. 441 They can do this using several request cache directives, with the 442 effect of either increasing or loosening constraints on freshness. 443 See Section 3.2.1. 445 [[ISSUE-no-req-for-directives: there are not requirements directly 446 applying to cache-request-directives and freshness.]] 448 Note that freshness applies only to cache operation; it cannot be 449 used to force a user agent to refresh its display or reload a 450 resource. See Section 4 for an explanation of the difference between 451 caches and history mechanisms. 453 2.3.1. Calculating Freshness Lifetime 455 A cache can calculate the freshness lifetime (denoted as 456 freshness_lifetime) of a response by using the first match of: 458 o If the cache is shared and the s-maxage response cache directive 459 (Section 3.2.2) is present, use its value, or 461 o If the max-age response cache directive (Section 3.2.2) is 462 present, use its value, or 464 o If the Expires response header field (Section 3.3) is present, use 465 its value minus the value of the Date response header field, or 467 o Otherwise, no explicit expiration time is present in the response. 468 A heuristic freshness lifetime might be applicable; see 469 Section 2.3.1.1. 471 Note that this calculation is not vulnerable to clock skew, since all 472 of the information comes from the origin server. 474 2.3.1.1. Calculating Heuristic Freshness 476 If no explicit expiration time is present in a stored response that 477 has a status code whose definition allows heuristic freshness to be 478 used (including the following in Section 8 of [Part2]: 200, 203, 206, 479 300, 301 and 410), a cache MAY calculate a heuristic expiration time. 480 A cache MUST NOT use heuristics to determine freshness for responses 481 with status codes that do not explicitly allow it. 483 When a heuristic is used to calculate freshness lifetime, a cache 484 SHOULD attach a Warning header field with a 113 warn-code to the 485 response if its current_age is more than 24 hours and such a warning 486 is not already present. 488 Also, if the response has a Last-Modified header field (Section 6.6 489 of [Part4]), a cache SHOULD NOT use a heuristic expiration value that 490 is more than some fraction of the interval since that time. A 491 typical setting of this fraction might be 10%. 493 Note: RFC 2616 ([RFC2616], Section 13.9) required that caches do 494 not calculate heuristic freshness for URIs with query components 495 (i.e., those containing '?'). In practice, this has not been 496 widely implemented. Therefore, servers are encouraged to send 497 explicit directives (e.g., Cache-Control: no-cache) if they wish 498 to preclude caching. 500 2.3.2. Calculating Age 502 HTTP/1.1 uses the Age header field to convey the estimated age of the 503 response message when obtained from a cache. The Age field value is 504 the cache's estimate of the amount of time since the response was 505 generated or validated by the origin server. In essence, the Age 506 value is the sum of the time that the response has been resident in 507 each of the caches along the path from the origin server, plus the 508 amount of time it has been in transit along network paths. 510 The following data is used for the age calculation: 512 age_value 514 The term "age_value" denotes the value of the Age header field 515 (Section 3.1), in a form appropriate for arithmetic operation; or 516 0, if not available. 518 date_value 520 HTTP/1.1 requires origin servers to send a Date header field, if 521 possible, with every response, giving the time at which the 522 response was generated. The term "date_value" denotes the value 523 of the Date header field, in a form appropriate for arithmetic 524 operations. See Section 9.3 of [Part1] for the definition of the 525 Date header field, and for requirements regarding responses 526 without it. 528 now 530 The term "now" means "the current value of the clock at the host 531 performing the calculation". A cache SHOULD use NTP ([RFC1305]) 532 or some similar protocol to synchronize its clocks to a globally 533 accurate time standard. 535 request_time 537 The current value of the clock at the host at the time the request 538 resulting in the stored response was made. 540 response_time 542 The current value of the clock at the host at the time the 543 response was received. 545 A response's age can be calculated in two entirely independent ways: 547 1. the "apparent_age": response_time minus date_value, if the local 548 clock is reasonably well synchronized to the origin server's 549 clock. If the result is negative, the result is replaced by 550 zero. 552 2. the "corrected_age_value", if all of the caches along the 553 response path implement HTTP/1.1. A cache MUST interpret this 554 value relative to the time the request was initiated, not the 555 time that the response was received. 557 apparent_age = max(0, response_time - date_value); 559 response_delay = response_time - request_time; 560 corrected_age_value = age_value + response_delay; 562 These are combined as 564 corrected_initial_age = max(apparent_age, corrected_age_value); 566 The current_age of a stored response can then be calculated by adding 567 the amount of time (in seconds) since the stored response was last 568 validated by the origin server to the corrected_initial_age. 570 resident_time = now - response_time; 571 current_age = corrected_initial_age + resident_time; 573 2.3.3. Serving Stale Responses 575 A "stale" response is one that either has explicit expiry information 576 or is allowed to have heuristic expiry calculated, but is not fresh 577 according to the calculations in Section 2.3. 579 A cache MUST NOT return a stale response if it is prohibited by an 580 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" 581 cache directive, a "must-revalidate" cache-response-directive, or an 582 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 583 see Section 3.2.2). 585 A cache SHOULD NOT return stale responses unless it is disconnected 586 (i.e., it cannot contact the origin server or otherwise find a 587 forward path) or otherwise explicitly allowed (e.g., the max-stale 588 request directive; see Section 3.2.1). 590 A cache SHOULD append a Warning header field with the 110 warn-code 591 (see Section 3.6) to stale responses. Likewise, a cache SHOULD add 592 the 112 warn-code to stale responses if the cache is disconnected. 594 If a cache receives a first-hand response (either an entire response, 595 or a 304 (Not Modified) response) that it would normally forward to 596 the requesting client, and the received response is no longer fresh, 597 the cache SHOULD forward it to the requesting client without adding a 598 new Warning (but without removing any existing Warning header 599 fields). A cache SHOULD NOT attempt to validate a response simply 600 because that response became stale in transit. 602 2.4. Validation Model 604 When a cache has one or more stored responses for a requested URI, 605 but cannot serve any of them (e.g., because they are not fresh, or 606 one cannot be selected; see Section 2.7), it can use the conditional 607 request mechanism [Part4] in the forwarded request to give the origin 608 server an opportunity to both select a valid stored response to be 609 used, and to update it. This process is known as "validating" or 610 "revalidating" the stored response. 612 When sending such a conditional request, a cache SHOULD add an If- 613 Modified-Since header field whose value is that of the Last-Modified 614 header field from the selected (see Section 2.7) stored response, if 615 available. 617 Additionally, a cache SHOULD add an If-None-Match header field whose 618 value is that of the ETag header field(s) from all responses stored 619 for the requested URI, if present. However, if any of the stored 620 responses contains only partial content, the cache SHOULD NOT include 621 its entity-tag in the If-None-Match header field unless the request 622 is for a range that would be fully satisfied by that stored response. 624 A 304 (Not Modified) response status code indicates that the stored 625 response can be updated and reused; see Section 2.8. 627 A full response (i.e., one with a response body) indicates that none 628 of the stored responses nominated in the conditional request is 629 suitable. Instead, a cache SHOULD use the full response to satisfy 630 the request and MAY replace the stored response. 632 If a cache receives a 5xx response while attempting to validate a 633 response, it MAY either forward this response to the requesting 634 client, or act as if the server failed to respond. In the latter 635 case, it MAY return a previously stored response (see Section 2.3.3). 637 2.5. Request Methods that Invalidate 639 Because unsafe request methods (Section 7.1.1 of [Part2]) have the 640 potential for changing state on the origin server, intervening caches 641 can use them to keep their contents up-to-date. 643 A cache MUST invalidate the effective Request URI (Section 4.3 of 644 [Part1]) as well as the URI(s) in the Location and Content-Location 645 header fields (if present) when the following request methods are 646 received: 648 o PUT 650 o DELETE 652 o POST 654 However, a cache MUST NOT invalidate a URI from a Location or 655 Content-Location header field if the host part of that URI differs 656 from the host part in the effective request URI (Section 4.3 of 657 [Part1]). This helps prevent denial of service attacks. 659 A cache that passes through requests with methods it does not 660 understand SHOULD invalidate the effective request URI (Section 4.3 661 of [Part1]). 663 Here, "invalidate" means that the cache will either remove all stored 664 responses related to the effective request URI, or will mark these as 665 "invalid" and in need of a mandatory validation before they can be 666 returned in response to a subsequent request. 668 Note that this does not guarantee that all appropriate responses are 669 invalidated. For example, the request that caused the change at the 670 origin server might not have gone through the cache where a response 671 is stored. 673 2.6. Shared Caching of Authenticated Responses 675 A shared cache MUST NOT use a cached response to a request with an 676 Authorization header field (Section 4.1 of [Part7]) to satisfy any 677 subsequent request unless a cache directive that allows such 678 responses to be stored is present in the response. 680 In this specification, the following Cache-Control response 681 directives (Section 3.2.2) have such an effect: must-revalidate, 682 public, s-maxage. 684 Note that cached responses that contain the "must-revalidate" and/or 685 "s-maxage" response directives are not allowed to be served stale 686 (Section 2.3.3) by shared caches. In particular, a response with 687 either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to 688 satisfy a subsequent request without revalidating it on the origin 689 server. 691 2.7. Caching Negotiated Responses 693 When a cache receives a request that can be satisfied by a stored 694 response that has a Vary header field (Section 3.5), it MUST NOT use 695 that response unless all of the selecting header fields nominated by 696 the Vary header field match in both the original request (i.e., that 697 associated with the stored response), and the presented request. 699 The selecting header fields from two requests are defined to match if 700 and only if those in the first request can be transformed to those in 701 the second request by applying any of the following: 703 o adding or removing whitespace, where allowed in the header field's 704 syntax 706 o combining multiple header fields with the same field name (see 707 Section 3.2 of [Part1]) 709 o normalizing both header field values in a way that is known to 710 have identical semantics, according to the header field's 711 specification (e.g., re-ordering field values when order is not 712 significant; case-normalization, where values are defined to be 713 case-insensitive) 715 If (after any normalization that might take place) a header field is 716 absent from a request, it can only match another request if it is 717 also absent there. 719 A Vary header field-value of "*" always fails to match, and 720 subsequent requests to that resource can only be properly interpreted 721 by the origin server. 723 The stored response with matching selecting header fields is known as 724 the selected response. 726 If no selected response is available, the cache MAY forward the 727 presented request to the origin server in a conditional request; see 728 Section 2.4. 730 2.8. Combining Responses 732 When a cache receives a 304 (Not Modified) response or a 206 (Partial 733 Content) response (in this section, the "new" response"), it needs to 734 create an updated response by combining the stored response with the 735 new one, so that the updated response can be used to satisfy the 736 request, and potentially update the cached response. 738 If the new response contains an ETag, it identifies the stored 739 response to use. [[TODO-mention-CL: might need language about 740 Content-Location here]][[TODO-select-for-combine: Shouldn't this be 741 the selected response?]] 743 When the new response's status code is 206 (partial content), a cache 744 MUST NOT combine it with the old response if either response does not 745 have a validator, and MUST NOT combine it with the old response when 746 those validators do not match with the strong comparison function 747 (see Section 4 of [Part4]). 749 The stored response header fields are used as those of the updated 750 response, except that 752 o a cache MUST delete any stored Warning header fields with warn- 753 code 1xx (see Section 3.6). 755 o a cache MUST retain any stored Warning header fields with warn- 756 code 2xx. 758 o a cache MUST use other header fields provided in the new response 759 to replace all instances of the corresponding header fields from 760 the stored response. 762 A cache MUST use the updated response header fields to replace those 763 of the stored response (unless the stored response is removed). In 764 the case of a 206 response, a cache MAY store the combined 765 representation. 767 3. Header Field Definitions 769 This section defines the syntax and semantics of HTTP/1.1 header 770 fields related to caching. 772 3.1. Age 774 The "Age" header field conveys the sender's estimate of the amount of 775 time since the response was generated or successfully validated at 776 the origin server. Age values are calculated as specified in 777 Section 2.3.2. 779 Age = "Age" ":" OWS Age-v 780 Age-v = delta-seconds 782 Age field-values are non-negative integers, representing time in 783 seconds. 785 delta-seconds = 1*DIGIT 787 If a cache receives a value larger than the largest positive integer 788 it can represent, or if any of its age calculations overflows, it 789 MUST transmit an Age header field with a field-value of 2147483648 790 (2^31). Recipients parsing the Age header field-value SHOULD use an 791 arithmetic type of at least 31 bits of range. 793 The presence of an Age header field in a response implies that a 794 response is not first-hand. However, the converse is not true, since 795 HTTP/1.0 caches might not implement the Age header field. 797 3.2. Cache-Control 799 The "Cache-Control" header field is used to specify directives for 800 caches along the request/response chain. Such cache directives are 801 unidirectional in that the presence of a directive in a request does 802 not imply that the same directive is to be given in the response. 804 A cache MUST obey the requirements of the Cache-Control directives 805 defined in this section. See Section 3.2.3 for information about how 806 Cache-Control directives defined elsewhere are handled. 808 Note: HTTP/1.0 caches might not implement Cache-Control and might 809 only implement Pragma: no-cache (see Section 3.4). 811 A proxy, whether or not it implements a cache, MUST pass cache 812 directives through in forwarded messages, regardless of their 813 significance to that application, since the directives might be 814 applicable to all recipients along the request/response chain. It is 815 not possible to target a directive to a specific cache. 817 Cache-Control = "Cache-Control" ":" OWS Cache-Control-v 818 Cache-Control-v = 1#cache-directive 820 cache-directive = cache-request-directive 821 / cache-response-directive 823 cache-extension = token [ "=" ( token / quoted-string ) ] 825 3.2.1. Request Cache-Control Directives 827 cache-request-directive = 828 "no-cache" 829 / "no-store" 830 / "max-age" "=" delta-seconds 831 / "max-stale" [ "=" delta-seconds ] 832 / "min-fresh" "=" delta-seconds 833 / "no-transform" 834 / "only-if-cached" 835 / cache-extension 837 no-cache 839 The no-cache request directive indicates that a cache MUST NOT use 840 a stored response to satisfy the request without successful 841 validation on the origin server. 843 no-store 845 The no-store request directive indicates that a cache MUST NOT 846 store any part of either this request or any response to it. This 847 directive applies to both private and shared caches. "MUST NOT 848 store" in this context means that the cache MUST NOT intentionally 849 store the information in non-volatile storage, and MUST make a 850 best-effort attempt to remove the information from volatile 851 storage as promptly as possible after forwarding it. 853 This directive is NOT a reliable or sufficient mechanism for 854 ensuring privacy. In particular, malicious or compromised caches 855 might not recognize or obey this directive, and communications 856 networks might be vulnerable to eavesdropping. 858 Note that if a request containing this directive is satisfied from 859 a cache, the no-store request directive does not apply to the 860 already stored response. 862 max-age 864 The max-age request directive indicates that the client is willing 865 to accept a response whose age is no greater than the specified 866 time in seconds. Unless the max-stale request directive is also 867 present, the client is not willing to accept a stale response. 869 max-stale 871 The max-stale request directive indicates that the client is 872 willing to accept a response that has exceeded its expiration 873 time. If max-stale is assigned a value, then the client is 874 willing to accept a response that has exceeded its expiration time 875 by no more than the specified number of seconds. If no value is 876 assigned to max-stale, then the client is willing to accept a 877 stale response of any age. 879 min-fresh 881 The min-fresh request directive indicates that the client is 882 willing to accept a response whose freshness lifetime is no less 883 than its current age plus the specified time in seconds. That is, 884 the client wants a response that will still be fresh for at least 885 the specified number of seconds. 887 no-transform 889 The no-transform request directive indicates that an intermediary 890 (whether or not it implements a cache) MUST NOT change the 891 Content-Encoding, Content-Range or Content-Type request header 892 fields, nor the request representation. 894 only-if-cached 896 The only-if-cached request directive indicates that the client 897 only wishes to return a stored response. If it receives this 898 directive, a cache SHOULD either respond using a stored response 899 that is consistent with the other constraints of the request, or 900 respond with a 504 (Gateway Timeout) status code. If a group of 901 caches is being operated as a unified system with good internal 902 connectivity, a member cache MAY forward such a request within 903 that group of caches. 905 3.2.2. Response Cache-Control Directives 907 cache-response-directive = 908 "public" 909 / "private" [ "=" DQUOTE 1#field-name DQUOTE ] 910 / "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] 911 / "no-store" 912 / "no-transform" 913 / "must-revalidate" 914 / "proxy-revalidate" 915 / "max-age" "=" delta-seconds 916 / "s-maxage" "=" delta-seconds 917 / cache-extension 919 public 921 The public response directive indicates that a response whose 922 associated request contains an 'Authentication' header MAY be 923 stored (see Section 2.6). 925 private 927 The private response directive indicates that the response message 928 is intended for a single user and MUST NOT be stored by a shared 929 cache. A private cache MAY store the response. 931 If the private response directive specifies one or more field- 932 names, this requirement is limited to the field-values associated 933 with the listed response header fields. That is, a shared cache 934 MUST NOT store the specified field-names(s), whereas it MAY store 935 the remainder of the response message. 937 Note: This usage of the word private only controls where the 938 response can be stored; it cannot ensure the privacy of the 939 message content. Also, private response directives with field- 940 names are often handled by implementations as if an unqualified 941 private directive was received; i.e., the special handling for the 942 qualified form is not widely implemented. 944 no-cache 946 The no-cache response directive indicates that the response MUST 947 NOT be used to satisfy a subsequent request without successful 948 validation on the origin server. This allows an origin server to 949 prevent a cache from using it to satisfy a request without 950 contacting it, even by caches that have been configured to return 951 stale responses. 953 If the no-cache response directive specifies one or more field- 954 names, this requirement is limited to the field-values associated 955 with the listed response header fields. That is, a cache MUST NOT 956 send the specified field-name(s) in the response to a subsequent 957 request without successful validation on the origin server. This 958 allows an origin server to prevent the re-use of certain header 959 fields in a response, while still allowing caching of the rest of 960 the response. 962 Note: Most HTTP/1.0 caches will not recognize or obey this 963 directive. Also, no-cache response directives with field-names 964 are often handled by implementations as if an unqualified no-cache 965 directive was received; i.e., the special handling for the 966 qualified form is not widely implemented. 968 no-store 970 The no-store response directive indicates that a cache MUST NOT 971 store any part of either the immediate request or response. This 972 directive applies to both private and shared caches. "MUST NOT 973 store" in this context means that the cache MUST NOT intentionally 974 store the information in non-volatile storage, and MUST make a 975 best-effort attempt to remove the information from volatile 976 storage as promptly as possible after forwarding it. 978 This directive is NOT a reliable or sufficient mechanism for 979 ensuring privacy. In particular, malicious or compromised caches 980 might not recognize or obey this directive, and communications 981 networks might be vulnerable to eavesdropping. 983 must-revalidate 985 The must-revalidate response directive indicates that once it has 986 become stale, a cache MUST NOT use the response to satisfy 987 subsequent requests without successful validation on the origin 988 server. 990 The must-revalidate directive is necessary to support reliable 991 operation for certain protocol features. In all circumstances a 992 cache MUST obey the must-revalidate directive; in particular, if a 993 cache cannot reach the origin server for any reason, it MUST 994 generate a 504 (Gateway Timeout) response. 996 A server SHOULD send the must-revalidate directive if and only if 997 failure to validate a request on the representation could result 998 in incorrect operation, such as a silently unexecuted financial 999 transaction. 1001 proxy-revalidate 1003 The proxy-revalidate response directive has the same meaning as 1004 the must-revalidate response directive, except that it does not 1005 apply to private caches. 1007 max-age 1009 The max-age response directive indicates that response is to be 1010 considered stale after its age is greater than the specified 1011 number of seconds. 1013 s-maxage 1015 The s-maxage response directive indicates that, in shared caches, 1016 the maximum age specified by this directive overrides the maximum 1017 age specified by either the max-age directive or the Expires 1018 header field. The s-maxage directive also implies the semantics 1019 of the proxy-revalidate response directive. 1021 no-transform 1023 The no-transform response directive indicates that an intermediary 1024 (regardless of whether it implements a cache) MUST NOT change the 1025 Content-Encoding, Content-Range or Content-Type response header 1026 fields, nor the response representation. 1028 3.2.3. Cache Control Extensions 1030 The Cache-Control header field can be extended through the use of one 1031 or more cache-extension tokens, each with an optional value. 1032 Informational extensions (those that do not require a change in cache 1033 behavior) can be added without changing the semantics of other 1034 directives. Behavioral extensions are designed to work by acting as 1035 modifiers to the existing base of cache directives. Both the new 1036 directive and the standard directive are supplied, such that 1037 applications that do not understand the new directive will default to 1038 the behavior specified by the standard directive, and those that 1039 understand the new directive will recognize it as modifying the 1040 requirements associated with the standard directive. In this way, 1041 extensions to the cache-control directives can be made without 1042 requiring changes to the base protocol. 1044 This extension mechanism depends on an HTTP cache obeying all of the 1045 cache-control directives defined for its native HTTP-version, obeying 1046 certain extensions, and ignoring all directives that it does not 1047 understand. 1049 For example, consider a hypothetical new response directive called 1050 "community" that acts as a modifier to the private directive. We 1051 define this new directive to mean that, in addition to any private 1052 cache, any cache that is shared only by members of the community 1053 named within its value may cache the response. An origin server 1054 wishing to allow the UCI community to use an otherwise private 1055 response in their shared cache(s) could do so by including 1057 Cache-Control: private, community="UCI" 1059 A cache seeing this header field will act correctly even if the cache 1060 does not understand the community cache-extension, since it will also 1061 see and understand the private directive and thus default to the safe 1062 behavior. 1064 A cache MUST be ignore unrecognized cache directives; it is assumed 1065 that any cache directive likely to be unrecognized by an HTTP/1.1 1066 cache will be combined with standard directives (or the response's 1067 default cacheability) such that the cache behavior will remain 1068 minimally correct even if the cache does not understand the 1069 extension(s). 1071 The HTTP Cache Directive Registry defines the name space for the 1072 cache directives. 1074 A registration MUST include the following fields: 1076 o Cache Directive Name 1078 o Pointer to specification text 1080 Values to be added to this name space are subject to IETF review 1081 ([RFC5226], Section 4.1). 1083 The registry itself is maintained at 1084 . 1086 3.3. Expires 1088 The "Expires" header field gives the date/time after which the 1089 response is considered stale. See Section 2.3 for further discussion 1090 of the freshness model. 1092 The presence of an Expires field does not imply that the original 1093 resource will change or cease to exist at, before, or after that 1094 time. 1096 The field-value is an absolute date and time as defined by HTTP-date 1097 in Section 6.1 of [Part1]; a sender MUST use the rfc1123-date format. 1099 Expires = "Expires" ":" OWS Expires-v 1100 Expires-v = HTTP-date 1102 For example 1104 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1106 Note: If a response includes a Cache-Control field with the max- 1107 age directive (see Section 3.2.2), that directive overrides the 1108 Expires field. Likewise, the s-maxage directive overrides Expires 1109 in shared caches. 1111 A server SHOULD NOT send Expires dates more than one year in the 1112 future. 1114 A cache MUST treat other invalid date formats, especially including 1115 the value "0", as in the past (i.e., "already expired"). 1117 3.4. Pragma 1119 The "Pragma" header field is used to include implementation-specific 1120 directives that might apply to any recipient along the request/ 1121 response chain. All pragma directives specify optional behavior from 1122 the viewpoint of the protocol; however, some systems MAY require that 1123 behavior be consistent with the directives. 1125 Pragma = "Pragma" ":" OWS Pragma-v 1126 Pragma-v = 1#pragma-directive 1127 pragma-directive = "no-cache" / extension-pragma 1128 extension-pragma = token [ "=" ( token / quoted-string ) ] 1130 When the no-cache directive is present in a request message, a cache 1131 SHOULD forward the request toward the origin server even if it has a 1132 stored copy of what is being requested. This pragma directive has 1133 the same semantics as the no-cache response directive (see 1134 Section 3.2.2) and is defined here for backward compatibility with 1135 HTTP/1.0. A client SHOULD include both header fields when a no-cache 1136 request is sent to a server not known to be HTTP/1.1 compliant. A 1137 cache SHOULD treat "Pragma: no-cache" as if the client had sent 1138 "Cache-Control: no-cache". 1140 Note: Because the meaning of "Pragma: no-cache" as a header field 1141 is not actually specified, it does not provide a reliable 1142 replacement for "Cache-Control: no-cache" in a response. 1144 This mechanism is deprecated; no new Pragma directives will be 1145 defined in HTTP. 1147 3.5. Vary 1149 The "Vary" header field conveys the set of header fields that were 1150 used to select the representation. 1152 Caches use this information, in part, to determine whether a stored 1153 response can be used to satisfy a given request; see Section 2.7. 1154 determines, while the response is fresh, whether a cache is permitted 1155 to use the response to reply to a subsequent request without 1156 validation; see Section 2.7. 1158 In uncacheable or stale responses, the Vary field value advises the 1159 user agent about the criteria that were used to select the 1160 representation. 1162 Vary = "Vary" ":" OWS Vary-v 1163 Vary-v = "*" / 1#field-name 1165 The set of header fields named by the Vary field value is known as 1166 the selecting header fields. 1168 A server SHOULD include a Vary header field with any cacheable 1169 response that is subject to server-driven negotiation. Doing so 1170 allows a cache to properly interpret future requests on that resource 1171 and informs the user agent about the presence of negotiation on that 1172 resource. A server MAY include a Vary header field with a non- 1173 cacheable response that is subject to server-driven negotiation, 1174 since this might provide the user agent with useful information about 1175 the dimensions over which the response varies at the time of the 1176 response. 1178 A Vary field value of "*" signals that unspecified parameters not 1179 limited to the header fields (e.g., the network address of the 1180 client), play a role in the selection of the response representation; 1181 therefore, a cache cannot determine whether this response is 1182 appropriate. A proxy MUST NOT generate the "*" value. 1184 The field-names given are not limited to the set of standard header 1185 fields defined by this specification. Field names are case- 1186 insensitive. 1188 3.6. Warning 1190 The "Warning" header field is used to carry additional information 1191 about the status or transformation of a message that might not be 1192 reflected in the message. This information is typically used to warn 1193 about possible incorrectness introduced by caching operations or 1194 transformations applied to the payload of the message. 1196 Warnings can be used for other purposes, both cache-related and 1197 otherwise. The use of a warning, rather than an error status code, 1198 distinguishes these responses from true failures. 1200 Warning header fields can in general be applied to any message, 1201 however some warn-codes are specific to caches and can only be 1202 applied to response messages. 1204 Warning = "Warning" ":" OWS Warning-v 1205 Warning-v = 1#warning-value 1207 warning-value = warn-code SP warn-agent SP warn-text 1208 [SP warn-date] 1210 warn-code = 3DIGIT 1211 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1212 ; the name or pseudonym of the server adding 1213 ; the Warning header field, for use in debugging 1214 warn-text = quoted-string 1215 warn-date = DQUOTE HTTP-date DQUOTE 1217 Multiple warnings can be attached to a response (either by the origin 1218 server or by a cache), including multiple warnings with the same code 1219 number, only differing in warn-text. 1221 When this occurs, the user agent SHOULD inform the user of as many of 1222 them as possible, in the order that they appear in the response. 1224 Systems that generate multiple Warning header fields SHOULD order 1225 them with this user agent behavior in mind. New Warning header 1226 fields SHOULD be added after any existing Warning headers fields. 1228 Warnings are assigned three digit warn-codes. The first digit 1229 indicates whether the Warning is required to be deleted from a stored 1230 response after validation: 1232 o 1xx Warnings describe the freshness or validation status of the 1233 response, and so MUST be deleted by a cache after validation. 1234 They can only be generated by a cache when validating a cached 1235 entry, and MUST NOT be generated in any other situation. 1237 o 2xx Warnings describe some aspect of the representation that is 1238 not rectified by a validation (for example, a lossy compression of 1239 the representation) and MUST NOT be deleted by a cache after 1240 validation, unless a full response is returned, in which case they 1241 MUST be. 1243 If an implementation sends a message with one or more Warning header 1244 fields to a receiver whose version is HTTP/1.0 or lower, then the 1245 sender MUST include in each warning-value a warn-date that matches 1246 the Date header field in the message. 1248 If a system receives a message with a warning-value that includes a 1249 warn-date, and that warn-date is different from the Date value in the 1250 response, then that warning-value MUST be deleted from the message 1251 before storing, forwarding, or using it. (preventing the consequences 1252 of naive caching of Warning header fields.) If all of the warning- 1253 values are deleted for this reason, the Warning header field MUST be 1254 deleted as well. 1256 The following warn-codes are defined by this specification, each with 1257 a recommended warn-text in English, and a description of its meaning. 1259 110 Response is stale 1261 A cache SHOULD include this whenever the returned response is 1262 stale. 1264 111 Revalidation failed 1266 A cache SHOULD include this when returning a stale response 1267 because an attempt to validate the response failed, due to an 1268 inability to reach the server. 1270 112 Disconnected operation 1272 A cache SHOULD b include this if it is intentionally disconnected 1273 from the rest of the network for a period of time. 1275 113 Heuristic expiration 1277 A cache SHOULD include this if it heuristically chose a freshness 1278 lifetime greater than 24 hours and the response's age is greater 1279 than 24 hours. 1281 199 Miscellaneous warning 1283 The warning text can include arbitrary information to be presented 1284 to a human user, or logged. A system receiving this warning MUST 1285 NOT take any automated action, besides presenting the warning to 1286 the user. 1288 214 Transformation applied 1290 MUST be added by a proxy if it applies any transformation to the 1291 representation, such as changing the content-coding, media-type, 1292 or modifying the representation data, unless this Warning code 1293 already appears in the response. 1295 299 Miscellaneous persistent warning 1297 The warning text can include arbitrary information to be presented 1298 to a human user, or logged. A system receiving this warning MUST 1299 NOT take any automated action. 1301 4. History Lists 1303 User agents often have history mechanisms, such as "Back" buttons and 1304 history lists, that can be used to redisplay a representation 1305 retrieved earlier in a session. 1307 The freshness model (Section 2.3) does not necessarily apply to 1308 history mechanisms. I.e., a history mechanism can display a previous 1309 representation even if it has expired. 1311 This does not prohibit the history mechanism from telling the user 1312 that a view might be stale, or from honoring cache directives (e.g., 1313 Cache-Control: no-store). 1315 5. IANA Considerations 1317 5.1. Cache Directive Registry 1319 The registration procedure for HTTP Cache Directives is defined by 1320 Section 3.2.3 of this document. 1322 The HTTP Cache Directive Registry shall be created at 1323 and be 1324 populated with the registrations below: 1326 +------------------------+------------------------------+ 1327 | Cache Directive | Reference | 1328 +------------------------+------------------------------+ 1329 | max-age | Section 3.2.1, Section 3.2.2 | 1330 | max-stale | Section 3.2.1 | 1331 | min-fresh | Section 3.2.1 | 1332 | must-revalidate | Section 3.2.2 | 1333 | no-cache | Section 3.2.1, Section 3.2.2 | 1334 | no-store | Section 3.2.1, Section 3.2.2 | 1335 | no-transform | Section 3.2.1, Section 3.2.2 | 1336 | only-if-cached | Section 3.2.1 | 1337 | private | Section 3.2.2 | 1338 | proxy-revalidate | Section 3.2.2 | 1339 | public | Section 3.2.2 | 1340 | s-maxage | Section 3.2.2 | 1341 | stale-if-error | [RFC5861], Section 4 | 1342 | stale-while-revalidate | [RFC5861], Section 3 | 1343 +------------------------+------------------------------+ 1345 5.2. Header Field Registration 1347 The Message Header Field Registry located at shall be 1349 updated with the permanent registrations below (see [RFC3864]): 1351 +-------------------+----------+----------+-------------+ 1352 | Header Field Name | Protocol | Status | Reference | 1353 +-------------------+----------+----------+-------------+ 1354 | Age | http | standard | Section 3.1 | 1355 | Cache-Control | http | standard | Section 3.2 | 1356 | Expires | http | standard | Section 3.3 | 1357 | Pragma | http | standard | Section 3.4 | 1358 | Vary | http | standard | Section 3.5 | 1359 | Warning | http | standard | Section 3.6 | 1360 +-------------------+----------+----------+-------------+ 1362 The change controller is: "IETF (iesg@ietf.org) - Internet 1363 Engineering Task Force". 1365 6. Security Considerations 1367 Caches expose additional potential vulnerabilities, since the 1368 contents of the cache represent an attractive target for malicious 1369 exploitation. Because cache contents persist after an HTTP request 1370 is complete, an attack on the cache can reveal information long after 1371 a user believes that the information has been removed from the 1372 network. Therefore, cache contents need to be protected as sensitive 1373 information. 1375 7. Acknowledgments 1377 Much of the content and presentation of the caching design is due to 1378 suggestions and comments from individuals including: Shel Kaphan, 1379 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 1381 8. References 1383 8.1. Normative References 1385 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1386 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1387 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 1388 and Message Parsing", draft-ietf-httpbis-p1-messaging-13 1389 (work in progress), March 2011. 1391 [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1392 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1393 and J. Reschke, Ed., "HTTP/1.1, part 2: Message 1394 Semantics", draft-ietf-httpbis-p2-semantics-13 (work in 1395 progress), March 2011. 1397 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1398 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1399 and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional 1400 Requests", draft-ietf-httpbis-p4-conditional-13 (work in 1401 progress), March 2011. 1403 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1404 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1405 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 1406 Partial Responses", draft-ietf-httpbis-p5-range-13 (work 1407 in progress), March 2011. 1409 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1410 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1411 and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", 1412 draft-ietf-httpbis-p7-auth-13 (work in progress), 1413 March 2011. 1415 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1416 Requirement Levels", BCP 14, RFC 2119, March 1997. 1418 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1419 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1421 8.2. Informative References 1423 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1424 Specification, Implementation", RFC 1305, March 1992. 1426 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1427 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1428 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1430 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1431 Procedures for Message Header Fields", BCP 90, RFC 3864, 1432 September 2004. 1434 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1435 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1436 May 2008. 1438 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1439 Content", RFC 5861, April 2010. 1441 Appendix A. Changes from RFC 2616 1443 Make the specified age calculation algorithm less conservative. 1444 (Section 2.3.2) 1446 Remove requirement to consider Content-Location in successful 1447 responses in order to determine the appropriate response to use. 1448 (Section 2.4) 1450 Clarify denial of service attack avoidance requirement. 1451 (Section 2.5) 1453 Do not mention RFC 2047 encoding and multiple languages in Warning 1454 header fields anymore, as these aspects never were implemented. 1455 (Section 3.6) 1457 Appendix B. Collected ABNF 1459 Age = "Age:" OWS Age-v 1460 Age-v = delta-seconds 1462 Cache-Control = "Cache-Control:" OWS Cache-Control-v 1463 Cache-Control-v = *( "," OWS ) cache-directive *( OWS "," [ OWS 1464 cache-directive ] ) 1466 Expires = "Expires:" OWS Expires-v 1467 Expires-v = HTTP-date 1468 HTTP-date = 1470 OWS = 1472 Pragma = "Pragma:" OWS Pragma-v 1473 Pragma-v = *( "," OWS ) pragma-directive *( OWS "," [ OWS 1474 pragma-directive ] ) 1476 Vary = "Vary:" OWS Vary-v 1477 Vary-v = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name 1478 ] ) ) 1480 Warning = "Warning:" OWS Warning-v 1481 Warning-v = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value 1482 ] ) 1484 cache-directive = cache-request-directive / cache-response-directive 1485 cache-extension = token [ "=" ( token / quoted-string ) ] 1486 cache-request-directive = "no-cache" / "no-store" / ( "max-age=" 1487 delta-seconds ) / ( "max-stale" [ "=" delta-seconds ] ) / ( 1488 "min-fresh=" delta-seconds ) / "no-transform" / "only-if-cached" / 1489 cache-extension 1490 cache-response-directive = "public" / ( "private" [ "=" DQUOTE *( "," 1491 OWS ) field-name *( OWS "," [ OWS field-name ] ) DQUOTE ] ) / ( 1492 "no-cache" [ "=" DQUOTE *( "," OWS ) field-name *( OWS "," [ OWS 1493 field-name ] ) DQUOTE ] ) / "no-store" / "no-transform" / 1494 "must-revalidate" / "proxy-revalidate" / ( "max-age=" delta-seconds 1495 ) / ( "s-maxage=" delta-seconds ) / cache-extension 1497 delta-seconds = 1*DIGIT 1499 extension-pragma = token [ "=" ( token / quoted-string ) ] 1501 field-name = 1503 port = 1504 pragma-directive = "no-cache" / extension-pragma 1505 pseudonym = 1507 quoted-string = 1509 token = 1511 uri-host = 1513 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1514 warn-code = 3DIGIT 1515 warn-date = DQUOTE HTTP-date DQUOTE 1516 warn-text = quoted-string 1517 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date 1518 ] 1520 ABNF diagnostics: 1522 ; Age defined but not used 1523 ; Cache-Control defined but not used 1524 ; Expires defined but not used 1525 ; Pragma defined but not used 1526 ; Vary defined but not used 1527 ; Warning defined but not used 1529 Appendix C. Change Log (to be removed by RFC Editor before publication) 1531 C.1. Since RFC 2616 1533 Extracted relevant partitions from [RFC2616]. 1535 C.2. Since draft-ietf-httpbis-p6-cache-00 1537 Closed issues: 1539 o : "Trailer" 1540 () 1542 o : "Invalidation 1543 after Update or Delete" 1544 () 1546 o : "Normative and 1547 Informative references" 1549 o : "Date reference 1550 typo" 1552 o : "Connection 1553 header text" 1555 o : "Informative 1556 references" 1558 o : "ISO-8859-1 1559 Reference" 1561 o : "Normative up- 1562 to-date references" 1564 o : "typo in 1565 13.2.2" 1567 Other changes: 1569 o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress 1570 on ) 1572 C.3. Since draft-ietf-httpbis-p6-cache-01 1574 Closed issues: 1576 o : "rel_path not 1577 used" 1579 Other changes: 1581 o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work 1582 in progress on ) 1584 o Add explicit references to BNF syntax and rules imported from 1585 other parts of the specification. 1587 C.4. Since draft-ietf-httpbis-p6-cache-02 1589 Ongoing work on IANA Message Header Field Registration 1590 (): 1592 o Reference RFC 3984, and update header field registrations for 1593 header fields defined in this document. 1595 C.5. Since draft-ietf-httpbis-p6-cache-03 1597 Closed issues: 1599 o : "Vary header 1600 classification" 1602 C.6. Since draft-ietf-httpbis-p6-cache-04 1604 Ongoing work on ABNF conversion 1605 (): 1607 o Use "/" instead of "|" for alternatives. 1609 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1610 whitespace ("OWS") and required whitespace ("RWS"). 1612 o Rewrite ABNFs to spell out whitespace rules, factor out header 1613 field value format definitions. 1615 C.7. Since draft-ietf-httpbis-p6-cache-05 1617 This is a total rewrite of this part of the specification. 1619 Affected issues: 1621 o : "Definition of 1622 1xx Warn-Codes" 1624 o : "Placement of 1625 13.5.1 and 13.5.2" 1627 o : "The role of 1628 Warning and Semantic Transparency in Caching" 1630 o : "Methods and 1631 Caching" 1633 In addition: Final work on ABNF conversion 1634 (): 1636 o Add appendix containing collected and expanded ABNF, reorganize 1637 ABNF introduction. 1639 C.8. Since draft-ietf-httpbis-p6-cache-06 1641 Closed issues: 1643 o : "base for 1644 numeric protocol elements" 1646 Affected issues: 1648 o : "Vary and non- 1649 existant headers" 1651 C.9. Since draft-ietf-httpbis-p6-cache-07 1653 Closed issues: 1655 o : "Definition of 1656 1xx Warn-Codes" 1658 o : "Content- 1659 Location on 304 responses" 1661 o : "private and 1662 no-cache CC directives with headers" 1664 o : "RFC2047 and 1665 warn-text" 1667 C.10. Since draft-ietf-httpbis-p6-cache-08 1669 Closed issues: 1671 o : "serving 1672 negotiated responses from cache: header-specific canonicalization" 1674 o : "Effect of CC 1675 directives on history lists" 1677 Affected issues: 1679 o : Status codes 1680 and caching 1682 Partly resolved issues: 1684 o : "Placement of 1685 13.5.1 and 13.5.2" 1687 C.11. Since draft-ietf-httpbis-p6-cache-09 1689 Closed issues: 1691 o : "Age 1692 calculation" 1694 o : "Clarify 1695 differences between / requirements for request and response CC 1696 directives" 1698 o : "Caching 1699 authenticated responses" 1701 o : "IANA registry 1702 for cache-control directives" 1704 o : "Heuristic 1705 caching of URLs with query components" 1707 Partly resolved issues: 1709 o : "Term for the 1710 requested resource's URI" 1712 C.12. Since draft-ietf-httpbis-p6-cache-10 1714 Closed issues: 1716 o : "Clarify 1717 entity / representation / variant terminology" 1719 o : "consider 1720 removing the 'changes from 2068' sections" 1722 o : "Allowing 1723 heuristic caching for new status codes" 1725 o : "Allowing 1726 heuristic caching for new status codes" 1728 o Clean up TODOs and prose in "Combining Responses." 1730 C.13. Since draft-ietf-httpbis-p6-cache-11 1732 Closed issues: 1734 o : "Text about 1735 clock requirement for caches belongs in p6" 1737 C.14. Since draft-ietf-httpbis-p6-cache-12 1739 Closed issues: 1741 o : "Header 1742 Classification" 1744 o : "Clarify 1745 'public'" 1747 Index 1749 A 1750 age 6 1751 Age header field 18 1753 C 1754 cache 5 1755 Cache Directives 1756 max-age 20, 23 1757 max-stale 20 1758 min-fresh 20 1759 must-revalidate 22 1760 no-cache 19, 21 1761 no-store 19, 22 1762 no-transform 20, 23 1763 only-if-cached 20 1764 private 21 1765 proxy-revalidate 23 1766 public 21 1767 s-maxage 23 1768 Cache-Control header field 18 1769 cacheable 5 1771 E 1772 Expires header field 24 1773 explicit expiration time 6 1775 F 1776 first-hand 6 1777 fresh 6 1778 freshness lifetime 6 1780 G 1781 Grammar 1782 Age 18 1783 Age-v 18 1784 Cache-Control 19 1785 Cache-Control-v 19 1786 cache-extension 19 1787 cache-request-directive 19 1788 cache-response-directive 21 1789 delta-seconds 18 1790 Expires 25 1791 Expires-v 25 1792 extension-pragma 25 1793 Pragma 25 1794 pragma-directive 25 1795 Pragma-v 25 1796 Vary 26 1797 Vary-v 26 1798 warn-agent 27 1799 warn-code 27 1800 warn-date 27 1801 warn-text 27 1802 Warning 27 1803 Warning-v 27 1804 warning-value 27 1806 H 1807 Header Fields 1808 Age 18 1809 Cache-Control 18 1810 Expires 24 1811 Pragma 25 1812 Vary 26 1813 Warning 26 1814 heuristic expiration time 6 1816 M 1817 max-age 1818 Cache Directive 20, 23 1819 max-stale 1820 Cache Directive 20 1821 min-fresh 1822 Cache Directive 20 1823 must-revalidate 1824 Cache Directive 22 1826 N 1827 no-cache 1828 Cache Directive 19, 21 1829 no-store 1830 Cache Directive 19, 22 1831 no-transform 1832 Cache Directive 20, 23 1834 O 1835 only-if-cached 1836 Cache Directive 20 1838 P 1839 Pragma header field 25 1840 private 1841 Cache Directive 21 1842 private cache 5 1843 proxy-revalidate 1844 Cache Directive 23 1845 public 1846 Cache Directive 21 1848 S 1849 s-maxage 1850 Cache Directive 23 1851 shared cache 5 1852 stale 6 1854 V 1855 validator 6 1856 Vary header field 26 1858 W 1859 Warning header field 26 1861 Authors' Addresses 1863 Roy T. Fielding (editor) 1864 Adobe Systems Incorporated 1865 345 Park Ave 1866 San Jose, CA 95110 1867 USA 1869 EMail: fielding@gbiv.com 1870 URI: http://roy.gbiv.com/ 1872 Jim Gettys 1873 Alcatel-Lucent Bell Labs 1874 21 Oak Knoll Road 1875 Carlisle, MA 01741 1876 USA 1878 EMail: jg@freedesktop.org 1879 URI: http://gettys.wordpress.com/ 1881 Jeffrey C. Mogul 1882 Hewlett-Packard Company 1883 HP Labs, Large Scale Systems Group 1884 1501 Page Mill Road, MS 1177 1885 Palo Alto, CA 94304 1886 USA 1888 EMail: JeffMogul@acm.org 1890 Henrik Frystyk Nielsen 1891 Microsoft Corporation 1892 1 Microsoft Way 1893 Redmond, WA 98052 1894 USA 1896 EMail: henrikn@microsoft.com 1897 Larry Masinter 1898 Adobe Systems Incorporated 1899 345 Park Ave 1900 San Jose, CA 95110 1901 USA 1903 EMail: LMM@acm.org 1904 URI: http://larry.masinter.net/ 1906 Paul J. Leach 1907 Microsoft Corporation 1908 1 Microsoft Way 1909 Redmond, WA 98052 1911 EMail: paulle@microsoft.com 1913 Tim Berners-Lee 1914 World Wide Web Consortium 1915 MIT Computer Science and Artificial Intelligence Laboratory 1916 The Stata Center, Building 32 1917 32 Vassar Street 1918 Cambridge, MA 02139 1919 USA 1921 EMail: timbl@w3.org 1922 URI: http://www.w3.org/People/Berners-Lee/ 1924 Yves Lafon (editor) 1925 World Wide Web Consortium 1926 W3C / ERCIM 1927 2004, rte des Lucioles 1928 Sophia-Antipolis, AM 06902 1929 France 1931 EMail: ylafon@w3.org 1932 URI: http://www.raubacapeu.net/people/yves/ 1934 Mark Nottingham (editor) 1936 EMail: mnot@mnot.net 1937 URI: http://www.mnot.net/ 1938 Julian F. Reschke (editor) 1939 greenbytes GmbH 1940 Hafenweg 16 1941 Muenster, NW 48155 1942 Germany 1944 Phone: +49 251 2807760 1945 Fax: +49 251 2807761 1946 EMail: julian.reschke@greenbytes.de 1947 URI: http://greenbytes.de/tech/webdav/