idnits 2.17.1 draft-ietf-httpbis-cache-18.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: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. 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 (18 August 2021) is 981 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: 'RFC7234' is defined on line 1790, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-18 -- Possible downref: Normative reference to a draft: ref. 'HTTP' -- 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 7234 (Obsoleted by RFC 9111) Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 5 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: 19 February 2022 J. Reschke, Ed. 7 greenbytes 8 18 August 2021 10 HTTP Caching 11 draft-ietf-httpbis-cache-18 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.19. 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 19 February 2022. 54 Copyright Notice 56 Copyright (c) 2021 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 (https://trustee.ietf.org/ 61 license-info) in effect on the date of publication of this document. 62 Please review these documents carefully, as they describe your rights 63 and restrictions with respect to this document. Code Components 64 extracted from this document must include Simplified BSD License text 65 as described in Section 4.e of the Trust Legal Provisions and are 66 provided without warranty as described in the Simplified BSD License. 68 This document may contain material from IETF Documents or IETF 69 Contributions published or made publicly available before November 70 10, 2008. The person(s) controlling the copyright in some of this 71 material may not have granted the IETF Trust the right to allow 72 modifications of such material outside the IETF Standards Process. 73 Without obtaining an adequate license from the person(s) controlling 74 the copyright in such materials, this document may not be modified 75 outside the IETF Standards Process, and derivative works of it may 76 not be created outside the IETF Standards Process, except to format 77 it for publication as an RFC or to translate it into languages other 78 than English. 80 Table of Contents 82 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 83 1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5 84 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5 85 1.2.1. Imported Rules . . . . . . . . . . . . . . . . . . . 5 86 1.2.2. Delta Seconds . . . . . . . . . . . . . . . . . . . . 6 87 2. Overview of Cache Operation . . . . . . . . . . . . . . . . . 6 88 3. Storing Responses in Caches . . . . . . . . . . . . . . . . . 7 89 3.1. Storing Header and Trailer Fields . . . . . . . . . . . . 8 90 3.2. Updating Stored Header Fields . . . . . . . . . . . . . . 9 91 3.3. Storing Incomplete Responses . . . . . . . . . . . . . . 10 92 3.4. Combining Partial Content . . . . . . . . . . . . . . . . 11 93 3.5. Storing Responses to Authenticated Requests . . . . . . . 11 94 4. Constructing Responses from Caches . . . . . . . . . . . . . 11 95 4.1. Calculating Cache Keys with the Vary Header Field . . . . 13 96 4.2. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 14 97 4.2.1. Calculating Freshness Lifetime . . . . . . . . . . . 15 98 4.2.2. Calculating Heuristic Freshness . . . . . . . . . . . 16 99 4.2.3. Calculating Age . . . . . . . . . . . . . . . . . . . 17 100 4.2.4. Serving Stale Responses . . . . . . . . . . . . . . . 18 101 4.3. Validation . . . . . . . . . . . . . . . . . . . . . . . 18 102 4.3.1. Sending a Validation Request . . . . . . . . . . . . 19 103 4.3.2. Handling a Received Validation Request . . . . . . . 20 104 4.3.3. Handling a Validation Response . . . . . . . . . . . 21 105 4.3.4. Freshening Stored Responses upon Validation . . . . . 21 106 4.3.5. Freshening Responses with HEAD . . . . . . . . . . . 22 107 4.4. Invalidating Stored Responses . . . . . . . . . . . . . . 23 108 5. Field Definitions . . . . . . . . . . . . . . . . . . . . . . 24 109 5.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 110 5.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 24 111 5.2.1. Request Cache-Control Directives . . . . . . . . . . 25 112 5.2.1.1. max-age . . . . . . . . . . . . . . . . . . . . . 25 113 5.2.1.2. max-stale . . . . . . . . . . . . . . . . . . . . 25 114 5.2.1.3. min-fresh . . . . . . . . . . . . . . . . . . . . 26 115 5.2.1.4. no-cache . . . . . . . . . . . . . . . . . . . . 26 116 5.2.1.5. no-store . . . . . . . . . . . . . . . . . . . . 26 117 5.2.1.6. no-transform . . . . . . . . . . . . . . . . . . 27 118 5.2.1.7. only-if-cached . . . . . . . . . . . . . . . . . 27 119 5.2.2. Response Cache-Control Directives . . . . . . . . . . 27 120 5.2.2.1. max-age . . . . . . . . . . . . . . . . . . . . . 27 121 5.2.2.2. must-revalidate . . . . . . . . . . . . . . . . . 27 122 5.2.2.3. must-understand . . . . . . . . . . . . . . . . . 28 123 5.2.2.4. no-cache . . . . . . . . . . . . . . . . . . . . 28 124 5.2.2.5. no-store . . . . . . . . . . . . . . . . . . . . 29 125 5.2.2.6. no-transform . . . . . . . . . . . . . . . . . . 29 126 5.2.2.7. private . . . . . . . . . . . . . . . . . . . . . 29 127 5.2.2.8. proxy-revalidate . . . . . . . . . . . . . . . . 30 128 5.2.2.9. public . . . . . . . . . . . . . . . . . . . . . 30 129 5.2.2.10. s-maxage . . . . . . . . . . . . . . . . . . . . 31 130 5.2.3. Cache Control Extensions . . . . . . . . . . . . . . 31 131 5.2.4. Cache Directive Registry . . . . . . . . . . . . . . 32 132 5.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 32 133 5.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . 33 134 5.5. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 34 135 6. Relationship to Applications and Other Caches . . . . . . . . 34 136 7. Security Considerations . . . . . . . . . . . . . . . . . . . 35 137 7.1. Cache Poisoning . . . . . . . . . . . . . . . . . . . . . 35 138 7.2. Timing Attacks . . . . . . . . . . . . . . . . . . . . . 35 139 7.3. Caching of Sensitive Information . . . . . . . . . . . . 36 140 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 141 8.1. Field Name Registration . . . . . . . . . . . . . . . . . 36 142 8.2. Cache Directive Registration . . . . . . . . . . . . . . 37 143 8.3. Warn Code Registry . . . . . . . . . . . . . . . . . . . 37 144 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 145 9.1. Normative References . . . . . . . . . . . . . . . . . . 37 146 9.2. Informative References . . . . . . . . . . . . . . . . . 38 147 Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 39 148 Appendix B. Changes from RFC 7234 . . . . . . . . . . . . . . . 39 149 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 40 150 C.1. Between RFC7234 and draft 00 . . . . . . . . . . . . . . 40 151 C.2. Since draft-ietf-httpbis-cache-00 . . . . . . . . . . . . 41 152 C.3. Since draft-ietf-httpbis-cache-01 . . . . . . . . . . . . 41 153 C.4. Since draft-ietf-httpbis-cache-02 . . . . . . . . . . . . 41 154 C.5. Since draft-ietf-httpbis-cache-03 . . . . . . . . . . . . 41 155 C.6. Since draft-ietf-httpbis-cache-04 . . . . . . . . . . . . 42 156 C.7. Since draft-ietf-httpbis-cache-05 . . . . . . . . . . . . 42 157 C.8. Since draft-ietf-httpbis-cache-06 . . . . . . . . . . . . 42 158 C.9. Since draft-ietf-httpbis-cache-07 . . . . . . . . . . . . 43 159 C.10. Since draft-ietf-httpbis-cache-08 . . . . . . . . . . . . 43 160 C.11. Since draft-ietf-httpbis-cache-09 . . . . . . . . . . . . 43 161 C.12. Since draft-ietf-httpbis-cache-10 . . . . . . . . . . . . 43 162 C.13. Since draft-ietf-httpbis-cache-11 . . . . . . . . . . . . 44 163 C.14. Since draft-ietf-httpbis-cache-12 . . . . . . . . . . . . 44 164 C.15. Since draft-ietf-httpbis-cache-13 . . . . . . . . . . . . 45 165 C.16. Since draft-ietf-httpbis-cache-14 . . . . . . . . . . . . 45 166 C.17. Since draft-ietf-httpbis-cache-15 . . . . . . . . . . . . 46 167 C.18. Since draft-ietf-httpbis-cache-16 . . . . . . . . . . . . 46 168 C.19. Since draft-ietf-httpbis-cache-17 . . . . . . . . . . . . 46 169 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 46 170 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 171 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 173 1. Introduction 175 The Hypertext Transfer Protocol (HTTP) is a stateless application- 176 level request/response protocol that uses extensible semantics and 177 self-descriptive messages for flexible interaction with network-based 178 hypertext information systems. It is typically used for distributed 179 information systems, where the use of response caches can improve 180 performance. This document defines aspects of HTTP related to 181 caching and reusing response messages. 183 An HTTP _cache_ is a local store of response messages and the 184 subsystem that controls storage, retrieval, and deletion of messages 185 in it. A cache stores cacheable responses to reduce the response 186 time and network bandwidth consumption on future equivalent requests. 187 Any client or server MAY use a cache, though not when acting as a 188 tunnel (Section 3.7 of [HTTP]). 190 A _shared cache_ is a cache that stores responses for reuse by more 191 than one user; shared caches are usually (but not always) deployed as 192 a part of an intermediary. A _private cache_, in contrast, is 193 dedicated to a single user; often, they are deployed as a component 194 of a user agent. 196 The goal of HTTP caching is significantly improving performance by 197 reusing a prior response message to satisfy a current request. A 198 cache considers a stored response "fresh", as defined in Section 4.2, 199 if it can be reused without "validation" (checking with the origin 200 server to see if the cached response remains valid for this request). 201 A fresh response can therefore reduce both latency and network 202 overhead each time the cache reuses it. When a cached response is 203 not fresh, it might still be reusable if validation can freshen it 204 (Section 4.3) or if the origin is unavailable (Section 4.2.4). 206 This document obsoletes RFC 7234, with the changes being summarized 207 in Appendix B. 209 1.1. Requirements Notation 211 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 212 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 213 "OPTIONAL" in this document are to be interpreted as described in BCP 214 14 [RFC2119] [RFC8174] when, and only when, they appear in all 215 capitals, as shown here. 217 Section 2 of [HTTP] defines conformance criteria and contains 218 considerations regarding error handling. 220 1.2. Syntax Notation 222 This specification uses the Augmented Backus-Naur Form (ABNF) 223 notation of [RFC5234], extended with the notation for case- 224 sensitivity in strings defined in [RFC7405]. 226 It also uses a list extension, defined in Section 5.6.1 of [HTTP], 227 that allows for compact definition of comma-separated lists using a 228 '#' operator (similar to how the '*' operator indicates repetition). 229 Appendix A shows the collected grammar with all list operators 230 expanded to standard ABNF notation. 232 1.2.1. Imported Rules 234 The following core rule is included by reference, as defined in 235 [RFC5234], Appendix B.1: DIGIT (decimal 0-9). 237 [HTTP] defines the following rules: 239 HTTP-date = 240 OWS = 241 field-name = 242 quoted-string = 243 token = 245 1.2.2. Delta Seconds 247 The delta-seconds rule specifies a non-negative integer, representing 248 time in seconds. 250 delta-seconds = 1*DIGIT 252 A recipient parsing a delta-seconds value and converting it to binary 253 form ought to use an arithmetic type of at least 31 bits of non- 254 negative integer range. If a cache receives a delta-seconds value 255 greater than the greatest integer it can represent, or if any of its 256 subsequent calculations overflows, the cache MUST consider the value 257 to be 2147483648 (2^31) or the greatest positive integer it can 258 conveniently represent. 260 | *Note:* The value 2147483648 is here for historical reasons, 261 | represents infinity (over 68 years), and does not need to be 262 | stored in binary form; an implementation could produce it as a 263 | string if any overflow occurs, even if the calculations are 264 | performed with an arithmetic type incapable of directly 265 | representing that number. What matters here is that an 266 | overflow be detected and not treated as a negative value in 267 | later calculations. 269 2. Overview of Cache Operation 271 Proper cache operation preserves the semantics of HTTP transfers 272 while reducing the transmission of information already held in the 273 cache. See Section 3 of [HTTP] for the general terminology and core 274 concepts of HTTP. 276 Although caching is an entirely OPTIONAL feature of HTTP, it can be 277 assumed that reusing a cached response is desirable and that such 278 reuse is the default behavior when no requirement or local 279 configuration prevents it. Therefore, HTTP cache requirements are 280 focused on preventing a cache from either storing a non-reusable 281 response or reusing a stored response inappropriately, rather than 282 mandating that caches always store and reuse particular responses. 284 The _cache key_ is the information a cache uses to choose a response 285 and is composed from, at a minimum, the request method and target URI 286 used to retrieve the stored response; the method determines under 287 which circumstances that response can be used to satisfy a subsequent 288 request. However, many HTTP caches in common use today only cache 289 GET responses, and therefore only use the URI as the cache key, 290 forwarding other methods. 292 A cache might store multiple responses for a request target that is 293 subject to content negotiation. Caches differentiate these responses 294 by incorporating some of the original request's header fields into 295 the cache key as well, using information in the Vary response header 296 field, as per Section 4.1. 298 Caches might incorporate additional material into the cache key. For 299 example, user agent caches might include the referring site's 300 identity, thereby "double keying" the cache to avoid some privacy 301 risks (see Section 7.2). 303 Most commonly, caches store the successful result of a retrieval 304 request: i.e., a 200 (OK) response to a GET request, which contains a 305 representation of the target resource (Section 9.3.1 of [HTTP]). 306 However, it is also possible to store redirects, negative results 307 (e.g., 404 (Not Found)), incomplete results (e.g., 206 (Partial 308 Content)), and responses to methods other than GET if the method's 309 definition allows such caching and defines something suitable for use 310 as a cache key. 312 A cache is _disconnected_ when it cannot contact the origin server or 313 otherwise find a forward path for a request. A disconnected cache 314 can serve stale responses in some circumstances (Section 4.2.4). 316 3. Storing Responses in Caches 318 A cache MUST NOT store a response to a request unless: 320 * the request method is understood by the cache; 322 * the response status code is final (see Section 15 of [HTTP]); 324 * if the response status code is 206 or 304, or the "must- 325 understand" cache directive (see Section 5.2.2.3) is present: the 326 cache understands the response status code; 328 * the "no-store" cache directive is not present in the response (see 329 Section 5.2.2.5); 331 * if the cache is shared: the "private" response directive is either 332 not present or allows a shared cache to store a modified response; 333 see Section 5.2.2.7); 335 * if the cache is shared: the Authorization header field is not 336 present in the request (see Section 11.6.2 of [HTTP]) or a 337 response directive is present that explicitly allows shared 338 caching (see Section 3.5); and, 340 * the response contains at least one of: 342 - a public response directive (see Section 5.2.2.9); 344 - a private response directive, if the cache is not shared (see 345 Section 5.2.2.7); 347 - an Expires header field (see Section 5.3); 349 - a max-age response directive (see Section 5.2.2.1); 351 - if the cache is shared: an s-maxage response directive (see 352 Section 5.2.2.10); 354 - a Cache Control Extension that allows it to be cached (see 355 Section 5.2.3); or, 357 - a status code that is defined as heuristically cacheable (see 358 Section 4.2.2). 360 Note that a cache-control extension can override any of the 361 requirements listed; see Section 5.2.3. 363 In this context, a cache has "understood" a request method or a 364 response status code if it recognizes it and implements all specified 365 caching-related behavior. 367 Note that, in normal operation, some caches will not store a response 368 that has neither a cache validator nor an explicit expiration time, 369 as such responses are not usually useful to store. However, caches 370 are not prohibited from storing such responses. 372 3.1. Storing Header and Trailer Fields 374 Caches MUST include all received response header fields - including 375 unrecognised ones - when storing a response; this assures that new 376 HTTP header fields can be successfully deployed. However, the 377 following exceptions are made: 379 * The Connection header field and fields whose names are listed in 380 it are required by Section 7.6.1 of [HTTP] to be removed before 381 forwarding the message. This MAY be implemented by doing so 382 before storage. 384 * Likewise, some fields' semantics require them to be removed before 385 forwarding the message, and this MAY be implemented by doing so 386 before storage; see Section 7.6.1 of [HTTP] for some examples. 388 * The no-cache (Section 5.2.2.4) and private (Section 5.2.2.7) cache 389 directives can have arguments that prevent storage of header 390 fields by all caches and shared caches, respectively. 392 * Header fields that are specific to the proxy that a cache uses 393 when forwarding a request MUST NOT be stored, unless the cache 394 incorporates the identity of the proxy into the cache key. 395 Effectively, this is limited to Proxy-Authenticate (Section 11.7.1 396 of [HTTP]), Proxy-Authentication-Info (Section 11.7.3 of [HTTP]), 397 and Proxy-Authorization (Section 11.7.2 of [HTTP]). 399 Caches MAY either store trailer fields separate from header fields, 400 or discard them. Caches MUST NOT combine trailer fields with header 401 fields. 403 3.2. Updating Stored Header Fields 405 Caches are required to update a stored response's header fields from 406 another (typically newer) response in several situations; for 407 example, see Section 3.4, Section 4.3.4 and Section 4.3.5. 409 When doing so, the cache MUST add each header field in the provided 410 response to the stored response, replacing field values that are 411 already present, with the following exceptions: 413 * Header fields excepted from storage in Section 3.1, 415 * Header fields that the cache's stored response depends upon, as 416 described below, 418 * Header fields that are automatically processed and removed by the 419 recipient, as described below, and 421 * The Content-Length header field. 423 In some cases, caches (especially in user agents) store the results 424 of processing the received response, rather than the response itself, 425 and updating header fields that affect that processing can result in 426 inconsistent behavior and security issues. Caches in this situation 427 MAY omit these header fields from updating stored responses on an 428 exceptional basis, but SHOULD limit such omission to those fields 429 necessary to assure integrity of the stored response. 431 For example, a browser might decode the content coding of a response 432 while it is being received, creating a disconnect between the data it 433 has stored and the response's original metadata. Updating that 434 stored metadata with a different Content-Encoding header field would 435 be problematic. Likewise, a browser might store a post-parse HTML 436 tree, rather than the content received in the response; updating the 437 Content-Type header field would not be workable in this case, because 438 any assumptions about the format made in parsing would now be 439 invalid. 441 Furthermore, some fields are automatically processed and removed by 442 the HTTP implementation; for example, the Content-Range header field. 443 Implementations MAY automatically omit such header fields from 444 updates, even when the processing does not actually occur. 446 Note that the Content-* prefix is not a signal that a header field is 447 omitted from update; it is a convention for MIME header fields, not 448 HTTP. 450 3.3. Storing Incomplete Responses 452 If the request method is GET, the response status code is 200 (OK), 453 and the entire response header section has been received, a cache MAY 454 store a response body that is not complete (Section 3.4 of [HTTP]) if 455 the stored response is recorded as being incomplete. Likewise, a 206 456 (Partial Content) response MAY be stored as if it were an incomplete 457 200 (OK) response. However, a cache MUST NOT store incomplete or 458 partial-content responses if it does not support the Range and 459 Content-Range header fields or if it does not understand the range 460 units used in those fields. 462 A cache MAY complete a stored incomplete response by making a 463 subsequent range request (Section 14.2 of [HTTP]) and combining the 464 successful response with the stored response, as defined in 465 Section 3.4. A cache MUST NOT use an incomplete response to answer 466 requests unless the response has been made complete, or the request 467 is partial and specifies a range wholly within the incomplete 468 response. A cache MUST NOT send a partial response to a client 469 without explicitly marking it using the 206 (Partial Content) status 470 code. 472 3.4. Combining Partial Content 474 A response might transfer only a partial representation if the 475 connection closed prematurely or if the request used one or more 476 Range specifiers (Section 14.2 of [HTTP]). After several such 477 transfers, a cache might have received several ranges of the same 478 representation. A cache MAY combine these ranges into a single 479 stored response, and reuse that response to satisfy later requests, 480 if they all share the same strong validator and the cache complies 481 with the client requirements in Section 15.3.7.3 of [HTTP]. 483 When combining the new response with one or more stored responses, a 484 cache MUST update the stored response header fields using the header 485 fields provided in the new response, as per Section 3.2. 487 3.5. Storing Responses to Authenticated Requests 489 A shared cache MUST NOT use a cached response to a request with an 490 Authorization header field (Section 11.6.2 of [HTTP]) to satisfy any 491 subsequent request unless the response contains a Cache-Control field 492 with a response directive (Section 5.2.2) that allows it to be stored 493 by a shared cache and the cache conforms to the requirements of that 494 directive for that response. 496 In this specification, the following response directives have such an 497 effect: must-revalidate (Section 5.2.2.2), public (Section 5.2.2.9), 498 and s-maxage (Section 5.2.2.10). 500 4. Constructing Responses from Caches 502 When presented with a request, a cache MUST NOT reuse a stored 503 response unless: 505 * The presented target URI (Section 7.1 of [HTTP]) and that of the 506 stored response match, and 508 * the request method associated with the stored response allows it 509 to be used for the presented request, and 511 * request header fields nominated by the stored response (if any) 512 match those presented (see Section 4.1), and 514 * the stored response does not contain the no-cache cache directive 515 (Section 5.2.2.4), unless it is successfully validated 516 (Section 4.3), and 518 * the stored response is either: 520 - fresh (see Section 4.2), or 522 - allowed to be served stale (see Section 4.2.4), or 524 - successfully validated (see Section 4.3). 526 Note that a cache-control extension can override any of the 527 requirements listed; see Section 5.2.3. 529 When a stored response is used to satisfy a request without 530 validation, a cache MUST generate an Age header field (Section 5.1), 531 replacing any present in the response with a value equal to the 532 stored response's current_age; see Section 4.2.3. 534 A cache MUST write through requests with methods that are unsafe 535 (Section 9.2.1 of [HTTP]) to the origin server; i.e., a cache is not 536 allowed to generate a reply to such a request before having forwarded 537 the request and having received a corresponding response. 539 Also, note that unsafe requests might invalidate already-stored 540 responses; see Section 4.4. 542 A response that is stored or storable can be used to satisfy multiple 543 requests, provided that it is allowed to reuse that response for the 544 requests in question. This enables caches to _collapse requests_ - 545 or combine multiple incoming requests into a single forward request 546 upon a cache miss - thereby reducing load on the origin server and 547 network. However, note that if the response returned is not able to 548 be used for some or all of the collapsed requests, additional latency 549 might be introduced, because they will need to be forwarded to be 550 satisfied. 552 When more than one suitable response is stored, a cache MUST use the 553 most recent one (as determined by the Date header field). It can 554 also forward the request with "Cache-Control: max-age=0" or "Cache- 555 Control: no-cache" to disambiguate which response to use. 557 A cache without a clock (Section 5.6.7 of [HTTP]) MUST revalidate 558 stored responses upon every use. 560 4.1. Calculating Cache Keys with the Vary Header Field 562 When a cache receives a request that can be satisfied by a stored 563 response and that stored response contains a Vary header field 564 (Section 12.5.5 of [HTTP]), the cache MUST NOT use that stored 565 response without revalidation unless all the presented request header 566 fields nominated by that Vary field value match those fields in the 567 original request (i.e., the request that caused the cached response 568 to be stored). 570 The header fields from two requests are defined to match if and only 571 if those in the first request can be transformed to those in the 572 second request by applying any of: 574 * adding or removing whitespace, where allowed in the header field's 575 syntax 577 * combining multiple header field lines with the same field name 578 (see Section 5.2 of [HTTP]) 580 * normalizing both header field values in a way that is known to 581 have identical semantics, according to the header field's 582 specification (e.g., reordering field values when order is not 583 significant; case-normalization, where values are defined to be 584 case-insensitive) 586 If (after any normalization that might take place) a header field is 587 absent from a request, it can only match another request if it is 588 also absent there. 590 A stored response with a Vary header field value containing a member 591 "*" always fails to match. 593 If multiple stored responses match, the cache will need to choose one 594 to use. When a nominated request header field has a known mechanism 595 for ranking preference (e.g., qvalues on Accept and similar request 596 header fields), that mechanism MAY be used to choose a preferred 597 response. If such a mechanism is not available, or leads to equally 598 preferred responses, the most recent response (as determined by the 599 Date header field) is chosen, as per Section 4. 601 Some resources mistakenly omit the Vary header field from their 602 default response (i.e., the one sent when the request does not 603 express any preferences), with the effect of choosing it for 604 subsequent requests to that resource even when more preferable 605 responses are available. When a cache has multiple stored responses 606 for a target URI and one or more omits the Vary header field, the 607 cache SHOULD choose the most recent (see Section 4.2.3) stored 608 response with a valid Vary field value. 610 If no stored response matches, the cache cannot satisfy the presented 611 request. Typically, the request is forwarded to the origin server, 612 potentially with preconditions added to describe what responses the 613 cache has already stored (Section 4.3). 615 4.2. Freshness 617 A _fresh_ response is one whose age has not yet exceeded its 618 freshness lifetime. Conversely, a _stale_ response is one where it 619 has. 621 A response's _freshness lifetime_ is the length of time between its 622 generation by the origin server and its expiration time. An 623 _explicit expiration time_ is the time at which the origin server 624 intends that a stored response can no longer be used by a cache 625 without further validation, whereas a _heuristic expiration time_ is 626 assigned by a cache when no explicit expiration time is available. 628 A response's _age_ is the time that has passed since it was generated 629 by, or successfully validated with, the origin server. 631 When a response is fresh, it can be used to satisfy subsequent 632 requests without contacting the origin server, thereby improving 633 efficiency. 635 The primary mechanism for determining freshness is for an origin 636 server to provide an explicit expiration time in the future, using 637 either the Expires header field (Section 5.3) or the max-age response 638 directive (Section 5.2.2.1). Generally, origin servers will assign 639 future explicit expiration times to responses in the belief that the 640 representation is not likely to change in a semantically significant 641 way before the expiration time is reached. 643 If an origin server wishes to force a cache to validate every 644 request, it can assign an explicit expiration time in the past to 645 indicate that the response is already stale. Compliant caches will 646 normally validate a stale cached response before reusing it for 647 subsequent requests (see Section 4.2.4). 649 Since origin servers do not always provide explicit expiration times, 650 caches are also allowed to use a heuristic to determine an expiration 651 time under certain circumstances (see Section 4.2.2). 653 The calculation to determine if a response is fresh is: 655 response_is_fresh = (freshness_lifetime > current_age) 657 freshness_lifetime is defined in Section 4.2.1; current_age is 658 defined in Section 4.2.3. 660 Clients can send the max-age or min-fresh request directives 661 (Section 5.2.1) to suggest limits on the freshness calculations for 662 the corresponding response. However, caches are not required to 663 honor them. 665 When calculating freshness, to avoid common problems in date parsing: 667 * Although all date formats are specified to be case-sensitive, a 668 cache recipient SHOULD match the field value case-insensitively. 670 * If a cache recipient's internal implementation of time has less 671 resolution than the value of an HTTP-date, the recipient MUST 672 internally represent a parsed Expires date as the nearest time 673 equal to or earlier than the received value. 675 * A cache recipient MUST NOT allow local time zones to influence the 676 calculation or comparison of an age or expiration time. 678 * A cache recipient SHOULD consider a date with a zone abbreviation 679 other than "GMT" to be invalid for calculating expiration. 681 Note that freshness applies only to cache operation; it cannot be 682 used to force a user agent to refresh its display or reload a 683 resource. See Section 6 for an explanation of the difference between 684 caches and history mechanisms. 686 4.2.1. Calculating Freshness Lifetime 688 A cache can calculate the freshness lifetime (denoted as 689 freshness_lifetime) of a response by using the first match of: 691 * If the cache is shared and the s-maxage response directive 692 (Section 5.2.2.10) is present, use its value, or 694 * If the max-age response directive (Section 5.2.2.1) is present, 695 use its value, or 697 * If the Expires response header field (Section 5.3) is present, use 698 its value minus the value of the Date response header field (using 699 the time the message was received if it is not present, as per 700 Section 6.6.1 of [HTTP]), or 702 * Otherwise, no explicit expiration time is present in the response. 703 A heuristic freshness lifetime might be applicable; see 704 Section 4.2.2. 706 Note that this calculation is intended to reduce clock skew by using 707 the clock information provided by the origin server whenever 708 possible. 710 When there is more than one value present for a given directive 711 (e.g., two Expires header field lines or multiple Cache-Control: max- 712 age directives), either the first occurrence should be used, or the 713 response should be considered stale. If directives conflict (e.g., 714 both max-age and no-cache are present), the most restrictive 715 directive should be honored. Caches are encouraged to consider 716 responses that have invalid freshness information (e.g., a max-age 717 directive with non-integer content) to be stale. 719 4.2.2. Calculating Heuristic Freshness 721 Since origin servers do not always provide explicit expiration times, 722 a cache MAY assign a heuristic expiration time when an explicit time 723 is not specified, employing algorithms that use other field values 724 (such as the Last-Modified time) to estimate a plausible expiration 725 time. This specification does not provide specific algorithms, but 726 does impose worst-case constraints on their results. 728 A cache MUST NOT use heuristics to determine freshness when an 729 explicit expiration time is present in the stored response. Because 730 of the requirements in Section 3, this means that heuristics can only 731 be used on responses without explicit freshness whose status codes 732 are defined as _heuristically cacheable_ (e.g., see Section 15.1 of 733 [HTTP]), and those responses without explicit freshness that have 734 been marked as explicitly cacheable (e.g., with a "public" response 735 directive). 737 Note that in previous specifications heuristically cacheable response 738 status codes were called "cacheable by default." 740 If the response has a Last-Modified header field (Section 8.8.2 of 741 [HTTP]), caches are encouraged to use a heuristic expiration value 742 that is no more than some fraction of the interval since that time. 743 A typical setting of this fraction might be 10%. 745 | *Note:* Section 13.9 of [RFC2616] prohibited caches from 746 | calculating heuristic freshness for URIs with query components 747 | (i.e., those containing '?'). In practice, this has not been 748 | widely implemented. Therefore, origin servers are encouraged 749 | to send explicit directives (e.g., Cache-Control: no-cache) if 750 | they wish to prevent caching. 752 4.2.3. Calculating Age 754 The Age header field is used to convey an estimated age of the 755 response message when obtained from a cache. The Age field value is 756 the cache's estimate of the number of seconds since the origin server 757 generated or validated the response. The Age value is therefore the 758 sum of the time that the response has been resident in each of the 759 caches along the path from the origin server, plus the time it has 760 been in transit along network paths. 762 Age calculation uses the following data: 764 _age_value_ The term "age_value" denotes the value of the Age header 765 field (Section 5.1), in a form appropriate for arithmetic 766 operation; or 0, if not available. 768 _date_value_ The term "date_value" denotes the value of the Date 769 header field, in a form appropriate for arithmetic operations. 770 See Section 6.6.1 of [HTTP] for the definition of the Date header 771 field, and for requirements regarding responses without it. 773 _now_ The term "now" means the current value of this 774 implementation's clock (Section 5.6.7 of [HTTP]). 776 _request_time_ The value of the clock at the time of the request 777 that resulted in the stored response. 779 _response_time_ The value of the clock at the time the response was 780 received. 782 A response's age can be calculated in two entirely independent ways: 784 1. the "apparent_age": response_time minus date_value, if the 785 implementation's clock is reasonably well synchronized to the 786 origin server's clock. If the result is negative, the result is 787 replaced by zero. 789 2. the "corrected_age_value", if all of the caches along the 790 response path implement HTTP/1.1 or greater. A cache MUST 791 interpret this value relative to the time the request was 792 initiated, not the time that the response was received. 794 apparent_age = max(0, response_time - date_value); 796 response_delay = response_time - request_time; 797 corrected_age_value = age_value + response_delay; 799 The corrected_age_value MAY be used as the corrected_initial_age. In 800 circumstances where very old cache implementations that might not 801 correctly insert Age are present, corrected_initial_age can be 802 calculated more conservatively as 804 corrected_initial_age = max(apparent_age, corrected_age_value); 806 The current_age of a stored response can then be calculated by adding 807 the time (in seconds) since the stored response was last validated by 808 the origin server to the corrected_initial_age. 810 resident_time = now - response_time; 811 current_age = corrected_initial_age + resident_time; 813 4.2.4. Serving Stale Responses 815 A "stale" response is one that either has explicit expiry information 816 or is allowed to have heuristic expiry calculated, but is not fresh 817 according to the calculations in Section 4.2. 819 A cache MUST NOT generate a stale response if it is prohibited by an 820 explicit in-protocol directive (e.g., by a "no-cache" cache 821 directive, a "must-revalidate" cache-response-directive, or an 822 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 823 see Section 5.2.2). 825 A cache MUST NOT generate a stale response unless it is disconnected 826 or doing so is explicitly permitted by the client or origin server 827 (e.g., by the max-stale request directive in Section 5.2.1, by 828 extension directives such as those defined in [RFC5861], or by 829 configuration in accordance with an out-of-band contract). 831 4.3. Validation 833 When a cache has one or more stored responses for a requested URI, 834 but cannot serve any of them (e.g., because they are not fresh, or 835 one cannot be chosen; see Section 4.1), it can use the conditional 836 request mechanism (Section 13.1 of [HTTP]) in the forwarded request 837 to give the next inbound server an opportunity to choose a valid 838 stored response to use, updating the stored metadata in the process, 839 or to replace the stored response(s) with a new response. This 840 process is known as _validating_ or _revalidating_ the stored 841 response. 843 4.3.1. Sending a Validation Request 845 When generating a conditional request for validation, a cache starts 846 with either a request it is attempting to satisfy, or - if it is 847 initiating the request independently - it synthesises a request using 848 a stored response by copying the method, target URI, and request 849 header fields identified by the Vary header field (Section 4.1). 851 It then updates that request with one or more precondition header 852 fields. These contain validator metadata sourced from stored 853 response(s) that have the same URI. Typically, this will include 854 only those stored responses(s) that have the same cache key, although 855 a cache is allowed to validate a response that it cannot choose with 856 the request header fields it is sending (see Section 4.1). 858 The precondition header fields are then compared by recipients to 859 determine whether any stored response is equivalent to a current 860 representation of the resource. 862 One such validator is the timestamp given in a Last-Modified header 863 field (Section 8.8.2 of [HTTP]), which can be used in an If-Modified- 864 Since header field for response validation, or in an If-Unmodified- 865 Since or If-Range header field for representation selection (i.e., 866 the client is referring specifically to a previously obtained 867 representation with that timestamp). 869 Another validator is the entity-tag given in an ETag field 870 (Section 8.8.3 of [HTTP]). One or more entity-tags, indicating one 871 or more stored responses, can be used in an If-None-Match header 872 field for response validation, or in an If-Match or If-Range header 873 field for representation selection (i.e., the client is referring 874 specifically to one or more previously obtained representations with 875 the listed entity-tags). 877 When generating a conditional request for validation, a cache: 879 * MUST send the relevant entity-tags (using If-Match, If-None-Match, 880 or If-Range) if the entity-tags were provided in the stored 881 response(s) being validated. 883 * SHOULD send the Last-Modified value (using If-Modified-Since) if 884 the request is not for a subrange, a single stored response is 885 being validated, and that response contains a Last-Modified value. 887 * MAY send the Last-Modified value (using If-Unmodified-Since or If- 888 Range) if the request is for a subrange, a single stored response 889 is being validated, and that response contains only a Last- 890 Modified value (not an entity-tag). 892 In most cases, both validators are generated in cache validation 893 requests, even when entity-tags are clearly superior, to allow old 894 intermediaries that do not understand entity-tag preconditions to 895 respond appropriately. 897 4.3.2. Handling a Received Validation Request 899 Each client in the request chain may have its own cache, so it is 900 common for a cache at an intermediary to receive conditional requests 901 from other (outbound) caches. Likewise, some user agents make use of 902 conditional requests to limit data transfers to recently modified 903 representations or to complete the transfer of a partially retrieved 904 representation. 906 If a cache receives a request that can be satisfied by reusing a 907 stored 200 (OK) or 206 (Partial Content) response, as per Section 4, 908 the cache SHOULD evaluate any applicable conditional header field 909 preconditions received in that request with respect to the 910 corresponding validators contained within the stored response. 912 A cache MUST NOT evaluate conditional header fields that only apply 913 to an origin server, occur in a request with semantics that cannot be 914 satisfied with a cached response, or occur in a request with a target 915 resource for which it has no stored responses; such preconditions are 916 likely intended for some other (inbound) server. 918 The proper evaluation of conditional requests by a cache depends on 919 the received precondition header fields and their precedence. In 920 summary, the If-Match and If-Unmodified-Since conditional header 921 fields are not applicable to a cache, and If-None-Match takes 922 precedence over If-Modified-Since. See Section 13.2.2 of [HTTP] for 923 a complete specification of precondition precedence. 925 A request containing an If-None-Match header field (Section 13.1.2 of 926 [HTTP]) indicates that the client wants to validate one or more of 927 its own stored responses in comparison to the stored response chosen 928 by the cache (as per Section 4). 930 If an If-None-Match header field is not present, a request containing 931 an If-Modified-Since header field (Section 13.1.3 of [HTTP]) 932 indicates that the client wants to validate one or more of its own 933 stored responses by modification date. 935 If a request contains an If-Modified-Since header field and the Last- 936 Modified header field is not present in a stored response, a cache 937 SHOULD use the stored response's Date field value (or, if no Date 938 field is present, the time that the stored response was received) to 939 evaluate the conditional. 941 A cache that implements partial responses to range requests, as 942 defined in Section 14.2 of [HTTP], also needs to evaluate a received 943 If-Range header field (Section 13.1.5 of [HTTP]) with respect to the 944 cache's chosen response. 946 When a cache decides to forward a request to revalidate its own 947 stored responses for a request that contains an If-None-Match list of 948 entity-tags, the cache MAY combine the received list with a list of 949 entity-tags from its own stored set of responses (fresh or stale) and 950 send the union of the two lists as a replacement If-None-Match header 951 field value in the forwarded request. If a stored response contains 952 only partial content, the cache MUST NOT include its entity-tag in 953 the union unless the request is for a range that would be fully 954 satisfied by that partial stored response. If the response to the 955 forwarded request is 304 (Not Modified) and has an ETag field value 956 with an entity-tag that is not in the client's list, the cache MUST 957 generate a 200 (OK) response for the client by reusing its 958 corresponding stored response, as updated by the 304 response 959 metadata (Section 4.3.4). 961 4.3.3. Handling a Validation Response 963 Cache handling of a response to a conditional request depends upon 964 its status code: 966 * A 304 (Not Modified) response status code indicates that the 967 stored response can be updated and reused; see Section 4.3.4. 969 * A full response (i.e., one containing content) indicates that none 970 of the stored responses nominated in the conditional request is 971 suitable. Instead, the cache MUST use the full response to 972 satisfy the request. The cache MAY store such a full response, 973 subject to its constraints (see Section 3). 975 * However, if a cache receives a 5xx (Server Error) response while 976 attempting to validate a response, it can either forward this 977 response to the requesting client, or act as if the server failed 978 to respond. In the latter case, the cache can send a previously 979 stored response, subject to its constraints on doing so (see 980 Section 4.2.4), or retry the validation request. 982 4.3.4. Freshening Stored Responses upon Validation 984 When a cache receives a 304 (Not Modified) response, it needs to 985 identify stored responses that are suitable for updating with the new 986 information provided, and then do so. 988 The initial set of stored responses to update are those that could 989 have been chosen for that request - i.e., those that meet the 990 requirements in Section 4, except the last requirement to be fresh, 991 able to be served stale or just validated. 993 Then, that initial set of stored response(s) is further filtered by 994 the first match of: 996 * If the new response contains one or more _strong validators_ (see 997 Section 8.8.1 of [HTTP]), then each of those strong validators 998 identify a selected representation for update. All the stored 999 responses in the initial set with one of those same strong 1000 validators are identified for update. If none of the initial set 1001 contain at least one of the same strong validators, then the cache 1002 MUST NOT use the new response to update any stored responses. 1004 * If the new response contains no strong validators but does contain 1005 one or more _weak validators_, and those validators correspond to 1006 one of the initial set's stored responses, then the most recent of 1007 those matching stored responses is identified for update. 1009 * If the new response does not include any form of validator (such 1010 as where a client generates an If-Modified-Since request from a 1011 source other than the Last-Modified response header field), and 1012 there is only one stored response in the initial set, and that 1013 stored response also lacks a validator, then that stored response 1014 is identified for update. 1016 For each stored response identified, the cache MUST update its header 1017 fields with the header fields provided in the 304 (Not Modified) 1018 response, as per Section 3.2. 1020 4.3.5. Freshening Responses with HEAD 1022 A response to the HEAD method is identical to what an equivalent 1023 request made with a GET would have been, without sending the content. 1024 This property of HEAD responses can be used to invalidate or update a 1025 cached GET response if the more efficient conditional GET request 1026 mechanism is not available (due to no validators being present in the 1027 stored response) or if transmission of the content is not desired 1028 even if it has changed. 1030 When a cache makes an inbound HEAD request for a target URI and 1031 receives a 200 (OK) response, the cache SHOULD update or invalidate 1032 each of its stored GET responses that could have been chosen for that 1033 request (see Section 4.1). 1035 For each of the stored responses that could have been chosen, if the 1036 stored response and HEAD response have matching values for any 1037 received validator fields (ETag and Last-Modified) and, if the HEAD 1038 response has a Content-Length header field, the value of Content- 1039 Length matches that of the stored response, the cache SHOULD update 1040 the stored response as described below; otherwise, the cache SHOULD 1041 consider the stored response to be stale. 1043 If a cache updates a stored response with the metadata provided in a 1044 HEAD response, the cache MUST use the header fields provided in the 1045 HEAD response to update the stored response (see Section 3.2). 1047 4.4. Invalidating Stored Responses 1049 Because unsafe request methods (Section 9.2.1 of [HTTP]) such as PUT, 1050 POST or DELETE have the potential for changing state on the origin 1051 server, intervening caches are required to invalidate stored 1052 responses to keep their contents up to date. 1054 A cache MUST invalidate the target URI (Section 7.1 of [HTTP]) when 1055 it receives a non-error status code in response to an unsafe request 1056 method (including methods whose safety is unknown). 1058 A cache MAY invalidate other URIs when it receives a non-error status 1059 code in response to an unsafe request method (including methods whose 1060 safety is unknown). In particular, the URI(s) in the Location and 1061 Content-Location response header fields (if present) are candidates 1062 for invalidation; other URIs might be discovered through mechanisms 1063 not specified in this document. However, a cache MUST NOT trigger an 1064 invalidation under these conditions if the origin (Section 4.3.1 of 1065 [HTTP]) of the URI to be invalidated differs from that of the target 1066 URI (Section 7.1 of [HTTP]). This helps prevent denial-of-service 1067 attacks. 1069 _Invalidate_ means that the cache will either remove all stored 1070 responses whose target URI matches the given URI, or will mark them 1071 as "invalid" and in need of a mandatory validation before they can be 1072 sent in response to a subsequent request. 1074 A "non-error response" is one with a 2xx (Successful) or 3xx 1075 (Redirection) status code. 1077 Note that this does not guarantee that all appropriate responses are 1078 invalidated globally; a state-changing request would only invalidate 1079 responses in the caches it travels through. 1081 5. Field Definitions 1083 This section defines the syntax and semantics of HTTP fields related 1084 to caching. 1086 5.1. Age 1088 The "Age" response header field conveys the sender's estimate of the 1089 time since the response was generated or successfully validated at 1090 the origin server. Age values are calculated as specified in 1091 Section 4.2.3. 1093 Age = delta-seconds 1095 The Age field value is a non-negative integer, representing time in 1096 seconds (see Section 1.2.2). 1098 Although it is defined as a singleton header field, a cache 1099 encountering a message with a list-based Age field value SHOULD use 1100 the first member of the field value, discarding subsequent ones. 1102 If the field value (after discarding additional members, as per 1103 above) is invalid (e.g., it contains something other than a non- 1104 negative integer), a cache SHOULD ignore the field. 1106 The presence of an Age header field implies that the response was not 1107 generated or validated by the origin server for this request. 1108 However, lack of an Age header field does not imply the origin was 1109 contacted. 1111 5.2. Cache-Control 1113 The "Cache-Control" header field is used to list directives for 1114 caches along the request/response chain. Such cache directives are 1115 unidirectional in that the presence of a directive in a request does 1116 not imply that the same directive is present in the response, or to 1117 be repeated in it. 1119 See Section 5.2.3 for information about how Cache-Control directives 1120 defined elsewhere are handled. 1122 A proxy, whether or not it implements a cache, MUST pass cache 1123 directives through in forwarded messages, regardless of their 1124 significance to that application, since the directives might apply to 1125 all recipients along the request/response chain. It is not possible 1126 to target a directive to a specific cache. 1128 Cache directives are identified by a token, to be compared case- 1129 insensitively, and have an optional argument that can use both token 1130 and quoted-string syntax. For the directives defined below that 1131 define arguments, recipients ought to accept both forms, even if a 1132 specific form is required for generation. 1134 Cache-Control = #cache-directive 1136 cache-directive = token [ "=" ( token / quoted-string ) ] 1138 For the cache directives defined below, no argument is defined (nor 1139 allowed) unless stated otherwise. 1141 5.2.1. Request Cache-Control Directives 1143 This section defines cache request directives. They are advisory; 1144 caches MAY implement them, but are not required to. 1146 5.2.1.1. max-age 1148 Argument syntax: 1150 delta-seconds (see Section 1.2.2) 1152 The "max-age" request directive indicates that the client prefers a 1153 response whose age is less than or equal to the specified number of 1154 seconds. Unless the max-stale request directive is also present, the 1155 client does not wish to receive a stale response. 1157 This directive uses the token form of the argument syntax: e.g., 1158 'max-age=5' not 'max-age="5"'. A sender MUST NOT generate the 1159 quoted-string form. 1161 5.2.1.2. max-stale 1163 Argument syntax: 1165 delta-seconds (see Section 1.2.2) 1167 The "max-stale" request directive indicates that the client will 1168 accept a response that has exceeded its freshness lifetime. If a 1169 value is present, then the client is willing to accept a response 1170 that has exceeded its freshness lifetime by no more than the 1171 specified number of seconds. If no value is assigned to max-stale, 1172 then the client will accept a stale response of any age. 1174 This directive uses the token form of the argument syntax: e.g., 1175 'max-stale=10' not 'max-stale="10"'. A sender MUST NOT generate the 1176 quoted-string form. 1178 5.2.1.3. min-fresh 1180 Argument syntax: 1182 delta-seconds (see Section 1.2.2) 1184 The "min-fresh" request directive indicates that the client prefers a 1185 response whose freshness lifetime is no less than its current age 1186 plus the specified time in seconds. That is, the client wants a 1187 response that will still be fresh for at least the specified number 1188 of seconds. 1190 This directive uses the token form of the argument syntax: e.g., 1191 'min-fresh=20' not 'min-fresh="20"'. A sender MUST NOT generate the 1192 quoted-string form. 1194 5.2.1.4. no-cache 1196 The "no-cache" request directive indicates that the client prefers 1197 stored response not be used to satisfy the request without successful 1198 validation on the origin server. 1200 5.2.1.5. no-store 1202 The "no-store" request directive indicates that a cache MUST NOT 1203 store any part of either this request or any response to it. This 1204 directive applies to both private and shared caches. "MUST NOT 1205 store" in this context means that the cache MUST NOT intentionally 1206 store the information in non-volatile storage, and MUST make a best- 1207 effort attempt to remove the information from volatile storage as 1208 promptly as possible after forwarding it. 1210 This directive is _not_ a reliable or sufficient mechanism for 1211 ensuring privacy. In particular, malicious or compromised caches 1212 might not recognize or obey this directive, and communications 1213 networks might be vulnerable to eavesdropping. 1215 Note that if a request containing this directive is satisfied from a 1216 cache, the no-store request directive does not apply to the already 1217 stored response. 1219 5.2.1.6. no-transform 1221 The "no-transform" request directive indicates that the client is 1222 asking for intermediaries to avoid transforming the content, as 1223 defined in Section 7.7 of [HTTP]. 1225 5.2.1.7. only-if-cached 1227 The "only-if-cached" request directive indicates that the client only 1228 wishes to obtain a stored response. Caches that honor this request 1229 directive SHOULD, upon receiving it, either respond using a stored 1230 response consistent with the other constraints of the request, or 1231 respond with a 504 (Gateway Timeout) status code. 1233 5.2.2. Response Cache-Control Directives 1235 This section defines cache response directives. A cache MUST obey 1236 the Cache-Control directives defined in this section. 1238 5.2.2.1. max-age 1240 Argument syntax: 1242 delta-seconds (see Section 1.2.2) 1244 The "max-age" response directive indicates that the response is to be 1245 considered stale after its age is greater than the specified number 1246 of seconds. 1248 This directive uses the token form of the argument syntax: e.g., 1249 'max-age=5' not 'max-age="5"'. A sender MUST NOT generate the 1250 quoted-string form. 1252 5.2.2.2. must-revalidate 1254 The "must-revalidate" response directive indicates that once the 1255 response has become stale, a cache MUST NOT reuse that response to 1256 satisfy another request until it has been successfully validated by 1257 the origin, as defined by Section 4.3. 1259 The must-revalidate directive is necessary to support reliable 1260 operation for certain protocol features. In all circumstances a 1261 cache MUST NOT ignore the must-revalidate directive; in particular, 1262 if a cache is disconnected, the cache MUST generate an error response 1263 rather than reuse the stale response. The generated status code 1264 SHOULD be 504 (Gateway Timeout) unless another error status code is 1265 more applicable. 1267 The must-revalidate directive ought to be used by servers if and only 1268 if failure to validate a request could cause incorrect operation, 1269 such as a silently unexecuted financial transaction. 1271 The must-revalidate directive also permits a shared cache to reuse a 1272 response to a request containing an Authorization header field 1273 (Section 11.6.2 of [HTTP]), subject to the above requirement on 1274 revalidation (Section 3.5). 1276 5.2.2.3. must-understand 1278 The "must-understand" response directive limits caching of the 1279 response to a cache that understands and conforms to the requirements 1280 for that response's status code. 1282 Responses containing "must-understand" SHOULD also contain the "no- 1283 store" directive; caches that implement "must-understand" SHOULD 1284 ignore the "no-store" directive in responses that contain both 1285 directives and a status code that the cache understands and conforms 1286 to any related caching requirements. 1288 5.2.2.4. no-cache 1290 Argument syntax: 1292 #field-name 1294 The "no-cache" response directive, in its unqualified form (without 1295 an argument), indicates that the response MUST NOT be used to satisfy 1296 any other request without forwarding it for validation and receiving 1297 a successful response; see Section 4.3. 1299 This allows an origin server to prevent a cache from using the 1300 response to satisfy a request without contacting it, even by caches 1301 that have been configured to send stale responses. 1303 The qualified form of no-cache response directive, with an argument 1304 that lists one or more field names, indicates that a cache MAY use 1305 the response to satisfy a subsequent request, subject to any other 1306 restrictions on caching, if the listed header fields are excluded 1307 from the subsequent response or the subsequent response has been 1308 successfully revalidated with the origin server (updating or removing 1309 those fields). This allows an origin server to prevent the re-use of 1310 certain header fields in a response, while still allowing caching of 1311 the rest of the response. 1313 The field names given are not limited to the set of header fields 1314 defined by this specification. Field names are case-insensitive. 1316 This directive uses the quoted-string form of the argument syntax. A 1317 sender SHOULD NOT generate the token form (even if quoting appears 1318 not to be needed for single-entry lists). 1320 | *Note:* The qualified form of the directive is often handled by 1321 | caches as if an unqualified no-cache directive was received; 1322 | i.e., the special handling for the qualified form is not widely 1323 | implemented. 1325 5.2.2.5. no-store 1327 The "no-store" response directive indicates that a cache MUST NOT 1328 store any part of either the immediate request or response, and MUST 1329 NOT use the response to satisfy any other request. 1331 This directive applies to both private and shared caches. "MUST NOT 1332 store" in this context means that the cache MUST NOT intentionally 1333 store the information in non-volatile storage, and MUST make a best- 1334 effort attempt to remove the information from volatile storage as 1335 promptly as possible after forwarding it. 1337 This directive is _not_ a reliable or sufficient mechanism for 1338 ensuring privacy. In particular, malicious or compromised caches 1339 might not recognize or obey this directive, and communications 1340 networks might be vulnerable to eavesdropping. 1342 Note that the "must-understand" cache directive overrides "no-store" 1343 in certain circumstances; see Section 5.2.2.3. 1345 5.2.2.6. no-transform 1347 The "no-transform" response directive indicates that an intermediary 1348 (regardless of whether it implements a cache) MUST NOT transform the 1349 content, as defined in Section 7.7 of [HTTP]. 1351 5.2.2.7. private 1353 Argument syntax: 1355 #field-name 1357 The unqualified "private" response directive indicates that a shared 1358 cache MUST NOT store the response (i.e., the response is intended for 1359 a single user). It also indicates that a private cache MAY store the 1360 response, subject the constraints defined in Section 3, even if the 1361 response would not otherwise be heuristically cacheable by a private 1362 cache. 1364 If a qualified private response directive is present, with an 1365 argument that lists one or more field names, then only the listed 1366 header fields are limited to a single user: a shared cache MUST NOT 1367 store the listed header fields if they are present in the original 1368 response, but MAY store the remainder of the response message without 1369 those header fields, subject the constraints defined in Section 3. 1371 The field names given are not limited to the set of header fields 1372 defined by this specification. Field names are case-insensitive. 1374 This directive uses the quoted-string form of the argument syntax. A 1375 sender SHOULD NOT generate the token form (even if quoting appears 1376 not to be needed for single-entry lists). 1378 | *Note:* This usage of the word "private" only controls where 1379 | the response can be stored; it cannot ensure the privacy of the 1380 | message content. Also, the qualified form of the directive is 1381 | often handled by caches as if an unqualified private directive 1382 | was received; i.e., the special handling for the qualified form 1383 | is not widely implemented. 1385 5.2.2.8. proxy-revalidate 1387 The "proxy-revalidate" response directive indicates that once the 1388 response has become stale, a shared cache MUST NOT reuse that 1389 response to satisfy another request until it has been successfully 1390 validated by the origin, as defined by Section 4.3. This is 1391 analogous to must-revalidate (Section 5.2.2.2), except that proxy- 1392 revalidate does not apply to private caches. 1394 Note that "proxy-revalidate" on its own does not imply that a 1395 response is cacheable. For example, it might be combined with the 1396 public directive (Section 5.2.2.9), allowing the response to be 1397 cached while requiring only a shared cache to revalidate when stale. 1399 5.2.2.9. public 1401 The "public" response directive indicates that a cache MAY store the 1402 response even if it would otherwise be prohibited, subject to the 1403 constraints defined in Section 3. In other words, public explicitly 1404 marks the response as cacheable. For example, public permits a 1405 shared cache to reuse a response to a request containing an 1406 Authorization header field (Section 3.5). 1408 Note that it is unnecessary to add the public directive to a response 1409 that is already cacheable according to Section 3. 1411 If a response with the public directive has no explicit freshness 1412 information, it is heuristically cacheable (Section 4.2.2). 1414 5.2.2.10. s-maxage 1416 Argument syntax: 1418 delta-seconds (see Section 1.2.2) 1420 The "s-maxage" response directive indicates that, for a shared cache, 1421 the maximum age specified by this directive overrides the maximum age 1422 specified by either the max-age directive or the Expires header 1423 field. 1425 The s-maxage directive incorporates the proxy-revalidate 1426 (Section 5.2.2.8) response directive's semantics for a shared cache. 1427 A shared cache MUST NOT reuse a stale response with s-maxage to 1428 satisfy another request until it has been successfully validated by 1429 the origin, as defined by Section 4.3. This directive also permits a 1430 shared cache to reuse a response to a request containing an 1431 Authorization header field, subject to the above requirements on 1432 maximum age and revalidation (Section 3.5). 1434 This directive uses the token form of the argument syntax: e.g., 1435 's-maxage=10' not 's-maxage="10"'. A sender MUST NOT generate the 1436 quoted-string form. 1438 5.2.3. Cache Control Extensions 1440 The Cache-Control header field can be extended through the use of one 1441 or more extension cache directives. A cache MUST ignore unrecognized 1442 cache directives. 1444 Informational extensions (those that do not require a change in cache 1445 behavior) can be added without changing the semantics of other 1446 directives. 1448 Behavioral extensions are designed to work by acting as modifiers to 1449 the existing base of cache directives. Both the new directive and 1450 the old directive are supplied, such that applications that do not 1451 understand the new directive will default to the behavior specified 1452 by the old directive, and those that understand the new directive 1453 will recognize it as modifying the requirements associated with the 1454 old directive. In this way, extensions to the existing cache-control 1455 directives can be made without breaking deployed caches. 1457 For example, consider a hypothetical new response directive called 1458 "community" that acts as a modifier to the private directive: in 1459 addition to private caches, any cache that is shared only by members 1460 of the named community is allowed to cache the response. An origin 1461 server wishing to allow the UCI community to use an otherwise private 1462 response in their shared cache(s) could do so by including 1464 Cache-Control: private, community="UCI" 1466 A cache that recognizes such a community cache directive could 1467 broaden its behavior in accordance with that extension. A cache that 1468 does not recognize the community cache directive would ignore it and 1469 adhere to the private directive. 1471 New extension directives ought to consider defining: 1473 * What it means for a directive to be specified multiple times, 1475 * When the directive does not take an argument, what it means when 1476 an argument is present, 1478 * When the directive requires an argument, what it means when it is 1479 missing, 1481 * Whether the directive is specific to requests, responses, or able 1482 to be used in either. 1484 5.2.4. Cache Directive Registry 1486 The "Hypertext Transfer Protocol (HTTP) Cache Directive Registry" 1487 defines the namespace for the cache directives. It has been created 1488 and is now maintained at . 1491 A registration MUST include the following fields: 1493 * Cache Directive Name 1495 * Pointer to specification text 1497 Values to be added to this namespace require IETF Review (see 1498 [RFC8126], Section 4.8). 1500 5.3. Expires 1502 The "Expires" response header field gives the date/time after which 1503 the response is considered stale. See Section 4.2 for further 1504 discussion of the freshness model. 1506 The presence of an Expires header field does not imply that the 1507 original resource will change or cease to exist at, before, or after 1508 that time. 1510 The Expires field value is an HTTP-date timestamp, as defined in 1511 Section 5.6.7 of [HTTP]. See also Section 4.2 for parsing 1512 requirements specific to caches. 1514 Expires = HTTP-date 1516 For example 1518 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1520 A cache recipient MUST interpret invalid date formats, especially the 1521 value "0", as representing a time in the past (i.e., "already 1522 expired"). 1524 If a response includes a Cache-Control header field with the max-age 1525 directive (Section 5.2.2.1), a recipient MUST ignore the Expires 1526 header field. Likewise, if a response includes the s-maxage 1527 directive (Section 5.2.2.10), a shared cache recipient MUST ignore 1528 the Expires header field. In both these cases, the value in Expires 1529 is only intended for recipients that have not yet implemented the 1530 Cache-Control header field. 1532 An origin server without a clock (Section 5.6.7 of [HTTP]) MUST NOT 1533 generate an Expires header field unless its value represents a fixed 1534 time in the past (always expired) or its value has been associated 1535 with the resource by a system with a clock. 1537 Historically, HTTP required the Expires field value to be no more 1538 than a year in the future. While longer freshness lifetimes are no 1539 longer prohibited, extremely large values have been demonstrated to 1540 cause problems (e.g., clock overflows due to use of 32-bit integers 1541 for time values), and many caches will evict a response far sooner 1542 than that. 1544 5.4. Pragma 1546 The "Pragma" request header field was defined for HTTP/1.0 caches, so 1547 that clients could specify a "no-cache" request (as Cache-Control was 1548 not defined until HTTP/1.1). 1550 However, support for Cache-Control is now widespread. As a result, 1551 this specification deprecates Pragma. 1553 | *Note:* Because the meaning of "Pragma: no-cache" in responses 1554 | was never specified, it does not provide a reliable replacement 1555 | for "Cache-Control: no-cache" in them. 1557 5.5. Warning 1559 The "Warning" header field was used to carry additional information 1560 about the status or transformation of a message that might not be 1561 reflected in the status code. This specification obsoletes it, as it 1562 is not widely generated or surfaced to users. The information it 1563 carried can be gleaned from examining other header fields, such as 1564 Age. 1566 6. Relationship to Applications and Other Caches 1568 Applications using HTTP often specify additional forms of caching. 1569 For example, Web browsers often have history mechanisms such as 1570 "Back" buttons that can be used to redisplay a representation 1571 retrieved earlier in a session. 1573 Likewise, some Web browsers implement caching of images and other 1574 assets within a page view; they may or may not honor HTTP caching 1575 semantics. 1577 The requirements in this specification do not necessarily apply to 1578 how applications use data after it is retrieved from an HTTP cache. 1579 For example, a history mechanism can display a previous 1580 representation even if it has expired, and an application can use 1581 cached data in other ways beyond its freshness lifetime. 1583 This specification does not prohibit the application from taking HTTP 1584 caching into account; for example, a history mechanism might tell the 1585 user that a view is stale, or it might honor cache directives (e.g., 1586 Cache-Control: no-store). 1588 However, when an application caches data and does not make this 1589 apparent to or easily controllable by the user, it is strongly 1590 encouraged to define its operation with respect to HTTP cache 1591 directives, so as not to surprise authors who expect caching 1592 semantics to be honoured. For example, while it might be reasonable 1593 to define an application cache "above" HTTP that allows a response 1594 containing Cache-Control: no-store to be reused for requests that are 1595 directly related to the request that fetched it (such as those 1596 created during the same page load), it would likely be surprising and 1597 confusing to users and authors if it were allowed to be reused for 1598 requests unrelated in any way to the one from which it was obtained. 1600 7. Security Considerations 1602 This section is meant to inform developers, information providers, 1603 and users of known security concerns specific to HTTP caching. More 1604 general security considerations are addressed in "HTTP/1.1" 1605 (Section 11 of [HTTP/1.1]) and "HTTP Semantics" (Section 17 of 1606 [HTTP]). 1608 Caches expose an additional attack surface, since the contents of the 1609 cache represent an attractive target for malicious exploitation. 1610 Because cache contents persist after an HTTP request is complete, an 1611 attack on the cache can reveal information long after a user believes 1612 that the information has been removed from the network. Therefore, 1613 cache contents need to be protected as sensitive information. 1615 In particular, because private caches are restricted to a single 1616 user, they can be used to reconstruct a user's activity. As a 1617 result, it is important for user agents to allow end users to control 1618 them; for example, allowing stored responses to be removed for some 1619 or all origin servers. 1621 7.1. Cache Poisoning 1623 Storing a malicious payload in a cache can extend the reach of an 1624 attacker to affect multiple users. Such "cache poisoning" attacks 1625 happen when an attacker uses implementation flaws, elevated 1626 privileges, or other techniques to insert a response into a cache. 1627 This is especially effective when shared caches are used to 1628 distribute malicious content to many clients. 1630 One common attack vector for cache poisoning is to exploit 1631 differences in message parsing on proxies and in user agents; see 1632 Section 6.3 of [HTTP/1.1] for the relevant requirements regarding 1633 HTTP/1.1. 1635 7.2. Timing Attacks 1637 Because one of the primary uses of a cache is to optimise 1638 performance, its use can "leak" information about what resources have 1639 been previously requested. 1641 For example, if a user visits a site and their browser caches some of 1642 its responses, and then navigates to a second site, that site can 1643 attempt to load responses it knows exists on the first site. If they 1644 load quickly, it can be assumed that the user has visited that site, 1645 or even a specific page on it. 1647 Such "timing attacks" can be mitigated by adding more information to 1648 the cache key, such as the identity of the referring site (to prevent 1649 the attack described above). This is sometimes called "double 1650 keying." 1652 7.3. Caching of Sensitive Information 1654 Implementation and deployment flaws (as well as misunderstanding of 1655 cache operation) might lead to caching of sensitive information 1656 (e.g., authentication credentials) that is thought to be private, 1657 exposing it to unauthorized parties. 1659 Note that the Set-Cookie response header field [COOKIE] does not 1660 inhibit caching; a cacheable response with a Set-Cookie header field 1661 can be (and often is) used to satisfy subsequent requests to caches. 1662 Servers who wish to control caching of these responses are encouraged 1663 to emit appropriate Cache-Control response header fields. 1665 8. IANA Considerations 1667 The change controller for the following registrations is: "IETF 1668 (iesg@ietf.org) - Internet Engineering Task Force". 1670 8.1. Field Name Registration 1672 First, introduce the new "Hypertext Transfer Protocol (HTTP) Field 1673 Name Registry" at as 1674 described in Section 18.4 of [HTTP]. 1676 Then, please update the registry with the field names listed in the 1677 table below: 1679 +===============+===========+======+==========+ 1680 | Field Name | Status | Ref. | Comments | 1681 +===============+===========+======+==========+ 1682 | Age | standard | 5.1 | | 1683 +---------------+-----------+------+----------+ 1684 | Cache-Control | standard | 5.2 | | 1685 +---------------+-----------+------+----------+ 1686 | Expires | standard | 5.3 | | 1687 +---------------+-----------+------+----------+ 1688 | Pragma | standard | 5.4 | | 1689 +---------------+-----------+------+----------+ 1690 | Warning | obsoleted | 5.5 | | 1691 +---------------+-----------+------+----------+ 1693 Table 1 1695 8.2. Cache Directive Registration 1697 Please update the "Hypertext Transfer Protocol (HTTP) Cache Directive 1698 Registry" at 1699 with the registration procedure of Section 5.2.4 and the cache 1700 directive names summarized in the table below. 1702 +==================+==================================+ 1703 | Cache Directive | Reference | 1704 +==================+==================================+ 1705 | max-age | Section 5.2.1.1, Section 5.2.2.1 | 1706 +------------------+----------------------------------+ 1707 | max-stale | Section 5.2.1.2 | 1708 +------------------+----------------------------------+ 1709 | min-fresh | Section 5.2.1.3 | 1710 +------------------+----------------------------------+ 1711 | must-revalidate | Section 5.2.2.2 | 1712 +------------------+----------------------------------+ 1713 | must-understand | Section 5.2.2.3 | 1714 +------------------+----------------------------------+ 1715 | no-cache | Section 5.2.1.4, Section 5.2.2.4 | 1716 +------------------+----------------------------------+ 1717 | no-store | Section 5.2.1.5, Section 5.2.2.5 | 1718 +------------------+----------------------------------+ 1719 | no-transform | Section 5.2.1.6, Section 5.2.2.6 | 1720 +------------------+----------------------------------+ 1721 | only-if-cached | Section 5.2.1.7 | 1722 +------------------+----------------------------------+ 1723 | private | Section 5.2.2.7 | 1724 +------------------+----------------------------------+ 1725 | proxy-revalidate | Section 5.2.2.8 | 1726 +------------------+----------------------------------+ 1727 | public | Section 5.2.2.9 | 1728 +------------------+----------------------------------+ 1729 | s-maxage | Section 5.2.2.10 | 1730 +------------------+----------------------------------+ 1732 Table 2 1734 8.3. Warn Code Registry 1736 Please add a note to the "Hypertext Transfer Protocol (HTTP) Warn 1737 Codes" registry at 1738 to the effect that Warning is obsoleted. 1740 9. References 1742 9.1. Normative References 1744 [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 1745 Ed., "HTTP Semantics", Work in Progress, Internet-Draft, 1746 draft-ietf-httpbis-semantics-18, 18 August 2021, 1747 . 1750 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1751 Requirement Levels", BCP 14, RFC 2119, 1752 DOI 10.17487/RFC2119, March 1997, 1753 . 1755 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1756 Specifications: ABNF", STD 68, RFC 5234, 1757 DOI 10.17487/RFC5234, January 2008, 1758 . 1760 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 1761 RFC 7405, DOI 10.17487/RFC7405, December 2014, 1762 . 1764 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1765 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1766 May 2017, . 1768 9.2. Informative References 1770 [COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1771 DOI 10.17487/RFC6265, April 2011, 1772 . 1774 [HTTP/1.1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 1775 Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft- 1776 ietf-httpbis-messaging-18, 18 August 2021, 1777 . 1780 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1781 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1782 Transfer Protocol -- HTTP/1.1", RFC 2616, 1783 DOI 10.17487/RFC2616, June 1999, 1784 . 1786 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1787 Content", RFC 5861, DOI 10.17487/RFC5861, April 2010, 1788 . 1790 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. F. Reschke, 1791 Ed., "Hypertext Transfer Protocol (HTTP): Caching", 1792 RFC 7234, DOI 10.17487/RFC7234, June 2014, 1793 . 1795 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1796 Writing an IANA Considerations Section in RFCs", BCP 26, 1797 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1798 . 1800 Appendix A. Collected ABNF 1802 In the collected ABNF below, list rules are expanded as per 1803 Section 5.6.1.1 of [HTTP]. 1805 Age = delta-seconds 1807 Cache-Control = [ cache-directive *( OWS "," OWS cache-directive ) ] 1809 Expires = HTTP-date 1811 HTTP-date = 1813 OWS = 1815 cache-directive = token [ "=" ( token / quoted-string ) ] 1817 delta-seconds = 1*DIGIT 1819 field-name = 1821 quoted-string = 1823 token = 1825 Appendix B. Changes from RFC 7234 1827 Handling of duplicate and conflicting cache directives has been 1828 clarified. (Section 4.2.1) 1830 Cache invalidation of the URIs in the Location and Content-Location 1831 header fields is no longer required, but still allowed. 1832 (Section 4.4) 1834 Cache invalidation of the URIs in the Location and Content-Location 1835 header fields is disallowed when the origin is different; previously, 1836 it was the host. (Section 4.4) 1837 Handling invalid and multiple Age header field values has been 1838 clarified. (Section 5.1) 1840 Some cache directives defined by this specification now have stronger 1841 prohibitions against generating the quoted form of their values, 1842 since this has been found to create interoperability problems. 1843 Consumers of extension cache directives are no longer required to 1844 accept both token and quoted-string forms, but they still need to 1845 parse them properly for unknown extensions. (Section 5.2) 1847 The "public" and "private" cache directives were clarified, so that 1848 they do not make responses reusable under any condition. 1849 (Section 5.2.2) 1851 The "must-understand" cache directive was introduced; caches are no 1852 longer required to understand the semantics of new response status 1853 codes unless it is present. (Section 5.2.2.3) 1855 The Warning response header was obsoleted. Much of the information 1856 supported by Warning could be gleaned by examining the response, and 1857 the remaining warn-codes - although potentially useful - were 1858 entirely advisory. In practice, Warning was not added by caches or 1859 intermediaries. (Section 5.5) 1861 Appendix C. Change Log 1863 This section is to be removed before publishing as an RFC. 1865 C.1. Between RFC7234 and draft 00 1867 The changes were purely editorial: 1869 * Change boilerplate and abstract to indicate the "draft" status, 1870 and update references to ancestor specifications. 1872 * Remove version "1.1" from document title, indicating that this 1873 specification applies to all HTTP versions. 1875 * Adjust historical notes. 1877 * Update links to sibling specifications. 1879 * Replace sections listing changes from RFC 2616 by new empty 1880 sections referring to RFC 723x. 1882 * Remove acknowledgements specific to RFC 723x. 1884 * Move "Acknowledgements" to the very end and make them unnumbered. 1886 C.2. Since draft-ietf-httpbis-cache-00 1888 The changes are purely editorial: 1890 * Moved all extensibility tips, registration procedures, and 1891 registry tables from the IANA considerations to normative 1892 sections, reducing the IANA considerations to just instructions 1893 that will be removed prior to publication as an RFC. 1895 C.3. Since draft-ietf-httpbis-cache-01 1897 * Cite RFC 8126 instead of RFC 5226 () 1900 * In Section 5.4, misleading statement about the relation between 1901 Pragma and Cache-Control (, ) 1904 C.4. Since draft-ietf-httpbis-cache-02 1906 * In Section 3, explain that only final responses are cacheable 1907 () 1909 * In Section 5.2.2, clarify what responses various directives apply 1910 to () 1912 * In Section 4.3.1, clarify the source of validators in conditional 1913 requests () 1915 * Revise Section 6 to apply to more than just History Lists 1916 () 1918 * In Section 5.5, deprecated "Warning" header field 1919 () 1921 * In Section 3.5, remove a spurious note 1922 () 1924 C.5. Since draft-ietf-httpbis-cache-03 1926 * In Section 2, define what a disconnected cache is 1927 () 1929 * In Section 4, clarify language around how to select a response 1930 when more than one matches () 1933 * in Section 4.2.4, mention stale-while-revalidate and stale-if- 1934 error () 1936 * Remove requirements around cache request directives 1937 () 1939 * Deprecate Pragma () 1942 * In Section 3.5 and Section 5.2.2, note effect of some directives 1943 on authenticated requests () 1946 C.6. Since draft-ietf-httpbis-cache-04 1948 * In Section 5.2, remove the registrations for stale-if-error and 1949 stale-while-revalidate which happened in RFC 7234 1950 () 1952 C.7. Since draft-ietf-httpbis-cache-05 1954 * In Section 3.3, clarify how weakly framed content is considered 1955 for purposes of completeness () 1958 * Throughout, describe Vary and cache key operations more clearly 1959 () 1961 * In Section 3, remove concept of "cacheable methods" in favor of 1962 prose (, 1963 ) 1965 * Refactored Section 7, and added a section on timing attacks 1966 () 1968 * Changed "cacheable by default" to "heuristically cacheable" 1969 throughout () 1971 C.8. Since draft-ietf-httpbis-cache-06 1973 * In Section 3 and Section 5.2.2.3, change response cacheability to 1974 only require understanding the response status code if the must- 1975 understand cache directive is present () 1978 * Change requirements for handling different forms of cache 1979 directives in Section 5.2 () 1982 * Fix typo in Section 5.2.2.10 () 1985 * In Section 5.2.2.9 and Section 5.2.2.7, clarify "private" and 1986 "public" so that they do not override all other cache directives 1987 () 1989 * In Section 3, distinguish between private with and without 1990 qualifying headers () 1993 * In Section 4.1, clarify that any "*" as a member of Vary will 1994 disable caching () 1996 * In Section 1.1, reference RFC 8174 as well 1997 () 1999 C.9. Since draft-ietf-httpbis-cache-07 2001 * Throughout, replace "effective request URI", "request-target" and 2002 similar with "target URI" () 2005 * In Section 5.2.2.9 and Section 5.2.2.7, make it clear that these 2006 directives do not ignore other requirements for caching 2007 () 2009 * In Section 3.3, move definition of "complete" into semantics 2010 () 2012 C.10. Since draft-ietf-httpbis-cache-08 2014 * Appendix A now uses the sender variant of the "#" list expansion 2015 () 2017 C.11. Since draft-ietf-httpbis-cache-09 2019 * In Section 5.1, discuss handling of invalid and multiple Age 2020 header field values () 2023 * Switch to xml2rfc v3 mode for draft generation 2024 () 2026 C.12. Since draft-ietf-httpbis-cache-10 2028 * In Section 5.2 (Cache-Control), adjust ABNF to allow empty lists 2029 () 2031 C.13. Since draft-ietf-httpbis-cache-11 2033 * None. 2035 C.14. Since draft-ietf-httpbis-cache-12 2037 * In Section 4.2.4, remove 'no-store', as it won't be in cache in 2038 the first place (, 2039 ) 2041 * In Section 3.1, make it clear that only response headers need be 2042 stored () 2044 * Rewrote "Updating Stored Header Fields" Section 3.2 2045 () 2047 * In Section 4.2.1 clarify how to handle invalid and conflicting 2048 directives () 2050 * In Section 4.3.3, mention retry of failed validation requests 2051 () 2053 * In Section 4.3.3, clarify requirement on storing a full response 2054 to a conditional request () 2057 * In Section 5.1, clarify error handling 2058 () 2060 * In Section 4.2, remove spurious "UTC" () 2063 * In Section 4.2, correct the date-related rule names to consider 2064 case-insensitive () 2067 * In Section 6, strengthen recommendation for application caches to 2068 pay attention to cache directives () 2071 * In Section 4, mention collapsed requests 2072 () 2074 * In Section 4.4, relax requirements on Content-Location and 2075 Location invalidation () 2078 * In Section 4.3.4, refine the exceptions to update on a 304 2079 () 2081 * Moved table of Cache-Control directives into Section 8.2 2082 () 2084 * In Section 1.2, remove unused core ABNF rules 2085 () 2087 * Changed to using "payload data" when defining requirements about 2088 the data being conveyed within a message, instead of the terms 2089 "payload body" or "response body" or "representation body", since 2090 they often get confused with the HTTP/1.1 message body (which 2091 includes transfer coding) () 2094 C.15. Since draft-ietf-httpbis-cache-13 2096 * In Section 5.2.2.2, clarify requirements around generating an 2097 error response () 2099 * Changed to using "content" instead of "payload" or "payload data" 2100 to avoid confusion with the payload of version-specific messaging 2101 frames () 2103 * In Section 4.3.4, clarify how multiple validators are handled 2104 () 2106 * In Section 4.2.3, Section 5.2, and Section 5.2.2.4, remove notes 2107 about very old HTTP/1.0 behaviours () 2110 * In Section 5.2.2.3, modify operation to be more backwards- 2111 compatible with existing implementations 2112 () 2114 C.16. Since draft-ietf-httpbis-cache-14 2116 * Fix subsection ordering in Section 5.2.2 2117 () 2119 * In Section 2, define what a cache key is 2120 () 2122 * In Section 3.1, clarify what cache proxy headers apply to 2123 () 2125 * In Section 7.1, cache poisoning can affect private caches too 2126 () 2128 * In Section 5.1, adjust handling of invalid values to match most 2129 deployed caches () 2131 * In Section 5.3, mention parsing requirement relaxation 2132 () 2134 C.17. Since draft-ietf-httpbis-cache-15 2136 * In Section 4.3.1, tune description of relation between cache keys 2137 and validators () 2139 C.18. Since draft-ietf-httpbis-cache-16 2141 This draft addresses mostly editorial issues raised during or past 2142 IETF Last Call; see for a summary. 2145 Furthermore: 2147 * Addressed Genart last call review comments 2148 () 2150 * In Section 4.3.4, clarify that only selectable responses are 2151 updated () 2153 C.19. Since draft-ietf-httpbis-cache-17 2155 * Made reference to [HTTP/1.1] informative only 2156 () 2158 * Move cache-related aspects of validator use from [HTTP] into 2159 Section 4.3.1 () 2161 * Use term "clock" defined in Section 6.6.1 of [HTTP] throughout 2162 () 2164 * Throughout, disambiguate "selected representation" and "selected 2165 response" (now "chosen response") () 2168 Acknowledgements 2170 See Appendix "Acknowledgements" of [HTTP]. 2172 Index 2174 A C E F G H M N O P S V W 2176 A 2178 Age header field Section 5.1 2179 age Section 4.2 2181 C 2183 Cache-Control header field Section 5.2 2184 cache Section 1 2185 cache key Section 2; Section 2 2186 collapsed requests Section 4 2188 E 2190 Expires header field Section 5.3 2191 explicit expiration time Section 4.2 2193 F 2195 Fields 2196 Age Section 5.1; Section 5.1 2197 Cache-Control Section 5.2 2198 Expires Section 5.3; Section 5.3 2199 Pragma Section 5.4; Section 5.4 2200 Warning Section 5.5 2201 fresh Section 4.2 2202 freshness lifetime Section 4.2 2204 G 2206 Grammar 2207 Age Section 5.1 2208 Cache-Control Section 5.2 2209 DIGIT Section 1.2 2210 Expires Section 5.3 2211 cache-directive Section 5.2 2212 delta-seconds Section 1.2.2 2214 H 2216 Header Fields 2217 Age Section 5.1; Section 5.1 2218 Cache-Control Section 5.2 2219 Expires Section 5.3; Section 5.3 2220 Pragma Section 5.4; Section 5.4 2221 Warning Section 5.5 2222 heuristic expiration time Section 4.2 2223 heuristically cacheable Section 4.2.2 2225 M 2227 max-age (cache directive) Section 5.2.1.1; Section 5.2.2.1 2228 max-stale (cache directive) Section 5.2.1.2 2229 min-fresh (cache directive) Section 5.2.1.3 2230 must-revalidate (cache directive) Section 5.2.2.2 2231 must-understand (cache directive) Section 5.2.2.3 2233 N 2235 no-cache (cache directive) Section 5.2.1.4; Section 5.2.2.4 2236 no-store (cache directive) Section 5.2.1.5; Section 5.2.2.5 2237 no-transform (cache directive) Section 5.2.1.6; 2238 Section 5.2.2.6 2240 O 2242 only-if-cached (cache directive) Section 5.2.1.7 2244 P 2246 Pragma header field Section 5.4 2247 private (cache directive) Section 5.2.2.7 2248 private cache Section 1 2249 proxy-revalidate (cache directive) Section 5.2.2.8 2250 public (cache directive) Section 5.2.2.9 2252 S 2254 s-maxage (cache directive) Section 5.2.2.10 2255 shared cache Section 1 2256 stale Section 4.2 2258 V 2260 validator Section 4.3.1 2262 W 2264 Warning header field Section 5.5 2266 Authors' Addresses 2267 Roy T. Fielding (editor) 2268 Adobe 2269 345 Park Ave 2270 San Jose, CA 95110 2271 United States of America 2273 Email: fielding@gbiv.com 2274 URI: https://roy.gbiv.com/ 2276 Mark Nottingham (editor) 2277 Fastly 2278 Prahran VIC 2279 Australia 2281 Email: mnot@mnot.net 2282 URI: https://www.mnot.net/ 2284 Julian Reschke (editor) 2285 greenbytes GmbH 2286 Hafenweg 16 2287 48155 Münster 2288 Germany 2290 Email: julian.reschke@greenbytes.de 2291 URI: https://greenbytes.de/tech/webdav/