idnits 2.17.1 draft-ietf-httpbis-p6-cache-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 12, 2010) is 5030 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-10 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-10 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-10 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-10 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-10 -- Obsolete informational reference (is this intentional?): RFC 1305 (Obsoleted by RFC 5905) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis Working Group R. Fielding, Ed. 3 Internet-Draft Day Software 4 Obsoletes: 2616 (if approved) J. Gettys 5 Intended status: Standards Track Alcatel-Lucent 6 Expires: January 13, 2011 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 12, 2010 24 HTTP/1.1, part 6: Caching 25 draft-ietf-httpbis-p6-cache-10 27 Abstract 29 The Hypertext Transfer Protocol (HTTP) is an application-level 30 protocol for distributed, collaborative, hypermedia information 31 systems. This document is Part 6 of the seven-part specification 32 that defines the protocol referred to as "HTTP/1.1" and, taken 33 together, obsoletes RFC 2616. Part 6 defines requirements on HTTP 34 caches and the associated header fields that control cache behavior 35 or indicate cacheable response messages. 37 Editorial Note (To be removed by RFC Editor) 39 Discussion of this draft should take place on the HTTPBIS working 40 group mailing list (ietf-http-wg@w3.org). The current issues list is 41 at and related 42 documents (including fancy diffs) can be found at 43 . 45 The changes in this draft are summarized in Appendix C.11. 47 Status of This Memo 48 This Internet-Draft is submitted in full conformance with the 49 provisions of BCP 78 and BCP 79. 51 Internet-Drafts are working documents of the Internet Engineering 52 Task Force (IETF). Note that other groups may also distribute 53 working documents as Internet-Drafts. The list of current Internet- 54 Drafts is at http://datatracker.ietf.org/drafts/current/. 56 Internet-Drafts are draft documents valid for a maximum of six months 57 and may be updated, replaced, or obsoleted by other documents at any 58 time. It is inappropriate to use Internet-Drafts as reference 59 material or to cite them other than as "work in progress." 61 This Internet-Draft will expire on January 13, 2011. 63 Copyright Notice 65 Copyright (c) 2010 IETF Trust and the persons identified as the 66 document authors. All rights reserved. 68 This document is subject to BCP 78 and the IETF Trust's Legal 69 Provisions Relating to IETF Documents 70 (http://trustee.ietf.org/license-info) in effect on the date of 71 publication of this document. Please review these documents 72 carefully, as they describe your rights and restrictions with respect 73 to this document. Code Components extracted from this document must 74 include Simplified BSD License text as described in Section 4.e of 75 the Trust Legal Provisions and are provided without warranty as 76 described in the Simplified BSD License. 78 This document may contain material from IETF Documents or IETF 79 Contributions published or made publicly available before November 80 10, 2008. The person(s) controlling the copyright in some of this 81 material may not have granted the IETF Trust the right to allow 82 modifications of such material outside the IETF Standards Process. 83 Without obtaining an adequate license from the person(s) controlling 84 the copyright in such materials, this document may not be modified 85 outside the IETF Standards Process, and derivative works of it may 86 not be created outside the IETF Standards Process, except to format 87 it for publication as an RFC or to translate it into languages other 88 than English. 90 Table of Contents 92 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 93 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 94 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 95 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 6 96 1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 97 1.4.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 7 98 1.4.2. ABNF Rules defined in other Parts of the 99 Specification . . . . . . . . . . . . . . . . . . . . 7 100 2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 7 101 2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 7 102 2.1.1. Storing Partial and Incomplete Responses . . . . . . . 8 103 2.2. Constructing Responses from Caches . . . . . . . . . . . . 9 104 2.3. Freshness Model . . . . . . . . . . . . . . . . . . . . . 10 105 2.3.1. Calculating Freshness Lifetime . . . . . . . . . . . . 11 106 2.3.2. Calculating Age . . . . . . . . . . . . . . . . . . . 12 107 2.3.3. Serving Stale Responses . . . . . . . . . . . . . . . 13 108 2.4. Validation Model . . . . . . . . . . . . . . . . . . . . . 14 109 2.5. Request Methods that Invalidate . . . . . . . . . . . . . 14 110 2.6. Shared Caching of Authenticated Responses . . . . . . . . 15 111 2.7. Caching Negotiated Responses . . . . . . . . . . . . . . . 16 112 2.8. Combining Responses . . . . . . . . . . . . . . . . . . . 16 113 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 17 114 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 115 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 18 116 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 19 117 3.2.2. Response Cache-Control Directives . . . . . . . . . . 20 118 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 23 119 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 24 120 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 25 121 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 122 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 26 123 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 29 124 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 125 5.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 29 126 5.2. Message Header Registration . . . . . . . . . . . . . . . 30 127 6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 128 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30 129 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 130 8.1. Normative References . . . . . . . . . . . . . . . . . . . 30 131 8.2. Informative References . . . . . . . . . . . . . . . . . . 31 132 Appendix A. Compatibility with Previous Versions . . . . . . . . 32 133 A.1. Changes from RFC 2068 . . . . . . . . . . . . . . . . . . 32 134 A.2. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 32 135 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 32 136 Appendix C. Change Log (to be removed by RFC Editor before 137 publication) . . . . . . . . . . . . . . . . . . . . 34 138 C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 34 139 C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 34 140 C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 35 141 C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 35 142 C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 35 143 C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 35 144 C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 36 145 C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 36 146 C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 36 147 C.10. Since draft-ietf-httpbis-p6-cache-08 . . . . . . . . . . . 37 148 C.11. Since draft-ietf-httpbis-p6-cache-09 . . . . . . . . . . . 37 149 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 151 1. Introduction 153 HTTP is typically used for distributed information systems, where 154 performance can be improved by the use of response caches. This 155 document defines aspects of HTTP/1.1 related to caching and reusing 156 response messages. 158 1.1. Purpose 160 An HTTP cache is a local store of response messages and the subsystem 161 that controls its message storage, retrieval, and deletion. A cache 162 stores cacheable responses in order to reduce the response time and 163 network bandwidth consumption on future, equivalent requests. Any 164 client or server may include a cache, though a cache cannot be used 165 by a server that is acting as a tunnel. 167 Caching would be useless if it did not significantly improve 168 performance. The goal of caching in HTTP/1.1 is to reuse a prior 169 response message to satisfy a current request. In some cases, a 170 stored response can be reused without the need for a network request, 171 reducing latency and network round-trips; a "freshness" mechanism is 172 used for this purpose (see Section 2.3). Even when a new request is 173 required, it is often possible to reuse all or parts of the payload 174 of a prior response to satisfy the request, thereby reducing network 175 bandwidth usage; a "validation" mechanism is used for this purpose 176 (see Section 2.4). 178 1.2. Terminology 180 This specification uses a number of terms to refer to the roles 181 played by participants in, and objects of, HTTP caching. 183 cacheable 185 A response is cacheable if a cache is allowed to store a copy of 186 the response message for use in answering subsequent requests. 187 Even when a response is cacheable, there may be additional 188 constraints on whether a cache can use the cached copy to satisfy 189 a particular request. 191 explicit expiration time 193 The time at which the origin server intends that an entity should 194 no longer be returned by a cache without further validation. 196 heuristic expiration time 198 An expiration time assigned by a cache when no explicit expiration 199 time is available. 201 age 203 The age of a response is the time since it was sent by, or 204 successfully validated with, the origin server. 206 first-hand 208 A response is first-hand if the freshness model is not in use; 209 i.e., its age is 0. 211 freshness lifetime 213 The length of time between the generation of a response and its 214 expiration time. 216 fresh 218 A response is fresh if its age has not yet exceeded its freshness 219 lifetime. 221 stale 223 A response is stale if its age has passed its freshness lifetime 224 (either explicit or heuristic). 226 validator 228 A protocol element (e.g., an entity tag or a Last-Modified time) 229 that is used to find out whether a stored response is an 230 equivalent copy of an entity. 232 shared cache 234 A cache that is accessible to more than one user. A non-shared 235 cache is dedicated to a single user. 237 1.3. Requirements 239 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 240 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 241 document are to be interpreted as described in [RFC2119]. 243 An implementation is not compliant if it fails to satisfy one or more 244 of the "MUST" or "REQUIRED" level requirements for the protocols it 245 implements. An implementation that satisfies all the "MUST" or 246 "REQUIRED" level and all the "SHOULD" level requirements for its 247 protocols is said to be "unconditionally compliant"; one that 248 satisfies all the "MUST" level requirements but not all the "SHOULD" 249 level requirements for its protocols is said to be "conditionally 250 compliant". 252 1.4. Syntax Notation 254 This specification uses the ABNF syntax defined in Section 1.2 of 255 [Part1] (which extends the syntax defined in [RFC5234] with a list 256 rule). Appendix B shows the collected ABNF, with the list rule 257 expanded. 259 The following core rules are included by reference, as defined in 260 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 261 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 262 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 263 sequence of data), SP (space), VCHAR (any visible USASCII character), 264 and WSP (whitespace). 266 1.4.1. Core Rules 268 The core rules below are defined in Section 1.2.2 of [Part1]: 270 quoted-string = 271 token = 272 OWS = 274 1.4.2. ABNF Rules defined in other Parts of the Specification 276 The ABNF rules below are defined in other parts: 278 field-name = 279 HTTP-date = 280 port = 281 pseudonym = 282 uri-host = 284 2. Cache Operation 286 2.1. Response Cacheability 288 A cache MUST NOT store a response to any request, unless: 290 o The request method is understood by the cache and defined as being 291 cacheable, and 293 o the response status code is understood by the cache, and 295 o the "no-store" cache directive (see Section 3.2) does not appear 296 in request or response headers, and 298 o the "private" cache response directive (see Section 3.2.2 does not 299 appear in the response, if the cache is shared, and 301 o the "Authorization" header (see Section 3.1 of [Part7]) does not 302 appear in the request, if the cache is shared, unless the response 303 explicitly allows it (see Section 2.6), and 305 o the response either: 307 * contains an Expires header (see Section 3.3), or 309 * contains a max-age response cache directive (see 310 Section 3.2.2), or 312 * contains a s-maxage response cache directive and the cache is 313 shared, or 315 * contains a Cache Control Extension (see Section 3.2.3) that 316 allows it to be cached, or 318 * has a status code that can be served with heuristic freshness 319 (see Section 2.3.1.1). 321 In this context, a cache has "understood" a request method or a 322 response status code if it recognises it and implements any cache- 323 specific behaviour. In particular, 206 Partial Content responses 324 cannot be cached by an implementation that does not handle partial 325 content (see Section 2.1.1). 327 Note that in normal operation, most caches will not store a response 328 that has neither a cache validator nor an explicit expiration time, 329 as such responses are not usually useful to store. However, caches 330 are not prohibited from storing such responses. 332 2.1.1. Storing Partial and Incomplete Responses 334 A cache that receives an incomplete response (for example, with fewer 335 bytes of data than specified in a Content-Length header) can store 336 the response, but MUST treat it as a partial response [Part5]. 337 Partial responses can be combined as described in Section 4 of 338 [Part5]; the result might be a full response or might still be 339 partial. A cache MUST NOT return a partial response to a client 340 without explicitly marking it as such using the 206 (Partial Content) 341 status code. 343 A cache that does not support the Range and Content-Range headers 344 MUST NOT store incomplete or partial responses. 346 2.2. Constructing Responses from Caches 348 For a presented request, a cache MUST NOT return a stored response, 349 unless: 351 o The presented Effective Request URI (Section 4.3 of [Part1]) and 352 that of the stored response match, and 354 o the request method associated with the stored response allows it 355 to be used for the presented request, and 357 o selecting request-headers nominated by the stored response (if 358 any) match those presented (see Section 2.7), and 360 o the presented request and stored response are free from directives 361 that would prevent its use (see Section 3.2 and Section 3.4), and 363 o the stored response is either: 365 * fresh (see Section 2.3), or 367 * allowed to be served stale (see Section 2.3.3), or 369 * successfully validated (see Section 2.4). 371 [[TODO-method-cacheability: define method cacheability for GET, HEAD 372 and POST in p2-semantics.]] 374 When a stored response is used to satisfy a request, caches MUST 375 include a single Age header field (Section 3.1) in the response with 376 a value equal to the stored response's current_age; see 377 Section 2.3.2. [[DISCUSS-includes-validated: this currently includes 378 successfully validated responses.]] 380 Requests with methods that are unsafe (Section 7.1.1 of [Part2]) MUST 381 be written through the cache to the origin server; i.e., a cache must 382 not reply to such a request before having forwarded the request and 383 having received a corresponding response. 385 Also, note that unsafe requests might invalidate already stored 386 responses; see Section 2.5. 388 Caches MUST use the most recent response (as determined by the Date 389 header) when more than one suitable response is stored. They can 390 also forward a request with "Cache-Control: max-age=0" or "Cache- 391 Control: no-cache" to disambiguate which response to use. 393 2.3. Freshness Model 395 When a response is "fresh" in the cache, it can be used to satisfy 396 subsequent requests without contacting the origin server, thereby 397 improving efficiency. 399 The primary mechanism for determining freshness is for an origin 400 server to provide an explicit expiration time in the future, using 401 either the Expires header (Section 3.3) or the max-age response cache 402 directive (Section 3.2.2). Generally, origin servers will assign 403 future explicit expiration times to responses in the belief that the 404 entity is not likely to change in a semantically significant way 405 before the expiration time is reached. 407 If an origin server wishes to force a cache to validate every 408 request, it can assign an explicit expiration time in the past. This 409 means that the response is always stale, so that caches should 410 validate it before using it for subsequent requests. [[TODO- 411 response-stale: This wording may cause confusion, because the 412 response may still be served stale.]] 414 Since origin servers do not always provide explicit expiration times, 415 HTTP caches may also assign heuristic expiration times when they are 416 not specified, employing algorithms that use other header values 417 (such as the Last-Modified time) to estimate a plausible expiration 418 time. The HTTP/1.1 specification does not provide specific 419 algorithms, but does impose worst-case constraints on their results. 421 The calculation to determine if a response is fresh is: 423 response_is_fresh = (freshness_lifetime > current_age) 425 The freshness_lifetime is defined in Section 2.3.1; the current_age 426 is defined in Section 2.3.2. 428 Additionally, clients may need to influence freshness calculation. 429 They can do this using several request cache directives, with the 430 effect of either increasing or loosening constraints on freshness. 431 See Section 3.2.1. 433 [[ISSUE-no-req-for-directives: there are not requirements directly 434 applying to cache-request-directives and freshness.]] 436 Note that freshness applies only to cache operation; it cannot be 437 used to force a user agent to refresh its display or reload a 438 resource. See Section 4 for an explanation of the difference between 439 caches and history mechanisms. 441 2.3.1. Calculating Freshness Lifetime 443 A cache can calculate the freshness lifetime (denoted as 444 freshness_lifetime) of a response by using the first match of: 446 o If the cache is shared and the s-maxage response cache directive 447 (Section 3.2.2) is present, use its value, or 449 o If the max-age response cache directive (Section 3.2.2) is 450 present, use its value, or 452 o If the Expires response header (Section 3.3) is present, use its 453 value minus the value of the Date response header, or 455 o Otherwise, no explicit expiration time is present in the response. 456 A heuristic freshness lifetime might be applicable; see 457 Section 2.3.1.1. 459 Note that this calculation is not vulnerable to clock skew, since all 460 of the information comes from the origin server. 462 2.3.1.1. Calculating Heuristic Freshness 464 If no explicit expiration time is present in a stored response that 465 has a status code of 200, 203, 206, 300, 301 or 410, a heuristic 466 expiration time can be calculated. Heuristics MUST NOT be used for 467 other response status codes. 469 When a heuristic is used to calculate freshness lifetime, the cache 470 SHOULD attach a Warning header with a 113 warn-code to the response 471 if its current_age is more than 24 hours and such a warning is not 472 already present. 474 Also, if the response has a Last-Modified header (Section 6.6 of 475 [Part4]), the heuristic expiration value SHOULD be no more than some 476 fraction of the interval since that time. A typical setting of this 477 fraction might be 10%. 479 Note: RFC 2616 ([RFC2616], Section 13.9) required that caches do 480 not calculate heuristic freshness for URLs with query components 481 (i.e., those containing '?'). In practice, this has not been 482 widely implemented. Therefore, servers are encouraged to send 483 explicit directives (e.g., Cache-Control: no-cache) if they wish 484 to preclude caching. 486 2.3.2. Calculating Age 488 HTTP/1.1 uses the Age response-header to convey the estimated age of 489 the response message when obtained from a cache. The Age field value 490 is the cache's estimate of the amount of time since the response was 491 generated or validated by the origin server. In essence, the Age 492 value is the sum of the time that the response has been resident in 493 each of the caches along the path from the origin server, plus the 494 amount of time it has been in transit along network paths. 496 The following data is used for the age calculation: 498 age_value 500 The term "age_value" denotes the value of the Age header 501 (Section 3.1), in a form appropriate for arithmetic operation; or 502 0, if not available. 504 date_value 506 HTTP/1.1 requires origin servers to send a Date header, if 507 possible, with every response, giving the time at which the 508 response was generated. The term "date_value" denotes the value 509 of the Date header, in a form appropriate for arithmetic 510 operations. See Section 9.3 of [Part1] for the definition of the 511 Date header, and for requirements regarding responses without a 512 Date response header. 514 now 516 The term "now" means "the current value of the clock at the host 517 performing the calculation". Hosts that use HTTP, but especially 518 hosts running origin servers and caches, SHOULD use NTP 519 ([RFC1305]) or some similar protocol to synchronize their clocks 520 to a globally accurate time standard. 522 request_time 524 The current value of the clock at the host at the time the request 525 resulting in the stored response was made. 527 response_time 529 The current value of the clock at the host at the time the 530 response was received. 532 A response's age can be calculated in two entirely independent ways: 534 1. the "apparent_age": response_time minus date_value, if the local 535 clock is reasonably well synchronized to the origin server's 536 clock. If the result is negative, the result is replaced by 537 zero. 539 2. the "corrected_age_value", if all of the caches along the 540 response path implement HTTP/1.1; note this value MUST be 541 interpreted relative to the time the request was initiated, not 542 the time that the response was received. 544 apparent_age = max(0, response_time - date_value); 546 response_delay = response_time - request_time; 547 corrected_age_value = age_value + response_delay; 549 These are combined as 551 corrected_initial_age = max(apparent_age, corrected_age_value); 553 The current_age of a stored response can then be calculated by adding 554 the amount of time (in seconds) since the stored response was last 555 validated by the origin server to the corrected_initial_age. 557 resident_time = now - response_time; 558 current_age = corrected_initial_age + resident_time; 560 2.3.3. Serving Stale Responses 562 A "stale" response is one that either has explicit expiry information 563 or is allowed to have heuristic expiry calculated, but is not fresh 564 according to the calculations in Section 2.3. 566 Caches MUST NOT return a stale response if it is prohibited by an 567 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" 568 cache directive, a "must-revalidate" cache-response-directive, or an 569 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 570 see Section 3.2.2). 572 Caches SHOULD NOT return stale responses unless they are disconnected 573 (i.e., it cannot contact the origin server or otherwise find a 574 forward path) or otherwise explicitly allowed (e.g., the max-stale 575 request directive; see Section 3.2.1). 577 Stale responses SHOULD have a Warning header with the 110 warn-code 578 (see Section 3.6). Likewise, the 112 warn-code SHOULD be sent on 579 stale responses if the cache is disconnected. 581 If a cache receives a first-hand response (either an entire response, 582 or a 304 (Not Modified) response) that it would normally forward to 583 the requesting client, and the received response is no longer fresh, 584 the cache SHOULD forward it to the requesting client without adding a 585 new Warning (but without removing any existing Warning headers). A 586 cache SHOULD NOT attempt to validate a response simply because that 587 response became stale in transit. 589 2.4. Validation Model 591 When a cache has one or more stored responses for a requested URI, 592 but cannot serve any of them (e.g., because they are not fresh, or 593 one cannot be selected; see Section 2.7), it can use the conditional 594 request mechanism [Part4] in the forwarded request to give the origin 595 server an opportunity to both select a valid stored response to be 596 used, and to update it. This process is known as "validating" or 597 "revalidating" the stored response. 599 When sending such a conditional request, the cache SHOULD add an If- 600 Modified-Since header whose value is that of the Last-Modified header 601 from the selected (see Section 2.7) stored response, if available. 603 Additionally, the cache SHOULD add an If-None-Match header whose 604 value is that of the ETag header(s) from all responses stored for the 605 requested URI, if present. However, if any of the stored responses 606 contains only partial content, its entity-tag SHOULD NOT be included 607 in the If-None-Match header field unless the request is for a range 608 that would be fully satisfied by that stored response. 610 A 304 (Not Modified) response status code indicates that the stored 611 response can be updated and reused; see Section 2.8. 613 A full response (i.e., one with a response body) indicates that none 614 of the stored responses nominated in the conditional request is 615 suitable. Instead, the full response is used both to satisfy the 616 request and replace the stored response. [[TODO-req-missing: Should 617 there be a requirement here?]] 619 If a cache receives a 5xx response while attempting to validate a 620 response, it MAY either forward this response to the requesting 621 client, or act as if the server failed to respond. In the latter 622 case, it MAY return a previously stored response (see Section 2.3.3). 624 2.5. Request Methods that Invalidate 626 Because unsafe methods (Section 7.1.1 of [Part2]) have the potential 627 for changing state on the origin server, intervening caches can use 628 them to keep their contents up-to-date. 630 The following HTTP methods MUST cause a cache to invalidate the 631 Effective Request URI (Section 4.3 of [Part1]) as well as the URI(s) 632 in the Location and Content-Location headers (if present): 634 o PUT 636 o DELETE 638 o POST 640 An invalidation based on a URI from a Location or Content-Location 641 header MUST NOT be performed if the host part of that URI differs 642 from the host part in the Effective Request URI (Section 4.3 of 643 [Part1]). This helps prevent denial of service attacks. 645 [[TODO-def-host-part: "host part" needs to be specified better.]] 647 A cache that passes through requests for methods it does not 648 understand SHOULD invalidate the Effective Request URI (Section 4.3 649 of [Part1]). 651 Here, "invalidate" means that the cache will either remove all stored 652 responses related to the Effective Request URI, or will mark these as 653 "invalid" and in need of a mandatory validation before they can be 654 returned in response to a subsequent request. 656 Note that this does not guarantee that all appropriate responses are 657 invalidated. For example, the request that caused the change at the 658 origin server might not have gone through the cache where a response 659 is stored. 661 [[TODO-spec-success-invalidate: specify that only successful (2xx, 662 3xx?) responses invalidate.]] 664 2.6. Shared Caching of Authenticated Responses 666 Shared caches MUST NOT use a cached response to a request with an 667 Authorization header (Section 3.1 of [Part7]) to satisfy any 668 subsequent request unless a cache directive that allows such 669 responses to be stored is present in the response. 671 In this specification, the following Cache-Control response 672 directives (Section 3.2.2) have such an effect: must-revalidate, 673 public, s-maxage. 675 Note that cached responses that contain the "must-revalidate" and/or 676 "s-maxage" response directives are not allowed to be served stale 677 (Section 2.3.3) by shared caches. In particular, a response with 678 either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to 679 satisfy a subsequent request without revalidating it on the origin 680 server. 682 2.7. Caching Negotiated Responses 684 When a cache receives a request that can be satisfied by a stored 685 response that has a Vary header field (Section 3.5), it MUST NOT use 686 that response unless all of the selecting request-headers nominated 687 by the Vary header match in both the original request (i.e., that 688 associated with the stored response), and the presented request. 690 The selecting request-headers from two requests are defined to match 691 if and only if those in the first request can be transformed to those 692 in the second request by applying any of the following: 694 o adding or removing whitespace, where allowed in the header's 695 syntax 697 o combining multiple message-header fields with the same field name 698 (see Section 3.2 of [Part1]) 700 o normalizing both header values in a way that is known to have 701 identical semantics, according to the header's specification 702 (e.g., re-ordering field values when order is not significant; 703 case-normalization, where values are defined to be case- 704 insensitive) 706 If (after any normalisation that may take place) a header field is 707 absent from a request, it can only match another request if it is 708 also absent there. 710 A Vary header field-value of "*" always fails to match, and 711 subsequent requests to that resource can only be properly interpreted 712 by the origin server. 714 The stored response with matching selecting request-headers is known 715 as the selected response. 717 If no selected response is available, the cache MAY forward the 718 presented request to the origin server in a conditional request; see 719 Section 2.4. 721 2.8. Combining Responses 723 When a cache receives a 304 (Not Modified) response or a 206 (Partial 724 Content) response (in this section, the "new" response"), it needs to 725 created an updated response by combining the stored response with the 726 new one, so that the updated response can be used to satisfy the 727 request. 729 If the new response contains an ETag, it identifies the stored 730 response to use. [[TODO-mention-CL: may need language about Content- 731 Location here]][[TODO-inm-mult-etags: cover case where INM with 732 multiple etags was sent]] 734 If the status code is 206 (partial content), both the stored and new 735 responses MUST have validators, and those validators MUST match using 736 the strong comparison function (see Section 4 of [Part4]). 737 Otherwise, the responses MUST NOT be combined. 739 The stored response headers are used as those of the updated 740 response, except that 742 o any stored Warning headers with warn-code 1xx (see Section 3.6) 743 MUST be deleted from the stored response and the updated response. 745 o any stored Warning headers with warn-code 2xx MUST be retained in 746 the stored response and the updated response. 748 o any headers provided in the new response MUST replace the 749 corresponding headers from the stored response. 751 If a header field-name in the new response matches more than one 752 header in the stored response, all such stored headers MUST be 753 replaced. 755 The updated response can [[TODO-is-req: requirement?]] be used to 756 replace the stored response in cache. In the case of a 206 response, 757 the combined entity-body MAY be stored. 759 [[ISSUE-how-head: discuss how to handle HEAD updates]] 761 3. Header Field Definitions 763 This section defines the syntax and semantics of HTTP/1.1 header 764 fields related to caching. 766 For entity-header fields, both sender and recipient refer to either 767 the client or the server, depending on who sends and who receives the 768 entity. 770 3.1. Age 772 The "Age" response-header field conveys the sender's estimate of the 773 amount of time since the response was generated or successfully 774 validated at the origin server. Age values are calculated as 775 specified in Section 2.3.2. 777 Age = "Age" ":" OWS Age-v 778 Age-v = delta-seconds 780 Age field-values are non-negative integers, representing time in 781 seconds. 783 delta-seconds = 1*DIGIT 785 If a cache receives a value larger than the largest positive integer 786 it can represent, or if any of its age calculations overflows, it 787 MUST transmit an Age header with a field-value of 2147483648 (2^31). 788 Caches SHOULD use an arithmetic type of at least 31 bits of range. 790 The presence of an Age header field in a response implies that a 791 response is not first-hand. However, the converse is not true, since 792 HTTP/1.0 caches may not implement the Age header field. 794 3.2. Cache-Control 796 The "Cache-Control" general-header field is used to specify 797 directives for caches along the request/response chain. Such cache 798 directives are unidirectional in that the presence of a directive in 799 a request does not imply that the same directive is to be given in 800 the response. 802 HTTP/1.1 caches MUST obey the requirements of the Cache-Control 803 directives defined in this section. See Section 3.2.3 for 804 information about how Cache-Control directives defined elsewhere are 805 handled. 807 Note: HTTP/1.0 caches might not implement Cache-Control and might 808 only implement Pragma: no-cache (see Section 3.4). 810 Cache directives MUST be passed through by a proxy or gateway 811 application, regardless of their significance to that application, 812 since the directives might be applicable to all recipients along the 813 request/response chain. It is not possible to target a directive to 814 a specific cache. 816 Cache-Control = "Cache-Control" ":" OWS Cache-Control-v 817 Cache-Control-v = 1#cache-directive 819 cache-directive = cache-request-directive 820 / cache-response-directive 822 cache-extension = token [ "=" ( token / quoted-string ) ] 824 3.2.1. Request Cache-Control Directives 826 cache-request-directive = 827 "no-cache" 828 / "no-store" 829 / "max-age" "=" delta-seconds 830 / "max-stale" [ "=" delta-seconds ] 831 / "min-fresh" "=" delta-seconds 832 / "no-transform" 833 / "only-if-cached" 834 / cache-extension 836 no-cache 838 The no-cache request directive indicates that a stored response 839 MUST NOT be used to satisfy the request without successful 840 validation on the origin server. 842 no-store 844 The no-store request directive indicates that a cache MUST NOT 845 store any part of either this request or any response to it. This 846 directive applies to both non-shared and shared caches. "MUST NOT 847 store" in this context means that the cache MUST NOT intentionally 848 store the information in non-volatile storage, and MUST make a 849 best-effort attempt to remove the information from volatile 850 storage as promptly as possible after forwarding it. 852 This directive is NOT a reliable or sufficient mechanism for 853 ensuring privacy. In particular, malicious or compromised caches 854 might not recognize or obey this directive, and communications 855 networks may be vulnerable to eavesdropping. 857 max-age 859 The max-age request directive indicates that the client is willing 860 to accept a response whose age is no greater than the specified 861 time in seconds. Unless the max-stale request directive is also 862 present, the client is not willing to accept a stale response. 864 max-stale 866 The max-stale request directive indicates that the client is 867 willing to accept a response that has exceeded its expiration 868 time. If max-stale is assigned a value, then the client is 869 willing to accept a response that has exceeded its expiration time 870 by no more than the specified number of seconds. If no value is 871 assigned to max-stale, then the client is willing to accept a 872 stale response of any age. [[TODO-staleness: of any staleness? 873 --mnot]] 875 min-fresh 877 The min-fresh request directive indicates that the client is 878 willing to accept a response whose freshness lifetime is no less 879 than its current age plus the specified time in seconds. That is, 880 the client wants a response that will still be fresh for at least 881 the specified number of seconds. 883 no-transform 885 The no-transform request directive indicates that an intermediate 886 cache or proxy MUST NOT change the Content-Encoding, Content-Range 887 or Content-Type request headers, nor the request entity-body. 889 only-if-cached 891 The only-if-cached request directive indicates that the client 892 only wishes to return a stored response. If it receives this 893 directive, a cache SHOULD either respond using a stored response 894 that is consistent with the other constraints of the request, or 895 respond with a 504 (Gateway Timeout) status. If a group of caches 896 is being operated as a unified system with good internal 897 connectivity, such a request MAY be forwarded within that group of 898 caches. 900 3.2.2. Response Cache-Control Directives 902 cache-response-directive = 903 "public" 904 / "private" [ "=" DQUOTE 1#field-name DQUOTE ] 905 / "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] 906 / "no-store" 907 / "no-transform" 908 / "must-revalidate" 909 / "proxy-revalidate" 910 / "max-age" "=" delta-seconds 911 / "s-maxage" "=" delta-seconds 912 / cache-extension 914 public 916 The public response directive indicates that the response MAY be 917 cached, even if it would normally be non-cacheable or cacheable 918 only within a non-shared cache. (See also Authorization, Section 919 3.1 of [Part7], for additional details.) 921 private 923 The private response directive indicates that the response message 924 is intended for a single user and MUST NOT be stored by a shared 925 cache. A private (non-shared) cache MAY store the response. 927 If the private response directive specifies one or more field- 928 names, this requirement is limited to the field-values associated 929 with the listed response headers. That is, the specified field- 930 names(s) MUST NOT be stored by a shared cache, whereas the 931 remainder of the response message MAY be. 933 Note: This usage of the word private only controls where the 934 response may be stored, and cannot ensure the privacy of the 935 message content. Also, private response directives with field- 936 names are often handled by implementations as if an unqualified 937 private directive was received; i.e., the special handling for the 938 qualified form is not widely implemented. 940 no-cache 942 The no-cache response directive indicates that the response MUST 943 NOT be used to satisfy a subsequent request without successful 944 validation on the origin server. This allows an origin server to 945 prevent caching even by caches that have been configured to return 946 stale responses. 948 If the no-cache response directive specifies one or more field- 949 names, this requirement is limited to the field-values associated 950 with the listed response headers. That is, the specified field- 951 name(s) MUST NOT be sent in the response to a subsequent request 952 without successful validation on the origin server. This allows 953 an origin server to prevent the re-use of certain header fields in 954 a response, while still allowing caching of the rest of the 955 response. 957 Note: Most HTTP/1.0 caches will not recognize or obey this 958 directive. Also, no-cache response directives with field-names 959 are often handled by implementations as if an unqualified no-cache 960 directive was received; i.e., the special handling for the 961 qualified form is not widely implemented. 963 no-store 965 The no-store response directive indicates that a cache MUST NOT 966 store any part of either the immediate request or response. This 967 directive applies to both non-shared and shared caches. "MUST NOT 968 store" in this context means that the cache MUST NOT intentionally 969 store the information in non-volatile storage, and MUST make a 970 best-effort attempt to remove the information from volatile 971 storage as promptly as possible after forwarding it. 973 This directive is NOT a reliable or sufficient mechanism for 974 ensuring privacy. In particular, malicious or compromised caches 975 might not recognize or obey this directive, and communications 976 networks may be vulnerable to eavesdropping. 978 must-revalidate 980 The must-revalidate response directive indicates that once it has 981 become stale, the response MUST NOT be used to satisfy subsequent 982 requests without successful validation on the origin server. 984 The must-revalidate directive is necessary to support reliable 985 operation for certain protocol features. In all circumstances an 986 HTTP/1.1 cache MUST obey the must-revalidate directive; in 987 particular, if the cache cannot reach the origin server for any 988 reason, it MUST generate a 504 (Gateway Timeout) response. 990 Servers SHOULD send the must-revalidate directive if and only if 991 failure to validate a request on the entity could result in 992 incorrect operation, such as a silently unexecuted financial 993 transaction. 995 proxy-revalidate 997 The proxy-revalidate response directive has the same meaning as 998 the must-revalidate response directive, except that it does not 999 apply to non-shared caches. 1001 max-age 1003 The max-age response directive indicates that response is to be 1004 considered stale after its age is greater than the specified 1005 number of seconds. 1007 s-maxage 1009 The s-maxage response directive indicates that, in shared caches, 1010 the maximum age specified by this directive overrides the maximum 1011 age specified by either the max-age directive or the Expires 1012 header. The s-maxage directive also implies the semantics of the 1013 proxy-revalidate response directive. 1015 no-transform 1017 The no-transform response directive indicates that an intermediate 1018 cache or proxy MUST NOT change the Content-Encoding, Content-Range 1019 or Content-Type response headers, nor the response entity-body. 1021 3.2.3. Cache Control Extensions 1023 The Cache-Control header field can be extended through the use of one 1024 or more cache-extension tokens, each with an optional value. 1025 Informational extensions (those that do not require a change in cache 1026 behavior) can be added without changing the semantics of other 1027 directives. Behavioral extensions are designed to work by acting as 1028 modifiers to the existing base of cache directives. Both the new 1029 directive and the standard directive are supplied, such that 1030 applications that do not understand the new directive will default to 1031 the behavior specified by the standard directive, and those that 1032 understand the new directive will recognize it as modifying the 1033 requirements associated with the standard directive. In this way, 1034 extensions to the cache-control directives can be made without 1035 requiring changes to the base protocol. 1037 This extension mechanism depends on an HTTP cache obeying all of the 1038 cache-control directives defined for its native HTTP-version, obeying 1039 certain extensions, and ignoring all directives that it does not 1040 understand. 1042 For example, consider a hypothetical new response directive called 1043 "community" that acts as a modifier to the private directive. We 1044 define this new directive to mean that, in addition to any non-shared 1045 cache, any cache that is shared only by members of the community 1046 named within its value may cache the response. An origin server 1047 wishing to allow the UCI community to use an otherwise private 1048 response in their shared cache(s) could do so by including 1050 Cache-Control: private, community="UCI" 1052 A cache seeing this header field will act correctly even if the cache 1053 does not understand the community cache-extension, since it will also 1054 see and understand the private directive and thus default to the safe 1055 behavior. 1057 Unrecognized cache directives MUST be ignored; it is assumed that any 1058 cache directive likely to be unrecognized by an HTTP/1.1 cache will 1059 be combined with standard directives (or the response's default 1060 cacheability) such that the cache behavior will remain minimally 1061 correct even if the cache does not understand the extension(s). 1063 The HTTP Cache Directive Registry defines the name space for the 1064 cache directives. 1066 Registrations MUST include the following fields: 1068 o Cache Directive Name 1070 o Pointer to specification text 1072 Values to be added to this name space are subject to IETF review 1073 ([RFC5226], Section 4.1). 1075 The registry itself is maintained at 1076 . 1078 3.3. Expires 1080 The "Expires" entity-header field gives the date/time after which the 1081 response is considered stale. See Section 2.3 for further discussion 1082 of the freshness model. 1084 The presence of an Expires field does not imply that the original 1085 resource will change or cease to exist at, before, or after that 1086 time. 1088 The field-value is an absolute date and time as defined by HTTP-date 1089 in Section 6.1 of [Part1]; it MUST be sent in rfc1123-date format. 1091 Expires = "Expires" ":" OWS Expires-v 1092 Expires-v = HTTP-date 1094 For example 1096 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1098 Note: If a response includes a Cache-Control field with the max- 1099 age directive (see Section 3.2.2), that directive overrides the 1100 Expires field. Likewise, the s-maxage directive overrides Expires 1101 in shared caches. 1103 HTTP/1.1 servers SHOULD NOT send Expires dates more than one year in 1104 the future. 1106 HTTP/1.1 clients and caches MUST treat other invalid date formats, 1107 especially including the value "0", as in the past (i.e., "already 1108 expired"). 1110 3.4. Pragma 1112 The "Pragma" general-header field is used to include implementation- 1113 specific directives that might apply to any recipient along the 1114 request/response chain. All pragma directives specify optional 1115 behavior from the viewpoint of the protocol; however, some systems 1116 MAY require that behavior be consistent with the directives. 1118 Pragma = "Pragma" ":" OWS Pragma-v 1119 Pragma-v = 1#pragma-directive 1120 pragma-directive = "no-cache" / extension-pragma 1121 extension-pragma = token [ "=" ( token / quoted-string ) ] 1123 When the no-cache directive is present in a request message, an 1124 application SHOULD forward the request toward the origin server even 1125 if it has a cached copy of what is being requested. This pragma 1126 directive has the same semantics as the no-cache response directive 1127 (see Section 3.2.2) and is defined here for backward compatibility 1128 with HTTP/1.0. Clients SHOULD include both header fields when a no- 1129 cache request is sent to a server not known to be HTTP/1.1 compliant. 1130 HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had 1131 sent "Cache-Control: no-cache". 1133 Note: Because the meaning of "Pragma: no-cache" as a response- 1134 header field is not actually specified, it does not provide a 1135 reliable replacement for "Cache-Control: no-cache" in a response. 1137 This mechanism is deprecated; no new Pragma directives will be 1138 defined in HTTP. 1140 3.5. Vary 1142 The "Vary" response-header field conveys the set of request-header 1143 fields that were used to select the representation. 1145 Caches use this information, in part, to determine whether a stored 1146 response can be used to satisfy a given request; see Section 2.7. 1147 determines, while the response is fresh, whether a cache is permitted 1148 to use the response to reply to a subsequent request without 1149 validation; see Section 2.7. 1151 In uncacheable or stale responses, the Vary field value advises the 1152 user agent about the criteria that were used to select the 1153 representation. 1155 Vary = "Vary" ":" OWS Vary-v 1156 Vary-v = "*" / 1#field-name 1158 The set of header fields named by the Vary field value is known as 1159 the selecting request-headers. 1161 Servers SHOULD include a Vary header field with any cacheable 1162 response that is subject to server-driven negotiation. Doing so 1163 allows a cache to properly interpret future requests on that resource 1164 and informs the user agent about the presence of negotiation on that 1165 resource. A server MAY include a Vary header field with a non- 1166 cacheable response that is subject to server-driven negotiation, 1167 since this might provide the user agent with useful information about 1168 the dimensions over which the response varies at the time of the 1169 response. 1171 A Vary field value of "*" signals that unspecified parameters not 1172 limited to the request-headers (e.g., the network address of the 1173 client), play a role in the selection of the response representation; 1174 therefore, a cache cannot determine whether this response is 1175 appropriate. The "*" value MUST NOT be generated by a proxy server; 1176 it may only be generated by an origin server. 1178 The field-names given are not limited to the set of standard request- 1179 header fields defined by this specification. Field names are case- 1180 insensitive. 1182 3.6. Warning 1184 The "Warning" general-header field is used to carry additional 1185 information about the status or transformation of a message that 1186 might not be reflected in the message. This information is typically 1187 used to warn about possible incorrectness introduced by caching 1188 operations or transformations applied to the entity body of the 1189 message. 1191 Warnings can be used for other purposes, both cache-related and 1192 otherwise. The use of a warning, rather than an error status code, 1193 distinguishes these responses from true failures. 1195 Warning headers can in general be applied to any message, however 1196 some warn-codes are specific to caches and can only be applied to 1197 response messages. 1199 Warning = "Warning" ":" OWS Warning-v 1200 Warning-v = 1#warning-value 1202 warning-value = warn-code SP warn-agent SP warn-text 1203 [SP warn-date] 1205 warn-code = 3DIGIT 1206 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1207 ; the name or pseudonym of the server adding 1208 ; the Warning header, for use in debugging 1209 warn-text = quoted-string 1210 warn-date = DQUOTE HTTP-date DQUOTE 1212 Multiple warnings can be attached to a response (either by the origin 1213 server or by a cache), including multiple warnings with the same code 1214 number, only differing in warn-text. 1216 When this occurs, the user agent SHOULD inform the user of as many of 1217 them as possible, in the order that they appear in the response. 1219 Systems that generate multiple Warning headers SHOULD order them with 1220 this user agent behavior in mind. New Warning headers SHOULD be 1221 added after any existing Warning headers. 1223 Warnings are assigned three digit warn-codes. The first digit 1224 indicates whether the Warning is required to be deleted from a stored 1225 response after validation: 1227 o 1xx Warnings describe the freshness or validation status of the 1228 response, and so MUST be deleted by caches after validation. They 1229 can only be generated by a cache when validating a cached entry, 1230 and MUST NOT be generated in any other situation. 1232 o 2xx Warnings describe some aspect of the entity body or entity 1233 headers that is not rectified by a validation (for example, a 1234 lossy compression of the entity bodies) and MUST NOT be deleted by 1235 caches after validation, unless a full response is returned, in 1236 which case they MUST be. 1238 If an implementation sends a message with one or more Warning headers 1239 to a receiver whose version is HTTP/1.0 or lower, then the sender 1240 MUST include in each warning-value a warn-date that matches the Date 1241 header in the message. 1243 If an implementation receives a message with a warning-value that 1244 includes a warn-date, and that warn-date is different from the Date 1245 value in the response, then that warning-value MUST be deleted from 1246 the message before storing, forwarding, or using it. (preventing the 1247 consequences of naive caching of Warning header fields.) If all of 1248 the warning-values are deleted for this reason, the Warning header 1249 MUST be deleted as well. 1251 The following warn-codes are defined by this specification, each with 1252 a recommended warn-text in English, and a description of its meaning. 1254 110 Response is stale 1256 SHOULD be included whenever the returned response is stale. 1258 111 Revalidation failed 1260 SHOULD be included if a cache returns a stale response because an 1261 attempt to validate the response failed, due to an inability to 1262 reach the server. 1264 112 Disconnected operation 1266 SHOULD be included if the cache is intentionally disconnected from 1267 the rest of the network for a period of time. 1269 113 Heuristic expiration 1271 SHOULD be included if the cache heuristically chose a freshness 1272 lifetime greater than 24 hours and the response's age is greater 1273 than 24 hours. 1275 199 Miscellaneous warning 1277 The warning text can include arbitrary information to be presented 1278 to a human user, or logged. A system receiving this warning MUST 1279 NOT take any automated action, besides presenting the warning to 1280 the user. 1282 214 Transformation applied 1284 MUST be added by an intermediate cache or proxy if it applies any 1285 transformation changing the content-coding (as specified in the 1286 Content-Encoding header) or media-type (as specified in the 1287 Content-Type header) of the response, or the entity-body of the 1288 response, unless this Warning code already appears in the 1289 response. 1291 299 Miscellaneous persistent warning 1293 The warning text can include arbitrary information to be presented 1294 to a human user, or logged. A system receiving this warning MUST 1295 NOT take any automated action. 1297 4. History Lists 1299 User agents often have history mechanisms, such as "Back" buttons and 1300 history lists, that can be used to redisplay an entity retrieved 1301 earlier in a session. 1303 The freshness model (Section 2.3) does not necessarily apply to 1304 history mechanisms. I.e., a history mechanism can display a previous 1305 representation even if it has expired. 1307 This does not prohibit the history mechanism from telling the user 1308 that a view might be stale, or from honoring cache directives (e.g., 1309 Cache-Control: no-store). 1311 5. IANA Considerations 1313 5.1. Cache Directive Registry 1315 The registration procedure for HTTP Cache Directives is defined by 1316 Section 3.2.3 of this document. 1318 The HTTP Cache Directive Registry should be created at 1319 and be 1320 populated with the registrations below: 1322 +------------------------+------------------------------+ 1323 | Cache Directive | Reference | 1324 +------------------------+------------------------------+ 1325 | max-age | Section 3.2.1, Section 3.2.2 | 1326 | max-stale | Section 3.2.1 | 1327 | min-fresh | Section 3.2.1 | 1328 | must-revalidate | Section 3.2.2 | 1329 | no-cache | Section 3.2.1, Section 3.2.2 | 1330 | no-store | Section 3.2.1, Section 3.2.2 | 1331 | no-transform | Section 3.2.1, Section 3.2.2 | 1332 | only-if-cached | Section 3.2.1 | 1333 | private | Section 3.2.2 | 1334 | proxy-revalidate | Section 3.2.2 | 1335 | public | Section 3.2.2 | 1336 | s-maxage | Section 3.2.2 | 1337 | stale-if-error | [RFC5861], Section 4 | 1338 | stale-while-revalidate | [RFC5861], Section 3 | 1339 +------------------------+------------------------------+ 1341 5.2. Message Header Registration 1343 The Message Header Registry located at should be 1345 updated with the permanent registrations below (see [RFC3864]): 1347 +-------------------+----------+----------+-------------+ 1348 | Header Field Name | Protocol | Status | Reference | 1349 +-------------------+----------+----------+-------------+ 1350 | Age | http | standard | Section 3.1 | 1351 | Cache-Control | http | standard | Section 3.2 | 1352 | Expires | http | standard | Section 3.3 | 1353 | Pragma | http | standard | Section 3.4 | 1354 | Vary | http | standard | Section 3.5 | 1355 | Warning | http | standard | Section 3.6 | 1356 +-------------------+----------+----------+-------------+ 1358 The change controller is: "IETF (iesg@ietf.org) - Internet 1359 Engineering Task Force". 1361 6. Security Considerations 1363 Caches expose additional potential vulnerabilities, since the 1364 contents of the cache represent an attractive target for malicious 1365 exploitation. Because cache contents persist after an HTTP request 1366 is complete, an attack on the cache can reveal information long after 1367 a user believes that the information has been removed from the 1368 network. Therefore, cache contents should be protected as sensitive 1369 information. 1371 7. Acknowledgments 1373 Much of the content and presentation of the caching design is due to 1374 suggestions and comments from individuals including: Shel Kaphan, 1375 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 1377 8. References 1379 8.1. Normative References 1381 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1382 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1383 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 1384 and Message Parsing", draft-ietf-httpbis-p1-messaging-10 1385 (work in progress), July 2010. 1387 [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1388 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1389 and J. Reschke, Ed., "HTTP/1.1, part 2: Message 1390 Semantics", draft-ietf-httpbis-p2-semantics-10 (work in 1391 progress), July 2010. 1393 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1394 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1395 and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional 1396 Requests", draft-ietf-httpbis-p4-conditional-10 (work in 1397 progress), July 2010. 1399 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1400 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1401 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 1402 Partial Responses", draft-ietf-httpbis-p5-range-10 (work 1403 in progress), July 2010. 1405 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1406 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1407 and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", 1408 draft-ietf-httpbis-p7-auth-10 (work in progress), 1409 July 2010. 1411 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1412 Requirement Levels", BCP 14, RFC 2119, March 1997. 1414 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1415 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1417 8.2. Informative References 1419 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1420 Specification, Implementation", RFC 1305, March 1992. 1422 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1423 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1424 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1426 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1427 Procedures for Message Header Fields", BCP 90, RFC 3864, 1428 September 2004. 1430 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1431 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1432 May 2008. 1434 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1435 Content", RFC 5861, April 2010. 1437 Appendix A. Compatibility with Previous Versions 1439 A.1. Changes from RFC 2068 1441 A case was missed in the Cache-Control model of HTTP/1.1; s-maxage 1442 was introduced to add this missing case. (Sections 2.1, 3.2). 1444 Range request responses would become very verbose if all meta-data 1445 were always returned; by allowing the server to only send needed 1446 headers in a 206 response, this problem can be avoided. 1447 (Section 2.8) 1449 The Cache-Control: max-age directive was not properly defined for 1450 responses. (Section 3.2.2) 1452 Warnings could be cached incorrectly, or not updated appropriately. 1453 (Section 2.3, 2.8, 3.2, and 3.6) Warning also needed to be a general 1454 header, as PUT or other methods may have need for it in requests. 1456 A.2. Changes from RFC 2616 1458 Make the specified age calculation algorithm less conservative. 1459 (Section 2.3.2) 1461 Remove requirement to consider Content-Location in successful 1462 responses in order to determine the appropriate response to use. 1463 (Section 2.4) 1465 Clarify denial of service attack avoidance requirement. 1466 (Section 2.5) 1468 Do not mention RFC 2047 encoding and multiple languages in Warning 1469 headers anymore, as these aspects never were implemented. 1470 (Section 3.6) 1472 Appendix B. Collected ABNF 1474 Age = "Age:" OWS Age-v 1475 Age-v = delta-seconds 1477 Cache-Control = "Cache-Control:" OWS Cache-Control-v 1478 Cache-Control-v = *( "," OWS ) cache-directive *( OWS "," [ OWS 1479 cache-directive ] ) 1481 Expires = "Expires:" OWS Expires-v 1482 Expires-v = HTTP-date 1484 HTTP-date = 1485 OWS = 1487 Pragma = "Pragma:" OWS Pragma-v 1488 Pragma-v = *( "," OWS ) pragma-directive *( OWS "," [ OWS 1489 pragma-directive ] ) 1491 Vary = "Vary:" OWS Vary-v 1492 Vary-v = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name 1493 ] ) ) 1495 Warning = "Warning:" OWS Warning-v 1496 Warning-v = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value 1497 ] ) 1499 cache-directive = cache-request-directive / cache-response-directive 1500 cache-extension = token [ "=" ( token / quoted-string ) ] 1501 cache-request-directive = "no-cache" / "no-store" / ( "max-age=" 1502 delta-seconds ) / ( "max-stale" [ "=" delta-seconds ] ) / ( 1503 "min-fresh=" delta-seconds ) / "no-transform" / "only-if-cached" / 1504 cache-extension 1505 cache-response-directive = "public" / ( "private" [ "=" DQUOTE *( "," 1506 OWS ) field-name *( OWS "," [ OWS field-name ] ) DQUOTE ] ) / ( 1507 "no-cache" [ "=" DQUOTE *( "," OWS ) field-name *( OWS "," [ OWS 1508 field-name ] ) DQUOTE ] ) / "no-store" / "no-transform" / 1509 "must-revalidate" / "proxy-revalidate" / ( "max-age=" delta-seconds 1510 ) / ( "s-maxage=" delta-seconds ) / cache-extension 1512 delta-seconds = 1*DIGIT 1514 extension-pragma = token [ "=" ( token / quoted-string ) ] 1516 field-name = 1518 port = 1519 pragma-directive = "no-cache" / extension-pragma 1520 pseudonym = 1522 quoted-string = 1524 token = 1526 uri-host = 1528 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1529 warn-code = 3DIGIT 1530 warn-date = DQUOTE HTTP-date DQUOTE 1531 warn-text = quoted-string 1532 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date 1533 ] 1535 ABNF diagnostics: 1537 ; Age defined but not used 1538 ; Cache-Control defined but not used 1539 ; Expires defined but not used 1540 ; Pragma defined but not used 1541 ; Vary defined but not used 1542 ; Warning defined but not used 1544 Appendix C. Change Log (to be removed by RFC Editor before publication) 1546 C.1. Since RFC2616 1548 Extracted relevant partitions from [RFC2616]. 1550 C.2. Since draft-ietf-httpbis-p6-cache-00 1552 Closed issues: 1554 o : "Trailer" 1555 () 1557 o : "Invalidation 1558 after Update or Delete" 1559 () 1561 o : "Normative and 1562 Informative references" 1564 o : "Date reference 1565 typo" 1567 o : "Connection 1568 header text" 1570 o : "Informative 1571 references" 1573 o : "ISO-8859-1 1574 Reference" 1576 o : "Normative up- 1577 to-date references" 1579 o : "typo in 1580 13.2.2" 1582 Other changes: 1584 o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress 1585 on ) 1587 C.3. Since draft-ietf-httpbis-p6-cache-01 1589 Closed issues: 1591 o : "rel_path not 1592 used" 1594 Other changes: 1596 o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work 1597 in progress on ) 1599 o Add explicit references to BNF syntax and rules imported from 1600 other parts of the specification. 1602 C.4. Since draft-ietf-httpbis-p6-cache-02 1604 Ongoing work on IANA Message Header Registration 1605 (): 1607 o Reference RFC 3984, and update header registrations for headers 1608 defined in this document. 1610 C.5. Since draft-ietf-httpbis-p6-cache-03 1612 Closed issues: 1614 o : "Vary header 1615 classification" 1617 C.6. Since draft-ietf-httpbis-p6-cache-04 1619 Ongoing work on ABNF conversion 1620 (): 1622 o Use "/" instead of "|" for alternatives. 1624 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1625 whitespace ("OWS") and required whitespace ("RWS"). 1627 o Rewrite ABNFs to spell out whitespace rules, factor out header 1628 value format definitions. 1630 C.7. Since draft-ietf-httpbis-p6-cache-05 1632 This is a total rewrite of this part of the specification. 1634 Affected issues: 1636 o : "Definition of 1637 1xx Warn-Codes" 1639 o : "Placement of 1640 13.5.1 and 13.5.2" 1642 o : "The role of 1643 Warning and Semantic Transparency in Caching" 1645 o : "Methods and 1646 Caching" 1648 In addition: Final work on ABNF conversion 1649 (): 1651 o Add appendix containing collected and expanded ABNF, reorganize 1652 ABNF introduction. 1654 C.8. Since draft-ietf-httpbis-p6-cache-06 1656 Closed issues: 1658 o : "base for 1659 numeric protocol elements" 1661 Affected issues: 1663 o : Vary and non- 1664 existant headers 1666 C.9. Since draft-ietf-httpbis-p6-cache-07 1668 Closed issues: 1670 o : "Definition of 1671 1xx Warn-Codes" 1673 o : "Content- 1674 Location on 304 responses" 1676 o : "private and 1677 no-cache CC directives with headers" 1679 o : "RFC2047 and 1680 warn-text" 1682 C.10. Since draft-ietf-httpbis-p6-cache-08 1684 Closed issues: 1686 o : "serving 1687 negotiated responses from cache: header-specific canonicalization" 1689 o : "Effect of CC 1690 directives on history lists" 1692 Affected issues: 1694 o : Status codes 1695 and caching 1697 Partly resolved issues: 1699 o : "Placement of 1700 13.5.1 and 13.5.2" 1702 C.11. Since draft-ietf-httpbis-p6-cache-09 1704 Closed issues: 1706 o : "Age 1707 calculation" 1709 o : "Clarify 1710 differences between / requirements for request and response CC 1711 directives" 1713 o : "Caching 1714 authenticated responses" 1716 o : "IANA registry 1717 for cache-control directives" 1719 o : "Heuristic 1720 caching of URLs with query components" 1722 Partly resolved issues: 1724 o : "Term for the 1725 requested resource's URI" 1727 Index 1729 A 1730 age 6 1731 Age header 17 1733 C 1734 cache 5 1735 Cache Directives 1736 max-age 19, 22 1737 max-stale 19 1738 min-fresh 20 1739 must-revalidate 22 1740 no-cache 19, 21 1741 no-store 19, 22 1742 no-transform 20, 23 1743 only-if-cached 20 1744 private 21 1745 proxy-revalidate 22 1746 public 20 1747 s-maxage 22 1748 Cache-Control header 18 1749 cacheable 5 1751 E 1752 Expires header 24 1753 explicit expiration time 5 1755 F 1756 first-hand 6 1757 fresh 6 1758 freshness lifetime 6 1760 G 1761 Grammar 1762 Age 18 1763 Age-v 18 1764 Cache-Control 18 1765 Cache-Control-v 18 1766 cache-extension 18 1767 cache-request-directive 19 1768 cache-response-directive 20 1769 delta-seconds 18 1770 Expires 24 1771 Expires-v 24 1772 extension-pragma 25 1773 Pragma 25 1774 pragma-directive 25 1775 Pragma-v 25 1776 Vary 26 1777 Vary-v 26 1778 warn-agent 27 1779 warn-code 27 1780 warn-date 27 1781 warn-text 27 1782 Warning 27 1783 Warning-v 27 1784 warning-value 27 1786 H 1787 Headers 1788 Age 17 1789 Cache-Control 18 1790 Expires 24 1791 Pragma 25 1792 Vary 25 1793 Warning 26 1794 heuristic expiration time 5 1796 M 1797 max-age 1798 Cache Directive 19, 22 1799 max-stale 1800 Cache Directive 19 1801 min-fresh 1802 Cache Directive 20 1803 must-revalidate 1804 Cache Directive 22 1806 N 1807 no-cache 1808 Cache Directive 19, 21 1809 no-store 1810 Cache Directive 19, 22 1811 no-transform 1812 Cache Directive 20, 23 1814 O 1815 only-if-cached 1816 Cache Directive 20 1818 P 1819 Pragma header 25 1820 private 1821 Cache Directive 21 1822 proxy-revalidate 1823 Cache Directive 22 1824 public 1825 Cache Directive 20 1827 S 1828 s-maxage 1829 Cache Directive 22 1830 stale 6 1832 V 1833 validator 6 1834 Vary header 25 1836 W 1837 Warning header 26 1839 Authors' Addresses 1841 Roy T. Fielding (editor) 1842 Day Software 1843 23 Corporate Plaza DR, Suite 280 1844 Newport Beach, CA 92660 1845 USA 1847 Phone: +1-949-706-5300 1848 Fax: +1-949-706-5305 1849 EMail: fielding@gbiv.com 1850 URI: http://roy.gbiv.com/ 1852 Jim Gettys 1853 Alcatel-Lucent Bell Labs 1854 21 Oak Knoll Road 1855 Carlisle, MA 01741 1856 USA 1858 EMail: jg@freedesktop.org 1859 URI: http://gettys.wordpress.com/ 1860 Jeffrey C. Mogul 1861 Hewlett-Packard Company 1862 HP Labs, Large Scale Systems Group 1863 1501 Page Mill Road, MS 1177 1864 Palo Alto, CA 94304 1865 USA 1867 EMail: JeffMogul@acm.org 1869 Henrik Frystyk Nielsen 1870 Microsoft Corporation 1871 1 Microsoft Way 1872 Redmond, WA 98052 1873 USA 1875 EMail: henrikn@microsoft.com 1877 Larry Masinter 1878 Adobe Systems, Incorporated 1879 345 Park Ave 1880 San Jose, CA 95110 1881 USA 1883 EMail: LMM@acm.org 1884 URI: http://larry.masinter.net/ 1886 Paul J. Leach 1887 Microsoft Corporation 1888 1 Microsoft Way 1889 Redmond, WA 98052 1891 EMail: paulle@microsoft.com 1893 Tim Berners-Lee 1894 World Wide Web Consortium 1895 MIT Computer Science and Artificial Intelligence Laboratory 1896 The Stata Center, Building 32 1897 32 Vassar Street 1898 Cambridge, MA 02139 1899 USA 1901 EMail: timbl@w3.org 1902 URI: http://www.w3.org/People/Berners-Lee/ 1903 Yves Lafon (editor) 1904 World Wide Web Consortium 1905 W3C / ERCIM 1906 2004, rte des Lucioles 1907 Sophia-Antipolis, AM 06902 1908 France 1910 EMail: ylafon@w3.org 1911 URI: http://www.raubacapeu.net/people/yves/ 1913 Mark Nottingham (editor) 1915 EMail: mnot@mnot.net 1916 URI: http://www.mnot.net/ 1918 Julian F. Reschke (editor) 1919 greenbytes GmbH 1920 Hafenweg 16 1921 Muenster, NW 48155 1922 Germany 1924 Phone: +49 251 2807760 1925 Fax: +49 251 2807761 1926 EMail: julian.reschke@greenbytes.de 1927 URI: http://greenbytes.de/tech/webdav/