idnits 2.17.1 draft-ietf-httpbis-p6-cache-12.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 (October 25, 2010) is 4925 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-12 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-12 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-12 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-12 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-12 -- 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: April 28, 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 October 25, 2010 24 HTTP/1.1, part 6: Caching 25 draft-ietf-httpbis-p6-cache-12 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.13. 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 April 28, 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 . . . . . . . . . . . . . 15 110 2.6. Shared Caching of Authenticated Responses . . . . . . . . 15 111 2.7. Caching Negotiated Responses . . . . . . . . . . . . . . . 16 112 2.8. Combining Responses . . . . . . . . . . . . . . . . . . . 17 113 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 17 114 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 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. Header Field 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. Changes from RFC 2616 . . . . . . . . . . . . . . . . 32 133 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 32 134 Appendix C. Change Log (to be removed by RFC Editor before 135 publication) . . . . . . . . . . . . . . . . . . . . 33 136 C.1. Since RFC 2616 . . . . . . . . . . . . . . . . . . . . . . 34 137 C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 34 138 C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 34 139 C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 35 140 C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 35 141 C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 35 142 C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 35 143 C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 36 144 C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 36 145 C.10. Since draft-ietf-httpbis-p6-cache-08 . . . . . . . . . . . 36 146 C.11. Since draft-ietf-httpbis-p6-cache-09 . . . . . . . . . . . 37 147 C.12. Since draft-ietf-httpbis-p6-cache-10 . . . . . . . . . . . 37 148 C.13. Since draft-ietf-httpbis-p6-cache-11 . . . . . . . . . . . 38 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 employ a cache, though a cache cannot be used by 165 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 might 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 a representation 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 has an 230 equivalent copy of a representation. 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 header fields, 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 field (see Section 4.1 of [Part7]) does 302 not appear in the request, if the cache is shared, unless the 303 response explicitly allows it (see Section 2.6), and 305 o the response either: 307 * contains an Expires header field (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 field) can 336 store 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 header 344 fields 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-header fields nominated by the stored response 358 (if 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 When a stored response is used to satisfy a request without 372 validation, caches MUST include a single Age header field 373 (Section 3.1) in the response with a value equal to the stored 374 response's current_age; see Section 2.3.2. 376 Requests with methods that are unsafe (Section 7.1.1 of [Part2]) MUST 377 be written through the cache to the origin server; i.e., a cache must 378 not reply to such a request before having forwarded the request and 379 having received a corresponding response. 381 Also, note that unsafe requests might invalidate already stored 382 responses; see Section 2.5. 384 Caches MUST use the most recent response (as determined by the Date 385 header field) when more than one suitable response is stored. They 386 can also forward a request with "Cache-Control: max-age=0" or "Cache- 387 Control: no-cache" to disambiguate which response to use. 389 An HTTP implementation without a clock MUST NOT used stored responses 390 without revalidating them on every use. An HTTP cache, especially a 391 shared cache, SHOULD use a mechanism, such as NTP [RFC1305], to 392 synchronize its clock with a reliable external standard. 394 2.3. Freshness Model 396 When a response is "fresh" in the cache, it can be used to satisfy 397 subsequent requests without contacting the origin server, thereby 398 improving efficiency. 400 The primary mechanism for determining freshness is for an origin 401 server to provide an explicit expiration time in the future, using 402 either the Expires header field (Section 3.3) or the max-age response 403 cache directive (Section 3.2.2). Generally, origin servers will 404 assign future explicit expiration times to responses in the belief 405 that the representation is not likely to change in a semantically 406 significant way before the expiration time is reached. 408 If an origin server wishes to force a cache to validate every 409 request, it can assign an explicit expiration time in the past to 410 indicate that the response is already stale. Compliant caches will 411 validate the cached response before reusing it for subsequent 412 requests. 414 Since origin servers do not always provide explicit expiration times, 415 HTTP caches MAY assign heuristic expiration times when explicit times 416 are not specified, employing algorithms that use other heade field 417 values (such as the Last-Modified time) to estimate a plausible 418 expiration time. The HTTP/1.1 specification does not provide 419 specific algorithms, but does impose worst-case constraints on their 420 results. 422 The calculation to determine if a response is fresh is: 424 response_is_fresh = (freshness_lifetime > current_age) 426 The freshness_lifetime is defined in Section 2.3.1; the current_age 427 is defined in Section 2.3.2. 429 Additionally, clients might need to influence freshness calculation. 430 They can do this using several request cache directives, with the 431 effect of either increasing or loosening constraints on freshness. 432 See Section 3.2.1. 434 [[ISSUE-no-req-for-directives: there are not requirements directly 435 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 field (Section 3.3) is present, use 453 its value minus the value of the Date response header field, 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 whose definition allows heuristic freshness to be 466 used (including the following in Section 8 of [Part2]: 200, 203, 206, 467 300, 301 and 410), a heuristic expiration time MAY be calculated. 468 Heuristics MUST NOT be used for response status codes that do not 469 explicitly allow it. 471 When a heuristic is used to calculate freshness lifetime, the cache 472 SHOULD attach a Warning header field with a 113 warn-code to the 473 response if its current_age is more than 24 hours and such a warning 474 is not already present. 476 Also, if the response has a Last-Modified header field (Section 6.6 477 of [Part4]), the heuristic expiration value SHOULD be no more than 478 some fraction of the interval since that time. A typical setting of 479 this fraction might be 10%. 481 Note: RFC 2616 ([RFC2616], Section 13.9) required that caches do 482 not calculate heuristic freshness for URLs with query components 483 (i.e., those containing '?'). In practice, this has not been 484 widely implemented. Therefore, servers are encouraged to send 485 explicit directives (e.g., Cache-Control: no-cache) if they wish 486 to preclude caching. 488 2.3.2. Calculating Age 490 HTTP/1.1 uses the Age response-header field to convey the estimated 491 age of the response message when obtained from a cache. The Age 492 field value is the cache's estimate of the amount of time since the 493 response was generated or validated by the origin server. In 494 essence, the Age value is the sum of the time that the response has 495 been resident in each of the caches along the path from the origin 496 server, plus the amount of time it has been in transit along network 497 paths. 499 The following data is used for the age calculation: 501 age_value 503 The term "age_value" denotes the value of the Age header field 504 (Section 3.1), in a form appropriate for arithmetic operation; or 505 0, if not available. 507 date_value 509 HTTP/1.1 requires origin servers to send a Date header field, if 510 possible, with every response, giving the time at which the 511 response was generated. The term "date_value" denotes the value 512 of the Date header field, in a form appropriate for arithmetic 513 operations. See Section 9.3 of [Part1] for the definition of the 514 Date header field, and for requirements regarding responses 515 without it. 517 now 519 The term "now" means "the current value of the clock at the host 520 performing the calculation". Hosts that use HTTP, but especially 521 hosts running origin servers and caches, SHOULD use NTP 522 ([RFC1305]) or some similar protocol to synchronize their clocks 523 to a globally accurate time standard. 525 request_time 527 The current value of the clock at the host at the time the request 528 resulting in the stored response was made. 530 response_time 532 The current value of the clock at the host at the time the 533 response was received. 535 A response's age can be calculated in two entirely independent ways: 537 1. the "apparent_age": response_time minus date_value, if the local 538 clock is reasonably well synchronized to the origin server's 539 clock. If the result is negative, the result is replaced by 540 zero. 542 2. the "corrected_age_value", if all of the caches along the 543 response path implement HTTP/1.1; note this value MUST be 544 interpreted relative to the time the request was initiated, not 545 the time that the response was received. 547 apparent_age = max(0, response_time - date_value); 549 response_delay = response_time - request_time; 550 corrected_age_value = age_value + response_delay; 552 These are combined as 554 corrected_initial_age = max(apparent_age, corrected_age_value); 556 The current_age of a stored response can then be calculated by adding 557 the amount of time (in seconds) since the stored response was last 558 validated by the origin server to the corrected_initial_age. 560 resident_time = now - response_time; 561 current_age = corrected_initial_age + resident_time; 563 2.3.3. Serving Stale Responses 565 A "stale" response is one that either has explicit expiry information 566 or is allowed to have heuristic expiry calculated, but is not fresh 567 according to the calculations in Section 2.3. 569 Caches MUST NOT return a stale response if it is prohibited by an 570 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" 571 cache directive, a "must-revalidate" cache-response-directive, or an 572 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 573 see Section 3.2.2). 575 Caches SHOULD NOT return stale responses unless they are disconnected 576 (i.e., it cannot contact the origin server or otherwise find a 577 forward path) or otherwise explicitly allowed (e.g., the max-stale 578 request directive; see Section 3.2.1). 580 Stale responses SHOULD have a Warning header field with the 110 warn- 581 code (see Section 3.6). Likewise, the 112 warn-code SHOULD be sent 582 on stale responses if the cache is disconnected. 584 If a cache receives a first-hand response (either an entire response, 585 or a 304 (Not Modified) response) that it would normally forward to 586 the requesting client, and the received response is no longer fresh, 587 the cache SHOULD forward it to the requesting client without adding a 588 new Warning (but without removing any existing Warning header 589 fields). A cache SHOULD NOT attempt to validate a response simply 590 because that response became stale in transit. 592 2.4. Validation Model 594 When a cache has one or more stored responses for a requested URI, 595 but cannot serve any of them (e.g., because they are not fresh, or 596 one cannot be selected; see Section 2.7), it can use the conditional 597 request mechanism [Part4] in the forwarded request to give the origin 598 server an opportunity to both select a valid stored response to be 599 used, and to update it. This process is known as "validating" or 600 "revalidating" the stored response. 602 When sending such a conditional request, the cache SHOULD add an If- 603 Modified-Since header field whose value is that of the Last-Modified 604 header field from the selected (see Section 2.7) stored response, if 605 available. 607 Additionally, the cache SHOULD add an If-None-Match header field 608 whose value is that of the ETag header field(s) from all responses 609 stored for the requested URI, if present. However, if any of the 610 stored responses contains only partial content, its entity-tag SHOULD 611 NOT be included in the If-None-Match header field unless the request 612 is for a range that would be fully satisfied by that stored response. 614 A 304 (Not Modified) response status code indicates that the stored 615 response can be updated and reused; see Section 2.8. 617 A full response (i.e., one with a response body) indicates that none 618 of the stored responses nominated in the conditional request is 619 suitable. Instead, the full response SHOULD be used to satisfy the 620 request and MAY replace the stored response. 622 If a cache receives a 5xx response while attempting to validate a 623 response, it MAY either forward this response to the requesting 624 client, or act as if the server failed to respond. In the latter 625 case, it MAY return a previously stored response (see Section 2.3.3). 627 2.5. Request Methods that Invalidate 629 Because unsafe methods (Section 7.1.1 of [Part2]) have the potential 630 for changing state on the origin server, intervening caches can use 631 them to keep their contents up-to-date. 633 The following HTTP methods MUST cause a cache to invalidate the 634 effective Request URI (Section 4.3 of [Part1]) as well as the URI(s) 635 in the Location and Content-Location header fields (if present): 637 o PUT 639 o DELETE 641 o POST 643 An invalidation based on a URI from a Location or Content-Location 644 header field MUST NOT be performed if the host part of that URI 645 differs from the host part in the effective request URI (Section 4.3 646 of [Part1]). This helps prevent denial of service attacks. 648 A cache that passes through requests for methods it does not 649 understand SHOULD invalidate the effective request URI (Section 4.3 650 of [Part1]). 652 Here, "invalidate" means that the cache will either remove all stored 653 responses related to the effective request URI, or will mark these as 654 "invalid" and in need of a mandatory validation before they can be 655 returned in response to a subsequent request. 657 Note that this does not guarantee that all appropriate responses are 658 invalidated. For example, the request that caused the change at the 659 origin server might not have gone through the cache where a response 660 is stored. 662 2.6. Shared Caching of Authenticated Responses 664 Shared caches MUST NOT use a cached response to a request with an 665 Authorization header field (Section 4.1 of [Part7]) to satisfy any 666 subsequent request unless a cache directive that allows such 667 responses to be stored is present in the response. 669 In this specification, the following Cache-Control response 670 directives (Section 3.2.2) have such an effect: must-revalidate, 671 public, s-maxage. 673 Note that cached responses that contain the "must-revalidate" and/or 674 "s-maxage" response directives are not allowed to be served stale 675 (Section 2.3.3) by shared caches. In particular, a response with 676 either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to 677 satisfy a subsequent request without revalidating it on the origin 678 server. 680 2.7. Caching Negotiated Responses 682 When a cache receives a request that can be satisfied by a stored 683 response that has a Vary header field (Section 3.5), it MUST NOT use 684 that response unless all of the selecting request-header fields 685 nominated by the Vary header field match in both the original request 686 (i.e., that associated with the stored response), and the presented 687 request. 689 The selecting request-header fields from two requests are defined to 690 match if and only if those in the first request can be transformed to 691 those in the second request by applying any of the following: 693 o adding or removing whitespace, where allowed in the header field's 694 syntax 696 o combining multiple message-header fields with the same field name 697 (see Section 3.2 of [Part1]) 699 o normalizing both header field values in a way that is known to 700 have identical semantics, according to the header field's 701 specification (e.g., re-ordering field values when order is not 702 significant; case-normalization, where values are defined to be 703 case-insensitive) 705 If (after any normalization that might take place) a header field is 706 absent from a request, it can only match another request if it is 707 also absent there. 709 A Vary header field-value of "*" always fails to match, and 710 subsequent requests to that resource can only be properly interpreted 711 by the origin server. 713 The stored response with matching selecting request-header fields is 714 known as the selected response. 716 If no selected response is available, the cache MAY forward the 717 presented request to the origin server in a conditional request; see 718 Section 2.4. 720 2.8. Combining Responses 722 When a cache receives a 304 (Not Modified) response or a 206 (Partial 723 Content) response (in this section, the "new" response"), it needs to 724 created an updated response by combining the stored response with the 725 new one, so that the updated response can be used to satisfy the 726 request, and potentially update the cached response. 728 If the new response contains an ETag, it identifies the stored 729 response to use. [[TODO-mention-CL: might need language about 730 Content-Location here]][[TODO-select-for-combine: Shouldn't this be 731 the selected response?]] 733 If the new response's status code is 206 (partial content), both the 734 stored and new responses MUST have validators, and those validators 735 MUST match using the strong comparison function (see Section 4 of 736 [Part4]). Otherwise, the responses MUST NOT be combined. 738 The stored response header fields are used as those of the updated 739 response, except that 741 o any stored Warning header fields with warn-code 1xx (see 742 Section 3.6) MUST be deleted. 744 o any stored Warning header fields with warn-code 2xx MUST be 745 retained. 747 o any other header fields provided in the new response MUST replace 748 all instances of the corresponding header fields from the stored 749 response. 751 The updated response header fields MUST be used to replace those of 752 the stored response in cache (unless the stored response is removed 753 from cache). In the case of a 206 response, the combined 754 representation MAY be stored. 756 3. Header Field Definitions 758 This section defines the syntax and semantics of HTTP/1.1 header 759 fields related to caching. 761 3.1. Age 763 The "Age" response-header field conveys the sender's estimate of the 764 amount of time since the response was generated or successfully 765 validated at the origin server. Age values are calculated as 766 specified in Section 2.3.2. 768 Age = "Age" ":" OWS Age-v 769 Age-v = delta-seconds 771 Age field-values are non-negative integers, representing time in 772 seconds. 774 delta-seconds = 1*DIGIT 776 If a cache receives a value larger than the largest positive integer 777 it can represent, or if any of its age calculations overflows, it 778 MUST transmit an Age header field with a field-value of 2147483648 779 (2^31). Caches SHOULD use an arithmetic type of at least 31 bits of 780 range. 782 The presence of an Age header field in a response implies that a 783 response is not first-hand. However, the converse is not true, since 784 HTTP/1.0 caches might not implement the Age header field. 786 3.2. Cache-Control 788 The "Cache-Control" general-header field is used to specify 789 directives for caches along the request/response chain. Such cache 790 directives are unidirectional in that the presence of a directive in 791 a request does not imply that the same directive is to be given in 792 the response. 794 HTTP/1.1 caches MUST obey the requirements of the Cache-Control 795 directives defined in this section. See Section 3.2.3 for 796 information about how Cache-Control directives defined elsewhere are 797 handled. 799 Note: HTTP/1.0 caches might not implement Cache-Control and might 800 only implement Pragma: no-cache (see Section 3.4). 802 Cache directives MUST be passed through by a proxy or gateway 803 application, regardless of their significance to that application, 804 since the directives might be applicable to all recipients along the 805 request/response chain. It is not possible to target a directive to 806 a specific cache. 808 Cache-Control = "Cache-Control" ":" OWS Cache-Control-v 809 Cache-Control-v = 1#cache-directive 811 cache-directive = cache-request-directive 812 / cache-response-directive 814 cache-extension = token [ "=" ( token / quoted-string ) ] 816 3.2.1. Request Cache-Control Directives 818 cache-request-directive = 819 "no-cache" 820 / "no-store" 821 / "max-age" "=" delta-seconds 822 / "max-stale" [ "=" delta-seconds ] 823 / "min-fresh" "=" delta-seconds 824 / "no-transform" 825 / "only-if-cached" 826 / cache-extension 828 no-cache 830 The no-cache request directive indicates that a stored response 831 MUST NOT be used to satisfy the request without successful 832 validation on the origin server. 834 no-store 836 The no-store request directive indicates that a cache MUST NOT 837 store any part of either this request or any response to it. This 838 directive applies to both non-shared and shared caches. "MUST NOT 839 store" in this context means that the cache MUST NOT intentionally 840 store the information in non-volatile storage, and MUST make a 841 best-effort attempt to remove the information from volatile 842 storage as promptly as possible after forwarding it. 844 This directive is NOT a reliable or sufficient mechanism for 845 ensuring privacy. In particular, malicious or compromised caches 846 might not recognize or obey this directive, and communications 847 networks might be vulnerable to eavesdropping. 849 max-age 851 The max-age request directive indicates that the client is willing 852 to accept a response whose age is no greater than the specified 853 time in seconds. Unless the max-stale request directive is also 854 present, the client is not willing to accept a stale response. 856 max-stale 858 The max-stale request directive indicates that the client is 859 willing to accept a response that has exceeded its expiration 860 time. If max-stale is assigned a value, then the client is 861 willing to accept a response that has exceeded its expiration time 862 by no more than the specified number of seconds. If no value is 863 assigned to max-stale, then the client is willing to accept a 864 stale response of any age. 866 min-fresh 868 The min-fresh request directive indicates that the client is 869 willing to accept a response whose freshness lifetime is no less 870 than its current age plus the specified time in seconds. That is, 871 the client wants a response that will still be fresh for at least 872 the specified number of seconds. 874 no-transform 876 The no-transform request directive indicates that an intermediate 877 cache or proxy MUST NOT change the Content-Encoding, Content-Range 878 or Content-Type request header fields, nor the request 879 representation. 881 only-if-cached 883 The only-if-cached request directive indicates that the client 884 only wishes to return a stored response. If it receives this 885 directive, a cache SHOULD either respond using a stored response 886 that is consistent with the other constraints of the request, or 887 respond with a 504 (Gateway Timeout) status code. If a group of 888 caches is being operated as a unified system with good internal 889 connectivity, such a request MAY be forwarded within that group of 890 caches. 892 3.2.2. Response Cache-Control Directives 894 cache-response-directive = 895 "public" 896 / "private" [ "=" DQUOTE 1#field-name DQUOTE ] 897 / "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] 898 / "no-store" 899 / "no-transform" 900 / "must-revalidate" 901 / "proxy-revalidate" 902 / "max-age" "=" delta-seconds 903 / "s-maxage" "=" delta-seconds 904 / cache-extension 906 public 908 The public response directive indicates that the response MAY be 909 cached, even if it would normally be non-cacheable or cacheable 910 only within a non-shared cache. (See also Authorization, Section 911 4.1 of [Part7], for additional details.) 913 private 915 The private response directive indicates that the response message 916 is intended for a single user and MUST NOT be stored by a shared 917 cache. A private (non-shared) cache MAY store the response. 919 If the private response directive specifies one or more field- 920 names, this requirement is limited to the field-values associated 921 with the listed response header fields. That is, the specified 922 field-names(s) MUST NOT be stored by a shared cache, whereas the 923 remainder of the response message MAY be. 925 Note: This usage of the word private only controls where the 926 response can be stored; it cannot ensure the privacy of the 927 message content. Also, private response directives with field- 928 names are often handled by implementations as if an unqualified 929 private directive was received; i.e., the special handling for the 930 qualified form is not widely implemented. 932 no-cache 934 The no-cache response directive indicates that the response MUST 935 NOT be used to satisfy a subsequent request without successful 936 validation on the origin server. This allows an origin server to 937 prevent a cache from using it to satisfy a request without 938 contacting it, even by caches that have been configured to return 939 stale responses. 941 If the no-cache response directive specifies one or more field- 942 names, this requirement is limited to the field-values associated 943 with the listed response header fields. That is, the specified 944 field-name(s) MUST NOT be sent in the response to a subsequent 945 request without successful validation on the origin server. This 946 allows an origin server to prevent the re-use of certain header 947 fields in a response, while still allowing caching of the rest of 948 the response. 950 Note: Most HTTP/1.0 caches will not recognize or obey this 951 directive. Also, no-cache response directives with field-names 952 are often handled by implementations as if an unqualified no-cache 953 directive was received; i.e., the special handling for the 954 qualified form is not widely implemented. 956 no-store 958 The no-store response directive indicates that a cache MUST NOT 959 store any part of either the immediate request or response. This 960 directive applies to both non-shared and shared caches. "MUST NOT 961 store" in this context means that the cache MUST NOT intentionally 962 store the information in non-volatile storage, and MUST make a 963 best-effort attempt to remove the information from volatile 964 storage as promptly as possible after forwarding it. 966 This directive is NOT a reliable or sufficient mechanism for 967 ensuring privacy. In particular, malicious or compromised caches 968 might not recognize or obey this directive, and communications 969 networks might be vulnerable to eavesdropping. 971 must-revalidate 973 The must-revalidate response directive indicates that once it has 974 become stale, the response MUST NOT be used to satisfy subsequent 975 requests without successful validation on the origin server. 977 The must-revalidate directive is necessary to support reliable 978 operation for certain protocol features. In all circumstances an 979 HTTP/1.1 cache MUST obey the must-revalidate directive; in 980 particular, if the cache cannot reach the origin server for any 981 reason, it MUST generate a 504 (Gateway Timeout) response. 983 Servers SHOULD send the must-revalidate directive if and only if 984 failure to validate a request on the representation could result 985 in incorrect operation, such as a silently unexecuted financial 986 transaction. 988 proxy-revalidate 990 The proxy-revalidate response directive has the same meaning as 991 the must-revalidate response directive, except that it does not 992 apply to non-shared caches. 994 max-age 996 The max-age response directive indicates that response is to be 997 considered stale after its age is greater than the specified 998 number of seconds. 1000 s-maxage 1002 The s-maxage response directive indicates that, in shared caches, 1003 the maximum age specified by this directive overrides the maximum 1004 age specified by either the max-age directive or the Expires 1005 header field. The s-maxage directive also implies the semantics 1006 of the proxy-revalidate response directive. 1008 no-transform 1010 The no-transform response directive indicates that an intermediate 1011 cache or proxy MUST NOT change the Content-Encoding, Content-Range 1012 or Content-Type response header fields, nor the response 1013 representation. 1015 3.2.3. Cache Control Extensions 1017 The Cache-Control header field can be extended through the use of one 1018 or more cache-extension tokens, each with an optional value. 1019 Informational extensions (those that do not require a change in cache 1020 behavior) can be added without changing the semantics of other 1021 directives. Behavioral extensions are designed to work by acting as 1022 modifiers to the existing base of cache directives. Both the new 1023 directive and the standard directive are supplied, such that 1024 applications that do not understand the new directive will default to 1025 the behavior specified by the standard directive, and those that 1026 understand the new directive will recognize it as modifying the 1027 requirements associated with the standard directive. In this way, 1028 extensions to the cache-control directives can be made without 1029 requiring changes to the base protocol. 1031 This extension mechanism depends on an HTTP cache obeying all of the 1032 cache-control directives defined for its native HTTP-version, obeying 1033 certain extensions, and ignoring all directives that it does not 1034 understand. 1036 For example, consider a hypothetical new response directive called 1037 "community" that acts as a modifier to the private directive. We 1038 define this new directive to mean that, in addition to any non-shared 1039 cache, any cache that is shared only by members of the community 1040 named within its value may cache the response. An origin server 1041 wishing to allow the UCI community to use an otherwise private 1042 response in their shared cache(s) could do so by including 1044 Cache-Control: private, community="UCI" 1046 A cache seeing this header field will act correctly even if the cache 1047 does not understand the community cache-extension, since it will also 1048 see and understand the private directive and thus default to the safe 1049 behavior. 1051 Unrecognized cache directives MUST be ignored; it is assumed that any 1052 cache directive likely to be unrecognized by an HTTP/1.1 cache will 1053 be combined with standard directives (or the response's default 1054 cacheability) such that the cache behavior will remain minimally 1055 correct even if the cache does not understand the extension(s). 1057 The HTTP Cache Directive Registry defines the name space for the 1058 cache directives. 1060 Registrations MUST include the following fields: 1062 o Cache Directive Name 1064 o Pointer to specification text 1066 Values to be added to this name space are subject to IETF review 1067 ([RFC5226], Section 4.1). 1069 The registry itself is maintained at 1070 . 1072 3.3. Expires 1074 The "Expires" header field gives the date/time after which the 1075 response is considered stale. See Section 2.3 for further discussion 1076 of the freshness model. 1078 The presence of an Expires field does not imply that the original 1079 resource will change or cease to exist at, before, or after that 1080 time. 1082 The field-value is an absolute date and time as defined by HTTP-date 1083 in Section 6.1 of [Part1]; it MUST be sent in rfc1123-date format. 1085 Expires = "Expires" ":" OWS Expires-v 1086 Expires-v = HTTP-date 1088 For example 1090 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1092 Note: If a response includes a Cache-Control field with the max- 1093 age directive (see Section 3.2.2), that directive overrides the 1094 Expires field. Likewise, the s-maxage directive overrides Expires 1095 in shared caches. 1097 HTTP/1.1 servers SHOULD NOT send Expires dates more than one year in 1098 the future. 1100 HTTP/1.1 clients and caches MUST treat other invalid date formats, 1101 especially including the value "0", as in the past (i.e., "already 1102 expired"). 1104 3.4. Pragma 1106 The "Pragma" general-header field is used to include implementation- 1107 specific directives that might apply to any recipient along the 1108 request/response chain. All pragma directives specify optional 1109 behavior from the viewpoint of the protocol; however, some systems 1110 MAY require that behavior be consistent with the directives. 1112 Pragma = "Pragma" ":" OWS Pragma-v 1113 Pragma-v = 1#pragma-directive 1114 pragma-directive = "no-cache" / extension-pragma 1115 extension-pragma = token [ "=" ( token / quoted-string ) ] 1117 When the no-cache directive is present in a request message, an 1118 application SHOULD forward the request toward the origin server even 1119 if it has a cached copy of what is being requested. This pragma 1120 directive has the same semantics as the no-cache response directive 1121 (see Section 3.2.2) and is defined here for backward compatibility 1122 with HTTP/1.0. Clients SHOULD include both header fields when a no- 1123 cache request is sent to a server not known to be HTTP/1.1 compliant. 1124 HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had 1125 sent "Cache-Control: no-cache". 1127 Note: Because the meaning of "Pragma: no-cache" as a response- 1128 header field is not actually specified, it does not provide a 1129 reliable replacement for "Cache-Control: no-cache" in a response. 1131 This mechanism is deprecated; no new Pragma directives will be 1132 defined in HTTP. 1134 3.5. Vary 1136 The "Vary" response-header field conveys the set of request-header 1137 fields that were used to select the representation. 1139 Caches use this information, in part, to determine whether a stored 1140 response can be used to satisfy a given request; see Section 2.7. 1141 determines, while the response is fresh, whether a cache is permitted 1142 to use the response to reply to a subsequent request without 1143 validation; see Section 2.7. 1145 In uncacheable or stale responses, the Vary field value advises the 1146 user agent about the criteria that were used to select the 1147 representation. 1149 Vary = "Vary" ":" OWS Vary-v 1150 Vary-v = "*" / 1#field-name 1152 The set of header fields named by the Vary field value is known as 1153 the selecting request-header fields. 1155 Servers SHOULD include a Vary header field with any cacheable 1156 response that is subject to server-driven negotiation. Doing so 1157 allows a cache to properly interpret future requests on that resource 1158 and informs the user agent about the presence of negotiation on that 1159 resource. A server MAY include a Vary header field with a non- 1160 cacheable response that is subject to server-driven negotiation, 1161 since this might provide the user agent with useful information about 1162 the dimensions over which the response varies at the time of the 1163 response. 1165 A Vary field value of "*" signals that unspecified parameters not 1166 limited to the request-header fields (e.g., the network address of 1167 the client), play a role in the selection of the response 1168 representation; therefore, a cache cannot determine whether this 1169 response is appropriate. The "*" value MUST NOT be generated by a 1170 proxy server. 1172 The field-names given are not limited to the set of standard request- 1173 header fields defined by this specification. Field names are case- 1174 insensitive. 1176 3.6. Warning 1178 The "Warning" general-header field is used to carry additional 1179 information about the status or transformation of a message that 1180 might not be reflected in the message. This information is typically 1181 used to warn about possible incorrectness introduced by caching 1182 operations or transformations applied to the payload of the message. 1184 Warnings can be used for other purposes, both cache-related and 1185 otherwise. The use of a warning, rather than an error status code, 1186 distinguishes these responses from true failures. 1188 Warning header fields can in general be applied to any message, 1189 however some warn-codes are specific to caches and can only be 1190 applied to response messages. 1192 Warning = "Warning" ":" OWS Warning-v 1193 Warning-v = 1#warning-value 1195 warning-value = warn-code SP warn-agent SP warn-text 1196 [SP warn-date] 1198 warn-code = 3DIGIT 1199 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1200 ; the name or pseudonym of the server adding 1201 ; the Warning header field, for use in debugging 1202 warn-text = quoted-string 1203 warn-date = DQUOTE HTTP-date DQUOTE 1205 Multiple warnings can be attached to a response (either by the origin 1206 server or by a cache), including multiple warnings with the same code 1207 number, only differing in warn-text. 1209 When this occurs, the user agent SHOULD inform the user of as many of 1210 them as possible, in the order that they appear in the response. 1212 Systems that generate multiple Warning header fields SHOULD order 1213 them with this user agent behavior in mind. New Warning header 1214 fields SHOULD be added after any existing Warning headers fields. 1216 Warnings are assigned three digit warn-codes. The first digit 1217 indicates whether the Warning is required to be deleted from a stored 1218 response after validation: 1220 o 1xx Warnings describe the freshness or validation status of the 1221 response, and so MUST be deleted by caches after validation. They 1222 can only be generated by a cache when validating a cached entry, 1223 and MUST NOT be generated in any other situation. 1225 o 2xx Warnings describe some aspect of the representation that is 1226 not rectified by a validation (for example, a lossy compression of 1227 the representation) and MUST NOT be deleted by caches after 1228 validation, unless a full response is returned, in which case they 1229 MUST be. 1231 If an implementation sends a message with one or more Warning header 1232 fields to a receiver whose version is HTTP/1.0 or lower, then the 1233 sender MUST include in each warning-value a warn-date that matches 1234 the Date header field in the message. 1236 If an implementation receives a message with a warning-value that 1237 includes a warn-date, and that warn-date is different from the Date 1238 value in the response, then that warning-value MUST be deleted from 1239 the message before storing, forwarding, or using it. (preventing the 1240 consequences of naive caching of Warning header fields.) If all of 1241 the warning-values are deleted for this reason, the Warning header 1242 field MUST be deleted as well. 1244 The following warn-codes are defined by this specification, each with 1245 a recommended warn-text in English, and a description of its meaning. 1247 110 Response is stale 1249 SHOULD be included whenever the returned response is stale. 1251 111 Revalidation failed 1253 SHOULD be included if a cache returns a stale response because an 1254 attempt to validate the response failed, due to an inability to 1255 reach the server. 1257 112 Disconnected operation 1259 SHOULD be included if the cache is intentionally disconnected from 1260 the rest of the network for a period of time. 1262 113 Heuristic expiration 1264 SHOULD be included if the cache heuristically chose a freshness 1265 lifetime greater than 24 hours and the response's age is greater 1266 than 24 hours. 1268 199 Miscellaneous warning 1270 The warning text can include arbitrary information to be presented 1271 to a human user, or logged. A system receiving this warning MUST 1272 NOT take any automated action, besides presenting the warning to 1273 the user. 1275 214 Transformation applied 1277 MUST be added by an intermediate proxy if it applies any 1278 transformation to the representation, such as changing the 1279 content-coding, media-type, or modifying the representation data, 1280 unless this Warning code already appears in the response. 1282 299 Miscellaneous persistent warning 1284 The warning text can include arbitrary information to be presented 1285 to a human user, or logged. A system receiving this warning MUST 1286 NOT take any automated action. 1288 4. History Lists 1290 User agents often have history mechanisms, such as "Back" buttons and 1291 history lists, that can be used to redisplay a representation 1292 retrieved earlier in a session. 1294 The freshness model (Section 2.3) does not necessarily apply to 1295 history mechanisms. I.e., a history mechanism can display a previous 1296 representation even if it has expired. 1298 This does not prohibit the history mechanism from telling the user 1299 that a view might be stale, or from honoring cache directives (e.g., 1300 Cache-Control: no-store). 1302 5. IANA Considerations 1304 5.1. Cache Directive Registry 1306 The registration procedure for HTTP Cache Directives is defined by 1307 Section 3.2.3 of this document. 1309 The HTTP Cache Directive Registry shall be created at 1310 and be 1311 populated with the registrations below: 1313 +------------------------+------------------------------+ 1314 | Cache Directive | Reference | 1315 +------------------------+------------------------------+ 1316 | max-age | Section 3.2.1, Section 3.2.2 | 1317 | max-stale | Section 3.2.1 | 1318 | min-fresh | Section 3.2.1 | 1319 | must-revalidate | Section 3.2.2 | 1320 | no-cache | Section 3.2.1, Section 3.2.2 | 1321 | no-store | Section 3.2.1, Section 3.2.2 | 1322 | no-transform | Section 3.2.1, Section 3.2.2 | 1323 | only-if-cached | Section 3.2.1 | 1324 | private | Section 3.2.2 | 1325 | proxy-revalidate | Section 3.2.2 | 1326 | public | Section 3.2.2 | 1327 | s-maxage | Section 3.2.2 | 1328 | stale-if-error | [RFC5861], Section 4 | 1329 | stale-while-revalidate | [RFC5861], Section 3 | 1330 +------------------------+------------------------------+ 1332 5.2. Header Field Registration 1334 The Message Header Field Registry located at shall be 1336 updated with the permanent registrations below (see [RFC3864]): 1338 +-------------------+----------+----------+-------------+ 1339 | Header Field Name | Protocol | Status | Reference | 1340 +-------------------+----------+----------+-------------+ 1341 | Age | http | standard | Section 3.1 | 1342 | Cache-Control | http | standard | Section 3.2 | 1343 | Expires | http | standard | Section 3.3 | 1344 | Pragma | http | standard | Section 3.4 | 1345 | Vary | http | standard | Section 3.5 | 1346 | Warning | http | standard | Section 3.6 | 1347 +-------------------+----------+----------+-------------+ 1349 The change controller is: "IETF (iesg@ietf.org) - Internet 1350 Engineering Task Force". 1352 6. Security Considerations 1354 Caches expose additional potential vulnerabilities, since the 1355 contents of the cache represent an attractive target for malicious 1356 exploitation. Because cache contents persist after an HTTP request 1357 is complete, an attack on the cache can reveal information long after 1358 a user believes that the information has been removed from the 1359 network. Therefore, cache contents need to be protected as sensitive 1360 information. 1362 7. Acknowledgments 1364 Much of the content and presentation of the caching design is due to 1365 suggestions and comments from individuals including: Shel Kaphan, 1366 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 1368 8. References 1370 8.1. Normative References 1372 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1373 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1374 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 1375 and Message Parsing", draft-ietf-httpbis-p1-messaging-12 1376 (work in progress), October 2010. 1378 [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1379 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1380 and J. Reschke, Ed., "HTTP/1.1, part 2: Message 1381 Semantics", draft-ietf-httpbis-p2-semantics-12 (work in 1382 progress), October 2010. 1384 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1385 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1386 and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional 1387 Requests", draft-ietf-httpbis-p4-conditional-12 (work in 1388 progress), October 2010. 1390 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1391 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1392 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 1393 Partial Responses", draft-ietf-httpbis-p5-range-12 (work 1394 in progress), October 2010. 1396 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1397 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1398 and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", 1399 draft-ietf-httpbis-p7-auth-12 (work in progress), 1400 October 2010. 1402 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1403 Requirement Levels", BCP 14, RFC 2119, March 1997. 1405 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1406 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1408 8.2. Informative References 1410 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1411 Specification, Implementation", RFC 1305, March 1992. 1413 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1414 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1415 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1417 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1418 Procedures for Message Header Fields", BCP 90, RFC 3864, 1419 September 2004. 1421 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1422 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1423 May 2008. 1425 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1426 Content", RFC 5861, April 2010. 1428 Appendix A. Changes from RFC 2616 1430 Make the specified age calculation algorithm less conservative. 1431 (Section 2.3.2) 1433 Remove requirement to consider Content-Location in successful 1434 responses in order to determine the appropriate response to use. 1435 (Section 2.4) 1437 Clarify denial of service attack avoidance requirement. 1438 (Section 2.5) 1440 Do not mention RFC 2047 encoding and multiple languages in Warning 1441 header fields anymore, as these aspects never were implemented. 1442 (Section 3.6) 1444 Appendix B. Collected ABNF 1446 Age = "Age:" OWS Age-v 1447 Age-v = delta-seconds 1449 Cache-Control = "Cache-Control:" OWS Cache-Control-v 1450 Cache-Control-v = *( "," OWS ) cache-directive *( OWS "," [ OWS 1451 cache-directive ] ) 1453 Expires = "Expires:" OWS Expires-v 1454 Expires-v = HTTP-date 1456 HTTP-date = 1458 OWS = 1460 Pragma = "Pragma:" OWS Pragma-v 1461 Pragma-v = *( "," OWS ) pragma-directive *( OWS "," [ OWS 1462 pragma-directive ] ) 1464 Vary = "Vary:" OWS Vary-v 1465 Vary-v = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name 1466 ] ) ) 1468 Warning = "Warning:" OWS Warning-v 1469 Warning-v = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value 1470 ] ) 1472 cache-directive = cache-request-directive / cache-response-directive 1473 cache-extension = token [ "=" ( token / quoted-string ) ] 1474 cache-request-directive = "no-cache" / "no-store" / ( "max-age=" 1475 delta-seconds ) / ( "max-stale" [ "=" delta-seconds ] ) / ( 1476 "min-fresh=" delta-seconds ) / "no-transform" / "only-if-cached" / 1477 cache-extension 1478 cache-response-directive = "public" / ( "private" [ "=" DQUOTE *( "," 1479 OWS ) field-name *( OWS "," [ OWS field-name ] ) DQUOTE ] ) / ( 1480 "no-cache" [ "=" DQUOTE *( "," OWS ) field-name *( OWS "," [ OWS 1481 field-name ] ) DQUOTE ] ) / "no-store" / "no-transform" / 1482 "must-revalidate" / "proxy-revalidate" / ( "max-age=" delta-seconds 1483 ) / ( "s-maxage=" delta-seconds ) / cache-extension 1485 delta-seconds = 1*DIGIT 1487 extension-pragma = token [ "=" ( token / quoted-string ) ] 1489 field-name = 1491 port = 1492 pragma-directive = "no-cache" / extension-pragma 1493 pseudonym = 1495 quoted-string = 1497 token = 1499 uri-host = 1501 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1502 warn-code = 3DIGIT 1503 warn-date = DQUOTE HTTP-date DQUOTE 1504 warn-text = quoted-string 1505 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date 1506 ] 1508 ABNF diagnostics: 1510 ; Age defined but not used 1511 ; Cache-Control defined but not used 1512 ; Expires defined but not used 1513 ; Pragma defined but not used 1514 ; Vary defined but not used 1515 ; Warning defined but not used 1517 Appendix C. Change Log (to be removed by RFC Editor before publication) 1518 C.1. Since RFC 2616 1520 Extracted relevant partitions from [RFC2616]. 1522 C.2. Since draft-ietf-httpbis-p6-cache-00 1524 Closed issues: 1526 o : "Trailer" 1527 () 1529 o : "Invalidation 1530 after Update or Delete" 1531 () 1533 o : "Normative and 1534 Informative references" 1536 o : "Date reference 1537 typo" 1539 o : "Connection 1540 header text" 1542 o : "Informative 1543 references" 1545 o : "ISO-8859-1 1546 Reference" 1548 o : "Normative up- 1549 to-date references" 1551 o : "typo in 1552 13.2.2" 1554 Other changes: 1556 o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress 1557 on ) 1559 C.3. Since draft-ietf-httpbis-p6-cache-01 1561 Closed issues: 1563 o : "rel_path not 1564 used" 1566 Other changes: 1568 o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work 1569 in progress on ) 1571 o Add explicit references to BNF syntax and rules imported from 1572 other parts of the specification. 1574 C.4. Since draft-ietf-httpbis-p6-cache-02 1576 Ongoing work on IANA Message Header Field Registration 1577 (): 1579 o Reference RFC 3984, and update header field registrations for 1580 header fields defined in this document. 1582 C.5. Since draft-ietf-httpbis-p6-cache-03 1584 Closed issues: 1586 o : "Vary header 1587 classification" 1589 C.6. Since draft-ietf-httpbis-p6-cache-04 1591 Ongoing work on ABNF conversion 1592 (): 1594 o Use "/" instead of "|" for alternatives. 1596 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1597 whitespace ("OWS") and required whitespace ("RWS"). 1599 o Rewrite ABNFs to spell out whitespace rules, factor out header 1600 field value format definitions. 1602 C.7. Since draft-ietf-httpbis-p6-cache-05 1604 This is a total rewrite of this part of the specification. 1606 Affected issues: 1608 o : "Definition of 1609 1xx Warn-Codes" 1611 o : "Placement of 1612 13.5.1 and 13.5.2" 1614 o : "The role of 1615 Warning and Semantic Transparency in Caching" 1617 o : "Methods and 1618 Caching" 1620 In addition: Final work on ABNF conversion 1621 (): 1623 o Add appendix containing collected and expanded ABNF, reorganize 1624 ABNF introduction. 1626 C.8. Since draft-ietf-httpbis-p6-cache-06 1628 Closed issues: 1630 o : "base for 1631 numeric protocol elements" 1633 Affected issues: 1635 o : WVary and non- 1636 existant headers" 1638 C.9. Since draft-ietf-httpbis-p6-cache-07 1640 Closed issues: 1642 o : "Definition of 1643 1xx Warn-Codes" 1645 o : "Content- 1646 Location on 304 responses" 1648 o : "private and 1649 no-cache CC directives with headers" 1651 o : "RFC2047 and 1652 warn-text" 1654 C.10. Since draft-ietf-httpbis-p6-cache-08 1656 Closed issues: 1658 o : "serving 1659 negotiated responses from cache: header-specific canonicalization" 1661 o : "Effect of CC 1662 directives on history lists" 1664 Affected issues: 1666 o : Status codes 1667 and caching 1669 Partly resolved issues: 1671 o : "Placement of 1672 13.5.1 and 13.5.2" 1674 C.11. Since draft-ietf-httpbis-p6-cache-09 1676 Closed issues: 1678 o : "Age 1679 calculation" 1681 o : "Clarify 1682 differences between / requirements for request and response CC 1683 directives" 1685 o : "Caching 1686 authenticated responses" 1688 o : "IANA registry 1689 for cache-control directives" 1691 o : "Heuristic 1692 caching of URLs with query components" 1694 Partly resolved issues: 1696 o : "Term for the 1697 requested resource's URI" 1699 C.12. Since draft-ietf-httpbis-p6-cache-10 1701 Closed issues: 1703 o : "Clarify 1704 entity / representation / variant terminology" 1706 o : "consider 1707 removing the 'changes from 2068' sections" 1709 o : "Allowing 1710 heuristic caching for new status codes" 1712 o : "Allowing 1713 heuristic caching for new status codes" 1715 o Clean up TODOs and prose in "Combining Responses." 1717 C.13. Since draft-ietf-httpbis-p6-cache-11 1719 Closed issues: 1721 o : "Text about 1722 clock requirement for caches belongs in p6" 1724 Index 1726 A 1727 age 6 1728 Age header 17 1730 C 1731 cache 5 1732 Cache Directives 1733 max-age 19, 22 1734 max-stale 19 1735 min-fresh 20 1736 must-revalidate 22 1737 no-cache 19, 21 1738 no-store 19, 21 1739 no-transform 20, 23 1740 only-if-cached 20 1741 private 21 1742 proxy-revalidate 22 1743 public 20 1744 s-maxage 22 1745 Cache-Control header 18 1746 cacheable 5 1748 E 1749 Expires header 24 1750 explicit expiration time 5 1752 F 1753 first-hand 6 1754 fresh 6 1755 freshness lifetime 6 1757 G 1758 Grammar 1759 Age 18 1760 Age-v 18 1761 Cache-Control 18 1762 Cache-Control-v 18 1763 cache-extension 18 1764 cache-request-directive 19 1765 cache-response-directive 20 1766 delta-seconds 18 1767 Expires 24 1768 Expires-v 24 1769 extension-pragma 25 1770 Pragma 25 1771 pragma-directive 25 1772 Pragma-v 25 1773 Vary 25 1774 Vary-v 25 1775 warn-agent 27 1776 warn-code 27 1777 warn-date 27 1778 warn-text 27 1779 Warning 27 1780 Warning-v 27 1781 warning-value 27 1783 H 1784 Headers 1785 Age 17 1786 Cache-Control 18 1787 Expires 24 1788 Pragma 25 1789 Vary 25 1790 Warning 26 1791 heuristic expiration time 5 1793 M 1794 max-age 1795 Cache Directive 19, 22 1796 max-stale 1797 Cache Directive 19 1798 min-fresh 1799 Cache Directive 20 1800 must-revalidate 1801 Cache Directive 22 1803 N 1804 no-cache 1805 Cache Directive 19, 21 1806 no-store 1807 Cache Directive 19, 21 1808 no-transform 1809 Cache Directive 20, 23 1811 O 1812 only-if-cached 1813 Cache Directive 20 1815 P 1816 Pragma header 25 1817 private 1818 Cache Directive 21 1819 proxy-revalidate 1820 Cache Directive 22 1821 public 1822 Cache Directive 20 1824 S 1825 s-maxage 1826 Cache Directive 22 1827 stale 6 1829 V 1830 validator 6 1831 Vary header 25 1833 W 1834 Warning header 26 1836 Authors' Addresses 1838 Roy T. Fielding (editor) 1839 Day Software 1840 23 Corporate Plaza DR, Suite 280 1841 Newport Beach, CA 92660 1842 USA 1844 Phone: +1-949-706-5300 1845 Fax: +1-949-706-5305 1846 EMail: fielding@gbiv.com 1847 URI: http://roy.gbiv.com/ 1848 Jim Gettys 1849 Alcatel-Lucent Bell Labs 1850 21 Oak Knoll Road 1851 Carlisle, MA 01741 1852 USA 1854 EMail: jg@freedesktop.org 1855 URI: http://gettys.wordpress.com/ 1857 Jeffrey C. Mogul 1858 Hewlett-Packard Company 1859 HP Labs, Large Scale Systems Group 1860 1501 Page Mill Road, MS 1177 1861 Palo Alto, CA 94304 1862 USA 1864 EMail: JeffMogul@acm.org 1866 Henrik Frystyk Nielsen 1867 Microsoft Corporation 1868 1 Microsoft Way 1869 Redmond, WA 98052 1870 USA 1872 EMail: henrikn@microsoft.com 1874 Larry Masinter 1875 Adobe Systems, Incorporated 1876 345 Park Ave 1877 San Jose, CA 95110 1878 USA 1880 EMail: LMM@acm.org 1881 URI: http://larry.masinter.net/ 1883 Paul J. Leach 1884 Microsoft Corporation 1885 1 Microsoft Way 1886 Redmond, WA 98052 1888 EMail: paulle@microsoft.com 1889 Tim Berners-Lee 1890 World Wide Web Consortium 1891 MIT Computer Science and Artificial Intelligence Laboratory 1892 The Stata Center, Building 32 1893 32 Vassar Street 1894 Cambridge, MA 02139 1895 USA 1897 EMail: timbl@w3.org 1898 URI: http://www.w3.org/People/Berners-Lee/ 1900 Yves Lafon (editor) 1901 World Wide Web Consortium 1902 W3C / ERCIM 1903 2004, rte des Lucioles 1904 Sophia-Antipolis, AM 06902 1905 France 1907 EMail: ylafon@w3.org 1908 URI: http://www.raubacapeu.net/people/yves/ 1910 Mark Nottingham (editor) 1912 EMail: mnot@mnot.net 1913 URI: http://www.mnot.net/ 1915 Julian F. Reschke (editor) 1916 greenbytes GmbH 1917 Hafenweg 16 1918 Muenster, NW 48155 1919 Germany 1921 Phone: +49 251 2807760 1922 Fax: +49 251 2807761 1923 EMail: julian.reschke@greenbytes.de 1924 URI: http://greenbytes.de/tech/webdav/