idnits 2.17.1 draft-ietf-httpbis-cache-19.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 (10 September 2021) is 959 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 1791, but no explicit reference was found in the text -- 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 (~~), 4 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: 14 March 2022 J. Reschke, Ed. 7 greenbytes 8 10 September 2021 10 HTTP Caching 11 draft-ietf-httpbis-cache-19 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.20. 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 14 March 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 C.20. Since draft-ietf-httpbis-cache-18 . . . . . . . . . . . . 46 170 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 47 171 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 172 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 49 174 1. Introduction 176 The Hypertext Transfer Protocol (HTTP) is a stateless application- 177 level request/response protocol that uses extensible semantics and 178 self-descriptive messages for flexible interaction with network-based 179 hypertext information systems. It is typically used for distributed 180 information systems, where the use of response caches can improve 181 performance. This document defines aspects of HTTP related to 182 caching and reusing response messages. 184 An HTTP _cache_ is a local store of response messages and the 185 subsystem that controls storage, retrieval, and deletion of messages 186 in it. A cache stores cacheable responses to reduce the response 187 time and network bandwidth consumption on future equivalent requests. 188 Any client or server MAY use a cache, though not when acting as a 189 tunnel (Section 3.7 of [HTTP]). 191 A _shared cache_ is a cache that stores responses for reuse by more 192 than one user; shared caches are usually (but not always) deployed as 193 a part of an intermediary. A _private cache_, in contrast, is 194 dedicated to a single user; often, they are deployed as a component 195 of a user agent. 197 The goal of HTTP caching is significantly improving performance by 198 reusing a prior response message to satisfy a current request. A 199 cache considers a stored response "fresh", as defined in Section 4.2, 200 if it can be reused without "validation" (checking with the origin 201 server to see if the cached response remains valid for this request). 202 A fresh response can therefore reduce both latency and network 203 overhead each time the cache reuses it. When a cached response is 204 not fresh, it might still be reusable if validation can freshen it 205 (Section 4.3) or if the origin is unavailable (Section 4.2.4). 207 This document obsoletes RFC 7234, with the changes being summarized 208 in Appendix B. 210 1.1. Requirements Notation 212 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 213 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 214 "OPTIONAL" in this document are to be interpreted as described in BCP 215 14 [RFC2119] [RFC8174] when, and only when, they appear in all 216 capitals, as shown here. 218 Section 2 of [HTTP] defines conformance criteria and contains 219 considerations regarding error handling. 221 1.2. Syntax Notation 223 This specification uses the Augmented Backus-Naur Form (ABNF) 224 notation of [RFC5234], extended with the notation for case- 225 sensitivity in strings defined in [RFC7405]. 227 It also uses a list extension, defined in Section 5.6.1 of [HTTP], 228 that allows for compact definition of comma-separated lists using a 229 '#' operator (similar to how the '*' operator indicates repetition). 230 Appendix A shows the collected grammar with all list operators 231 expanded to standard ABNF notation. 233 1.2.1. Imported Rules 235 The following core rule is included by reference, as defined in 236 [RFC5234], Appendix B.1: DIGIT (decimal 0-9). 238 [HTTP] defines the following rules: 240 HTTP-date = 241 OWS = 242 field-name = 243 quoted-string = 244 token = 246 1.2.2. Delta Seconds 248 The delta-seconds rule specifies a non-negative integer, representing 249 time in seconds. 251 delta-seconds = 1*DIGIT 253 A recipient parsing a delta-seconds value and converting it to binary 254 form ought to use an arithmetic type of at least 31 bits of non- 255 negative integer range. If a cache receives a delta-seconds value 256 greater than the greatest integer it can represent, or if any of its 257 subsequent calculations overflows, the cache MUST consider the value 258 to be 2147483648 (2^31) or the greatest positive integer it can 259 conveniently represent. 261 | *Note:* The value 2147483648 is here for historical reasons, 262 | represents infinity (over 68 years), and does not need to be 263 | stored in binary form; an implementation could produce it as a 264 | string if any overflow occurs, even if the calculations are 265 | performed with an arithmetic type incapable of directly 266 | representing that number. What matters here is that an 267 | overflow be detected and not treated as a negative value in 268 | later calculations. 270 2. Overview of Cache Operation 272 Proper cache operation preserves the semantics of HTTP transfers 273 while reducing the transmission of information already held in the 274 cache. See Section 3 of [HTTP] for the general terminology and core 275 concepts of HTTP. 277 Although caching is an entirely OPTIONAL feature of HTTP, it can be 278 assumed that reusing a cached response is desirable and that such 279 reuse is the default behavior when no requirement or local 280 configuration prevents it. Therefore, HTTP cache requirements are 281 focused on preventing a cache from either storing a non-reusable 282 response or reusing a stored response inappropriately, rather than 283 mandating that caches always store and reuse particular responses. 285 The _cache key_ is the information a cache uses to choose a response 286 and is composed from, at a minimum, the request method and target URI 287 used to retrieve the stored response; the method determines under 288 which circumstances that response can be used to satisfy a subsequent 289 request. However, many HTTP caches in common use today only cache 290 GET responses, and therefore only use the URI as the cache key, 291 forwarding other methods. 293 A cache might store multiple responses for a request target that is 294 subject to content negotiation. Caches differentiate these responses 295 by incorporating some of the original request's header fields into 296 the cache key as well, using information in the Vary response header 297 field, as per Section 4.1. 299 Caches might incorporate additional material into the cache key. For 300 example, user agent caches might include the referring site's 301 identity, thereby "double keying" the cache to avoid some privacy 302 risks (see Section 7.2). 304 Most commonly, caches store the successful result of a retrieval 305 request: i.e., a 200 (OK) response to a GET request, which contains a 306 representation of the target resource (Section 9.3.1 of [HTTP]). 307 However, it is also possible to store redirects, negative results 308 (e.g., 404 (Not Found)), incomplete results (e.g., 206 (Partial 309 Content)), and responses to methods other than GET if the method's 310 definition allows such caching and defines something suitable for use 311 as a cache key. 313 A cache is _disconnected_ when it cannot contact the origin server or 314 otherwise find a forward path for a request. A disconnected cache 315 can serve stale responses in some circumstances (Section 4.2.4). 317 3. Storing Responses in Caches 319 A cache MUST NOT store a response to a request unless: 321 * the request method is understood by the cache; 323 * the response status code is final (see Section 15 of [HTTP]); 325 * if the response status code is 206 or 304, or the "must- 326 understand" cache directive (see Section 5.2.2.3) is present: the 327 cache understands the response status code; 329 * the "no-store" cache directive is not present in the response (see 330 Section 5.2.2.5); 332 * if the cache is shared: the "private" response directive is either 333 not present or allows a shared cache to store a modified response; 334 see Section 5.2.2.7); 336 * if the cache is shared: the Authorization header field is not 337 present in the request (see Section 11.6.2 of [HTTP]) or a 338 response directive is present that explicitly allows shared 339 caching (see Section 3.5); and, 341 * the response contains at least one of: 343 - a public response directive (see Section 5.2.2.9); 345 - a private response directive, if the cache is not shared (see 346 Section 5.2.2.7); 348 - an Expires header field (see Section 5.3); 350 - a max-age response directive (see Section 5.2.2.1); 352 - if the cache is shared: an s-maxage response directive (see 353 Section 5.2.2.10); 355 - a Cache Control Extension that allows it to be cached (see 356 Section 5.2.3); or, 358 - a status code that is defined as heuristically cacheable (see 359 Section 4.2.2). 361 Note that a cache-control extension can override any of the 362 requirements listed; see Section 5.2.3. 364 In this context, a cache has "understood" a request method or a 365 response status code if it recognizes it and implements all specified 366 caching-related behavior. 368 Note that, in normal operation, some caches will not store a response 369 that has neither a cache validator nor an explicit expiration time, 370 as such responses are not usually useful to store. However, caches 371 are not prohibited from storing such responses. 373 3.1. Storing Header and Trailer Fields 375 Caches MUST include all received response header fields - including 376 unrecognised ones - when storing a response; this assures that new 377 HTTP header fields can be successfully deployed. However, the 378 following exceptions are made: 380 * The Connection header field and fields whose names are listed in 381 it are required by Section 7.6.1 of [HTTP] to be removed before 382 forwarding the message. This MAY be implemented by doing so 383 before storage. 385 * Likewise, some fields' semantics require them to be removed before 386 forwarding the message, and this MAY be implemented by doing so 387 before storage; see Section 7.6.1 of [HTTP] for some examples. 389 * The no-cache (Section 5.2.2.4) and private (Section 5.2.2.7) cache 390 directives can have arguments that prevent storage of header 391 fields by all caches and shared caches, respectively. 393 * Header fields that are specific to the proxy that a cache uses 394 when forwarding a request MUST NOT be stored, unless the cache 395 incorporates the identity of the proxy into the cache key. 396 Effectively, this is limited to Proxy-Authenticate (Section 11.7.1 397 of [HTTP]), Proxy-Authentication-Info (Section 11.7.3 of [HTTP]), 398 and Proxy-Authorization (Section 11.7.2 of [HTTP]). 400 Caches MAY either store trailer fields separate from header fields, 401 or discard them. Caches MUST NOT combine trailer fields with header 402 fields. 404 3.2. Updating Stored Header Fields 406 Caches are required to update a stored response's header fields from 407 another (typically newer) response in several situations; for 408 example, see Section 3.4, Section 4.3.4 and Section 4.3.5. 410 When doing so, the cache MUST add each header field in the provided 411 response to the stored response, replacing field values that are 412 already present, with the following exceptions: 414 * Header fields excepted from storage in Section 3.1, 416 * Header fields that the cache's stored response depends upon, as 417 described below, 419 * Header fields that are automatically processed and removed by the 420 recipient, as described below, and 422 * The Content-Length header field. 424 In some cases, caches (especially in user agents) store the results 425 of processing the received response, rather than the response itself, 426 and updating header fields that affect that processing can result in 427 inconsistent behavior and security issues. Caches in this situation 428 MAY omit these header fields from updating stored responses on an 429 exceptional basis, but SHOULD limit such omission to those fields 430 necessary to assure integrity of the stored response. 432 For example, a browser might decode the content coding of a response 433 while it is being received, creating a disconnect between the data it 434 has stored and the response's original metadata. Updating that 435 stored metadata with a different Content-Encoding header field would 436 be problematic. Likewise, a browser might store a post-parse HTML 437 tree, rather than the content received in the response; updating the 438 Content-Type header field would not be workable in this case, because 439 any assumptions about the format made in parsing would now be 440 invalid. 442 Furthermore, some fields are automatically processed and removed by 443 the HTTP implementation; for example, the Content-Range header field. 444 Implementations MAY automatically omit such header fields from 445 updates, even when the processing does not actually occur. 447 Note that the Content-* prefix is not a signal that a header field is 448 omitted from update; it is a convention for MIME header fields, not 449 HTTP. 451 3.3. Storing Incomplete Responses 453 If the request method is GET, the response status code is 200 (OK), 454 and the entire response header section has been received, a cache MAY 455 store a response body that is not complete (Section 3.4 of [HTTP]) if 456 the stored response is recorded as being incomplete. Likewise, a 206 457 (Partial Content) response MAY be stored as if it were an incomplete 458 200 (OK) response. However, a cache MUST NOT store incomplete or 459 partial-content responses if it does not support the Range and 460 Content-Range header fields or if it does not understand the range 461 units used in those fields. 463 A cache MAY complete a stored incomplete response by making a 464 subsequent range request (Section 14.2 of [HTTP]) and combining the 465 successful response with the stored response, as defined in 466 Section 3.4. A cache MUST NOT use an incomplete response to answer 467 requests unless the response has been made complete, or the request 468 is partial and specifies a range wholly within the incomplete 469 response. A cache MUST NOT send a partial response to a client 470 without explicitly marking it using the 206 (Partial Content) status 471 code. 473 3.4. Combining Partial Content 475 A response might transfer only a partial representation if the 476 connection closed prematurely or if the request used one or more 477 Range specifiers (Section 14.2 of [HTTP]). After several such 478 transfers, a cache might have received several ranges of the same 479 representation. A cache MAY combine these ranges into a single 480 stored response, and reuse that response to satisfy later requests, 481 if they all share the same strong validator and the cache complies 482 with the client requirements in Section 15.3.7.3 of [HTTP]. 484 When combining the new response with one or more stored responses, a 485 cache MUST update the stored response header fields using the header 486 fields provided in the new response, as per Section 3.2. 488 3.5. Storing Responses to Authenticated Requests 490 A shared cache MUST NOT use a cached response to a request with an 491 Authorization header field (Section 11.6.2 of [HTTP]) to satisfy any 492 subsequent request unless the response contains a Cache-Control field 493 with a response directive (Section 5.2.2) that allows it to be stored 494 by a shared cache and the cache conforms to the requirements of that 495 directive for that response. 497 In this specification, the following response directives have such an 498 effect: must-revalidate (Section 5.2.2.2), public (Section 5.2.2.9), 499 and s-maxage (Section 5.2.2.10). 501 4. Constructing Responses from Caches 503 When presented with a request, a cache MUST NOT reuse a stored 504 response unless: 506 * The presented target URI (Section 7.1 of [HTTP]) and that of the 507 stored response match, and 509 * the request method associated with the stored response allows it 510 to be used for the presented request, and 512 * request header fields nominated by the stored response (if any) 513 match those presented (see Section 4.1), and 515 * the stored response does not contain the no-cache cache directive 516 (Section 5.2.2.4), unless it is successfully validated 517 (Section 4.3), and 519 * the stored response is either: 521 - fresh (see Section 4.2), or 523 - allowed to be served stale (see Section 4.2.4), or 525 - successfully validated (see Section 4.3). 527 Note that a cache-control extension can override any of the 528 requirements listed; see Section 5.2.3. 530 When a stored response is used to satisfy a request without 531 validation, a cache MUST generate an Age header field (Section 5.1), 532 replacing any present in the response with a value equal to the 533 stored response's current_age; see Section 4.2.3. 535 A cache MUST write through requests with methods that are unsafe 536 (Section 9.2.1 of [HTTP]) to the origin server; i.e., a cache is not 537 allowed to generate a reply to such a request before having forwarded 538 the request and having received a corresponding response. 540 Also, note that unsafe requests might invalidate already-stored 541 responses; see Section 4.4. 543 A response that is stored or storable can be used to satisfy multiple 544 requests, provided that it is allowed to reuse that response for the 545 requests in question. This enables caches to _collapse requests_ - 546 or combine multiple incoming requests into a single forward request 547 upon a cache miss - thereby reducing load on the origin server and 548 network. However, note that if the response returned is not able to 549 be used for some or all of the collapsed requests, additional latency 550 might be introduced, because they will need to be forwarded to be 551 satisfied. 553 When more than one suitable response is stored, a cache MUST use the 554 most recent one (as determined by the Date header field). It can 555 also forward the request with "Cache-Control: max-age=0" or "Cache- 556 Control: no-cache" to disambiguate which response to use. 558 A cache without a clock (Section 5.6.7 of [HTTP]) MUST revalidate 559 stored responses upon every use. 561 4.1. Calculating Cache Keys with the Vary Header Field 563 When a cache receives a request that can be satisfied by a stored 564 response and that stored response contains a Vary header field 565 (Section 12.5.5 of [HTTP]), the cache MUST NOT use that stored 566 response without revalidation unless all the presented request header 567 fields nominated by that Vary field value match those fields in the 568 original request (i.e., the request that caused the cached response 569 to be stored). 571 The header fields from two requests are defined to match if and only 572 if those in the first request can be transformed to those in the 573 second request by applying any of: 575 * adding or removing whitespace, where allowed in the header field's 576 syntax 578 * combining multiple header field lines with the same field name 579 (see Section 5.2 of [HTTP]) 581 * normalizing both header field values in a way that is known to 582 have identical semantics, according to the header field's 583 specification (e.g., reordering field values when order is not 584 significant; case-normalization, where values are defined to be 585 case-insensitive) 587 If (after any normalization that might take place) a header field is 588 absent from a request, it can only match another request if it is 589 also absent there. 591 A stored response with a Vary header field value containing a member 592 "*" always fails to match. 594 If multiple stored responses match, the cache will need to choose one 595 to use. When a nominated request header field has a known mechanism 596 for ranking preference (e.g., qvalues on Accept and similar request 597 header fields), that mechanism MAY be used to choose a preferred 598 response. If such a mechanism is not available, or leads to equally 599 preferred responses, the most recent response (as determined by the 600 Date header field) is chosen, as per Section 4. 602 Some resources mistakenly omit the Vary header field from their 603 default response (i.e., the one sent when the request does not 604 express any preferences), with the effect of choosing it for 605 subsequent requests to that resource even when more preferable 606 responses are available. When a cache has multiple stored responses 607 for a target URI and one or more omits the Vary header field, the 608 cache SHOULD choose the most recent (see Section 4.2.3) stored 609 response with a valid Vary field value. 611 If no stored response matches, the cache cannot satisfy the presented 612 request. Typically, the request is forwarded to the origin server, 613 potentially with preconditions added to describe what responses the 614 cache has already stored (Section 4.3). 616 4.2. Freshness 618 A _fresh_ response is one whose age has not yet exceeded its 619 freshness lifetime. Conversely, a _stale_ response is one where it 620 has. 622 A response's _freshness lifetime_ is the length of time between its 623 generation by the origin server and its expiration time. An 624 _explicit expiration time_ is the time at which the origin server 625 intends that a stored response can no longer be used by a cache 626 without further validation, whereas a _heuristic expiration time_ is 627 assigned by a cache when no explicit expiration time is available. 629 A response's _age_ is the time that has passed since it was generated 630 by, or successfully validated with, the origin server. 632 When a response is fresh, it can be used to satisfy subsequent 633 requests without contacting the origin server, thereby improving 634 efficiency. 636 The primary mechanism for determining freshness is for an origin 637 server to provide an explicit expiration time in the future, using 638 either the Expires header field (Section 5.3) or the max-age response 639 directive (Section 5.2.2.1). Generally, origin servers will assign 640 future explicit expiration times to responses in the belief that the 641 representation is not likely to change in a semantically significant 642 way before the expiration time is reached. 644 If an origin server wishes to force a cache to validate every 645 request, it can assign an explicit expiration time in the past to 646 indicate that the response is already stale. Compliant caches will 647 normally validate a stale cached response before reusing it for 648 subsequent requests (see Section 4.2.4). 650 Since origin servers do not always provide explicit expiration times, 651 caches are also allowed to use a heuristic to determine an expiration 652 time under certain circumstances (see Section 4.2.2). 654 The calculation to determine if a response is fresh is: 656 response_is_fresh = (freshness_lifetime > current_age) 658 freshness_lifetime is defined in Section 4.2.1; current_age is 659 defined in Section 4.2.3. 661 Clients can send the max-age or min-fresh request directives 662 (Section 5.2.1) to suggest limits on the freshness calculations for 663 the corresponding response. However, caches are not required to 664 honor them. 666 When calculating freshness, to avoid common problems in date parsing: 668 * Although all date formats are specified to be case-sensitive, a 669 cache recipient SHOULD match the field value case-insensitively. 671 * If a cache recipient's internal implementation of time has less 672 resolution than the value of an HTTP-date, the recipient MUST 673 internally represent a parsed Expires date as the nearest time 674 equal to or earlier than the received value. 676 * A cache recipient MUST NOT allow local time zones to influence the 677 calculation or comparison of an age or expiration time. 679 * A cache recipient SHOULD consider a date with a zone abbreviation 680 other than "GMT" to be invalid for calculating expiration. 682 Note that freshness applies only to cache operation; it cannot be 683 used to force a user agent to refresh its display or reload a 684 resource. See Section 6 for an explanation of the difference between 685 caches and history mechanisms. 687 4.2.1. Calculating Freshness Lifetime 689 A cache can calculate the freshness lifetime (denoted as 690 freshness_lifetime) of a response by using the first match of: 692 * If the cache is shared and the s-maxage response directive 693 (Section 5.2.2.10) is present, use its value, or 695 * If the max-age response directive (Section 5.2.2.1) is present, 696 use its value, or 698 * If the Expires response header field (Section 5.3) is present, use 699 its value minus the value of the Date response header field (using 700 the time the message was received if it is not present, as per 701 Section 6.6.1 of [HTTP]), or 703 * Otherwise, no explicit expiration time is present in the response. 704 A heuristic freshness lifetime might be applicable; see 705 Section 4.2.2. 707 Note that this calculation is intended to reduce clock skew by using 708 the clock information provided by the origin server whenever 709 possible. 711 When there is more than one value present for a given directive 712 (e.g., two Expires header field lines or multiple Cache-Control: max- 713 age directives), either the first occurrence should be used, or the 714 response should be considered stale. If directives conflict (e.g., 715 both max-age and no-cache are present), the most restrictive 716 directive should be honored. Caches are encouraged to consider 717 responses that have invalid freshness information (e.g., a max-age 718 directive with non-integer content) to be stale. 720 4.2.2. Calculating Heuristic Freshness 722 Since origin servers do not always provide explicit expiration times, 723 a cache MAY assign a heuristic expiration time when an explicit time 724 is not specified, employing algorithms that use other field values 725 (such as the Last-Modified time) to estimate a plausible expiration 726 time. This specification does not provide specific algorithms, but 727 does impose worst-case constraints on their results. 729 A cache MUST NOT use heuristics to determine freshness when an 730 explicit expiration time is present in the stored response. Because 731 of the requirements in Section 3, this means that heuristics can only 732 be used on responses without explicit freshness whose status codes 733 are defined as _heuristically cacheable_ (e.g., see Section 15.1 of 734 [HTTP]), and those responses without explicit freshness that have 735 been marked as explicitly cacheable (e.g., with a "public" response 736 directive). 738 Note that in previous specifications heuristically cacheable response 739 status codes were called "cacheable by default." 741 If the response has a Last-Modified header field (Section 8.8.2 of 742 [HTTP]), caches are encouraged to use a heuristic expiration value 743 that is no more than some fraction of the interval since that time. 744 A typical setting of this fraction might be 10%. 746 | *Note:* Section 13.9 of [RFC2616] prohibited caches from 747 | calculating heuristic freshness for URIs with query components 748 | (i.e., those containing '?'). In practice, this has not been 749 | widely implemented. Therefore, origin servers are encouraged 750 | to send explicit directives (e.g., Cache-Control: no-cache) if 751 | they wish to prevent caching. 753 4.2.3. Calculating Age 755 The Age header field is used to convey an estimated age of the 756 response message when obtained from a cache. The Age field value is 757 the cache's estimate of the number of seconds since the origin server 758 generated or validated the response. The Age value is therefore the 759 sum of the time that the response has been resident in each of the 760 caches along the path from the origin server, plus the time it has 761 been in transit along network paths. 763 Age calculation uses the following data: 765 _age_value_ The term "age_value" denotes the value of the Age header 766 field (Section 5.1), in a form appropriate for arithmetic 767 operation; or 0, if not available. 769 _date_value_ The term "date_value" denotes the value of the Date 770 header field, in a form appropriate for arithmetic operations. 771 See Section 6.6.1 of [HTTP] for the definition of the Date header 772 field, and for requirements regarding responses without it. 774 _now_ The term "now" means the current value of this 775 implementation's clock (Section 5.6.7 of [HTTP]). 777 _request_time_ The value of the clock at the time of the request 778 that resulted in the stored response. 780 _response_time_ The value of the clock at the time the response was 781 received. 783 A response's age can be calculated in two entirely independent ways: 785 1. the "apparent_age": response_time minus date_value, if the 786 implementation's clock is reasonably well synchronized to the 787 origin server's clock. If the result is negative, the result is 788 replaced by zero. 790 2. the "corrected_age_value", if all of the caches along the 791 response path implement HTTP/1.1 or greater. A cache MUST 792 interpret this value relative to the time the request was 793 initiated, not the time that the response was received. 795 apparent_age = max(0, response_time - date_value); 797 response_delay = response_time - request_time; 798 corrected_age_value = age_value + response_delay; 800 The corrected_age_value MAY be used as the corrected_initial_age. In 801 circumstances where very old cache implementations that might not 802 correctly insert Age are present, corrected_initial_age can be 803 calculated more conservatively as 805 corrected_initial_age = max(apparent_age, corrected_age_value); 807 The current_age of a stored response can then be calculated by adding 808 the time (in seconds) since the stored response was last validated by 809 the origin server to the corrected_initial_age. 811 resident_time = now - response_time; 812 current_age = corrected_initial_age + resident_time; 814 4.2.4. Serving Stale Responses 816 A "stale" response is one that either has explicit expiry information 817 or is allowed to have heuristic expiry calculated, but is not fresh 818 according to the calculations in Section 4.2. 820 A cache MUST NOT generate a stale response if it is prohibited by an 821 explicit in-protocol directive (e.g., by a "no-cache" cache 822 directive, a "must-revalidate" cache-response-directive, or an 823 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 824 see Section 5.2.2). 826 A cache MUST NOT generate a stale response unless it is disconnected 827 or doing so is explicitly permitted by the client or origin server 828 (e.g., by the max-stale request directive in Section 5.2.1, by 829 extension directives such as those defined in [RFC5861], or by 830 configuration in accordance with an out-of-band contract). 832 4.3. Validation 834 When a cache has one or more stored responses for a requested URI, 835 but cannot serve any of them (e.g., because they are not fresh, or 836 one cannot be chosen; see Section 4.1), it can use the conditional 837 request mechanism (Section 13.1 of [HTTP]) in the forwarded request 838 to give the next inbound server an opportunity to choose a valid 839 stored response to use, updating the stored metadata in the process, 840 or to replace the stored response(s) with a new response. This 841 process is known as _validating_ or _revalidating_ the stored 842 response. 844 4.3.1. Sending a Validation Request 846 When generating a conditional request for validation, a cache starts 847 with either a request it is attempting to satisfy, or - if it is 848 initiating the request independently - it synthesises a request using 849 a stored response by copying the method, target URI, and request 850 header fields identified by the Vary header field (Section 4.1). 852 It then updates that request with one or more precondition header 853 fields. These contain validator metadata sourced from stored 854 response(s) that have the same URI. Typically, this will include 855 only those stored responses(s) that have the same cache key, although 856 a cache is allowed to validate a response that it cannot choose with 857 the request header fields it is sending (see Section 4.1). 859 The precondition header fields are then compared by recipients to 860 determine whether any stored response is equivalent to a current 861 representation of the resource. 863 One such validator is the timestamp given in a Last-Modified header 864 field (Section 8.8.2 of [HTTP]), which can be used in an If-Modified- 865 Since header field for response validation, or in an If-Unmodified- 866 Since or If-Range header field for representation selection (i.e., 867 the client is referring specifically to a previously obtained 868 representation with that timestamp). 870 Another validator is the entity-tag given in an ETag field 871 (Section 8.8.3 of [HTTP]). One or more entity-tags, indicating one 872 or more stored responses, can be used in an If-None-Match header 873 field for response validation, or in an If-Match or If-Range header 874 field for representation selection (i.e., the client is referring 875 specifically to one or more previously obtained representations with 876 the listed entity-tags). 878 When generating a conditional request for validation, a cache: 880 * MUST send the relevant entity-tags (using If-Match, If-None-Match, 881 or If-Range) if the entity-tags were provided in the stored 882 response(s) being validated. 884 * SHOULD send the Last-Modified value (using If-Modified-Since) if 885 the request is not for a subrange, a single stored response is 886 being validated, and that response contains a Last-Modified value. 888 * MAY send the Last-Modified value (using If-Unmodified-Since or If- 889 Range) if the request is for a subrange, a single stored response 890 is being validated, and that response contains only a Last- 891 Modified value (not an entity-tag). 893 In most cases, both validators are generated in cache validation 894 requests, even when entity-tags are clearly superior, to allow old 895 intermediaries that do not understand entity-tag preconditions to 896 respond appropriately. 898 4.3.2. Handling a Received Validation Request 900 Each client in the request chain may have its own cache, so it is 901 common for a cache at an intermediary to receive conditional requests 902 from other (outbound) caches. Likewise, some user agents make use of 903 conditional requests to limit data transfers to recently modified 904 representations or to complete the transfer of a partially retrieved 905 representation. 907 If a cache receives a request that can be satisfied by reusing a 908 stored 200 (OK) or 206 (Partial Content) response, as per Section 4, 909 the cache SHOULD evaluate any applicable conditional header field 910 preconditions received in that request with respect to the 911 corresponding validators contained within the stored response. 913 A cache MUST NOT evaluate conditional header fields that only apply 914 to an origin server, occur in a request with semantics that cannot be 915 satisfied with a cached response, or occur in a request with a target 916 resource for which it has no stored responses; such preconditions are 917 likely intended for some other (inbound) server. 919 The proper evaluation of conditional requests by a cache depends on 920 the received precondition header fields and their precedence. In 921 summary, the If-Match and If-Unmodified-Since conditional header 922 fields are not applicable to a cache, and If-None-Match takes 923 precedence over If-Modified-Since. See Section 13.2.2 of [HTTP] for 924 a complete specification of precondition precedence. 926 A request containing an If-None-Match header field (Section 13.1.2 of 927 [HTTP]) indicates that the client wants to validate one or more of 928 its own stored responses in comparison to the stored response chosen 929 by the cache (as per Section 4). 931 If an If-None-Match header field is not present, a request containing 932 an If-Modified-Since header field (Section 13.1.3 of [HTTP]) 933 indicates that the client wants to validate one or more of its own 934 stored responses by modification date. 936 If a request contains an If-Modified-Since header field and the Last- 937 Modified header field is not present in a stored response, a cache 938 SHOULD use the stored response's Date field value (or, if no Date 939 field is present, the time that the stored response was received) to 940 evaluate the conditional. 942 A cache that implements partial responses to range requests, as 943 defined in Section 14.2 of [HTTP], also needs to evaluate a received 944 If-Range header field (Section 13.1.5 of [HTTP]) with respect to the 945 cache's chosen response. 947 When a cache decides to forward a request to revalidate its own 948 stored responses for a request that contains an If-None-Match list of 949 entity-tags, the cache MAY combine the received list with a list of 950 entity-tags from its own stored set of responses (fresh or stale) and 951 send the union of the two lists as a replacement If-None-Match header 952 field value in the forwarded request. If a stored response contains 953 only partial content, the cache MUST NOT include its entity-tag in 954 the union unless the request is for a range that would be fully 955 satisfied by that partial stored response. If the response to the 956 forwarded request is 304 (Not Modified) and has an ETag field value 957 with an entity-tag that is not in the client's list, the cache MUST 958 generate a 200 (OK) response for the client by reusing its 959 corresponding stored response, as updated by the 304 response 960 metadata (Section 4.3.4). 962 4.3.3. Handling a Validation Response 964 Cache handling of a response to a conditional request depends upon 965 its status code: 967 * A 304 (Not Modified) response status code indicates that the 968 stored response can be updated and reused; see Section 4.3.4. 970 * A full response (i.e., one containing content) indicates that none 971 of the stored responses nominated in the conditional request is 972 suitable. Instead, the cache MUST use the full response to 973 satisfy the request. The cache MAY store such a full response, 974 subject to its constraints (see Section 3). 976 * However, if a cache receives a 5xx (Server Error) response while 977 attempting to validate a response, it can either forward this 978 response to the requesting client, or act as if the server failed 979 to respond. In the latter case, the cache can send a previously 980 stored response, subject to its constraints on doing so (see 981 Section 4.2.4), or retry the validation request. 983 4.3.4. Freshening Stored Responses upon Validation 985 When a cache receives a 304 (Not Modified) response, it needs to 986 identify stored responses that are suitable for updating with the new 987 information provided, and then do so. 989 The initial set of stored responses to update are those that could 990 have been chosen for that request - i.e., those that meet the 991 requirements in Section 4, except the last requirement to be fresh, 992 able to be served stale or just validated. 994 Then, that initial set of stored response(s) is further filtered by 995 the first match of: 997 * If the new response contains one or more _strong validators_ (see 998 Section 8.8.1 of [HTTP]), then each of those strong validators 999 identify a selected representation for update. All the stored 1000 responses in the initial set with one of those same strong 1001 validators are identified for update. If none of the initial set 1002 contain at least one of the same strong validators, then the cache 1003 MUST NOT use the new response to update any stored responses. 1005 * If the new response contains no strong validators but does contain 1006 one or more _weak validators_, and those validators correspond to 1007 one of the initial set's stored responses, then the most recent of 1008 those matching stored responses is identified for update. 1010 * If the new response does not include any form of validator (such 1011 as where a client generates an If-Modified-Since request from a 1012 source other than the Last-Modified response header field), and 1013 there is only one stored response in the initial set, and that 1014 stored response also lacks a validator, then that stored response 1015 is identified for update. 1017 For each stored response identified, the cache MUST update its header 1018 fields with the header fields provided in the 304 (Not Modified) 1019 response, as per Section 3.2. 1021 4.3.5. Freshening Responses with HEAD 1023 A response to the HEAD method is identical to what an equivalent 1024 request made with a GET would have been, without sending the content. 1025 This property of HEAD responses can be used to invalidate or update a 1026 cached GET response if the more efficient conditional GET request 1027 mechanism is not available (due to no validators being present in the 1028 stored response) or if transmission of the content is not desired 1029 even if it has changed. 1031 When a cache makes an inbound HEAD request for a target URI and 1032 receives a 200 (OK) response, the cache SHOULD update or invalidate 1033 each of its stored GET responses that could have been chosen for that 1034 request (see Section 4.1). 1036 For each of the stored responses that could have been chosen, if the 1037 stored response and HEAD response have matching values for any 1038 received validator fields (ETag and Last-Modified) and, if the HEAD 1039 response has a Content-Length header field, the value of Content- 1040 Length matches that of the stored response, the cache SHOULD update 1041 the stored response as described below; otherwise, the cache SHOULD 1042 consider the stored response to be stale. 1044 If a cache updates a stored response with the metadata provided in a 1045 HEAD response, the cache MUST use the header fields provided in the 1046 HEAD response to update the stored response (see Section 3.2). 1048 4.4. Invalidating Stored Responses 1050 Because unsafe request methods (Section 9.2.1 of [HTTP]) such as PUT, 1051 POST or DELETE have the potential for changing state on the origin 1052 server, intervening caches are required to invalidate stored 1053 responses to keep their contents up to date. 1055 A cache MUST invalidate the target URI (Section 7.1 of [HTTP]) when 1056 it receives a non-error status code in response to an unsafe request 1057 method (including methods whose safety is unknown). 1059 A cache MAY invalidate other URIs when it receives a non-error status 1060 code in response to an unsafe request method (including methods whose 1061 safety is unknown). In particular, the URI(s) in the Location and 1062 Content-Location response header fields (if present) are candidates 1063 for invalidation; other URIs might be discovered through mechanisms 1064 not specified in this document. However, a cache MUST NOT trigger an 1065 invalidation under these conditions if the origin (Section 4.3.1 of 1066 [HTTP]) of the URI to be invalidated differs from that of the target 1067 URI (Section 7.1 of [HTTP]). This helps prevent denial-of-service 1068 attacks. 1070 _Invalidate_ means that the cache will either remove all stored 1071 responses whose target URI matches the given URI, or will mark them 1072 as "invalid" and in need of a mandatory validation before they can be 1073 sent in response to a subsequent request. 1075 A "non-error response" is one with a 2xx (Successful) or 3xx 1076 (Redirection) status code. 1078 Note that this does not guarantee that all appropriate responses are 1079 invalidated globally; a state-changing request would only invalidate 1080 responses in the caches it travels through. 1082 5. Field Definitions 1084 This section defines the syntax and semantics of HTTP fields related 1085 to caching. 1087 5.1. Age 1089 The "Age" response header field conveys the sender's estimate of the 1090 time since the response was generated or successfully validated at 1091 the origin server. Age values are calculated as specified in 1092 Section 4.2.3. 1094 Age = delta-seconds 1096 The Age field value is a non-negative integer, representing time in 1097 seconds (see Section 1.2.2). 1099 Although it is defined as a singleton header field, a cache 1100 encountering a message with a list-based Age field value SHOULD use 1101 the first member of the field value, discarding subsequent ones. 1103 If the field value (after discarding additional members, as per 1104 above) is invalid (e.g., it contains something other than a non- 1105 negative integer), a cache SHOULD ignore the field. 1107 The presence of an Age header field implies that the response was not 1108 generated or validated by the origin server for this request. 1109 However, lack of an Age header field does not imply the origin was 1110 contacted. 1112 5.2. Cache-Control 1114 The "Cache-Control" header field is used to list directives for 1115 caches along the request/response chain. Such cache directives are 1116 unidirectional in that the presence of a directive in a request does 1117 not imply that the same directive is present in the response, or to 1118 be repeated in it. 1120 See Section 5.2.3 for information about how Cache-Control directives 1121 defined elsewhere are handled. 1123 A proxy, whether or not it implements a cache, MUST pass cache 1124 directives through in forwarded messages, regardless of their 1125 significance to that application, since the directives might apply to 1126 all recipients along the request/response chain. It is not possible 1127 to target a directive to a specific cache. 1129 Cache directives are identified by a token, to be compared case- 1130 insensitively, and have an optional argument that can use both token 1131 and quoted-string syntax. For the directives defined below that 1132 define arguments, recipients ought to accept both forms, even if a 1133 specific form is required for generation. 1135 Cache-Control = #cache-directive 1137 cache-directive = token [ "=" ( token / quoted-string ) ] 1139 For the cache directives defined below, no argument is defined (nor 1140 allowed) unless stated otherwise. 1142 5.2.1. Request Cache-Control Directives 1144 This section defines cache request directives. They are advisory; 1145 caches MAY implement them, but are not required to. 1147 5.2.1.1. max-age 1149 Argument syntax: 1151 delta-seconds (see Section 1.2.2) 1153 The "max-age" request directive indicates that the client prefers a 1154 response whose age is less than or equal to the specified number of 1155 seconds. Unless the max-stale request directive is also present, the 1156 client does not wish to receive a stale response. 1158 This directive uses the token form of the argument syntax: e.g., 1159 'max-age=5' not 'max-age="5"'. A sender MUST NOT generate the 1160 quoted-string form. 1162 5.2.1.2. max-stale 1164 Argument syntax: 1166 delta-seconds (see Section 1.2.2) 1168 The "max-stale" request directive indicates that the client will 1169 accept a response that has exceeded its freshness lifetime. If a 1170 value is present, then the client is willing to accept a response 1171 that has exceeded its freshness lifetime by no more than the 1172 specified number of seconds. If no value is assigned to max-stale, 1173 then the client will accept a stale response of any age. 1175 This directive uses the token form of the argument syntax: e.g., 1176 'max-stale=10' not 'max-stale="10"'. A sender MUST NOT generate the 1177 quoted-string form. 1179 5.2.1.3. min-fresh 1181 Argument syntax: 1183 delta-seconds (see Section 1.2.2) 1185 The "min-fresh" request directive indicates that the client prefers a 1186 response whose freshness lifetime is no less than its current age 1187 plus the specified time in seconds. That is, the client wants a 1188 response that will still be fresh for at least the specified number 1189 of seconds. 1191 This directive uses the token form of the argument syntax: e.g., 1192 'min-fresh=20' not 'min-fresh="20"'. A sender MUST NOT generate the 1193 quoted-string form. 1195 5.2.1.4. no-cache 1197 The "no-cache" request directive indicates that the client prefers 1198 stored response not be used to satisfy the request without successful 1199 validation on the origin server. 1201 5.2.1.5. no-store 1203 The "no-store" request directive indicates that a cache MUST NOT 1204 store any part of either this request or any response to it. This 1205 directive applies to both private and shared caches. "MUST NOT 1206 store" in this context means that the cache MUST NOT intentionally 1207 store the information in non-volatile storage, and MUST make a best- 1208 effort attempt to remove the information from volatile storage as 1209 promptly as possible after forwarding it. 1211 This directive is _not_ a reliable or sufficient mechanism for 1212 ensuring privacy. In particular, malicious or compromised caches 1213 might not recognize or obey this directive, and communications 1214 networks might be vulnerable to eavesdropping. 1216 Note that if a request containing this directive is satisfied from a 1217 cache, the no-store request directive does not apply to the already 1218 stored response. 1220 5.2.1.6. no-transform 1222 The "no-transform" request directive indicates that the client is 1223 asking for intermediaries to avoid transforming the content, as 1224 defined in Section 7.7 of [HTTP]. 1226 5.2.1.7. only-if-cached 1228 The "only-if-cached" request directive indicates that the client only 1229 wishes to obtain a stored response. Caches that honor this request 1230 directive SHOULD, upon receiving it, either respond using a stored 1231 response consistent with the other constraints of the request, or 1232 respond with a 504 (Gateway Timeout) status code. 1234 5.2.2. Response Cache-Control Directives 1236 This section defines cache response directives. A cache MUST obey 1237 the Cache-Control directives defined in this section. 1239 5.2.2.1. max-age 1241 Argument syntax: 1243 delta-seconds (see Section 1.2.2) 1245 The "max-age" response directive indicates that the response is to be 1246 considered stale after its age is greater than the specified number 1247 of seconds. 1249 This directive uses the token form of the argument syntax: e.g., 1250 'max-age=5' not 'max-age="5"'. A sender MUST NOT generate the 1251 quoted-string form. 1253 5.2.2.2. must-revalidate 1255 The "must-revalidate" response directive indicates that once the 1256 response has become stale, a cache MUST NOT reuse that response to 1257 satisfy another request until it has been successfully validated by 1258 the origin, as defined by Section 4.3. 1260 The must-revalidate directive is necessary to support reliable 1261 operation for certain protocol features. In all circumstances a 1262 cache MUST NOT ignore the must-revalidate directive; in particular, 1263 if a cache is disconnected, the cache MUST generate an error response 1264 rather than reuse the stale response. The generated status code 1265 SHOULD be 504 (Gateway Timeout) unless another error status code is 1266 more applicable. 1268 The must-revalidate directive ought to be used by servers if and only 1269 if failure to validate a request could cause incorrect operation, 1270 such as a silently unexecuted financial transaction. 1272 The must-revalidate directive also permits a shared cache to reuse a 1273 response to a request containing an Authorization header field 1274 (Section 11.6.2 of [HTTP]), subject to the above requirement on 1275 revalidation (Section 3.5). 1277 5.2.2.3. must-understand 1279 The "must-understand" response directive limits caching of the 1280 response to a cache that understands and conforms to the requirements 1281 for that response's status code. 1283 Responses containing "must-understand" SHOULD also contain the "no- 1284 store" directive; caches that implement "must-understand" SHOULD 1285 ignore the "no-store" directive in responses that contain both 1286 directives and a status code that the cache understands and conforms 1287 to any related caching requirements. 1289 5.2.2.4. no-cache 1291 Argument syntax: 1293 #field-name 1295 The "no-cache" response directive, in its unqualified form (without 1296 an argument), indicates that the response MUST NOT be used to satisfy 1297 any other request without forwarding it for validation and receiving 1298 a successful response; see Section 4.3. 1300 This allows an origin server to prevent a cache from using the 1301 response to satisfy a request without contacting it, even by caches 1302 that have been configured to send stale responses. 1304 The qualified form of no-cache response directive, with an argument 1305 that lists one or more field names, indicates that a cache MAY use 1306 the response to satisfy a subsequent request, subject to any other 1307 restrictions on caching, if the listed header fields are excluded 1308 from the subsequent response or the subsequent response has been 1309 successfully revalidated with the origin server (updating or removing 1310 those fields). This allows an origin server to prevent the re-use of 1311 certain header fields in a response, while still allowing caching of 1312 the rest of the response. 1314 The field names given are not limited to the set of header fields 1315 defined by this specification. Field names are case-insensitive. 1317 This directive uses the quoted-string form of the argument syntax. A 1318 sender SHOULD NOT generate the token form (even if quoting appears 1319 not to be needed for single-entry lists). 1321 | *Note:* The qualified form of the directive is often handled by 1322 | caches as if an unqualified no-cache directive was received; 1323 | i.e., the special handling for the qualified form is not widely 1324 | implemented. 1326 5.2.2.5. no-store 1328 The "no-store" response directive indicates that a cache MUST NOT 1329 store any part of either the immediate request or response, and MUST 1330 NOT use the response to satisfy any other request. 1332 This directive applies to both private and shared caches. "MUST NOT 1333 store" in this context means that the cache MUST NOT intentionally 1334 store the information in non-volatile storage, and MUST make a best- 1335 effort attempt to remove the information from volatile storage as 1336 promptly as possible after forwarding it. 1338 This directive is _not_ a reliable or sufficient mechanism for 1339 ensuring privacy. In particular, malicious or compromised caches 1340 might not recognize or obey this directive, and communications 1341 networks might be vulnerable to eavesdropping. 1343 Note that the "must-understand" cache directive overrides "no-store" 1344 in certain circumstances; see Section 5.2.2.3. 1346 5.2.2.6. no-transform 1348 The "no-transform" response directive indicates that an intermediary 1349 (regardless of whether it implements a cache) MUST NOT transform the 1350 content, as defined in Section 7.7 of [HTTP]. 1352 5.2.2.7. private 1354 Argument syntax: 1356 #field-name 1358 The unqualified "private" response directive indicates that a shared 1359 cache MUST NOT store the response (i.e., the response is intended for 1360 a single user). It also indicates that a private cache MAY store the 1361 response, subject the constraints defined in Section 3, even if the 1362 response would not otherwise be heuristically cacheable by a private 1363 cache. 1365 If a qualified private response directive is present, with an 1366 argument that lists one or more field names, then only the listed 1367 header fields are limited to a single user: a shared cache MUST NOT 1368 store the listed header fields if they are present in the original 1369 response, but MAY store the remainder of the response message without 1370 those header fields, subject the constraints defined in Section 3. 1372 The field names given are not limited to the set of header fields 1373 defined by this specification. Field names are case-insensitive. 1375 This directive uses the quoted-string form of the argument syntax. A 1376 sender SHOULD NOT generate the token form (even if quoting appears 1377 not to be needed for single-entry lists). 1379 | *Note:* This usage of the word "private" only controls where 1380 | the response can be stored; it cannot ensure the privacy of the 1381 | message content. Also, the qualified form of the directive is 1382 | often handled by caches as if an unqualified private directive 1383 | was received; i.e., the special handling for the qualified form 1384 | is not widely implemented. 1386 5.2.2.8. proxy-revalidate 1388 The "proxy-revalidate" response directive indicates that once the 1389 response has become stale, a shared cache MUST NOT reuse that 1390 response to satisfy another request until it has been successfully 1391 validated by the origin, as defined by Section 4.3. This is 1392 analogous to must-revalidate (Section 5.2.2.2), except that proxy- 1393 revalidate does not apply to private caches. 1395 Note that "proxy-revalidate" on its own does not imply that a 1396 response is cacheable. For example, it might be combined with the 1397 public directive (Section 5.2.2.9), allowing the response to be 1398 cached while requiring only a shared cache to revalidate when stale. 1400 5.2.2.9. public 1402 The "public" response directive indicates that a cache MAY store the 1403 response even if it would otherwise be prohibited, subject to the 1404 constraints defined in Section 3. In other words, public explicitly 1405 marks the response as cacheable. For example, public permits a 1406 shared cache to reuse a response to a request containing an 1407 Authorization header field (Section 3.5). 1409 Note that it is unnecessary to add the public directive to a response 1410 that is already cacheable according to Section 3. 1412 If a response with the public directive has no explicit freshness 1413 information, it is heuristically cacheable (Section 4.2.2). 1415 5.2.2.10. s-maxage 1417 Argument syntax: 1419 delta-seconds (see Section 1.2.2) 1421 The "s-maxage" response directive indicates that, for a shared cache, 1422 the maximum age specified by this directive overrides the maximum age 1423 specified by either the max-age directive or the Expires header 1424 field. 1426 The s-maxage directive incorporates the proxy-revalidate 1427 (Section 5.2.2.8) response directive's semantics for a shared cache. 1428 A shared cache MUST NOT reuse a stale response with s-maxage to 1429 satisfy another request until it has been successfully validated by 1430 the origin, as defined by Section 4.3. This directive also permits a 1431 shared cache to reuse a response to a request containing an 1432 Authorization header field, subject to the above requirements on 1433 maximum age and revalidation (Section 3.5). 1435 This directive uses the token form of the argument syntax: e.g., 1436 's-maxage=10' not 's-maxage="10"'. A sender MUST NOT generate the 1437 quoted-string form. 1439 5.2.3. Cache Control Extensions 1441 The Cache-Control header field can be extended through the use of one 1442 or more extension cache directives. A cache MUST ignore unrecognized 1443 cache directives. 1445 Informational extensions (those that do not require a change in cache 1446 behavior) can be added without changing the semantics of other 1447 directives. 1449 Behavioral extensions are designed to work by acting as modifiers to 1450 the existing base of cache directives. Both the new directive and 1451 the old directive are supplied, such that applications that do not 1452 understand the new directive will default to the behavior specified 1453 by the old directive, and those that understand the new directive 1454 will recognize it as modifying the requirements associated with the 1455 old directive. In this way, extensions to the existing cache-control 1456 directives can be made without breaking deployed caches. 1458 For example, consider a hypothetical new response directive called 1459 "community" that acts as a modifier to the private directive: in 1460 addition to private caches, any cache that is shared only by members 1461 of the named community is allowed to cache the response. An origin 1462 server wishing to allow the UCI community to use an otherwise private 1463 response in their shared cache(s) could do so by including 1465 Cache-Control: private, community="UCI" 1467 A cache that recognizes such a community cache directive could 1468 broaden its behavior in accordance with that extension. A cache that 1469 does not recognize the community cache directive would ignore it and 1470 adhere to the private directive. 1472 New extension directives ought to consider defining: 1474 * What it means for a directive to be specified multiple times, 1476 * When the directive does not take an argument, what it means when 1477 an argument is present, 1479 * When the directive requires an argument, what it means when it is 1480 missing, 1482 * Whether the directive is specific to requests, responses, or able 1483 to be used in either. 1485 5.2.4. Cache Directive Registry 1487 The "Hypertext Transfer Protocol (HTTP) Cache Directive Registry" 1488 defines the namespace for the cache directives. It has been created 1489 and is now maintained at . 1492 A registration MUST include the following fields: 1494 * Cache Directive Name 1496 * Pointer to specification text 1498 Values to be added to this namespace require IETF Review (see 1499 [RFC8126], Section 4.8). 1501 5.3. Expires 1503 The "Expires" response header field gives the date/time after which 1504 the response is considered stale. See Section 4.2 for further 1505 discussion of the freshness model. 1507 The presence of an Expires header field does not imply that the 1508 original resource will change or cease to exist at, before, or after 1509 that time. 1511 The Expires field value is an HTTP-date timestamp, as defined in 1512 Section 5.6.7 of [HTTP]. See also Section 4.2 for parsing 1513 requirements specific to caches. 1515 Expires = HTTP-date 1517 For example 1519 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1521 A cache recipient MUST interpret invalid date formats, especially the 1522 value "0", as representing a time in the past (i.e., "already 1523 expired"). 1525 If a response includes a Cache-Control header field with the max-age 1526 directive (Section 5.2.2.1), a recipient MUST ignore the Expires 1527 header field. Likewise, if a response includes the s-maxage 1528 directive (Section 5.2.2.10), a shared cache recipient MUST ignore 1529 the Expires header field. In both these cases, the value in Expires 1530 is only intended for recipients that have not yet implemented the 1531 Cache-Control header field. 1533 An origin server without a clock (Section 5.6.7 of [HTTP]) MUST NOT 1534 generate an Expires header field unless its value represents a fixed 1535 time in the past (always expired) or its value has been associated 1536 with the resource by a system with a clock. 1538 Historically, HTTP required the Expires field value to be no more 1539 than a year in the future. While longer freshness lifetimes are no 1540 longer prohibited, extremely large values have been demonstrated to 1541 cause problems (e.g., clock overflows due to use of 32-bit integers 1542 for time values), and many caches will evict a response far sooner 1543 than that. 1545 5.4. Pragma 1547 The "Pragma" request header field was defined for HTTP/1.0 caches, so 1548 that clients could specify a "no-cache" request (as Cache-Control was 1549 not defined until HTTP/1.1). 1551 However, support for Cache-Control is now widespread. As a result, 1552 this specification deprecates Pragma. 1554 | *Note:* Because the meaning of "Pragma: no-cache" in responses 1555 | was never specified, it does not provide a reliable replacement 1556 | for "Cache-Control: no-cache" in them. 1558 5.5. Warning 1560 The "Warning" header field was used to carry additional information 1561 about the status or transformation of a message that might not be 1562 reflected in the status code. This specification obsoletes it, as it 1563 is not widely generated or surfaced to users. The information it 1564 carried can be gleaned from examining other header fields, such as 1565 Age. 1567 6. Relationship to Applications and Other Caches 1569 Applications using HTTP often specify additional forms of caching. 1570 For example, Web browsers often have history mechanisms such as 1571 "Back" buttons that can be used to redisplay a representation 1572 retrieved earlier in a session. 1574 Likewise, some Web browsers implement caching of images and other 1575 assets within a page view; they may or may not honor HTTP caching 1576 semantics. 1578 The requirements in this specification do not necessarily apply to 1579 how applications use data after it is retrieved from an HTTP cache. 1580 For example, a history mechanism can display a previous 1581 representation even if it has expired, and an application can use 1582 cached data in other ways beyond its freshness lifetime. 1584 This specification does not prohibit the application from taking HTTP 1585 caching into account; for example, a history mechanism might tell the 1586 user that a view is stale, or it might honor cache directives (e.g., 1587 Cache-Control: no-store). 1589 However, when an application caches data and does not make this 1590 apparent to or easily controllable by the user, it is strongly 1591 encouraged to define its operation with respect to HTTP cache 1592 directives, so as not to surprise authors who expect caching 1593 semantics to be honoured. For example, while it might be reasonable 1594 to define an application cache "above" HTTP that allows a response 1595 containing Cache-Control: no-store to be reused for requests that are 1596 directly related to the request that fetched it (such as those 1597 created during the same page load), it would likely be surprising and 1598 confusing to users and authors if it were allowed to be reused for 1599 requests unrelated in any way to the one from which it was obtained. 1601 7. Security Considerations 1603 This section is meant to inform developers, information providers, 1604 and users of known security concerns specific to HTTP caching. More 1605 general security considerations are addressed in "HTTP/1.1" 1606 (Section 11 of [HTTP/1.1]) and "HTTP Semantics" (Section 17 of 1607 [HTTP]). 1609 Caches expose an additional attack surface, since the contents of the 1610 cache represent an attractive target for malicious exploitation. 1611 Because cache contents persist after an HTTP request is complete, an 1612 attack on the cache can reveal information long after a user believes 1613 that the information has been removed from the network. Therefore, 1614 cache contents need to be protected as sensitive information. 1616 In particular, because private caches are restricted to a single 1617 user, they can be used to reconstruct a user's activity. As a 1618 result, it is important for user agents to allow end users to control 1619 them; for example, allowing stored responses to be removed for some 1620 or all origin servers. 1622 7.1. Cache Poisoning 1624 Storing a malicious payload in a cache can extend the reach of an 1625 attacker to affect multiple users. Such "cache poisoning" attacks 1626 happen when an attacker uses implementation flaws, elevated 1627 privileges, or other techniques to insert a response into a cache. 1628 This is especially effective when shared caches are used to 1629 distribute malicious content to many clients. 1631 One common attack vector for cache poisoning is to exploit 1632 differences in message parsing on proxies and in user agents; see 1633 Section 6.3 of [HTTP/1.1] for the relevant requirements regarding 1634 HTTP/1.1. 1636 7.2. Timing Attacks 1638 Because one of the primary uses of a cache is to optimise 1639 performance, its use can "leak" information about what resources have 1640 been previously requested. 1642 For example, if a user visits a site and their browser caches some of 1643 its responses, and then navigates to a second site, that site can 1644 attempt to load responses it knows exists on the first site. If they 1645 load quickly, it can be assumed that the user has visited that site, 1646 or even a specific page on it. 1648 Such "timing attacks" can be mitigated by adding more information to 1649 the cache key, such as the identity of the referring site (to prevent 1650 the attack described above). This is sometimes called "double 1651 keying." 1653 7.3. Caching of Sensitive Information 1655 Implementation and deployment flaws (as well as misunderstanding of 1656 cache operation) might lead to caching of sensitive information 1657 (e.g., authentication credentials) that is thought to be private, 1658 exposing it to unauthorized parties. 1660 Note that the Set-Cookie response header field [COOKIE] does not 1661 inhibit caching; a cacheable response with a Set-Cookie header field 1662 can be (and often is) used to satisfy subsequent requests to caches. 1663 Servers who wish to control caching of these responses are encouraged 1664 to emit appropriate Cache-Control response header fields. 1666 8. IANA Considerations 1668 The change controller for the following registrations is: "IETF 1669 (iesg@ietf.org) - Internet Engineering Task Force". 1671 8.1. Field Name Registration 1673 First, introduce the new "Hypertext Transfer Protocol (HTTP) Field 1674 Name Registry" at as 1675 described in Section 18.4 of [HTTP]. 1677 Then, please update the registry with the field names listed in the 1678 table below: 1680 +===============+===========+======+==========+ 1681 | Field Name | Status | Ref. | Comments | 1682 +===============+===========+======+==========+ 1683 | Age | standard | 5.1 | | 1684 +---------------+-----------+------+----------+ 1685 | Cache-Control | standard | 5.2 | | 1686 +---------------+-----------+------+----------+ 1687 | Expires | standard | 5.3 | | 1688 +---------------+-----------+------+----------+ 1689 | Pragma | standard | 5.4 | | 1690 +---------------+-----------+------+----------+ 1691 | Warning | obsoleted | 5.5 | | 1692 +---------------+-----------+------+----------+ 1694 Table 1 1696 8.2. Cache Directive Registration 1698 Please update the "Hypertext Transfer Protocol (HTTP) Cache Directive 1699 Registry" at 1700 with the registration procedure of Section 5.2.4 and the cache 1701 directive names summarized in the table below. 1703 +==================+==================================+ 1704 | Cache Directive | Reference | 1705 +==================+==================================+ 1706 | max-age | Section 5.2.1.1, Section 5.2.2.1 | 1707 +------------------+----------------------------------+ 1708 | max-stale | Section 5.2.1.2 | 1709 +------------------+----------------------------------+ 1710 | min-fresh | Section 5.2.1.3 | 1711 +------------------+----------------------------------+ 1712 | must-revalidate | Section 5.2.2.2 | 1713 +------------------+----------------------------------+ 1714 | must-understand | Section 5.2.2.3 | 1715 +------------------+----------------------------------+ 1716 | no-cache | Section 5.2.1.4, Section 5.2.2.4 | 1717 +------------------+----------------------------------+ 1718 | no-store | Section 5.2.1.5, Section 5.2.2.5 | 1719 +------------------+----------------------------------+ 1720 | no-transform | Section 5.2.1.6, Section 5.2.2.6 | 1721 +------------------+----------------------------------+ 1722 | only-if-cached | Section 5.2.1.7 | 1723 +------------------+----------------------------------+ 1724 | private | Section 5.2.2.7 | 1725 +------------------+----------------------------------+ 1726 | proxy-revalidate | Section 5.2.2.8 | 1727 +------------------+----------------------------------+ 1728 | public | Section 5.2.2.9 | 1729 +------------------+----------------------------------+ 1730 | s-maxage | Section 5.2.2.10 | 1731 +------------------+----------------------------------+ 1733 Table 2 1735 8.3. Warn Code Registry 1737 Please add a note to the "Hypertext Transfer Protocol (HTTP) Warn 1738 Codes" registry at 1739 to the effect that Warning is obsoleted. 1741 9. References 1743 9.1. Normative References 1745 [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 1746 Ed., "HTTP Semantics", Work in Progress, Internet-Draft, 1747 draft-ietf-httpbis-semantics-19, 10 September 2021, 1748 . 1751 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1752 Requirement Levels", BCP 14, RFC 2119, 1753 DOI 10.17487/RFC2119, March 1997, 1754 . 1756 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1757 Specifications: ABNF", STD 68, RFC 5234, 1758 DOI 10.17487/RFC5234, January 2008, 1759 . 1761 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 1762 RFC 7405, DOI 10.17487/RFC7405, December 2014, 1763 . 1765 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1766 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1767 May 2017, . 1769 9.2. Informative References 1771 [COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1772 DOI 10.17487/RFC6265, April 2011, 1773 . 1775 [HTTP/1.1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 1776 Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft- 1777 ietf-httpbis-messaging-19, 10 September 2021, 1778 . 1781 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1782 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1783 Transfer Protocol -- HTTP/1.1", RFC 2616, 1784 DOI 10.17487/RFC2616, June 1999, 1785 . 1787 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1788 Content", RFC 5861, DOI 10.17487/RFC5861, April 2010, 1789 . 1791 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. F. Reschke, 1792 Ed., "Hypertext Transfer Protocol (HTTP): Caching", 1793 RFC 7234, DOI 10.17487/RFC7234, June 2014, 1794 . 1796 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1797 Writing an IANA Considerations Section in RFCs", BCP 26, 1798 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1799 . 1801 Appendix A. Collected ABNF 1803 In the collected ABNF below, list rules are expanded as per 1804 Section 5.6.1 of [HTTP]. 1806 Age = delta-seconds 1808 Cache-Control = [ cache-directive *( OWS "," OWS cache-directive ) ] 1810 Expires = HTTP-date 1812 HTTP-date = 1814 OWS = 1816 cache-directive = token [ "=" ( token / quoted-string ) ] 1818 delta-seconds = 1*DIGIT 1820 field-name = 1822 quoted-string = 1824 token = 1826 Appendix B. Changes from RFC 7234 1828 Handling of duplicate and conflicting cache directives has been 1829 clarified. (Section 4.2.1) 1831 Cache invalidation of the URIs in the Location and Content-Location 1832 header fields is no longer required, but still allowed. 1833 (Section 4.4) 1835 Cache invalidation of the URIs in the Location and Content-Location 1836 header fields is disallowed when the origin is different; previously, 1837 it was the host. (Section 4.4) 1838 Handling invalid and multiple Age header field values has been 1839 clarified. (Section 5.1) 1841 Some cache directives defined by this specification now have stronger 1842 prohibitions against generating the quoted form of their values, 1843 since this has been found to create interoperability problems. 1844 Consumers of extension cache directives are no longer required to 1845 accept both token and quoted-string forms, but they still need to 1846 parse them properly for unknown extensions. (Section 5.2) 1848 The "public" and "private" cache directives were clarified, so that 1849 they do not make responses reusable under any condition. 1850 (Section 5.2.2) 1852 The "must-understand" cache directive was introduced; caches are no 1853 longer required to understand the semantics of new response status 1854 codes unless it is present. (Section 5.2.2.3) 1856 The Warning response header was obsoleted. Much of the information 1857 supported by Warning could be gleaned by examining the response, and 1858 the remaining warn-codes - although potentially useful - were 1859 entirely advisory. In practice, Warning was not added by caches or 1860 intermediaries. (Section 5.5) 1862 Appendix C. Change Log 1864 This section is to be removed before publishing as an RFC. 1866 C.1. Between RFC7234 and draft 00 1868 The changes were purely editorial: 1870 * Change boilerplate and abstract to indicate the "draft" status, 1871 and update references to ancestor specifications. 1873 * Remove version "1.1" from document title, indicating that this 1874 specification applies to all HTTP versions. 1876 * Adjust historical notes. 1878 * Update links to sibling specifications. 1880 * Replace sections listing changes from RFC 2616 by new empty 1881 sections referring to RFC 723x. 1883 * Remove acknowledgements specific to RFC 723x. 1885 * Move "Acknowledgements" to the very end and make them unnumbered. 1887 C.2. Since draft-ietf-httpbis-cache-00 1889 The changes are purely editorial: 1891 * Moved all extensibility tips, registration procedures, and 1892 registry tables from the IANA considerations to normative 1893 sections, reducing the IANA considerations to just instructions 1894 that will be removed prior to publication as an RFC. 1896 C.3. Since draft-ietf-httpbis-cache-01 1898 * Cite RFC 8126 instead of RFC 5226 () 1901 * In Section 5.4, misleading statement about the relation between 1902 Pragma and Cache-Control (, ) 1905 C.4. Since draft-ietf-httpbis-cache-02 1907 * In Section 3, explain that only final responses are cacheable 1908 () 1910 * In Section 5.2.2, clarify what responses various directives apply 1911 to () 1913 * In Section 4.3.1, clarify the source of validators in conditional 1914 requests () 1916 * Revise Section 6 to apply to more than just History Lists 1917 () 1919 * In Section 5.5, deprecated "Warning" header field 1920 () 1922 * In Section 3.5, remove a spurious note 1923 () 1925 C.5. Since draft-ietf-httpbis-cache-03 1927 * In Section 2, define what a disconnected cache is 1928 () 1930 * In Section 4, clarify language around how to select a response 1931 when more than one matches () 1934 * in Section 4.2.4, mention stale-while-revalidate and stale-if- 1935 error () 1937 * Remove requirements around cache request directives 1938 () 1940 * Deprecate Pragma () 1943 * In Section 3.5 and Section 5.2.2, note effect of some directives 1944 on authenticated requests () 1947 C.6. Since draft-ietf-httpbis-cache-04 1949 * In Section 5.2, remove the registrations for stale-if-error and 1950 stale-while-revalidate which happened in RFC 7234 1951 () 1953 C.7. Since draft-ietf-httpbis-cache-05 1955 * In Section 3.3, clarify how weakly framed content is considered 1956 for purposes of completeness () 1959 * Throughout, describe Vary and cache key operations more clearly 1960 () 1962 * In Section 3, remove concept of "cacheable methods" in favor of 1963 prose (, 1964 ) 1966 * Refactored Section 7, and added a section on timing attacks 1967 () 1969 * Changed "cacheable by default" to "heuristically cacheable" 1970 throughout () 1972 C.8. Since draft-ietf-httpbis-cache-06 1974 * In Section 3 and Section 5.2.2.3, change response cacheability to 1975 only require understanding the response status code if the must- 1976 understand cache directive is present () 1979 * Change requirements for handling different forms of cache 1980 directives in Section 5.2 () 1983 * Fix typo in Section 5.2.2.10 () 1986 * In Section 5.2.2.9 and Section 5.2.2.7, clarify "private" and 1987 "public" so that they do not override all other cache directives 1988 () 1990 * In Section 3, distinguish between private with and without 1991 qualifying headers () 1994 * In Section 4.1, clarify that any "*" as a member of Vary will 1995 disable caching () 1997 * In Section 1.1, reference RFC 8174 as well 1998 () 2000 C.9. Since draft-ietf-httpbis-cache-07 2002 * Throughout, replace "effective request URI", "request-target" and 2003 similar with "target URI" () 2006 * In Section 5.2.2.9 and Section 5.2.2.7, make it clear that these 2007 directives do not ignore other requirements for caching 2008 () 2010 * In Section 3.3, move definition of "complete" into semantics 2011 () 2013 C.10. Since draft-ietf-httpbis-cache-08 2015 * Appendix A now uses the sender variant of the "#" list expansion 2016 () 2018 C.11. Since draft-ietf-httpbis-cache-09 2020 * In Section 5.1, discuss handling of invalid and multiple Age 2021 header field values () 2024 * Switch to xml2rfc v3 mode for draft generation 2025 () 2027 C.12. Since draft-ietf-httpbis-cache-10 2029 * In Section 5.2 (Cache-Control), adjust ABNF to allow empty lists 2030 () 2032 C.13. Since draft-ietf-httpbis-cache-11 2034 * None. 2036 C.14. Since draft-ietf-httpbis-cache-12 2038 * In Section 4.2.4, remove 'no-store', as it won't be in cache in 2039 the first place (, 2040 ) 2042 * In Section 3.1, make it clear that only response headers need be 2043 stored () 2045 * Rewrote "Updating Stored Header Fields" Section 3.2 2046 () 2048 * In Section 4.2.1 clarify how to handle invalid and conflicting 2049 directives () 2051 * In Section 4.3.3, mention retry of failed validation requests 2052 () 2054 * In Section 4.3.3, clarify requirement on storing a full response 2055 to a conditional request () 2058 * In Section 5.1, clarify error handling 2059 () 2061 * In Section 4.2, remove spurious "UTC" () 2064 * In Section 4.2, correct the date-related rule names to consider 2065 case-insensitive () 2068 * In Section 6, strengthen recommendation for application caches to 2069 pay attention to cache directives () 2072 * In Section 4, mention collapsed requests 2073 () 2075 * In Section 4.4, relax requirements on Content-Location and 2076 Location invalidation () 2079 * In Section 4.3.4, refine the exceptions to update on a 304 2080 () 2082 * Moved table of Cache-Control directives into Section 8.2 2083 () 2085 * In Section 1.2, remove unused core ABNF rules 2086 () 2088 * Changed to using "payload data" when defining requirements about 2089 the data being conveyed within a message, instead of the terms 2090 "payload body" or "response body" or "representation body", since 2091 they often get confused with the HTTP/1.1 message body (which 2092 includes transfer coding) () 2095 C.15. Since draft-ietf-httpbis-cache-13 2097 * In Section 5.2.2.2, clarify requirements around generating an 2098 error response () 2100 * Changed to using "content" instead of "payload" or "payload data" 2101 to avoid confusion with the payload of version-specific messaging 2102 frames () 2104 * In Section 4.3.4, clarify how multiple validators are handled 2105 () 2107 * In Section 4.2.3, Section 5.2, and Section 5.2.2.4, remove notes 2108 about very old HTTP/1.0 behaviours () 2111 * In Section 5.2.2.3, modify operation to be more backwards- 2112 compatible with existing implementations 2113 () 2115 C.16. Since draft-ietf-httpbis-cache-14 2117 * Fix subsection ordering in Section 5.2.2 2118 () 2120 * In Section 2, define what a cache key is 2121 () 2123 * In Section 3.1, clarify what cache proxy headers apply to 2124 () 2126 * In Section 7.1, cache poisoning can affect private caches too 2127 () 2129 * In Section 5.1, adjust handling of invalid values to match most 2130 deployed caches () 2132 * In Section 5.3, mention parsing requirement relaxation 2133 () 2135 C.17. Since draft-ietf-httpbis-cache-15 2137 * In Section 4.3.1, tune description of relation between cache keys 2138 and validators () 2140 C.18. Since draft-ietf-httpbis-cache-16 2142 This draft addresses mostly editorial issues raised during or past 2143 IETF Last Call; see for a summary. 2146 Furthermore: 2148 * Addressed Genart last call review comments 2149 () 2151 * In Section 4.3.4, clarify that only selectable responses are 2152 updated () 2154 C.19. Since draft-ietf-httpbis-cache-17 2156 * Made reference to [HTTP/1.1] informative only 2157 () 2159 * Move cache-related aspects of validator use from [HTTP] into 2160 Section 4.3.1 () 2162 * Use term "clock" defined in Section 6.6.1 of [HTTP] throughout 2163 () 2165 * Throughout, disambiguate "selected representation" and "selected 2166 response" (now "chosen response") () 2169 C.20. Since draft-ietf-httpbis-cache-18 2171 * None. 2173 Acknowledgements 2175 See Appendix "Acknowledgements" of [HTTP]. 2177 Index 2179 A C E F G H M N O P S V W 2181 A 2183 Age header field Section 5.1 2184 age Section 4.2 2186 C 2188 Cache-Control header field Section 5.2 2189 cache Section 1 2190 cache key Section 2; Section 2 2191 collapsed requests Section 4 2193 E 2195 Expires header field Section 5.3 2196 explicit expiration time Section 4.2 2198 F 2200 Fields 2201 Age Section 5.1; Section 5.1 2202 Cache-Control Section 5.2 2203 Expires Section 5.3; Section 5.3 2204 Pragma Section 5.4; Section 5.4 2205 Warning Section 5.5 2206 fresh Section 4.2 2207 freshness lifetime Section 4.2 2209 G 2211 Grammar 2212 Age Section 5.1 2213 Cache-Control Section 5.2 2214 DIGIT Section 1.2 2215 Expires Section 5.3 2216 cache-directive Section 5.2 2217 delta-seconds Section 1.2.2 2219 H 2221 Header Fields 2222 Age Section 5.1; Section 5.1 2223 Cache-Control Section 5.2 2224 Expires Section 5.3; Section 5.3 2225 Pragma Section 5.4; Section 5.4 2226 Warning Section 5.5 2227 heuristic expiration time Section 4.2 2228 heuristically cacheable Section 4.2.2 2230 M 2232 max-age (cache directive) Section 5.2.1.1; Section 5.2.2.1 2233 max-stale (cache directive) Section 5.2.1.2 2234 min-fresh (cache directive) Section 5.2.1.3 2235 must-revalidate (cache directive) Section 5.2.2.2 2236 must-understand (cache directive) Section 5.2.2.3 2238 N 2240 no-cache (cache directive) Section 5.2.1.4; Section 5.2.2.4 2241 no-store (cache directive) Section 5.2.1.5; Section 5.2.2.5 2242 no-transform (cache directive) Section 5.2.1.6; 2243 Section 5.2.2.6 2245 O 2247 only-if-cached (cache directive) Section 5.2.1.7 2249 P 2251 Pragma header field Section 5.4 2252 private (cache directive) Section 5.2.2.7 2253 private cache Section 1 2254 proxy-revalidate (cache directive) Section 5.2.2.8 2255 public (cache directive) Section 5.2.2.9 2257 S 2259 s-maxage (cache directive) Section 5.2.2.10 2260 shared cache Section 1 2261 stale Section 4.2 2263 V 2265 validator Section 4.3.1 2267 W 2269 Warning header field Section 5.5 2271 Authors' Addresses 2273 Roy T. Fielding (editor) 2274 Adobe 2275 345 Park Ave 2276 San Jose, CA 95110 2277 United States of America 2279 Email: fielding@gbiv.com 2280 URI: https://roy.gbiv.com/ 2282 Mark Nottingham (editor) 2283 Fastly 2284 Prahran VIC 2285 Australia 2287 Email: mnot@mnot.net 2288 URI: https://www.mnot.net/ 2290 Julian Reschke (editor) 2291 greenbytes GmbH 2292 Hafenweg 16 2293 48155 Münster 2294 Germany 2296 Email: julian.reschke@greenbytes.de 2297 URI: https://greenbytes.de/tech/webdav/