idnits 2.17.1 draft-ietf-httpbis-p6-cache-14.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 (April 18, 2011) is 4729 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-14 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-14 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-14 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-14 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-14 -- Obsolete informational reference (is this intentional?): RFC 1305 (Obsoleted by RFC 5905) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis Working Group R. Fielding, Ed. 3 Internet-Draft Adobe 4 Obsoletes: 2616 (if approved) J. Gettys 5 Intended status: Standards Track Alcatel-Lucent 6 Expires: October 20, 2011 J. Mogul 7 HP 8 H. Frystyk 9 Microsoft 10 L. Masinter 11 Adobe 12 P. Leach 13 Microsoft 14 T. Berners-Lee 15 W3C/MIT 16 Y. Lafon, Ed. 17 W3C 18 M. Nottingham, Ed. 20 J. Reschke, Ed. 21 greenbytes 22 April 18, 2011 24 HTTP/1.1, part 6: Caching 25 draft-ietf-httpbis-p6-cache-14 27 Abstract 29 The Hypertext Transfer Protocol (HTTP) is an application-level 30 protocol for distributed, collaborative, hypermedia information 31 systems. This document is Part 6 of the seven-part specification 32 that defines the protocol referred to as "HTTP/1.1" and, taken 33 together, obsoletes RFC 2616. Part 6 defines requirements on HTTP 34 caches and the associated header fields that control cache behavior 35 or indicate cacheable response messages. 37 Editorial Note (To be removed by RFC Editor) 39 Discussion of this draft should take place on the HTTPBIS working 40 group mailing list (ietf-http-wg@w3.org), which is archived at 41 . 43 The current issues list is at 44 and related 45 documents (including fancy diffs) can be found at 46 . 48 The changes in this draft are summarized in Appendix C.15. 50 Status of This Memo 52 This Internet-Draft is submitted in full conformance with the 53 provisions of BCP 78 and BCP 79. 55 Internet-Drafts are working documents of the Internet Engineering 56 Task Force (IETF). Note that other groups may also distribute 57 working documents as Internet-Drafts. The list of current Internet- 58 Drafts is at http://datatracker.ietf.org/drafts/current/. 60 Internet-Drafts are draft documents valid for a maximum of six months 61 and may be updated, replaced, or obsoleted by other documents at any 62 time. It is inappropriate to use Internet-Drafts as reference 63 material or to cite them other than as "work in progress." 65 This Internet-Draft will expire on October 20, 2011. 67 Copyright Notice 69 Copyright (c) 2011 IETF Trust and the persons identified as the 70 document authors. All rights reserved. 72 This document is subject to BCP 78 and the IETF Trust's Legal 73 Provisions Relating to IETF Documents 74 (http://trustee.ietf.org/license-info) in effect on the date of 75 publication of this document. Please review these documents 76 carefully, as they describe your rights and restrictions with respect 77 to this document. Code Components extracted from this document must 78 include Simplified BSD License text as described in Section 4.e of 79 the Trust Legal Provisions and are provided without warranty as 80 described in the Simplified BSD License. 82 This document may contain material from IETF Documents or IETF 83 Contributions published or made publicly available before November 84 10, 2008. The person(s) controlling the copyright in some of this 85 material may not have granted the IETF Trust the right to allow 86 modifications of such material outside the IETF Standards Process. 87 Without obtaining an adequate license from the person(s) controlling 88 the copyright in such materials, this document may not be modified 89 outside the IETF Standards Process, and derivative works of it may 90 not be created outside the IETF Standards Process, except to format 91 it for publication as an RFC or to translate it into languages other 92 than English. 94 Table of Contents 96 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 97 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 98 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 99 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 7 100 1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 101 1.4.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 7 102 1.4.2. ABNF Rules defined in other Parts of the 103 Specification . . . . . . . . . . . . . . . . . . . . 7 104 2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 8 105 2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 8 106 2.1.1. Storing Partial and Incomplete Responses . . . . . . . 9 107 2.2. Constructing Responses from Caches . . . . . . . . . . . . 9 108 2.3. Freshness Model . . . . . . . . . . . . . . . . . . . . . 10 109 2.3.1. Calculating Freshness Lifetime . . . . . . . . . . . . 11 110 2.3.2. Calculating Age . . . . . . . . . . . . . . . . . . . 12 111 2.3.3. Serving Stale Responses . . . . . . . . . . . . . . . 13 112 2.4. Validation Model . . . . . . . . . . . . . . . . . . . . . 14 113 2.5. Request Methods that Invalidate . . . . . . . . . . . . . 15 114 2.6. Shared Caching of Authenticated Responses . . . . . . . . 15 115 2.7. Caching Negotiated Responses . . . . . . . . . . . . . . . 16 116 2.8. Combining Responses . . . . . . . . . . . . . . . . . . . 17 117 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 17 118 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 119 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 18 120 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 19 121 3.2.2. Response Cache-Control Directives . . . . . . . . . . 21 122 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 23 123 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 24 124 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 25 125 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 126 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 26 127 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 29 128 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 129 5.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 29 130 5.2. Header Field Registration . . . . . . . . . . . . . . . . 30 131 6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 132 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 31 133 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 134 8.1. Normative References . . . . . . . . . . . . . . . . . . . 31 135 8.2. Informative References . . . . . . . . . . . . . . . . . . 32 136 Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 32 137 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 32 138 Appendix C. Change Log (to be removed by RFC Editor before 139 publication) . . . . . . . . . . . . . . . . . . . . 34 140 C.1. Since RFC 2616 . . . . . . . . . . . . . . . . . . . . . . 34 141 C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 34 142 C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 35 143 C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 35 144 C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 35 145 C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 35 146 C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 36 147 C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 36 148 C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 36 149 C.10. Since draft-ietf-httpbis-p6-cache-08 . . . . . . . . . . . 37 150 C.11. Since draft-ietf-httpbis-p6-cache-09 . . . . . . . . . . . 37 151 C.12. Since draft-ietf-httpbis-p6-cache-10 . . . . . . . . . . . 38 152 C.13. Since draft-ietf-httpbis-p6-cache-11 . . . . . . . . . . . 38 153 C.14. Since draft-ietf-httpbis-p6-cache-12 . . . . . . . . . . . 38 154 C.15. Since draft-ietf-httpbis-p6-cache-13 . . . . . . . . . . . 38 155 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 157 1. Introduction 159 HTTP is typically used for distributed information systems, where 160 performance can be improved by the use of response caches. This 161 document defines aspects of HTTP/1.1 related to caching and reusing 162 response messages. 164 1.1. Purpose 166 An HTTP cache is a local store of response messages and the subsystem 167 that controls its message storage, retrieval, and deletion. A cache 168 stores cacheable responses in order to reduce the response time and 169 network bandwidth consumption on future, equivalent requests. Any 170 client or server MAY employ a cache, though a cache cannot be used by 171 a server that is acting as a tunnel. 173 Caching would be useless if it did not significantly improve 174 performance. The goal of caching in HTTP/1.1 is to reuse a prior 175 response message to satisfy a current request. In some cases, a 176 stored response can be reused without the need for a network request, 177 reducing latency and network round-trips; a "freshness" mechanism is 178 used for this purpose (see Section 2.3). Even when a new request is 179 required, it is often possible to reuse all or parts of the payload 180 of a prior response to satisfy the request, thereby reducing network 181 bandwidth usage; a "validation" mechanism is used for this purpose 182 (see Section 2.4). 184 1.2. Terminology 186 This specification uses a number of terms to refer to the roles 187 played by participants in, and objects of, HTTP caching. 189 cache 191 A conformant implementation of a HTTP cache. Note that this 192 implies an HTTP/1.1 cache; this specification does not define 193 conformance for HTTP/1.0 caches. 195 shared cache 197 A cache that is accessible to more than one user; usually (but not 198 always) deployed as part of an intermediary. 200 private cache 202 A cache that is dedicated to a single user. 204 cacheable 206 A response is cacheable if a cache is allowed to store a copy of 207 the response message for use in answering subsequent requests. 208 Even when a response is cacheable, there might be additional 209 constraints on whether a cache can use the stored copy to satisfy 210 a particular request. 212 explicit expiration time 214 The time at which the origin server intends that a representation 215 no longer be returned by a cache without further validation. 217 heuristic expiration time 219 An expiration time assigned by a cache when no explicit expiration 220 time is available. 222 age 224 The age of a response is the time since it was sent by, or 225 successfully validated with, the origin server. 227 first-hand 229 A response is first-hand if the freshness model is not in use; 230 i.e., its age is 0. 232 freshness lifetime 234 The length of time between the generation of a response and its 235 expiration time. 237 fresh 239 A response is fresh if its age has not yet exceeded its freshness 240 lifetime. 242 stale 244 A response is stale if its age has passed its freshness lifetime 245 (either explicit or heuristic). 247 validator 249 A protocol element (e.g., an entity-tag or a Last-Modified time) 250 that is used to find out whether a stored response is an 251 equivalent copy of a representation. 253 1.3. Requirements 255 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 256 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 257 document are to be interpreted as described in [RFC2119]. 259 An implementation is not compliant if it fails to satisfy one or more 260 of the "MUST" or "REQUIRED" level requirements for the protocols it 261 implements. An implementation that satisfies all the "MUST" or 262 "REQUIRED" level and all the "SHOULD" level requirements for its 263 protocols is said to be "unconditionally compliant"; one that 264 satisfies all the "MUST" level requirements but not all the "SHOULD" 265 level requirements for its protocols is said to be "conditionally 266 compliant". 268 1.4. Syntax Notation 270 This specification uses the ABNF syntax defined in Section 1.2 of 271 [Part1] (which extends the syntax defined in [RFC5234] with a list 272 rule). Appendix B shows the collected ABNF, with the list rule 273 expanded. 275 The following core rules are included by reference, as defined in 276 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 277 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 278 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 279 sequence of data), SP (space), VCHAR (any visible USASCII character), 280 and WSP (whitespace). 282 1.4.1. Core Rules 284 The core rules below are defined in Section 1.2.2 of [Part1]: 286 quoted-string = 287 token = 288 OWS = 290 1.4.2. ABNF Rules defined in other Parts of the Specification 292 The ABNF rules below are defined in other parts: 294 field-name = 295 HTTP-date = 296 port = 297 pseudonym = 298 uri-host = 300 2. Cache Operation 302 2.1. Response Cacheability 304 A cache MUST NOT store a response to any request, unless: 306 o The request method is understood by the cache and defined as being 307 cacheable, and 309 o the response status code is understood by the cache, and 311 o the "no-store" cache directive (see Section 3.2) does not appear 312 in request or response header fields, and 314 o the "private" cache response directive (see Section 3.2.2 does not 315 appear in the response, if the cache is shared, and 317 o the "Authorization" header field (see Section 4.1 of [Part7]) does 318 not appear in the request, if the cache is shared, unless the 319 response explicitly allows it (see Section 2.6), and 321 o the response either: 323 * contains an Expires header field (see Section 3.3), or 325 * contains a max-age response cache directive (see 326 Section 3.2.2), or 328 * contains a s-maxage response cache directive and the cache is 329 shared, or 331 * contains a Cache Control Extension (see Section 3.2.3) that 332 allows it to be cached, or 334 * has a status code that can be served with heuristic freshness 335 (see Section 2.3.1.1). 337 In this context, a cache has "understood" a request method or a 338 response status code if it recognises it and implements any cache- 339 specific behaviour. In particular, 206 Partial Content responses 340 cannot be cached by an implementation that does not handle partial 341 content (see Section 2.1.1). 343 Note that in normal operation, most caches will not store a response 344 that has neither a cache validator nor an explicit expiration time, 345 as such responses are not usually useful to store. However, caches 346 are not prohibited from storing such responses. 348 2.1.1. Storing Partial and Incomplete Responses 350 A cache that receives an incomplete response (for example, with fewer 351 bytes of data than specified in a Content-Length header field) can 352 store the response, but MUST treat it as a partial response [Part5]. 353 Partial responses can be combined as described in Section 4 of 354 [Part5]; the result might be a full response or might still be 355 partial. A cache MUST NOT return a partial response to a client 356 without explicitly marking it as such using the 206 (Partial Content) 357 status code. 359 A cache that does not support the Range and Content-Range header 360 fields MUST NOT store incomplete or partial responses. 362 2.2. Constructing Responses from Caches 364 For a presented request, a cache MUST NOT return a stored response, 365 unless: 367 o The presented effective request URI (Section 4.3 of [Part1]) and 368 that of the stored response match, and 370 o the request method associated with the stored response allows it 371 to be used for the presented request, and 373 o selecting header fields nominated by the stored response (if any) 374 match those presented (see Section 2.7), and 376 o the presented request and stored response are free from directives 377 that would prevent its use (see Section 3.2 and Section 3.4), and 379 o the stored response is either: 381 * fresh (see Section 2.3), or 383 * allowed to be served stale (see Section 2.3.3), or 385 * successfully validated (see Section 2.4). 387 When a stored response is used to satisfy a request without 388 validation, a cache MUST include a single Age header field 389 (Section 3.1) in the response with a value equal to the stored 390 response's current_age; see Section 2.3.2. 392 A cache MUST write through requests with methods that are unsafe 393 (Section 7.1.1 of [Part2]) to the origin server; i.e., a cache must 394 not generate a reply to such a request before having forwarded the 395 request and having received a corresponding response. 397 Also, note that unsafe requests might invalidate already stored 398 responses; see Section 2.5. 400 A cache MUST use the most recent response (as determined by the Date 401 header field) when more than one suitable response is stored. It can 402 also forward a request with "Cache-Control: max-age=0" or "Cache- 403 Control: no-cache" to disambiguate which response to use. 405 A cache that does not have a clock available MUST NOT use stored 406 responses without revalidating them on every use. A cache, 407 especially a shared cache, SHOULD use a mechanism, such as NTP 408 [RFC1305], to synchronize its clock with a reliable external 409 standard. 411 2.3. Freshness Model 413 When a response is "fresh" in the cache, it can be used to satisfy 414 subsequent requests without contacting the origin server, thereby 415 improving efficiency. 417 The primary mechanism for determining freshness is for an origin 418 server to provide an explicit expiration time in the future, using 419 either the Expires header field (Section 3.3) or the max-age response 420 cache directive (Section 3.2.2). Generally, origin servers will 421 assign future explicit expiration times to responses in the belief 422 that the representation is not likely to change in a semantically 423 significant way before the expiration time is reached. 425 If an origin server wishes to force a cache to validate every 426 request, it can assign an explicit expiration time in the past to 427 indicate that the response is already stale. Compliant caches will 428 normally validate the cached response before reusing it for 429 subsequent requests (see Section 2.3.3). 431 Since origin servers do not always provide explicit expiration times, 432 a cache MAY assign a heuristic expiration time when an explicit time 433 is not specified, employing algorithms that use other header field 434 values (such as the Last-Modified time) to estimate a plausible 435 expiration time. This specification does not provide specific 436 algorithms, but does impose worst-case constraints on their results. 438 The calculation to determine if a response is fresh is: 440 response_is_fresh = (freshness_lifetime > current_age) 442 The freshness_lifetime is defined in Section 2.3.1; the current_age 443 is defined in Section 2.3.2. 445 Additionally, clients might need to influence freshness calculation. 446 They can do this using several request cache directives, with the 447 effect of either increasing or loosening constraints on freshness. 448 See Section 3.2.1. 450 [[ISSUE-no-req-for-directives: there are not requirements directly 451 applying to cache-request-directives and freshness.]] 453 Note that freshness applies only to cache operation; it cannot be 454 used to force a user agent to refresh its display or reload a 455 resource. See Section 4 for an explanation of the difference between 456 caches and history mechanisms. 458 2.3.1. Calculating Freshness Lifetime 460 A cache can calculate the freshness lifetime (denoted as 461 freshness_lifetime) of a response by using the first match of: 463 o If the cache is shared and the s-maxage response cache directive 464 (Section 3.2.2) is present, use its value, or 466 o If the max-age response cache directive (Section 3.2.2) is 467 present, use its value, or 469 o If the Expires response header field (Section 3.3) is present, use 470 its value minus the value of the Date response header field, or 472 o Otherwise, no explicit expiration time is present in the response. 473 A heuristic freshness lifetime might be applicable; see 474 Section 2.3.1.1. 476 Note that this calculation is not vulnerable to clock skew, since all 477 of the information comes from the origin server. 479 2.3.1.1. Calculating Heuristic Freshness 481 If no explicit expiration time is present in a stored response that 482 has a status code whose definition allows heuristic freshness to be 483 used (including the following in Section 8 of [Part2]: 200, 203, 206, 484 300, 301 and 410), a cache MAY calculate a heuristic expiration time. 485 A cache MUST NOT use heuristics to determine freshness for responses 486 with status codes that do not explicitly allow it. 488 When a heuristic is used to calculate freshness lifetime, a cache 489 SHOULD attach a Warning header field with a 113 warn-code to the 490 response if its current_age is more than 24 hours and such a warning 491 is not already present. 493 Also, if the response has a Last-Modified header field (Section 2.1 494 of [Part4]), a cache SHOULD NOT use a heuristic expiration value that 495 is more than some fraction of the interval since that time. A 496 typical setting of this fraction might be 10%. 498 Note: RFC 2616 ([RFC2616], Section 13.9) required that caches do 499 not calculate heuristic freshness for URIs with query components 500 (i.e., those containing '?'). In practice, this has not been 501 widely implemented. Therefore, servers are encouraged to send 502 explicit directives (e.g., Cache-Control: no-cache) if they wish 503 to preclude caching. 505 2.3.2. Calculating Age 507 HTTP/1.1 uses the Age header field to convey the estimated age of the 508 response message when obtained from a cache. The Age field value is 509 the cache's estimate of the amount of time since the response was 510 generated or validated by the origin server. In essence, the Age 511 value is the sum of the time that the response has been resident in 512 each of the caches along the path from the origin server, plus the 513 amount of time it has been in transit along network paths. 515 The following data is used for the age calculation: 517 age_value 519 The term "age_value" denotes the value of the Age header field 520 (Section 3.1), in a form appropriate for arithmetic operation; or 521 0, if not available. 523 date_value 525 HTTP/1.1 requires origin servers to send a Date header field, if 526 possible, with every response, giving the time at which the 527 response was generated. The term "date_value" denotes the value 528 of the Date header field, in a form appropriate for arithmetic 529 operations. See Section 9.3 of [Part1] for the definition of the 530 Date header field, and for requirements regarding responses 531 without it. 533 now 535 The term "now" means "the current value of the clock at the host 536 performing the calculation". A cache SHOULD use NTP ([RFC1305]) 537 or some similar protocol to synchronize its clocks to a globally 538 accurate time standard. 540 request_time 542 The current value of the clock at the host at the time the request 543 resulting in the stored response was made. 545 response_time 547 The current value of the clock at the host at the time the 548 response was received. 550 A response's age can be calculated in two entirely independent ways: 552 1. the "apparent_age": response_time minus date_value, if the local 553 clock is reasonably well synchronized to the origin server's 554 clock. If the result is negative, the result is replaced by 555 zero. 557 2. the "corrected_age_value", if all of the caches along the 558 response path implement HTTP/1.1. A cache MUST interpret this 559 value relative to the time the request was initiated, not the 560 time that the response was received. 562 apparent_age = max(0, response_time - date_value); 564 response_delay = response_time - request_time; 565 corrected_age_value = age_value + response_delay; 567 These are combined as 569 corrected_initial_age = max(apparent_age, corrected_age_value); 571 The current_age of a stored response can then be calculated by adding 572 the amount of time (in seconds) since the stored response was last 573 validated by the origin server to the corrected_initial_age. 575 resident_time = now - response_time; 576 current_age = corrected_initial_age + resident_time; 578 2.3.3. Serving Stale Responses 580 A "stale" response is one that either has explicit expiry information 581 or is allowed to have heuristic expiry calculated, but is not fresh 582 according to the calculations in Section 2.3. 584 A cache MUST NOT return a stale response if it is prohibited by an 585 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" 586 cache directive, a "must-revalidate" cache-response-directive, or an 587 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 588 see Section 3.2.2). 590 A cache SHOULD NOT return stale responses unless it is disconnected 591 (i.e., it cannot contact the origin server or otherwise find a 592 forward path) or doing so is explicitly allowed (e.g., by the max- 593 stale request directive; see Section 3.2.1). 595 A cache SHOULD append a Warning header field with the 110 warn-code 596 (see Section 3.6) to stale responses. Likewise, a cache SHOULD add 597 the 112 warn-code to stale responses if the cache is disconnected. 599 If a cache receives a first-hand response (either an entire response, 600 or a 304 (Not Modified) response) that it would normally forward to 601 the requesting client, and the received response is no longer fresh, 602 the cache SHOULD forward it to the requesting client without adding a 603 new Warning (but without removing any existing Warning header 604 fields). A cache SHOULD NOT attempt to validate a response simply 605 because that response became stale in transit. 607 2.4. Validation Model 609 When a cache has one or more stored responses for a requested URI, 610 but cannot serve any of them (e.g., because they are not fresh, or 611 one cannot be selected; see Section 2.7), it can use the conditional 612 request mechanism [Part4] in the forwarded request to give the origin 613 server an opportunity to both select a valid stored response to be 614 used, and to update it. This process is known as "validating" or 615 "revalidating" the stored response. 617 When sending such a conditional request, a cache SHOULD add an If- 618 Modified-Since header field whose value is that of the Last-Modified 619 header field from the selected (see Section 2.7) stored response, if 620 available. 622 Additionally, a cache SHOULD add an If-None-Match header field whose 623 value is that of the ETag header field(s) from all responses stored 624 for the requested URI, if present. However, if any of the stored 625 responses contains only partial content, the cache SHOULD NOT include 626 its entity-tag in the If-None-Match header field unless the request 627 is for a range that would be fully satisfied by that stored response. 629 A 304 (Not Modified) response status code indicates that the stored 630 response can be updated and reused; see Section 2.8. 632 A full response (i.e., one with a response body) indicates that none 633 of the stored responses nominated in the conditional request is 634 suitable. Instead, a cache SHOULD use the full response to satisfy 635 the request and MAY replace the stored response. 637 If a cache receives a 5xx response while attempting to validate a 638 response, it MAY either forward this response to the requesting 639 client, or act as if the server failed to respond. In the latter 640 case, it MAY return a previously stored response (see Section 2.3.3). 642 2.5. Request Methods that Invalidate 644 Because unsafe request methods (Section 7.1.1 of [Part2]) have the 645 potential for changing state on the origin server, intervening caches 646 can use them to keep their contents up-to-date. 648 A cache MUST invalidate the effective Request URI (Section 4.3 of 649 [Part1]) as well as the URI(s) in the Location and Content-Location 650 header fields (if present) when the following request methods are 651 received: 653 o PUT 655 o DELETE 657 o POST 659 However, a cache MUST NOT invalidate a URI from a Location or 660 Content-Location header field if the host part of that URI differs 661 from the host part in the effective request URI (Section 4.3 of 662 [Part1]). This helps prevent denial of service attacks. 664 A cache that passes through requests with methods it does not 665 understand SHOULD invalidate the effective request URI (Section 4.3 666 of [Part1]). 668 Here, "invalidate" means that the cache will either remove all stored 669 responses related to the effective request URI, or will mark these as 670 "invalid" and in need of a mandatory validation before they can be 671 returned in response to a subsequent request. 673 Note that this does not guarantee that all appropriate responses are 674 invalidated. For example, the request that caused the change at the 675 origin server might not have gone through the cache where a response 676 is stored. 678 2.6. Shared Caching of Authenticated Responses 680 A shared cache MUST NOT use a cached response to a request with an 681 Authorization header field (Section 4.1 of [Part7]) to satisfy any 682 subsequent request unless a cache directive that allows such 683 responses to be stored is present in the response. 685 In this specification, the following Cache-Control response 686 directives (Section 3.2.2) have such an effect: must-revalidate, 687 public, s-maxage. 689 Note that cached responses that contain the "must-revalidate" and/or 690 "s-maxage" response directives are not allowed to be served stale 691 (Section 2.3.3) by shared caches. In particular, a response with 692 either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to 693 satisfy a subsequent request without revalidating it on the origin 694 server. 696 2.7. Caching Negotiated Responses 698 When a cache receives a request that can be satisfied by a stored 699 response that has a Vary header field (Section 3.5), it MUST NOT use 700 that response unless all of the selecting header fields nominated by 701 the Vary header field match in both the original request (i.e., that 702 associated with the stored response), and the presented request. 704 The selecting header fields from two requests are defined to match if 705 and only if those in the first request can be transformed to those in 706 the second request by applying any of the following: 708 o adding or removing whitespace, where allowed in the header field's 709 syntax 711 o combining multiple header fields with the same field name (see 712 Section 3.2 of [Part1]) 714 o normalizing both header field values in a way that is known to 715 have identical semantics, according to the header field's 716 specification (e.g., re-ordering field values when order is not 717 significant; case-normalization, where values are defined to be 718 case-insensitive) 720 If (after any normalization that might take place) a header field is 721 absent from a request, it can only match another request if it is 722 also absent there. 724 A Vary header field-value of "*" always fails to match, and 725 subsequent requests to that resource can only be properly interpreted 726 by the origin server. 728 The stored response with matching selecting header fields is known as 729 the selected response. 731 If no selected response is available, the cache MAY forward the 732 presented request to the origin server in a conditional request; see 733 Section 2.4. 735 2.8. Combining Responses 737 When a cache receives a 304 (Not Modified) response or a 206 (Partial 738 Content) response (in this section, the "new" response"), it needs to 739 create an updated response by combining the stored response with the 740 new one, so that the updated response can be used to satisfy the 741 request, and potentially update the cached response. 743 If the new response contains an ETag, it identifies the stored 744 response to use. [[TODO-mention-CL: might need language about 745 Content-Location here]][[TODO-select-for-combine: Shouldn't this be 746 the selected response?]] 748 When the new response's status code is 206 (partial content), a cache 749 MUST NOT combine it with the old response if either response does not 750 have a validator, and MUST NOT combine it with the old response when 751 those validators do not match with the strong comparison function 752 (see Section 2.2.2 of [Part4]). 754 The stored response header fields are used as those of the updated 755 response, except that 757 o a cache MUST delete any stored Warning header fields with warn- 758 code 1xx (see Section 3.6). 760 o a cache MUST retain any stored Warning header fields with warn- 761 code 2xx. 763 o a cache MUST use other header fields provided in the new response 764 to replace all instances of the corresponding header fields from 765 the stored response. 767 A cache MUST use the updated response header fields to replace those 768 of the stored response (unless the stored response is removed). In 769 the case of a 206 response, a cache MAY store the combined 770 representation. 772 3. Header Field Definitions 774 This section defines the syntax and semantics of HTTP/1.1 header 775 fields related to caching. 777 3.1. Age 779 The "Age" header field conveys the sender's estimate of the amount of 780 time since the response was generated or successfully validated at 781 the origin server. Age values are calculated as specified in 782 Section 2.3.2. 784 Age = delta-seconds 786 Age field-values are non-negative integers, representing time in 787 seconds. 789 delta-seconds = 1*DIGIT 791 If a cache receives a value larger than the largest positive integer 792 it can represent, or if any of its age calculations overflows, it 793 MUST transmit an Age header field with a field-value of 2147483648 794 (2^31). Recipients parsing the Age header field-value SHOULD use an 795 arithmetic type of at least 31 bits of range. 797 The presence of an Age header field in a response implies that a 798 response is not first-hand. However, the converse is not true, since 799 HTTP/1.0 caches might not implement the Age header field. 801 3.2. Cache-Control 803 The "Cache-Control" header field is used to specify directives for 804 caches along the request/response chain. Such cache directives are 805 unidirectional in that the presence of a directive in a request does 806 not imply that the same directive is to be given in the response. 808 A cache MUST obey the requirements of the Cache-Control directives 809 defined in this section. See Section 3.2.3 for information about how 810 Cache-Control directives defined elsewhere are handled. 812 Note: HTTP/1.0 caches might not implement Cache-Control and might 813 only implement Pragma: no-cache (see Section 3.4). 815 A proxy, whether or not it implements a cache, MUST pass cache 816 directives through in forwarded messages, regardless of their 817 significance to that application, since the directives might be 818 applicable to all recipients along the request/response chain. It is 819 not possible to target a directive to a specific cache. 821 Cache-Control = 1#cache-directive 823 cache-directive = cache-request-directive 824 / cache-response-directive 826 cache-extension = token [ "=" ( token / quoted-string ) ] 828 3.2.1. Request Cache-Control Directives 830 cache-request-directive = 831 "no-cache" 832 / "no-store" 833 / "max-age" "=" delta-seconds 834 / "max-stale" [ "=" delta-seconds ] 835 / "min-fresh" "=" delta-seconds 836 / "no-transform" 837 / "only-if-cached" 838 / cache-extension 840 no-cache 842 The no-cache request directive indicates that a cache MUST NOT use 843 a stored response to satisfy the request without successful 844 validation on the origin server. 846 no-store 848 The no-store request directive indicates that a cache MUST NOT 849 store any part of either this request or any response to it. This 850 directive applies to both private and shared caches. "MUST NOT 851 store" in this context means that the cache MUST NOT intentionally 852 store the information in non-volatile storage, and MUST make a 853 best-effort attempt to remove the information from volatile 854 storage as promptly as possible after forwarding it. 856 This directive is NOT a reliable or sufficient mechanism for 857 ensuring privacy. In particular, malicious or compromised caches 858 might not recognize or obey this directive, and communications 859 networks might be vulnerable to eavesdropping. 861 Note that if a request containing this directive is satisfied from 862 a cache, the no-store request directive does not apply to the 863 already stored response. 865 max-age 867 The max-age request directive indicates that the client is willing 868 to accept a response whose age is no greater than the specified 869 time in seconds. Unless the max-stale request directive is also 870 present, the client is not willing to accept a stale response. 872 max-stale 874 The max-stale request directive indicates that the client is 875 willing to accept a response that has exceeded its expiration 876 time. If max-stale is assigned a value, then the client is 877 willing to accept a response that has exceeded its expiration time 878 by no more than the specified number of seconds. If no value is 879 assigned to max-stale, then the client is willing to accept a 880 stale response of any age. 882 min-fresh 884 The min-fresh request directive indicates that the client is 885 willing to accept a response whose freshness lifetime is no less 886 than its current age plus the specified time in seconds. That is, 887 the client wants a response that will still be fresh for at least 888 the specified number of seconds. 890 no-transform 892 The no-transform request directive indicates that an intermediary 893 (whether or not it implements a cache) MUST NOT change the 894 Content-Encoding, Content-Range or Content-Type request header 895 fields, nor the request representation. 897 only-if-cached 899 The only-if-cached request directive indicates that the client 900 only wishes to return a stored response. If it receives this 901 directive, a cache SHOULD either respond using a stored response 902 that is consistent with the other constraints of the request, or 903 respond with a 504 (Gateway Timeout) status code. If a group of 904 caches is being operated as a unified system with good internal 905 connectivity, a member cache MAY forward such a request within 906 that group of caches. 908 3.2.2. Response Cache-Control Directives 910 cache-response-directive = 911 "public" 912 / "private" [ "=" DQUOTE 1#field-name DQUOTE ] 913 / "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] 914 / "no-store" 915 / "no-transform" 916 / "must-revalidate" 917 / "proxy-revalidate" 918 / "max-age" "=" delta-seconds 919 / "s-maxage" "=" delta-seconds 920 / cache-extension 922 public 924 The public response directive indicates that a response whose 925 associated request contains an 'Authentication' header MAY be 926 stored (see Section 2.6). 928 private 930 The private response directive indicates that the response message 931 is intended for a single user and MUST NOT be stored by a shared 932 cache. A private cache MAY store the response. 934 If the private response directive specifies one or more field- 935 names, this requirement is limited to the field-values associated 936 with the listed response header fields. That is, a shared cache 937 MUST NOT store the specified field-names(s), whereas it MAY store 938 the remainder of the response message. 940 Note: This usage of the word private only controls where the 941 response can be stored; it cannot ensure the privacy of the 942 message content. Also, private response directives with field- 943 names are often handled by implementations as if an unqualified 944 private directive was received; i.e., the special handling for the 945 qualified form is not widely implemented. 947 no-cache 949 The no-cache response directive indicates that the response MUST 950 NOT be used to satisfy a subsequent request without successful 951 validation on the origin server. This allows an origin server to 952 prevent a cache from using it to satisfy a request without 953 contacting it, even by caches that have been configured to return 954 stale responses. 956 If the no-cache response directive specifies one or more field- 957 names, this requirement is limited to the field-values associated 958 with the listed response header fields. That is, a cache MUST NOT 959 send the specified field-name(s) in the response to a subsequent 960 request without successful validation on the origin server. This 961 allows an origin server to prevent the re-use of certain header 962 fields in a response, while still allowing caching of the rest of 963 the response. 965 Note: Most HTTP/1.0 caches will not recognize or obey this 966 directive. Also, no-cache response directives with field-names 967 are often handled by implementations as if an unqualified no-cache 968 directive was received; i.e., the special handling for the 969 qualified form is not widely implemented. 971 no-store 973 The no-store response directive indicates that a cache MUST NOT 974 store any part of either the immediate request or response. This 975 directive applies to both private and shared caches. "MUST NOT 976 store" in this context means that the cache MUST NOT intentionally 977 store the information in non-volatile storage, and MUST make a 978 best-effort attempt to remove the information from volatile 979 storage as promptly as possible after forwarding it. 981 This directive is NOT a reliable or sufficient mechanism for 982 ensuring privacy. In particular, malicious or compromised caches 983 might not recognize or obey this directive, and communications 984 networks might be vulnerable to eavesdropping. 986 must-revalidate 988 The must-revalidate response directive indicates that once it has 989 become stale, a cache MUST NOT use the response to satisfy 990 subsequent requests without successful validation on the origin 991 server. 993 The must-revalidate directive is necessary to support reliable 994 operation for certain protocol features. In all circumstances a 995 cache MUST obey the must-revalidate directive; in particular, if a 996 cache cannot reach the origin server for any reason, it MUST 997 generate a 504 (Gateway Timeout) response. 999 A server SHOULD send the must-revalidate directive if and only if 1000 failure to validate a request on the representation could result 1001 in incorrect operation, such as a silently unexecuted financial 1002 transaction. 1004 proxy-revalidate 1006 The proxy-revalidate response directive has the same meaning as 1007 the must-revalidate response directive, except that it does not 1008 apply to private caches. 1010 max-age 1012 The max-age response directive indicates that the response is to 1013 be considered stale after its age is greater than the specified 1014 number of seconds. 1016 s-maxage 1018 The s-maxage response directive indicates that, in shared caches, 1019 the maximum age specified by this directive overrides the maximum 1020 age specified by either the max-age directive or the Expires 1021 header field. The s-maxage directive also implies the semantics 1022 of the proxy-revalidate response directive. 1024 no-transform 1026 The no-transform response directive indicates that an intermediary 1027 (regardless of whether it implements a cache) MUST NOT change the 1028 Content-Encoding, Content-Range or Content-Type response header 1029 fields, nor the response representation. 1031 3.2.3. Cache Control Extensions 1033 The Cache-Control header field can be extended through the use of one 1034 or more cache-extension tokens, each with an optional value. 1035 Informational extensions (those that do not require a change in cache 1036 behavior) can be added without changing the semantics of other 1037 directives. Behavioral extensions are designed to work by acting as 1038 modifiers to the existing base of cache directives. Both the new 1039 directive and the standard directive are supplied, such that 1040 applications that do not understand the new directive will default to 1041 the behavior specified by the standard directive, and those that 1042 understand the new directive will recognize it as modifying the 1043 requirements associated with the standard directive. In this way, 1044 extensions to the cache-control directives can be made without 1045 requiring changes to the base protocol. 1047 This extension mechanism depends on an HTTP cache obeying all of the 1048 cache-control directives defined for its native HTTP-version, obeying 1049 certain extensions, and ignoring all directives that it does not 1050 understand. 1052 For example, consider a hypothetical new response directive called 1053 "community" that acts as a modifier to the private directive. We 1054 define this new directive to mean that, in addition to any private 1055 cache, any cache that is shared only by members of the community 1056 named within its value may cache the response. An origin server 1057 wishing to allow the UCI community to use an otherwise private 1058 response in their shared cache(s) could do so by including 1060 Cache-Control: private, community="UCI" 1062 A cache seeing this header field will act correctly even if the cache 1063 does not understand the community cache-extension, since it will also 1064 see and understand the private directive and thus default to the safe 1065 behavior. 1067 A cache MUST be ignore unrecognized cache directives; it is assumed 1068 that any cache directive likely to be unrecognized by an HTTP/1.1 1069 cache will be combined with standard directives (or the response's 1070 default cacheability) such that the cache behavior will remain 1071 minimally correct even if the cache does not understand the 1072 extension(s). 1074 The HTTP Cache Directive Registry defines the name space for the 1075 cache directives. 1077 A registration MUST include the following fields: 1079 o Cache Directive Name 1081 o Pointer to specification text 1083 Values to be added to this name space are subject to IETF review 1084 ([RFC5226], Section 4.1). 1086 The registry itself is maintained at 1087 . 1089 3.3. Expires 1091 The "Expires" header field gives the date/time after which the 1092 response is considered stale. See Section 2.3 for further discussion 1093 of the freshness model. 1095 The presence of an Expires field does not imply that the original 1096 resource will change or cease to exist at, before, or after that 1097 time. 1099 The field-value is an absolute date and time as defined by HTTP-date 1100 in Section 6.1 of [Part1]; a sender MUST use the rfc1123-date format. 1102 Expires = HTTP-date 1104 For example 1106 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1108 Note: If a response includes a Cache-Control field with the max- 1109 age directive (see Section 3.2.2), that directive overrides the 1110 Expires field. Likewise, the s-maxage directive overrides Expires 1111 in shared caches. 1113 A server SHOULD NOT send Expires dates more than one year in the 1114 future. 1116 A cache MUST treat other invalid date formats, especially including 1117 the value "0", as in the past (i.e., "already expired"). 1119 3.4. Pragma 1121 The "Pragma" header field is used to include implementation-specific 1122 directives that might apply to any recipient along the request/ 1123 response chain. All pragma directives specify optional behavior from 1124 the viewpoint of the protocol; however, some systems MAY require that 1125 behavior be consistent with the directives. 1127 Pragma = 1#pragma-directive 1128 pragma-directive = "no-cache" / extension-pragma 1129 extension-pragma = token [ "=" ( token / quoted-string ) ] 1131 When the no-cache directive is present in a request message, a cache 1132 SHOULD forward the request toward the origin server even if it has a 1133 stored copy of what is being requested. This pragma directive has 1134 the same semantics as the no-cache response directive (see 1135 Section 3.2.2) and is defined here for backward compatibility with 1136 HTTP/1.0. A client SHOULD include both header fields when a no-cache 1137 request is sent to a server not known to be HTTP/1.1 compliant. A 1138 cache SHOULD treat "Pragma: no-cache" as if the client had sent 1139 "Cache-Control: no-cache". 1141 Note: Because the meaning of "Pragma: no-cache" as a header field 1142 is not actually specified, it does not provide a reliable 1143 replacement for "Cache-Control: no-cache" in a response. 1145 This mechanism is deprecated; no new Pragma directives will be 1146 defined in HTTP. 1148 3.5. Vary 1150 The "Vary" header field conveys the set of header fields that were 1151 used to select the representation. 1153 Caches use this information, in part, to determine whether a stored 1154 response can be used to satisfy a given request; see Section 2.7. 1155 determines, while the response is fresh, whether a cache is permitted 1156 to use the response to reply to a subsequent request without 1157 validation; see Section 2.7. 1159 In uncacheable or stale responses, the Vary field value advises the 1160 user agent about the criteria that were used to select the 1161 representation. 1163 Vary = "*" / 1#field-name 1165 The set of header fields named by the Vary field value is known as 1166 the selecting header fields. 1168 A server SHOULD include a Vary header field with any cacheable 1169 response that is subject to server-driven negotiation. Doing so 1170 allows a cache to properly interpret future requests on that resource 1171 and informs the user agent about the presence of negotiation on that 1172 resource. A server MAY include a Vary header field with a non- 1173 cacheable response that is subject to server-driven negotiation, 1174 since this might provide the user agent with useful information about 1175 the dimensions over which the response varies at the time of the 1176 response. 1178 A Vary field value of "*" signals that unspecified parameters not 1179 limited to the header fields (e.g., the network address of the 1180 client), play a role in the selection of the response representation; 1181 therefore, a cache cannot determine whether this response is 1182 appropriate. A proxy MUST NOT generate the "*" value. 1184 The field-names given are not limited to the set of standard header 1185 fields defined by this specification. Field names are case- 1186 insensitive. 1188 3.6. Warning 1190 The "Warning" header field is used to carry additional information 1191 about the status or transformation of a message that might not be 1192 reflected in the message. This information is typically used to warn 1193 about possible incorrectness introduced by caching operations or 1194 transformations applied to the payload of the message. 1196 Warnings can be used for other purposes, both cache-related and 1197 otherwise. The use of a warning, rather than an error status code, 1198 distinguishes these responses from true failures. 1200 Warning header fields can in general be applied to any message, 1201 however some warn-codes are specific to caches and can only be 1202 applied to response messages. 1204 Warning = 1#warning-value 1206 warning-value = warn-code SP warn-agent SP warn-text 1207 [SP warn-date] 1209 warn-code = 3DIGIT 1210 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1211 ; the name or pseudonym of the server adding 1212 ; the Warning header field, for use in debugging 1213 warn-text = quoted-string 1214 warn-date = DQUOTE HTTP-date DQUOTE 1216 Multiple warnings can be attached to a response (either by the origin 1217 server or by a cache), including multiple warnings with the same code 1218 number, only differing in warn-text. 1220 When this occurs, the user agent SHOULD inform the user of as many of 1221 them as possible, in the order that they appear in the response. 1223 Systems that generate multiple Warning header fields SHOULD order 1224 them with this user agent behavior in mind. New Warning header 1225 fields SHOULD be added after any existing Warning headers fields. 1227 Warnings are assigned three digit warn-codes. The first digit 1228 indicates whether the Warning is required to be deleted from a stored 1229 response after validation: 1231 o 1xx Warnings describe the freshness or validation status of the 1232 response, and so MUST be deleted by a cache after validation. 1233 They can only be generated by a cache when validating a cached 1234 entry, and MUST NOT be generated in any other situation. 1236 o 2xx Warnings describe some aspect of the representation that is 1237 not rectified by a validation (for example, a lossy compression of 1238 the representation) and MUST NOT be deleted by a cache after 1239 validation, unless a full response is returned, in which case they 1240 MUST be. 1242 If an implementation sends a message with one or more Warning header 1243 fields to a receiver whose version is HTTP/1.0 or lower, then the 1244 sender MUST include in each warning-value a warn-date that matches 1245 the Date header field in the message. 1247 If a system receives a message with a warning-value that includes a 1248 warn-date, and that warn-date is different from the Date value in the 1249 response, then that warning-value MUST be deleted from the message 1250 before storing, forwarding, or using it. (preventing the consequences 1251 of naive caching of Warning header fields.) If all of the warning- 1252 values are deleted for this reason, the Warning header field MUST be 1253 deleted as well. 1255 The following warn-codes are defined by this specification, each with 1256 a recommended warn-text in English, and a description of its meaning. 1258 110 Response is stale 1260 A cache SHOULD include this whenever the returned response is 1261 stale. 1263 111 Revalidation failed 1265 A cache SHOULD include this when returning a stale response 1266 because an attempt to validate the response failed, due to an 1267 inability to reach the server. 1269 112 Disconnected operation 1271 A cache SHOULD b include this if it is intentionally disconnected 1272 from the rest of the network for a period of time. 1274 113 Heuristic expiration 1276 A cache SHOULD include this if it heuristically chose a freshness 1277 lifetime greater than 24 hours and the response's age is greater 1278 than 24 hours. 1280 199 Miscellaneous warning 1282 The warning text can include arbitrary information to be presented 1283 to a human user, or logged. A system receiving this warning MUST 1284 NOT take any automated action, besides presenting the warning to 1285 the user. 1287 214 Transformation applied 1289 MUST be added by a proxy if it applies any transformation to the 1290 representation, such as changing the content-coding, media-type, 1291 or modifying the representation data, unless this Warning code 1292 already appears in the response. 1294 299 Miscellaneous persistent warning 1296 The warning text can include arbitrary information to be presented 1297 to a human user, or logged. A system receiving this warning MUST 1298 NOT take any automated action. 1300 4. History Lists 1302 User agents often have history mechanisms, such as "Back" buttons and 1303 history lists, that can be used to redisplay a representation 1304 retrieved earlier in a session. 1306 The freshness model (Section 2.3) does not necessarily apply to 1307 history mechanisms. I.e., a history mechanism can display a previous 1308 representation even if it has expired. 1310 This does not prohibit the history mechanism from telling the user 1311 that a view might be stale, or from honoring cache directives (e.g., 1312 Cache-Control: no-store). 1314 5. IANA Considerations 1316 5.1. Cache Directive Registry 1318 The registration procedure for HTTP Cache Directives is defined by 1319 Section 3.2.3 of this document. 1321 The HTTP Cache Directive Registry shall be created at 1322 and be 1323 populated with the registrations below: 1325 +------------------------+------------------------------+ 1326 | Cache Directive | Reference | 1327 +------------------------+------------------------------+ 1328 | max-age | Section 3.2.1, Section 3.2.2 | 1329 | max-stale | Section 3.2.1 | 1330 | min-fresh | Section 3.2.1 | 1331 | must-revalidate | Section 3.2.2 | 1332 | no-cache | Section 3.2.1, Section 3.2.2 | 1333 | no-store | Section 3.2.1, Section 3.2.2 | 1334 | no-transform | Section 3.2.1, Section 3.2.2 | 1335 | only-if-cached | Section 3.2.1 | 1336 | private | Section 3.2.2 | 1337 | proxy-revalidate | Section 3.2.2 | 1338 | public | Section 3.2.2 | 1339 | s-maxage | Section 3.2.2 | 1340 | stale-if-error | [RFC5861], Section 4 | 1341 | stale-while-revalidate | [RFC5861], Section 3 | 1342 +------------------------+------------------------------+ 1344 5.2. Header Field Registration 1346 The Message Header Field Registry located at shall be 1348 updated with the permanent registrations below (see [RFC3864]): 1350 +-------------------+----------+----------+-------------+ 1351 | Header Field Name | Protocol | Status | Reference | 1352 +-------------------+----------+----------+-------------+ 1353 | Age | http | standard | Section 3.1 | 1354 | Cache-Control | http | standard | Section 3.2 | 1355 | Expires | http | standard | Section 3.3 | 1356 | Pragma | http | standard | Section 3.4 | 1357 | Vary | http | standard | Section 3.5 | 1358 | Warning | http | standard | Section 3.6 | 1359 +-------------------+----------+----------+-------------+ 1361 The change controller is: "IETF (iesg@ietf.org) - Internet 1362 Engineering Task Force". 1364 6. Security Considerations 1366 Caches expose additional potential vulnerabilities, since the 1367 contents of the cache represent an attractive target for malicious 1368 exploitation. Because cache contents persist after an HTTP request 1369 is complete, an attack on the cache can reveal information long after 1370 a user believes that the information has been removed from the 1371 network. Therefore, cache contents need to be protected as sensitive 1372 information. 1374 7. Acknowledgments 1376 Much of the content and presentation of the caching design is due to 1377 suggestions and comments from individuals including: Shel Kaphan, 1378 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 1380 8. References 1382 8.1. Normative References 1384 [Part1] 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 1: URIs, Connections, 1387 and Message Parsing", draft-ietf-httpbis-p1-messaging-14 1388 (work in progress), April 2011. 1390 [Part2] 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 2: Message 1393 Semantics", draft-ietf-httpbis-p2-semantics-14 (work in 1394 progress), April 2011. 1396 [Part4] 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 4: Conditional 1399 Requests", draft-ietf-httpbis-p4-conditional-14 (work in 1400 progress), April 2011. 1402 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1403 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1404 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 1405 Partial Responses", draft-ietf-httpbis-p5-range-14 (work 1406 in progress), April 2011. 1408 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1409 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1410 and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", 1411 draft-ietf-httpbis-p7-auth-14 (work in progress), 1412 April 2011. 1414 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1415 Requirement Levels", BCP 14, RFC 2119, March 1997. 1417 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1418 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1420 8.2. Informative References 1422 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1423 Specification, Implementation", RFC 1305, March 1992. 1425 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1426 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1427 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1429 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1430 Procedures for Message Header Fields", BCP 90, RFC 3864, 1431 September 2004. 1433 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1434 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1435 May 2008. 1437 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1438 Content", RFC 5861, April 2010. 1440 Appendix A. Changes from RFC 2616 1442 Make the specified age calculation algorithm less conservative. 1443 (Section 2.3.2) 1445 Remove requirement to consider Content-Location in successful 1446 responses in order to determine the appropriate response to use. 1447 (Section 2.4) 1449 Clarify denial of service attack avoidance requirement. 1450 (Section 2.5) 1452 Change ABNF productions for header fields to only define the field 1453 value. (Section 3) 1455 Do not mention RFC 2047 encoding and multiple languages in Warning 1456 header fields anymore, as these aspects never were implemented. 1457 (Section 3.6) 1459 Appendix B. Collected ABNF 1461 Age = delta-seconds 1463 Cache-Control = *( "," OWS ) cache-directive *( OWS "," [ OWS 1464 cache-directive ] ) 1466 Expires = HTTP-date 1467 HTTP-date = 1469 OWS = 1471 Pragma = *( "," OWS ) pragma-directive *( OWS "," [ OWS 1472 pragma-directive ] ) 1474 Vary = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name ] 1475 ) ) 1477 Warning = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value ] 1478 ) 1480 cache-directive = cache-request-directive / cache-response-directive 1481 cache-extension = token [ "=" ( token / quoted-string ) ] 1482 cache-request-directive = "no-cache" / "no-store" / ( "max-age=" 1483 delta-seconds ) / ( "max-stale" [ "=" delta-seconds ] ) / ( 1484 "min-fresh=" delta-seconds ) / "no-transform" / "only-if-cached" / 1485 cache-extension 1486 cache-response-directive = "public" / ( "private" [ "=" DQUOTE *( "," 1487 OWS ) field-name *( OWS "," [ OWS field-name ] ) DQUOTE ] ) / ( 1488 "no-cache" [ "=" DQUOTE *( "," OWS ) field-name *( OWS "," [ OWS 1489 field-name ] ) DQUOTE ] ) / "no-store" / "no-transform" / 1490 "must-revalidate" / "proxy-revalidate" / ( "max-age=" delta-seconds 1491 ) / ( "s-maxage=" delta-seconds ) / cache-extension 1493 delta-seconds = 1*DIGIT 1495 extension-pragma = token [ "=" ( token / quoted-string ) ] 1497 field-name = 1499 port = 1500 pragma-directive = "no-cache" / extension-pragma 1501 pseudonym = 1503 quoted-string = 1505 token = 1507 uri-host = 1509 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1510 warn-code = 3DIGIT 1511 warn-date = DQUOTE HTTP-date DQUOTE 1512 warn-text = quoted-string 1513 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date 1514 ] 1516 ABNF diagnostics: 1518 ; Age defined but not used 1519 ; Cache-Control defined but not used 1520 ; Expires defined but not used 1521 ; Pragma defined but not used 1522 ; Vary defined but not used 1523 ; Warning defined but not used 1525 Appendix C. Change Log (to be removed by RFC Editor before publication) 1527 C.1. Since RFC 2616 1529 Extracted relevant partitions from [RFC2616]. 1531 C.2. Since draft-ietf-httpbis-p6-cache-00 1533 Closed issues: 1535 o : "Trailer" 1536 () 1538 o : "Invalidation 1539 after Update or Delete" 1540 () 1542 o : "Normative and 1543 Informative references" 1545 o : "Date reference 1546 typo" 1548 o : "Connection 1549 header text" 1551 o : "Informative 1552 references" 1554 o : "ISO-8859-1 1555 Reference" 1557 o : "Normative up- 1558 to-date references" 1560 o : "typo in 1561 13.2.2" 1563 Other changes: 1565 o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress 1566 on ) 1568 C.3. Since draft-ietf-httpbis-p6-cache-01 1570 Closed issues: 1572 o : "rel_path not 1573 used" 1575 Other changes: 1577 o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work 1578 in progress on ) 1580 o Add explicit references to BNF syntax and rules imported from 1581 other parts of the specification. 1583 C.4. Since draft-ietf-httpbis-p6-cache-02 1585 Ongoing work on IANA Message Header Field Registration 1586 (): 1588 o Reference RFC 3984, and update header field registrations for 1589 header fields defined in this document. 1591 C.5. Since draft-ietf-httpbis-p6-cache-03 1593 Closed issues: 1595 o : "Vary header 1596 classification" 1598 C.6. Since draft-ietf-httpbis-p6-cache-04 1600 Ongoing work on ABNF conversion 1601 (): 1603 o Use "/" instead of "|" for alternatives. 1605 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1606 whitespace ("OWS") and required whitespace ("RWS"). 1608 o Rewrite ABNFs to spell out whitespace rules, factor out header 1609 field value format definitions. 1611 C.7. Since draft-ietf-httpbis-p6-cache-05 1613 This is a total rewrite of this part of the specification. 1615 Affected issues: 1617 o : "Definition of 1618 1xx Warn-Codes" 1620 o : "Placement of 1621 13.5.1 and 13.5.2" 1623 o : "The role of 1624 Warning and Semantic Transparency in Caching" 1626 o : "Methods and 1627 Caching" 1629 In addition: Final work on ABNF conversion 1630 (): 1632 o Add appendix containing collected and expanded ABNF, reorganize 1633 ABNF introduction. 1635 C.8. Since draft-ietf-httpbis-p6-cache-06 1637 Closed issues: 1639 o : "base for 1640 numeric protocol elements" 1642 Affected issues: 1644 o : "Vary and non- 1645 existant headers" 1647 C.9. Since draft-ietf-httpbis-p6-cache-07 1649 Closed issues: 1651 o : "Definition of 1652 1xx Warn-Codes" 1654 o : "Content- 1655 Location on 304 responses" 1657 o : "private and 1658 no-cache CC directives with headers" 1660 o : "RFC2047 and 1661 warn-text" 1663 C.10. Since draft-ietf-httpbis-p6-cache-08 1665 Closed issues: 1667 o : "serving 1668 negotiated responses from cache: header-specific canonicalization" 1670 o : "Effect of CC 1671 directives on history lists" 1673 Affected issues: 1675 o : Status codes 1676 and caching 1678 Partly resolved issues: 1680 o : "Placement of 1681 13.5.1 and 13.5.2" 1683 C.11. Since draft-ietf-httpbis-p6-cache-09 1685 Closed issues: 1687 o : "Age 1688 calculation" 1690 o : "Clarify 1691 differences between / requirements for request and response CC 1692 directives" 1694 o : "Caching 1695 authenticated responses" 1697 o : "IANA registry 1698 for cache-control directives" 1700 o : "Heuristic 1701 caching of URLs with query components" 1703 Partly resolved issues: 1705 o : "Term for the 1706 requested resource's URI" 1708 C.12. Since draft-ietf-httpbis-p6-cache-10 1710 Closed issues: 1712 o : "Clarify 1713 entity / representation / variant terminology" 1715 o : "consider 1716 removing the 'changes from 2068' sections" 1718 o : "Allowing 1719 heuristic caching for new status codes" 1721 o : "Allowing 1722 heuristic caching for new status codes" 1724 o Clean up TODOs and prose in "Combining Responses." 1726 C.13. Since draft-ietf-httpbis-p6-cache-11 1728 Closed issues: 1730 o : "Text about 1731 clock requirement for caches belongs in p6" 1733 C.14. Since draft-ietf-httpbis-p6-cache-12 1735 Closed issues: 1737 o : "Header 1738 Classification" 1740 o : "Clarify 1741 'public'" 1743 C.15. Since draft-ietf-httpbis-p6-cache-13 1745 Closed issues: 1747 o : "untangle 1748 ABNFs for header fields" 1750 Index 1752 A 1753 age 6 1754 Age header field 18 1756 C 1757 cache 5 1758 Cache Directives 1759 max-age 19, 23 1760 max-stale 20 1761 min-fresh 20 1762 must-revalidate 22 1763 no-cache 19, 21 1764 no-store 19, 22 1765 no-transform 20, 23 1766 only-if-cached 20 1767 private 21 1768 proxy-revalidate 23 1769 public 21 1770 s-maxage 23 1771 Cache-Control header field 18 1772 cacheable 5 1774 E 1775 Expires header field 24 1776 explicit expiration time 6 1778 F 1779 first-hand 6 1780 fresh 6 1781 freshness lifetime 6 1783 G 1784 Grammar 1785 Age 18 1786 Cache-Control 19 1787 cache-extension 19 1788 cache-request-directive 19 1789 cache-response-directive 21 1790 delta-seconds 18 1791 Expires 25 1792 extension-pragma 25 1793 Pragma 25 1794 pragma-directive 25 1795 Vary 26 1796 warn-agent 27 1797 warn-code 27 1798 warn-date 27 1799 warn-text 27 1800 Warning 27 1801 warning-value 27 1803 H 1804 Header Fields 1805 Age 18 1806 Cache-Control 18 1807 Expires 24 1808 Pragma 25 1809 Vary 26 1810 Warning 26 1811 heuristic expiration time 6 1813 M 1814 max-age 1815 Cache Directive 19, 23 1816 max-stale 1817 Cache Directive 20 1818 min-fresh 1819 Cache Directive 20 1820 must-revalidate 1821 Cache Directive 22 1823 N 1824 no-cache 1825 Cache Directive 19, 21 1826 no-store 1827 Cache Directive 19, 22 1828 no-transform 1829 Cache Directive 20, 23 1831 O 1832 only-if-cached 1833 Cache Directive 20 1835 P 1836 Pragma header field 25 1837 private 1838 Cache Directive 21 1839 private cache 5 1840 proxy-revalidate 1841 Cache Directive 23 1842 public 1843 Cache Directive 21 1845 S 1846 s-maxage 1847 Cache Directive 23 1848 shared cache 5 1849 stale 6 1851 V 1852 validator 6 1853 Vary header field 26 1855 W 1856 Warning header field 26 1858 Authors' Addresses 1860 Roy T. Fielding (editor) 1861 Adobe Systems Incorporated 1862 345 Park Ave 1863 San Jose, CA 95110 1864 USA 1866 EMail: fielding@gbiv.com 1867 URI: http://roy.gbiv.com/ 1869 Jim Gettys 1870 Alcatel-Lucent Bell Labs 1871 21 Oak Knoll Road 1872 Carlisle, MA 01741 1873 USA 1875 EMail: jg@freedesktop.org 1876 URI: http://gettys.wordpress.com/ 1878 Jeffrey C. Mogul 1879 Hewlett-Packard Company 1880 HP Labs, Large Scale Systems Group 1881 1501 Page Mill Road, MS 1177 1882 Palo Alto, CA 94304 1883 USA 1885 EMail: JeffMogul@acm.org 1887 Henrik Frystyk Nielsen 1888 Microsoft Corporation 1889 1 Microsoft Way 1890 Redmond, WA 98052 1891 USA 1893 EMail: henrikn@microsoft.com 1894 Larry Masinter 1895 Adobe Systems Incorporated 1896 345 Park Ave 1897 San Jose, CA 95110 1898 USA 1900 EMail: LMM@acm.org 1901 URI: http://larry.masinter.net/ 1903 Paul J. Leach 1904 Microsoft Corporation 1905 1 Microsoft Way 1906 Redmond, WA 98052 1908 EMail: paulle@microsoft.com 1910 Tim Berners-Lee 1911 World Wide Web Consortium 1912 MIT Computer Science and Artificial Intelligence Laboratory 1913 The Stata Center, Building 32 1914 32 Vassar Street 1915 Cambridge, MA 02139 1916 USA 1918 EMail: timbl@w3.org 1919 URI: http://www.w3.org/People/Berners-Lee/ 1921 Yves Lafon (editor) 1922 World Wide Web Consortium 1923 W3C / ERCIM 1924 2004, rte des Lucioles 1925 Sophia-Antipolis, AM 06902 1926 France 1928 EMail: ylafon@w3.org 1929 URI: http://www.raubacapeu.net/people/yves/ 1931 Mark Nottingham (editor) 1933 EMail: mnot@mnot.net 1934 URI: http://www.mnot.net/ 1935 Julian F. Reschke (editor) 1936 greenbytes GmbH 1937 Hafenweg 16 1938 Muenster, NW 48155 1939 Germany 1941 Phone: +49 251 2807760 1942 Fax: +49 251 2807761 1943 EMail: julian.reschke@greenbytes.de 1944 URI: http://greenbytes.de/tech/webdav/