idnits 2.17.1 draft-ietf-httpbis-p6-cache-15.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 (July 11, 2011) is 4672 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-15 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-15 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-15 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-15 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-15 -- 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: January 12, 2012 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 July 11, 2011 24 HTTP/1.1, part 6: Caching 25 draft-ietf-httpbis-p6-cache-15 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), which is archived at 41 . 43 The current issues list is at 44 and related 45 documents (including fancy diffs) can be found at 46 . 48 The changes in this draft are summarized in Appendix C.16. 50 Status of This Memo 52 This Internet-Draft is submitted in full conformance with the 53 provisions of BCP 78 and BCP 79. 55 Internet-Drafts are working documents of the Internet Engineering 56 Task Force (IETF). Note that other groups may also distribute 57 working documents as Internet-Drafts. The list of current Internet- 58 Drafts is at http://datatracker.ietf.org/drafts/current/. 60 Internet-Drafts are draft documents valid for a maximum of six months 61 and may be updated, replaced, or obsoleted by other documents at any 62 time. It is inappropriate to use Internet-Drafts as reference 63 material or to cite them other than as "work in progress." 65 This Internet-Draft will expire on January 12, 2012. 67 Copyright Notice 69 Copyright (c) 2011 IETF Trust and the persons identified as the 70 document authors. All rights reserved. 72 This document is subject to BCP 78 and the IETF Trust's Legal 73 Provisions Relating to IETF Documents 74 (http://trustee.ietf.org/license-info) in effect on the date of 75 publication of this document. Please review these documents 76 carefully, as they describe your rights and restrictions with respect 77 to this document. Code Components extracted from this document must 78 include Simplified BSD License text as described in Section 4.e of 79 the Trust Legal Provisions and are provided without warranty as 80 described in the Simplified BSD License. 82 This document may contain material from IETF Documents or IETF 83 Contributions published or made publicly available before November 84 10, 2008. The person(s) controlling the copyright in some of this 85 material may not have granted the IETF Trust the right to allow 86 modifications of such material outside the IETF Standards Process. 87 Without obtaining an adequate license from the person(s) controlling 88 the copyright in such materials, this document may not be modified 89 outside the IETF Standards Process, and derivative works of it may 90 not be created outside the IETF Standards Process, except to format 91 it for publication as an RFC or to translate it into languages other 92 than English. 94 Table of Contents 96 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 97 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 98 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 99 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 7 100 1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 101 1.4.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 7 102 1.4.2. ABNF Rules defined in other Parts of the 103 Specification . . . . . . . . . . . . . . . . . . . . 7 104 1.5. Delta Seconds . . . . . . . . . . . . . . . . . . . . . . 8 105 2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 8 106 2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 8 107 2.1.1. Storing Partial and Incomplete Responses . . . . . . . 9 108 2.2. Constructing Responses from Caches . . . . . . . . . . . . 9 109 2.3. Freshness Model . . . . . . . . . . . . . . . . . . . . . 10 110 2.3.1. Calculating Freshness Lifetime . . . . . . . . . . . . 11 111 2.3.2. Calculating Age . . . . . . . . . . . . . . . . . . . 12 112 2.3.3. Serving Stale Responses . . . . . . . . . . . . . . . 14 113 2.4. Validation Model . . . . . . . . . . . . . . . . . . . . . 14 114 2.5. Request Methods that Invalidate . . . . . . . . . . . . . 15 115 2.6. Shared Caching of Authenticated Responses . . . . . . . . 16 116 2.7. Caching Negotiated Responses . . . . . . . . . . . . . . . 16 117 2.8. Combining Responses . . . . . . . . . . . . . . . . . . . 17 118 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 18 119 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 120 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 18 121 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 19 122 3.2.2. Response Cache-Control Directives . . . . . . . . . . 21 123 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 23 124 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 24 125 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 25 126 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 127 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 27 128 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 29 129 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 130 5.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 29 131 5.2. Header Field Registration . . . . . . . . . . . . . . . . 30 132 6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 133 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 31 134 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 135 8.1. Normative References . . . . . . . . . . . . . . . . . . . 31 136 8.2. Informative References . . . . . . . . . . . . . . . . . . 32 137 Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 32 138 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 32 139 Appendix C. Change Log (to be removed by RFC Editor before 140 publication) . . . . . . . . . . . . . . . . . . . . 34 141 C.1. Since RFC 2616 . . . . . . . . . . . . . . . . . . . . . . 34 142 C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 34 143 C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 35 144 C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 35 145 C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 35 146 C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 35 147 C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 36 148 C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 36 149 C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 36 150 C.10. Since draft-ietf-httpbis-p6-cache-08 . . . . . . . . . . . 37 151 C.11. Since draft-ietf-httpbis-p6-cache-09 . . . . . . . . . . . 37 152 C.12. Since draft-ietf-httpbis-p6-cache-10 . . . . . . . . . . . 38 153 C.13. Since draft-ietf-httpbis-p6-cache-11 . . . . . . . . . . . 38 154 C.14. Since draft-ietf-httpbis-p6-cache-12 . . . . . . . . . . . 38 155 C.15. Since draft-ietf-httpbis-p6-cache-13 . . . . . . . . . . . 38 156 C.16. Since draft-ietf-httpbis-p6-cache-14 . . . . . . . . . . . 38 157 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 159 1. Introduction 161 HTTP is typically used for distributed information systems, where 162 performance can be improved by the use of response caches. This 163 document defines aspects of HTTP/1.1 related to caching and reusing 164 response messages. 166 1.1. Purpose 168 An HTTP cache is a local store of response messages and the subsystem 169 that controls its message storage, retrieval, and deletion. A cache 170 stores cacheable responses in order to reduce the response time and 171 network bandwidth consumption on future, equivalent requests. Any 172 client or server MAY employ a cache, though a cache cannot be used by 173 a server that is acting as a tunnel. 175 Caching would be useless if it did not significantly improve 176 performance. The goal of caching in HTTP/1.1 is to reuse a prior 177 response message to satisfy a current request. In some cases, a 178 stored response can be reused without the need for a network request, 179 reducing latency and network round-trips; a "freshness" mechanism is 180 used for this purpose (see Section 2.3). Even when a new request is 181 required, it is often possible to reuse all or parts of the payload 182 of a prior response to satisfy the request, thereby reducing network 183 bandwidth usage; a "validation" mechanism is used for this purpose 184 (see Section 2.4). 186 1.2. Terminology 188 This specification uses a number of terms to refer to the roles 189 played by participants in, and objects of, HTTP caching. 191 cache 193 A conformant implementation of a HTTP cache. Note that this 194 implies an HTTP/1.1 cache; this specification does not define 195 conformance for HTTP/1.0 caches. 197 shared cache 199 A cache that is accessible to more than one user; usually (but not 200 always) deployed as part of an intermediary. 202 private cache 204 A cache that is dedicated to a single user. 206 cacheable 208 A response is cacheable if a cache is allowed to store a copy of 209 the response message for use in answering subsequent requests. 210 Even when a response is cacheable, there might be additional 211 constraints on whether a cache can use the stored copy to satisfy 212 a particular request. 214 explicit expiration time 216 The time at which the origin server intends that a representation 217 no longer be returned by a cache without further validation. 219 heuristic expiration time 221 An expiration time assigned by a cache when no explicit expiration 222 time is available. 224 age 226 The age of a response is the time since it was sent by, or 227 successfully validated with, the origin server. 229 first-hand 231 A response is first-hand if the freshness model is not in use; 232 i.e., its age is 0. 234 freshness lifetime 236 The length of time between the generation of a response and its 237 expiration time. 239 fresh 241 A response is fresh if its age has not yet exceeded its freshness 242 lifetime. 244 stale 246 A response is stale if its age has passed its freshness lifetime 247 (either explicit or heuristic). 249 validator 251 A protocol element (e.g., an entity-tag or a Last-Modified time) 252 that is used to find out whether a stored response is an 253 equivalent copy of a representation. 255 1.3. Requirements 257 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 258 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 259 document are to be interpreted as described in [RFC2119]. 261 An implementation is not compliant if it fails to satisfy one or more 262 of the "MUST" or "REQUIRED" level requirements for the protocols it 263 implements. An implementation that satisfies all the "MUST" or 264 "REQUIRED" level and all the "SHOULD" level requirements for its 265 protocols is said to be "unconditionally compliant"; one that 266 satisfies all the "MUST" level requirements but not all the "SHOULD" 267 level requirements for its protocols is said to be "conditionally 268 compliant". 270 1.4. Syntax Notation 272 This specification uses the ABNF syntax defined in Section 1.2 of 273 [Part1] (which extends the syntax defined in [RFC5234] with a list 274 rule). Appendix B shows the collected ABNF, with the list rule 275 expanded. 277 The following core rules are included by reference, as defined in 278 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 279 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 280 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 281 sequence of data), SP (space), VCHAR (any visible USASCII character), 282 and WSP (whitespace). 284 1.4.1. Core Rules 286 The core rules below are defined in Section 1.2.2 of [Part1]: 288 quoted-string = 289 token = 290 OWS = 292 1.4.2. ABNF Rules defined in other Parts of the Specification 294 The ABNF rules below are defined in other parts: 296 field-name = 297 HTTP-date = 298 port = 299 pseudonym = 300 uri-host = 302 1.5. Delta Seconds 304 The delta-seconds rule specifies a non-negative integer, representing 305 time in seconds. 307 delta-seconds = 1*DIGIT 309 If an implementation receives a delta-seconds value larger than the 310 largest positive integer it can represent, or if any of its 311 subsequent calculations overflows, it MUST consider the value to be 312 2147483648 (2^31). Recipients parsing a delta-seconds value SHOULD 313 use an arithmetic type of at least 31 bits of range, and senders MUST 314 NOT send delta-seconds with a value greater than 2147483648. 316 2. Cache Operation 318 2.1. Response Cacheability 320 A cache MUST NOT store a response to any request, unless: 322 o The request method is understood by the cache and defined as being 323 cacheable, and 325 o the response status code is understood by the cache, and 327 o the "no-store" cache directive (see Section 3.2) does not appear 328 in request or response header fields, and 330 o the "private" cache response directive (see Section 3.2.2 does not 331 appear in the response, if the cache is shared, and 333 o the "Authorization" header field (see Section 4.1 of [Part7]) does 334 not appear in the request, if the cache is shared, unless the 335 response explicitly allows it (see Section 2.6), and 337 o the response either: 339 * contains an Expires header field (see Section 3.3), or 341 * contains a max-age response cache directive (see 342 Section 3.2.2), or 344 * contains a s-maxage response cache directive and the cache is 345 shared, or 347 * contains a Cache Control Extension (see Section 3.2.3) that 348 allows it to be cached, or 350 * has a status code that can be served with heuristic freshness 351 (see Section 2.3.1.1). 353 Note that any of the requirements listed above can be overridden by a 354 cache-control extension; see Section 3.2.3. 356 In this context, a cache has "understood" a request method or a 357 response status code if it recognises it and implements any cache- 358 specific behavior. In particular, 206 Partial Content responses 359 cannot be cached by an implementation that does not handle partial 360 content (see Section 2.1.1). 362 Note that in normal operation, most caches will not store a response 363 that has neither a cache validator nor an explicit expiration time, 364 as such responses are not usually useful to store. However, caches 365 are not prohibited from storing such responses. 367 2.1.1. Storing Partial and Incomplete Responses 369 A cache that receives an incomplete response (for example, with fewer 370 bytes of data than specified in a Content-Length header field) can 371 store the response, but MUST treat it as a partial response [Part5]. 372 Partial responses can be combined as described in Section 4 of 373 [Part5]; the result might be a full response or might still be 374 partial. A cache MUST NOT return a partial response to a client 375 without explicitly marking it as such using the 206 (Partial Content) 376 status code. 378 A cache that does not support the Range and Content-Range header 379 fields MUST NOT store incomplete or partial responses. 381 2.2. Constructing Responses from Caches 383 For a presented request, a cache MUST NOT return a stored response, 384 unless: 386 o The presented effective request URI (Section 4.3 of [Part1]) and 387 that of the stored response match, and 389 o the request method associated with the stored response allows it 390 to be used for the presented request, and 392 o selecting header fields nominated by the stored response (if any) 393 match those presented (see Section 2.7), and 395 o the presented request and stored response are free from directives 396 that would prevent its use (see Section 3.2 and Section 3.4), and 398 o the stored response is either: 400 * fresh (see Section 2.3), or 402 * allowed to be served stale (see Section 2.3.3), or 404 * successfully validated (see Section 2.4). 406 Note that any of the requirements listed above can be overridden by a 407 cache-control extension; see Section 3.2.3. 409 When a stored response is used to satisfy a request without 410 validation, a cache MUST include a single Age header field 411 (Section 3.1) in the response with a value equal to the stored 412 response's current_age; see Section 2.3.2. 414 A cache MUST write through requests with methods that are unsafe 415 (Section 7.1.1 of [Part2]) to the origin server; i.e., a cache must 416 not generate a reply to such a request before having forwarded the 417 request and having received a corresponding response. 419 Also, note that unsafe requests might invalidate already stored 420 responses; see Section 2.5. 422 When more than one suitable response is stored, a cache MUST use the 423 most recent response (as determined by the Date header field). It 424 can also forward a request with "Cache-Control: max-age=0" or "Cache- 425 Control: no-cache" to disambiguate which response to use. 427 A cache that does not have a clock available MUST NOT use stored 428 responses without revalidating them on every use. A cache, 429 especially a shared cache, SHOULD use a mechanism, such as NTP 430 [RFC1305], to synchronize its clock with a reliable external 431 standard. 433 2.3. Freshness Model 435 When a response is "fresh" in the cache, it can be used to satisfy 436 subsequent requests without contacting the origin server, thereby 437 improving efficiency. 439 The primary mechanism for determining freshness is for an origin 440 server to provide an explicit expiration time in the future, using 441 either the Expires header field (Section 3.3) or the max-age response 442 cache directive (Section 3.2.2). Generally, origin servers will 443 assign future explicit expiration times to responses in the belief 444 that the representation is not likely to change in a semantically 445 significant way before the expiration time is reached. 447 If an origin server wishes to force a cache to validate every 448 request, it can assign an explicit expiration time in the past to 449 indicate that the response is already stale. Compliant caches will 450 normally validate the cached response before reusing it for 451 subsequent requests (see Section 2.3.3). 453 Since origin servers do not always provide explicit expiration times, 454 a cache MAY assign a heuristic expiration time when an explicit time 455 is not specified, employing algorithms that use other header field 456 values (such as the Last-Modified time) to estimate a plausible 457 expiration time. This specification does not provide specific 458 algorithms, but does impose worst-case constraints on their results. 460 The calculation to determine if a response is fresh is: 462 response_is_fresh = (freshness_lifetime > current_age) 464 The freshness_lifetime is defined in Section 2.3.1; the current_age 465 is defined in Section 2.3.2. 467 Additionally, clients might need to influence freshness calculation. 468 They can do this using several request cache directives, with the 469 effect of either increasing or loosening constraints on freshness. 470 See Section 3.2.1. 472 Note that freshness applies only to cache operation; it cannot be 473 used to force a user agent to refresh its display or reload a 474 resource. See Section 4 for an explanation of the difference between 475 caches and history mechanisms. 477 2.3.1. Calculating Freshness Lifetime 479 A cache can calculate the freshness lifetime (denoted as 480 freshness_lifetime) of a response by using the first match of: 482 o If the cache is shared and the s-maxage response cache directive 483 (Section 3.2.2) is present, use its value, or 485 o If the max-age response cache directive (Section 3.2.2) is 486 present, use its value, or 488 o If the Expires response header field (Section 3.3) is present, use 489 its value minus the value of the Date response header field, or 491 o Otherwise, no explicit expiration time is present in the response. 492 A heuristic freshness lifetime might be applicable; see 493 Section 2.3.1.1. 495 Note that this calculation is not vulnerable to clock skew, since all 496 of the information comes from the origin server. 498 2.3.1.1. Calculating Heuristic Freshness 500 If no explicit expiration time is present in a stored response that 501 has a status code whose definition allows heuristic freshness to be 502 used (including the following in Section 8 of [Part2]: 200, 203, 206, 503 300, 301 and 410), a cache MAY calculate a heuristic expiration time. 504 A cache MUST NOT use heuristics to determine freshness for responses 505 with status codes that do not explicitly allow it. 507 When a heuristic is used to calculate freshness lifetime, a cache 508 SHOULD attach a Warning header field with a 113 warn-code to the 509 response if its current_age is more than 24 hours and such a warning 510 is not already present. 512 Also, if the response has a Last-Modified header field (Section 2.1 513 of [Part4]), a cache SHOULD NOT use a heuristic expiration value that 514 is more than some fraction of the interval since that time. A 515 typical setting of this fraction might be 10%. 517 Note: RFC 2616 ([RFC2616], Section 13.9) required that caches do 518 not calculate heuristic freshness for URIs with query components 519 (i.e., those containing '?'). In practice, this has not been 520 widely implemented. Therefore, servers are encouraged to send 521 explicit directives (e.g., Cache-Control: no-cache) if they wish 522 to preclude caching. 524 2.3.2. Calculating Age 526 HTTP/1.1 uses the Age header field to convey the estimated age of the 527 response message when obtained from a cache. The Age field value is 528 the cache's estimate of the amount of time since the response was 529 generated or validated by the origin server. In essence, the Age 530 value is the sum of the time that the response has been resident in 531 each of the caches along the path from the origin server, plus the 532 amount of time it has been in transit along network paths. 534 The following data is used for the age calculation: 536 age_value 538 The term "age_value" denotes the value of the Age header field 539 (Section 3.1), in a form appropriate for arithmetic operation; or 540 0, if not available. 542 date_value 544 HTTP/1.1 requires origin servers to send a Date header field, if 545 possible, with every response, giving the time at which the 546 response was generated. The term "date_value" denotes the value 547 of the Date header field, in a form appropriate for arithmetic 548 operations. See Section 9.3 of [Part1] for the definition of the 549 Date header field, and for requirements regarding responses 550 without it. 552 now 554 The term "now" means "the current value of the clock at the host 555 performing the calculation". A cache SHOULD use NTP ([RFC1305]) 556 or some similar protocol to synchronize its clocks to a globally 557 accurate time standard. 559 request_time 561 The current value of the clock at the host at the time the request 562 resulting in the stored response was made. 564 response_time 566 The current value of the clock at the host at the time the 567 response was received. 569 A response's age can be calculated in two entirely independent ways: 571 1. the "apparent_age": response_time minus date_value, if the local 572 clock is reasonably well synchronized to the origin server's 573 clock. If the result is negative, the result is replaced by 574 zero. 576 2. the "corrected_age_value", if all of the caches along the 577 response path implement HTTP/1.1. A cache MUST interpret this 578 value relative to the time the request was initiated, not the 579 time that the response was received. 581 apparent_age = max(0, response_time - date_value); 583 response_delay = response_time - request_time; 584 corrected_age_value = age_value + response_delay; 586 These are combined as 588 corrected_initial_age = max(apparent_age, corrected_age_value); 590 The current_age of a stored response can then be calculated by adding 591 the amount of time (in seconds) since the stored response was last 592 validated by the origin server to the corrected_initial_age. 594 resident_time = now - response_time; 595 current_age = corrected_initial_age + resident_time; 597 2.3.3. Serving Stale Responses 599 A "stale" response is one that either has explicit expiry information 600 or is allowed to have heuristic expiry calculated, but is not fresh 601 according to the calculations in Section 2.3. 603 A cache MUST NOT return a stale response if it is prohibited by an 604 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" 605 cache directive, a "must-revalidate" cache-response-directive, or an 606 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 607 see Section 3.2.2). 609 A cache SHOULD NOT return stale responses unless it is disconnected 610 (i.e., it cannot contact the origin server or otherwise find a 611 forward path) or doing so is explicitly allowed (e.g., by the max- 612 stale request directive; see Section 3.2.1). 614 A cache SHOULD append a Warning header field with the 110 warn-code 615 (see Section 3.6) to stale responses. Likewise, a cache SHOULD add 616 the 112 warn-code to stale responses if the cache is disconnected. 618 If a cache receives a first-hand response (either an entire response, 619 or a 304 (Not Modified) response) that it would normally forward to 620 the requesting client, and the received response is no longer fresh, 621 the cache SHOULD forward it to the requesting client without adding a 622 new Warning (but without removing any existing Warning header 623 fields). A cache SHOULD NOT attempt to validate a response simply 624 because that response became stale in transit. 626 2.4. Validation Model 628 When a cache has one or more stored responses for a requested URI, 629 but cannot serve any of them (e.g., because they are not fresh, or 630 one cannot be selected; see Section 2.7), it can use the conditional 631 request mechanism [Part4] in the forwarded request to give the origin 632 server an opportunity to both select a valid stored response to be 633 used, and to update it. This process is known as "validating" or 634 "revalidating" the stored response. 636 When sending such a conditional request, a cache SHOULD add an If- 637 Modified-Since header field whose value is that of the Last-Modified 638 header field from the selected (see Section 2.7) stored response, if 639 available. 641 Additionally, a cache SHOULD add an If-None-Match header field whose 642 value is that of the ETag header field(s) from all responses stored 643 for the requested URI, if present. However, if any of the stored 644 responses contains only partial content, the cache SHOULD NOT include 645 its entity-tag in the If-None-Match header field unless the request 646 is for a range that would be fully satisfied by that stored response. 648 A 304 (Not Modified) response status code indicates that the stored 649 response can be updated and reused; see Section 2.8. 651 A full response (i.e., one with a response body) indicates that none 652 of the stored responses nominated in the conditional request is 653 suitable. Instead, a cache SHOULD use the full response to satisfy 654 the request and MAY replace the stored response. 656 If a cache receives a 5xx response while attempting to validate a 657 response, it MAY either forward this response to the requesting 658 client, or act as if the server failed to respond. In the latter 659 case, it MAY return a previously stored response (see Section 2.3.3). 661 2.5. Request Methods that Invalidate 663 Because unsafe request methods (Section 7.1.1 of [Part2]) such as 664 PUT, POST or DELETE have the potential for changing state on the 665 origin server, intervening caches can use them to keep their contents 666 up-to-date. 668 A cache MUST invalidate the effective Request URI (Section 4.3 of 669 [Part1]) as well as the URI(s) in the Location and Content-Location 670 header fields (if present) when a non-error response to a request 671 with an unsafe method is received. 673 However, a cache MUST NOT invalidate a URI from a Location or 674 Content-Location header field if the host part of that URI differs 675 from the host part in the effective request URI (Section 4.3 of 676 [Part1]). This helps prevent denial of service attacks. 678 A cache SHOULD invalidate the effective request URI (Section 4.3 of 679 [Part1]) when it receives a non-error response to a request with a 680 method whose safety is unknown. 682 Here, a "non-error response" is one with a 2xx or 3xx status code. 683 "Invalidate" means that the cache will either remove all stored 684 responses related to the effective request URI, or will mark these as 685 "invalid" and in need of a mandatory validation before they can be 686 returned in response to a subsequent request. 688 Note that this does not guarantee that all appropriate responses are 689 invalidated. For example, the request that caused the change at the 690 origin server might not have gone through the cache where a response 691 is stored. 693 2.6. Shared Caching of Authenticated Responses 695 A shared cache MUST NOT use a cached response to a request with an 696 Authorization header field (Section 4.1 of [Part7]) to satisfy any 697 subsequent request unless a cache directive that allows such 698 responses to be stored is present in the response. 700 In this specification, the following Cache-Control response 701 directives (Section 3.2.2) have such an effect: must-revalidate, 702 public, s-maxage. 704 Note that cached responses that contain the "must-revalidate" and/or 705 "s-maxage" response directives are not allowed to be served stale 706 (Section 2.3.3) by shared caches. In particular, a response with 707 either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to 708 satisfy a subsequent request without revalidating it on the origin 709 server. 711 2.7. Caching Negotiated Responses 713 When a cache receives a request that can be satisfied by a stored 714 response that has a Vary header field (Section 3.5), it MUST NOT use 715 that response unless all of the selecting header fields nominated by 716 the Vary header field match in both the original request (i.e., that 717 associated with the stored response), and the presented request. 719 The selecting header fields from two requests are defined to match if 720 and only if those in the first request can be transformed to those in 721 the second request by applying any of the following: 723 o adding or removing whitespace, where allowed in the header field's 724 syntax 726 o combining multiple header fields with the same field name (see 727 Section 3.2 of [Part1]) 729 o normalizing both header field values in a way that is known to 730 have identical semantics, according to the header field's 731 specification (e.g., re-ordering field values when order is not 732 significant; case-normalization, where values are defined to be 733 case-insensitive) 735 If (after any normalization that might take place) a header field is 736 absent from a request, it can only match another request if it is 737 also absent there. 739 A Vary header field-value of "*" always fails to match, and 740 subsequent requests to that resource can only be properly interpreted 741 by the origin server. 743 The stored response with matching selecting header fields is known as 744 the selected response. 746 If multiple selected responses are available, the most recent 747 response (as determined by the Date header field) is used; see 748 Section 2.2. 750 If no selected response is available, the cache MAY forward the 751 presented request to the origin server in a conditional request; see 752 Section 2.4. 754 2.8. Combining Responses 756 When a cache receives a 304 (Not Modified) response or a 206 (Partial 757 Content) response (in this section, the "new" response"), it needs to 758 create an updated response by combining the stored response with the 759 new one, so that the updated response can be used to satisfy the 760 request, and potentially update the cached response. 762 If the new response contains an ETag, it identifies the stored 763 response to use. [[TODO-mention-CL: might need language about 764 Content-Location here]][[TODO-select-for-combine: Shouldn't this be 765 the selected response?]] 767 When the new response's status code is 206 (partial content), a cache 768 MUST NOT combine it with the old response if either response does not 769 have a validator, and MUST NOT combine it with the old response when 770 those validators do not match with the strong comparison function 771 (see Section 2.2.2 of [Part4]). 773 The stored response header fields are used as those of the updated 774 response, except that 775 o a cache MUST delete any stored Warning header fields with warn- 776 code 1xx (see Section 3.6). 778 o a cache MUST retain any stored Warning header fields with warn- 779 code 2xx. 781 o a cache MUST use other header fields provided in the new response 782 to replace all instances of the corresponding header fields from 783 the stored response. 785 A cache MUST use the updated response header fields to replace those 786 of the stored response (unless the stored response is removed). In 787 the case of a 206 response, a cache MAY store the combined 788 representation. 790 3. Header Field Definitions 792 This section defines the syntax and semantics of HTTP/1.1 header 793 fields related to caching. 795 3.1. Age 797 The "Age" header field conveys the sender's estimate of the amount of 798 time since the response was generated or successfully validated at 799 the origin server. Age values are calculated as specified in 800 Section 2.3.2. 802 Age = delta-seconds 804 Age field-values are non-negative integers, representing time in 805 seconds (see Section 1.5). 807 The presence of an Age header field in a response implies that a 808 response is not first-hand. However, the converse is not true, since 809 HTTP/1.0 caches might not implement the Age header field. 811 3.2. Cache-Control 813 The "Cache-Control" header field is used to specify directives for 814 caches along the request/response chain. Such cache directives are 815 unidirectional in that the presence of a directive in a request does 816 not imply that the same directive is to be given in the response. 818 A cache MUST obey the requirements of the Cache-Control directives 819 defined in this section. See Section 3.2.3 for information about how 820 Cache-Control directives defined elsewhere are handled. 822 Note: HTTP/1.0 caches might not implement Cache-Control and might 823 only implement Pragma: no-cache (see Section 3.4). 825 A proxy, whether or not it implements a cache, MUST pass cache 826 directives through in forwarded messages, regardless of their 827 significance to that application, since the directives might be 828 applicable to all recipients along the request/response chain. It is 829 not possible to target a directive to a specific cache. 831 Cache-Control = 1#cache-directive 833 cache-directive = cache-request-directive 834 / cache-response-directive 836 cache-extension = token [ "=" ( token / quoted-string ) ] 838 3.2.1. Request Cache-Control Directives 840 cache-request-directive = 841 "no-cache" 842 / "no-store" 843 / "max-age" "=" delta-seconds 844 / "max-stale" [ "=" delta-seconds ] 845 / "min-fresh" "=" delta-seconds 846 / "no-transform" 847 / "only-if-cached" 848 / cache-extension 850 no-cache 852 The no-cache request directive indicates that a cache MUST NOT use 853 a stored response to satisfy the request without successful 854 validation on the origin server. 856 no-store 858 The no-store request directive indicates that a cache MUST NOT 859 store any part of either this request or any response to it. This 860 directive applies to both private and shared caches. "MUST NOT 861 store" in this context means that the cache MUST NOT intentionally 862 store the information in non-volatile storage, and MUST make a 863 best-effort attempt to remove the information from volatile 864 storage as promptly as possible after forwarding it. 866 This directive is NOT a reliable or sufficient mechanism for 867 ensuring privacy. In particular, malicious or compromised caches 868 might not recognize or obey this directive, and communications 869 networks might be vulnerable to eavesdropping. 871 Note that if a request containing this directive is satisfied from 872 a cache, the no-store request directive does not apply to the 873 already stored response. 875 max-age 877 The max-age request directive indicates that the client is 878 unwilling to accept a response whose age is greater than the 879 specified number of seconds. Unless the max-stale request 880 directive is also present, the client is not willing to accept a 881 stale response. 883 max-stale 885 The max-stale request directive indicates that the client is 886 willing to accept a response that has exceeded its expiration 887 time. If max-stale is assigned a value, then the client is 888 willing to accept a response that has exceeded its expiration time 889 by no more than the specified number of seconds. If no value is 890 assigned to max-stale, then the client is willing to accept a 891 stale response of any age. 893 min-fresh 895 The min-fresh request directive indicates that the client is 896 willing to accept a response whose freshness lifetime is no less 897 than its current age plus the specified time in seconds. That is, 898 the client wants a response that will still be fresh for at least 899 the specified number of seconds. 901 no-transform 903 The no-transform request directive indicates that an intermediary 904 (whether or not it implements a cache) MUST NOT change the 905 Content-Encoding, Content-Range or Content-Type request header 906 fields, nor the request representation. 908 only-if-cached 910 The only-if-cached request directive indicates that the client 911 only wishes to obtain a stored response. If it receives this 912 directive, a cache SHOULD either respond using a stored response 913 that is consistent with the other constraints of the request, or 914 respond with a 504 (Gateway Timeout) status code. If a group of 915 caches is being operated as a unified system with good internal 916 connectivity, a member cache MAY forward such a request within 917 that group of caches. 919 3.2.2. Response Cache-Control Directives 921 cache-response-directive = 922 "public" 923 / "private" [ "=" DQUOTE 1#field-name DQUOTE ] 924 / "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] 925 / "no-store" 926 / "no-transform" 927 / "must-revalidate" 928 / "proxy-revalidate" 929 / "max-age" "=" delta-seconds 930 / "s-maxage" "=" delta-seconds 931 / cache-extension 933 public 935 The public response directive indicates that a response whose 936 associated request contains an 'Authentication' header MAY be 937 stored (see Section 2.6). 939 private 941 The private response directive indicates that the response message 942 is intended for a single user and MUST NOT be stored by a shared 943 cache. A private cache MAY store the response. 945 If the private response directive specifies one or more field- 946 names, this requirement is limited to the field-values associated 947 with the listed response header fields. That is, a shared cache 948 MUST NOT store the specified field-names(s), whereas it MAY store 949 the remainder of the response message. 951 Note: This usage of the word private only controls where the 952 response can be stored; it cannot ensure the privacy of the 953 message content. Also, private response directives with field- 954 names are often handled by implementations as if an unqualified 955 private directive was received; i.e., the special handling for the 956 qualified form is not widely implemented. 958 no-cache 960 The no-cache response directive indicates that the response MUST 961 NOT be used to satisfy a subsequent request without successful 962 validation on the origin server. This allows an origin server to 963 prevent a cache from using it to satisfy a request without 964 contacting it, even by caches that have been configured to return 965 stale responses. 967 If the no-cache response directive specifies one or more field- 968 names, this requirement is limited to the field-values associated 969 with the listed response header fields. That is, a cache MUST NOT 970 send the specified field-name(s) in the response to a subsequent 971 request without successful validation on the origin server. This 972 allows an origin server to prevent the re-use of certain header 973 fields in a response, while still allowing caching of the rest of 974 the response. 976 Note: Most HTTP/1.0 caches will not recognize or obey this 977 directive. Also, no-cache response directives with field-names 978 are often handled by implementations as if an unqualified no-cache 979 directive was received; i.e., the special handling for the 980 qualified form is not widely implemented. 982 no-store 984 The no-store response directive indicates that a cache MUST NOT 985 store any part of either the immediate request or response. This 986 directive applies to both private and shared caches. "MUST NOT 987 store" in this context means that the cache MUST NOT intentionally 988 store the information in non-volatile storage, and MUST make a 989 best-effort attempt to remove the information from volatile 990 storage as promptly as possible after forwarding it. 992 This directive is NOT a reliable or sufficient mechanism for 993 ensuring privacy. In particular, malicious or compromised caches 994 might not recognize or obey this directive, and communications 995 networks might be vulnerable to eavesdropping. 997 must-revalidate 999 The must-revalidate response directive indicates that once it has 1000 become stale, a cache MUST NOT use the response to satisfy 1001 subsequent requests without successful validation on the origin 1002 server. 1004 The must-revalidate directive is necessary to support reliable 1005 operation for certain protocol features. In all circumstances a 1006 cache MUST obey the must-revalidate directive; in particular, if a 1007 cache cannot reach the origin server for any reason, it MUST 1008 generate a 504 (Gateway Timeout) response. 1010 A server SHOULD send the must-revalidate directive if and only if 1011 failure to validate a request on the representation could result 1012 in incorrect operation, such as a silently unexecuted financial 1013 transaction. 1015 proxy-revalidate 1017 The proxy-revalidate response directive has the same meaning as 1018 the must-revalidate response directive, except that it does not 1019 apply to private caches. 1021 max-age 1023 The max-age response directive indicates that the response is to 1024 be considered stale after its age is greater than the specified 1025 number of seconds. 1027 s-maxage 1029 The s-maxage response directive indicates that, in shared caches, 1030 the maximum age specified by this directive overrides the maximum 1031 age specified by either the max-age directive or the Expires 1032 header field. The s-maxage directive also implies the semantics 1033 of the proxy-revalidate response directive. 1035 no-transform 1037 The no-transform response directive indicates that an intermediary 1038 (regardless of whether it implements a cache) MUST NOT change the 1039 Content-Encoding, Content-Range or Content-Type response header 1040 fields, nor the response representation. 1042 3.2.3. Cache Control Extensions 1044 The Cache-Control header field can be extended through the use of one 1045 or more cache-extension tokens, each with an optional value. 1046 Informational extensions (those that do not require a change in cache 1047 behavior) can be added without changing the semantics of other 1048 directives. Behavioral extensions are designed to work by acting as 1049 modifiers to the existing base of cache directives. Both the new 1050 directive and the standard directive are supplied, such that 1051 applications that do not understand the new directive will default to 1052 the behavior specified by the standard directive, and those that 1053 understand the new directive will recognize it as modifying the 1054 requirements associated with the standard directive. In this way, 1055 extensions to the cache-control directives can be made without 1056 requiring changes to the base protocol. 1058 This extension mechanism depends on an HTTP cache obeying all of the 1059 cache-control directives defined for its native HTTP-version, obeying 1060 certain extensions, and ignoring all directives that it does not 1061 understand. 1063 For example, consider a hypothetical new response directive called 1064 "community" that acts as a modifier to the private directive. We 1065 define this new directive to mean that, in addition to any private 1066 cache, any cache that is shared only by members of the community 1067 named within its value may cache the response. An origin server 1068 wishing to allow the UCI community to use an otherwise private 1069 response in their shared cache(s) could do so by including 1071 Cache-Control: private, community="UCI" 1073 A cache seeing this header field will act correctly even if the cache 1074 does not understand the community cache-extension, since it will also 1075 see and understand the private directive and thus default to the safe 1076 behavior. 1078 A cache MUST ignore unrecognized cache directives; it is assumed that 1079 any cache directive likely to be unrecognized by an HTTP/1.1 cache 1080 will be combined with standard directives (or the response's default 1081 cacheability) such that the cache behavior will remain minimally 1082 correct even if the cache does not understand the extension(s). 1084 The HTTP Cache Directive Registry defines the name space for the 1085 cache directives. 1087 A registration MUST include the following fields: 1089 o Cache Directive Name 1091 o Pointer to specification text 1093 Values to be added to this name space are subject to IETF review 1094 ([RFC5226], Section 4.1). 1096 The registry itself is maintained at 1097 . 1099 3.3. Expires 1101 The "Expires" header field gives the date/time after which the 1102 response is considered stale. See Section 2.3 for further discussion 1103 of the freshness model. 1105 The presence of an Expires field does not imply that the original 1106 resource will change or cease to exist at, before, or after that 1107 time. 1109 The field-value is an absolute date and time as defined by HTTP-date 1110 in Section 6.1 of [Part1]; a sender MUST use the rfc1123-date format. 1112 Expires = HTTP-date 1114 For example 1116 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1118 Note: If a response includes a Cache-Control field with the max- 1119 age directive (see Section 3.2.2), that directive overrides the 1120 Expires field. Likewise, the s-maxage directive overrides Expires 1121 in shared caches. 1123 A server SHOULD NOT send Expires dates more than one year in the 1124 future. 1126 A cache MUST treat other invalid date formats, especially including 1127 the value "0", as in the past (i.e., "already expired"). 1129 3.4. Pragma 1131 The "Pragma" header field allows backwards compatibility with 1132 HTTP/1.0 caches, so that clients can specify a "no-cache" request 1133 that they will understand (as Cache-Control was not defined until 1134 HTTP/1.1). When the Cache-Control header is also present and 1135 understood in a request, Pragma is ignored. 1137 In HTTP/1.0, Pragma was defined as an extensible field for 1138 implementation-specified directives for recipients. This 1139 specification deprecates such extensions to improve interoperability. 1141 Pragma = 1#pragma-directive 1142 pragma-directive = "no-cache" / extension-pragma 1143 extension-pragma = token [ "=" ( token / quoted-string ) ] 1145 When the Cache-Control header is not present in a request, the no- 1146 cache request pragma-directive MUST have the same effect on caches as 1147 if "Cache-Control: no-cache" were present (see Section 3.2.1). 1149 When sending a no-cache request, a client SHOULD include both pragma 1150 and cache-control directives unless Cache-Control: no-cache is 1151 purposefully omitted to target other Cache-Control response 1152 directives at HTTP/1.1 caches. For example: 1154 GET / HTTP/1.1 1155 Host: www.example.com 1156 Cache-Control: max-age=30 1157 Pragma: no-cache 1159 will constrain HTTP/1.1 caches to serve a response no older than 30 1160 seconds, while precluding implementations that do not understand 1161 Cache-Control from serving a cached response. 1163 Note: Because the meaning of "Pragma: no-cache" in responses is 1164 not specified, it does not provide a reliable replacement for 1165 "Cache-Control: no-cache" in them. 1167 3.5. Vary 1169 The "Vary" header field conveys the set of header fields that were 1170 used to select the representation. 1172 Caches use this information, in part, to determine whether a stored 1173 response can be used to satisfy a given request; see Section 2.7. 1174 determines, while the response is fresh, whether a cache is permitted 1175 to use the response to reply to a subsequent request without 1176 validation; see Section 2.7. 1178 In uncacheable or stale responses, the Vary field value advises the 1179 user agent about the criteria that were used to select the 1180 representation. 1182 Vary = "*" / 1#field-name 1184 The set of header fields named by the Vary field value is known as 1185 the selecting header fields. 1187 A server SHOULD include a Vary header field with any cacheable 1188 response that is subject to server-driven negotiation. Doing so 1189 allows a cache to properly interpret future requests on that resource 1190 and informs the user agent about the presence of negotiation on that 1191 resource. A server MAY include a Vary header field with a non- 1192 cacheable response that is subject to server-driven negotiation, 1193 since this might provide the user agent with useful information about 1194 the dimensions over which the response varies at the time of the 1195 response. 1197 A Vary field value of "*" signals that unspecified parameters not 1198 limited to the header fields (e.g., the network address of the 1199 client), play a role in the selection of the response representation; 1200 therefore, a cache cannot determine whether this response is 1201 appropriate. A proxy MUST NOT generate the "*" value. 1203 The field-names given are not limited to the set of standard header 1204 fields defined by this specification. Field names are case- 1205 insensitive. 1207 3.6. Warning 1209 The "Warning" header field is used to carry additional information 1210 about the status or transformation of a message that might not be 1211 reflected in the message. This information is typically used to warn 1212 about possible incorrectness introduced by caching operations or 1213 transformations applied to the payload of the message. 1215 Warnings can be used for other purposes, both cache-related and 1216 otherwise. The use of a warning, rather than an error status code, 1217 distinguishes these responses from true failures. 1219 Warning header fields can in general be applied to any message, 1220 however some warn-codes are specific to caches and can only be 1221 applied to response messages. 1223 Warning = 1#warning-value 1225 warning-value = warn-code SP warn-agent SP warn-text 1226 [SP warn-date] 1228 warn-code = 3DIGIT 1229 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1230 ; the name or pseudonym of the server adding 1231 ; the Warning header field, for use in debugging 1232 warn-text = quoted-string 1233 warn-date = DQUOTE HTTP-date DQUOTE 1235 Multiple warnings can be attached to a response (either by the origin 1236 server or by a cache), including multiple warnings with the same code 1237 number, only differing in warn-text. 1239 When this occurs, the user agent SHOULD inform the user of as many of 1240 them as possible, in the order that they appear in the response. 1242 Systems that generate multiple Warning header fields SHOULD order 1243 them with this user agent behavior in mind. New Warning header 1244 fields SHOULD be added after any existing Warning headers fields. 1246 Warnings are assigned three digit warn-codes. The first digit 1247 indicates whether the Warning is required to be deleted from a stored 1248 response after validation: 1250 o 1xx Warnings describe the freshness or validation status of the 1251 response, and so MUST be deleted by a cache after validation. 1252 They can only be generated by a cache when validating a cached 1253 entry, and MUST NOT be generated in any other situation. 1255 o 2xx Warnings describe some aspect of the representation that is 1256 not rectified by a validation (for example, a lossy compression of 1257 the representation) and MUST NOT be deleted by a cache after 1258 validation, unless a full response is returned, in which case they 1259 MUST be. 1261 If an implementation sends a message with one or more Warning header 1262 fields to a receiver whose version is HTTP/1.0 or lower, then the 1263 sender MUST include in each warning-value a warn-date that matches 1264 the Date header field in the message. 1266 If a system receives a message with a warning-value that includes a 1267 warn-date, and that warn-date is different from the Date value in the 1268 response, then that warning-value MUST be deleted from the message 1269 before storing, forwarding, or using it. (preventing the consequences 1270 of naive caching of Warning header fields.) If all of the warning- 1271 values are deleted for this reason, the Warning header field MUST be 1272 deleted as well. 1274 The following warn-codes are defined by this specification, each with 1275 a recommended warn-text in English, and a description of its meaning. 1277 110 Response is stale 1279 A cache SHOULD include this whenever the returned response is 1280 stale. 1282 111 Revalidation failed 1284 A cache SHOULD include this when returning a stale response 1285 because an attempt to validate the response failed, due to an 1286 inability to reach the server. 1288 112 Disconnected operation 1290 A cache SHOULD b include this if it is intentionally disconnected 1291 from the rest of the network for a period of time. 1293 113 Heuristic expiration 1295 A cache SHOULD include this if it heuristically chose a freshness 1296 lifetime greater than 24 hours and the response's age is greater 1297 than 24 hours. 1299 199 Miscellaneous warning 1301 The warning text can include arbitrary information to be presented 1302 to a human user, or logged. A system receiving this warning MUST 1303 NOT take any automated action, besides presenting the warning to 1304 the user. 1306 214 Transformation applied 1308 MUST be added by a proxy if it applies any transformation to the 1309 representation, such as changing the content-coding, media-type, 1310 or modifying the representation data, unless this Warning code 1311 already appears in the response. 1313 299 Miscellaneous persistent warning 1315 The warning text can include arbitrary information to be presented 1316 to a human user, or logged. A system receiving this warning MUST 1317 NOT take any automated action. 1319 4. History Lists 1321 User agents often have history mechanisms, such as "Back" buttons and 1322 history lists, that can be used to redisplay a representation 1323 retrieved earlier in a session. 1325 The freshness model (Section 2.3) does not necessarily apply to 1326 history mechanisms. I.e., a history mechanism can display a previous 1327 representation even if it has expired. 1329 This does not prohibit the history mechanism from telling the user 1330 that a view might be stale, or from honoring cache directives (e.g., 1331 Cache-Control: no-store). 1333 5. IANA Considerations 1335 5.1. Cache Directive Registry 1337 The registration procedure for HTTP Cache Directives is defined by 1338 Section 3.2.3 of this document. 1340 The HTTP Cache Directive Registry shall be created at 1341 and be 1342 populated with the registrations below: 1344 +------------------------+------------------------------+ 1345 | Cache Directive | Reference | 1346 +------------------------+------------------------------+ 1347 | max-age | Section 3.2.1, Section 3.2.2 | 1348 | max-stale | Section 3.2.1 | 1349 | min-fresh | Section 3.2.1 | 1350 | must-revalidate | Section 3.2.2 | 1351 | no-cache | Section 3.2.1, Section 3.2.2 | 1352 | no-store | Section 3.2.1, Section 3.2.2 | 1353 | no-transform | Section 3.2.1, Section 3.2.2 | 1354 | only-if-cached | Section 3.2.1 | 1355 | private | Section 3.2.2 | 1356 | proxy-revalidate | Section 3.2.2 | 1357 | public | Section 3.2.2 | 1358 | s-maxage | Section 3.2.2 | 1359 | stale-if-error | [RFC5861], Section 4 | 1360 | stale-while-revalidate | [RFC5861], Section 3 | 1361 +------------------------+------------------------------+ 1363 5.2. Header Field Registration 1365 The Message Header Field Registry located at shall be 1367 updated with the permanent registrations below (see [RFC3864]): 1369 +-------------------+----------+----------+-------------+ 1370 | Header Field Name | Protocol | Status | Reference | 1371 +-------------------+----------+----------+-------------+ 1372 | Age | http | standard | Section 3.1 | 1373 | Cache-Control | http | standard | Section 3.2 | 1374 | Expires | http | standard | Section 3.3 | 1375 | Pragma | http | standard | Section 3.4 | 1376 | Vary | http | standard | Section 3.5 | 1377 | Warning | http | standard | Section 3.6 | 1378 +-------------------+----------+----------+-------------+ 1380 The change controller is: "IETF (iesg@ietf.org) - Internet 1381 Engineering Task Force". 1383 6. Security Considerations 1385 Caches expose additional potential vulnerabilities, since the 1386 contents of the cache represent an attractive target for malicious 1387 exploitation. Because cache contents persist after an HTTP request 1388 is complete, an attack on the cache can reveal information long after 1389 a user believes that the information has been removed from the 1390 network. Therefore, cache contents need to be protected as sensitive 1391 information. 1393 7. Acknowledgments 1395 Much of the content and presentation of the caching design is due to 1396 suggestions and comments from individuals including: Shel Kaphan, 1397 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 1399 8. References 1401 8.1. Normative References 1403 [Part1] 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 1: URIs, Connections, 1406 and Message Parsing", draft-ietf-httpbis-p1-messaging-15 1407 (work in progress), July 2011. 1409 [Part2] 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 2: Message 1412 Semantics", draft-ietf-httpbis-p2-semantics-15 (work in 1413 progress), July 2011. 1415 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1416 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1417 and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional 1418 Requests", draft-ietf-httpbis-p4-conditional-15 (work in 1419 progress), July 2011. 1421 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1422 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1423 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 1424 Partial Responses", draft-ietf-httpbis-p5-range-15 (work 1425 in progress), July 2011. 1427 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1428 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1429 and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", 1430 draft-ietf-httpbis-p7-auth-15 (work in progress), 1431 July 2011. 1433 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1434 Requirement Levels", BCP 14, RFC 2119, March 1997. 1436 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1437 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1439 8.2. Informative References 1441 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1442 Specification, Implementation", RFC 1305, March 1992. 1444 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1445 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1446 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1448 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1449 Procedures for Message Header Fields", BCP 90, RFC 3864, 1450 September 2004. 1452 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1453 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1454 May 2008. 1456 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1457 Content", RFC 5861, April 2010. 1459 Appendix A. Changes from RFC 2616 1461 Make the specified age calculation algorithm less conservative. 1462 (Section 2.3.2) 1464 Remove requirement to consider Content-Location in successful 1465 responses in order to determine the appropriate response to use. 1466 (Section 2.4) 1468 Clarify denial of service attack avoidance requirement. 1469 (Section 2.5) 1471 Change ABNF productions for header fields to only define the field 1472 value. (Section 3) 1474 Do not mention RFC 2047 encoding and multiple languages in Warning 1475 header fields anymore, as these aspects never were implemented. 1476 (Section 3.6) 1478 Appendix B. Collected ABNF 1480 Age = delta-seconds 1482 Cache-Control = *( "," OWS ) cache-directive *( OWS "," [ OWS 1483 cache-directive ] ) 1485 Expires = HTTP-date 1486 HTTP-date = 1488 OWS = 1490 Pragma = *( "," OWS ) pragma-directive *( OWS "," [ OWS 1491 pragma-directive ] ) 1493 Vary = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name ] 1494 ) ) 1496 Warning = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value ] 1497 ) 1499 cache-directive = cache-request-directive / cache-response-directive 1500 cache-extension = token [ "=" ( token / quoted-string ) ] 1501 cache-request-directive = "no-cache" / "no-store" / ( "max-age=" 1502 delta-seconds ) / ( "max-stale" [ "=" delta-seconds ] ) / ( 1503 "min-fresh=" delta-seconds ) / "no-transform" / "only-if-cached" / 1504 cache-extension 1505 cache-response-directive = "public" / ( "private" [ "=" DQUOTE *( "," 1506 OWS ) field-name *( OWS "," [ OWS field-name ] ) DQUOTE ] ) / ( 1507 "no-cache" [ "=" DQUOTE *( "," OWS ) field-name *( OWS "," [ OWS 1508 field-name ] ) DQUOTE ] ) / "no-store" / "no-transform" / 1509 "must-revalidate" / "proxy-revalidate" / ( "max-age=" delta-seconds 1510 ) / ( "s-maxage=" delta-seconds ) / cache-extension 1512 delta-seconds = 1*DIGIT 1514 extension-pragma = token [ "=" ( token / quoted-string ) ] 1516 field-name = 1518 port = 1519 pragma-directive = "no-cache" / extension-pragma 1520 pseudonym = 1522 quoted-string = 1524 token = 1526 uri-host = 1528 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1529 warn-code = 3DIGIT 1530 warn-date = DQUOTE HTTP-date DQUOTE 1531 warn-text = quoted-string 1532 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date 1533 ] 1535 ABNF diagnostics: 1537 ; Age defined but not used 1538 ; Cache-Control defined but not used 1539 ; Expires defined but not used 1540 ; Pragma defined but not used 1541 ; Vary defined but not used 1542 ; Warning defined but not used 1544 Appendix C. Change Log (to be removed by RFC Editor before publication) 1546 C.1. Since RFC 2616 1548 Extracted relevant partitions from [RFC2616]. 1550 C.2. Since draft-ietf-httpbis-p6-cache-00 1552 Closed issues: 1554 o : "Trailer" 1555 () 1557 o : "Invalidation 1558 after Update or Delete" 1559 () 1561 o : "Normative and 1562 Informative references" 1564 o : "Date reference 1565 typo" 1567 o : "Connection 1568 header text" 1570 o : "Informative 1571 references" 1573 o : "ISO-8859-1 1574 Reference" 1576 o : "Normative up- 1577 to-date references" 1579 o : "typo in 1580 13.2.2" 1582 Other changes: 1584 o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress 1585 on ) 1587 C.3. Since draft-ietf-httpbis-p6-cache-01 1589 Closed issues: 1591 o : "rel_path not 1592 used" 1594 Other changes: 1596 o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work 1597 in progress on ) 1599 o Add explicit references to BNF syntax and rules imported from 1600 other parts of the specification. 1602 C.4. Since draft-ietf-httpbis-p6-cache-02 1604 Ongoing work on IANA Message Header Field Registration 1605 (): 1607 o Reference RFC 3984, and update header field registrations for 1608 header fields defined in this document. 1610 C.5. Since draft-ietf-httpbis-p6-cache-03 1612 Closed issues: 1614 o : "Vary header 1615 classification" 1617 C.6. Since draft-ietf-httpbis-p6-cache-04 1619 Ongoing work on ABNF conversion 1620 (): 1622 o Use "/" instead of "|" for alternatives. 1624 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1625 whitespace ("OWS") and required whitespace ("RWS"). 1627 o Rewrite ABNFs to spell out whitespace rules, factor out header 1628 field value format definitions. 1630 C.7. Since draft-ietf-httpbis-p6-cache-05 1632 This is a total rewrite of this part of the specification. 1634 Affected issues: 1636 o : "Definition of 1637 1xx Warn-Codes" 1639 o : "Placement of 1640 13.5.1 and 13.5.2" 1642 o : "The role of 1643 Warning and Semantic Transparency in Caching" 1645 o : "Methods and 1646 Caching" 1648 In addition: Final work on ABNF conversion 1649 (): 1651 o Add appendix containing collected and expanded ABNF, reorganize 1652 ABNF introduction. 1654 C.8. Since draft-ietf-httpbis-p6-cache-06 1656 Closed issues: 1658 o : "base for 1659 numeric protocol elements" 1661 Affected issues: 1663 o : "Vary and non- 1664 existant headers" 1666 C.9. Since draft-ietf-httpbis-p6-cache-07 1668 Closed issues: 1670 o : "Definition of 1671 1xx Warn-Codes" 1673 o : "Content- 1674 Location on 304 responses" 1676 o : "private and 1677 no-cache CC directives with headers" 1679 o : "RFC2047 and 1680 warn-text" 1682 C.10. Since draft-ietf-httpbis-p6-cache-08 1684 Closed issues: 1686 o : "serving 1687 negotiated responses from cache: header-specific canonicalization" 1689 o : "Effect of CC 1690 directives on history lists" 1692 o : "Cache 1693 Extensions can override no-store, etc." 1695 Affected issues: 1697 o : Status codes 1698 and caching 1700 Partly resolved issues: 1702 o : "Placement of 1703 13.5.1 and 13.5.2" 1705 C.11. Since draft-ietf-httpbis-p6-cache-09 1707 Closed issues: 1709 o : "Age 1710 calculation" 1712 o : "Clarify 1713 differences between / requirements for request and response CC 1714 directives" 1716 o : "Caching 1717 authenticated responses" 1719 o : "IANA registry 1720 for cache-control directives" 1722 o : "Heuristic 1723 caching of URLs with query components" 1725 Partly resolved issues: 1727 o : "Term for the 1728 requested resource's URI" 1730 C.12. Since draft-ietf-httpbis-p6-cache-10 1732 Closed issues: 1734 o : "Clarify 1735 entity / representation / variant terminology" 1737 o : "consider 1738 removing the 'changes from 2068' sections" 1740 o : "Allowing 1741 heuristic caching for new status codes" 1743 o Clean up TODOs and prose in "Combining Responses." 1745 C.13. Since draft-ietf-httpbis-p6-cache-11 1747 Closed issues: 1749 o : "Text about 1750 clock requirement for caches belongs in p6" 1752 C.14. Since draft-ietf-httpbis-p6-cache-12 1754 Closed issues: 1756 o : "Header 1757 Classification" 1759 o : "Clarify 1760 'public'" 1762 C.15. Since draft-ietf-httpbis-p6-cache-13 1764 Closed issues: 1766 o : "untangle 1767 ABNFs for header fields" 1769 C.16. Since draft-ietf-httpbis-p6-cache-14 1771 Closed issues: 1773 o : "Mismatch Vary" 1774 o : "Cache 1775 Invalidation only happens upon successful responses" 1777 o : "Recommend 1778 minimum sizes for protocol elements" 1780 o : "Proxies don't 1781 'understand' methods" 1783 o : "Pragma" 1785 Index 1787 A 1788 age 6 1789 Age header field 18 1791 C 1792 cache 5 1793 Cache Directives 1794 max-age 20, 23 1795 max-stale 20 1796 min-fresh 20 1797 must-revalidate 22 1798 no-cache 19, 21 1799 no-store 19, 22 1800 no-transform 20, 23 1801 only-if-cached 20 1802 private 21 1803 proxy-revalidate 23 1804 public 21 1805 s-maxage 23 1806 Cache-Control header field 18 1807 cacheable 5 1809 E 1810 Expires header field 24 1811 explicit expiration time 6 1813 F 1814 first-hand 6 1815 fresh 6 1816 freshness lifetime 6 1818 G 1819 Grammar 1820 Age 18 1821 Cache-Control 19 1822 cache-extension 19 1823 cache-request-directive 19 1824 cache-response-directive 21 1825 delta-seconds 8 1826 Expires 25 1827 extension-pragma 25 1828 Pragma 25 1829 pragma-directive 25 1830 Vary 26 1831 warn-agent 27 1832 warn-code 27 1833 warn-date 27 1834 warn-text 27 1835 Warning 27 1836 warning-value 27 1838 H 1839 Header Fields 1840 Age 18 1841 Cache-Control 18 1842 Expires 24 1843 Pragma 25 1844 Vary 26 1845 Warning 27 1846 heuristic expiration time 6 1848 M 1849 max-age 1850 Cache Directive 20, 23 1851 max-stale 1852 Cache Directive 20 1853 min-fresh 1854 Cache Directive 20 1855 must-revalidate 1856 Cache Directive 22 1858 N 1859 no-cache 1860 Cache Directive 19, 21 1861 no-store 1862 Cache Directive 19, 22 1863 no-transform 1864 Cache Directive 20, 23 1866 O 1867 only-if-cached 1868 Cache Directive 20 1870 P 1871 Pragma header field 25 1872 private 1873 Cache Directive 21 1874 private cache 5 1875 proxy-revalidate 1876 Cache Directive 23 1877 public 1878 Cache Directive 21 1880 S 1881 s-maxage 1882 Cache Directive 23 1883 shared cache 5 1884 stale 6 1886 V 1887 validator 6 1888 Vary header field 26 1890 W 1891 Warning header field 27 1893 Authors' Addresses 1895 Roy T. Fielding (editor) 1896 Adobe Systems Incorporated 1897 345 Park Ave 1898 San Jose, CA 95110 1899 USA 1901 EMail: fielding@gbiv.com 1902 URI: http://roy.gbiv.com/ 1904 Jim Gettys 1905 Alcatel-Lucent Bell Labs 1906 21 Oak Knoll Road 1907 Carlisle, MA 01741 1908 USA 1910 EMail: jg@freedesktop.org 1911 URI: http://gettys.wordpress.com/ 1912 Jeffrey C. Mogul 1913 Hewlett-Packard Company 1914 HP Labs, Large Scale Systems Group 1915 1501 Page Mill Road, MS 1177 1916 Palo Alto, CA 94304 1917 USA 1919 EMail: JeffMogul@acm.org 1921 Henrik Frystyk Nielsen 1922 Microsoft Corporation 1923 1 Microsoft Way 1924 Redmond, WA 98052 1925 USA 1927 EMail: henrikn@microsoft.com 1929 Larry Masinter 1930 Adobe Systems Incorporated 1931 345 Park Ave 1932 San Jose, CA 95110 1933 USA 1935 EMail: LMM@acm.org 1936 URI: http://larry.masinter.net/ 1938 Paul J. Leach 1939 Microsoft Corporation 1940 1 Microsoft Way 1941 Redmond, WA 98052 1943 EMail: paulle@microsoft.com 1945 Tim Berners-Lee 1946 World Wide Web Consortium 1947 MIT Computer Science and Artificial Intelligence Laboratory 1948 The Stata Center, Building 32 1949 32 Vassar Street 1950 Cambridge, MA 02139 1951 USA 1953 EMail: timbl@w3.org 1954 URI: http://www.w3.org/People/Berners-Lee/ 1955 Yves Lafon (editor) 1956 World Wide Web Consortium 1957 W3C / ERCIM 1958 2004, rte des Lucioles 1959 Sophia-Antipolis, AM 06902 1960 France 1962 EMail: ylafon@w3.org 1963 URI: http://www.raubacapeu.net/people/yves/ 1965 Mark Nottingham (editor) 1967 EMail: mnot@mnot.net 1968 URI: http://www.mnot.net/ 1970 Julian F. Reschke (editor) 1971 greenbytes GmbH 1972 Hafenweg 16 1973 Muenster, NW 48155 1974 Germany 1976 Phone: +49 251 2807760 1977 Fax: +49 251 2807761 1978 EMail: julian.reschke@greenbytes.de 1979 URI: http://greenbytes.de/tech/webdav/