idnits 2.17.1 draft-ietf-httpbis-p6-cache-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) 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 9, 2009) is 5498 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-8859-1' == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-06 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-06 == Outdated reference: A later version (-20) exists of draft-ietf-httpbis-p3-payload-06 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-06 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-06 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-06 -- 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) Summary: 1 error (**), 0 flaws (~~), 7 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 Day Software 4 Obsoletes: 2616 (if approved) J. Gettys 5 Intended status: Standards Track One Laptop per Child 6 Expires: September 10, 2009 J. Mogul 7 HP 8 H. Frystyk 9 Microsoft 10 L. Masinter 11 Adobe Systems 12 P. Leach 13 Microsoft 14 T. Berners-Lee 15 W3C/MIT 16 Y. Lafon, Ed. 17 W3C 18 J. Reschke, Ed. 19 greenbytes 20 March 9, 2009 22 HTTP/1.1, part 6: Caching 23 draft-ietf-httpbis-p6-cache-06 25 Status of this Memo 27 This Internet-Draft is submitted to IETF in full conformance with the 28 provisions of BCP 78 and BCP 79. This document may contain material 29 from IETF Documents or IETF Contributions published or made publicly 30 available before November 10, 2008. The person(s) controlling the 31 copyright in some of this material may not have granted the IETF 32 Trust the right to allow modifications of such material outside the 33 IETF Standards Process. Without obtaining an adequate license from 34 the person(s) controlling the copyright in such materials, this 35 document may not be modified outside the IETF Standards Process, and 36 derivative works of it may not be created outside the IETF Standards 37 Process, except to format it for publication as an RFC or to 38 translate it into languages other than English. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF), its areas, and its working groups. Note that 42 other groups may also distribute working documents as Internet- 43 Drafts. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 The list of current Internet-Drafts can be accessed at 50 http://www.ietf.org/ietf/1id-abstracts.txt. 52 The list of Internet-Draft Shadow Directories can be accessed at 53 http://www.ietf.org/shadow.html. 55 This Internet-Draft will expire on September 10, 2009. 57 Copyright Notice 59 Copyright (c) 2009 IETF Trust and the persons identified as the 60 document authors. All rights reserved. 62 This document is subject to BCP 78 and the IETF Trust's Legal 63 Provisions Relating to IETF Documents in effect on the date of 64 publication of this document (http://trustee.ietf.org/license-info). 65 Please review these documents carefully, as they describe your rights 66 and restrictions with respect to this document. 68 Abstract 70 The Hypertext Transfer Protocol (HTTP) is an application-level 71 protocol for distributed, collaborative, hypermedia information 72 systems. This document is Part 6 of the seven-part specification 73 that defines the protocol referred to as "HTTP/1.1" and, taken 74 together, obsoletes RFC 2616. Part 6 defines requirements on HTTP 75 caches and the associated header fields that control cache behavior 76 or indicate cacheable response messages. 78 Editorial Note (To be removed by RFC Editor) 80 Discussion of this draft should take place on the HTTPBIS working 81 group mailing list (ietf-http-wg@w3.org). The current issues list is 82 at and related 83 documents (including fancy diffs) can be found at 84 . 86 The changes in this draft are summarized in Appendix C.7. 88 Table of Contents 90 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 91 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 92 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 93 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 6 94 1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 95 1.4.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 7 96 1.4.2. ABNF Rules defined in other Parts of the 97 Specification . . . . . . . . . . . . . . . . . . . . 7 98 2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 7 99 2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 7 100 2.1.1. Storing Partial and Incomplete Responses . . . . . . . 8 101 2.2. Constructing Responses from Caches . . . . . . . . . . . . 8 102 2.3. Freshness Model . . . . . . . . . . . . . . . . . . . . . 9 103 2.3.1. Calculating Freshness Lifetime . . . . . . . . . . . . 10 104 2.3.2. Calculating Age . . . . . . . . . . . . . . . . . . . 11 105 2.3.3. Serving Stale Responses . . . . . . . . . . . . . . . 13 106 2.4. Validation Model . . . . . . . . . . . . . . . . . . . . . 13 107 2.5. Request Methods that Invalidate . . . . . . . . . . . . . 14 108 2.6. Caching Negotiated Responses . . . . . . . . . . . . . . . 15 109 2.7. Combining Responses . . . . . . . . . . . . . . . . . . . 16 110 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 16 111 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 112 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 17 113 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 18 114 3.2.2. Response Cache-Control Directives . . . . . . . . . . 20 115 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 22 116 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 23 117 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 23 118 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 119 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 25 120 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 28 121 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 122 5.1. Message Header Registration . . . . . . . . . . . . . . . 28 123 6. Security Considerations . . . . . . . . . . . . . . . . . . . 29 124 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29 125 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 126 8.1. Normative References . . . . . . . . . . . . . . . . . . . 29 127 8.2. Informative References . . . . . . . . . . . . . . . . . . 30 128 Appendix A. Compatibility with Previous Versions . . . . . . . . 31 129 A.1. Changes from RFC 2068 . . . . . . . . . . . . . . . . . . 31 130 A.2. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 31 131 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 31 132 Appendix C. Change Log (to be removed by RFC Editor before 133 publication) . . . . . . . . . . . . . . . . . . . . 33 134 C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 33 135 C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 33 136 C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 34 137 C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 34 138 C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 34 139 C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 35 140 C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 35 141 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 142 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38 144 1. Introduction 146 HTTP is typically used for distributed information systems, where 147 performance can be improved by the use of response caches. This 148 document defines aspects of HTTP/1.1 related to caching and reusing 149 response messages. 151 1.1. Purpose 153 An HTTP cache is a local store of response messages and the subsystem 154 that controls its message storage, retrieval, and deletion. A cache 155 stores cacheable responses in order to reduce the response time and 156 network bandwidth consumption on future, equivalent requests. Any 157 client or server may include a cache, though a cache cannot be used 158 by a server that is acting as a tunnel. 160 Caching would be useless if it did not significantly improve 161 performance. The goal of caching in HTTP/1.1 is to reuse a prior 162 response message to satisfy a current request. In some cases, a 163 stored response can be reused without the need for a network request, 164 reducing latency and network round-trips; a "freshness" mechanism is 165 used for this purpose (see Section 2.3). Even when a new request is 166 required, it is often possible to reuse all or parts of the payload 167 of a prior response to satisfy the request, thereby reducing network 168 bandwidth usage; a "validation" mechanism is used for this purpose 169 (see Section 2.4). 171 1.2. Terminology 173 This specification uses a number of terms to refer to the roles 174 played by participants in, and objects of, HTTP caching. 176 cacheable 178 A response is cacheable if a cache is allowed to store a copy of 179 the response message for use in answering subsequent requests. 180 Even when a response is cacheable, there may be additional 181 constraints on whether a cache can use the cached copy to satisfy 182 a particular request. 184 explicit expiration time 186 The time at which the origin server intends that an entity should 187 no longer be returned by a cache without further validation. 189 heuristic expiration time 191 An expiration time assigned by a cache when no explicit expiration 192 time is available. 194 age 196 The age of a response is the time since it was sent by, or 197 successfully validated with, the origin server. 199 first-hand 201 A response is first-hand if the freshness model is not in use; 202 i.e., its age is 0. 204 freshness lifetime 206 The length of time between the generation of a response and its 207 expiration time. 209 fresh 211 A response is fresh if its age has not yet exceeded its freshness 212 lifetime. 214 stale 216 A response is stale if its age has passed its freshness lifetime 217 (either explicit or heuristic). 219 validator 221 A protocol element (e.g., an entity tag or a Last-Modified time) 222 that is used to find out whether a stored response is an 223 equivalent copy of an entity. 225 shared cache 227 A cache that is accessible to more than one user. A non-shared 228 cache is dedicated to a single user. 230 1.3. Requirements 232 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 233 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 234 document are to be interpreted as described in [RFC2119]. 236 An implementation is not compliant if it fails to satisfy one or more 237 of the MUST or REQUIRED level requirements for the protocols it 238 implements. An implementation that satisfies all the MUST or 239 REQUIRED level and all the SHOULD level requirements for its 240 protocols is said to be "unconditionally compliant"; one that 241 satisfies all the MUST level requirements but not all the SHOULD 242 level requirements for its protocols is said to be "conditionally 243 compliant." 245 1.4. Syntax Notation 247 This specification uses the ABNF syntax defined in Section 1.2 of 248 [Part1] (which extends the syntax defined in [RFC5234] with a list 249 rule). Appendix B shows the collected ABNF, with the list rule 250 expanded. 252 The following core rules are included by reference, as defined in 253 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 254 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 255 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 256 sequence of data), SP (space), VCHAR (any visible USASCII character), 257 and WSP (whitespace). 259 1.4.1. Core Rules 261 The core rules below are defined in Section 1.2.2 of [Part1]: 263 quoted-string = 264 token = 265 OWS = 267 1.4.2. ABNF Rules defined in other Parts of the Specification 269 The ABNF rules below are defined in other parts: 271 field-name = 272 HTTP-date = 273 port = 274 pseudonym = 275 uri-host = 277 2. Cache Operation 279 2.1. Response Cacheability 281 A cache MUST NOT store a response to any request, unless: 283 o The request method is defined as being cacheable, and 285 o the "no-store" cache directive (see Section 3.2) does not appear 286 in request or response headers, and 288 o the "private" cache response directive (see Section 3.2 does not 289 appear in the response, if the cache is shared, and 291 o the "Authorization" header (see Section 3.1 of [Part7]) does not 292 appear in the request, if the cache is shared (unless the "public" 293 directive is present; see Section 3.2), and 295 o the cache understands partial responses, if the response is 296 partial or incomplete (see Section 2.1.1). 298 Note that in normal operation, most caches will not store a response 299 that has neither a cache validator nor an explicit expiration time, 300 as such responses are not usually useful to store. However, caches 301 are not prohibited from storing such responses. 303 2.1.1. Storing Partial and Incomplete Responses 305 A cache that receives an incomplete response (for example, with fewer 306 bytes of data than specified in a Content-Length header) can store 307 the response, but MUST treat it as a partial response [Part5]. 308 Partial responses can be combined as described in Section 4 of 309 [Part5]; the result might be a full response or might still be 310 partial. A cache MUST NOT return a partial response to a client 311 without explicitly marking it as such using the 206 (Partial Content) 312 status code. 314 A cache that does not support the Range and Content-Range headers 315 MUST NOT store incomplete or partial responses. 317 2.2. Constructing Responses from Caches 319 For a presented request, a cache MUST NOT return a stored response, 320 unless: 322 o The presented Request-URI and that of the stored response match 323 (see [[anchor1: TBD]]), and 325 o the request method associated with the stored response allows it 326 to be used for the presented request, and 328 o selecting request-headers nominated by the stored response (if 329 any) match those presented (see Section 2.6), and 331 o the presented request and stored response are free from directives 332 that would prevent its use (see Section 3.2 and Section 3.4), and 334 o the stored response is either: 336 * fresh (see Section 2.3), or 338 * allowed to be served stale (see Section 2.3.3), or 340 * successfully validated (see Section 2.4). 342 [[anchor2: TODO: define method cacheability for GET, HEAD and POST in 343 p2-semantics.]] 345 When a stored response is used to satisfy a request, caches MUST 346 include a single Age header field Section 3.1 in the response with a 347 value equal to the stored response's current_age; see Section 2.3.2. 348 [[anchor3: DISCUSS: this currently includes successfully validated 349 responses.]] 351 Requests with methods that are unsafe (Section 7.1.1 of [Part2]) MUST 352 be written through the cache to the origin server; i.e., A cache must 353 not reply to such a request before having forwarded the request and 354 having received a corresponding response. 356 Also, note that unsafe requests might invalidate already stored 357 responses; see Section 2.5. 359 Caches MUST use the most recent response (as determined by the Date 360 header) when more than one suitable response is stored. They can 361 also forward a request with "Cache-Control: max-age=0" or "Cache- 362 Control: no-cache" to disambiguate which response to use. 364 [[anchor4: TODO: end-to-end and hop-by-hop headers, non-modifiable 365 headers removed; re-spec in p1]] 367 2.3. Freshness Model 369 When a response is "fresh" in the cache, it can be used to satisfy 370 subsequent requests without contacting the origin server, thereby 371 improving efficiency. 373 The primary mechanism for determining freshness is for an origin 374 server to provide an explicit expiration time in the future, using 375 either the Expires header (Section 3.3) or the max-age response cache 376 directive (Section 3.2.2). Generally, origin servers will assign 377 future explicit expiration times to responses in the belief that the 378 entity is not likely to change in a semantically significant way 379 before the expiration time is reached. 381 If an origin server wishes to force a cache to validate every 382 request, it can assign an explicit expiration time in the past. This 383 means that the response is always stale, so that caches should 384 validate it before using it for subsequent requests. [[anchor5: This 385 wording may cause confusion, because the response may still be served 386 stale.]] 388 Since origin servers do not always provide explicit expiration times, 389 HTTP caches may also assign heuristic expiration times when they are 390 not specified, employing algorithms that use other header values 391 (such as the Last-Modified time) to estimate a plausible expiration 392 time. The HTTP/1.1 specification does not provide specific 393 algorithms, but does impose worst-case constraints on their results. 395 The calculation to determine if a response is fresh is: 397 response_is_fresh = (freshness_lifetime > current_age) 399 The freshness_lifetime is defined in Section 2.3.1; the current_age 400 is defined in Section 2.3.2. 402 Additionally, clients may need to influence freshness calculation. 403 They can do this using several request cache directives, with the 404 effect of either increasing or loosening constraints on freshness. 405 See Section 3.2.1. 407 [[anchor6: ISSUE: there are not requirements directly applying to 408 cache-request-directives and freshness.]] 410 Note that freshness applies only to cache operation; it cannot be 411 used to force a user agent to refresh its display or reload a 412 resource. See Section 4 for an explanation of the difference between 413 caches and history mechanisms. 415 2.3.1. Calculating Freshness Lifetime 417 A cache can calculate the freshness lifetime (denoted as 418 freshness_lifetime) of a response by using the first match of: 420 o If the cache is shared and the s-maxage response cache directive 421 (Section 3.2.2) is present, use its value, or 423 o If the max-age response cache directive (Section 3.2.2) is 424 present, use its value, or 426 o If the Expires response header (Section 3.3) is present, use its 427 value minus the value of the Date response header, or 429 o Otherwise, no explicit expiration time is present in the response, 430 but a heuristic may be used; see Section 2.3.1.1. 432 Note that this calculation is not vulnerable to clock skew, since all 433 of the information comes from the origin server. 435 2.3.1.1. Calculating Heuristic Freshness 437 If no explicit expiration time is present in a stored response that 438 has a status code of 200, 203, 206, 300, 301 or 410, a heuristic 439 expiration time can be calculated. Heuristics MUST NOT be used for 440 other response status codes. 442 When a heuristic is used to calculate freshness lifetime, the cache 443 SHOULD attach a Warning header with a 113 warn-code to the response 444 if its current_age is more than 24 hours and such a warning is not 445 already present. 447 Also, if the response has a Last-Modified header (Section 6.6 of 448 [Part4]), the heuristic expiration value SHOULD be no more than some 449 fraction of the interval since that time. A typical setting of this 450 fraction might be 10%. 452 [[anchor7: REVIEW: took away HTTP/1.0 query string heuristic 453 uncacheability.]] 455 2.3.2. Calculating Age 457 HTTP/1.1 uses the Age response-header to convey the estimated age of 458 the response message when obtained from a cache. The Age field value 459 is the cache's estimate of the amount of time since the response was 460 generated or validated by the origin server. In essence, the Age 461 value is the sum of the time that the response has been resident in 462 each of the caches along the path from the origin server, plus the 463 amount of time it has been in transit along network paths. 465 The term "age_value" denotes the value of the Age header, in a form 466 appropriate for arithmetic operations. 468 HTTP/1.1 requires origin servers to send a Date header, if possible, 469 with every response, giving the time at which the response was 470 generated (see Section 8.3 of [Part1]). The term "date_value" 471 denotes the value of the Date header, in a form appropriate for 472 arithmetic operations. 474 The term "now" means "the current value of the clock at the host 475 performing the calculation." Hosts that use HTTP, but especially 476 hosts running origin servers and caches, SHOULD use NTP [RFC1305] or 477 some similar protocol to synchronize their clocks to a globally 478 accurate time standard. 480 A response's age can be calculated in two entirely independent ways: 482 1. now minus date_value, if the local clock is reasonably well 483 synchronized to the origin server's clock. If the result is 484 negative, the result is replaced by zero. 486 2. age_value, if all of the caches along the response path implement 487 HTTP/1.1. 489 These are combined as 491 corrected_received_age = max(now - date_value, age_value) 493 When an Age value is received, it MUST be interpreted relative to the 494 time the request was initiated, not the time that the response was 495 received. 497 corrected_initial_age = corrected_received_age 498 + (now - request_time) 500 where "request_time" is the time (according to the local clock) when 501 the request that elicited this response was sent. 503 The current_age of a stored response can then be calculated by adding 504 the amount of time (in seconds) since the stored response was last 505 validated by the origin server to the corrected_initial_age. 507 In summary: 509 age_value - Age header field-value received with the response 510 date_value - Date header field-value received with the response 511 request_time - local time when the cache made the request 512 resulting in the stored response 513 response_time - local time when the cache received the response 514 now - current local time 516 apparent_age = max(0, response_time - date_value); 517 corrected_received_age = max(apparent_age, age_value); 518 response_delay = response_time - request_time; 519 corrected_initial_age = corrected_received_age + response_delay; 520 resident_time = now - response_time; 521 current_age = corrected_initial_age + resident_time; 523 2.3.3. Serving Stale Responses 525 A "stale" response is one that either has explicit expiry 526 information, or is allowed to have heuristic expiry calculated, but 527 is not fresh according to the calculations in Section 2.3. 529 Caches MUST NOT return a stale response if it is prohibited by an 530 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" 531 cache directive, a "must-revalidate" cache-response-directive, or an 532 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 533 see Section 3.2.2). 535 Caches SHOULD NOT return stale responses unless they are disconnected 536 (i.e., it cannot contact the origin server or otherwise find a 537 forward path) or otherwise explicitly allowed (e.g., the max-stale 538 request directive; see Section 3.2.1). 540 Stale responses SHOULD have a Warning header with the 110 warn-code 541 (see Section 3.6). Likewise, the 112 warn-code SHOULD be sent on 542 stale responses if the cache is disconnected. 544 If a cache receives a first-hand response (either an entire response, 545 or a 304 (Not Modified) response) that it would normally forward to 546 the requesting client, and the received response is no longer fresh, 547 the cache SHOULD forward it to the requesting client without adding a 548 new Warning (but without removing any existing Warning headers). A 549 cache SHOULD NOT attempt to validate a response simply because that 550 response became stale in transit. 552 2.4. Validation Model 554 Checking with the origin server to see if a stale or otherwise 555 unusable cached response can be reused is called "validating" or 556 "revalidating." Doing so potentially avoids the overhead of 557 retransmitting the response body when the stored response is valid. 559 HTTP's conditional request mechanism [Part4] is used for this 560 purpose. When a stored response includes one or more validators, 561 such as the field values of an ETag or Last-Modified header field, 562 then a validating request SHOULD be made conditional to those field 563 values. 565 A 304 (Not Modified) response status code indicates that the stored 566 response can be updated and reused; see Section 2.7. 568 If instead the cache receives a full response (i.e., one with a 569 response body), it is used to satisfy the request and replace the 570 stored response. [[anchor8: Should there be a requirement here?]] 571 If a cache receives a 5xx response while attempting to validate a 572 response, it MAY either forward this response to the requesting 573 client, or act as if the server failed to respond. In the latter 574 case, it MAY return a previously stored response (which SHOULD 575 include the 111 warn-code; see Section 3.6) unless the stored 576 response includes the "must-revalidate" cache directive (see 577 Section 2.3.3). 579 2.5. Request Methods that Invalidate 581 Because unsafe methods (Section 7.1.1 of [Part2]) have the potential 582 for changing state on the origin server, intervening caches can use 583 them to keep their contents up-to-date. 585 The following HTTP methods MUST cause a cache to invalidate the 586 Request-URI as well as the Location and Content-Location headers (if 587 present): 589 o PUT 591 o DELETE 593 o POST 595 An invalidation based on the URI in a Location or Content-Location 596 header MUST NOT be performed if the host part of that URI differs 597 from the host part in the Request-URI. This helps prevent denial of 598 service attacks. 600 [[anchor9: TODO: "host part" needs to be specified better.]] 602 A cache that passes through requests for methods it does not 603 understand SHOULD invalidate the Request-URI. 605 Here, "invalidate" means that the cache will either remove all stored 606 responses related to the Request-URI, or will mark these as "invalid" 607 and in need of a mandatory validation before they can be returned in 608 response to a subsequent request. 610 Note that this does not guarantee that all appropriate responses are 611 invalidated. For example, the request that caused the change at the 612 origin server might not have gone through the cache where a response 613 is stored. 615 [[anchor10: TODO: specify that only successful (2xx, 3xx?) responses 616 invalidate.]] 618 2.6. Caching Negotiated Responses 620 Use of server-driven content negotiation (Section 4.1 of [Part3]) 621 alters the conditions under which a cache can use the response for 622 subsequent requests. 624 When a cache receives a request that can be satisfied by a stored 625 response that includes a Vary header field (Section 3.5), it MUST NOT 626 use that response unless all of the selecting request-headers in the 627 presented request match the corresponding stored request-headers from 628 the original request. 630 The selecting request-headers from two requests are defined to match 631 if and only if the selecting request-headers in the first request can 632 be transformed to the selecting request-headers in the second request 633 by adding or removing linear white space [[anchor11: [ref]]] at 634 places where this is allowed by the corresponding ABNF, and/or 635 combining multiple message-header fields with the same field name 636 following the rules about message headers in Section 4.2 of [Part1]. 637 [[anchor12: DISCUSS: header-specific canonicalisation]] 639 A Vary header field-value of "*" always fails to match, and 640 subsequent requests to that resource can only be properly interpreted 641 by the origin server. 643 If no stored response matches, the cache MAY forward the presented 644 request to the origin server in a conditional request, and SHOULD 645 include all ETags stored with potentially suitable responses in an 646 If-None-Match request header. If the server responds with 304 (Not 647 Modified) and includes an entity tag or Content-Location that 648 indicates the entity to be used, that cached response MUST be used to 649 satisfy the presented request, and SHOULD be used to update the 650 corresponding stored response; see Section 2.7. 652 If any of the stored responses contains only partial content, its 653 entity-tag SHOULD NOT be included in the If-None-Match header field 654 unless the request is for a range that would be fully satisfied by 655 that stored response. 657 If a cache receives a successful response whose Content-Location 658 field matches that of an existing stored response for the same 659 Request-URI, whose entity-tag differs from that of the existing 660 stored response, and whose Date is more recent than that of the 661 existing response, the existing response SHOULD NOT be returned in 662 response to future requests and SHOULD be deleted from the 663 cache.[[anchor13: DISCUSS: Not sure if this is necessary.]] 665 2.7. Combining Responses 667 When a cache receives a 304 (Not Modified) response or a 206 (Partial 668 Content) response, it needs to update the stored response with the 669 new one, so that the updated response can be sent to the client. 671 If the status code is 304 (Not Modified), the cache SHOULD use the 672 stored entity-body as the updated entity-body. If the status code is 673 206 (Partial Content) and the ETag or Last-Modified headers match 674 exactly, the cache MAY combine the stored entity-body in the stored 675 response with the updated entity-body received in the response and 676 use the result as the updated entity-body (see Section 4 of [Part5]). 678 The stored response headers are used for the updated response, except 679 that 681 o any stored Warning headers with warn-code 1xx (see Section 3.6) 682 MUST be deleted from the stored response and the forwarded 683 response. 685 o any stored Warning headers with warn-code 2xx MUST be retained in 686 the stored response and the forwarded response. 688 o any headers provided in the 304 or 206 response MUST replace the 689 corresponding headers from the stored response. 691 A cache MUST also replace any stored headers with corresponding 692 headers received in the incoming response, except for Warning headers 693 as described immediately above. If a header field-name in the 694 incoming response matches more than one header in the stored 695 response, all such old headers MUST be replaced. It MAY store the 696 combined entity-body. 698 [[anchor14: ISSUE: discuss how to handle HEAD updates]] 700 3. Header Field Definitions 702 This section defines the syntax and semantics of HTTP/1.1 header 703 fields related to caching. 705 For entity-header fields, both sender and recipient refer to either 706 the client or the server, depending on who sends and who receives the 707 entity. 709 3.1. Age 711 The response-header field "Age" conveys the sender's estimate of the 712 amount of time since the response (or its validation) was generated 713 at the origin server. Age values are calculated as specified in 714 Section 2.3.2. 716 Age = "Age" ":" OWS Age-v 717 Age-v = delta-seconds 719 Age field-values are non-negative decimal integers, representing time 720 in seconds. 722 delta-seconds = 1*DIGIT 724 If a cache receives a value larger than the largest positive integer 725 it can represent, or if any of its age calculations overflows, it 726 MUST transmit an Age header with a field-value of 2147483648 (2^31). 727 Caches SHOULD use an arithmetic type of at least 31 bits of range. 729 The presence of an Age header field in a response implies that a 730 response is not first-hand. However, the converse is not true, since 731 HTTP/1.0 caches may not implement the Age header field. 733 3.2. Cache-Control 735 The general-header field "Cache-Control" is used to specify 736 directives that MUST be obeyed by all caches along the request/ 737 response chain. The directives specify behavior intended to prevent 738 caches from adversely interfering with the request or response. 739 Cache directives are unidirectional in that the presence of a 740 directive in a request does not imply that the same directive is to 741 be given in the response. 743 Note that HTTP/1.0 caches might not implement Cache-Control and 744 might only implement Pragma: no-cache (see Section 3.4). 746 Cache directives MUST be passed through by a proxy or gateway 747 application, regardless of their significance to that application, 748 since the directives might be applicable to all recipients along the 749 request/response chain. It is not possible to target a directive to 750 a specific cache. 752 Cache-Control = "Cache-Control" ":" OWS Cache-Control-v 753 Cache-Control-v = 1#cache-directive 755 cache-directive = cache-request-directive 756 / cache-response-directive 758 cache-extension = token [ "=" ( token / quoted-string ) ] 760 3.2.1. Request Cache-Control Directives 762 cache-request-directive = 763 "no-cache" 764 / "no-store" 765 / "max-age" "=" delta-seconds 766 / "max-stale" [ "=" delta-seconds ] 767 / "min-fresh" "=" delta-seconds 768 / "no-transform" 769 / "only-if-cached" 770 / cache-extension 772 no-cache 774 The no-cache request directive indicates that a stored response 775 MUST NOT be used to satisfy the request without successful 776 validation on the origin server. 778 no-store 780 The no-store request directive indicates that a cache MUST NOT 781 store any part of either this request or any response to it. This 782 directive applies to both non-shared and shared caches. "MUST NOT 783 store" in this context means that the cache MUST NOT intentionally 784 store the information in non-volatile storage, and MUST make a 785 best-effort attempt to remove the information from volatile 786 storage as promptly as possible after forwarding it. 788 This directive is NOT a reliable or sufficient mechanism for 789 ensuring privacy. In particular, malicious or compromised caches 790 might not recognize or obey this directive, and communications 791 networks may be vulnerable to eavesdropping. 793 max-age 795 The max-age request directive indicates that the client is willing 796 to accept a response whose age is no greater than the specified 797 time in seconds. Unless max-stale directive is also included, the 798 client is not willing to accept a stale response. 800 max-stale 802 The max-stale request directive indicates that the client is 803 willing to accept a response that has exceeded its expiration 804 time. If max-stale is assigned a value, then the client is 805 willing to accept a response that has exceeded its expiration time 806 by no more than the specified number of seconds. If no value is 807 assigned to max-stale, then the client is willing to accept a 808 stale response of any age. [[anchor15: of any staleness? --mnot]] 810 min-fresh 812 The min-fresh request directive indicates that the client is 813 willing to accept a response whose freshness lifetime is no less 814 than its current age plus the specified time in seconds. That is, 815 the client wants a response that will still be fresh for at least 816 the specified number of seconds. 818 no-transform 820 The no-transform request directive indicates that an intermediate 821 cache or proxy MUST NOT change the Content-Encoding, Content-Range 822 or Content-Type request headers, nor the request entity-body. 824 only-if-cached 826 The only-if-cached request directive indicates that the client 827 only wishes to return a stored response. If it receives this 828 directive, a cache SHOULD either respond using a stored response 829 that is consistent with the other constraints of the request, or 830 respond with a 504 (Gateway Timeout) status. If a group of caches 831 is being operated as a unified system with good internal 832 connectivity, such a request MAY be forwarded within that group of 833 caches. 835 3.2.2. Response Cache-Control Directives 837 cache-response-directive = 838 "public" 839 / "private" [ "=" DQUOTE 1#field-name DQUOTE ] 840 / "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] 841 / "no-store" 842 / "no-transform" 843 / "must-revalidate" 844 / "proxy-revalidate" 845 / "max-age" "=" delta-seconds 846 / "s-maxage" "=" delta-seconds 847 / cache-extension 849 public 851 The public response directive indicates that the response MAY be 852 cached, even if it would normally be non-cacheable or cacheable 853 only within a non-shared cache. (See also Authorization, Section 854 3.1 of [Part7], for additional details.) 856 private 858 The private response directive indicates that the response message 859 is intended for a single user and MUST NOT be stored by a shared 860 cache. A private (non-shared) cache MAY store the response. 862 If the private response directive specifies one or more field- 863 names, this requirement is limited to the field-values associated 864 with the listed response headers. That is, the specified field- 865 names(s) MUST NOT be stored by a shared cache, whereas the 866 remainder of the response message MAY be. 868 Note: This usage of the word private only controls where the 869 response may be stored, and cannot ensure the privacy of the 870 message content. 872 no-cache 874 The no-cache response directive indicates that the response MUST 875 NOT be used to satisfy a subsequent request without successful 876 validation on the origin server. This allows an origin server to 877 prevent caching even by caches that have been configured to return 878 stale responses. 880 If the no-cache response directive specifies one or more field- 881 names, this requirement is limited to the field-values assosicated 882 with the listed response headers. That is, the specified field- 883 name(s) MUST NOT be sent in the response to a subsequent request 884 without successful validation on the origin server. This allows 885 an origin server to prevent the re-use of certain header fields in 886 a response, while still allowing caching of the rest of the 887 response. 889 Note: Most HTTP/1.0 caches will not recognize or obey this 890 directive. 892 no-store 894 The no-store response directive indicates that a cache MUST NOT 895 store any part of either the immediate request or response. This 896 directive applies to both non-shared and shared caches. "MUST NOT 897 store" in this context means that the cache MUST NOT intentionally 898 store the information in non-volatile storage, and MUST make a 899 best-effort attempt to remove the information from volatile 900 storage as promptly as possible after forwarding it. 902 This directive is NOT a reliable or sufficient mechanism for 903 ensuring privacy. In particular, malicious or compromised caches 904 might not recognize or obey this directive, and communications 905 networks may be vulnerable to eavesdropping. 907 must-revalidate 909 The must-revalidate response directive indicates that once it has 910 become stale, the response MUST NOT be used to satisfy subsequent 911 requests without successful validation on the origin server. 913 The must-revalidate directive is necessary to support reliable 914 operation for certain protocol features. In all circumstances an 915 HTTP/1.1 cache MUST obey the must-revalidate directive; in 916 particular, if the cache cannot reach the origin server for any 917 reason, it MUST generate a 504 (Gateway Timeout) response. 919 Servers SHOULD send the must-revalidate directive if and only if 920 failure to validate a request on the entity could result in 921 incorrect operation, such as a silently unexecuted financial 922 transaction. 924 proxy-revalidate 926 The proxy-revalidate response directive has the same meaning as 927 the must-revalidate response directive, except that it does not 928 apply to non-shared caches. 930 max-age 931 The max-age response directive indicates that response is to be 932 considered stale after its age is greater than the specified 933 number of seconds. 935 s-maxage 937 The s-maxage response directive indicates that, in shared caches, 938 the maximum age specified by this directive overrides the maximum 939 age specified by either the max-age directive or the Expires 940 header. The s-maxage directive also implies the semantics of the 941 proxy-revalidate response directive. 943 no-transform 945 The no-transform response directive indicates that an intermediate 946 cache or proxy MUST NOT change the Content-Encoding, Content-Range 947 or Content-Type response headers, nor the response entity-body. 949 3.2.3. Cache Control Extensions 951 The Cache-Control header field can be extended through the use of one 952 or more cache-extension tokens, each with an optional value. 953 Informational extensions (those that do not require a change in cache 954 behavior) can be added without changing the semantics of other 955 directives. Behavioral extensions are designed to work by acting as 956 modifiers to the existing base of cache directives. Both the new 957 directive and the standard directive are supplied, such that 958 applications that do not understand the new directive will default to 959 the behavior specified by the standard directive, and those that 960 understand the new directive will recognize it as modifying the 961 requirements associated with the standard directive. In this way, 962 extensions to the cache-control directives can be made without 963 requiring changes to the base protocol. 965 This extension mechanism depends on an HTTP cache obeying all of the 966 cache-control directives defined for its native HTTP-version, obeying 967 certain extensions, and ignoring all directives that it does not 968 understand. 970 For example, consider a hypothetical new response directive called 971 "community" that acts as a modifier to the private directive. We 972 define this new directive to mean that, in addition to any non-shared 973 cache, any cache that is shared only by members of the community 974 named within its value may cache the response. An origin server 975 wishing to allow the UCI community to use an otherwise private 976 response in their shared cache(s) could do so by including 978 Cache-Control: private, community="UCI" 980 A cache seeing this header field will act correctly even if the cache 981 does not understand the community cache-extension, since it will also 982 see and understand the private directive and thus default to the safe 983 behavior. 985 Unrecognized cache directives MUST be ignored; it is assumed that any 986 cache directive likely to be unrecognized by an HTTP/1.1 cache will 987 be combined with standard directives (or the response's default 988 cacheability) such that the cache behavior will remain minimally 989 correct even if the cache does not understand the extension(s). 991 3.3. Expires 993 The entity-header field "Expires" gives the date/time after which the 994 response is considered stale. See Section 2.3 for further discussion 995 of the freshness model. 997 The presence of an Expires field does not imply that the original 998 resource will change or cease to exist at, before, or after that 999 time. 1001 The field-value is an absolute date and time as defined by HTTP-date 1002 in Section 3.2.1 of [Part1]; it MUST be sent in rfc1123-date format. 1004 Expires = "Expires" ":" OWS Expires-v 1005 Expires-v = HTTP-date 1007 For example 1009 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1011 Note: if a response includes a Cache-Control field with the max- 1012 age directive (see Section 3.2.2), that directive overrides the 1013 Expires field. Likewise, the s-maxage directive overrides Expires 1014 in shared caches. 1016 HTTP/1.1 servers SHOULD NOT send Expires dates more than one year in 1017 the future. 1019 HTTP/1.1 clients and caches MUST treat other invalid date formats, 1020 especially including the value "0", as in the past (i.e., "already 1021 expired"). 1023 3.4. Pragma 1025 The general-header field "Pragma" is used to include implementation- 1026 specific directives that might apply to any recipient along the 1027 request/response chain. All pragma directives specify optional 1028 behavior from the viewpoint of the protocol; however, some systems 1029 MAY require that behavior be consistent with the directives. 1031 Pragma = "Pragma" ":" OWS Pragma-v 1032 Pragma-v = 1#pragma-directive 1033 pragma-directive = "no-cache" / extension-pragma 1034 extension-pragma = token [ "=" ( token / quoted-string ) ] 1036 When the no-cache directive is present in a request message, an 1037 application SHOULD forward the request toward the origin server even 1038 if it has a cached copy of what is being requested. This pragma 1039 directive has the same semantics as the no-cache response directive 1040 (see Section 3.2.2) and is defined here for backward compatibility 1041 with HTTP/1.0. Clients SHOULD include both header fields when a no- 1042 cache request is sent to a server not known to be HTTP/1.1 compliant. 1043 HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had 1044 sent "Cache-Control: no-cache". 1046 Note: because the meaning of "Pragma: no-cache" as a response- 1047 header field is not actually specified, it does not provide a 1048 reliable replacement for "Cache-Control: no-cache" in a response. 1050 This mechanism is deprecated; no new Pragma directives will be 1051 defined in HTTP. 1053 3.5. Vary 1055 The "Vary" response-header field's value indicates the set of 1056 request-header fields that determines, while the response is fresh, 1057 whether a cache is permitted to use the response to reply to a 1058 subsequent request without validation; see Section 2.6. 1060 In uncacheable or stale responses, the Vary field value advises the 1061 user agent about the criteria that were used to select the 1062 representation. 1064 Vary = "Vary" ":" OWS Vary-v 1065 Vary-v = "*" / 1#field-name 1067 The set of header fields named by the Vary field value is known as 1068 the selecting request-headers. 1070 Servers SHOULD include a Vary header field with any cacheable 1071 response that is subject to server-driven negotiation. Doing so 1072 allows a cache to properly interpret future requests on that resource 1073 and informs the user agent about the presence of negotiation on that 1074 resource. A server MAY include a Vary header field with a non- 1075 cacheable response that is subject to server-driven negotiation, 1076 since this might provide the user agent with useful information about 1077 the dimensions over which the response varies at the time of the 1078 response. 1080 A Vary field value of "*" signals that unspecified parameters not 1081 limited to the request-headers (e.g., the network address of the 1082 client), play a role in the selection of the response representation; 1083 therefore, a cache cannot determine whether this response is 1084 appropriate. The "*" value MUST NOT be generated by a proxy server; 1085 it may only be generated by an origin server. 1087 The field-names given are not limited to the set of standard request- 1088 header fields defined by this specification. Field names are case- 1089 insensitive. 1091 3.6. Warning 1093 The general-header field "Warning" is used to carry additional 1094 information about the status or transformation of a message that 1095 might not be reflected in the message. This information is typically 1096 used to warn about possible incorrectness introduced by caching 1097 operations or transformations applied to the entity body of the 1098 message. 1100 Warnings can be used for other purposes, both cache-related and 1101 otherwise. The use of a warning, rather than an error status code, 1102 distinguish these responses from true failures. 1104 Warning headers can in general be applied to any message, however 1105 some warn-codes are specific to caches and can only be applied to 1106 response messages. 1108 Warning = "Warning" ":" OWS Warning-v 1109 Warning-v = 1#warning-value 1111 warning-value = warn-code SP warn-agent SP warn-text 1112 [SP warn-date] 1114 warn-code = 3DIGIT 1115 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1116 ; the name or pseudonym of the server adding 1117 ; the Warning header, for use in debugging 1118 warn-text = quoted-string 1119 warn-date = DQUOTE HTTP-date DQUOTE 1121 Multiple warnings can be attached to a response (either by the origin 1122 server or by a cache), including multiple warnings with the same code 1123 number. For example, a server might provide the same warning with 1124 texts in both English and Basque. 1126 When this occurs, the user agent SHOULD inform the user of as many of 1127 them as possible, in the order that they appear in the response. If 1128 it is not possible to inform the user of all of the warnings, the 1129 user agent SHOULD follow these heuristics: 1131 o Warnings that appear early in the response take priority over 1132 those appearing later in the response. 1134 o Warnings in the user's preferred character set take priority over 1135 warnings in other character sets but with identical warn-codes and 1136 warn-agents. 1138 Systems that generate multiple Warning headers SHOULD order them with 1139 this user agent behavior in mind. New Warning headers SHOULD be 1140 added after any existing Warning headers. 1142 Warnings are assigned three digit warn-codes. The first digit 1143 indicates whether the Warning is required to be deleted from a stored 1144 response after validation: 1146 o 1xx Warnings that describe the freshness or validation status of 1147 the response, and so MUST be deleted by caches after validation. 1148 They MUST NOT be generated by a cache except when validating a 1149 cached entry, and MUST NOT be generated by clients. 1151 o 2xx Warnings that describe some aspect of the entity body or 1152 entity headers that is not rectified by a validation (for example, 1153 a lossy compression of the entity bodies) and MUST NOT be deleted 1154 by caches after validation, unless a full response is returned, in 1155 which case they MUST be. 1157 The warn-text SHOULD be in a natural language and character set that 1158 is most likely to be intelligible to the human user receiving the 1159 response. This decision can be based on any available knowledge, 1160 such as the location of the cache or user, the Accept-Language field 1161 in a request, the Content-Language field in a response, etc. The 1162 default language is English and the default character set is ISO- 1163 8859-1 ([ISO-8859-1]). 1165 If a character set other than ISO-8859-1 is used, it MUST be encoded 1166 in the warn-text using the method described in [RFC2047]. 1168 If an implementation sends a message with one or more Warning headers 1169 to a receiver whose version is HTTP/1.0 or lower, then the sender 1170 MUST include in each warning-value a warn-date that matches the Date 1171 header in the message. 1173 If an implementation receives a message with a warning-value that 1174 includes a warn-date, and that warn-date is different from the Date 1175 value in the response, then that warning-value MUST be deleted from 1176 the message before storing, forwarding, or using it. (preventing the 1177 consequences of naive caching of Warning header fields.) If all of 1178 the warning-values are deleted for this reason, the Warning header 1179 MUST be deleted as well. 1181 The following warn-codes are defined by this specification, each with 1182 a recommended warn-text in English, and a description of its meaning. 1184 110 Response is stale 1186 SHOULD be included whenever the returned response is stale. 1188 111 Revalidation failed 1190 SHOULD be included if a cache returns a stale response because an 1191 attempt to validate the response failed, due to an inability to 1192 reach the server. 1194 112 Disconnected operation 1196 SHOULD be included if the cache is intentionally disconnected from 1197 the rest of the network for a period of time. 1199 113 Heuristic expiration 1201 SHOULD be included if the cache heuristically chose a freshness 1202 lifetime greater than 24 hours and the response's age is greater 1203 than 24 hours. 1205 199 Miscellaneous warning 1207 The warning text can include arbitrary information to be presented 1208 to a human user, or logged. A system receiving this warning MUST 1209 NOT take any automated action, besides presenting the warning to 1210 the user. 1212 214 Transformation applied 1214 MUST be added by an intermediate cache or proxy if it applies any 1215 transformation changing the content-coding (as specified in the 1216 Content-Encoding header) or media-type (as specified in the 1217 Content-Type header) of the response, or the entity-body of the 1218 response, unless this Warning code already appears in the 1219 response. 1221 299 Miscellaneous persistent warning 1223 The warning text can include arbitrary information to be presented 1224 to a human user, or logged. A system receiving this warning MUST 1225 NOT take any automated action. 1227 4. History Lists 1229 User agents often have history mechanisms, such as "Back" buttons and 1230 history lists, that can be used to redisplay an entity retrieved 1231 earlier in a session. 1233 History mechanisms and caches are different. In particular history 1234 mechanisms SHOULD NOT try to show a correct view of the current state 1235 of a resource. Rather, a history mechanism is meant to show exactly 1236 what the user saw at the time when the resource was retrieved. 1238 By default, an expiration time does not apply to history mechanisms. 1239 If the entity is still in storage, a history mechanism SHOULD display 1240 it even if the entity has expired, unless the user has specifically 1241 configured the agent to refresh expired history documents. 1243 This is not to be construed to prohibit the history mechanism from 1244 telling the user that a view might be stale. 1246 Note: if history list mechanisms unnecessarily prevent users from 1247 viewing stale resources, this will tend to force service authors 1248 to avoid using HTTP expiration controls and cache controls when 1249 they would otherwise like to. Service authors may consider it 1250 important that users not be presented with error messages or 1251 warning messages when they use navigation controls (such as BACK) 1252 to view previously fetched resources. Even though sometimes such 1253 resources ought not be cached, or ought to expire quickly, user 1254 interface considerations may force service authors to resort to 1255 other means of preventing caching (e.g. "once-only" URLs) in order 1256 not to suffer the effects of improperly functioning history 1257 mechanisms. 1259 5. IANA Considerations 1261 5.1. Message Header Registration 1263 The Message Header Registry located at should be 1265 updated with the permanent registrations below (see [RFC3864]): 1267 +-------------------+----------+----------+-------------+ 1268 | Header Field Name | Protocol | Status | Reference | 1269 +-------------------+----------+----------+-------------+ 1270 | Age | http | standard | Section 3.1 | 1271 | Cache-Control | http | standard | Section 3.2 | 1272 | Expires | http | standard | Section 3.3 | 1273 | Pragma | http | standard | Section 3.4 | 1274 | Vary | http | standard | Section 3.5 | 1275 | Warning | http | standard | Section 3.6 | 1276 +-------------------+----------+----------+-------------+ 1278 The change controller is: "IETF (iesg@ietf.org) - Internet 1279 Engineering Task Force". 1281 6. Security Considerations 1283 Caches expose additional potential vulnerabilities, since the 1284 contents of the cache represent an attractive target for malicious 1285 exploitation. Because cache contents persist after an HTTP request 1286 is complete, an attack on the cache can reveal information long after 1287 a user believes that the information has been removed from the 1288 network. Therefore, cache contents should be protected as sensitive 1289 information. 1291 7. Acknowledgments 1293 Much of the content and presentation of the caching design is due to 1294 suggestions and comments from individuals including: Shel Kaphan, 1295 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 1297 8. References 1299 8.1. Normative References 1301 [ISO-8859-1] 1302 International Organization for Standardization, 1303 "Information technology -- 8-bit single-byte coded graphic 1304 character sets -- Part 1: Latin alphabet No. 1", ISO/ 1305 IEC 8859-1:1998, 1998. 1307 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1308 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1309 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 1310 and Message Parsing", draft-ietf-httpbis-p1-messaging-06 1311 (work in progress), March 2009. 1313 [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1314 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1315 and J. Reschke, Ed., "HTTP/1.1, part 2: Message 1316 Semantics", draft-ietf-httpbis-p2-semantics-06 (work in 1317 progress), March 2009. 1319 [Part3] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1320 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1321 and J. Reschke, Ed., "HTTP/1.1, part 3: Message Payload 1322 and Content Negotiation", draft-ietf-httpbis-p3-payload-06 1323 (work in progress), March 2009. 1325 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1326 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1327 and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional 1328 Requests", draft-ietf-httpbis-p4-conditional-06 (work in 1329 progress), March 2009. 1331 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1332 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1333 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 1334 Partial Responses", draft-ietf-httpbis-p5-range-06 (work 1335 in progress), March 2009. 1337 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1338 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1339 and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", 1340 draft-ietf-httpbis-p7-auth-06 (work in progress), 1341 March 2009. 1343 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 1344 Part Three: Message Header Extensions for Non-ASCII Text", 1345 RFC 2047, November 1996. 1347 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1348 Requirement Levels", BCP 14, RFC 2119, March 1997. 1350 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1351 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1353 8.2. Informative References 1355 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1356 Specification, Implementation", RFC 1305, March 1992. 1358 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1359 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1360 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1362 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1363 Procedures for Message Header Fields", BCP 90, RFC 3864, 1364 September 2004. 1366 Appendix A. Compatibility with Previous Versions 1368 A.1. Changes from RFC 2068 1370 A case was missed in the Cache-Control model of HTTP/1.1; s-maxage 1371 was introduced to add this missing case. (Sections 2.1, 3.2). 1373 Transfer-coding and message lengths all interact in ways that 1374 required fixing exactly when chunked encoding is used (to allow for 1375 transfer encoding that may not be self delimiting); it was important 1376 to straighten out exactly how message lengths are computed. (see also 1377 [Part1], [Part3] and [Part5]) [[anchor18: This used to refer to the 1378 text about non-modifiable headers, and will have to be updated later 1379 on. --jre]] 1381 Proxies should be able to add Content-Length when appropriate. 1382 [[anchor19: This used to refer to the text about non-modifiable 1383 headers, and will have to be updated later on. --jre]] 1385 Range request responses would become very verbose if all meta-data 1386 were always returned; by allowing the server to only send needed 1387 headers in a 206 response, this problem can be avoided. 1388 (Section 2.7) 1390 The Cache-Control: max-age directive was not properly defined for 1391 responses. (Section 3.2.2) 1393 Warnings could be cached incorrectly, or not updated appropriately. 1394 (Section 2.3, 2.7, 3.2, and 3.6) Warning also needed to be a general 1395 header, as PUT or other methods may have need for it in requests. 1397 A.2. Changes from RFC 2616 1399 Clarify denial of service attack avoidance requirement. 1400 (Section 2.5) 1402 Appendix B. Collected ABNF 1404 Age = "Age:" OWS Age-v 1405 Age-v = delta-seconds 1407 Cache-Control = "Cache-Control:" OWS Cache-Control-v 1408 Cache-Control-v = *( "," OWS ) cache-directive *( OWS "," [ OWS 1409 cache-directive ] ) 1411 Expires = "Expires:" OWS Expires-v 1412 Expires-v = HTTP-date 1414 HTTP-date = 1416 OWS = 1418 Pragma = "Pragma:" OWS Pragma-v 1419 Pragma-v = *( "," OWS ) pragma-directive *( OWS "," [ OWS 1420 pragma-directive ] ) 1422 Vary = "Vary:" OWS Vary-v 1423 Vary-v = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name 1424 ] ) ) 1426 Warning = "Warning:" OWS Warning-v 1427 Warning-v = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value 1428 ] ) 1430 cache-directive = cache-request-directive / cache-response-directive 1431 cache-extension = token [ "=" ( token / quoted-string ) ] 1432 cache-request-directive = "no-cache" / "no-store" / ( "max-age=" 1433 delta-seconds ) / ( "max-stale" [ "=" delta-seconds ] ) / ( 1434 "min-fresh=" delta-seconds ) / "no-transform" / "only-if-cached" / 1435 cache-extension 1436 cache-response-directive = "public" / ( "private" [ "=" DQUOTE *( "," 1437 OWS ) field-name *( OWS "," [ OWS field-name ] ) DQUOTE ] ) / ( 1438 "no-cache" [ "=" DQUOTE *( "," OWS ) field-name *( OWS "," [ OWS 1439 field-name ] ) DQUOTE ] ) / "no-store" / "no-transform" / 1440 "must-revalidate" / "proxy-revalidate" / ( "max-age=" delta-seconds 1441 ) / ( "s-maxage=" delta-seconds ) / cache-extension 1443 delta-seconds = 1*DIGIT 1445 extension-pragma = token [ "=" ( token / quoted-string ) ] 1447 field-name = 1449 port = 1450 pragma-directive = "no-cache" / extension-pragma 1451 pseudonym = 1453 quoted-string = 1455 token = 1456 uri-host = 1458 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1459 warn-code = 3DIGIT 1460 warn-date = DQUOTE HTTP-date DQUOTE 1461 warn-text = quoted-string 1462 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date 1463 ] 1465 ABNF diagnostics: 1467 ; Age defined but not used 1468 ; Cache-Control defined but not used 1469 ; Expires defined but not used 1470 ; Pragma defined but not used 1471 ; Vary defined but not used 1472 ; Warning defined but not used 1474 Appendix C. Change Log (to be removed by RFC Editor before publication) 1476 C.1. Since RFC2616 1478 Extracted relevant partitions from [RFC2616]. 1480 C.2. Since draft-ietf-httpbis-p6-cache-00 1482 Closed issues: 1484 o : "Trailer" 1485 () 1487 o : "Invalidation 1488 after Update or Delete" 1489 () 1491 o : "Normative and 1492 Informative references" 1494 o : "Date reference 1495 typo" 1497 o : "Connection 1498 header text" 1500 o : "Informative 1501 references" 1503 o : "ISO-8859-1 1504 Reference" 1506 o : "Normative up- 1507 to-date references" 1509 o : "typo in 1510 13.2.2" 1512 Other changes: 1514 o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress 1515 on ) 1517 C.3. Since draft-ietf-httpbis-p6-cache-01 1519 Closed issues: 1521 o : "rel_path not 1522 used" 1524 Other changes: 1526 o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work 1527 in progress on ) 1529 o Add explicit references to BNF syntax and rules imported from 1530 other parts of the specification. 1532 C.4. Since draft-ietf-httpbis-p6-cache-02 1534 Ongoing work on IANA Message Header Registration 1535 (): 1537 o Reference RFC 3984, and update header registrations for headers 1538 defined in this document. 1540 C.5. Since draft-ietf-httpbis-p6-cache-03 1542 Closed issues: 1544 o : "Vary header 1545 classification" 1547 C.6. Since draft-ietf-httpbis-p6-cache-04 1549 Ongoing work on ABNF conversion 1550 (): 1552 o Use "/" instead of "|" for alternatives. 1554 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1555 whitespace ("OWS") and required whitespace ("RWS"). 1557 o Rewrite ABNFs to spell out whitespace rules, factor out header 1558 value format definitions. 1560 C.7. Since draft-ietf-httpbis-p6-cache-05 1562 This is a total rewrite of this part of the specification. 1564 Affected issues: 1566 o : "Definition of 1567 1xx Warn-Codes" 1569 o : "Placement 1570 of 13.5.1 and 13.5.2" 1572 o : "The role 1573 of Warning and Semantic Transparency in Caching" 1575 o : "Methods 1576 and Caching" 1578 In addition: Final work on ABNF conversion 1579 (): 1581 o Add appendix containing collected and expanded ABNF, reorganize 1582 ABNF introduction. 1584 Index 1586 A 1587 age 6 1588 Age header 17 1590 C 1591 cache 5 1592 Cache Directives 1593 max-age 18, 21 1594 max-stale 19 1595 min-fresh 19 1596 must-revalidate 21 1597 no-cache 18, 20 1598 no-store 18, 21 1599 no-transform 19, 22 1600 only-if-cached 19 1601 private 20 1602 proxy-revalidate 21 1603 public 20 1604 s-maxage 22 1605 Cache-Control header 17 1606 cacheable 5 1608 E 1609 Expires header 23 1610 explicit expiration time 5 1612 F 1613 first-hand 6 1614 fresh 6 1615 freshness lifetime 6 1617 G 1618 Grammar 1619 Age 17 1620 Age-v 17 1621 Cache-Control 18 1622 Cache-Control-v 18 1623 cache-extension 18 1624 cache-request-directive 18 1625 cache-response-directive 20 1626 delta-seconds 17 1627 Expires 23 1628 Expires-v 23 1629 extension-pragma 24 1630 Pragma 24 1631 pragma-directive 24 1632 Pragma-v 24 1633 Vary 24 1634 Vary-v 24 1635 warn-agent 25 1636 warn-code 25 1637 warn-date 25 1638 warn-text 25 1639 Warning 25 1640 Warning-v 25 1641 warning-value 25 1643 H 1644 Headers 1645 Age 17 1646 Cache-Control 17 1647 Expires 23 1648 Pragma 23 1649 Vary 24 1650 Warning 25 1651 heuristic expiration time 5 1653 M 1654 max-age 1655 Cache Directive 18, 21 1656 max-stale 1657 Cache Directive 19 1658 min-fresh 1659 Cache Directive 19 1660 must-revalidate 1661 Cache Directive 21 1663 N 1664 no-cache 1665 Cache Directive 18, 20 1666 no-store 1667 Cache Directive 18, 21 1668 no-transform 1669 Cache Directive 19, 22 1671 O 1672 only-if-cached 1673 Cache Directive 19 1675 P 1676 Pragma header 23 1677 private 1678 Cache Directive 20 1679 proxy-revalidate 1680 Cache Directive 21 1681 public 1682 Cache Directive 20 1684 S 1685 s-maxage 1686 Cache Directive 22 1687 stale 6 1689 V 1690 validator 6 1691 Vary header 24 1693 W 1694 Warning header 25 1696 Authors' Addresses 1698 Roy T. Fielding (editor) 1699 Day Software 1700 23 Corporate Plaza DR, Suite 280 1701 Newport Beach, CA 92660 1702 USA 1704 Phone: +1-949-706-5300 1705 Fax: +1-949-706-5305 1706 Email: fielding@gbiv.com 1707 URI: http://roy.gbiv.com/ 1709 Jim Gettys 1710 One Laptop per Child 1711 21 Oak Knoll Road 1712 Carlisle, MA 01741 1713 USA 1715 Email: jg@laptop.org 1716 URI: http://www.laptop.org/ 1718 Jeffrey C. Mogul 1719 Hewlett-Packard Company 1720 HP Labs, Large Scale Systems Group 1721 1501 Page Mill Road, MS 1177 1722 Palo Alto, CA 94304 1723 USA 1725 Email: JeffMogul@acm.org 1727 Henrik Frystyk Nielsen 1728 Microsoft Corporation 1729 1 Microsoft Way 1730 Redmond, WA 98052 1731 USA 1733 Email: henrikn@microsoft.com 1734 Larry Masinter 1735 Adobe Systems, Incorporated 1736 345 Park Ave 1737 San Jose, CA 95110 1738 USA 1740 Email: LMM@acm.org 1741 URI: http://larry.masinter.net/ 1743 Paul J. Leach 1744 Microsoft Corporation 1745 1 Microsoft Way 1746 Redmond, WA 98052 1748 Email: paulle@microsoft.com 1750 Tim Berners-Lee 1751 World Wide Web Consortium 1752 MIT Computer Science and Artificial Intelligence Laboratory 1753 The Stata Center, Building 32 1754 32 Vassar Street 1755 Cambridge, MA 02139 1756 USA 1758 Email: timbl@w3.org 1759 URI: http://www.w3.org/People/Berners-Lee/ 1761 Yves Lafon (editor) 1762 World Wide Web Consortium 1763 W3C / ERCIM 1764 2004, rte des Lucioles 1765 Sophia-Antipolis, AM 06902 1766 France 1768 Email: ylafon@w3.org 1769 URI: http://www.raubacapeu.net/people/yves/ 1770 Julian F. Reschke (editor) 1771 greenbytes GmbH 1772 Hafenweg 16 1773 Muenster, NW 48155 1774 Germany 1776 Phone: +49 251 2807760 1777 Fax: +49 251 2807761 1778 Email: julian.reschke@greenbytes.de 1779 URI: http://greenbytes.de/tech/webdav/