idnits 2.17.1 draft-ietf-httpbis-cache-17.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 (26 July 2021) is 977 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 1779, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-17 -- Possible downref: Normative reference to a draft: ref. 'HTTP' -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 7234 (Obsoleted by RFC 9111) Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP Working Group R. Fielding, Ed. 3 Internet-Draft Adobe 4 Obsoletes: 7234 (if approved) M. Nottingham, Ed. 5 Intended status: Standards Track Fastly 6 Expires: 27 January 2022 J. Reschke, Ed. 7 greenbytes 8 26 July 2021 10 HTTP Caching 11 draft-ietf-httpbis-cache-17 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.18. 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 27 January 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 . . . . . . . . . . . . . . . . . . . . . . . 19 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 . . . . . . . . . . . . 44 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 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 46 169 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 170 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 172 1. Introduction 174 The Hypertext Transfer Protocol (HTTP) is a stateless application- 175 level request/response protocol that uses extensible semantics and 176 self-descriptive messages for flexible interaction with network-based 177 hypertext information systems. It is typically used for distributed 178 information systems, where the use of response caches can improve 179 performance. This document defines aspects of HTTP related to 180 caching and reusing response messages. 182 An HTTP _cache_ is a local store of response messages and the 183 subsystem that controls storage, retrieval, and deletion of messages 184 in it. A cache stores cacheable responses to reduce the response 185 time and network bandwidth consumption on future equivalent requests. 186 Any client or server MAY use a cache, though not when acting as a 187 tunnel (Section 3.7 of [HTTP]). 189 A _shared cache_ is a cache that stores responses for reuse by more 190 than one user; shared caches are usually (but not always) deployed as 191 a part of an intermediary. A _private cache_, in contrast, is 192 dedicated to a single user; often, they are deployed as a component 193 of a user agent. 195 The goal of HTTP caching is significantly improving performance by 196 reusing a prior response message to satisfy a current request. A 197 cache considers a stored response "fresh", as defined in Section 4.2, 198 if it can be reused without "validation" (checking with the origin 199 server to see if the cached response remains valid for this request). 200 A fresh response can therefore reduce both latency and network 201 overhead each time the cache reuses it. When a cached response is 202 not fresh, it might still be reusable if validation can freshen it 203 (Section 4.3) or if the origin is unavailable (Section 4.2.4). 205 This document obsoletes RFC 7234, with the changes being summarized 206 in Appendix B. 208 1.1. Requirements Notation 210 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 211 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 212 "OPTIONAL" in this document are to be interpreted as described in BCP 213 14 [RFC2119] [RFC8174] when, and only when, they appear in all 214 capitals, as shown here. 216 Section 2 of [HTTP] defines conformance criteria and contains 217 considerations regarding error handling. 219 1.2. Syntax Notation 221 This specification uses the Augmented Backus-Naur Form (ABNF) 222 notation of [RFC5234], extended with the notation for case- 223 sensitivity in strings defined in [RFC7405]. 225 It also uses a list extension, defined in Section 5.6.1 of [HTTP], 226 that allows for compact definition of comma-separated lists using a 227 '#' operator (similar to how the '*' operator indicates repetition). 228 Appendix A shows the collected grammar with all list operators 229 expanded to standard ABNF notation. 231 1.2.1. Imported Rules 233 The following core rule is included by reference, as defined in 234 [RFC5234], Appendix B.1: DIGIT (decimal 0-9). 236 [HTTP] defines the following rules: 238 HTTP-date = 239 OWS = 240 field-name = 241 quoted-string = 242 token = 244 1.2.2. Delta Seconds 246 The delta-seconds rule specifies a non-negative integer, representing 247 time in seconds. 249 delta-seconds = 1*DIGIT 251 A recipient parsing a delta-seconds value and converting it to binary 252 form ought to use an arithmetic type of at least 31 bits of non- 253 negative integer range. If a cache receives a delta-seconds value 254 greater than the greatest integer it can represent, or if any of its 255 subsequent calculations overflows, the cache MUST consider the value 256 to be 2147483648 (2^31) or the greatest positive integer it can 257 conveniently represent. 259 | *Note:* The value 2147483648 is here for historical reasons, 260 | represents infinity (over 68 years), and does not need to be 261 | stored in binary form; an implementation could produce it as a 262 | string if any overflow occurs, even if the calculations are 263 | performed with an arithmetic type incapable of directly 264 | representing that number. What matters here is that an 265 | overflow be detected and not treated as a negative value in 266 | later calculations. 268 2. Overview of Cache Operation 270 Proper cache operation preserves the semantics of HTTP transfers 271 while reducing the transmission of information already held in the 272 cache. See Section 3 of [HTTP] for the general terminology and core 273 concepts of HTTP. 275 Although caching is an entirely OPTIONAL feature of HTTP, it can be 276 assumed that reusing a cached response is desirable and that such 277 reuse is the default behavior when no requirement or local 278 configuration prevents it. Therefore, HTTP cache requirements are 279 focused on preventing a cache from either storing a non-reusable 280 response or reusing a stored response inappropriately, rather than 281 mandating that caches always store and reuse particular responses. 283 The _cache key_ is the information a cache uses to select a response 284 and is composed from, at a minimum, the request method and target URI 285 used to retrieve the stored response; the method determines under 286 which circumstances that response can be used to satisfy a subsequent 287 request. However, many HTTP caches in common use today only cache 288 GET responses, and therefore only use the URI as the cache key, 289 forwarding other methods. 291 If a request target is subject to content negotiation, the cache 292 might store multiple responses for it. Caches differentiate these 293 responses by incorporating values of the original request's selecting 294 header fields into the cache key as well, using information in the 295 Vary response header field, as per Section 4.1. 297 Caches might incorporate additional material into the cache key. For 298 example, user agent caches might include the referring site's 299 identity, thereby "double keying" the cache to avoid some privacy 300 risks (see Section 7.2). 302 Most commonly, caches store the successful result of a retrieval 303 request: i.e., a 200 (OK) response to a GET request, which contains a 304 representation of the target resource (Section 9.3.1 of [HTTP]). 305 However, it is also possible to store redirects, negative results 306 (e.g., 404 (Not Found)), incomplete results (e.g., 206 (Partial 307 Content)), and responses to methods other than GET if the method's 308 definition allows such caching and defines something suitable for use 309 as a cache key. 311 A cache is _disconnected_ when it cannot contact the origin server or 312 otherwise find a forward path for a request. A disconnected cache 313 can serve stale responses in some circumstances (Section 4.2.4). 315 3. Storing Responses in Caches 317 A cache MUST NOT store a response to a request unless: 319 * the request method is understood by the cache; 321 * the response status code is final (see Section 15 of [HTTP]); 323 * if the response status code is 206 or 304, or the "must- 324 understand" cache directive (see Section 5.2.2.3) is present: the 325 cache understands the response status code; 327 * the "no-store" cache directive is not present in the response (see 328 Section 5.2.2.5); 330 * if the cache is shared: the "private" response directive is either 331 not present or allows a shared cache to store a modified response; 332 see Section 5.2.2.7); 334 * if the cache is shared: the Authorization header field is not 335 present in the request (see Section 11.6.2 of [HTTP]) or a 336 response directive is present that explicitly allows shared 337 caching (see Section 3.5); and, 339 * the response contains at least one of: 341 - a public response directive (see Section 5.2.2.9); 343 - a private response directive, if the cache is not shared (see 344 Section 5.2.2.7); 346 - an Expires header field (see Section 5.3); 348 - a max-age response directive (see Section 5.2.2.1); 350 - if the cache is shared: an s-maxage response directive (see 351 Section 5.2.2.10); 353 - a Cache Control Extension that allows it to be cached (see 354 Section 5.2.3); or, 356 - a status code that is defined as heuristically cacheable (see 357 Section 4.2.2). 359 Note that a cache-control extension can override any of the 360 requirements listed; see Section 5.2.3. 362 In this context, a cache has "understood" a request method or a 363 response status code if it recognizes it and implements all specified 364 caching-related behavior. 366 Note that, in normal operation, some caches will not store a response 367 that has neither a cache validator nor an explicit expiration time, 368 as such responses are not usually useful to store. However, caches 369 are not prohibited from storing such responses. 371 3.1. Storing Header and Trailer Fields 373 Caches MUST include all received response header fields - including 374 unrecognised ones - when storing a response; this assures that new 375 HTTP header fields can be successfully deployed. However, the 376 following exceptions are made: 378 * The Connection header field and fields whose names are listed in 379 it are required by Section 7.6.1 of [HTTP] to be removed before 380 forwarding the message. This MAY be implemented by doing so 381 before storage. 383 * Likewise, some fields' semantics require them to be removed before 384 forwarding the message, and this MAY be implemented by doing so 385 before storage; see Section 7.6.1 of [HTTP] for some examples. 387 * The no-cache (Section 5.2.2.4) and private (Section 5.2.2.7) cache 388 directives can have arguments that prevent storage of header 389 fields by all caches and shared caches, respectively. 391 * Header fields that are specific to the proxy that a cache uses 392 when forwarding a request MUST NOT be stored, unless the cache 393 incorporates the identity of the proxy into the cache key. 394 Effectively, this is limited to Proxy-Authenticate (Section 11.7.1 395 of [HTTP]), Proxy-Authentication-Info (Section 11.7.3 of [HTTP]), 396 and Proxy-Authorization (Section 11.7.2 of [HTTP]). 398 Caches MAY either store trailer fields separate from header fields, 399 or discard them. Caches MUST NOT combine trailer fields with header 400 fields. 402 3.2. Updating Stored Header Fields 404 Caches are required to update a stored response's header fields from 405 another (typically newer) response in several situations; for 406 example, see Section 3.4, Section 4.3.4 and Section 4.3.5. 408 When doing so, the cache MUST add each header field in the provided 409 response to the stored response, replacing field values that are 410 already present, with the following exceptions: 412 * Header fields excepted from storage in Section 3.1, 414 * Header fields that the cache's stored response depends upon, as 415 described below, 417 * Header fields that are automatically processed and removed by the 418 recipient, as described below, and 420 * The Content-Length header field. 422 In some cases, caches (especially in user agents) store the results 423 of processing the received response, rather than the response itself, 424 and updating header fields that affect that processing can result in 425 inconsistent behavior and security issues. Caches in this situation 426 MAY omit these header fields from updating stored responses on an 427 exceptional basis, but SHOULD limit such omission to those fields 428 necessary to assure integrity of the stored response. 430 For example, a browser might decode the content coding of a response 431 while it is being received, creating a disconnect between the data it 432 has stored and the response's original metadata. Updating that 433 stored metadata with a different Content-Encoding header field would 434 be problematic. Likewise, a browser might store a post-parse HTML 435 tree, rather than the content received in the response; updating the 436 Content-Type header field would not be workable in this case, because 437 any assumptions about the format made in parsing would now be 438 invalid. 440 Furthermore, some fields are automatically processed and removed by 441 the HTTP implementation; for example, the Content-Range header field. 442 Implementations MAY automatically omit such header fields from 443 updates, even when the processing does not actually occur. 445 Note that the Content-* prefix is not a signal that a header field is 446 omitted from update; it is a convention for MIME header fields, not 447 HTTP. 449 3.3. Storing Incomplete Responses 451 If the request method is GET, the response status code is 200 (OK), 452 and the entire response header section has been received, a cache MAY 453 store a response body that is not complete (Section 3.4 of [HTTP]) if 454 the stored response is recorded as being incomplete. Likewise, a 206 455 (Partial Content) response MAY be stored as if it were an incomplete 456 200 (OK) response. However, a cache MUST NOT store incomplete or 457 partial-content responses if it does not support the Range and 458 Content-Range header fields or if it does not understand the range 459 units used in those fields. 461 A cache MAY complete a stored incomplete response by making a 462 subsequent range request (Section 14.2 of [HTTP]) and combining the 463 successful response with the stored response, as defined in 464 Section 3.4. A cache MUST NOT use an incomplete response to answer 465 requests unless the response has been made complete, or the request 466 is partial and specifies a range wholly within the incomplete 467 response. A cache MUST NOT send a partial response to a client 468 without explicitly marking it using the 206 (Partial Content) status 469 code. 471 3.4. Combining Partial Content 473 A response might transfer only a partial representation if the 474 connection closed prematurely or if the request used one or more 475 Range specifiers (Section 14.2 of [HTTP]). After several such 476 transfers, a cache might have received several ranges of the same 477 representation. A cache MAY combine these ranges into a single 478 stored response, and reuse that response to satisfy later requests, 479 if they all share the same strong validator and the cache complies 480 with the client requirements in Section 15.3.7.3 of [HTTP]. 482 When combining the new response with one or more stored responses, a 483 cache MUST update the stored response header fields using the header 484 fields provided in the new response, as per Section 3.2. 486 3.5. Storing Responses to Authenticated Requests 488 A shared cache MUST NOT use a cached response to a request with an 489 Authorization header field (Section 11.6.2 of [HTTP]) to satisfy any 490 subsequent request unless the response contains a Cache-Control field 491 with a response directive (Section 5.2.2) that allows it to be stored 492 by a shared cache and the cache conforms to the requirements of that 493 directive for that response. 495 In this specification, the following response directives have such an 496 effect: must-revalidate (Section 5.2.2.2), public (Section 5.2.2.9), 497 and s-maxage (Section 5.2.2.10). 499 4. Constructing Responses from Caches 501 When presented with a request, a cache MUST NOT reuse a stored 502 response unless: 504 * The presented target URI (Section 7.1 of [HTTP]) and that of the 505 stored response match, and 507 * the request method associated with the stored response allows it 508 to be used for the presented request, and 510 * selecting header fields nominated by the stored response (if any) 511 match those presented (see Section 4.1), and 513 * the stored response does not contain the no-cache cache directive 514 (Section 5.2.2.4), unless it is successfully validated 515 (Section 4.3), and 517 * the stored response is either: 519 - fresh (see Section 4.2), or 521 - allowed to be served stale (see Section 4.2.4), or 523 - successfully validated (see Section 4.3). 525 Note that a cache-control extension can override any of the 526 requirements listed; see Section 5.2.3. 528 When a stored response is used to satisfy a request without 529 validation, a cache MUST generate an Age header field (Section 5.1), 530 replacing any present in the response with a value equal to the 531 stored response's current_age; see Section 4.2.3. 533 A cache MUST write through requests with methods that are unsafe 534 (Section 9.2.1 of [HTTP]) to the origin server; i.e., a cache is not 535 allowed to generate a reply to such a request before having forwarded 536 the request and having received a corresponding response. 538 Also, note that unsafe requests might invalidate already-stored 539 responses; see Section 4.4. 541 A response that is stored or storable can be used to satisfy multiple 542 requests, provided that it is allowed to reuse that response for the 543 requests in question. This enables caches to _collapse requests_ - 544 or combine multiple incoming requests into a single forward request 545 upon a cache miss - thereby reducing load on the origin server and 546 network. However, note that if the response returned is not able to 547 be used for some or all of the collapsed requests, additional latency 548 might be introduced, because they will need to be forwarded to be 549 satisfied. 551 When more than one suitable response is stored, a cache MUST use the 552 most recent one (as determined by the Date header field). It can 553 also forward the request with "Cache-Control: max-age=0" or "Cache- 554 Control: no-cache" to disambiguate which response to use. 556 A cache that does not have a clock available MUST NOT use stored 557 responses without revalidating them upon every use. 559 4.1. Calculating Cache Keys with the Vary Header Field 561 When a cache receives a request that can be satisfied by a stored 562 response and that stored response contains a Vary header field 563 (Section 12.5.5 of [HTTP]), the cache MUST NOT use that stored 564 response without revalidation unless all the selecting header fields 565 (nominated by that Vary field value) in the present request match 566 those fields in the original request (i.e., the request that caused 567 the cached response to be stored). 569 The selecting header fields from two requests are defined to match if 570 and only if those in the first request can be transformed to those in 571 the second request by applying any of: 573 * adding or removing whitespace, where allowed in the header field's 574 syntax 576 * combining multiple header field lines with the same field name 577 (see Section 5.2 of [HTTP]) 579 * normalizing both header field values in a way that is known to 580 have identical semantics, according to the header field's 581 specification (e.g., reordering field values when order is not 582 significant; case-normalization, where values are defined to be 583 case-insensitive) 585 If (after any normalization that might take place) a header field is 586 absent from a request, it can only match another request if it is 587 also absent there. 589 A stored response with a Vary header field value containing a member 590 "*" always fails to match. 592 The stored response with matching selecting header fields is known as 593 the _selected response_. 595 If multiple selected responses are available (potentially including 596 responses without a Vary header field), the cache will need to choose 597 one to use. When a selecting header field has a known mechanism for 598 doing so (e.g., qvalues on Accept and similar request header fields), 599 that mechanism MAY be used to select a preferred response. If such a 600 mechanism is not available, or leads to equally preferred responses, 601 the most recent response (as determined by the Date header field) is 602 used, as per Section 4. 604 Some resources mistakenly omit the Vary header field from their 605 default response (i.e., the one sent when no more preferable response 606 is available), with the effect of selecting it for requests to that 607 resource even when more preferable responses are available. When a 608 cache has multiple responses for a target URI and one or more omits 609 the Vary header field, it SHOULD use the most recent (see 610 Section 4.2.3) valid Vary field value available to select an 611 appropriate response for the request. 613 If no selected response is available, the cache cannot satisfy the 614 presented request. Typically, it is forwarded to the origin server 615 in a (possibly conditional; see Section 4.3) request. 617 4.2. Freshness 619 A _fresh_ response is one whose age has not yet exceeded its 620 freshness lifetime. Conversely, a _stale_ response is one where it 621 has. 623 A response's _freshness lifetime_ is the length of time between its 624 generation by the origin server and its expiration time. An 625 _explicit expiration time_ is the time at which the origin server 626 intends that a stored response can no longer be used by a cache 627 without further validation, whereas a _heuristic expiration time_ is 628 assigned by a cache when no explicit expiration time is available. 630 A response's _age_ is the time that has passed since it was generated 631 by, or successfully validated with, the origin server. 633 When a response is fresh, it can be used to satisfy subsequent 634 requests without contacting the origin server, thereby improving 635 efficiency. 637 The primary mechanism for determining freshness is for an origin 638 server to provide an explicit expiration time in the future, using 639 either the Expires header field (Section 5.3) or the max-age response 640 directive (Section 5.2.2.1). Generally, origin servers will assign 641 future explicit expiration times to responses in the belief that the 642 representation is not likely to change in a semantically significant 643 way before the expiration time is reached. 645 If an origin server wishes to force a cache to validate every 646 request, it can assign an explicit expiration time in the past to 647 indicate that the response is already stale. Compliant caches will 648 normally validate a stale cached response before reusing it for 649 subsequent requests (see Section 4.2.4). 651 Since origin servers do not always provide explicit expiration times, 652 caches are also allowed to use a heuristic to determine an expiration 653 time under certain circumstances (see Section 4.2.2). 655 The calculation to determine if a response is fresh is: 657 response_is_fresh = (freshness_lifetime > current_age) 659 freshness_lifetime is defined in Section 4.2.1; current_age is 660 defined in Section 4.2.3. 662 Clients can send the max-age or min-fresh request directives 663 (Section 5.2.1) to suggest limits on the freshness calculations for 664 the corresponding response. However, caches are not required to 665 honor them. 667 When calculating freshness, to avoid common problems in date parsing: 669 * Although all date formats are specified to be case-sensitive, a 670 cache recipient SHOULD match the field value case-insensitively. 672 * If a cache recipient's internal implementation of time has less 673 resolution than the value of an HTTP-date, the recipient MUST 674 internally represent a parsed Expires date as the nearest time 675 equal to or earlier than the received value. 677 * A cache recipient MUST NOT allow local time zones to influence the 678 calculation or comparison of an age or expiration time. 680 * A cache recipient SHOULD consider a date with a zone abbreviation 681 other than "GMT" to be invalid for calculating expiration. 683 Note that freshness applies only to cache operation; it cannot be 684 used to force a user agent to refresh its display or reload a 685 resource. See Section 6 for an explanation of the difference between 686 caches and history mechanisms. 688 4.2.1. Calculating Freshness Lifetime 690 A cache can calculate the freshness lifetime (denoted as 691 freshness_lifetime) of a response by using the first match of: 693 * If the cache is shared and the s-maxage response directive 694 (Section 5.2.2.10) is present, use its value, or 696 * If the max-age response directive (Section 5.2.2.1) is present, 697 use its value, or 699 * If the Expires response header field (Section 5.3) is present, use 700 its value minus the value of the Date response header field (using 701 the time the message was received if it is not present, as per 702 Section 10.2.2 of [HTTP]), or 704 * Otherwise, no explicit expiration time is present in the response. 705 A heuristic freshness lifetime might be applicable; see 706 Section 4.2.2. 708 Note that this calculation is intended to reduce clock skew by using 709 the clock information provided by the origin server whenever 710 possible. 712 When there is more than one value present for a given directive 713 (e.g., two Expires header field lines or multiple Cache-Control: max- 714 age directives), either the first occurrence should be used, or the 715 response should be considered stale. If directives conflict (e.g., 716 both max-age and no-cache are present), the most restrictive 717 directive should be honored. Caches are encouraged to consider 718 responses that have invalid freshness information (e.g., a max-age 719 directive with non-integer content) to be stale. 721 4.2.2. Calculating Heuristic Freshness 723 Since origin servers do not always provide explicit expiration times, 724 a cache MAY assign a heuristic expiration time when an explicit time 725 is not specified, employing algorithms that use other field values 726 (such as the Last-Modified time) to estimate a plausible expiration 727 time. This specification does not provide specific algorithms, but 728 does impose worst-case constraints on their results. 730 A cache MUST NOT use heuristics to determine freshness when an 731 explicit expiration time is present in the stored response. Because 732 of the requirements in Section 3, this means that heuristics can only 733 be used on responses without explicit freshness whose status codes 734 are defined as _heuristically cacheable_ (e.g., see Section 15.1 of 735 [HTTP]), and those responses without explicit freshness that have 736 been marked as explicitly cacheable (e.g., with a "public" response 737 directive). 739 Note that in previous specifications heuristically cacheable response 740 status codes were called "cacheable by default." 742 If the response has a Last-Modified header field (Section 8.8.2 of 743 [HTTP]), caches are encouraged to use a heuristic expiration value 744 that is no more than some fraction of the interval since that time. 745 A typical setting of this fraction might be 10%. 747 | *Note:* Section 13.9 of [RFC2616] prohibited caches from 748 | calculating heuristic freshness for URIs with query components 749 | (i.e., those containing '?'). In practice, this has not been 750 | widely implemented. Therefore, origin servers are encouraged 751 | to send explicit directives (e.g., Cache-Control: no-cache) if 752 | they wish to prevent caching. 754 4.2.3. Calculating Age 756 The Age header field is used to convey an estimated age of the 757 response message when obtained from a cache. The Age field value is 758 the cache's estimate of the number of seconds since the origin server 759 generated or validated the response. The Age value is therefore the 760 sum of the time that the response has been resident in each of the 761 caches along the path from the origin server, plus the time it has 762 been in transit along network paths. 764 Age calculation uses the following data: 766 _age_value_ The term "age_value" denotes the value of the Age header 767 field (Section 5.1), in a form appropriate for arithmetic 768 operation; or 0, if not available. 770 _date_value_ The term "date_value" denotes the value of the Date 771 header field, in a form appropriate for arithmetic operations. 772 See Section 10.2.2 of [HTTP] for the definition of the Date header 773 field, and for requirements regarding responses without it. 775 _now_ The term "now" means "the current value of the clock at the 776 host performing the calculation". A host ought to use NTP 777 ([RFC5905]) or some similar protocol to synchronize its clocks to 778 Coordinated Universal Time. 780 _request_time_ The current value of the clock at the host at the 781 time the request resulting in the stored response was made. 783 _response_time_ The current value of the clock at the host at the 784 time the response was received. 786 A response's age can be calculated in two entirely independent ways: 788 1. the "apparent_age": response_time minus date_value, if the local 789 clock is reasonably well synchronized to the origin server's 790 clock. If the result is negative, the result is replaced by 791 zero. 793 2. the "corrected_age_value", if all of the caches along the 794 response path implement HTTP/1.1 or greater. A cache MUST 795 interpret this value relative to the time the request was 796 initiated, not the time that the response was received. 798 apparent_age = max(0, response_time - date_value); 800 response_delay = response_time - request_time; 801 corrected_age_value = age_value + response_delay; 803 The corrected_age_value MAY be used as the corrected_initial_age. In 804 circumstances where very old cache implementations that might not 805 correctly insert Age are present, corrected_initial_age can be 806 calculated more conservatively as 808 corrected_initial_age = max(apparent_age, corrected_age_value); 810 The current_age of a stored response can then be calculated by adding 811 the time (in seconds) since the stored response was last validated by 812 the origin server to the corrected_initial_age. 814 resident_time = now - response_time; 815 current_age = corrected_initial_age + resident_time; 817 4.2.4. Serving Stale Responses 819 A "stale" response is one that either has explicit expiry information 820 or is allowed to have heuristic expiry calculated, but is not fresh 821 according to the calculations in Section 4.2. 823 A cache MUST NOT generate a stale response if it is prohibited by an 824 explicit in-protocol directive (e.g., by a "no-cache" cache 825 directive, a "must-revalidate" cache-response-directive, or an 826 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 827 see Section 5.2.2). 829 A cache MUST NOT generate a stale response unless it is disconnected 830 or doing so is explicitly permitted by the client or origin server 831 (e.g., by the max-stale request directive in Section 5.2.1, by 832 extension directives such as those defined in [RFC5861], or by 833 configuration in accordance with an out-of-band contract). 835 4.3. Validation 837 When a cache has one or more stored responses for a requested URI, 838 but cannot serve any of them (e.g., because they are not fresh, or 839 one cannot be selected; see Section 4.1), it can use the conditional 840 request mechanism (Section 13.1 of [HTTP]) in the forwarded request 841 to give the next inbound server an opportunity to select a valid 842 stored response to use, updating the stored metadata in the process, 843 or to replace the stored response(s) with a new response. This 844 process is known as _validating_ or _revalidating_ the stored 845 response. 847 4.3.1. Sending a Validation Request 849 When generating a conditional request for validation, a cache starts 850 with either a request it is attempting to satisfy, or - if it is 851 initiating the request independently - it synthesises a request using 852 a stored response by copying the method, target URI, and request 853 header fields identified by the Vary header field (Section 4.1). 855 It then updates that request with one or more precondition header 856 fields. These contain validator metadata sourced from stored 857 response(s) that have the same URI. Typically, this will include 858 only those stored responses(s) that have the same cache key, although 859 a cache is allowed to validate a response that it cannot select with 860 the request header fields it is sending (see Section 4.1). 862 The precondition header fields are then compared by recipients to 863 determine whether any stored response is equivalent to a current 864 representation of the resource. 866 One such validator is the timestamp given in a Last-Modified header 867 field (Section 8.8.2 of [HTTP]), which can be used in an If-Modified- 868 Since header field for response validation, or in an If-Unmodified- 869 Since or If-Range header field for representation selection (i.e., 870 the client is referring specifically to a previously obtained 871 representation with that timestamp). 873 Another validator is the entity-tag given in an ETag field 874 (Section 8.8.3 of [HTTP]). One or more entity-tags, indicating one 875 or more stored responses, can be used in an If-None-Match header 876 field for response validation, or in an If-Match or If-Range header 877 field for representation selection (i.e., the client is referring 878 specifically to one or more previously obtained representations with 879 the listed entity-tags). 881 4.3.2. Handling a Received Validation Request 883 Each client in the request chain may have its own cache, so it is 884 common for a cache at an intermediary to receive conditional requests 885 from other (outbound) caches. Likewise, some user agents make use of 886 conditional requests to limit data transfers to recently modified 887 representations or to complete the transfer of a partially retrieved 888 representation. 890 If a cache receives a request that can be satisfied by reusing a 891 stored 200 (OK) or 206 (Partial Content) response, as per Section 4, 892 the cache SHOULD evaluate any applicable conditional header field 893 preconditions received in that request with respect to the 894 corresponding validators contained within the selected response. 896 A cache MUST NOT evaluate conditional header fields that only apply 897 to an origin server, occur in a request with semantics that cannot be 898 satisfied with a cached response, or occur in a request with a target 899 resource for which it has no stored responses; such preconditions are 900 likely intended for some other (inbound) server. 902 The proper evaluation of conditional requests by a cache depends on 903 the received precondition header fields and their precedence. In 904 summary, the If-Match and If-Unmodified-Since conditional header 905 fields are not applicable to a cache, and If-None-Match takes 906 precedence over If-Modified-Since. See Section 13.2.2 of [HTTP] for 907 a complete specification of precondition precedence. 909 A request containing an If-None-Match header field (Section 13.1.2 of 910 [HTTP]) indicates that the client wants to validate one or more of 911 its own stored responses in comparison to the stored response 912 selected by the cache (as per Section 4). 914 If an If-None-Match header field is not present, a request containing 915 an If-Modified-Since header field (Section 13.1.3 of [HTTP]) 916 indicates that the client wants to validate one or more of its own 917 stored responses by modification date. 919 If a request contains an If-Modified-Since header field and the Last- 920 Modified header field is not present in a selected stored response, a 921 cache SHOULD use the stored response's Date field value (or, if no 922 Date field is present, the time that the stored response was 923 received) to evaluate the conditional. 925 A cache that implements partial responses to range requests, as 926 defined in Section 14.2 of [HTTP], also needs to evaluate a received 927 If-Range header field (Section 13.1.5 of [HTTP]) regarding its 928 selected stored response. 930 When a cache decides to forward a request to revalidate its own 931 stored responses for a request that contains an If-None-Match list of 932 entity-tags, the cache MAY combine the received list with a list of 933 entity-tags from its own stored set of responses (fresh or stale) and 934 send the union of the two lists as a replacement If-None-Match header 935 field value in the forwarded request. If a stored response contains 936 only partial content, the cache MUST NOT include its entity-tag in 937 the union unless the request is for a range that would be fully 938 satisfied by that partial stored response. If the response to the 939 forwarded request is 304 (Not Modified) and has an ETag field value 940 with an entity-tag that is not in the client's list, the cache MUST 941 generate a 200 (OK) response for the client by reusing its 942 corresponding stored response, as updated by the 304 response 943 metadata (Section 4.3.4). 945 4.3.3. Handling a Validation Response 947 Cache handling of a response to a conditional request depends upon 948 its status code: 950 * A 304 (Not Modified) response status code indicates that the 951 stored response can be updated and reused; see Section 4.3.4. 953 * A full response (i.e., one containing content) indicates that none 954 of the stored responses nominated in the conditional request is 955 suitable. Instead, the cache MUST use the full response to 956 satisfy the request. The cache MAY store such a full response, 957 subject to its constraints (see Section 3). 959 * However, if a cache receives a 5xx (Server Error) response while 960 attempting to validate a response, it can either forward this 961 response to the requesting client, or act as if the server failed 962 to respond. In the latter case, the cache can send a previously 963 stored response, subject to its constraints on doing so (see 964 Section 4.2.4), or retry the validation request. 966 4.3.4. Freshening Stored Responses upon Validation 968 When a cache receives a 304 (Not Modified) response, it needs to 969 identify stored responses that are suitable for updating with the new 970 information provided, and then do so. 972 The initial set of stored responses to update are those that could 973 have been selected for that request - i.e., those that meet the 974 requirements in Section 4, except the last requirement to be fresh, 975 able to be served stale or just validated. 977 Then, that initial set of stored response(s) is further filtered by 978 the first match of: 980 * If the new response contains one or more _strong validators_ (see 981 Section 8.8.1 of [HTTP]), then each of those strong validators 982 identify a selected representation for update. All the stored 983 responses in the initial set with one of those same strong 984 validators are identified for update. If none of the initial set 985 contain at least one of the same strong validators, then the cache 986 MUST NOT use the new response to update any stored responses. 988 * If the new response contains no strong validators but does contain 989 one or more _weak validators_, and those validators correspond to 990 one of the initial set's stored responses, then the most recent of 991 those matching stored responses is identified for update. 993 * If the new response does not include any form of validator (such 994 as where a client generates an If-Modified-Since request from a 995 source other than the Last-Modified response header field), and 996 there is only one stored response in the initial set, and that 997 stored response also lacks a validator, then that stored response 998 is identified for update. 1000 For each stored response identified, the cache MUST update its header 1001 fields with the header fields provided in the 304 (Not Modified) 1002 response, as per Section 3.2. 1004 4.3.5. Freshening Responses with HEAD 1006 A response to the HEAD method is identical to what an equivalent 1007 request made with a GET would have been, without sending the content. 1008 This property of HEAD responses can be used to invalidate or update a 1009 cached GET response if the more efficient conditional GET request 1010 mechanism is not available (due to no validators being present in the 1011 stored response) or if transmission of the content is not desired 1012 even if it has changed. 1014 When a cache makes an inbound HEAD request for a target URI and 1015 receives a 200 (OK) response, the cache SHOULD update or invalidate 1016 each of its stored GET responses that could have been selected for 1017 that request (see Section 4.1). 1019 For each of the stored responses that could have been selected, if 1020 the stored response and HEAD response have matching values for any 1021 received validator fields (ETag and Last-Modified) and, if the HEAD 1022 response has a Content-Length header field, the value of Content- 1023 Length matches that of the stored response, the cache SHOULD update 1024 the stored response as described below; otherwise, the cache SHOULD 1025 consider the stored response to be stale. 1027 If a cache updates a stored response with the metadata provided in a 1028 HEAD response, the cache MUST use the header fields provided in the 1029 HEAD response to update the stored response (see Section 3.2). 1031 4.4. Invalidating Stored Responses 1033 Because unsafe request methods (Section 9.2.1 of [HTTP]) such as PUT, 1034 POST or DELETE have the potential for changing state on the origin 1035 server, intervening caches are required to invalidate stored 1036 responses to keep their contents up to date. 1038 A cache MUST invalidate the target URI (Section 7.1 of [HTTP]) when 1039 it receives a non-error status code in response to an unsafe request 1040 method (including methods whose safety is unknown). 1042 A cache MAY invalidate other URIs when it receives a non-error status 1043 code in response to an unsafe request method (including methods whose 1044 safety is unknown). In particular, the URI(s) in the Location and 1045 Content-Location response header fields (if present) are candidates 1046 for invalidation; other URIs might be discovered through mechanisms 1047 not specified in this document. However, a cache MUST NOT trigger an 1048 invalidation under these conditions if the origin (Section 4.3.1 of 1049 [HTTP]) of the URI to be invalidated differs from that of the target 1050 URI (Section 7.1 of [HTTP]). This helps prevent denial-of-service 1051 attacks. 1053 _Invalidate_ means that the cache will either remove all stored 1054 responses whose target URI matches the given URI, or will mark them 1055 as "invalid" and in need of a mandatory validation before they can be 1056 sent in response to a subsequent request. 1058 A "non-error response" is one with a 2xx (Successful) or 3xx 1059 (Redirection) status code. 1061 Note that this does not guarantee that all appropriate responses are 1062 invalidated globally; a state-changing request would only invalidate 1063 responses in the caches it travels through. 1065 5. Field Definitions 1067 This section defines the syntax and semantics of HTTP fields related 1068 to caching. 1070 5.1. Age 1072 The "Age" response header field conveys the sender's estimate of the 1073 time since the response was generated or successfully validated at 1074 the origin server. Age values are calculated as specified in 1075 Section 4.2.3. 1077 Age = delta-seconds 1079 The Age field value is a non-negative integer, representing time in 1080 seconds (see Section 1.2.2). 1082 Although it is defined as a singleton header field, a cache 1083 encountering a message with a list-based Age field value SHOULD use 1084 the first member of the field value, discarding subsequent ones. 1086 If the field value (after discarding additional members, as per 1087 above) is invalid (e.g., it contains something other than a non- 1088 negative integer), a cache SHOULD ignore the field. 1090 The presence of an Age header field implies that the response was not 1091 generated or validated by the origin server for this request. 1092 However, lack of an Age header field does not imply the origin was 1093 contacted. 1095 5.2. Cache-Control 1097 The "Cache-Control" header field is used to list directives for 1098 caches along the request/response chain. Such cache directives are 1099 unidirectional in that the presence of a directive in a request does 1100 not imply that the same directive is present in the response, or to 1101 be repeated in it. 1103 See Section 5.2.3 for information about how Cache-Control directives 1104 defined elsewhere are handled. 1106 A proxy, whether or not it implements a cache, MUST pass cache 1107 directives through in forwarded messages, regardless of their 1108 significance to that application, since the directives might apply to 1109 all recipients along the request/response chain. It is not possible 1110 to target a directive to a specific cache. 1112 Cache directives are identified by a token, to be compared case- 1113 insensitively, and have an optional argument that can use both token 1114 and quoted-string syntax. For the directives defined below that 1115 define arguments, recipients ought to accept both forms, even if a 1116 specific form is required for generation. 1118 Cache-Control = #cache-directive 1120 cache-directive = token [ "=" ( token / quoted-string ) ] 1122 For the cache directives defined below, no argument is defined (nor 1123 allowed) unless stated otherwise. 1125 5.2.1. Request Cache-Control Directives 1127 This section defines cache request directives. They are advisory; 1128 caches MAY implement them, but are not required to. 1130 5.2.1.1. max-age 1132 Argument syntax: 1134 delta-seconds (see Section 1.2.2) 1136 The "max-age" request directive indicates that the client prefers a 1137 response whose age is less than or equal to the specified number of 1138 seconds. Unless the max-stale request directive is also present, the 1139 client does not wish to receive a stale response. 1141 This directive uses the token form of the argument syntax: e.g., 1142 'max-age=5' not 'max-age="5"'. A sender MUST NOT generate the 1143 quoted-string form. 1145 5.2.1.2. max-stale 1147 Argument syntax: 1149 delta-seconds (see Section 1.2.2) 1151 The "max-stale" request directive indicates that the client will 1152 accept a response that has exceeded its freshness lifetime. If a 1153 value is present, then the client is willing to accept a response 1154 that has exceeded its freshness lifetime by no more than the 1155 specified number of seconds. If no value is assigned to max-stale, 1156 then the client will accept a stale response of any age. 1158 This directive uses the token form of the argument syntax: e.g., 1159 'max-stale=10' not 'max-stale="10"'. A sender MUST NOT generate the 1160 quoted-string form. 1162 5.2.1.3. min-fresh 1164 Argument syntax: 1166 delta-seconds (see Section 1.2.2) 1168 The "min-fresh" request directive indicates that the client prefers a 1169 response whose freshness lifetime is no less than its current age 1170 plus the specified time in seconds. That is, the client wants a 1171 response that will still be fresh for at least the specified number 1172 of seconds. 1174 This directive uses the token form of the argument syntax: e.g., 1175 'min-fresh=20' not 'min-fresh="20"'. A sender MUST NOT generate the 1176 quoted-string form. 1178 5.2.1.4. no-cache 1180 The "no-cache" request directive indicates that the client prefers 1181 stored response not be used to satisfy the request without successful 1182 validation on the origin server. 1184 5.2.1.5. no-store 1186 The "no-store" request directive indicates that a cache MUST NOT 1187 store any part of either this request or any response to it. This 1188 directive applies to both private and shared caches. "MUST NOT 1189 store" in this context means that the cache MUST NOT intentionally 1190 store the information in non-volatile storage, and MUST make a best- 1191 effort attempt to remove the information from volatile storage as 1192 promptly as possible after forwarding it. 1194 This directive is _not_ a reliable or sufficient mechanism for 1195 ensuring privacy. In particular, malicious or compromised caches 1196 might not recognize or obey this directive, and communications 1197 networks might be vulnerable to eavesdropping. 1199 Note that if a request containing this directive is satisfied from a 1200 cache, the no-store request directive does not apply to the already 1201 stored response. 1203 5.2.1.6. no-transform 1205 The "no-transform" request directive indicates that the client is 1206 asking for intermediaries to avoid transforming the content, as 1207 defined in Section 7.7 of [HTTP]. 1209 5.2.1.7. only-if-cached 1211 The "only-if-cached" request directive indicates that the client only 1212 wishes to obtain a stored response. Caches that honor this request 1213 directive SHOULD, upon receiving it, either respond using a stored 1214 response consistent with the other constraints of the request, or 1215 respond with a 504 (Gateway Timeout) status code. 1217 5.2.2. Response Cache-Control Directives 1219 This section defines cache response directives. A cache MUST obey 1220 the Cache-Control directives defined in this section. 1222 5.2.2.1. max-age 1224 Argument syntax: 1226 delta-seconds (see Section 1.2.2) 1228 The "max-age" response directive indicates that the response is to be 1229 considered stale after its age is greater than the specified number 1230 of seconds. 1232 This directive uses the token form of the argument syntax: e.g., 1233 'max-age=5' not 'max-age="5"'. A sender MUST NOT generate the 1234 quoted-string form. 1236 5.2.2.2. must-revalidate 1238 The "must-revalidate" response directive indicates that once the 1239 response has become stale, a cache MUST NOT reuse that response to 1240 satisfy another request until it has been successfully validated by 1241 the origin, as defined by Section 4.3. 1243 The must-revalidate directive is necessary to support reliable 1244 operation for certain protocol features. In all circumstances a 1245 cache MUST NOT ignore the must-revalidate directive; in particular, 1246 if a cache is disconnected, the cache MUST generate an error response 1247 rather than reuse the stale response. The generated status code 1248 SHOULD be 504 (Gateway Timeout) unless another error status code is 1249 more applicable. 1251 The must-revalidate directive ought to be used by servers if and only 1252 if failure to validate a request could cause incorrect operation, 1253 such as a silently unexecuted financial transaction. 1255 The must-revalidate directive also permits a shared cache to reuse a 1256 response to a request containing an Authorization header field 1257 (Section 11.6.2 of [HTTP]), subject to the above requirement on 1258 revalidation (Section 3.5). 1260 5.2.2.3. must-understand 1262 The "must-understand" response directive limits caching of the 1263 response to a cache that understands and conforms to the requirements 1264 for that response's status code. 1266 Responses containing "must-understand" SHOULD also contain the "no- 1267 store" directive; caches that implement "must-understand" SHOULD 1268 ignore the "no-store" directive in responses that contain both 1269 directives and a status code that the cache understands and conforms 1270 to any related caching requirements. 1272 5.2.2.4. no-cache 1274 Argument syntax: 1276 #field-name 1278 The "no-cache" response directive, in its unqualified form (without 1279 an argument), indicates that the response MUST NOT be used to satisfy 1280 any other request without forwarding it for validation and receiving 1281 a successful response; see Section 4.3. 1283 This allows an origin server to prevent a cache from using the 1284 response to satisfy a request without contacting it, even by caches 1285 that have been configured to send stale responses. 1287 The qualified form of no-cache response directive, with an argument 1288 that lists one or more field names, indicates that a cache MAY use 1289 the response to satisfy a subsequent request, subject to any other 1290 restrictions on caching, if the listed header fields are excluded 1291 from the subsequent response or the subsequent response has been 1292 successfully revalidated with the origin server (updating or removing 1293 those fields). This allows an origin server to prevent the re-use of 1294 certain header fields in a response, while still allowing caching of 1295 the rest of the response. 1297 The field names given are not limited to the set of header fields 1298 defined by this specification. Field names are case-insensitive. 1300 This directive uses the quoted-string form of the argument syntax. A 1301 sender SHOULD NOT generate the token form (even if quoting appears 1302 not to be needed for single-entry lists). 1304 | *Note:* The qualified form of the directive is often handled by 1305 | caches as if an unqualified no-cache directive was received; 1306 | i.e., the special handling for the qualified form is not widely 1307 | implemented. 1309 5.2.2.5. no-store 1311 The "no-store" response directive indicates that a cache MUST NOT 1312 store any part of either the immediate request or response, and MUST 1313 NOT use the response to satisfy any other request. 1315 This directive applies to both private and shared caches. "MUST NOT 1316 store" in this context means that the cache MUST NOT intentionally 1317 store the information in non-volatile storage, and MUST make a best- 1318 effort attempt to remove the information from volatile storage as 1319 promptly as possible after forwarding it. 1321 This directive is _not_ a reliable or sufficient mechanism for 1322 ensuring privacy. In particular, malicious or compromised caches 1323 might not recognize or obey this directive, and communications 1324 networks might be vulnerable to eavesdropping. 1326 Note that the "must-understand" cache directive overrides "no-store" 1327 in certain circumstances; see Section 5.2.2.3. 1329 5.2.2.6. no-transform 1331 The "no-transform" response directive indicates that an intermediary 1332 (regardless of whether it implements a cache) MUST NOT transform the 1333 content, as defined in Section 7.7 of [HTTP]. 1335 5.2.2.7. private 1337 Argument syntax: 1339 #field-name 1341 The unqualified "private" response directive indicates that a shared 1342 cache MUST NOT store the response (i.e., the response is intended for 1343 a single user). It also indicates that a private cache MAY store the 1344 response, subject the constraints defined in Section 3, even if the 1345 response would not otherwise be heuristically cacheable by a private 1346 cache. 1348 If a qualified private response directive is present, with an 1349 argument that lists one or more field names, then only the listed 1350 header fields are limited to a single user: a shared cache MUST NOT 1351 store the listed header fields if they are present in the original 1352 response, but MAY store the remainder of the response message without 1353 those header fields, subject the constraints defined in Section 3. 1355 The field names given are not limited to the set of header fields 1356 defined by this specification. Field names are case-insensitive. 1358 This directive uses the quoted-string form of the argument syntax. A 1359 sender SHOULD NOT generate the token form (even if quoting appears 1360 not to be needed for single-entry lists). 1362 | *Note:* This usage of the word "private" only controls where 1363 | the response can be stored; it cannot ensure the privacy of the 1364 | message content. Also, the qualified form of the directive is 1365 | often handled by caches as if an unqualified private directive 1366 | was received; i.e., the special handling for the qualified form 1367 | is not widely implemented. 1369 5.2.2.8. proxy-revalidate 1371 The "proxy-revalidate" response directive indicates that once the 1372 response has become stale, a shared cache MUST NOT reuse that 1373 response to satisfy another request until it has been successfully 1374 validated by the origin, as defined by Section 4.3. This is 1375 analogous to must-revalidate (Section 5.2.2.2), except that proxy- 1376 revalidate does not apply to private caches. 1378 Note that "proxy-revalidate" on its own does not imply that a 1379 response is cacheable. For example, it might be combined with the 1380 public directive (Section 5.2.2.9), allowing the response to be 1381 cached while requiring only a shared cache to revalidate when stale. 1383 5.2.2.9. public 1385 The "public" response directive indicates that a cache MAY store the 1386 response even if it would otherwise be prohibited, subject to the 1387 constraints defined in Section 3. In other words, public explicitly 1388 marks the response as cacheable. For example, public permits a 1389 shared cache to reuse a response to a request containing an 1390 Authorization header field (Section 3.5). 1392 Note that it is unnecessary to add the public directive to a response 1393 that is already cacheable according to Section 3. 1395 If a response with the public directive has no explicit freshness 1396 information, it is heuristically cacheable (Section 4.2.2). 1398 5.2.2.10. s-maxage 1400 Argument syntax: 1402 delta-seconds (see Section 1.2.2) 1404 The "s-maxage" response directive indicates that, for a shared cache, 1405 the maximum age specified by this directive overrides the maximum age 1406 specified by either the max-age directive or the Expires header 1407 field. 1409 The s-maxage directive incorporates the proxy-revalidate 1410 (Section 5.2.2.8) response directive's semantics for a shared cache. 1411 A shared cache MUST NOT reuse a stale response with s-maxage to 1412 satisfy another request until it has been successfully validated by 1413 the origin, as defined by Section 4.3. This directive also permits a 1414 shared cache to reuse a response to a request containing an 1415 Authorization header field, subject to the above requirements on 1416 maximum age and revalidation (Section 3.5). 1418 This directive uses the token form of the argument syntax: e.g., 1419 's-maxage=10' not 's-maxage="10"'. A sender MUST NOT generate the 1420 quoted-string form. 1422 5.2.3. Cache Control Extensions 1424 The Cache-Control header field can be extended through the use of one 1425 or more extension cache directives. A cache MUST ignore unrecognized 1426 cache directives. 1428 Informational extensions (those that do not require a change in cache 1429 behavior) can be added without changing the semantics of other 1430 directives. 1432 Behavioral extensions are designed to work by acting as modifiers to 1433 the existing base of cache directives. Both the new directive and 1434 the old directive are supplied, such that applications that do not 1435 understand the new directive will default to the behavior specified 1436 by the old directive, and those that understand the new directive 1437 will recognize it as modifying the requirements associated with the 1438 old directive. In this way, extensions to the existing cache-control 1439 directives can be made without breaking deployed caches. 1441 For example, consider a hypothetical new response directive called 1442 "community" that acts as a modifier to the private directive: in 1443 addition to private caches, any cache that is shared only by members 1444 of the named community is allowed to cache the response. An origin 1445 server wishing to allow the UCI community to use an otherwise private 1446 response in their shared cache(s) could do so by including 1448 Cache-Control: private, community="UCI" 1450 A cache that recognizes such a community cache directive could 1451 broaden its behavior in accordance with that extension. A cache that 1452 does not recognize the community cache directive would ignore it and 1453 adhere to the private directive. 1455 New extension directives ought to consider defining: 1457 * What it means for a directive to be specified multiple times, 1459 * When the directive does not take an argument, what it means when 1460 an argument is present, 1462 * When the directive requires an argument, what it means when it is 1463 missing, 1465 * Whether the directive is specific to requests, responses, or able 1466 to be used in either. 1468 5.2.4. Cache Directive Registry 1470 The "Hypertext Transfer Protocol (HTTP) Cache Directive Registry" 1471 defines the namespace for the cache directives. It has been created 1472 and is now maintained at . 1475 A registration MUST include the following fields: 1477 * Cache Directive Name 1479 * Pointer to specification text 1481 Values to be added to this namespace require IETF Review (see 1482 [RFC8126], Section 4.8). 1484 5.3. Expires 1486 The "Expires" response header field gives the date/time after which 1487 the response is considered stale. See Section 4.2 for further 1488 discussion of the freshness model. 1490 The presence of an Expires header field does not imply that the 1491 original resource will change or cease to exist at, before, or after 1492 that time. 1494 The Expires field value is an HTTP-date timestamp, as defined in 1495 Section 5.6.7 of [HTTP]. See also Section 4.2 for parsing 1496 requirements specific to caches. 1498 Expires = HTTP-date 1500 For example 1502 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1504 A cache recipient MUST interpret invalid date formats, especially the 1505 value "0", as representing a time in the past (i.e., "already 1506 expired"). 1508 If a response includes a Cache-Control header field with the max-age 1509 directive (Section 5.2.2.1), a recipient MUST ignore the Expires 1510 header field. Likewise, if a response includes the s-maxage 1511 directive (Section 5.2.2.10), a shared cache recipient MUST ignore 1512 the Expires header field. In both these cases, the value in Expires 1513 is only intended for recipients that have not yet implemented the 1514 Cache-Control header field. 1516 An origin server without a clock MUST NOT generate an Expires header 1517 field unless its value represents a fixed time in the past (always 1518 expired) or its value has been associated with the resource by a 1519 system or user with a reliable clock. 1521 Historically, HTTP required the Expires field value to be no more 1522 than a year in the future. While longer freshness lifetimes are no 1523 longer prohibited, extremely large values have been demonstrated to 1524 cause problems (e.g., clock overflows due to use of 32-bit integers 1525 for time values), and many caches will evict a response far sooner 1526 than that. 1528 5.4. Pragma 1530 The "Pragma" request header field was defined for HTTP/1.0 caches, so 1531 that clients could specify a "no-cache" request (as Cache-Control was 1532 not defined until HTTP/1.1). 1534 However, support for Cache-Control is now widespread. As a result, 1535 this specification deprecates Pragma. 1537 | *Note:* Because the meaning of "Pragma: no-cache" in responses 1538 | was never specified, it does not provide a reliable replacement 1539 | for "Cache-Control: no-cache" in them. 1541 5.5. Warning 1543 The "Warning" header field was used to carry additional information 1544 about the status or transformation of a message that might not be 1545 reflected in the status code. This specification obsoletes it, as it 1546 is not widely generated or surfaced to users. The information it 1547 carried can be gleaned from examining other header fields, such as 1548 Age. 1550 6. Relationship to Applications and Other Caches 1552 Applications using HTTP often specify additional forms of caching. 1553 For example, Web browsers often have history mechanisms such as 1554 "Back" buttons that can be used to redisplay a representation 1555 retrieved earlier in a session. 1557 Likewise, some Web browsers implement caching of images and other 1558 assets within a page view; they may or may not honor HTTP caching 1559 semantics. 1561 The requirements in this specification do not necessarily apply to 1562 how applications use data after it is retrieved from an HTTP cache. 1563 For example, a history mechanism can display a previous 1564 representation even if it has expired, and an application can use 1565 cached data in other ways beyond its freshness lifetime. 1567 This specification does not prohibit the application from taking HTTP 1568 caching into account; for example, a history mechanism might tell the 1569 user that a view is stale, or it might honor cache directives (e.g., 1570 Cache-Control: no-store). 1572 However, when an application caches data and does not make this 1573 apparent to or easily controllable by the user, it is strongly 1574 encouraged to define its operation with respect to HTTP cache 1575 directives, so as not to surprise authors who expect caching 1576 semantics to be honoured. For example, while it might be reasonable 1577 to define an application cache "above" HTTP that allows a response 1578 containing Cache-Control: no-store to be reused for requests that are 1579 directly related to the request that fetched it (such as those 1580 created during the same page load), it would likely be surprising and 1581 confusing to users and authors if it were allowed to be reused for 1582 requests unrelated in any way to the one from which it was obtained. 1584 7. Security Considerations 1586 This section is meant to inform developers, information providers, 1587 and users of known security concerns specific to HTTP caching. More 1588 general security considerations are addressed in "HTTP/1.1" 1589 (Section 11 of [HTTP/1.1]) and "HTTP Semantics" (Section 17 of 1590 [HTTP]). 1592 Caches expose an additional attack surface, since the contents of the 1593 cache represent an attractive target for malicious exploitation. 1594 Because cache contents persist after an HTTP request is complete, an 1595 attack on the cache can reveal information long after a user believes 1596 that the information has been removed from the network. Therefore, 1597 cache contents need to be protected as sensitive information. 1599 In particular, because private caches are restricted to a single 1600 user, they can be used to reconstruct a user's activity. As a 1601 result, is important for user agents to allow end users to control 1602 them; for example, allowing stored responses to be removed for some 1603 or all origin servers. 1605 7.1. Cache Poisoning 1607 Storing a malicious payload in a cache can extend the reach of an 1608 attacker to affect multiple users. Such "cache poisoning" attacks 1609 happen when an attacker uses implementation flaws, elevated 1610 privileges, or other techniques to insert a response into a cache. 1611 This is especially effective when shared caches are used to 1612 distribute malicious content to many clients. 1614 One common attack vector for cache poisoning is to exploit 1615 differences in message parsing on proxies and in user agents; see 1616 Section 6.3 of [HTTP/1.1] for the relevant requirements regarding 1617 HTTP/1.1. 1619 7.2. Timing Attacks 1621 Because one of the primary uses of a cache is to optimise 1622 performance, its use can "leak" information about what resources have 1623 been previously requested. 1625 For example, if a user visits a site and their browser caches some of 1626 its responses, and then navigates to a second site, that site can 1627 attempt to load responses it knows exists on the first site. If they 1628 load quickly, it can be assumed that the user has visited that site, 1629 or even a specific page on it. 1631 Such "timing attacks" can be mitigated by adding more information to 1632 the cache key, such as the identity of the referring site (to prevent 1633 the attack described above). This is sometimes called "double 1634 keying." 1636 7.3. Caching of Sensitive Information 1638 Implementation and deployment flaws (as well as misunderstanding of 1639 cache operation) might lead to caching of sensitive information 1640 (e.g., authentication credentials) that is thought to be private, 1641 exposing it to unauthorized parties. 1643 Note that the Set-Cookie response header field [COOKIE] does not 1644 inhibit caching; a cacheable response with a Set-Cookie header field 1645 can be (and often is) used to satisfy subsequent requests to caches. 1646 Servers who wish to control caching of these responses are encouraged 1647 to emit appropriate Cache-Control response header fields. 1649 8. IANA Considerations 1651 The change controller for the following registrations is: "IETF 1652 (iesg@ietf.org) - Internet Engineering Task Force". 1654 8.1. Field Name Registration 1656 First, introduce the new "Hypertext Transfer Protocol (HTTP) Field 1657 Name Registry" at as 1658 described in Section 18.4 of [HTTP]. 1660 Then, please update the registry with the field names listed in the 1661 table below: 1663 +===============+===========+======+==========+ 1664 | Field Name | Status | Ref. | Comments | 1665 +===============+===========+======+==========+ 1666 | Age | standard | 5.1 | | 1667 +---------------+-----------+------+----------+ 1668 | Cache-Control | standard | 5.2 | | 1669 +---------------+-----------+------+----------+ 1670 | Expires | standard | 5.3 | | 1671 +---------------+-----------+------+----------+ 1672 | Pragma | standard | 5.4 | | 1673 +---------------+-----------+------+----------+ 1674 | Warning | obsoleted | 5.5 | | 1675 +---------------+-----------+------+----------+ 1677 Table 1 1679 8.2. Cache Directive Registration 1681 Please update the "Hypertext Transfer Protocol (HTTP) Cache Directive 1682 Registry" at 1683 with the registration procedure of Section 5.2.4 and the cache 1684 directive names summarized in the table below. 1686 +==================+==================================+ 1687 | Cache Directive | Reference | 1688 +==================+==================================+ 1689 | max-age | Section 5.2.1.1, Section 5.2.2.1 | 1690 +------------------+----------------------------------+ 1691 | max-stale | Section 5.2.1.2 | 1692 +------------------+----------------------------------+ 1693 | min-fresh | Section 5.2.1.3 | 1694 +------------------+----------------------------------+ 1695 | must-revalidate | Section 5.2.2.2 | 1696 +------------------+----------------------------------+ 1697 | must-understand | Section 5.2.2.3 | 1698 +------------------+----------------------------------+ 1699 | no-cache | Section 5.2.1.4, Section 5.2.2.4 | 1700 +------------------+----------------------------------+ 1701 | no-store | Section 5.2.1.5, Section 5.2.2.5 | 1702 +------------------+----------------------------------+ 1703 | no-transform | Section 5.2.1.6, Section 5.2.2.6 | 1704 +------------------+----------------------------------+ 1705 | only-if-cached | Section 5.2.1.7 | 1706 +------------------+----------------------------------+ 1707 | private | Section 5.2.2.7 | 1708 +------------------+----------------------------------+ 1709 | proxy-revalidate | Section 5.2.2.8 | 1710 +------------------+----------------------------------+ 1711 | public | Section 5.2.2.9 | 1712 +------------------+----------------------------------+ 1713 | s-maxage | Section 5.2.2.10 | 1714 +------------------+----------------------------------+ 1716 Table 2 1718 8.3. Warn Code Registry 1720 Please add a note to the "Hypertext Transfer Protocol (HTTP) Warn 1721 Codes" registry at 1722 to the effect that Warning is obsoleted. 1724 9. References 1726 9.1. Normative References 1728 [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 1729 Ed., "HTTP Semantics", Work in Progress, Internet-Draft, 1730 draft-ietf-httpbis-semantics-17, 26 July 2021, 1731 . 1734 [HTTP/1.1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 1735 Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft- 1736 ietf-httpbis-messaging-17, 26 July 2021, 1737 . 1740 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1741 Requirement Levels", BCP 14, RFC 2119, 1742 DOI 10.17487/RFC2119, March 1997, 1743 . 1745 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1746 Specifications: ABNF", STD 68, RFC 5234, 1747 DOI 10.17487/RFC5234, January 2008, 1748 . 1750 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 1751 RFC 7405, DOI 10.17487/RFC7405, December 2014, 1752 . 1754 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1755 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1756 May 2017, . 1758 9.2. Informative References 1760 [COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1761 DOI 10.17487/RFC6265, April 2011, 1762 . 1764 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1765 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1766 Transfer Protocol -- HTTP/1.1", RFC 2616, 1767 DOI 10.17487/RFC2616, June 1999, 1768 . 1770 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1771 Content", RFC 5861, DOI 10.17487/RFC5861, April 2010, 1772 . 1774 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 1775 "Network Time Protocol Version 4: Protocol and Algorithms 1776 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 1777 . 1779 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. F. Reschke, 1780 Ed., "Hypertext Transfer Protocol (HTTP): Caching", 1781 RFC 7234, DOI 10.17487/RFC7234, June 2014, 1782 . 1784 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1785 Writing an IANA Considerations Section in RFCs", BCP 26, 1786 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1787 . 1789 Appendix A. Collected ABNF 1791 In the collected ABNF below, list rules are expanded as per 1792 Section 5.6.1.1 of [HTTP]. 1794 Age = delta-seconds 1796 Cache-Control = [ cache-directive *( OWS "," OWS cache-directive ) ] 1798 Expires = HTTP-date 1800 HTTP-date = 1802 OWS = 1804 cache-directive = token [ "=" ( token / quoted-string ) ] 1806 delta-seconds = 1*DIGIT 1808 field-name = 1810 quoted-string = 1812 token = 1814 Appendix B. Changes from RFC 7234 1816 Handling of duplicate and conflicting cache directives has been 1817 clarified. (Section 4.2.1) 1819 Cache invalidation of the URIs in the Location and Content-Location 1820 header fields is no longer required, but still allowed. 1821 (Section 4.4) 1822 Cache invalidation of the URIs in the Location and Content-Location 1823 header fields is disallowed when the origin is different; previously, 1824 it was the host. (Section 4.4) 1826 Handling invalid and multiple Age header field values has been 1827 clarified. (Section 5.1) 1829 Some cache directives defined by this specification now have stronger 1830 prohibitions against generating the quoted form of their values, 1831 since this has been found to create interoperability problems. 1832 Consumers of extension cache directives are no longer required to 1833 accept both token and quoted-string forms, but they still need to 1834 parse them properly for unknown extensions. (Section 5.2) 1836 The "public" and "private" cache directives were clarified, so that 1837 they do not make responses reusable under any condition. 1838 (Section 5.2.2) 1840 The "must-understand" cache directive was introduced; caches are no 1841 longer required to understand the semantics of new response status 1842 codes unless it is present. (Section 5.2.2.3) 1844 The Warning response header was obsoleted. Much of the information 1845 supported by Warning could be gleaned by examining the response, and 1846 the remaining warn-codes - although potentially useful - were 1847 entirely advisory. In practice, Warning was not added by caches or 1848 intermediaries. (Section 5.5) 1850 Appendix C. Change Log 1852 This section is to be removed before publishing as an RFC. 1854 C.1. Between RFC7234 and draft 00 1856 The changes were purely editorial: 1858 * Change boilerplate and abstract to indicate the "draft" status, 1859 and update references to ancestor specifications. 1861 * Remove version "1.1" from document title, indicating that this 1862 specification applies to all HTTP versions. 1864 * Adjust historical notes. 1866 * Update links to sibling specifications. 1868 * Replace sections listing changes from RFC 2616 by new empty 1869 sections referring to RFC 723x. 1871 * Remove acknowledgements specific to RFC 723x. 1873 * Move "Acknowledgements" to the very end and make them unnumbered. 1875 C.2. Since draft-ietf-httpbis-cache-00 1877 The changes are purely editorial: 1879 * Moved all extensibility tips, registration procedures, and 1880 registry tables from the IANA considerations to normative 1881 sections, reducing the IANA considerations to just instructions 1882 that will be removed prior to publication as an RFC. 1884 C.3. Since draft-ietf-httpbis-cache-01 1886 * Cite RFC 8126 instead of RFC 5226 () 1889 * In Section 5.4, misleading statement about the relation between 1890 Pragma and Cache-Control (, ) 1893 C.4. Since draft-ietf-httpbis-cache-02 1895 * In Section 3, explain that only final responses are cacheable 1896 () 1898 * In Section 5.2.2, clarify what responses various directives apply 1899 to () 1901 * In Section 4.3.1, clarify the source of validators in conditional 1902 requests () 1904 * Revise Section 6 to apply to more than just History Lists 1905 () 1907 * In Section 5.5, deprecated "Warning" header field 1908 () 1910 * In Section 3.5, remove a spurious note 1911 () 1913 C.5. Since draft-ietf-httpbis-cache-03 1915 * In Section 2, define what a disconnected cache is 1916 () 1918 * In Section 4, clarify language around how to select a response 1919 when more than one matches () 1922 * in Section 4.2.4, mention stale-while-revalidate and stale-if- 1923 error () 1925 * Remove requirements around cache request directives 1926 () 1928 * Deprecate Pragma () 1931 * In Section 3.5 and Section 5.2.2, note effect of some directives 1932 on authenticated requests () 1935 C.6. Since draft-ietf-httpbis-cache-04 1937 * In Section 5.2, remove the registrations for stale-if-error and 1938 stale-while-revalidate which happened in RFC 7234 1939 () 1941 C.7. Since draft-ietf-httpbis-cache-05 1943 * In Section 3.3, clarify how weakly framed content is considered 1944 for purposes of completeness () 1947 * Throughout, describe Vary and cache key operations more clearly 1948 () 1950 * In Section 3, remove concept of "cacheable methods" in favor of 1951 prose (, 1952 ) 1954 * Refactored Section 7, and added a section on timing attacks 1955 () 1957 * Changed "cacheable by default" to "heuristically cacheable" 1958 throughout () 1960 C.8. Since draft-ietf-httpbis-cache-06 1962 * In Section 3 and Section 5.2.2.3, change response cacheability to 1963 only require understanding the response status code if the must- 1964 understand cache directive is present () 1967 * Change requirements for handling different forms of cache 1968 directives in Section 5.2 () 1971 * Fix typo in Section 5.2.2.10 () 1974 * In Section 5.2.2.9 and Section 5.2.2.7, clarify "private" and 1975 "public" so that they do not override all other cache directives 1976 () 1978 * In Section 3, distinguish between private with and without 1979 qualifying headers () 1982 * In Section 4.1, clarify that any "*" as a member of Vary will 1983 disable caching () 1985 * In Section 1.1, reference RFC 8174 as well 1986 () 1988 C.9. Since draft-ietf-httpbis-cache-07 1990 * Throughout, replace "effective request URI", "request-target" and 1991 similar with "target URI" () 1994 * In Section 5.2.2.9 and Section 5.2.2.7, make it clear that these 1995 directives do not ignore other requirements for caching 1996 () 1998 * In Section 3.3, move definition of "complete" into semantics 1999 () 2001 C.10. Since draft-ietf-httpbis-cache-08 2003 * Appendix A now uses the sender variant of the "#" list expansion 2004 () 2006 C.11. Since draft-ietf-httpbis-cache-09 2008 * In Section 5.1, discuss handling of invalid and multiple Age 2009 header field values () 2012 * Switch to xml2rfc v3 mode for draft generation 2013 () 2015 C.12. Since draft-ietf-httpbis-cache-10 2017 * In Section 5.2 (Cache-Control), adjust ABNF to allow empty lists 2018 () 2020 C.13. Since draft-ietf-httpbis-cache-11 2022 * None. 2024 C.14. Since draft-ietf-httpbis-cache-12 2026 * In Section 4.2.4, remove 'no-store', as it won't be in cache in 2027 the first place (, 2028 ) 2030 * In Section 3.1, make it clear that only response headers need be 2031 stored () 2033 * Rewrote "Updating Stored Header Fields" Section 3.2 2034 () 2036 * In Section 4.2.1 clarify how to handle invalid and conflicting 2037 directives () 2039 * In Section 4.3.3, mention retry of failed validation requests 2040 () 2042 * In Section 4.3.3, clarify requirement on storing a full response 2043 to a conditional request () 2046 * In Section 5.1, clarify error handling 2047 () 2049 * In Section 4.2, remove spurious "UTC" () 2052 * In Section 4.2, correct the date-related rule names to consider 2053 case-insensitive () 2056 * In Section 6, strengthen recommendation for application caches to 2057 pay attention to cache directives () 2060 * In Section 4, mention collapsed requests 2061 () 2063 * In Section 4.4, relax requirements on Content-Location and 2064 Location invalidation () 2067 * In Section 4.3.4, refine the exceptions to update on a 304 2068 () 2070 * Moved table of Cache-Control directives into Section 8.2 2071 () 2073 * In Section 1.2, remove unused core ABNF rules 2074 () 2076 * Changed to using "payload data" when defining requirements about 2077 the data being conveyed within a message, instead of the terms 2078 "payload body" or "response body" or "representation body", since 2079 they often get confused with the HTTP/1.1 message body (which 2080 includes transfer coding) () 2083 C.15. Since draft-ietf-httpbis-cache-13 2085 * In Section 5.2.2.2, clarify requirements around generating an 2086 error response () 2088 * Changed to using "content" instead of "payload" or "payload data" 2089 to avoid confusion with the payload of version-specific messaging 2090 frames () 2092 * In Section 4.3.4, clarify how multiple validators are handled 2093 () 2095 * In Section 4.2.3, Section 5.2, and Section 5.2.2.4, remove notes 2096 about very old HTTP/1.0 behaviours () 2099 * In Section 5.2.2.3, modify operation to be more backwards- 2100 compatible with existing implementations 2101 () 2103 C.16. Since draft-ietf-httpbis-cache-14 2105 * Fix subsection ordering in Section 5.2.2 2106 () 2108 * In Section 2, define what a cache key is 2109 () 2111 * In Section 3.1, clarify what cache proxy headers apply to 2112 () 2114 * In Section 7.1, cache poisoning can affect private caches too 2115 () 2117 * In Section 5.1, adjust handling of invalid values to match most 2118 deployed caches () 2120 * In Section 5.3, mention parsing requirement relaxation 2121 () 2123 C.17. Since draft-ietf-httpbis-cache-15 2125 * In Section 4.3.1, tune description of relation between cache keys 2126 and validators () 2128 C.18. Since draft-ietf-httpbis-cache-16 2130 This draft addresses mostly editorial issues raised during or past 2131 IETF Last Call; see for a summary. 2134 Furthermore: 2136 * Addressed Genart last call review comments 2137 () 2139 * In Section 4.3.4, clarify that only selectable responses are 2140 updated () 2142 Acknowledgements 2144 See Appendix "Acknowledgements" of [HTTP]. 2146 Index 2148 A C E F G H M N O P S V W 2150 A 2152 Age header field Section 5.1 2153 age Section 4.2 2155 C 2157 Cache-Control header field Section 5.2 2158 cache Section 1 2159 cache key Section 2; Section 2 2160 collapsed requests Section 4 2162 E 2164 Expires header field Section 5.3 2165 explicit expiration time Section 4.2 2167 F 2169 Fields 2170 Age Section 5.1; Section 5.1 2171 Cache-Control Section 5.2 2172 Expires Section 5.3; Section 5.3 2173 Pragma Section 5.4; Section 5.4 2174 Warning Section 5.5 2175 fresh Section 4.2 2176 freshness lifetime Section 4.2 2178 G 2180 Grammar 2181 Age Section 5.1 2182 Cache-Control Section 5.2 2183 DIGIT Section 1.2 2184 Expires Section 5.3 2185 cache-directive Section 5.2 2186 delta-seconds Section 1.2.2 2188 H 2190 Header Fields 2191 Age Section 5.1; Section 5.1 2192 Cache-Control Section 5.2 2193 Expires Section 5.3; Section 5.3 2194 Pragma Section 5.4; Section 5.4 2195 Warning Section 5.5 2196 heuristic expiration time Section 4.2 2197 heuristically cacheable Section 4.2.2 2199 M 2201 max-age (cache directive) Section 5.2.1.1; Section 5.2.2.1 2202 max-stale (cache directive) Section 5.2.1.2 2203 min-fresh (cache directive) Section 5.2.1.3 2204 must-revalidate (cache directive) Section 5.2.2.2 2205 must-understand (cache directive) Section 5.2.2.3 2207 N 2209 no-cache (cache directive) Section 5.2.1.4; Section 5.2.2.4 2210 no-store (cache directive) Section 5.2.1.5; Section 5.2.2.5 2211 no-transform (cache directive) Section 5.2.1.6; 2212 Section 5.2.2.6 2214 O 2216 only-if-cached (cache directive) Section 5.2.1.7 2218 P 2220 Pragma header field Section 5.4 2221 private (cache directive) Section 5.2.2.7 2222 private cache Section 1 2223 proxy-revalidate (cache directive) Section 5.2.2.8 2224 public (cache directive) Section 5.2.2.9 2226 S 2228 s-maxage (cache directive) Section 5.2.2.10 2229 selected response Section 4.1 2230 shared cache Section 1 2231 stale Section 4.2 2233 V 2235 validator Section 4.3.1 2237 W 2239 Warning header field Section 5.5 2241 Authors' Addresses 2243 Roy T. Fielding (editor) 2244 Adobe 2245 345 Park Ave 2246 San Jose, CA 95110 2247 United States of America 2249 Email: fielding@gbiv.com 2250 URI: https://roy.gbiv.com/ 2251 Mark Nottingham (editor) 2252 Fastly 2253 Prahran VIC 2254 Australia 2256 Email: mnot@mnot.net 2257 URI: https://www.mnot.net/ 2259 Julian Reschke (editor) 2260 greenbytes GmbH 2261 Hafenweg 16 2262 48155 Münster 2263 Germany 2265 Email: julian.reschke@greenbytes.de 2266 URI: https://greenbytes.de/tech/webdav/