idnits 2.17.1 draft-ietf-httpbis-p6-cache-07.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 (July 13, 2009) is 5398 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-07 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-07 == Outdated reference: A later version (-20) exists of draft-ietf-httpbis-p3-payload-07 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-07 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-07 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-07 -- 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: January 14, 2010 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 M. Nottingham, Ed. 20 J. Reschke, Ed. 21 greenbytes 22 July 13, 2009 24 HTTP/1.1, part 6: Caching 25 draft-ietf-httpbis-p6-cache-07 27 Status of this Memo 29 This Internet-Draft is submitted to IETF in full conformance with the 30 provisions of BCP 78 and BCP 79. This document may contain material 31 from IETF Documents or IETF Contributions published or made publicly 32 available before November 10, 2008. The person(s) controlling the 33 copyright in some of this material may not have granted the IETF 34 Trust the right to allow modifications of such material outside the 35 IETF Standards Process. Without obtaining an adequate license from 36 the person(s) controlling the copyright in such materials, this 37 document may not be modified outside the IETF Standards Process, and 38 derivative works of it may not be created outside the IETF Standards 39 Process, except to format it for publication as an RFC or to 40 translate it into languages other than English. 42 Internet-Drafts are working documents of the Internet Engineering 43 Task Force (IETF), its areas, and its working groups. Note that 44 other groups may also distribute working documents as Internet- 45 Drafts. 47 Internet-Drafts are draft documents valid for a maximum of six months 48 and may be updated, replaced, or obsoleted by other documents at any 49 time. It is inappropriate to use Internet-Drafts as reference 50 material or to cite them other than as "work in progress." 52 The list of current Internet-Drafts can be accessed at 53 http://www.ietf.org/ietf/1id-abstracts.txt. 55 The list of Internet-Draft Shadow Directories can be accessed at 56 http://www.ietf.org/shadow.html. 58 This Internet-Draft will expire on January 14, 2010. 60 Copyright Notice 62 Copyright (c) 2009 IETF Trust and the persons identified as the 63 document authors. All rights reserved. 65 This document is subject to BCP 78 and the IETF Trust's Legal 66 Provisions Relating to IETF Documents in effect on the date of 67 publication of this document (http://trustee.ietf.org/license-info). 68 Please review these documents carefully, as they describe your rights 69 and restrictions with respect to this document. 71 Abstract 73 The Hypertext Transfer Protocol (HTTP) is an application-level 74 protocol for distributed, collaborative, hypermedia information 75 systems. This document is Part 6 of the seven-part specification 76 that defines the protocol referred to as "HTTP/1.1" and, taken 77 together, obsoletes RFC 2616. Part 6 defines requirements on HTTP 78 caches and the associated header fields that control cache behavior 79 or indicate cacheable response messages. 81 Editorial Note (To be removed by RFC Editor) 83 Discussion of this draft should take place on the HTTPBIS working 84 group mailing list (ietf-http-wg@w3.org). The current issues list is 85 at and related 86 documents (including fancy diffs) can be found at 87 . 89 The changes in this draft are summarized in Appendix C.8. 91 Table of Contents 93 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 94 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 95 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 96 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 6 97 1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 98 1.4.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 7 99 1.4.2. ABNF Rules defined in other Parts of the 100 Specification . . . . . . . . . . . . . . . . . . . . 7 101 2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 7 102 2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 7 103 2.1.1. Storing Partial and Incomplete Responses . . . . . . . 8 104 2.2. Constructing Responses from Caches . . . . . . . . . . . . 8 105 2.3. Freshness Model . . . . . . . . . . . . . . . . . . . . . 9 106 2.3.1. Calculating Freshness Lifetime . . . . . . . . . . . . 10 107 2.3.2. Calculating Age . . . . . . . . . . . . . . . . . . . 11 108 2.3.3. Serving Stale Responses . . . . . . . . . . . . . . . 13 109 2.4. Validation Model . . . . . . . . . . . . . . . . . . . . . 13 110 2.5. Request Methods that Invalidate . . . . . . . . . . . . . 14 111 2.6. Caching Negotiated Responses . . . . . . . . . . . . . . . 15 112 2.7. Combining Responses . . . . . . . . . . . . . . . . . . . 16 113 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 17 114 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 115 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 17 116 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 18 117 3.2.2. Response Cache-Control Directives . . . . . . . . . . 20 118 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 22 119 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 23 120 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 23 121 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 122 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 25 123 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 28 124 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 125 5.1. Message Header Registration . . . . . . . . . . . . . . . 28 126 6. Security Considerations . . . . . . . . . . . . . . . . . . . 29 127 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29 128 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 129 8.1. Normative References . . . . . . . . . . . . . . . . . . . 29 130 8.2. Informative References . . . . . . . . . . . . . . . . . . 30 131 Appendix A. Compatibility with Previous Versions . . . . . . . . 31 132 A.1. Changes from RFC 2068 . . . . . . . . . . . . . . . . . . 31 133 A.2. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 31 134 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 31 135 Appendix C. Change Log (to be removed by RFC Editor before 136 publication) . . . . . . . . . . . . . . . . . . . . 33 137 C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 33 138 C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 33 139 C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 34 140 C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 34 141 C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 34 142 C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 35 143 C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 35 144 C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 35 145 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 146 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38 148 1. Introduction 150 HTTP is typically used for distributed information systems, where 151 performance can be improved by the use of response caches. This 152 document defines aspects of HTTP/1.1 related to caching and reusing 153 response messages. 155 1.1. Purpose 157 An HTTP cache is a local store of response messages and the subsystem 158 that controls its message storage, retrieval, and deletion. A cache 159 stores cacheable responses in order to reduce the response time and 160 network bandwidth consumption on future, equivalent requests. Any 161 client or server may include a cache, though a cache cannot be used 162 by a server that is acting as a tunnel. 164 Caching would be useless if it did not significantly improve 165 performance. The goal of caching in HTTP/1.1 is to reuse a prior 166 response message to satisfy a current request. In some cases, a 167 stored response can be reused without the need for a network request, 168 reducing latency and network round-trips; a "freshness" mechanism is 169 used for this purpose (see Section 2.3). Even when a new request is 170 required, it is often possible to reuse all or parts of the payload 171 of a prior response to satisfy the request, thereby reducing network 172 bandwidth usage; a "validation" mechanism is used for this purpose 173 (see Section 2.4). 175 1.2. Terminology 177 This specification uses a number of terms to refer to the roles 178 played by participants in, and objects of, HTTP caching. 180 cacheable 182 A response is cacheable if a cache is allowed to store a copy of 183 the response message for use in answering subsequent requests. 184 Even when a response is cacheable, there may be additional 185 constraints on whether a cache can use the cached copy to satisfy 186 a particular request. 188 explicit expiration time 190 The time at which the origin server intends that an entity should 191 no longer be returned by a cache without further validation. 193 heuristic expiration time 195 An expiration time assigned by a cache when no explicit expiration 196 time is available. 198 age 200 The age of a response is the time since it was sent by, or 201 successfully validated with, the origin server. 203 first-hand 205 A response is first-hand if the freshness model is not in use; 206 i.e., its age is 0. 208 freshness lifetime 210 The length of time between the generation of a response and its 211 expiration time. 213 fresh 215 A response is fresh if its age has not yet exceeded its freshness 216 lifetime. 218 stale 220 A response is stale if its age has passed its freshness lifetime 221 (either explicit or heuristic). 223 validator 225 A protocol element (e.g., an entity tag or a Last-Modified time) 226 that is used to find out whether a stored response is an 227 equivalent copy of an entity. 229 shared cache 231 A cache that is accessible to more than one user. A non-shared 232 cache is dedicated to a single user. 234 1.3. Requirements 236 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 237 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 238 document are to be interpreted as described in [RFC2119]. 240 An implementation is not compliant if it fails to satisfy one or more 241 of the MUST or REQUIRED level requirements for the protocols it 242 implements. An implementation that satisfies all the MUST or 243 REQUIRED level and all the SHOULD level requirements for its 244 protocols is said to be "unconditionally compliant"; one that 245 satisfies all the MUST level requirements but not all the SHOULD 246 level requirements for its protocols is said to be "conditionally 247 compliant." 249 1.4. Syntax Notation 251 This specification uses the ABNF syntax defined in Section 1.2 of 252 [Part1] (which extends the syntax defined in [RFC5234] with a list 253 rule). Appendix B shows the collected ABNF, with the list rule 254 expanded. 256 The following core rules are included by reference, as defined in 257 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 258 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 259 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 260 sequence of data), SP (space), VCHAR (any visible USASCII character), 261 and WSP (whitespace). 263 1.4.1. Core Rules 265 The core rules below are defined in Section 1.2.2 of [Part1]: 267 quoted-string = 268 token = 269 OWS = 271 1.4.2. ABNF Rules defined in other Parts of the Specification 273 The ABNF rules below are defined in other parts: 275 field-name = 276 HTTP-date = 277 port = 278 pseudonym = 279 uri-host = 281 2. Cache Operation 283 2.1. Response Cacheability 285 A cache MUST NOT store a response to any request, unless: 287 o The request method is defined as being cacheable, and 289 o the "no-store" cache directive (see Section 3.2) does not appear 290 in request or response headers, and 292 o the "private" cache response directive (see Section 3.2 does not 293 appear in the response, if the cache is shared, and 295 o the "Authorization" header (see Section 3.1 of [Part7]) does not 296 appear in the request, if the cache is shared (unless the "public" 297 directive is present; see Section 3.2), and 299 o the cache understands partial responses, if the response is 300 partial or incomplete (see Section 2.1.1). 302 Note that in normal operation, most caches will not store a response 303 that has neither a cache validator nor an explicit expiration time, 304 as such responses are not usually useful to store. However, caches 305 are not prohibited from storing such responses. 307 2.1.1. Storing Partial and Incomplete Responses 309 A cache that receives an incomplete response (for example, with fewer 310 bytes of data than specified in a Content-Length header) can store 311 the response, but MUST treat it as a partial response [Part5]. 312 Partial responses can be combined as described in Section 4 of 313 [Part5]; the result might be a full response or might still be 314 partial. A cache MUST NOT return a partial response to a client 315 without explicitly marking it as such using the 206 (Partial Content) 316 status code. 318 A cache that does not support the Range and Content-Range headers 319 MUST NOT store incomplete or partial responses. 321 2.2. Constructing Responses from Caches 323 For a presented request, a cache MUST NOT return a stored response, 324 unless: 326 o The presented Request-URI and that of the stored response match 327 ([[TODO-Request-URI: Need to find a new term for this, as Part 1 328 doesn't define Request-URI anymore; the new term request-target 329 does not work for this.]]), and 331 o the request method associated with the stored response allows it 332 to be used for the presented request, and 334 o selecting request-headers nominated by the stored response (if 335 any) match those presented (see Section 2.6), and 337 o the presented request and stored response are free from directives 338 that would prevent its use (see Section 3.2 and Section 3.4), and 340 o the stored response is either: 342 * fresh (see Section 2.3), or 344 * allowed to be served stale (see Section 2.3.3), or 346 * successfully validated (see Section 2.4). 348 [[TODO-method-cacheability: define method cacheability for GET, HEAD 349 and POST in p2-semantics.]] 351 When a stored response is used to satisfy a request, caches MUST 352 include a single Age header field (Section 3.1) in the response with 353 a value equal to the stored response's current_age; see 354 Section 2.3.2. [[anchor1: DISCUSS: this currently includes 355 successfully validated responses.]] 357 Requests with methods that are unsafe (Section 7.1.1 of [Part2]) MUST 358 be written through the cache to the origin server; i.e., A cache must 359 not reply to such a request before having forwarded the request and 360 having received a corresponding response. 362 Also, note that unsafe requests might invalidate already stored 363 responses; see Section 2.5. 365 Caches MUST use the most recent response (as determined by the Date 366 header) when more than one suitable response is stored. They can 367 also forward a request with "Cache-Control: max-age=0" or "Cache- 368 Control: no-cache" to disambiguate which response to use. 370 [[TODO-header-properties: end-to-end and hop-by-hop headers, non- 371 modifiable headers removed; re-spec in p1]] 373 2.3. Freshness Model 375 When a response is "fresh" in the cache, it can be used to satisfy 376 subsequent requests without contacting the origin server, thereby 377 improving efficiency. 379 The primary mechanism for determining freshness is for an origin 380 server to provide an explicit expiration time in the future, using 381 either the Expires header (Section 3.3) or the max-age response cache 382 directive (Section 3.2.2). Generally, origin servers will assign 383 future explicit expiration times to responses in the belief that the 384 entity is not likely to change in a semantically significant way 385 before the expiration time is reached. 387 If an origin server wishes to force a cache to validate every 388 request, it can assign an explicit expiration time in the past. This 389 means that the response is always stale, so that caches should 390 validate it before using it for subsequent requests. [[anchor2: This 391 wording may cause confusion, because the response may still be served 392 stale.]] 394 Since origin servers do not always provide explicit expiration times, 395 HTTP caches may also assign heuristic expiration times when they are 396 not specified, employing algorithms that use other header values 397 (such as the Last-Modified time) to estimate a plausible expiration 398 time. The HTTP/1.1 specification does not provide specific 399 algorithms, but does impose worst-case constraints on their results. 401 The calculation to determine if a response is fresh is: 403 response_is_fresh = (freshness_lifetime > current_age) 405 The freshness_lifetime is defined in Section 2.3.1; the current_age 406 is defined in Section 2.3.2. 408 Additionally, clients may need to influence freshness calculation. 409 They can do this using several request cache directives, with the 410 effect of either increasing or loosening constraints on freshness. 411 See Section 3.2.1. 413 [[anchor3: ISSUE: there are not requirements directly applying to 414 cache-request-directives and freshness.]] 416 Note that freshness applies only to cache operation; it cannot be 417 used to force a user agent to refresh its display or reload a 418 resource. See Section 4 for an explanation of the difference between 419 caches and history mechanisms. 421 2.3.1. Calculating Freshness Lifetime 423 A cache can calculate the freshness lifetime (denoted as 424 freshness_lifetime) of a response by using the first match of: 426 o If the cache is shared and the s-maxage response cache directive 427 (Section 3.2.2) is present, use its value, or 429 o If the max-age response cache directive (Section 3.2.2) is 430 present, use its value, or 432 o If the Expires response header (Section 3.3) is present, use its 433 value minus the value of the Date response header, or 435 o Otherwise, no explicit expiration time is present in the response, 436 but a heuristic may be used; see Section 2.3.1.1. 438 Note that this calculation is not vulnerable to clock skew, since all 439 of the information comes from the origin server. 441 2.3.1.1. Calculating Heuristic Freshness 443 If no explicit expiration time is present in a stored response that 444 has a status code of 200, 203, 206, 300, 301 or 410, a heuristic 445 expiration time can be calculated. Heuristics MUST NOT be used for 446 other response status codes. 448 When a heuristic is used to calculate freshness lifetime, the cache 449 SHOULD attach a Warning header with a 113 warn-code to the response 450 if its current_age is more than 24 hours and such a warning is not 451 already present. 453 Also, if the response has a Last-Modified header (Section 6.6 of 454 [Part4]), the heuristic expiration value SHOULD be no more than some 455 fraction of the interval since that time. A typical setting of this 456 fraction might be 10%. 458 [[anchor4: REVIEW: took away HTTP/1.0 query string heuristic 459 uncacheability.]] 461 2.3.2. Calculating Age 463 HTTP/1.1 uses the Age response-header to convey the estimated age of 464 the response message when obtained from a cache. The Age field value 465 is the cache's estimate of the amount of time since the response was 466 generated or validated by the origin server. In essence, the Age 467 value is the sum of the time that the response has been resident in 468 each of the caches along the path from the origin server, plus the 469 amount of time it has been in transit along network paths. 471 The term "age_value" denotes the value of the Age header, in a form 472 appropriate for arithmetic operations. 474 HTTP/1.1 requires origin servers to send a Date header, if possible, 475 with every response, giving the time at which the response was 476 generated (see Section 8.3 of [Part1]). The term "date_value" 477 denotes the value of the Date header, in a form appropriate for 478 arithmetic operations. 480 The term "now" means "the current value of the clock at the host 481 performing the calculation." Hosts that use HTTP, but especially 482 hosts running origin servers and caches, SHOULD use NTP [RFC1305] or 483 some similar protocol to synchronize their clocks to a globally 484 accurate time standard. 486 A response's age can be calculated in two entirely independent ways: 488 1. now minus date_value, if the local clock is reasonably well 489 synchronized to the origin server's clock. If the result is 490 negative, the result is replaced by zero. 492 2. age_value, if all of the caches along the response path implement 493 HTTP/1.1. 495 These are combined as 497 corrected_received_age = max(now - date_value, age_value) 499 When an Age value is received, it MUST be interpreted relative to the 500 time the request was initiated, not the time that the response was 501 received. 503 corrected_initial_age = corrected_received_age 504 + (now - request_time) 506 where "request_time" is the time (according to the local clock) when 507 the request that elicited this response was sent. 509 The current_age of a stored response can then be calculated by adding 510 the amount of time (in seconds) since the stored response was last 511 validated by the origin server to the corrected_initial_age. 513 In summary: 515 age_value - Age header field-value received with the response 516 date_value - Date header field-value received with the response 517 request_time - local time when the cache made the request 518 resulting in the stored response 519 response_time - local time when the cache received the response 520 now - current local time 522 apparent_age = max(0, response_time - date_value); 523 corrected_received_age = max(apparent_age, age_value); 524 response_delay = response_time - request_time; 525 corrected_initial_age = corrected_received_age + response_delay; 526 resident_time = now - response_time; 527 current_age = corrected_initial_age + resident_time; 529 2.3.3. Serving Stale Responses 531 A "stale" response is one that either has explicit expiry 532 information, or is allowed to have heuristic expiry calculated, but 533 is not fresh according to the calculations in Section 2.3. 535 Caches MUST NOT return a stale response if it is prohibited by an 536 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" 537 cache directive, a "must-revalidate" cache-response-directive, or an 538 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 539 see Section 3.2.2). 541 Caches SHOULD NOT return stale responses unless they are disconnected 542 (i.e., it cannot contact the origin server or otherwise find a 543 forward path) or otherwise explicitly allowed (e.g., the max-stale 544 request directive; see Section 3.2.1). 546 Stale responses SHOULD have a Warning header with the 110 warn-code 547 (see Section 3.6). Likewise, the 112 warn-code SHOULD be sent on 548 stale responses if the cache is disconnected. 550 If a cache receives a first-hand response (either an entire response, 551 or a 304 (Not Modified) response) that it would normally forward to 552 the requesting client, and the received response is no longer fresh, 553 the cache SHOULD forward it to the requesting client without adding a 554 new Warning (but without removing any existing Warning headers). A 555 cache SHOULD NOT attempt to validate a response simply because that 556 response became stale in transit. 558 2.4. Validation Model 560 When a cache has one or more stored responses for a requested URI, 561 but cannot serve any of them (e.g., because they are not fresh, or 562 one cannot be selected; see Section 2.6), it can use the conditional 563 request mechanism [Part4] in the forwarded request to give the origin 564 server an opportunity to both select a valid stored response to be 565 used, and to update it. This process is known as "validating" or 566 "revalidating" the stored response. 568 When sending such a conditional request, the cache SHOULD add an If- 569 Modified-Since header whose value is that of the Last-Modified header 570 from the selected (see Section 2.6) stored response, if available. 572 Additionally, the cache SHOULD add an If-None-Match header whose 573 value is that of the ETag header(s) from all responses stored for the 574 requested URI, if present. However, if any of the stored responses 575 contains only partial content, its entity-tag SHOULD NOT be included 576 in the If-None-Match header field unless the request is for a range 577 that would be fully satisfied by that stored response. 579 A 304 (Not Modified) response status code indicates that the stored 580 response can be updated and reused; see Section 2.7. 582 A full response (i.e., one with a response body) indicates that none 583 of the stored responses nominated in the conditional request is 584 suitable. Instead, the full response is used both to satisfy the 585 request and replace the stored response. [[anchor5: Should there be a 586 requirement here?]] 588 If a cache receives a 5xx response while attempting to validate a 589 response, it MAY either forward this response to the requesting 590 client, or act as if the server failed to respond. In the latter 591 case, it MAY return a previously stored response (see Section 2.3.3). 593 If a cache receives a successful response whose Content-Location 594 field matches that of an existing stored response for the same 595 Request-URI, whose entity-tag differs from that of the existing 596 stored response, and whose Date is more recent than that of the 597 existing response, the existing response SHOULD NOT be returned in 598 response to future requests and SHOULD be deleted from the cache. 599 [[anchor6: DISCUSS: Not sure if this is necessary.]] 601 2.5. Request Methods that Invalidate 603 Because unsafe methods (Section 7.1.1 of [Part2]) have the potential 604 for changing state on the origin server, intervening caches can use 605 them to keep their contents up-to-date. 607 The following HTTP methods MUST cause a cache to invalidate the 608 Request-URI as well as the URI(s) in the Location and Content- 609 Location headers (if present): 611 o PUT 613 o DELETE 615 o POST 617 An invalidation based on a URI from a Location or Content-Location 618 header MUST NOT be performed if the host part of that URI differs 619 from the host part in the Request-URI. This helps prevent denial of 620 service attacks. 622 [[anchor7: TODO: "host part" needs to be specified better.]] 624 A cache that passes through requests for methods it does not 625 understand SHOULD invalidate the Request-URI. 627 Here, "invalidate" means that the cache will either remove all stored 628 responses related to the Request-URI, or will mark these as "invalid" 629 and in need of a mandatory validation before they can be returned in 630 response to a subsequent request. 632 Note that this does not guarantee that all appropriate responses are 633 invalidated. For example, the request that caused the change at the 634 origin server might not have gone through the cache where a response 635 is stored. 637 [[anchor8: TODO: specify that only successful (2xx, 3xx?) responses 638 invalidate.]] 640 2.6. Caching Negotiated Responses 642 When a cache receives a request that can be satisfied by a stored 643 response that has a Vary header field (Section 3.5), it MUST NOT use 644 that response unless all of the selecting request-headers nominated 645 by the Vary header match in both the original request (i.e., that 646 associated with the stored response), and the presented request. 648 The selecting request-headers from two requests are defined to match 649 if and only if the selecting request-headers in the first request can 650 be transformed to the selecting request-headers in the second request 651 by adding or removing linear white space [[anchor9: [ref]]] at places 652 where this is allowed by the corresponding ABNF, and/or combining 653 multiple message-header fields with the same field name following the 654 rules about message headers in Section 4.2 of [Part1]. 656 If a header field is absent from a request, it can only match another 657 request if it is also absent there. 659 A Vary header field-value of "*" always fails to match, and 660 subsequent requests to that resource can only be properly interpreted 661 by the origin server. 663 The stored response with matching selecting request-headers is known 664 as the selected response. 666 If no selected response is available, the cache MAY forward the 667 presented request to the origin server in a conditional request; see 668 Section 2.4. 670 2.7. Combining Responses 672 When a cache receives a 304 (Not Modified) response or a 206 (Partial 673 Content) response (in this section, the "new" response"), it needs to 674 created an updated response by combining the stored response with the 675 new one, so that the updated response can be used to satisfy the 676 request. 678 If the new response contains an ETag, it identifies the stored 679 response to use. [[anchor10: may need language about Content-Location 680 here]][[anchor11: cover case where INM with multiple etags was sent]] 682 If the status code is 206 (partial content), both the stored and new 683 responses MUST have ETags, and those ETags MUST match using the 684 strong comparison function (see Section 4 of [Part4]). Otherwise, 685 the responses MUST NOT be combined. 687 The stored response headers are used as those of the updated 688 response, except that 690 o any stored Warning headers with warn-code 1xx (see Section 3.6) 691 MUST be deleted from the stored response and the updated response. 693 o any stored Warning headers with warn-code 2xx MUST be retained in 694 the stored response and the updated response. 696 o any headers provided in the new response MUST replace the 697 corresponding headers from the stored response. 699 If a header field-name in the new response matches more than one 700 header in the stored response, all such stored headers MUST be 701 replaced. 703 The updated response can [[[[anchor12: requirement?]]]] be used to 704 replace the stored response in cache. In the case of a 206 response, 705 the combined entity-body MAY be stored. 707 [[anchor13: ISSUE: discuss how to handle HEAD updates]] 709 3. Header Field Definitions 711 This section defines the syntax and semantics of HTTP/1.1 header 712 fields related to caching. 714 For entity-header fields, both sender and recipient refer to either 715 the client or the server, depending on who sends and who receives the 716 entity. 718 3.1. Age 720 The response-header field "Age" conveys the sender's estimate of the 721 amount of time since the response (or its validation) was generated 722 at the origin server. Age values are calculated as specified in 723 Section 2.3.2. 725 Age = "Age" ":" OWS Age-v 726 Age-v = delta-seconds 728 Age field-values are non-negative integers, representing time in 729 seconds. 731 delta-seconds = 1*DIGIT 733 If a cache receives a value larger than the largest positive integer 734 it can represent, or if any of its age calculations overflows, it 735 MUST transmit an Age header with a field-value of 2147483648 (2^31). 736 Caches SHOULD use an arithmetic type of at least 31 bits of range. 738 The presence of an Age header field in a response implies that a 739 response is not first-hand. However, the converse is not true, since 740 HTTP/1.0 caches may not implement the Age header field. 742 3.2. Cache-Control 744 The general-header field "Cache-Control" is used to specify 745 directives that MUST be obeyed by all caches along the request/ 746 response chain. The directives specify behavior intended to prevent 747 caches from adversely interfering with the request or response. 748 Cache directives are unidirectional in that the presence of a 749 directive in a request does not imply that the same directive is to 750 be given in the response. 752 Note that HTTP/1.0 caches might not implement Cache-Control and 753 might only implement Pragma: no-cache (see Section 3.4). 755 Cache directives MUST be passed through by a proxy or gateway 756 application, regardless of their significance to that application, 757 since the directives might be applicable to all recipients along the 758 request/response chain. It is not possible to target a directive to 759 a specific cache. 761 Cache-Control = "Cache-Control" ":" OWS Cache-Control-v 762 Cache-Control-v = 1#cache-directive 764 cache-directive = cache-request-directive 765 / cache-response-directive 767 cache-extension = token [ "=" ( token / quoted-string ) ] 769 3.2.1. Request Cache-Control Directives 771 cache-request-directive = 772 "no-cache" 773 / "no-store" 774 / "max-age" "=" delta-seconds 775 / "max-stale" [ "=" delta-seconds ] 776 / "min-fresh" "=" delta-seconds 777 / "no-transform" 778 / "only-if-cached" 779 / cache-extension 781 no-cache 783 The no-cache request directive indicates that a stored response 784 MUST NOT be used to satisfy the request without successful 785 validation on the origin server. 787 no-store 789 The no-store request directive indicates that a cache MUST NOT 790 store any part of either this request or any response to it. This 791 directive applies to both non-shared and shared caches. "MUST NOT 792 store" in this context means that the cache MUST NOT intentionally 793 store the information in non-volatile storage, and MUST make a 794 best-effort attempt to remove the information from volatile 795 storage as promptly as possible after forwarding it. 797 This directive is NOT a reliable or sufficient mechanism for 798 ensuring privacy. In particular, malicious or compromised caches 799 might not recognize or obey this directive, and communications 800 networks may be vulnerable to eavesdropping. 802 max-age 804 The max-age request directive indicates that the client is willing 805 to accept a response whose age is no greater than the specified 806 time in seconds. Unless max-stale directive is also included, the 807 client is not willing to accept a stale response. 809 max-stale 811 The max-stale request directive indicates that the client is 812 willing to accept a response that has exceeded its expiration 813 time. If max-stale is assigned a value, then the client is 814 willing to accept a response that has exceeded its expiration time 815 by no more than the specified number of seconds. If no value is 816 assigned to max-stale, then the client is willing to accept a 817 stale response of any age. [[anchor14: of any staleness? --mnot]] 819 min-fresh 821 The min-fresh request directive indicates that the client is 822 willing to accept a response whose freshness lifetime is no less 823 than its current age plus the specified time in seconds. That is, 824 the client wants a response that will still be fresh for at least 825 the specified number of seconds. 827 no-transform 829 The no-transform request directive indicates that an intermediate 830 cache or proxy MUST NOT change the Content-Encoding, Content-Range 831 or Content-Type request headers, nor the request entity-body. 833 only-if-cached 835 The only-if-cached request directive indicates that the client 836 only wishes to return a stored response. If it receives this 837 directive, a cache SHOULD either respond using a stored response 838 that is consistent with the other constraints of the request, or 839 respond with a 504 (Gateway Timeout) status. If a group of caches 840 is being operated as a unified system with good internal 841 connectivity, such a request MAY be forwarded within that group of 842 caches. 844 3.2.2. Response Cache-Control Directives 846 cache-response-directive = 847 "public" 848 / "private" [ "=" DQUOTE 1#field-name DQUOTE ] 849 / "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] 850 / "no-store" 851 / "no-transform" 852 / "must-revalidate" 853 / "proxy-revalidate" 854 / "max-age" "=" delta-seconds 855 / "s-maxage" "=" delta-seconds 856 / cache-extension 858 public 860 The public response directive indicates that the response MAY be 861 cached, even if it would normally be non-cacheable or cacheable 862 only within a non-shared cache. (See also Authorization, Section 863 3.1 of [Part7], for additional details.) 865 private 867 The private response directive indicates that the response message 868 is intended for a single user and MUST NOT be stored by a shared 869 cache. A private (non-shared) cache MAY store the response. 871 If the private response directive specifies one or more field- 872 names, this requirement is limited to the field-values associated 873 with the listed response headers. That is, the specified field- 874 names(s) MUST NOT be stored by a shared cache, whereas the 875 remainder of the response message MAY be. 877 Note: This usage of the word private only controls where the 878 response may be stored, and cannot ensure the privacy of the 879 message content. 881 no-cache 883 The no-cache response directive indicates that the response MUST 884 NOT be used to satisfy a subsequent request without successful 885 validation on the origin server. This allows an origin server to 886 prevent caching even by caches that have been configured to return 887 stale responses. 889 If the no-cache response directive specifies one or more field- 890 names, this requirement is limited to the field-values associated 891 with the listed response headers. That is, the specified field- 892 name(s) MUST NOT be sent in the response to a subsequent request 893 without successful validation on the origin server. This allows 894 an origin server to prevent the re-use of certain header fields in 895 a response, while still allowing caching of the rest of the 896 response. 898 Note: Most HTTP/1.0 caches will not recognize or obey this 899 directive. 901 no-store 903 The no-store response directive indicates that a cache MUST NOT 904 store any part of either the immediate request or response. This 905 directive applies to both non-shared and shared caches. "MUST NOT 906 store" in this context means that the cache MUST NOT intentionally 907 store the information in non-volatile storage, and MUST make a 908 best-effort attempt to remove the information from volatile 909 storage as promptly as possible after forwarding it. 911 This directive is NOT a reliable or sufficient mechanism for 912 ensuring privacy. In particular, malicious or compromised caches 913 might not recognize or obey this directive, and communications 914 networks may be vulnerable to eavesdropping. 916 must-revalidate 918 The must-revalidate response directive indicates that once it has 919 become stale, the response MUST NOT be used to satisfy subsequent 920 requests without successful validation on the origin server. 922 The must-revalidate directive is necessary to support reliable 923 operation for certain protocol features. In all circumstances an 924 HTTP/1.1 cache MUST obey the must-revalidate directive; in 925 particular, if the cache cannot reach the origin server for any 926 reason, it MUST generate a 504 (Gateway Timeout) response. 928 Servers SHOULD send the must-revalidate directive if and only if 929 failure to validate a request on the entity could result in 930 incorrect operation, such as a silently unexecuted financial 931 transaction. 933 proxy-revalidate 935 The proxy-revalidate response directive has the same meaning as 936 the must-revalidate response directive, except that it does not 937 apply to non-shared caches. 939 max-age 940 The max-age response directive indicates that response is to be 941 considered stale after its age is greater than the specified 942 number of seconds. 944 s-maxage 946 The s-maxage response directive indicates that, in shared caches, 947 the maximum age specified by this directive overrides the maximum 948 age specified by either the max-age directive or the Expires 949 header. The s-maxage directive also implies the semantics of the 950 proxy-revalidate response directive. 952 no-transform 954 The no-transform response directive indicates that an intermediate 955 cache or proxy MUST NOT change the Content-Encoding, Content-Range 956 or Content-Type response headers, nor the response entity-body. 958 3.2.3. Cache Control Extensions 960 The Cache-Control header field can be extended through the use of one 961 or more cache-extension tokens, each with an optional value. 962 Informational extensions (those that do not require a change in cache 963 behavior) can be added without changing the semantics of other 964 directives. Behavioral extensions are designed to work by acting as 965 modifiers to the existing base of cache directives. Both the new 966 directive and the standard directive are supplied, such that 967 applications that do not understand the new directive will default to 968 the behavior specified by the standard directive, and those that 969 understand the new directive will recognize it as modifying the 970 requirements associated with the standard directive. In this way, 971 extensions to the cache-control directives can be made without 972 requiring changes to the base protocol. 974 This extension mechanism depends on an HTTP cache obeying all of the 975 cache-control directives defined for its native HTTP-version, obeying 976 certain extensions, and ignoring all directives that it does not 977 understand. 979 For example, consider a hypothetical new response directive called 980 "community" that acts as a modifier to the private directive. We 981 define this new directive to mean that, in addition to any non-shared 982 cache, any cache that is shared only by members of the community 983 named within its value may cache the response. An origin server 984 wishing to allow the UCI community to use an otherwise private 985 response in their shared cache(s) could do so by including 987 Cache-Control: private, community="UCI" 989 A cache seeing this header field will act correctly even if the cache 990 does not understand the community cache-extension, since it will also 991 see and understand the private directive and thus default to the safe 992 behavior. 994 Unrecognized cache directives MUST be ignored; it is assumed that any 995 cache directive likely to be unrecognized by an HTTP/1.1 cache will 996 be combined with standard directives (or the response's default 997 cacheability) such that the cache behavior will remain minimally 998 correct even if the cache does not understand the extension(s). 1000 3.3. Expires 1002 The entity-header field "Expires" gives the date/time after which the 1003 response is considered stale. See Section 2.3 for further discussion 1004 of the freshness model. 1006 The presence of an Expires field does not imply that the original 1007 resource will change or cease to exist at, before, or after that 1008 time. 1010 The field-value is an absolute date and time as defined by HTTP-date 1011 in Section 3.2 of [Part1]; it MUST be sent in rfc1123-date format. 1013 Expires = "Expires" ":" OWS Expires-v 1014 Expires-v = HTTP-date 1016 For example 1018 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1020 Note: if a response includes a Cache-Control field with the max- 1021 age directive (see Section 3.2.2), that directive overrides the 1022 Expires field. Likewise, the s-maxage directive overrides Expires 1023 in shared caches. 1025 HTTP/1.1 servers SHOULD NOT send Expires dates more than one year in 1026 the future. 1028 HTTP/1.1 clients and caches MUST treat other invalid date formats, 1029 especially including the value "0", as in the past (i.e., "already 1030 expired"). 1032 3.4. Pragma 1034 The general-header field "Pragma" is used to include implementation- 1035 specific directives that might apply to any recipient along the 1036 request/response chain. All pragma directives specify optional 1037 behavior from the viewpoint of the protocol; however, some systems 1038 MAY require that behavior be consistent with the directives. 1040 Pragma = "Pragma" ":" OWS Pragma-v 1041 Pragma-v = 1#pragma-directive 1042 pragma-directive = "no-cache" / extension-pragma 1043 extension-pragma = token [ "=" ( token / quoted-string ) ] 1045 When the no-cache directive is present in a request message, an 1046 application SHOULD forward the request toward the origin server even 1047 if it has a cached copy of what is being requested. This pragma 1048 directive has the same semantics as the no-cache response directive 1049 (see Section 3.2.2) and is defined here for backward compatibility 1050 with HTTP/1.0. Clients SHOULD include both header fields when a no- 1051 cache request is sent to a server not known to be HTTP/1.1 compliant. 1052 HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had 1053 sent "Cache-Control: no-cache". 1055 Note: because the meaning of "Pragma: no-cache" as a response- 1056 header field is not actually specified, it does not provide a 1057 reliable replacement for "Cache-Control: no-cache" in a response. 1059 This mechanism is deprecated; no new Pragma directives will be 1060 defined in HTTP. 1062 3.5. Vary 1064 The "Vary" response-header field's value indicates the set of 1065 request-header fields that determines, while the response is fresh, 1066 whether a cache is permitted to use the response to reply to a 1067 subsequent request without validation; see Section 2.6. 1069 In uncacheable or stale responses, the Vary field value advises the 1070 user agent about the criteria that were used to select the 1071 representation. 1073 Vary = "Vary" ":" OWS Vary-v 1074 Vary-v = "*" / 1#field-name 1076 The set of header fields named by the Vary field value is known as 1077 the selecting request-headers. 1079 Servers SHOULD include a Vary header field with any cacheable 1080 response that is subject to server-driven negotiation. Doing so 1081 allows a cache to properly interpret future requests on that resource 1082 and informs the user agent about the presence of negotiation on that 1083 resource. A server MAY include a Vary header field with a non- 1084 cacheable response that is subject to server-driven negotiation, 1085 since this might provide the user agent with useful information about 1086 the dimensions over which the response varies at the time of the 1087 response. 1089 A Vary field value of "*" signals that unspecified parameters not 1090 limited to the request-headers (e.g., the network address of the 1091 client), play a role in the selection of the response representation; 1092 therefore, a cache cannot determine whether this response is 1093 appropriate. The "*" value MUST NOT be generated by a proxy server; 1094 it may only be generated by an origin server. 1096 The field-names given are not limited to the set of standard request- 1097 header fields defined by this specification. Field names are case- 1098 insensitive. 1100 3.6. Warning 1102 The general-header field "Warning" is used to carry additional 1103 information about the status or transformation of a message that 1104 might not be reflected in the message. This information is typically 1105 used to warn about possible incorrectness introduced by caching 1106 operations or transformations applied to the entity body of the 1107 message. 1109 Warnings can be used for other purposes, both cache-related and 1110 otherwise. The use of a warning, rather than an error status code, 1111 distinguish these responses from true failures. 1113 Warning headers can in general be applied to any message, however 1114 some warn-codes are specific to caches and can only be applied to 1115 response messages. 1117 Warning = "Warning" ":" OWS Warning-v 1118 Warning-v = 1#warning-value 1120 warning-value = warn-code SP warn-agent SP warn-text 1121 [SP warn-date] 1123 warn-code = 3DIGIT 1124 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1125 ; the name or pseudonym of the server adding 1126 ; the Warning header, for use in debugging 1127 warn-text = quoted-string 1128 warn-date = DQUOTE HTTP-date DQUOTE 1130 Multiple warnings can be attached to a response (either by the origin 1131 server or by a cache), including multiple warnings with the same code 1132 number. For example, a server might provide the same warning with 1133 texts in both English and Basque. 1135 When this occurs, the user agent SHOULD inform the user of as many of 1136 them as possible, in the order that they appear in the response. If 1137 it is not possible to inform the user of all of the warnings, the 1138 user agent SHOULD follow these heuristics: 1140 o Warnings that appear early in the response take priority over 1141 those appearing later in the response. 1143 o Warnings in the user's preferred character set take priority over 1144 warnings in other character sets but with identical warn-codes and 1145 warn-agents. 1147 Systems that generate multiple Warning headers SHOULD order them with 1148 this user agent behavior in mind. New Warning headers SHOULD be 1149 added after any existing Warning headers. 1151 Warnings are assigned three digit warn-codes. The first digit 1152 indicates whether the Warning is required to be deleted from a stored 1153 response after validation: 1155 o 1xx Warnings that describe the freshness or validation status of 1156 the response, and so MUST be deleted by caches after validation. 1157 They MUST NOT be generated by a cache except when validating a 1158 cached entry, and MUST NOT be generated by clients. 1160 o 2xx Warnings that describe some aspect of the entity body or 1161 entity headers that is not rectified by a validation (for example, 1162 a lossy compression of the entity bodies) and MUST NOT be deleted 1163 by caches after validation, unless a full response is returned, in 1164 which case they MUST be. 1166 The warn-text SHOULD be in a natural language and character set that 1167 is most likely to be intelligible to the human user receiving the 1168 response. This decision can be based on any available knowledge, 1169 such as the location of the cache or user, the Accept-Language field 1170 in a request, the Content-Language field in a response, etc. The 1171 default language is English and the default character set is ISO- 1172 8859-1 ([ISO-8859-1]). 1174 If a character set other than ISO-8859-1 is used, it MUST be encoded 1175 in the warn-text using the method described in [RFC2047]. 1177 If an implementation sends a message with one or more Warning headers 1178 to a receiver whose version is HTTP/1.0 or lower, then the sender 1179 MUST include in each warning-value a warn-date that matches the Date 1180 header in the message. 1182 If an implementation receives a message with a warning-value that 1183 includes a warn-date, and that warn-date is different from the Date 1184 value in the response, then that warning-value MUST be deleted from 1185 the message before storing, forwarding, or using it. (preventing the 1186 consequences of naive caching of Warning header fields.) If all of 1187 the warning-values are deleted for this reason, the Warning header 1188 MUST be deleted as well. 1190 The following warn-codes are defined by this specification, each with 1191 a recommended warn-text in English, and a description of its meaning. 1193 110 Response is stale 1195 SHOULD be included whenever the returned response is stale. 1197 111 Revalidation failed 1199 SHOULD be included if a cache returns a stale response because an 1200 attempt to validate the response failed, due to an inability to 1201 reach the server. 1203 112 Disconnected operation 1205 SHOULD be included if the cache is intentionally disconnected from 1206 the rest of the network for a period of time. 1208 113 Heuristic expiration 1210 SHOULD be included if the cache heuristically chose a freshness 1211 lifetime greater than 24 hours and the response's age is greater 1212 than 24 hours. 1214 199 Miscellaneous warning 1216 The warning text can include arbitrary information to be presented 1217 to a human user, or logged. A system receiving this warning MUST 1218 NOT take any automated action, besides presenting the warning to 1219 the user. 1221 214 Transformation applied 1223 MUST be added by an intermediate cache or proxy if it applies any 1224 transformation changing the content-coding (as specified in the 1225 Content-Encoding header) or media-type (as specified in the 1226 Content-Type header) of the response, or the entity-body of the 1227 response, unless this Warning code already appears in the 1228 response. 1230 299 Miscellaneous persistent warning 1232 The warning text can include arbitrary information to be presented 1233 to a human user, or logged. A system receiving this warning MUST 1234 NOT take any automated action. 1236 4. History Lists 1238 User agents often have history mechanisms, such as "Back" buttons and 1239 history lists, that can be used to redisplay an entity retrieved 1240 earlier in a session. 1242 History mechanisms and caches are different. In particular history 1243 mechanisms SHOULD NOT try to show a correct view of the current state 1244 of a resource. Rather, a history mechanism is meant to show exactly 1245 what the user saw at the time when the resource was retrieved. 1247 By default, an expiration time does not apply to history mechanisms. 1248 If the entity is still in storage, a history mechanism SHOULD display 1249 it even if the entity has expired, unless the user has specifically 1250 configured the agent to refresh expired history documents. 1252 This is not to be construed to prohibit the history mechanism from 1253 telling the user that a view might be stale. 1255 Note: if history list mechanisms unnecessarily prevent users from 1256 viewing stale resources, this will tend to force service authors 1257 to avoid using HTTP expiration controls and cache controls when 1258 they would otherwise like to. Service authors may consider it 1259 important that users not be presented with error messages or 1260 warning messages when they use navigation controls (such as BACK) 1261 to view previously fetched resources. Even though sometimes such 1262 resources ought not be cached, or ought to expire quickly, user 1263 interface considerations may force service authors to resort to 1264 other means of preventing caching (e.g. "once-only" URLs) in order 1265 not to suffer the effects of improperly functioning history 1266 mechanisms. 1268 5. IANA Considerations 1270 5.1. Message Header Registration 1272 The Message Header Registry located at should be 1274 updated with the permanent registrations below (see [RFC3864]): 1276 +-------------------+----------+----------+-------------+ 1277 | Header Field Name | Protocol | Status | Reference | 1278 +-------------------+----------+----------+-------------+ 1279 | Age | http | standard | Section 3.1 | 1280 | Cache-Control | http | standard | Section 3.2 | 1281 | Expires | http | standard | Section 3.3 | 1282 | Pragma | http | standard | Section 3.4 | 1283 | Vary | http | standard | Section 3.5 | 1284 | Warning | http | standard | Section 3.6 | 1285 +-------------------+----------+----------+-------------+ 1287 The change controller is: "IETF (iesg@ietf.org) - Internet 1288 Engineering Task Force". 1290 6. Security Considerations 1292 Caches expose additional potential vulnerabilities, since the 1293 contents of the cache represent an attractive target for malicious 1294 exploitation. Because cache contents persist after an HTTP request 1295 is complete, an attack on the cache can reveal information long after 1296 a user believes that the information has been removed from the 1297 network. Therefore, cache contents should be protected as sensitive 1298 information. 1300 7. Acknowledgments 1302 Much of the content and presentation of the caching design is due to 1303 suggestions and comments from individuals including: Shel Kaphan, 1304 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 1306 8. References 1308 8.1. Normative References 1310 [ISO-8859-1] 1311 International Organization for Standardization, 1312 "Information technology -- 8-bit single-byte coded graphic 1313 character sets -- Part 1: Latin alphabet No. 1", ISO/ 1314 IEC 8859-1:1998, 1998. 1316 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1317 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1318 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 1319 and Message Parsing", draft-ietf-httpbis-p1-messaging-07 1320 (work in progress), July 2009. 1322 [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1323 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1324 and J. Reschke, Ed., "HTTP/1.1, part 2: Message 1325 Semantics", draft-ietf-httpbis-p2-semantics-07 (work in 1326 progress), July 2009. 1328 [Part3] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1329 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1330 and J. Reschke, Ed., "HTTP/1.1, part 3: Message Payload 1331 and Content Negotiation", draft-ietf-httpbis-p3-payload-07 1332 (work in progress), July 2009. 1334 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1335 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1336 and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional 1337 Requests", draft-ietf-httpbis-p4-conditional-07 (work in 1338 progress), July 2009. 1340 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1341 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1342 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 1343 Partial Responses", draft-ietf-httpbis-p5-range-07 (work 1344 in progress), July 2009. 1346 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1347 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1348 and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", 1349 draft-ietf-httpbis-p7-auth-07 (work in progress), 1350 July 2009. 1352 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 1353 Part Three: Message Header Extensions for Non-ASCII Text", 1354 RFC 2047, November 1996. 1356 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1357 Requirement Levels", BCP 14, RFC 2119, March 1997. 1359 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1360 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1362 8.2. Informative References 1364 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1365 Specification, Implementation", RFC 1305, March 1992. 1367 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1368 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1369 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1371 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1372 Procedures for Message Header Fields", BCP 90, RFC 3864, 1373 September 2004. 1375 Appendix A. Compatibility with Previous Versions 1377 A.1. Changes from RFC 2068 1379 A case was missed in the Cache-Control model of HTTP/1.1; s-maxage 1380 was introduced to add this missing case. (Sections 2.1, 3.2). 1382 Transfer-coding and message lengths all interact in ways that 1383 required fixing exactly when chunked encoding is used (to allow for 1384 transfer encoding that may not be self delimiting); it was important 1385 to straighten out exactly how message lengths are computed. (see also 1386 [Part1], [Part3] and [Part5]) [[anchor17: This used to refer to the 1387 text about non-modifiable headers, and will have to be updated later 1388 on. --jre]] 1390 Proxies should be able to add Content-Length when appropriate. 1391 [[anchor18: This used to refer to the text about non-modifiable 1392 headers, and will have to be updated later on. --jre]] 1394 Range request responses would become very verbose if all meta-data 1395 were always returned; by allowing the server to only send needed 1396 headers in a 206 response, this problem can be avoided. 1397 (Section 2.7) 1399 The Cache-Control: max-age directive was not properly defined for 1400 responses. (Section 3.2.2) 1402 Warnings could be cached incorrectly, or not updated appropriately. 1403 (Section 2.3, 2.7, 3.2, and 3.6) Warning also needed to be a general 1404 header, as PUT or other methods may have need for it in requests. 1406 A.2. Changes from RFC 2616 1408 Clarify denial of service attack avoidance requirement. 1409 (Section 2.5) 1411 Appendix B. Collected ABNF 1413 Age = "Age:" OWS Age-v 1414 Age-v = delta-seconds 1416 Cache-Control = "Cache-Control:" OWS Cache-Control-v 1417 Cache-Control-v = *( "," OWS ) cache-directive *( OWS "," [ OWS 1418 cache-directive ] ) 1420 Expires = "Expires:" OWS Expires-v 1421 Expires-v = HTTP-date 1423 HTTP-date = 1425 OWS = 1427 Pragma = "Pragma:" OWS Pragma-v 1428 Pragma-v = *( "," OWS ) pragma-directive *( OWS "," [ OWS 1429 pragma-directive ] ) 1431 Vary = "Vary:" OWS Vary-v 1432 Vary-v = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name 1433 ] ) ) 1435 Warning = "Warning:" OWS Warning-v 1436 Warning-v = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value 1437 ] ) 1439 cache-directive = cache-request-directive / cache-response-directive 1440 cache-extension = token [ "=" ( token / quoted-string ) ] 1441 cache-request-directive = "no-cache" / "no-store" / ( "max-age=" 1442 delta-seconds ) / ( "max-stale" [ "=" delta-seconds ] ) / ( 1443 "min-fresh=" delta-seconds ) / "no-transform" / "only-if-cached" / 1444 cache-extension 1445 cache-response-directive = "public" / ( "private" [ "=" DQUOTE *( "," 1446 OWS ) field-name *( OWS "," [ OWS field-name ] ) DQUOTE ] ) / ( 1447 "no-cache" [ "=" DQUOTE *( "," OWS ) field-name *( OWS "," [ OWS 1448 field-name ] ) DQUOTE ] ) / "no-store" / "no-transform" / 1449 "must-revalidate" / "proxy-revalidate" / ( "max-age=" delta-seconds 1450 ) / ( "s-maxage=" delta-seconds ) / cache-extension 1452 delta-seconds = 1*DIGIT 1454 extension-pragma = token [ "=" ( token / quoted-string ) ] 1456 field-name = 1458 port = 1459 pragma-directive = "no-cache" / extension-pragma 1460 pseudonym = 1462 quoted-string = 1464 token = 1465 uri-host = 1467 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1468 warn-code = 3DIGIT 1469 warn-date = DQUOTE HTTP-date DQUOTE 1470 warn-text = quoted-string 1471 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date 1472 ] 1474 ABNF diagnostics: 1476 ; Age defined but not used 1477 ; Cache-Control defined but not used 1478 ; Expires defined but not used 1479 ; Pragma defined but not used 1480 ; Vary defined but not used 1481 ; Warning defined but not used 1483 Appendix C. Change Log (to be removed by RFC Editor before publication) 1485 C.1. Since RFC2616 1487 Extracted relevant partitions from [RFC2616]. 1489 C.2. Since draft-ietf-httpbis-p6-cache-00 1491 Closed issues: 1493 o : "Trailer" 1494 () 1496 o : "Invalidation 1497 after Update or Delete" 1498 () 1500 o : "Normative and 1501 Informative references" 1503 o : "Date reference 1504 typo" 1506 o : "Connection 1507 header text" 1509 o : "Informative 1510 references" 1512 o : "ISO-8859-1 1513 Reference" 1515 o : "Normative up- 1516 to-date references" 1518 o : "typo in 1519 13.2.2" 1521 Other changes: 1523 o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress 1524 on ) 1526 C.3. Since draft-ietf-httpbis-p6-cache-01 1528 Closed issues: 1530 o : "rel_path not 1531 used" 1533 Other changes: 1535 o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work 1536 in progress on ) 1538 o Add explicit references to BNF syntax and rules imported from 1539 other parts of the specification. 1541 C.4. Since draft-ietf-httpbis-p6-cache-02 1543 Ongoing work on IANA Message Header Registration 1544 (): 1546 o Reference RFC 3984, and update header registrations for headers 1547 defined in this document. 1549 C.5. Since draft-ietf-httpbis-p6-cache-03 1551 Closed issues: 1553 o : "Vary header 1554 classification" 1556 C.6. Since draft-ietf-httpbis-p6-cache-04 1558 Ongoing work on ABNF conversion 1559 (): 1561 o Use "/" instead of "|" for alternatives. 1563 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1564 whitespace ("OWS") and required whitespace ("RWS"). 1566 o Rewrite ABNFs to spell out whitespace rules, factor out header 1567 value format definitions. 1569 C.7. Since draft-ietf-httpbis-p6-cache-05 1571 This is a total rewrite of this part of the specification. 1573 Affected issues: 1575 o : "Definition of 1576 1xx Warn-Codes" 1578 o : "Placement 1579 of 13.5.1 and 13.5.2" 1581 o : "The role 1582 of Warning and Semantic Transparency in Caching" 1584 o : "Methods 1585 and Caching" 1587 In addition: Final work on ABNF conversion 1588 (): 1590 o Add appendix containing collected and expanded ABNF, reorganize 1591 ABNF introduction. 1593 C.8. Since draft-ietf-httpbis-p6-cache-06 1595 Closed issues: 1597 o : "base for 1598 numeric protocol elements" 1600 Affected issues: 1602 o : Vary and non- 1603 existant headers 1605 Index 1607 A 1608 age 6 1609 Age header 17 1611 C 1612 cache 5 1613 Cache Directives 1614 max-age 19, 21 1615 max-stale 19 1616 min-fresh 19 1617 must-revalidate 21 1618 no-cache 18, 20 1619 no-store 18, 21 1620 no-transform 19, 22 1621 only-if-cached 19 1622 private 20 1623 proxy-revalidate 21 1624 public 20 1625 s-maxage 22 1626 Cache-Control header 17 1627 cacheable 5 1629 E 1630 Expires header 23 1631 explicit expiration time 5 1633 F 1634 first-hand 6 1635 fresh 6 1636 freshness lifetime 6 1638 G 1639 Grammar 1640 Age 17 1641 Age-v 17 1642 Cache-Control 18 1643 Cache-Control-v 18 1644 cache-extension 18 1645 cache-request-directive 18 1646 cache-response-directive 20 1647 delta-seconds 17 1648 Expires 23 1649 Expires-v 23 1650 extension-pragma 24 1651 Pragma 24 1652 pragma-directive 24 1653 Pragma-v 24 1654 Vary 24 1655 Vary-v 24 1656 warn-agent 25 1657 warn-code 25 1658 warn-date 25 1659 warn-text 25 1660 Warning 25 1661 Warning-v 25 1662 warning-value 25 1664 H 1665 Headers 1666 Age 17 1667 Cache-Control 17 1668 Expires 23 1669 Pragma 23 1670 Vary 24 1671 Warning 25 1672 heuristic expiration time 5 1674 M 1675 max-age 1676 Cache Directive 19, 21 1677 max-stale 1678 Cache Directive 19 1679 min-fresh 1680 Cache Directive 19 1681 must-revalidate 1682 Cache Directive 21 1684 N 1685 no-cache 1686 Cache Directive 18, 20 1687 no-store 1688 Cache Directive 18, 21 1689 no-transform 1690 Cache Directive 19, 22 1692 O 1693 only-if-cached 1694 Cache Directive 19 1696 P 1697 Pragma header 23 1698 private 1699 Cache Directive 20 1700 proxy-revalidate 1701 Cache Directive 21 1702 public 1703 Cache Directive 20 1705 S 1706 s-maxage 1707 Cache Directive 22 1708 stale 6 1710 V 1711 validator 6 1712 Vary header 24 1714 W 1715 Warning header 25 1717 Authors' Addresses 1719 Roy T. Fielding (editor) 1720 Day Software 1721 23 Corporate Plaza DR, Suite 280 1722 Newport Beach, CA 92660 1723 USA 1725 Phone: +1-949-706-5300 1726 Fax: +1-949-706-5305 1727 Email: fielding@gbiv.com 1728 URI: http://roy.gbiv.com/ 1730 Jim Gettys 1731 One Laptop per Child 1732 21 Oak Knoll Road 1733 Carlisle, MA 01741 1734 USA 1736 Email: jg@laptop.org 1737 URI: http://www.laptop.org/ 1738 Jeffrey C. Mogul 1739 Hewlett-Packard Company 1740 HP Labs, Large Scale Systems Group 1741 1501 Page Mill Road, MS 1177 1742 Palo Alto, CA 94304 1743 USA 1745 Email: JeffMogul@acm.org 1747 Henrik Frystyk Nielsen 1748 Microsoft Corporation 1749 1 Microsoft Way 1750 Redmond, WA 98052 1751 USA 1753 Email: henrikn@microsoft.com 1755 Larry Masinter 1756 Adobe Systems, Incorporated 1757 345 Park Ave 1758 San Jose, CA 95110 1759 USA 1761 Email: LMM@acm.org 1762 URI: http://larry.masinter.net/ 1764 Paul J. Leach 1765 Microsoft Corporation 1766 1 Microsoft Way 1767 Redmond, WA 98052 1769 Email: paulle@microsoft.com 1771 Tim Berners-Lee 1772 World Wide Web Consortium 1773 MIT Computer Science and Artificial Intelligence Laboratory 1774 The Stata Center, Building 32 1775 32 Vassar Street 1776 Cambridge, MA 02139 1777 USA 1779 Email: timbl@w3.org 1780 URI: http://www.w3.org/People/Berners-Lee/ 1781 Yves Lafon (editor) 1782 World Wide Web Consortium 1783 W3C / ERCIM 1784 2004, rte des Lucioles 1785 Sophia-Antipolis, AM 06902 1786 France 1788 Email: ylafon@w3.org 1789 URI: http://www.raubacapeu.net/people/yves/ 1791 Mark Nottingham (editor) 1793 Email: mnot@mnot.net 1794 URI: http://www.mnot.net/ 1796 Julian F. Reschke (editor) 1797 greenbytes GmbH 1798 Hafenweg 16 1799 Muenster, NW 48155 1800 Germany 1802 Phone: +49 251 2807760 1803 Fax: +49 251 2807761 1804 Email: julian.reschke@greenbytes.de 1805 URI: http://greenbytes.de/tech/webdav/