idnits 2.17.00 (12 Aug 2021) /tmp/idnits27104/draft-ietf-httpbis-cache-03.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, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 18, 2018) is 1310 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC3986' is defined on line 1532, but no explicit reference was found in the text == Unused Reference: 'RFC7234' is defined on line 1572, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-messaging-03 -- Possible downref: Normative reference to a draft: ref. 'Messaging' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-03 -- Possible downref: Normative reference to a draft: ref. 'Semantics' -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP Working Group R. Fielding, Ed. 3 Internet-Draft Adobe 4 Obsoletes: 7234 (if approved) M. Nottingham, Ed. 5 Intended status: Standards Track Fastly 6 Expires: April 21, 2019 J. Reschke, Ed. 7 greenbytes 8 October 18, 2018 10 HTTP Caching 11 draft-ietf-httpbis-cache-03 13 Abstract 15 The Hypertext Transfer Protocol (HTTP) is a stateless application- 16 level protocol for distributed, collaborative, hypertext information 17 systems. This document defines HTTP caches and the associated header 18 fields that control cache behavior or indicate cacheable response 19 messages. 21 This document obsoletes RFC 7234. 23 Editorial Note 25 This note is to be removed before publishing as an RFC. 27 Discussion of this draft takes place on the HTTP working group 28 mailing list (ietf-http-wg@w3.org), which is archived at 29 . 31 Working Group information can be found at ; 32 source code and issues list for this draft can be found at 33 . 35 The changes in this draft are summarized in Appendix C.4. 37 Status of This Memo 39 This Internet-Draft is submitted in full conformance with the 40 provisions of BCP 78 and BCP 79. 42 Internet-Drafts are working documents of the Internet Engineering 43 Task Force (IETF). Note that other groups may also distribute 44 working documents as Internet-Drafts. The list of current Internet- 45 Drafts is at https://datatracker.ietf.org/drafts/current/. 47 Internet-Drafts are draft documents valid for a maximum of six months 48 and may be updated, replaced, or obsoleted by other documents at any 49 time. It is inappropriate to use Internet-Drafts as reference 50 material or to cite them other than as "work in progress." 52 This Internet-Draft will expire on April 21, 2019. 54 Copyright Notice 56 Copyright (c) 2018 IETF Trust and the persons identified as the 57 document authors. All rights reserved. 59 This document is subject to BCP 78 and the IETF Trust's Legal 60 Provisions Relating to IETF Documents 61 (https://trustee.ietf.org/license-info) in effect on the date of 62 publication of this document. Please review these documents 63 carefully, as they describe your rights and restrictions with respect 64 to this document. Code Components extracted from this document must 65 include Simplified BSD License text as described in Section 4.e of 66 the Trust Legal Provisions and are provided without warranty as 67 described in the Simplified BSD License. 69 This document may contain material from IETF Documents or IETF 70 Contributions published or made publicly available before November 71 10, 2008. The person(s) controlling the copyright in some of this 72 material may not have granted the IETF Trust the right to allow 73 modifications of such material outside the IETF Standards Process. 74 Without obtaining an adequate license from the person(s) controlling 75 the copyright in such materials, this document may not be modified 76 outside the IETF Standards Process, and derivative works of it may 77 not be created outside the IETF Standards Process, except to format 78 it for publication as an RFC or to translate it into languages other 79 than English. 81 Table of Contents 83 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 84 1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5 85 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5 86 1.3. Delta Seconds . . . . . . . . . . . . . . . . . . . . . . 5 87 2. Overview of Cache Operation . . . . . . . . . . . . . . . . . 6 88 3. Storing Responses in Caches . . . . . . . . . . . . . . . . . 7 89 3.1. Storing Incomplete Responses . . . . . . . . . . . . . . 8 90 3.2. Storing Responses to Authenticated Requests . . . . . . . 8 91 3.3. Combining Partial Content . . . . . . . . . . . . . . . . 8 92 4. Constructing Responses from Caches . . . . . . . . . . . . . 9 93 4.1. Calculating Secondary Keys with Vary . . . . . . . . . . 10 94 4.2. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 11 95 4.2.1. Calculating Freshness Lifetime . . . . . . . . . . . 12 96 4.2.2. Calculating Heuristic Freshness . . . . . . . . . . . 13 97 4.2.3. Calculating Age . . . . . . . . . . . . . . . . . . . 14 98 4.2.4. Serving Stale Responses . . . . . . . . . . . . . . . 15 99 4.3. Validation . . . . . . . . . . . . . . . . . . . . . . . 15 100 4.3.1. Sending a Validation Request . . . . . . . . . . . . 16 101 4.3.2. Handling a Received Validation Request . . . . . . . 16 102 4.3.3. Handling a Validation Response . . . . . . . . . . . 18 103 4.3.4. Freshening Stored Responses upon Validation . . . . . 18 104 4.3.5. Freshening Responses with HEAD . . . . . . . . . . . 19 105 4.4. Invalidation . . . . . . . . . . . . . . . . . . . . . . 20 106 5. Header Field Definitions . . . . . . . . . . . . . . . . . . 20 107 5.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 108 5.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 21 109 5.2.1. Request Cache-Control Directives . . . . . . . . . . 22 110 5.2.1.1. max-age . . . . . . . . . . . . . . . . . . . . . 22 111 5.2.1.2. max-stale . . . . . . . . . . . . . . . . . . . . 22 112 5.2.1.3. min-fresh . . . . . . . . . . . . . . . . . . . . 23 113 5.2.1.4. no-cache . . . . . . . . . . . . . . . . . . . . 23 114 5.2.1.5. no-store . . . . . . . . . . . . . . . . . . . . 23 115 5.2.1.6. no-transform . . . . . . . . . . . . . . . . . . 24 116 5.2.1.7. only-if-cached . . . . . . . . . . . . . . . . . 24 117 5.2.2. Response Cache-Control Directives . . . . . . . . . . 24 118 5.2.2.1. must-revalidate . . . . . . . . . . . . . . . . . 24 119 5.2.2.2. no-cache . . . . . . . . . . . . . . . . . . . . 24 120 5.2.2.3. no-store . . . . . . . . . . . . . . . . . . . . 25 121 5.2.2.4. no-transform . . . . . . . . . . . . . . . . . . 26 122 5.2.2.5. public . . . . . . . . . . . . . . . . . . . . . 26 123 5.2.2.6. private . . . . . . . . . . . . . . . . . . . . . 26 124 5.2.2.7. proxy-revalidate . . . . . . . . . . . . . . . . 27 125 5.2.2.8. max-age . . . . . . . . . . . . . . . . . . . . . 27 126 5.2.2.9. s-maxage . . . . . . . . . . . . . . . . . . . . 27 127 5.2.3. Cache Control Extensions . . . . . . . . . . . . . . 27 128 5.2.4. Cache Directive Registry . . . . . . . . . . . . . . 28 129 5.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 29 130 5.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . 30 131 5.5. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 30 132 6. Relationship to Applications . . . . . . . . . . . . . . . . 31 133 7. Security Considerations . . . . . . . . . . . . . . . . . . . 31 134 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 135 8.1. Header Field Registration . . . . . . . . . . . . . . . . 32 136 8.2. Cache Directive Registration . . . . . . . . . . . . . . 32 137 8.3. Warn Code Registry . . . . . . . . . . . . . . . . . . . 32 138 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 139 9.1. Normative References . . . . . . . . . . . . . . . . . . 32 140 9.2. Informative References . . . . . . . . . . . . . . . . . 33 141 Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 35 142 Appendix B. Changes from RFC 7234 . . . . . . . . . . . . . . . 35 143 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 36 144 C.1. Between RFC7234 and draft 00 . . . . . . . . . . . . . . 36 145 C.2. Since draft-ietf-httpbis-cache-00 . . . . . . . . . . . . 36 146 C.3. Since draft-ietf-httpbis-cache-01 . . . . . . . . . . . . 36 147 C.4. Since draft-ietf-httpbis-cache-02 . . . . . . . . . . . . 36 148 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 149 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 39 150 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39 152 1. Introduction 154 The Hypertext Transfer Protocol (HTTP) is a stateless application- 155 level request/response protocol that uses extensible semantics and 156 self-descriptive messages for flexible interaction with network-based 157 hypertext information systems. HTTP is defined by a series of 158 documents that collectively form the HTTP/1.1 specification: 160 o "HTTP Semantics" [Semantics] 162 o "HTTP Caching" (this document) 164 o "HTTP/1.1 Messaging" [Messaging] 166 HTTP is typically used for distributed information systems, where 167 performance can be improved by the use of response caches. This 168 document defines aspects of HTTP related to caching and reusing 169 response messages. 171 An HTTP cache is a local store of response messages and the subsystem 172 that controls storage, retrieval, and deletion of messages in it. A 173 cache stores cacheable responses in order to reduce the response time 174 and network bandwidth consumption on future, equivalent requests. 175 Any client or server MAY employ a cache, though a cache cannot be 176 used by a server that is acting as a tunnel. 178 A shared cache is a cache that stores responses to be reused by more 179 than one user; shared caches are usually (but not always) deployed as 180 a part of an intermediary. A private cache, in contrast, is 181 dedicated to a single user; often, they are deployed as a component 182 of a user agent. 184 The goal of caching in HTTP is to significantly improve performance 185 by reusing a prior response message to satisfy a current request. A 186 stored response is considered "fresh", as defined in Section 4.2, if 187 the response can be reused without "validation" (checking with the 188 origin server to see if the cached response remains valid for this 189 request). A fresh response can therefore reduce both latency and 190 network overhead each time it is reused. When a cached response is 191 not fresh, it might still be reusable if it can be freshened by 192 validation (Section 4.3) or if the origin is unavailable 193 (Section 4.2.4). 195 This document obsoletes RFC 7234, with the changes being summarized 196 in Appendix B. 198 1.1. Requirements Notation 200 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 201 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 202 document are to be interpreted as described in [RFC2119]. 204 Conformance criteria and considerations regarding error handling are 205 defined in Section 3 of [Semantics]. 207 1.2. Syntax Notation 209 This specification uses the Augmented Backus-Naur Form (ABNF) 210 notation of [RFC5234] with a list extension, defined in Section 11 of 211 [Semantics], that allows for compact definition of comma-separated 212 lists using a '#' operator (similar to how the '*' operator indicates 213 repetition). Appendix A shows the collected grammar with all list 214 operators expanded to standard ABNF notation. 216 The following core rules are included by reference, as defined in 217 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 218 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 219 HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF (line 220 feed), OCTET (any 8-bit sequence of data), SP (space), and VCHAR (any 221 visible [USASCII] character). 223 The rules below are defined in [Semantics]: 225 HTTP-date = 226 OWS = 227 field-name = 228 quoted-string = 229 token = 230 uri-host = 231 port = 232 pseudonym = 234 1.3. Delta Seconds 236 The delta-seconds rule specifies a non-negative integer, representing 237 time in seconds. 239 delta-seconds = 1*DIGIT 241 A recipient parsing a delta-seconds value and converting it to binary 242 form ought to use an arithmetic type of at least 31 bits of non- 243 negative integer range. If a cache receives a delta-seconds value 244 greater than the greatest integer it can represent, or if any of its 245 subsequent calculations overflows, the cache MUST consider the value 246 to be either 2147483648 (2^31) or the greatest positive integer it 247 can conveniently represent. 249 Note: The value 2147483648 is here for historical reasons, 250 effectively represents infinity (over 68 years), and does not need 251 to be stored in binary form; an implementation could produce it as 252 a canned string if any overflow occurs, even if the calculations 253 are performed with an arithmetic type incapable of directly 254 representing that number. What matters here is that an overflow 255 be detected and not treated as a negative value in later 256 calculations. 258 2. Overview of Cache Operation 260 Proper cache operation preserves the semantics of HTTP transfers 261 ([Semantics]) while reducing the transfer of information already held 262 in the cache. Although caching is an entirely OPTIONAL feature of 263 HTTP, it can be assumed that reusing a cached response is desirable 264 and that such reuse is the default behavior when no requirement or 265 local configuration prevents it. Therefore, HTTP cache requirements 266 are focused on preventing a cache from either storing a non-reusable 267 response or reusing a stored response inappropriately, rather than 268 mandating that caches always store and reuse particular responses. 270 Each cache entry consists of a cache key and one or more HTTP 271 responses corresponding to prior requests that used the same key. 272 The most common form of cache entry is a successful result of a 273 retrieval request: i.e., a 200 (OK) response to a GET request, which 274 contains a representation of the resource identified by the request 275 target (Section 7.3.1 of [Semantics]). However, it is also possible 276 to cache permanent redirects, negative results (e.g., 404 (Not 277 Found)), incomplete results (e.g., 206 (Partial Content)), and 278 responses to methods other than GET if the method's definition allows 279 such caching and defines something suitable for use as a cache key. 281 The primary cache key consists of the request method and target URI. 282 However, since HTTP caches in common use today are typically limited 283 to caching responses to GET, many caches simply decline other methods 284 and use only the URI as the primary cache key. 286 If a request target is subject to content negotiation, its cache 287 entry might consist of multiple stored responses, each differentiated 288 by a secondary key for the values of the original request's selecting 289 header fields (Section 4.1). 291 3. Storing Responses in Caches 293 A cache MUST NOT store a response to any request, unless: 295 o The request method is understood by the cache and defined as being 296 cacheable, and 298 o the response status code is final (see Section 9.3 of 299 [Messaging]), and 301 o the response status code is understood by the cache, and 303 o the "no-store" cache directive (see Section 5.2) does not appear 304 in request or response header fields, and 306 o the "private" response directive (see Section 5.2.2.6) does not 307 appear in the response, if the cache is shared, and 309 o the Authorization header field (see Section 8.5.3 of [Semantics]) 310 does not appear in the request, if the cache is shared, unless the 311 response explicitly allows it (see Section 3.2), and 313 o the response either: 315 * contains an Expires header field (see Section 5.3), or 317 * contains a max-age response directive (see Section 5.2.2.8), or 319 * contains a s-maxage response directive (see Section 5.2.2.9) 320 and the cache is shared, or 322 * contains a Cache Control Extension (see Section 5.2.3) that 323 allows it to be cached, or 325 * has a status code that is defined as cacheable by default (see 326 Section 4.2.2), or 328 * contains a public response directive (see Section 5.2.2.5). 330 Note that any of the requirements listed above can be overridden by a 331 cache-control extension; see Section 5.2.3. 333 In this context, a cache has "understood" a request method or a 334 response status code if it recognizes it and implements all specified 335 caching-related behavior. 337 Note that, in normal operation, some caches will not store a response 338 that has neither a cache validator nor an explicit expiration time, 339 as such responses are not usually useful to store. However, caches 340 are not prohibited from storing such responses. 342 3.1. Storing Incomplete Responses 344 A response message is considered complete when all of the octets 345 indicated by the message framing ([Messaging]) are received prior to 346 the connection being closed. If the request method is GET, the 347 response status code is 200 (OK), and the entire response header 348 section has been received, a cache MAY store an incomplete response 349 message body if the cache entry is recorded as incomplete. Likewise, 350 a 206 (Partial Content) response MAY be stored as if it were an 351 incomplete 200 (OK) cache entry. However, a cache MUST NOT store 352 incomplete or partial-content responses if it does not support the 353 Range and Content-Range header fields or if it does not understand 354 the range units used in those fields. 356 A cache MAY complete a stored incomplete response by making a 357 subsequent range request (Section 8.3 of [Semantics]) and combining 358 the successful response with the stored entry, as defined in 359 Section 3.3. A cache MUST NOT use an incomplete response to answer 360 requests unless the response has been made complete or the request is 361 partial and specifies a range that is wholly within the incomplete 362 response. A cache MUST NOT send a partial response to a client 363 without explicitly marking it as such using the 206 (Partial Content) 364 status code. 366 3.2. Storing Responses to Authenticated Requests 368 A shared cache MUST NOT use a cached response to a request with an 369 Authorization header field (Section 8.5.3 of [Semantics]) to satisfy 370 any subsequent request unless a cache directive that allows such 371 responses to be stored is present in the response. 373 In this specification, the following Cache-Control response 374 directives (Section 5.2.2) have such an effect: must-revalidate, 375 public, and s-maxage. 377 3.3. Combining Partial Content 379 A response might transfer only a partial representation if the 380 connection closed prematurely or if the request used one or more 381 Range specifiers (Section 8.3 of [Semantics]). After several such 382 transfers, a cache might have received several ranges of the same 383 representation. A cache MAY combine these ranges into a single 384 stored response, and reuse that response to satisfy later requests, 385 if they all share the same strong validator and the cache complies 386 with the client requirements in Section 9.3.7.3 of [Semantics]. 388 When combining the new response with one or more stored responses, a 389 cache MUST use the header fields provided in the new response, aside 390 from Content-Range, to replace all instances of the corresponding 391 header fields in the stored response. 393 4. Constructing Responses from Caches 395 When presented with a request, a cache MUST NOT reuse a stored 396 response, unless: 398 o The presented effective request URI (Section 5.3 of [Semantics]) 399 and that of the stored response match, and 401 o the request method associated with the stored response allows it 402 to be used for the presented request, and 404 o selecting header fields nominated by the stored response (if any) 405 match those presented (see Section 4.1), and 407 o the presented request does not contain the no-cache pragma 408 (Section 5.4), nor the no-cache cache directive (Section 5.2.1), 409 unless the stored response is successfully validated 410 (Section 4.3), and 412 o the stored response does not contain the no-cache cache directive 413 (Section 5.2.2.2), unless it is successfully validated 414 (Section 4.3), and 416 o the stored response is either: 418 * fresh (see Section 4.2), or 420 * allowed to be served stale (see Section 4.2.4), or 422 * successfully validated (see Section 4.3). 424 Note that any of the requirements listed above can be overridden by a 425 cache-control extension; see Section 5.2.3. 427 When a stored response is used to satisfy a request without 428 validation, a cache MUST generate an Age header field (Section 5.1), 429 replacing any present in the response with a value equal to the 430 stored response's current_age; see Section 4.2.3. 432 A cache MUST write through requests with methods that are unsafe 433 (Section 7.2.1 of [Semantics]) to the origin server; i.e., a cache is 434 not allowed to generate a reply to such a request before having 435 forwarded the request and having received a corresponding response. 437 Also, note that unsafe requests might invalidate already-stored 438 responses; see Section 4.4. 440 When more than one suitable response is stored, a cache MUST use the 441 most recent response (as determined by the Date header field). It 442 can also forward the request with "Cache-Control: max-age=0" or 443 "Cache-Control: no-cache" to disambiguate which response to use. 445 A cache that does not have a clock available MUST NOT use stored 446 responses without revalidating them upon every use. 448 4.1. Calculating Secondary Keys with Vary 450 When a cache receives a request that can be satisfied by a stored 451 response that has a Vary header field (Section 10.1.4 of 452 [Semantics]), it MUST NOT use that response unless all of the 453 selecting header fields nominated by the Vary header field match in 454 both the original request (i.e., that associated with the stored 455 response), and the presented request. 457 The selecting header fields from two requests are defined to match if 458 and only if those in the first request can be transformed to those in 459 the second request by applying any of the following: 461 o adding or removing whitespace, where allowed in the header field's 462 syntax 464 o combining multiple header fields with the same field name (see 465 Section 4.2 of [Semantics]) 467 o normalizing both header field values in a way that is known to 468 have identical semantics, according to the header field's 469 specification (e.g., reordering field values when order is not 470 significant; case-normalization, where values are defined to be 471 case-insensitive) 473 If (after any normalization that might take place) a header field is 474 absent from a request, it can only match another request if it is 475 also absent there. 477 A Vary header field-value of "*" always fails to match. 479 The stored response with matching selecting header fields is known as 480 the selected response. 482 If multiple selected responses are available (potentially including 483 responses without a Vary header field), the cache will need to choose 484 one to use. When a selecting header field has a known mechanism for 485 doing so (e.g., qvalues on Accept and similar request header fields), 486 that mechanism MAY be used to select preferred responses; of the 487 remainder, the most recent response (as determined by the Date header 488 field) is used, as per Section 4. 490 If no selected response is available, the cache cannot satisfy the 491 presented request. Typically, it is forwarded to the origin server 492 in a (possibly conditional; see Section 4.3) request. 494 4.2. Freshness 496 A fresh response is one whose age has not yet exceeded its freshness 497 lifetime. Conversely, a stale response is one where it has. 499 A response's freshness lifetime is the length of time between its 500 generation by the origin server and its expiration time. An explicit 501 expiration time is the time at which the origin server intends that a 502 stored response can no longer be used by a cache without further 503 validation, whereas a heuristic expiration time is assigned by a 504 cache when no explicit expiration time is available. 506 A response's age is the time that has passed since it was generated 507 by, or successfully validated with, the origin server. 509 When a response is "fresh" in the cache, it can be used to satisfy 510 subsequent requests without contacting the origin server, thereby 511 improving efficiency. 513 The primary mechanism for determining freshness is for an origin 514 server to provide an explicit expiration time in the future, using 515 either the Expires header field (Section 5.3) or the max-age response 516 directive (Section 5.2.2.8). Generally, origin servers will assign 517 future explicit expiration times to responses in the belief that the 518 representation is not likely to change in a semantically significant 519 way before the expiration time is reached. 521 If an origin server wishes to force a cache to validate every 522 request, it can assign an explicit expiration time in the past to 523 indicate that the response is already stale. Compliant caches will 524 normally validate a stale cached response before reusing it for 525 subsequent requests (see Section 4.2.4). 527 Since origin servers do not always provide explicit expiration times, 528 caches are also allowed to use a heuristic to determine an expiration 529 time under certain circumstances (see Section 4.2.2). 531 The calculation to determine if a response is fresh is: 533 response_is_fresh = (freshness_lifetime > current_age) 535 freshness_lifetime is defined in Section 4.2.1; current_age is 536 defined in Section 4.2.3. 538 Clients can send the max-age or min-fresh cache directives in a 539 request to constrain or relax freshness calculations for the 540 corresponding response (Section 5.2.1). 542 When calculating freshness, to avoid common problems in date parsing: 544 o Although all date formats are specified to be case-sensitive, a 545 cache recipient SHOULD match day, week, and time-zone names case- 546 insensitively. 548 o If a cache recipient's internal implementation of time has less 549 resolution than the value of an HTTP-date, the recipient MUST 550 internally represent a parsed Expires date as the nearest time 551 equal to or earlier than the received value. 553 o A cache recipient MUST NOT allow local time zones to influence the 554 calculation or comparison of an age or expiration time. 556 o A cache recipient SHOULD consider a date with a zone abbreviation 557 other than GMT or UTC to be invalid for calculating expiration. 559 Note that freshness applies only to cache operation; it cannot be 560 used to force a user agent to refresh its display or reload a 561 resource. See Section 6 for an explanation of the difference between 562 caches and history mechanisms. 564 4.2.1. Calculating Freshness Lifetime 566 A cache can calculate the freshness lifetime (denoted as 567 freshness_lifetime) of a response by using the first match of the 568 following: 570 o If the cache is shared and the s-maxage response directive 571 (Section 5.2.2.9) is present, use its value, or 573 o If the max-age response directive (Section 5.2.2.8) is present, 574 use its value, or 576 o If the Expires response header field (Section 5.3) is present, use 577 its value minus the value of the Date response header field, or 579 o Otherwise, no explicit expiration time is present in the response. 580 A heuristic freshness lifetime might be applicable; see 581 Section 4.2.2. 583 Note that this calculation is not vulnerable to clock skew, since all 584 of the information comes from the origin server. 586 When there is more than one value present for a given directive 587 (e.g., two Expires header fields, multiple Cache-Control: max-age 588 directives), the directive's value is considered invalid. Caches are 589 encouraged to consider responses that have invalid freshness 590 information to be stale. 592 4.2.2. Calculating Heuristic Freshness 594 Since origin servers do not always provide explicit expiration times, 595 a cache MAY assign a heuristic expiration time when an explicit time 596 is not specified, employing algorithms that use other header field 597 values (such as the Last-Modified time) to estimate a plausible 598 expiration time. This specification does not provide specific 599 algorithms, but does impose worst-case constraints on their results. 601 A cache MUST NOT use heuristics to determine freshness when an 602 explicit expiration time is present in the stored response. Because 603 of the requirements in Section 3, this means that, effectively, 604 heuristics can only be used on responses without explicit freshness 605 whose status codes are defined as cacheable by default (see 606 Section 9.1 of [Semantics]), and those responses without explicit 607 freshness that have been marked as explicitly cacheable (e.g., with a 608 "public" response directive). 610 If the response has a Last-Modified header field (Section 10.2.2 of 611 [Semantics]), caches are encouraged to use a heuristic expiration 612 value that is no more than some fraction of the interval since that 613 time. A typical setting of this fraction might be 10%. 615 Note: Section 13.9 of [RFC2616] prohibited caches from calculating 616 heuristic freshness for URIs with query components (i.e., those 617 containing '?'). In practice, this has not been widely 618 implemented. Therefore, origin servers are encouraged to send 619 explicit directives (e.g., Cache-Control: no-cache) if they wish 620 to preclude caching. 622 4.2.3. Calculating Age 624 The Age header field is used to convey an estimated age of the 625 response message when obtained from a cache. The Age field value is 626 the cache's estimate of the number of seconds since the response was 627 generated or validated by the origin server. In essence, the Age 628 value is the sum of the time that the response has been resident in 629 each of the caches along the path from the origin server, plus the 630 amount of time it has been in transit along network paths. 632 The following data is used for the age calculation: 634 age_value 635 The term "age_value" denotes the value of the Age header field 636 (Section 5.1), in a form appropriate for arithmetic operation; or 637 0, if not available. 639 date_value 640 The term "date_value" denotes the value of the Date header field, 641 in a form appropriate for arithmetic operations. See 642 Section 10.1.1.2 of [Semantics] for the definition of the Date 643 header field, and for requirements regarding responses without it. 645 now 646 The term "now" means "the current value of the clock at the host 647 performing the calculation". A host ought to use NTP ([RFC5905]) 648 or some similar protocol to synchronize its clocks to Coordinated 649 Universal Time. 651 request_time 652 The current value of the clock at the host at the time the request 653 resulting in the stored response was made. 655 response_time 656 The current value of the clock at the host at the time the 657 response was received. 659 A response's age can be calculated in two entirely independent ways: 661 1. the "apparent_age": response_time minus date_value, if the local 662 clock is reasonably well synchronized to the origin server's 663 clock. If the result is negative, the result is replaced by 664 zero. 666 2. the "corrected_age_value", if all of the caches along the 667 response path implement HTTP/1.1 or greater. A cache MUST 668 interpret this value relative to the time the request was 669 initiated, not the time that the response was received. 671 apparent_age = max(0, response_time - date_value); 673 response_delay = response_time - request_time; 674 corrected_age_value = age_value + response_delay; 676 These are combined as 678 corrected_initial_age = max(apparent_age, corrected_age_value); 680 unless the cache is confident in the value of the Age header field 681 (e.g., because there are no HTTP/1.0 hops in the Via header field), 682 in which case the corrected_age_value MAY be used as the 683 corrected_initial_age. 685 The current_age of a stored response can then be calculated by adding 686 the amount of time (in seconds) since the stored response was last 687 validated by the origin server to the corrected_initial_age. 689 resident_time = now - response_time; 690 current_age = corrected_initial_age + resident_time; 692 4.2.4. Serving Stale Responses 694 A "stale" response is one that either has explicit expiry information 695 or is allowed to have heuristic expiry calculated, but is not fresh 696 according to the calculations in Section 4.2. 698 A cache MUST NOT generate a stale response if it is prohibited by an 699 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" 700 cache directive, a "must-revalidate" cache-response-directive, or an 701 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 702 see Section 5.2.2). 704 A cache MUST NOT send stale responses unless it is disconnected 705 (i.e., it cannot contact the origin server or otherwise find a 706 forward path) or doing so is explicitly allowed (e.g., by the max- 707 stale request directive; see Section 5.2.1). 709 4.3. Validation 711 When a cache has one or more stored responses for a requested URI, 712 but cannot serve any of them (e.g., because they are not fresh, or 713 one cannot be selected; see Section 4.1), it can use the conditional 714 request mechanism Section 8.2 of [Semantics] in the forwarded request 715 to give the next inbound server an opportunity to select a valid 716 stored response to use, updating the stored metadata in the process, 717 or to replace the stored response(s) with a new response. This 718 process is known as "validating" or "revalidating" the stored 719 response. 721 4.3.1. Sending a Validation Request 723 When generating a conditional request for validation, a cache starts 724 with either a request it is attempting to satisfy, or -- if it is 725 initiating the request independently -- it synthesises a request 726 using a stored response by copying the method, request-target, and 727 request header fields used for identifying the secondary cache key 728 Section 4.1. 730 It then updates that request with one or more precondition header 731 fields. These contain validator metadata sourced from stored 732 response(s) that have the same cache key (both primary and secondary, 733 as applicable). 735 The precondition header fields are then compared by recipients to 736 determine whether any stored response is equivalent to a current 737 representation of the resource. 739 One such validator is the timestamp given in a Last-Modified header 740 field (Section 10.2.2 of [Semantics]), which can be used in an If- 741 Modified-Since header field for response validation, or in an If- 742 Unmodified-Since or If-Range header field for representation 743 selection (i.e., the client is referring specifically to a previously 744 obtained representation with that timestamp). 746 Another validator is the entity-tag given in an ETag header field 747 (Section 10.2.3 of [Semantics]). One or more entity-tags, indicating 748 one or more stored responses, can be used in an If-None-Match header 749 field for response validation, or in an If-Match or If-Range header 750 field for representation selection (i.e., the client is referring 751 specifically to one or more previously obtained representations with 752 the listed entity-tags). 754 4.3.2. Handling a Received Validation Request 756 Each client in the request chain may have its own cache, so it is 757 common for a cache at an intermediary to receive conditional requests 758 from other (outbound) caches. Likewise, some user agents make use of 759 conditional requests to limit data transfers to recently modified 760 representations or to complete the transfer of a partially retrieved 761 representation. 763 If a cache receives a request that can be satisfied by reusing one of 764 its stored 200 (OK) or 206 (Partial Content) responses, the cache 765 SHOULD evaluate any applicable conditional header field preconditions 766 received in that request with respect to the corresponding validators 767 contained within the selected response. A cache MUST NOT evaluate 768 conditional header fields that are only applicable to an origin 769 server, found in a request with semantics that cannot be satisfied 770 with a cached response, or applied to a target resource for which it 771 has no stored responses; such preconditions are likely intended for 772 some other (inbound) server. 774 The proper evaluation of conditional requests by a cache depends on 775 the received precondition header fields and their precedence, as 776 defined in Section 8.2.2 of [Semantics]. The If-Match and If- 777 Unmodified-Since conditional header fields are not applicable to a 778 cache. 780 A request containing an If-None-Match header field (Section 8.2.4 of 781 [Semantics]) indicates that the client wants to validate one or more 782 of its own stored responses in comparison to whichever stored 783 response is selected by the cache. If the field-value is "*", or if 784 the field-value is a list of entity-tags and at least one of them 785 matches the entity-tag of the selected stored response, a cache 786 recipient SHOULD generate a 304 (Not Modified) response (using the 787 metadata of the selected stored response) instead of sending that 788 stored response. 790 When a cache decides to revalidate its own stored responses for a 791 request that contains an If-None-Match list of entity-tags, the cache 792 MAY combine the received list with a list of entity-tags from its own 793 stored set of responses (fresh or stale) and send the union of the 794 two lists as a replacement If-None-Match header field value in the 795 forwarded request. If a stored response contains only partial 796 content, the cache MUST NOT include its entity-tag in the union 797 unless the request is for a range that would be fully satisfied by 798 that partial stored response. If the response to the forwarded 799 request is 304 (Not Modified) and has an ETag header field value with 800 an entity-tag that is not in the client's list, the cache MUST 801 generate a 200 (OK) response for the client by reusing its 802 corresponding stored response, as updated by the 304 response 803 metadata (Section 4.3.4). 805 If an If-None-Match header field is not present, a request containing 806 an If-Modified-Since header field (Section 8.2.5 of [Semantics]) 807 indicates that the client wants to validate one or more of its own 808 stored responses by modification date. A cache recipient SHOULD 809 generate a 304 (Not Modified) response (using the metadata of the 810 selected stored response) if one of the following cases is true: 1) 811 the selected stored response has a Last-Modified field-value that is 812 earlier than or equal to the conditional timestamp; 2) no Last- 813 Modified field is present in the selected stored response, but it has 814 a Date field-value that is earlier than or equal to the conditional 815 timestamp; or, 3) neither Last-Modified nor Date is present in the 816 selected stored response, but the cache recorded it as having been 817 received at a time earlier than or equal to the conditional 818 timestamp. 820 A cache that implements partial responses to range requests, as 821 defined in Section 8.3 of [Semantics], also needs to evaluate a 822 received If-Range header field (Section 8.2.7 of [Semantics]) with 823 respect to its selected stored response. 825 4.3.3. Handling a Validation Response 827 Cache handling of a response to a conditional request is dependent 828 upon its status code: 830 o A 304 (Not Modified) response status code indicates that the 831 stored response can be updated and reused; see Section 4.3.4. 833 o A full response (i.e., one with a payload body) indicates that 834 none of the stored responses nominated in the conditional request 835 is suitable. Instead, the cache MUST use the full response to 836 satisfy the request and MAY replace the stored response(s). 838 o However, if a cache receives a 5xx (Server Error) response while 839 attempting to validate a response, it can either forward this 840 response to the requesting client, or act as if the server failed 841 to respond. In the latter case, the cache MAY send a previously 842 stored response (see Section 4.2.4). 844 4.3.4. Freshening Stored Responses upon Validation 846 When a cache receives a 304 (Not Modified) response and already has 847 one or more stored 200 (OK) responses for the applicable cache key, 848 the cache needs to identify which (if any) are to be updated by the 849 new information provided, and then do so. 851 The stored response(s) to update are identified by using the first 852 match (if any) of the following: 854 o If the new response contains a strong validator (see 855 Section 10.2.1 of [Semantics]), then that strong validator 856 identifies the selected representation for update. All of the 857 stored responses with the same strong validator are identified for 858 update. If none of the stored responses contain the same strong 859 validator, then the cache MUST NOT use the new response to update 860 any stored responses. 862 o If the new response contains a weak validator and that validator 863 corresponds to one of the cache's stored responses, then the most 864 recent of those matching stored responses is identified for 865 update. 867 o If the new response does not include any form of validator (such 868 as in the case where a client generates an If-Modified-Since 869 request from a source other than the Last-Modified response header 870 field), and there is only one stored response, and that stored 871 response also lacks a validator, then that stored response is 872 identified for update. 874 For each stored response identified for update, the cache MUST use 875 the header fields provided in the 304 (Not Modified) response to 876 replace all instances of the corresponding header fields in the 877 stored response. 879 4.3.5. Freshening Responses with HEAD 881 A response to the HEAD method is identical to what an equivalent 882 request made with a GET would have been, except it lacks a body. 883 This property of HEAD responses can be used to invalidate or update a 884 cached GET response if the more efficient conditional GET request 885 mechanism is not available (due to no validators being present in the 886 stored response) or if transmission of the representation body is not 887 desired even if it has changed. 889 When a cache makes an inbound HEAD request for a given request target 890 and receives a 200 (OK) response, the cache SHOULD update or 891 invalidate each of its stored GET responses that could have been 892 selected for that request (see Section 4.1). 894 For each of the stored responses that could have been selected, if 895 the stored response and HEAD response have matching values for any 896 received validator fields (ETag and Last-Modified) and, if the HEAD 897 response has a Content-Length header field, the value of Content- 898 Length matches that of the stored response, the cache SHOULD update 899 the stored response as described below; otherwise, the cache SHOULD 900 consider the stored response to be stale. 902 If a cache updates a stored response with the metadata provided in a 903 HEAD response, the cache MUST use the header fields provided in the 904 HEAD response to replace all instances of the corresponding header 905 fields in the stored response and append new header fields to the 906 stored response's header section unless otherwise restricted by the 907 Cache-Control header field. 909 4.4. Invalidation 911 Because unsafe request methods (Section 7.2.1 of [Semantics]) such as 912 PUT, POST or DELETE have the potential for changing state on the 913 origin server, intervening caches can use them to keep their contents 914 up to date. 916 A cache MUST invalidate the effective Request URI (Section 5.3 of 917 [Semantics]) as well as the URI(s) in the Location and Content- 918 Location response header fields (if present) when a non-error status 919 code is received in response to an unsafe request method. 921 However, a cache MUST NOT invalidate a URI from a Location or 922 Content-Location response header field if the host part of that URI 923 differs from the host part in the effective request URI (Section 5.3 924 of [Semantics]). This helps prevent denial-of-service attacks. 926 A cache MUST invalidate the effective request URI (Section 5.3 of 927 [Semantics]) when it receives a non-error response to a request with 928 a method whose safety is unknown. 930 Here, a "non-error response" is one with a 2xx (Successful) or 3xx 931 (Redirection) status code. "Invalidate" means that the cache will 932 either remove all stored responses related to the effective request 933 URI or will mark these as "invalid" and in need of a mandatory 934 validation before they can be sent in response to a subsequent 935 request. 937 Note that this does not guarantee that all appropriate responses are 938 invalidated. For example, a state-changing request might invalidate 939 responses in the caches it travels through, but relevant responses 940 still might be stored in other caches that it has not. 942 5. Header Field Definitions 944 This section defines the syntax and semantics of HTTP header fields 945 related to caching. 947 +-------------------+----------+-----------+--------------+ 948 | Header Field Name | Protocol | Status | Reference | 949 +-------------------+----------+-----------+--------------+ 950 | Age | http | standard | Section 5.1 | 951 | Cache-Control | http | standard | Section 5.2 | 952 | Expires | http | standard | Section 5.3 | 953 | Pragma | http | standard | Section 5.4 | 954 | Warning | http | obsoleted | Section 5.5 | 955 +-------------------+----------+-----------+--------------+ 957 5.1. Age 959 The "Age" header field conveys the sender's estimate of the amount of 960 time since the response was generated or successfully validated at 961 the origin server. Age values are calculated as specified in 962 Section 4.2.3. 964 Age = delta-seconds 966 The Age field-value is a non-negative integer, representing time in 967 seconds (see Section 1.3). 969 The presence of an Age header field implies that the response was not 970 generated or validated by the origin server for this request. 971 However, lack of an Age header field does not imply the origin was 972 contacted, since the response might have been received from an 973 HTTP/1.0 cache that does not implement Age. 975 5.2. Cache-Control 977 The "Cache-Control" header field is used to specify directives for 978 caches along the request/response chain. Such cache directives are 979 unidirectional in that the presence of a directive in a request does 980 not imply that the same directive is present in the response, or to 981 be repeated in it. 983 A cache MUST obey the requirements of the Cache-Control directives 984 defined in this section. See Section 5.2.3 for information about how 985 Cache-Control directives defined elsewhere are handled. 987 Note: Some HTTP/1.0 caches might not implement Cache-Control. 989 A proxy, whether or not it implements a cache, MUST pass cache 990 directives through in forwarded messages, regardless of their 991 significance to that application, since the directives might be 992 applicable to all recipients along the request/response chain. It is 993 not possible to target a directive to a specific cache. 995 Cache directives are identified by a token, to be compared case- 996 insensitively, and have an optional argument, that can use both token 997 and quoted-string syntax. For the directives defined below that 998 define arguments, recipients ought to accept both forms, even if one 999 is documented to be preferred. For any directive not defined by this 1000 specification, a recipient MUST accept both forms. 1002 Cache-Control = 1#cache-directive 1004 cache-directive = token [ "=" ( token / quoted-string ) ] 1006 For the cache directives defined below, no argument is defined (nor 1007 allowed) unless stated otherwise. 1009 +------------------------+-----------------------------------+ 1010 | Cache Directive | Reference | 1011 +------------------------+-----------------------------------+ 1012 | max-age | Section 5.2.1.1, Section 5.2.2.8 | 1013 | max-stale | Section 5.2.1.2 | 1014 | min-fresh | Section 5.2.1.3 | 1015 | must-revalidate | Section 5.2.2.1 | 1016 | no-cache | Section 5.2.1.4, Section 5.2.2.2 | 1017 | no-store | Section 5.2.1.5, Section 5.2.2.3 | 1018 | no-transform | Section 5.2.1.6, Section 5.2.2.4 | 1019 | only-if-cached | Section 5.2.1.7 | 1020 | private | Section 5.2.2.6 | 1021 | proxy-revalidate | Section 5.2.2.7 | 1022 | public | Section 5.2.2.5 | 1023 | s-maxage | Section 5.2.2.9 | 1024 | stale-if-error | [RFC5861], Section 4 | 1025 | stale-while-revalidate | [RFC5861], Section 3 | 1026 +------------------------+-----------------------------------+ 1028 5.2.1. Request Cache-Control Directives 1030 5.2.1.1. max-age 1032 Argument syntax: 1034 delta-seconds (see Section 1.3) 1036 The "max-age" request directive indicates that the client is 1037 unwilling to accept a response whose age is greater than the 1038 specified number of seconds. Unless the max-stale request directive 1039 is also present, the client is not willing to accept a stale 1040 response. 1042 This directive uses the token form of the argument syntax: e.g., 1043 'max-age=5' not 'max-age="5"'. A sender SHOULD NOT generate the 1044 quoted-string form. 1046 5.2.1.2. max-stale 1048 Argument syntax: 1050 delta-seconds (see Section 1.3) 1052 The "max-stale" request directive indicates that the client is 1053 willing to accept a response that has exceeded its freshness 1054 lifetime. If max-stale is assigned a value, then the client is 1055 willing to accept a response that has exceeded its freshness lifetime 1056 by no more than the specified number of seconds. If no value is 1057 assigned to max-stale, then the client is willing to accept a stale 1058 response of any age. 1060 This directive uses the token form of the argument syntax: e.g., 1061 'max-stale=10' not 'max-stale="10"'. A sender SHOULD NOT generate 1062 the quoted-string form. 1064 5.2.1.3. min-fresh 1066 Argument syntax: 1068 delta-seconds (see Section 1.3) 1070 The "min-fresh" request directive indicates that the client is 1071 willing to accept a response whose freshness lifetime is no less than 1072 its current age plus the specified time in seconds. That is, the 1073 client wants a response that will still be fresh for at least the 1074 specified number of seconds. 1076 This directive uses the token form of the argument syntax: e.g., 1077 'min-fresh=20' not 'min-fresh="20"'. A sender SHOULD NOT generate 1078 the quoted-string form. 1080 5.2.1.4. no-cache 1082 The "no-cache" request directive indicates that a cache MUST NOT use 1083 a stored response to satisfy the request without successful 1084 validation on the origin server. 1086 5.2.1.5. no-store 1088 The "no-store" request directive indicates that a cache MUST NOT 1089 store any part of either this request or any response to it. This 1090 directive applies to both private and shared caches. "MUST NOT 1091 store" in this context means that the cache MUST NOT intentionally 1092 store the information in non-volatile storage, and MUST make a best- 1093 effort attempt to remove the information from volatile storage as 1094 promptly as possible after forwarding it. 1096 This directive is NOT a reliable or sufficient mechanism for ensuring 1097 privacy. In particular, malicious or compromised caches might not 1098 recognize or obey this directive, and communications networks might 1099 be vulnerable to eavesdropping. 1101 Note that if a request containing this directive is satisfied from a 1102 cache, the no-store request directive does not apply to the already 1103 stored response. 1105 5.2.1.6. no-transform 1107 The "no-transform" request directive indicates that an intermediary 1108 (whether or not it implements a cache) MUST NOT transform the 1109 payload, as defined in Section 5.5.2 of [Semantics]. 1111 5.2.1.7. only-if-cached 1113 The "only-if-cached" request directive indicates that the client only 1114 wishes to obtain a stored response. If it receives this directive, a 1115 cache SHOULD either respond using a stored response that is 1116 consistent with the other constraints of the request, or respond with 1117 a 504 (Gateway Timeout) status code. If a group of caches is being 1118 operated as a unified system with good internal connectivity, a 1119 member cache MAY forward such a request within that group of caches. 1121 5.2.2. Response Cache-Control Directives 1123 5.2.2.1. must-revalidate 1125 The "must-revalidate" response directive indicates that once it has 1126 become stale, the response MUST NOT be used to satisfy any other 1127 request without forwarding it for validation and receiving a 1128 successful response; see Section 4.3. 1130 The must-revalidate directive is necessary to support reliable 1131 operation for certain protocol features. In all circumstances a 1132 cache MUST obey the must-revalidate directive; in particular, if a 1133 cache cannot reach the origin server for any reason, it MUST generate 1134 a 504 (Gateway Timeout) response. 1136 The must-revalidate directive ought to be used by servers if and only 1137 if failure to validate a request on the representation could result 1138 in incorrect operation, such as a silently unexecuted financial 1139 transaction. 1141 5.2.2.2. no-cache 1143 Argument syntax: 1145 #field-name 1147 The "no-cache" response directive indicates that the response MUST 1148 NOT be used to satisfy any other request without forwarding it for 1149 validation and receiving a successful response; see Section 4.3. 1151 This allows an origin server to prevent a cache from using it to 1152 satisfy a request without contacting it, even by caches that have 1153 been configured to send stale responses. 1155 If the no-cache response directive specifies one or more field-names, 1156 then a cache MAY use the response to satisfy a subsequent request, 1157 subject to any other restrictions on caching. However, any header 1158 fields in the response that have the field-name(s) listed MUST NOT be 1159 sent in the response to a subsequent request without successful 1160 revalidation with the origin server. This allows an origin server to 1161 prevent the re-use of certain header fields in a response, while 1162 still allowing caching of the rest of the response. 1164 The field-names given are not limited to the set of header fields 1165 defined by this specification. Field names are case-insensitive. 1167 This directive uses the quoted-string form of the argument syntax. A 1168 sender SHOULD NOT generate the token form (even if quoting appears 1169 not to be needed for single-entry lists). 1171 Note: Although it has been back-ported to many implementations, some 1172 HTTP/1.0 caches will not recognize or obey this directive. Also, no- 1173 cache response directives with field-names are often handled by 1174 caches as if an unqualified no-cache directive was received; i.e., 1175 the special handling for the qualified form is not widely 1176 implemented. 1178 5.2.2.3. no-store 1180 The "no-store" response directive indicates that a cache MUST NOT 1181 store any part of either the immediate request or response, and MUST 1182 NOT use the response to satisfy any other request. 1184 This directive applies to both private and shared caches. "MUST NOT 1185 store" in this context means that the cache MUST NOT intentionally 1186 store the information in non-volatile storage, and MUST make a best- 1187 effort attempt to remove the information from volatile storage as 1188 promptly as possible after forwarding it. 1190 This directive is NOT a reliable or sufficient mechanism for ensuring 1191 privacy. In particular, malicious or compromised caches might not 1192 recognize or obey this directive, and communications networks might 1193 be vulnerable to eavesdropping. 1195 5.2.2.4. no-transform 1197 The "no-transform" response directive indicates that an intermediary 1198 (regardless of whether it implements a cache) MUST NOT transform the 1199 payload, as defined in Section 5.5.2 of [Semantics]. 1201 5.2.2.5. public 1203 The "public" response directive indicates that any cache MAY store 1204 the response, even if the response would normally be non-cacheable or 1205 cacheable only within a private cache. (See Section 3.2 for 1206 additional details related to the use of public in response to a 1207 request containing Authorization, and Section 3 for details of how 1208 public affects responses that would normally not be stored, due to 1209 their status codes not being defined as cacheable by default; see 1210 Section 4.2.2.) 1212 5.2.2.6. private 1214 Argument syntax: 1216 #field-name 1218 The "private" response directive indicates that the response message 1219 is intended for a single user and MUST NOT be stored by a shared 1220 cache. A private cache MAY store the response and reuse it for later 1221 requests, even if the response would normally be non-cacheable. 1223 If the private response directive specifies one or more field-names, 1224 this requirement is limited to the field-values associated with the 1225 listed response header fields. That is, a shared cache MUST NOT 1226 store the specified field-names(s), whereas it MAY store the 1227 remainder of the response message. 1229 The field-names given are not limited to the set of header fields 1230 defined by this specification. Field names are case-insensitive. 1232 This directive uses the quoted-string form of the argument syntax. A 1233 sender SHOULD NOT generate the token form (even if quoting appears 1234 not to be needed for single-entry lists). 1236 Note: This usage of the word "private" only controls where the 1237 response can be stored; it cannot ensure the privacy of the message 1238 content. Also, private response directives with field-names are 1239 often handled by caches as if an unqualified private directive was 1240 received; i.e., the special handling for the qualified form is not 1241 widely implemented. 1243 5.2.2.7. proxy-revalidate 1245 The "proxy-revalidate" response directive has the same meaning as the 1246 must-revalidate response directive, except that it does not apply to 1247 private caches. 1249 5.2.2.8. max-age 1251 Argument syntax: 1253 delta-seconds (see Section 1.3) 1255 The "max-age" response directive indicates that the response is to be 1256 considered stale after its age is greater than the specified number 1257 of seconds. 1259 This directive uses the token form of the argument syntax: e.g., 1260 'max-age=5' not 'max-age="5"'. A sender SHOULD NOT generate the 1261 quoted-string form. 1263 5.2.2.9. s-maxage 1265 Argument syntax: 1267 delta-seconds (see Section 1.3) 1269 The "s-maxage" response directive indicates that, in shared caches, 1270 the maximum age specified by this directive overrides the maximum age 1271 specified by either the max-age directive or the Expires header 1272 field. The s-maxage directive also implies the semantics of the 1273 proxy-revalidate response directive. 1275 This directive uses the token form of the argument syntax: e.g., 1276 's-maxage=10' not 's-maxage="10"'. A sender SHOULD NOT generate the 1277 quoted-string form. 1279 5.2.3. Cache Control Extensions 1281 The Cache-Control header field can be extended through the use of one 1282 or more cache-extension tokens, each with an optional value. A cache 1283 MUST ignore unrecognized cache directives. 1285 Informational extensions (those that do not require a change in cache 1286 behavior) can be added without changing the semantics of other 1287 directives. 1289 Behavioral extensions are designed to work by acting as modifiers to 1290 the existing base of cache directives. Both the new directive and 1291 the old directive are supplied, such that applications that do not 1292 understand the new directive will default to the behavior specified 1293 by the old directive, and those that understand the new directive 1294 will recognize it as modifying the requirements associated with the 1295 old directive. In this way, extensions to the existing cache-control 1296 directives can be made without breaking deployed caches. 1298 For example, consider a hypothetical new response directive called 1299 "community" that acts as a modifier to the private directive: in 1300 addition to private caches, any cache that is shared only by members 1301 of the named community is allowed to cache the response. An origin 1302 server wishing to allow the UCI community to use an otherwise private 1303 response in their shared cache(s) could do so by including 1305 Cache-Control: private, community="UCI" 1307 A cache that recognizes such a community cache-extension could 1308 broaden its behavior in accordance with that extension. A cache that 1309 does not recognize the community cache-extension would ignore it and 1310 adhere to the private directive. 1312 New extension directives ought to consider defining: 1314 o What it means for a directive to be specified multiple times, 1316 o When the directive does not take an argument, what it means when 1317 an argument is present, 1319 o When the directive requires an argument, what it means when it is 1320 missing, 1322 o Whether the directive is specific to requests, responses, or able 1323 to be used in either. 1325 5.2.4. Cache Directive Registry 1327 The "Hypertext Transfer Protocol (HTTP) Cache Directive Registry" 1328 defines the namespace for the cache directives. It has been created 1329 and is now maintained at . 1332 A registration MUST include the following fields: 1334 o Cache Directive Name 1336 o Pointer to specification text 1337 Values to be added to this namespace require IETF Review (see 1338 [RFC8126], Section 4.8). 1340 5.3. Expires 1342 The "Expires" header field gives the date/time after which the 1343 response is considered stale. See Section 4.2 for further discussion 1344 of the freshness model. 1346 The presence of an Expires field does not imply that the original 1347 resource will change or cease to exist at, before, or after that 1348 time. 1350 The Expires value is an HTTP-date timestamp, as defined in 1351 Section 10.1.1.1 of [Semantics]. 1353 Expires = HTTP-date 1355 For example 1357 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1359 A cache recipient MUST interpret invalid date formats, especially the 1360 value "0", as representing a time in the past (i.e., "already 1361 expired"). 1363 If a response includes a Cache-Control field with the max-age 1364 directive (Section 5.2.2.8), a recipient MUST ignore the Expires 1365 field. Likewise, if a response includes the s-maxage directive 1366 (Section 5.2.2.9), a shared cache recipient MUST ignore the Expires 1367 field. In both these cases, the value in Expires is only intended 1368 for recipients that have not yet implemented the Cache-Control field. 1370 An origin server without a clock MUST NOT generate an Expires field 1371 unless its value represents a fixed time in the past (always expired) 1372 or its value has been associated with the resource by a system or 1373 user with a reliable clock. 1375 Historically, HTTP required the Expires field-value to be no more 1376 than a year in the future. While longer freshness lifetimes are no 1377 longer prohibited, extremely large values have been demonstrated to 1378 cause problems (e.g., clock overflows due to use of 32-bit integers 1379 for time values), and many caches will evict a response far sooner 1380 than that. 1382 5.4. Pragma 1384 The "Pragma" header field allows backwards compatibility with 1385 HTTP/1.0 caches, so that clients can specify a "no-cache" request 1386 that they will understand (as Cache-Control was not defined until 1387 HTTP/1.1). When the Cache-Control header field is also present and 1388 understood in a request, Pragma is ignored. 1390 In HTTP/1.0, Pragma was defined as an extensible field for 1391 implementation-specified directives for recipients. This 1392 specification deprecates such extensions to improve interoperability. 1394 Pragma = 1#pragma-directive 1395 pragma-directive = "no-cache" / extension-pragma 1396 extension-pragma = token [ "=" ( token / quoted-string ) ] 1398 When the Cache-Control header field is not present in a request, 1399 caches MUST consider the no-cache request pragma-directive as having 1400 the same effect as if "Cache-Control: no-cache" were present (see 1401 Section 5.2.1). 1403 When sending a no-cache request, a client ought to include both the 1404 pragma and cache-control directives, unless Cache-Control: no-cache 1405 is purposefully omitted to target other Cache-Control request 1406 directives at HTTP/1.1 or greater caches. For example: 1408 GET / HTTP/1.1 1409 Host: www.example.com 1410 Cache-Control: max-age=30 1411 Pragma: no-cache 1413 will constrain HTTP/1.1 and greater caches to serve a response no 1414 older than 30 seconds, while precluding implementations that do not 1415 understand Cache-Control from serving a cached response. 1417 Note: Because the meaning of "Pragma: no-cache" in responses is 1418 not specified, it does not provide a reliable replacement for 1419 "Cache-Control: no-cache" in them. 1421 5.5. Warning 1423 The "Warning" header field was used to carry additional information 1424 about the status or transformation of a message that might not be 1425 reflected in the status code. This specification obsoletes it, as it 1426 is not widely generated or surfaced to users. The information it 1427 carried can be gleaned from examining other header fields, such as 1428 Age. 1430 6. Relationship to Applications 1432 Applications using HTTP often specify additional forms of caching. 1433 For example, Web browsers often have history mechanisms such as 1434 "Back" buttons that can be used to redisplay a representation 1435 retrieved earlier in a session. 1437 Likewise, some Web browsers implement caching of images and other 1438 assets within a page view; they may or may not honor HTTP caching 1439 semantics. 1441 The requirements in this specification do not necessarily apply to 1442 how applications use data after it is retrieved from a HTTP cache. 1443 That is, a history mechanism can display a previous representation 1444 even if it has expired, and an application can use cached data in 1445 other ways beyond its freshness lifetime. 1447 This does not prohibit the application from taking HTTP caching into 1448 account; for example, a history mechanism might tell the user that a 1449 view is stale, or it might honor cache directives (e.g., Cache- 1450 Control: no-store). 1452 7. Security Considerations 1454 This section is meant to inform developers, information providers, 1455 and users of known security concerns specific to HTTP caching. More 1456 general security considerations are addressed in HTTP messaging 1457 [Messaging] and semantics [Semantics]. 1459 Caches expose additional potential vulnerabilities, since the 1460 contents of the cache represent an attractive target for malicious 1461 exploitation. Because cache contents persist after an HTTP request 1462 is complete, an attack on the cache can reveal information long after 1463 a user believes that the information has been removed from the 1464 network. Therefore, cache contents need to be protected as sensitive 1465 information. 1467 In particular, various attacks might be amplified by being stored in 1468 a shared cache; such "cache poisoning" attacks use the cache to 1469 distribute a malicious payload to many clients, and are especially 1470 effective when an attacker can use implementation flaws, elevated 1471 privileges, or other techniques to insert such a response into a 1472 cache. One common attack vector for cache poisoning is to exploit 1473 differences in message parsing on proxies and in user agents; see 1474 Section 6.3 of [Messaging] for the relevant requirements. 1476 Likewise, implementation flaws (as well as misunderstanding of cache 1477 operation) might lead to caching of sensitive information (e.g., 1478 authentication credentials) that is thought to be private, exposing 1479 it to unauthorized parties. 1481 Furthermore, the very use of a cache can bring about privacy 1482 concerns. For example, if two users share a cache, and the first one 1483 browses to a site, the second may be able to detect that the other 1484 has been to that site, because the resources from it load more 1485 quickly, thanks to the cache. 1487 Note that the Set-Cookie response header field [RFC6265] does not 1488 inhibit caching; a cacheable response with a Set-Cookie header field 1489 can be (and often is) used to satisfy subsequent requests to caches. 1490 Servers who wish to control caching of these responses are encouraged 1491 to emit appropriate Cache-Control response header fields. 1493 8. IANA Considerations 1495 The change controller for the following registrations is: "IETF 1496 (iesg@ietf.org) - Internet Engineering Task Force". 1498 8.1. Header Field Registration 1500 Please update the "Message Headers" registry of "Permanent Message 1501 Header Field Names" at with the header field names listed in the table of 1503 Section 5. 1505 8.2. Cache Directive Registration 1507 Please update the "Hypertext Transfer Protocol (HTTP) Cache Directive 1508 Registry" at 1509 with the registration procedure of Section 5.2.4 and the cache 1510 directive names summarized in the table of Section 5.2. 1512 8.3. Warn Code Registry 1514 Please add a note to the "Hypertext Transfer Protocol (HTTP) Warn 1515 Codes" registry at 1516 to the effect that Warning is obsoleted. 1518 9. References 1520 9.1. Normative References 1522 [Messaging] 1523 Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 1524 Ed., "HTTP/1.1 Messaging", draft-ietf-httpbis-messaging-03 1525 (work in progress), October 2018. 1527 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1528 Requirement Levels", BCP 14, RFC 2119, 1529 DOI 10.17487/RFC2119, March 1997, 1530 . 1532 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1533 Resource Identifier (URI): Generic Syntax", STD 66, 1534 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1535 . 1537 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1538 Specifications: ABNF", STD 68, RFC 5234, 1539 DOI 10.17487/RFC5234, January 2008, 1540 . 1542 [Semantics] 1543 Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 1544 Ed., "HTTP Semantics", draft-ietf-httpbis-semantics-03 1545 (work in progress), October 2018. 1547 [USASCII] American National Standards Institute, "Coded Character 1548 Set -- 7-bit American Standard Code for Information 1549 Interchange", ANSI X3.4, 1986. 1551 9.2. Informative References 1553 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1554 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1555 Transfer Protocol -- HTTP/1.1", RFC 2616, 1556 DOI 10.17487/RFC2616, June 1999, 1557 . 1559 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1560 Content", RFC 5861, DOI 10.17487/RFC5861, April 2010, 1561 . 1563 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 1564 "Network Time Protocol Version 4: Protocol and Algorithms 1565 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 1566 . 1568 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1569 DOI 10.17487/RFC6265, April 2011, 1570 . 1572 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 1573 Ed., "Hypertext Transfer Protocol (HTTP): Caching", 1574 RFC 7234, DOI 10.17487/RFC7234, June 2014, 1575 . 1577 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1578 Writing an IANA Considerations Section in RFCs", BCP 26, 1579 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1580 . 1582 Appendix A. Collected ABNF 1584 In the collected ABNF below, list rules are expanded as per 1585 Section 11 of [Semantics]. 1587 Age = delta-seconds 1589 Cache-Control = *( "," OWS ) cache-directive *( OWS "," [ OWS 1590 cache-directive ] ) 1592 Expires = HTTP-date 1594 HTTP-date = 1596 OWS = 1598 Pragma = *( "," OWS ) pragma-directive *( OWS "," [ OWS 1599 pragma-directive ] ) 1601 cache-directive = token [ "=" ( token / quoted-string ) ] 1603 delta-seconds = 1*DIGIT 1605 extension-pragma = token [ "=" ( token / quoted-string ) ] 1607 field-name = 1609 port = 1610 pragma-directive = "no-cache" / extension-pragma 1611 pseudonym = 1613 quoted-string = 1615 token = 1617 uri-host = 1619 Appendix B. Changes from RFC 7234 1621 The Warning response header was obsoleted. Much of the information 1622 supported by Warning could be gleaned by examining the response), and 1623 the remaining warn-codes -- although potentially useful -- were 1624 entirely advisory, and in practice were not added by caches or 1625 intermediaries. (Section 5.5) 1627 Appendix C. Change Log 1629 This section is to be removed before publishing as an RFC. 1631 C.1. Between RFC7234 and draft 00 1633 The changes were purely editorial: 1635 o Change boilerplate and abstract to indicate the "draft" status, 1636 and update references to ancestor specifications. 1638 o Remove version "1.1" from document title, indicating that this 1639 specification applies to all HTTP versions. 1641 o Adjust historical notes. 1643 o Update links to sibling specifications. 1645 o Replace sections listing changes from RFC 2616 by new empty 1646 sections referring to RFC 723x. 1648 o Remove acknowledgements specific to RFC 723x. 1650 o Move "Acknowledgements" to the very end and make them unnumbered. 1652 C.2. Since draft-ietf-httpbis-cache-00 1654 The changes are purely editorial: 1656 o Moved all extensibility tips, registration procedures, and 1657 registry tables from the IANA considerations to normative 1658 sections, reducing the IANA considerations to just instructions 1659 that will be removed prior to publication as an RFC. 1661 C.3. Since draft-ietf-httpbis-cache-01 1663 o Cite RFC 8126 instead of RFC 5226 () 1666 o In Section 5.4, misleading statement about the relation between 1667 Pragma and Cache-Control (, ) 1670 C.4. Since draft-ietf-httpbis-cache-02 1672 o In Section 3, explain that only final responses are cacheable 1673 () 1675 o In Section 5.2.2, clarify what responses various directives apply 1676 to () 1678 o In Section 4.3.1, clarify the source of validators in conditional 1679 requests () 1681 o Revise Section 6 to apply to more than just History Lists 1682 () 1684 o In Section 5.5, deprecated "Warning" header field 1685 () 1687 o In Section 3.2, remove a spurious note 1688 () 1690 Index 1692 A 1693 Age header field 21 1694 age 11 1696 C 1697 Cache-Control header field 21 1698 cache 4 1699 cache entry 6 1700 cache key 6 1702 E 1703 Expires header field 29 1704 explicit expiration time 11 1706 F 1707 fresh 11 1708 freshness lifetime 11 1710 G 1711 Grammar 1712 Age 21 1713 ALPHA 5 1714 Cache-Control 21 1715 cache-directive 21 1716 CR 5 1717 CRLF 5 1718 CTL 5 1719 delta-seconds 5 1720 DIGIT 5 1721 DQUOTE 5 1722 Expires 29 1723 extension-pragma 30 1724 HEXDIG 5 1725 HTAB 5 1726 LF 5 1727 OCTET 5 1728 Pragma 30 1729 pragma-directive 30 1730 SP 5 1731 VCHAR 5 1733 H 1734 heuristic expiration time 11 1736 M 1737 max-age (cache directive) 22, 27 1738 max-stale (cache directive) 22 1739 min-fresh (cache directive) 23 1740 must-revalidate (cache directive) 24 1742 N 1743 no-cache (cache directive) 23-24 1744 no-store (cache directive) 23, 25 1745 no-transform (cache directive) 24, 26 1747 O 1748 only-if-cached (cache directive) 24 1750 P 1751 Pragma header field 30 1752 private (cache directive) 26 1753 private cache 4 1754 proxy-revalidate (cache directive) 27 1755 public (cache directive) 26 1757 S 1758 s-maxage (cache directive) 27 1759 shared cache 4 1760 stale 11 1761 strong validator 18 1763 V 1764 validator 16 1766 W 1767 Warning header field 30 1769 Acknowledgments 1771 See Appendix "Acknowledgments" of [Semantics]. 1773 Authors' Addresses 1775 Roy T. Fielding (editor) 1776 Adobe 1777 345 Park Ave 1778 San Jose, CA 95110 1779 USA 1781 EMail: fielding@gbiv.com 1782 URI: https://roy.gbiv.com/ 1784 Mark Nottingham (editor) 1785 Fastly 1787 EMail: mnot@mnot.net 1788 URI: https://www.mnot.net/ 1790 Julian F. Reschke (editor) 1791 greenbytes GmbH 1792 Hafenweg 16 1793 Muenster, NW 48155 1794 Germany 1796 EMail: julian.reschke@greenbytes.de 1797 URI: https://greenbytes.de/tech/webdav/