idnits 2.17.1 draft-ietf-httpbis-p6-cache-11.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 (August 4, 2010) is 5012 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-11 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-11 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-11 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-11 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-11 -- 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: February 5, 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 August 4, 2010 24 HTTP/1.1, part 6: Caching 25 draft-ietf-httpbis-p6-cache-11 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.12. 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 February 5, 2011. 63 Copyright Notice 65 Copyright (c) 2010 IETF Trust and the persons identified as the 66 document authors. All rights reserved. 68 This document is subject to BCP 78 and the IETF Trust's Legal 69 Provisions Relating to IETF Documents 70 (http://trustee.ietf.org/license-info) in effect on the date of 71 publication of this document. Please review these documents 72 carefully, as they describe your rights and restrictions with respect 73 to this document. Code Components extracted from this document must 74 include Simplified BSD License text as described in Section 4.e of 75 the Trust Legal Provisions and are provided without warranty as 76 described in the Simplified BSD License. 78 This document may contain material from IETF Documents or IETF 79 Contributions published or made publicly available before November 80 10, 2008. The person(s) controlling the copyright in some of this 81 material may not have granted the IETF Trust the right to allow 82 modifications of such material outside the IETF Standards Process. 83 Without obtaining an adequate license from the person(s) controlling 84 the copyright in such materials, this document may not be modified 85 outside the IETF Standards Process, and derivative works of it may 86 not be created outside the IETF Standards Process, except to format 87 it for publication as an RFC or to translate it into languages other 88 than English. 90 Table of Contents 92 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 93 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 94 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 95 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 6 96 1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 97 1.4.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 7 98 1.4.2. ABNF Rules defined in other Parts of the 99 Specification . . . . . . . . . . . . . . . . . . . . 7 100 2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 7 101 2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 7 102 2.1.1. Storing Partial and Incomplete Responses . . . . . . . 8 103 2.2. Constructing Responses from Caches . . . . . . . . . . . . 9 104 2.3. Freshness Model . . . . . . . . . . . . . . . . . . . . . 10 105 2.3.1. Calculating Freshness Lifetime . . . . . . . . . . . . 11 106 2.3.2. Calculating Age . . . . . . . . . . . . . . . . . . . 12 107 2.3.3. Serving Stale Responses . . . . . . . . . . . . . . . 13 108 2.4. Validation Model . . . . . . . . . . . . . . . . . . . . . 14 109 2.5. Request Methods that Invalidate . . . . . . . . . . . . . 14 110 2.6. Shared Caching of Authenticated Responses . . . . . . . . 15 111 2.7. Caching Negotiated Responses . . . . . . . . . . . . . . . 16 112 2.8. Combining Responses . . . . . . . . . . . . . . . . . . . 16 113 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 17 114 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 115 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 18 116 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 18 117 3.2.2. Response Cache-Control Directives . . . . . . . . . . 20 118 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 22 119 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 24 120 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 24 121 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 122 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 26 123 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 28 124 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 125 5.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 28 126 5.2. Header Field Registration . . . . . . . . . . . . . . . . 29 127 6. Security Considerations . . . . . . . . . . . . . . . . . . . 29 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 . . . . . . . . . . . . . . . . 31 133 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 31 134 Appendix C. Change Log (to be removed by RFC Editor before 135 publication) . . . . . . . . . . . . . . . . . . . . 33 136 C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 33 137 C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 33 138 C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 34 139 C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 34 140 C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 34 141 C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 34 142 C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 35 143 C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 35 144 C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 35 145 C.10. Since draft-ietf-httpbis-p6-cache-08 . . . . . . . . . . . 36 146 C.11. Since draft-ietf-httpbis-p6-cache-09 . . . . . . . . . . . 36 147 C.12. Since draft-ietf-httpbis-p6-cache-10 . . . . . . . . . . . 37 148 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 150 1. Introduction 152 HTTP is typically used for distributed information systems, where 153 performance can be improved by the use of response caches. This 154 document defines aspects of HTTP/1.1 related to caching and reusing 155 response messages. 157 1.1. Purpose 159 An HTTP cache is a local store of response messages and the subsystem 160 that controls its message storage, retrieval, and deletion. A cache 161 stores cacheable responses in order to reduce the response time and 162 network bandwidth consumption on future, equivalent requests. Any 163 client or server MAY employ a cache, though a cache cannot be used by 164 a server that is acting as a tunnel. 166 Caching would be useless if it did not significantly improve 167 performance. The goal of caching in HTTP/1.1 is to reuse a prior 168 response message to satisfy a current request. In some cases, a 169 stored response can be reused without the need for a network request, 170 reducing latency and network round-trips; a "freshness" mechanism is 171 used for this purpose (see Section 2.3). Even when a new request is 172 required, it is often possible to reuse all or parts of the payload 173 of a prior response to satisfy the request, thereby reducing network 174 bandwidth usage; a "validation" mechanism is used for this purpose 175 (see Section 2.4). 177 1.2. Terminology 179 This specification uses a number of terms to refer to the roles 180 played by participants in, and objects of, HTTP caching. 182 cacheable 184 A response is cacheable if a cache is allowed to store a copy of 185 the response message for use in answering subsequent requests. 186 Even when a response is cacheable, there might be additional 187 constraints on whether a cache can use the cached copy to satisfy 188 a particular request. 190 explicit expiration time 192 The time at which the origin server intends that a representation 193 no longer be returned by a cache without further validation. 195 heuristic expiration time 197 An expiration time assigned by a cache when no explicit expiration 198 time is available. 200 age 202 The age of a response is the time since it was sent by, or 203 successfully validated with, the origin server. 205 first-hand 207 A response is first-hand if the freshness model is not in use; 208 i.e., its age is 0. 210 freshness lifetime 212 The length of time between the generation of a response and its 213 expiration time. 215 fresh 217 A response is fresh if its age has not yet exceeded its freshness 218 lifetime. 220 stale 222 A response is stale if its age has passed its freshness lifetime 223 (either explicit or heuristic). 225 validator 227 A protocol element (e.g., an entity-tag or a Last-Modified time) 228 that is used to find out whether a stored response has an 229 equivalent copy of a representation. 231 shared cache 233 A cache that is accessible to more than one user. A non-shared 234 cache is dedicated to a single user. 236 1.3. Requirements 238 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 239 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 240 document are to be interpreted as described in [RFC2119]. 242 An implementation is not compliant if it fails to satisfy one or more 243 of the "MUST" or "REQUIRED" level requirements for the protocols it 244 implements. An implementation that satisfies all the "MUST" or 245 "REQUIRED" level and all the "SHOULD" level requirements for its 246 protocols is said to be "unconditionally compliant"; one that 247 satisfies all the "MUST" level requirements but not all the "SHOULD" 248 level requirements for its protocols is said to be "conditionally 249 compliant". 251 1.4. Syntax Notation 253 This specification uses the ABNF syntax defined in Section 1.2 of 254 [Part1] (which extends the syntax defined in [RFC5234] with a list 255 rule). Appendix B shows the collected ABNF, with the list rule 256 expanded. 258 The following core rules are included by reference, as defined in 259 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 260 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 261 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 262 sequence of data), SP (space), VCHAR (any visible USASCII character), 263 and WSP (whitespace). 265 1.4.1. Core Rules 267 The core rules below are defined in Section 1.2.2 of [Part1]: 269 quoted-string = 270 token = 271 OWS = 273 1.4.2. ABNF Rules defined in other Parts of the Specification 275 The ABNF rules below are defined in other parts: 277 field-name = 278 HTTP-date = 279 port = 280 pseudonym = 281 uri-host = 283 2. Cache Operation 285 2.1. Response Cacheability 287 A cache MUST NOT store a response to any request, unless: 289 o The request method is understood by the cache and defined as being 290 cacheable, and 292 o the response status code is understood by the cache, and 294 o the "no-store" cache directive (see Section 3.2) does not appear 295 in request or response headers, and 297 o the "private" cache response directive (see Section 3.2.2 does not 298 appear in the response, if the cache is shared, and 300 o the "Authorization" header (see Section 3.1 of [Part7]) does not 301 appear in the request, if the cache is shared, unless the response 302 explicitly allows it (see Section 2.6), and 304 o the response either: 306 * contains an Expires header (see Section 3.3), or 308 * contains a max-age response cache directive (see 309 Section 3.2.2), or 311 * contains a s-maxage response cache directive and the cache is 312 shared, or 314 * contains a Cache Control Extension (see Section 3.2.3) that 315 allows it to be cached, or 317 * has a status code that can be served with heuristic freshness 318 (see Section 2.3.1.1). 320 In this context, a cache has "understood" a request method or a 321 response status code if it recognises it and implements any cache- 322 specific behaviour. In particular, 206 Partial Content responses 323 cannot be cached by an implementation that does not handle partial 324 content (see Section 2.1.1). 326 Note that in normal operation, most caches will not store a response 327 that has neither a cache validator nor an explicit expiration time, 328 as such responses are not usually useful to store. However, caches 329 are not prohibited from storing such responses. 331 2.1.1. Storing Partial and Incomplete Responses 333 A cache that receives an incomplete response (for example, with fewer 334 bytes of data than specified in a Content-Length header) can store 335 the response, but MUST treat it as a partial response [Part5]. 336 Partial responses can be combined as described in Section 4 of 337 [Part5]; the result might be a full response or might still be 338 partial. A cache MUST NOT return a partial response to a client 339 without explicitly marking it as such using the 206 (Partial Content) 340 status code. 342 A cache that does not support the Range and Content-Range headers 343 MUST NOT store incomplete or partial responses. 345 2.2. Constructing Responses from Caches 347 For a presented request, a cache MUST NOT return a stored response, 348 unless: 350 o The presented effective request URI (Section 4.3 of [Part1]) and 351 that of the stored response match, and 353 o the request method associated with the stored response allows it 354 to be used for the presented request, and 356 o selecting request-headers nominated by the stored response (if 357 any) match those presented (see Section 2.7), and 359 o the presented request and stored response are free from directives 360 that would prevent its use (see Section 3.2 and Section 3.4), and 362 o the stored response is either: 364 * fresh (see Section 2.3), or 366 * allowed to be served stale (see Section 2.3.3), or 368 * successfully validated (see Section 2.4). 370 When a stored response is used to satisfy a request without 371 validation, caches MUST include a single Age header field 372 (Section 3.1) in the response with a value equal to the stored 373 response's current_age; see Section 2.3.2. 375 Requests with methods that are unsafe (Section 7.1.1 of [Part2]) MUST 376 be written through the cache to the origin server; i.e., a cache must 377 not reply to such a request before having forwarded the request and 378 having received a corresponding response. 380 Also, note that unsafe requests might invalidate already stored 381 responses; see Section 2.5. 383 Caches MUST use the most recent response (as determined by the Date 384 header) when more than one suitable response is stored. They can 385 also forward a request with "Cache-Control: max-age=0" or "Cache- 386 Control: no-cache" to disambiguate which response to use. 388 2.3. Freshness Model 390 When a response is "fresh" in the cache, it can be used to satisfy 391 subsequent requests without contacting the origin server, thereby 392 improving efficiency. 394 The primary mechanism for determining freshness is for an origin 395 server to provide an explicit expiration time in the future, using 396 either the Expires header (Section 3.3) or the max-age response cache 397 directive (Section 3.2.2). Generally, origin servers will assign 398 future explicit expiration times to responses in the belief that the 399 representation is not likely to change in a semantically significant 400 way before the expiration time is reached. 402 If an origin server wishes to force a cache to validate every 403 request, it can assign an explicit expiration time in the past to 404 indicate that the response is already stale. Compliant caches will 405 validate the cached response before reusing it for subsequent 406 requests. 408 Since origin servers do not always provide explicit expiration times, 409 HTTP caches MAY assign heuristic expiration times when explicit times 410 are not specified, employing algorithms that use other header values 411 (such as the Last-Modified time) to estimate a plausible expiration 412 time. The HTTP/1.1 specification does not provide specific 413 algorithms, but does impose worst-case constraints on their results. 415 The calculation to determine if a response is fresh is: 417 response_is_fresh = (freshness_lifetime > current_age) 419 The freshness_lifetime is defined in Section 2.3.1; the current_age 420 is defined in Section 2.3.2. 422 Additionally, clients might need to influence freshness calculation. 423 They can do this using several request cache directives, with the 424 effect of either increasing or loosening constraints on freshness. 425 See Section 3.2.1. 427 [[ISSUE-no-req-for-directives: there are not requirements directly 428 applying to cache-request-directives and freshness.]] 430 Note that freshness applies only to cache operation; it cannot be 431 used to force a user agent to refresh its display or reload a 432 resource. See Section 4 for an explanation of the difference between 433 caches and history mechanisms. 435 2.3.1. Calculating Freshness Lifetime 437 A cache can calculate the freshness lifetime (denoted as 438 freshness_lifetime) of a response by using the first match of: 440 o If the cache is shared and the s-maxage response cache directive 441 (Section 3.2.2) is present, use its value, or 443 o If the max-age response cache directive (Section 3.2.2) is 444 present, use its value, or 446 o If the Expires response header (Section 3.3) is present, use its 447 value minus the value of the Date response header, or 449 o Otherwise, no explicit expiration time is present in the response. 450 A heuristic freshness lifetime might be applicable; see 451 Section 2.3.1.1. 453 Note that this calculation is not vulnerable to clock skew, since all 454 of the information comes from the origin server. 456 2.3.1.1. Calculating Heuristic Freshness 458 If no explicit expiration time is present in a stored response that 459 has a status code whose definition allows heuristic freshness to be 460 used (including the following in Section 8 of [Part2]: 200, 203, 206, 461 300, 301 and 410), a heuristic expiration time MAY be calculated. 462 Heuristics MUST NOT be used for response status codes that do not 463 explicitly allow it. 465 When a heuristic is used to calculate freshness lifetime, the cache 466 SHOULD attach a Warning header with a 113 warn-code to the response 467 if its current_age is more than 24 hours and such a warning is not 468 already present. 470 Also, if the response has a Last-Modified header (Section 6.6 of 471 [Part4]), the heuristic expiration value SHOULD be no more than some 472 fraction of the interval since that time. A typical setting of this 473 fraction might be 10%. 475 Note: RFC 2616 ([RFC2616], Section 13.9) required that caches do 476 not calculate heuristic freshness for URLs with query components 477 (i.e., those containing '?'). In practice, this has not been 478 widely implemented. Therefore, servers are encouraged to send 479 explicit directives (e.g., Cache-Control: no-cache) if they wish 480 to preclude caching. 482 2.3.2. Calculating Age 484 HTTP/1.1 uses the Age response-header to convey the estimated age of 485 the response message when obtained from a cache. The Age field value 486 is the cache's estimate of the amount of time since the response was 487 generated or validated by the origin server. In essence, the Age 488 value is the sum of the time that the response has been resident in 489 each of the caches along the path from the origin server, plus the 490 amount of time it has been in transit along network paths. 492 The following data is used for the age calculation: 494 age_value 496 The term "age_value" denotes the value of the Age header 497 (Section 3.1), in a form appropriate for arithmetic operation; or 498 0, if not available. 500 date_value 502 HTTP/1.1 requires origin servers to send a Date header, if 503 possible, with every response, giving the time at which the 504 response was generated. The term "date_value" denotes the value 505 of the Date header, in a form appropriate for arithmetic 506 operations. See Section 9.3 of [Part1] for the definition of the 507 Date header, and for requirements regarding responses without a 508 Date response header. 510 now 512 The term "now" means "the current value of the clock at the host 513 performing the calculation". Hosts that use HTTP, but especially 514 hosts running origin servers and caches, SHOULD use NTP 515 ([RFC1305]) or some similar protocol to synchronize their clocks 516 to a globally accurate time standard. 518 request_time 520 The current value of the clock at the host at the time the request 521 resulting in the stored response was made. 523 response_time 525 The current value of the clock at the host at the time the 526 response was received. 528 A response's age can be calculated in two entirely independent ways: 530 1. the "apparent_age": response_time minus date_value, if the local 531 clock is reasonably well synchronized to the origin server's 532 clock. If the result is negative, the result is replaced by 533 zero. 535 2. the "corrected_age_value", if all of the caches along the 536 response path implement HTTP/1.1; note this value MUST be 537 interpreted relative to the time the request was initiated, not 538 the time that the response was received. 540 apparent_age = max(0, response_time - date_value); 542 response_delay = response_time - request_time; 543 corrected_age_value = age_value + response_delay; 545 These are combined as 547 corrected_initial_age = max(apparent_age, corrected_age_value); 549 The current_age of a stored response can then be calculated by adding 550 the amount of time (in seconds) since the stored response was last 551 validated by the origin server to the corrected_initial_age. 553 resident_time = now - response_time; 554 current_age = corrected_initial_age + resident_time; 556 2.3.3. Serving Stale Responses 558 A "stale" response is one that either has explicit expiry information 559 or is allowed to have heuristic expiry calculated, but is not fresh 560 according to the calculations in Section 2.3. 562 Caches MUST NOT return a stale response if it is prohibited by an 563 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" 564 cache directive, a "must-revalidate" cache-response-directive, or an 565 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 566 see Section 3.2.2). 568 Caches SHOULD NOT return stale responses unless they are disconnected 569 (i.e., it cannot contact the origin server or otherwise find a 570 forward path) or otherwise explicitly allowed (e.g., the max-stale 571 request directive; see Section 3.2.1). 573 Stale responses SHOULD have a Warning header with the 110 warn-code 574 (see Section 3.6). Likewise, the 112 warn-code SHOULD be sent on 575 stale responses if the cache is disconnected. 577 If a cache receives a first-hand response (either an entire response, 578 or a 304 (Not Modified) response) that it would normally forward to 579 the requesting client, and the received response is no longer fresh, 580 the cache SHOULD forward it to the requesting client without adding a 581 new Warning (but without removing any existing Warning headers). A 582 cache SHOULD NOT attempt to validate a response simply because that 583 response became stale in transit. 585 2.4. Validation Model 587 When a cache has one or more stored responses for a requested URI, 588 but cannot serve any of them (e.g., because they are not fresh, or 589 one cannot be selected; see Section 2.7), it can use the conditional 590 request mechanism [Part4] in the forwarded request to give the origin 591 server an opportunity to both select a valid stored response to be 592 used, and to update it. This process is known as "validating" or 593 "revalidating" the stored response. 595 When sending such a conditional request, the cache SHOULD add an If- 596 Modified-Since header whose value is that of the Last-Modified header 597 from the selected (see Section 2.7) stored response, if available. 599 Additionally, the cache SHOULD add an If-None-Match header whose 600 value is that of the ETag header(s) from all responses stored for the 601 requested URI, if present. However, if any of the stored responses 602 contains only partial content, its entity-tag SHOULD NOT be included 603 in the If-None-Match header field unless the request is for a range 604 that would be fully satisfied by that stored response. 606 A 304 (Not Modified) response status code indicates that the stored 607 response can be updated and reused; see Section 2.8. 609 A full response (i.e., one with a response body) indicates that none 610 of the stored responses nominated in the conditional request is 611 suitable. Instead, the full response SHOULD be used to satisfy the 612 request and MAY replace the stored response. 614 If a cache receives a 5xx response while attempting to validate a 615 response, it MAY either forward this response to the requesting 616 client, or act as if the server failed to respond. In the latter 617 case, it MAY return a previously stored response (see Section 2.3.3). 619 2.5. Request Methods that Invalidate 621 Because unsafe methods (Section 7.1.1 of [Part2]) have the potential 622 for changing state on the origin server, intervening caches can use 623 them to keep their contents up-to-date. 625 The following HTTP methods MUST cause a cache to invalidate the 626 effective Request URI (Section 4.3 of [Part1]) as well as the URI(s) 627 in the Location and Content-Location headers (if present): 629 o PUT 631 o DELETE 633 o POST 635 An invalidation based on a URI from a Location or Content-Location 636 header MUST NOT be performed if the host part of that URI differs 637 from the host part in the effective request URI (Section 4.3 of 638 [Part1]). This helps prevent denial of service attacks. 640 A cache that passes through requests for methods it does not 641 understand SHOULD invalidate the effective request URI (Section 4.3 642 of [Part1]). 644 Here, "invalidate" means that the cache will either remove all stored 645 responses related to the effective request URI, or will mark these as 646 "invalid" and in need of a mandatory validation before they can be 647 returned in response to a subsequent request. 649 Note that this does not guarantee that all appropriate responses are 650 invalidated. For example, the request that caused the change at the 651 origin server might not have gone through the cache where a response 652 is stored. 654 2.6. Shared Caching of Authenticated Responses 656 Shared caches MUST NOT use a cached response to a request with an 657 Authorization header (Section 3.1 of [Part7]) to satisfy any 658 subsequent request unless a cache directive that allows such 659 responses to be stored is present in the response. 661 In this specification, the following Cache-Control response 662 directives (Section 3.2.2) have such an effect: must-revalidate, 663 public, s-maxage. 665 Note that cached responses that contain the "must-revalidate" and/or 666 "s-maxage" response directives are not allowed to be served stale 667 (Section 2.3.3) by shared caches. In particular, a response with 668 either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to 669 satisfy a subsequent request without revalidating it on the origin 670 server. 672 2.7. Caching Negotiated Responses 674 When a cache receives a request that can be satisfied by a stored 675 response that has a Vary header field (Section 3.5), it MUST NOT use 676 that response unless all of the selecting request-headers nominated 677 by the Vary header match in both the original request (i.e., that 678 associated with the stored response), and the presented request. 680 The selecting request-headers from two requests are defined to match 681 if and only if those in the first request can be transformed to those 682 in the second request by applying any of the following: 684 o adding or removing whitespace, where allowed in the header's 685 syntax 687 o combining multiple message-header fields with the same field name 688 (see Section 3.2 of [Part1]) 690 o normalizing both header values in a way that is known to have 691 identical semantics, according to the header's specification 692 (e.g., re-ordering field values when order is not significant; 693 case-normalization, where values are defined to be case- 694 insensitive) 696 If (after any normalization that might take place) a header field is 697 absent from a request, it can only match another request if it is 698 also absent there. 700 A Vary header field-value of "*" always fails to match, and 701 subsequent requests to that resource can only be properly interpreted 702 by the origin server. 704 The stored response with matching selecting request-headers is known 705 as the selected response. 707 If no selected response is available, the cache MAY forward the 708 presented request to the origin server in a conditional request; see 709 Section 2.4. 711 2.8. Combining Responses 713 When a cache receives a 304 (Not Modified) response or a 206 (Partial 714 Content) response (in this section, the "new" response"), it needs to 715 created an updated response by combining the stored response with the 716 new one, so that the updated response can be used to satisfy the 717 request, and potentially update the cached response. 719 If the new response contains an ETag, it identifies the stored 720 response to use. [[TODO-mention-CL: might need language about 721 Content-Location here]][[TODO-select-for-combine: Shouldn't this be 722 the selected response?]] 724 If the new response's status code is 206 (partial content), both the 725 stored and new responses MUST have validators, and those validators 726 MUST match using the strong comparison function (see Section 4 of 727 [Part4]). Otherwise, the responses MUST NOT be combined. 729 The stored response headers are used as those of the updated 730 response, except that 732 o any stored Warning headers with warn-code 1xx (see Section 3.6) 733 MUST be deleted. 735 o any stored Warning headers with warn-code 2xx MUST be retained. 737 o any other headers provided in the new response MUST replace all 738 instances of the corresponding headers from the stored response. 740 The updated response headers MUST be used to replace those of the 741 stored response in cache (unless the stored response is removed from 742 cache). In the case of a 206 response, the combined representation 743 MAY be stored. 745 3. Header Field Definitions 747 This section defines the syntax and semantics of HTTP/1.1 header 748 fields related to caching. 750 3.1. Age 752 The "Age" response-header field conveys the sender's estimate of the 753 amount of time since the response was generated or successfully 754 validated at the origin server. Age values are calculated as 755 specified in Section 2.3.2. 757 Age = "Age" ":" OWS Age-v 758 Age-v = delta-seconds 760 Age field-values are non-negative integers, representing time in 761 seconds. 763 delta-seconds = 1*DIGIT 765 If a cache receives a value larger than the largest positive integer 766 it can represent, or if any of its age calculations overflows, it 767 MUST transmit an Age header with a field-value of 2147483648 (2^31). 769 Caches SHOULD use an arithmetic type of at least 31 bits of range. 771 The presence of an Age header field in a response implies that a 772 response is not first-hand. However, the converse is not true, since 773 HTTP/1.0 caches might not implement the Age header field. 775 3.2. Cache-Control 777 The "Cache-Control" general-header field is used to specify 778 directives for caches along the request/response chain. Such cache 779 directives are unidirectional in that the presence of a directive in 780 a request does not imply that the same directive is to be given in 781 the response. 783 HTTP/1.1 caches MUST obey the requirements of the Cache-Control 784 directives defined in this section. See Section 3.2.3 for 785 information about how Cache-Control directives defined elsewhere are 786 handled. 788 Note: HTTP/1.0 caches might not implement Cache-Control and might 789 only implement Pragma: no-cache (see Section 3.4). 791 Cache directives MUST be passed through by a proxy or gateway 792 application, regardless of their significance to that application, 793 since the directives might be applicable to all recipients along the 794 request/response chain. It is not possible to target a directive to 795 a specific cache. 797 Cache-Control = "Cache-Control" ":" OWS Cache-Control-v 798 Cache-Control-v = 1#cache-directive 800 cache-directive = cache-request-directive 801 / cache-response-directive 803 cache-extension = token [ "=" ( token / quoted-string ) ] 805 3.2.1. Request Cache-Control Directives 807 cache-request-directive = 808 "no-cache" 809 / "no-store" 810 / "max-age" "=" delta-seconds 811 / "max-stale" [ "=" delta-seconds ] 812 / "min-fresh" "=" delta-seconds 813 / "no-transform" 814 / "only-if-cached" 815 / cache-extension 817 no-cache 819 The no-cache request directive indicates that a stored response 820 MUST NOT be used to satisfy the request without successful 821 validation on the origin server. 823 no-store 825 The no-store request directive indicates that a cache MUST NOT 826 store any part of either this request or any response to it. This 827 directive applies to both non-shared and shared caches. "MUST NOT 828 store" in this context means that the cache MUST NOT intentionally 829 store the information in non-volatile storage, and MUST make a 830 best-effort attempt to remove the information from volatile 831 storage as promptly as possible after forwarding it. 833 This directive is NOT a reliable or sufficient mechanism for 834 ensuring privacy. In particular, malicious or compromised caches 835 might not recognize or obey this directive, and communications 836 networks might be vulnerable to eavesdropping. 838 max-age 840 The max-age request directive indicates that the client is willing 841 to accept a response whose age is no greater than the specified 842 time in seconds. Unless the max-stale request directive is also 843 present, the client is not willing to accept a stale response. 845 max-stale 847 The max-stale request directive indicates that the client is 848 willing to accept a response that has exceeded its expiration 849 time. If max-stale is assigned a value, then the client is 850 willing to accept a response that has exceeded its expiration time 851 by no more than the specified number of seconds. If no value is 852 assigned to max-stale, then the client is willing to accept a 853 stale response of any age. 855 min-fresh 857 The min-fresh request directive indicates that the client is 858 willing to accept a response whose freshness lifetime is no less 859 than its current age plus the specified time in seconds. That is, 860 the client wants a response that will still be fresh for at least 861 the specified number of seconds. 863 no-transform 865 The no-transform request directive indicates that an intermediate 866 cache or proxy MUST NOT change the Content-Encoding, Content-Range 867 or Content-Type request headers, nor the request representation. 869 only-if-cached 871 The only-if-cached request directive indicates that the client 872 only wishes to return a stored response. If it receives this 873 directive, a cache SHOULD either respond using a stored response 874 that is consistent with the other constraints of the request, or 875 respond with a 504 (Gateway Timeout) status code. If a group of 876 caches is being operated as a unified system with good internal 877 connectivity, such a request MAY be forwarded within that group of 878 caches. 880 3.2.2. Response Cache-Control Directives 882 cache-response-directive = 883 "public" 884 / "private" [ "=" DQUOTE 1#field-name DQUOTE ] 885 / "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] 886 / "no-store" 887 / "no-transform" 888 / "must-revalidate" 889 / "proxy-revalidate" 890 / "max-age" "=" delta-seconds 891 / "s-maxage" "=" delta-seconds 892 / cache-extension 894 public 896 The public response directive indicates that the response MAY be 897 cached, even if it would normally be non-cacheable or cacheable 898 only within a non-shared cache. (See also Authorization, Section 899 3.1 of [Part7], for additional details.) 901 private 903 The private response directive indicates that the response message 904 is intended for a single user and MUST NOT be stored by a shared 905 cache. A private (non-shared) cache MAY store the response. 907 If the private response directive specifies one or more field- 908 names, this requirement is limited to the field-values associated 909 with the listed response headers. That is, the specified field- 910 names(s) MUST NOT be stored by a shared cache, whereas the 911 remainder of the response message MAY be. 913 Note: This usage of the word private only controls where the 914 response can be stored; it cannot ensure the privacy of the 915 message content. Also, private response directives with field- 916 names are often handled by implementations as if an unqualified 917 private directive was received; i.e., the special handling for the 918 qualified form is not widely implemented. 920 no-cache 922 The no-cache response directive indicates that the response MUST 923 NOT be used to satisfy a subsequent request without successful 924 validation on the origin server. This allows an origin server to 925 prevent a cache from using it to satisfy a request without 926 contacting it, even by caches that have been configured to return 927 stale responses. 929 If the no-cache response directive specifies one or more field- 930 names, this requirement is limited to the field-values associated 931 with the listed response headers. That is, the specified field- 932 name(s) MUST NOT be sent in the response to a subsequent request 933 without successful validation on the origin server. This allows 934 an origin server to prevent the re-use of certain header fields in 935 a response, while still allowing caching of the rest of the 936 response. 938 Note: Most HTTP/1.0 caches will not recognize or obey this 939 directive. Also, no-cache response directives with field-names 940 are often handled by implementations as if an unqualified no-cache 941 directive was received; i.e., the special handling for the 942 qualified form is not widely implemented. 944 no-store 946 The no-store response directive indicates that a cache MUST NOT 947 store any part of either the immediate request or response. This 948 directive applies to both non-shared and shared caches. "MUST NOT 949 store" in this context means that the cache MUST NOT intentionally 950 store the information in non-volatile storage, and MUST make a 951 best-effort attempt to remove the information from volatile 952 storage as promptly as possible after forwarding it. 954 This directive is NOT a reliable or sufficient mechanism for 955 ensuring privacy. In particular, malicious or compromised caches 956 might not recognize or obey this directive, and communications 957 networks might be vulnerable to eavesdropping. 959 must-revalidate 961 The must-revalidate response directive indicates that once it has 962 become stale, the response MUST NOT be used to satisfy subsequent 963 requests without successful validation on the origin server. 965 The must-revalidate directive is necessary to support reliable 966 operation for certain protocol features. In all circumstances an 967 HTTP/1.1 cache MUST obey the must-revalidate directive; in 968 particular, if the cache cannot reach the origin server for any 969 reason, it MUST generate a 504 (Gateway Timeout) response. 971 Servers SHOULD send the must-revalidate directive if and only if 972 failure to validate a request on the representation could result 973 in incorrect operation, such as a silently unexecuted financial 974 transaction. 976 proxy-revalidate 978 The proxy-revalidate response directive has the same meaning as 979 the must-revalidate response directive, except that it does not 980 apply to non-shared caches. 982 max-age 984 The max-age response directive indicates that response is to be 985 considered stale after its age is greater than the specified 986 number of seconds. 988 s-maxage 990 The s-maxage response directive indicates that, in shared caches, 991 the maximum age specified by this directive overrides the maximum 992 age specified by either the max-age directive or the Expires 993 header. The s-maxage directive also implies the semantics of the 994 proxy-revalidate response directive. 996 no-transform 998 The no-transform response directive indicates that an intermediate 999 cache or proxy MUST NOT change the Content-Encoding, Content-Range 1000 or Content-Type response headers, nor the response representation. 1002 3.2.3. Cache Control Extensions 1004 The Cache-Control header field can be extended through the use of one 1005 or more cache-extension tokens, each with an optional value. 1006 Informational extensions (those that do not require a change in cache 1007 behavior) can be added without changing the semantics of other 1008 directives. Behavioral extensions are designed to work by acting as 1009 modifiers to the existing base of cache directives. Both the new 1010 directive and the standard directive are supplied, such that 1011 applications that do not understand the new directive will default to 1012 the behavior specified by the standard directive, and those that 1013 understand the new directive will recognize it as modifying the 1014 requirements associated with the standard directive. In this way, 1015 extensions to the cache-control directives can be made without 1016 requiring changes to the base protocol. 1018 This extension mechanism depends on an HTTP cache obeying all of the 1019 cache-control directives defined for its native HTTP-version, obeying 1020 certain extensions, and ignoring all directives that it does not 1021 understand. 1023 For example, consider a hypothetical new response directive called 1024 "community" that acts as a modifier to the private directive. We 1025 define this new directive to mean that, in addition to any non-shared 1026 cache, any cache that is shared only by members of the community 1027 named within its value may cache the response. An origin server 1028 wishing to allow the UCI community to use an otherwise private 1029 response in their shared cache(s) could do so by including 1031 Cache-Control: private, community="UCI" 1033 A cache seeing this header field will act correctly even if the cache 1034 does not understand the community cache-extension, since it will also 1035 see and understand the private directive and thus default to the safe 1036 behavior. 1038 Unrecognized cache directives MUST be ignored; it is assumed that any 1039 cache directive likely to be unrecognized by an HTTP/1.1 cache will 1040 be combined with standard directives (or the response's default 1041 cacheability) such that the cache behavior will remain minimally 1042 correct even if the cache does not understand the extension(s). 1044 The HTTP Cache Directive Registry defines the name space for the 1045 cache directives. 1047 Registrations MUST include the following fields: 1049 o Cache Directive Name 1051 o Pointer to specification text 1053 Values to be added to this name space are subject to IETF review 1054 ([RFC5226], Section 4.1). 1056 The registry itself is maintained at 1057 . 1059 3.3. Expires 1061 The "Expires" header field gives the date/time after which the 1062 response is considered stale. See Section 2.3 for further discussion 1063 of the freshness model. 1065 The presence of an Expires field does not imply that the original 1066 resource will change or cease to exist at, before, or after that 1067 time. 1069 The field-value is an absolute date and time as defined by HTTP-date 1070 in Section 6.1 of [Part1]; it MUST be sent in rfc1123-date format. 1072 Expires = "Expires" ":" OWS Expires-v 1073 Expires-v = HTTP-date 1075 For example 1077 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1079 Note: If a response includes a Cache-Control field with the max- 1080 age directive (see Section 3.2.2), that directive overrides the 1081 Expires field. Likewise, the s-maxage directive overrides Expires 1082 in shared caches. 1084 HTTP/1.1 servers SHOULD NOT send Expires dates more than one year in 1085 the future. 1087 HTTP/1.1 clients and caches MUST treat other invalid date formats, 1088 especially including the value "0", as in the past (i.e., "already 1089 expired"). 1091 3.4. Pragma 1093 The "Pragma" general-header field is used to include implementation- 1094 specific directives that might apply to any recipient along the 1095 request/response chain. All pragma directives specify optional 1096 behavior from the viewpoint of the protocol; however, some systems 1097 MAY require that behavior be consistent with the directives. 1099 Pragma = "Pragma" ":" OWS Pragma-v 1100 Pragma-v = 1#pragma-directive 1101 pragma-directive = "no-cache" / extension-pragma 1102 extension-pragma = token [ "=" ( token / quoted-string ) ] 1104 When the no-cache directive is present in a request message, an 1105 application SHOULD forward the request toward the origin server even 1106 if it has a cached copy of what is being requested. This pragma 1107 directive has the same semantics as the no-cache response directive 1108 (see Section 3.2.2) and is defined here for backward compatibility 1109 with HTTP/1.0. Clients SHOULD include both header fields when a no- 1110 cache request is sent to a server not known to be HTTP/1.1 compliant. 1111 HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had 1112 sent "Cache-Control: no-cache". 1114 Note: Because the meaning of "Pragma: no-cache" as a response- 1115 header field is not actually specified, it does not provide a 1116 reliable replacement for "Cache-Control: no-cache" in a response. 1118 This mechanism is deprecated; no new Pragma directives will be 1119 defined in HTTP. 1121 3.5. Vary 1123 The "Vary" response-header field conveys the set of request-header 1124 fields that were used to select the representation. 1126 Caches use this information, in part, to determine whether a stored 1127 response can be used to satisfy a given request; see Section 2.7. 1128 determines, while the response is fresh, whether a cache is permitted 1129 to use the response to reply to a subsequent request without 1130 validation; see Section 2.7. 1132 In uncacheable or stale responses, the Vary field value advises the 1133 user agent about the criteria that were used to select the 1134 representation. 1136 Vary = "Vary" ":" OWS Vary-v 1137 Vary-v = "*" / 1#field-name 1139 The set of header fields named by the Vary field value is known as 1140 the selecting request-headers. 1142 Servers SHOULD include a Vary header field with any cacheable 1143 response that is subject to server-driven negotiation. Doing so 1144 allows a cache to properly interpret future requests on that resource 1145 and informs the user agent about the presence of negotiation on that 1146 resource. A server MAY include a Vary header field with a non- 1147 cacheable response that is subject to server-driven negotiation, 1148 since this might provide the user agent with useful information about 1149 the dimensions over which the response varies at the time of the 1150 response. 1152 A Vary field value of "*" signals that unspecified parameters not 1153 limited to the request-headers (e.g., the network address of the 1154 client), play a role in the selection of the response representation; 1155 therefore, a cache cannot determine whether this response is 1156 appropriate. The "*" value MUST NOT be generated by a proxy server. 1158 The field-names given are not limited to the set of standard request- 1159 header fields defined by this specification. Field names are case- 1160 insensitive. 1162 3.6. Warning 1164 The "Warning" general-header field is used to carry additional 1165 information about the status or transformation of a message that 1166 might not be reflected in the message. This information is typically 1167 used to warn about possible incorrectness introduced by caching 1168 operations or transformations applied to the payload of the message. 1170 Warnings can be used for other purposes, both cache-related and 1171 otherwise. The use of a warning, rather than an error status code, 1172 distinguishes these responses from true failures. 1174 Warning headers can in general be applied to any message, however 1175 some warn-codes are specific to caches and can only be applied to 1176 response messages. 1178 Warning = "Warning" ":" OWS Warning-v 1179 Warning-v = 1#warning-value 1181 warning-value = warn-code SP warn-agent SP warn-text 1182 [SP warn-date] 1184 warn-code = 3DIGIT 1185 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1186 ; the name or pseudonym of the server adding 1187 ; the Warning header, for use in debugging 1188 warn-text = quoted-string 1189 warn-date = DQUOTE HTTP-date DQUOTE 1191 Multiple warnings can be attached to a response (either by the origin 1192 server or by a cache), including multiple warnings with the same code 1193 number, only differing in warn-text. 1195 When this occurs, the user agent SHOULD inform the user of as many of 1196 them as possible, in the order that they appear in the response. 1198 Systems that generate multiple Warning headers SHOULD order them with 1199 this user agent behavior in mind. New Warning headers SHOULD be 1200 added after any existing Warning headers. 1202 Warnings are assigned three digit warn-codes. The first digit 1203 indicates whether the Warning is required to be deleted from a stored 1204 response after validation: 1206 o 1xx Warnings describe the freshness or validation status of the 1207 response, and so MUST be deleted by caches after validation. They 1208 can only be generated by a cache when validating a cached entry, 1209 and MUST NOT be generated in any other situation. 1211 o 2xx Warnings describe some aspect of the representation that is 1212 not rectified by a validation (for example, a lossy compression of 1213 the representation) and MUST NOT be deleted by caches after 1214 validation, unless a full response is returned, in which case they 1215 MUST be. 1217 If an implementation sends a message with one or more Warning headers 1218 to a receiver whose version is HTTP/1.0 or lower, then the sender 1219 MUST include in each warning-value a warn-date that matches the Date 1220 header in the message. 1222 If an implementation receives a message with a warning-value that 1223 includes a warn-date, and that warn-date is different from the Date 1224 value in the response, then that warning-value MUST be deleted from 1225 the message before storing, forwarding, or using it. (preventing the 1226 consequences of naive caching of Warning header fields.) If all of 1227 the warning-values are deleted for this reason, the Warning header 1228 MUST be deleted as well. 1230 The following warn-codes are defined by this specification, each with 1231 a recommended warn-text in English, and a description of its meaning. 1233 110 Response is stale 1235 SHOULD be included whenever the returned response is stale. 1237 111 Revalidation failed 1239 SHOULD be included if a cache returns a stale response because an 1240 attempt to validate the response failed, due to an inability to 1241 reach the server. 1243 112 Disconnected operation 1245 SHOULD be included if the cache is intentionally disconnected from 1246 the rest of the network for a period of time. 1248 113 Heuristic expiration 1250 SHOULD be included if the cache heuristically chose a freshness 1251 lifetime greater than 24 hours and the response's age is greater 1252 than 24 hours. 1254 199 Miscellaneous warning 1256 The warning text can include arbitrary information to be presented 1257 to a human user, or logged. A system receiving this warning MUST 1258 NOT take any automated action, besides presenting the warning to 1259 the user. 1261 214 Transformation applied 1263 MUST be added by an intermediate proxy if it applies any 1264 transformation to the representation, such as changing the 1265 content-coding, media-type, or modifying the representation data, 1266 unless this Warning code already appears in the response. 1268 299 Miscellaneous persistent 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. 1274 4. History Lists 1276 User agents often have history mechanisms, such as "Back" buttons and 1277 history lists, that can be used to redisplay a representation 1278 retrieved earlier in a session. 1280 The freshness model (Section 2.3) does not necessarily apply to 1281 history mechanisms. I.e., a history mechanism can display a previous 1282 representation even if it has expired. 1284 This does not prohibit the history mechanism from telling the user 1285 that a view might be stale, or from honoring cache directives (e.g., 1286 Cache-Control: no-store). 1288 5. IANA Considerations 1290 5.1. Cache Directive Registry 1292 The registration procedure for HTTP Cache Directives is defined by 1293 Section 3.2.3 of this document. 1295 The HTTP Cache Directive Registry shall be created at 1296 and be 1297 populated with the registrations below: 1299 +------------------------+------------------------------+ 1300 | Cache Directive | Reference | 1301 +------------------------+------------------------------+ 1302 | max-age | Section 3.2.1, Section 3.2.2 | 1303 | max-stale | Section 3.2.1 | 1304 | min-fresh | Section 3.2.1 | 1305 | must-revalidate | Section 3.2.2 | 1306 | no-cache | Section 3.2.1, Section 3.2.2 | 1307 | no-store | Section 3.2.1, Section 3.2.2 | 1308 | no-transform | Section 3.2.1, Section 3.2.2 | 1309 | only-if-cached | Section 3.2.1 | 1310 | private | Section 3.2.2 | 1311 | proxy-revalidate | Section 3.2.2 | 1312 | public | Section 3.2.2 | 1313 | s-maxage | Section 3.2.2 | 1314 | stale-if-error | [RFC5861], Section 4 | 1315 | stale-while-revalidate | [RFC5861], Section 3 | 1316 +------------------------+------------------------------+ 1318 5.2. Header Field Registration 1320 The Message Header Field Registry located at shall be 1322 updated with the permanent registrations below (see [RFC3864]): 1324 +-------------------+----------+----------+-------------+ 1325 | Header Field Name | Protocol | Status | Reference | 1326 +-------------------+----------+----------+-------------+ 1327 | Age | http | standard | Section 3.1 | 1328 | Cache-Control | http | standard | Section 3.2 | 1329 | Expires | http | standard | Section 3.3 | 1330 | Pragma | http | standard | Section 3.4 | 1331 | Vary | http | standard | Section 3.5 | 1332 | Warning | http | standard | Section 3.6 | 1333 +-------------------+----------+----------+-------------+ 1335 The change controller is: "IETF (iesg@ietf.org) - Internet 1336 Engineering Task Force". 1338 6. Security Considerations 1340 Caches expose additional potential vulnerabilities, since the 1341 contents of the cache represent an attractive target for malicious 1342 exploitation. Because cache contents persist after an HTTP request 1343 is complete, an attack on the cache can reveal information long after 1344 a user believes that the information has been removed from the 1345 network. Therefore, cache contents need to be protected as sensitive 1346 information. 1348 7. Acknowledgments 1350 Much of the content and presentation of the caching design is due to 1351 suggestions and comments from individuals including: Shel Kaphan, 1352 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 1354 8. References 1356 8.1. Normative References 1358 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1359 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1360 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 1361 and Message Parsing", draft-ietf-httpbis-p1-messaging-11 1362 (work in progress), August 2010. 1364 [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1365 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1366 and J. Reschke, Ed., "HTTP/1.1, part 2: Message 1367 Semantics", draft-ietf-httpbis-p2-semantics-11 (work in 1368 progress), August 2010. 1370 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1371 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1372 and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional 1373 Requests", draft-ietf-httpbis-p4-conditional-11 (work in 1374 progress), August 2010. 1376 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1377 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1378 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 1379 Partial Responses", draft-ietf-httpbis-p5-range-11 (work 1380 in progress), August 2010. 1382 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1383 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1384 and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", 1385 draft-ietf-httpbis-p7-auth-11 (work in progress), 1386 August 2010. 1388 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1389 Requirement Levels", BCP 14, RFC 2119, March 1997. 1391 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1392 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1394 8.2. Informative References 1396 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1397 Specification, Implementation", RFC 1305, March 1992. 1399 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1400 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1401 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1403 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1404 Procedures for Message Header Fields", BCP 90, RFC 3864, 1405 September 2004. 1407 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1408 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1409 May 2008. 1411 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1412 Content", RFC 5861, April 2010. 1414 Appendix A. Changes from RFC 2616 1416 Make the specified age calculation algorithm less conservative. 1417 (Section 2.3.2) 1419 Remove requirement to consider Content-Location in successful 1420 responses in order to determine the appropriate response to use. 1421 (Section 2.4) 1423 Clarify denial of service attack avoidance requirement. 1424 (Section 2.5) 1426 Do not mention RFC 2047 encoding and multiple languages in Warning 1427 headers anymore, as these aspects never were implemented. 1428 (Section 3.6) 1430 Appendix B. Collected ABNF 1432 Age = "Age:" OWS Age-v 1433 Age-v = delta-seconds 1435 Cache-Control = "Cache-Control:" OWS Cache-Control-v 1436 Cache-Control-v = *( "," OWS ) cache-directive *( OWS "," [ OWS 1437 cache-directive ] ) 1439 Expires = "Expires:" OWS Expires-v 1440 Expires-v = HTTP-date 1442 HTTP-date = 1444 OWS = 1446 Pragma = "Pragma:" OWS Pragma-v 1447 Pragma-v = *( "," OWS ) pragma-directive *( OWS "," [ OWS 1448 pragma-directive ] ) 1450 Vary = "Vary:" OWS Vary-v 1451 Vary-v = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name 1452 ] ) ) 1454 Warning = "Warning:" OWS Warning-v 1455 Warning-v = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value 1456 ] ) 1458 cache-directive = cache-request-directive / cache-response-directive 1459 cache-extension = token [ "=" ( token / quoted-string ) ] 1460 cache-request-directive = "no-cache" / "no-store" / ( "max-age=" 1461 delta-seconds ) / ( "max-stale" [ "=" delta-seconds ] ) / ( 1462 "min-fresh=" delta-seconds ) / "no-transform" / "only-if-cached" / 1463 cache-extension 1464 cache-response-directive = "public" / ( "private" [ "=" DQUOTE *( "," 1465 OWS ) field-name *( OWS "," [ OWS field-name ] ) DQUOTE ] ) / ( 1466 "no-cache" [ "=" DQUOTE *( "," OWS ) field-name *( OWS "," [ OWS 1467 field-name ] ) DQUOTE ] ) / "no-store" / "no-transform" / 1468 "must-revalidate" / "proxy-revalidate" / ( "max-age=" delta-seconds 1469 ) / ( "s-maxage=" delta-seconds ) / cache-extension 1471 delta-seconds = 1*DIGIT 1473 extension-pragma = token [ "=" ( token / quoted-string ) ] 1475 field-name = 1477 port = 1478 pragma-directive = "no-cache" / extension-pragma 1479 pseudonym = 1481 quoted-string = 1483 token = 1485 uri-host = 1487 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1488 warn-code = 3DIGIT 1489 warn-date = DQUOTE HTTP-date DQUOTE 1490 warn-text = quoted-string 1491 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date 1492 ] 1494 ABNF diagnostics: 1496 ; Age defined but not used 1497 ; Cache-Control defined but not used 1498 ; Expires defined but not used 1499 ; Pragma defined but not used 1500 ; Vary defined but not used 1501 ; Warning defined but not used 1503 Appendix C. Change Log (to be removed by RFC Editor before publication) 1505 C.1. Since RFC2616 1507 Extracted relevant partitions from [RFC2616]. 1509 C.2. Since draft-ietf-httpbis-p6-cache-00 1511 Closed issues: 1513 o : "Trailer" 1514 () 1516 o : "Invalidation 1517 after Update or Delete" 1518 () 1520 o : "Normative and 1521 Informative references" 1523 o : "Date reference 1524 typo" 1526 o : "Connection 1527 header text" 1529 o : "Informative 1530 references" 1532 o : "ISO-8859-1 1533 Reference" 1535 o : "Normative up- 1536 to-date references" 1538 o : "typo in 1539 13.2.2" 1541 Other changes: 1543 o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress 1544 on ) 1546 C.3. Since draft-ietf-httpbis-p6-cache-01 1548 Closed issues: 1550 o : "rel_path not 1551 used" 1553 Other changes: 1555 o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work 1556 in progress on ) 1558 o Add explicit references to BNF syntax and rules imported from 1559 other parts of the specification. 1561 C.4. Since draft-ietf-httpbis-p6-cache-02 1563 Ongoing work on IANA Message Header Registration 1564 (): 1566 o Reference RFC 3984, and update header registrations for headers 1567 defined in this document. 1569 C.5. Since draft-ietf-httpbis-p6-cache-03 1571 Closed issues: 1573 o : "Vary header 1574 classification" 1576 C.6. Since draft-ietf-httpbis-p6-cache-04 1578 Ongoing work on ABNF conversion 1579 (): 1581 o Use "/" instead of "|" for alternatives. 1583 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1584 whitespace ("OWS") and required whitespace ("RWS"). 1586 o Rewrite ABNFs to spell out whitespace rules, factor out header 1587 value format definitions. 1589 C.7. Since draft-ietf-httpbis-p6-cache-05 1591 This is a total rewrite of this part of the specification. 1593 Affected issues: 1595 o : "Definition of 1596 1xx Warn-Codes" 1598 o : "Placement of 1599 13.5.1 and 13.5.2" 1601 o : "The role of 1602 Warning and Semantic Transparency in Caching" 1604 o : "Methods and 1605 Caching" 1607 In addition: Final work on ABNF conversion 1608 (): 1610 o Add appendix containing collected and expanded ABNF, reorganize 1611 ABNF introduction. 1613 C.8. Since draft-ietf-httpbis-p6-cache-06 1615 Closed issues: 1617 o : "base for 1618 numeric protocol elements" 1620 Affected issues: 1622 o : Vary and non- 1623 existant headers 1625 C.9. Since draft-ietf-httpbis-p6-cache-07 1627 Closed issues: 1629 o : "Definition of 1630 1xx Warn-Codes" 1632 o : "Content- 1633 Location on 304 responses" 1635 o : "private and 1636 no-cache CC directives with headers" 1638 o : "RFC2047 and 1639 warn-text" 1641 C.10. Since draft-ietf-httpbis-p6-cache-08 1643 Closed issues: 1645 o : "serving 1646 negotiated responses from cache: header-specific canonicalization" 1648 o : "Effect of CC 1649 directives on history lists" 1651 Affected issues: 1653 o : Status codes 1654 and caching 1656 Partly resolved issues: 1658 o : "Placement of 1659 13.5.1 and 13.5.2" 1661 C.11. Since draft-ietf-httpbis-p6-cache-09 1663 Closed issues: 1665 o : "Age 1666 calculation" 1668 o : "Clarify 1669 differences between / requirements for request and response CC 1670 directives" 1672 o : "Caching 1673 authenticated responses" 1675 o : "IANA registry 1676 for cache-control directives" 1678 o : "Heuristic 1679 caching of URLs with query components" 1681 Partly resolved issues: 1683 o : "Term for the 1684 requested resource's URI" 1686 C.12. Since draft-ietf-httpbis-p6-cache-10 1688 Closed issues: 1690 o : "Clarify 1691 entity / representation / variant terminology" 1693 o : "consider 1694 removing the 'changes from 2068' sections" 1696 o : "Allowing 1697 heuristic caching for new status codes" 1699 o : "Allowing 1700 heuristic caching for new status codes" 1702 o Clean up TODOs and prose in "Combining Responses." 1704 Index 1706 A 1707 age 6 1708 Age header 17 1710 C 1711 cache 5 1712 Cache Directives 1713 max-age 19, 22 1714 max-stale 19 1715 min-fresh 19 1716 must-revalidate 22 1717 no-cache 19, 21 1718 no-store 19, 21 1719 no-transform 20, 22 1720 only-if-cached 20 1721 private 20 1722 proxy-revalidate 22 1723 public 20 1724 s-maxage 22 1725 Cache-Control header 18 1726 cacheable 5 1728 E 1729 Expires header 24 1730 explicit expiration time 5 1732 F 1733 first-hand 6 1734 fresh 6 1735 freshness lifetime 6 1737 G 1738 Grammar 1739 Age 17 1740 Age-v 17 1741 Cache-Control 18 1742 Cache-Control-v 18 1743 cache-extension 18 1744 cache-request-directive 18 1745 cache-response-directive 20 1746 delta-seconds 17 1747 Expires 24 1748 Expires-v 24 1749 extension-pragma 24 1750 Pragma 24 1751 pragma-directive 24 1752 Pragma-v 24 1753 Vary 25 1754 Vary-v 25 1755 warn-agent 26 1756 warn-code 26 1757 warn-date 26 1758 warn-text 26 1759 Warning 26 1760 Warning-v 26 1761 warning-value 26 1763 H 1764 Headers 1765 Age 17 1766 Cache-Control 18 1767 Expires 24 1768 Pragma 24 1769 Vary 25 1770 Warning 26 1771 heuristic expiration time 5 1773 M 1774 max-age 1775 Cache Directive 19, 22 1776 max-stale 1777 Cache Directive 19 1778 min-fresh 1779 Cache Directive 19 1780 must-revalidate 1781 Cache Directive 22 1783 N 1784 no-cache 1785 Cache Directive 19, 21 1786 no-store 1787 Cache Directive 19, 21 1788 no-transform 1789 Cache Directive 20, 22 1791 O 1792 only-if-cached 1793 Cache Directive 20 1795 P 1796 Pragma header 24 1797 private 1798 Cache Directive 20 1799 proxy-revalidate 1800 Cache Directive 22 1801 public 1802 Cache Directive 20 1804 S 1805 s-maxage 1806 Cache Directive 22 1807 stale 6 1809 V 1810 validator 6 1811 Vary header 25 1813 W 1814 Warning header 26 1816 Authors' Addresses 1818 Roy T. Fielding (editor) 1819 Day Software 1820 23 Corporate Plaza DR, Suite 280 1821 Newport Beach, CA 92660 1822 USA 1824 Phone: +1-949-706-5300 1825 Fax: +1-949-706-5305 1826 EMail: fielding@gbiv.com 1827 URI: http://roy.gbiv.com/ 1829 Jim Gettys 1830 Alcatel-Lucent Bell Labs 1831 21 Oak Knoll Road 1832 Carlisle, MA 01741 1833 USA 1835 EMail: jg@freedesktop.org 1836 URI: http://gettys.wordpress.com/ 1838 Jeffrey C. Mogul 1839 Hewlett-Packard Company 1840 HP Labs, Large Scale Systems Group 1841 1501 Page Mill Road, MS 1177 1842 Palo Alto, CA 94304 1843 USA 1845 EMail: JeffMogul@acm.org 1847 Henrik Frystyk Nielsen 1848 Microsoft Corporation 1849 1 Microsoft Way 1850 Redmond, WA 98052 1851 USA 1853 EMail: henrikn@microsoft.com 1854 Larry Masinter 1855 Adobe Systems, Incorporated 1856 345 Park Ave 1857 San Jose, CA 95110 1858 USA 1860 EMail: LMM@acm.org 1861 URI: http://larry.masinter.net/ 1863 Paul J. Leach 1864 Microsoft Corporation 1865 1 Microsoft Way 1866 Redmond, WA 98052 1868 EMail: paulle@microsoft.com 1870 Tim Berners-Lee 1871 World Wide Web Consortium 1872 MIT Computer Science and Artificial Intelligence Laboratory 1873 The Stata Center, Building 32 1874 32 Vassar Street 1875 Cambridge, MA 02139 1876 USA 1878 EMail: timbl@w3.org 1879 URI: http://www.w3.org/People/Berners-Lee/ 1881 Yves Lafon (editor) 1882 World Wide Web Consortium 1883 W3C / ERCIM 1884 2004, rte des Lucioles 1885 Sophia-Antipolis, AM 06902 1886 France 1888 EMail: ylafon@w3.org 1889 URI: http://www.raubacapeu.net/people/yves/ 1891 Mark Nottingham (editor) 1893 EMail: mnot@mnot.net 1894 URI: http://www.mnot.net/ 1895 Julian F. Reschke (editor) 1896 greenbytes GmbH 1897 Hafenweg 16 1898 Muenster, NW 48155 1899 Germany 1901 Phone: +49 251 2807760 1902 Fax: +49 251 2807761 1903 EMail: julian.reschke@greenbytes.de 1904 URI: http://greenbytes.de/tech/webdav/