idnits 2.17.1 draft-ietf-httpbis-cache-16.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 (27 May 2021) is 1065 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 1766, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-messaging-16 -- Possible downref: Normative reference to a draft: ref. 'Messaging' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-16 -- Possible downref: Normative reference to a draft: ref. 'Semantics' -- 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 (~~), 6 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP Working Group R. Fielding, Ed. 3 Internet-Draft Adobe 4 Obsoletes: 7234 (if approved) M. Nottingham, Ed. 5 Intended status: Standards Track Fastly 6 Expires: 28 November 2021 J. Reschke, Ed. 7 greenbytes 8 27 May 2021 10 HTTP Caching 11 draft-ietf-httpbis-cache-16 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.17. 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 28 November 2021. 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.3. Delta Seconds . . . . . . . . . . . . . . . . . . . . . . 6 86 2. Overview of Cache Operation . . . . . . . . . . . . . . . . . 6 87 3. Storing Responses in Caches . . . . . . . . . . . . . . . . . 7 88 3.1. Storing Header and Trailer Fields . . . . . . . . . . . . 8 89 3.2. Updating Stored Header Fields . . . . . . . . . . . . . . 9 90 3.3. Storing Incomplete Responses . . . . . . . . . . . . . . 10 91 3.4. Combining Partial Content . . . . . . . . . . . . . . . . 11 92 3.5. Storing Responses to Authenticated Requests . . . . . . . 11 93 4. Constructing Responses from Caches . . . . . . . . . . . . . 11 94 4.1. Calculating Cache Keys with Vary . . . . . . . . . . . . 12 95 4.2. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 14 96 4.2.1. Calculating Freshness Lifetime . . . . . . . . . . . 15 97 4.2.2. Calculating Heuristic Freshness . . . . . . . . . . . 16 98 4.2.3. Calculating Age . . . . . . . . . . . . . . . . . . . 17 99 4.2.4. Serving Stale Responses . . . . . . . . . . . . . . . 18 100 4.3. Validation . . . . . . . . . . . . . . . . . . . . . . . 18 101 4.3.1. Sending a Validation Request . . . . . . . . . . . . 19 102 4.3.2. Handling a Received Validation Request . . . . . . . 19 103 4.3.3. Handling a Validation Response . . . . . . . . . . . 21 104 4.3.4. Freshening Stored Responses upon Validation . . . . . 21 105 4.3.5. Freshening Responses with HEAD . . . . . . . . . . . 22 106 4.4. Invalidating Stored Responses . . . . . . . . . . . . . . 22 107 5. Field Definitions . . . . . . . . . . . . . . . . . . . . . . 23 108 5.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 109 5.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 24 110 5.2.1. Request Cache-Control Directives . . . . . . . . . . 24 111 5.2.1.1. max-age . . . . . . . . . . . . . . . . . . . . . 24 112 5.2.1.2. max-stale . . . . . . . . . . . . . . . . . . . . 25 113 5.2.1.3. min-fresh . . . . . . . . . . . . . . . . . . . . 25 114 5.2.1.4. no-cache . . . . . . . . . . . . . . . . . . . . 25 115 5.2.1.5. no-store . . . . . . . . . . . . . . . . . . . . 26 116 5.2.1.6. no-transform . . . . . . . . . . . . . . . . . . 26 117 5.2.1.7. only-if-cached . . . . . . . . . . . . . . . . . 26 118 5.2.2. Response Cache-Control Directives . . . . . . . . . . 26 119 5.2.2.1. max-age . . . . . . . . . . . . . . . . . . . . . 26 120 5.2.2.2. must-revalidate . . . . . . . . . . . . . . . . . 27 121 5.2.2.3. must-understand . . . . . . . . . . . . . . . . . 27 122 5.2.2.4. no-cache . . . . . . . . . . . . . . . . . . . . 27 123 5.2.2.5. no-store . . . . . . . . . . . . . . . . . . . . 28 124 5.2.2.6. no-transform . . . . . . . . . . . . . . . . . . 29 125 5.2.2.7. private . . . . . . . . . . . . . . . . . . . . . 29 126 5.2.2.8. proxy-revalidate . . . . . . . . . . . . . . . . 30 127 5.2.2.9. public . . . . . . . . . . . . . . . . . . . . . 30 128 5.2.2.10. s-maxage . . . . . . . . . . . . . . . . . . . . 30 129 5.2.3. Cache Control Extensions . . . . . . . . . . . . . . 31 130 5.2.4. Cache Directive Registry . . . . . . . . . . . . . . 32 131 5.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 32 132 5.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . 33 133 5.5. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 33 134 6. Relationship to Applications and Other Caches . . . . . . . . 33 135 7. Security Considerations . . . . . . . . . . . . . . . . . . . 34 136 7.1. Cache Poisoning . . . . . . . . . . . . . . . . . . . . . 35 137 7.2. Timing Attacks . . . . . . . . . . . . . . . . . . . . . 35 138 7.3. Caching of Sensitive Information . . . . . . . . . . . . 35 139 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 140 8.1. Field Name Registration . . . . . . . . . . . . . . . . . 36 141 8.2. Cache Directive Registration . . . . . . . . . . . . . . 36 142 8.3. Warn Code Registry . . . . . . . . . . . . . . . . . . . 37 144 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 145 9.1. Normative References . . . . . . . . . . . . . . . . . . 37 146 9.2. Informative References . . . . . . . . . . . . . . . . . 38 147 Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 39 148 Appendix B. Changes from RFC 7234 . . . . . . . . . . . . . . . 39 149 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 40 150 C.1. Between RFC7234 and draft 00 . . . . . . . . . . . . . . 40 151 C.2. Since draft-ietf-httpbis-cache-00 . . . . . . . . . . . . 41 152 C.3. Since draft-ietf-httpbis-cache-01 . . . . . . . . . . . . 41 153 C.4. Since draft-ietf-httpbis-cache-02 . . . . . . . . . . . . 41 154 C.5. Since draft-ietf-httpbis-cache-03 . . . . . . . . . . . . 41 155 C.6. Since draft-ietf-httpbis-cache-04 . . . . . . . . . . . . 42 156 C.7. Since draft-ietf-httpbis-cache-05 . . . . . . . . . . . . 42 157 C.8. Since draft-ietf-httpbis-cache-06 . . . . . . . . . . . . 42 158 C.9. Since draft-ietf-httpbis-cache-07 . . . . . . . . . . . . 43 159 C.10. Since draft-ietf-httpbis-cache-08 . . . . . . . . . . . . 43 160 C.11. Since draft-ietf-httpbis-cache-09 . . . . . . . . . . . . 43 161 C.12. Since draft-ietf-httpbis-cache-10 . . . . . . . . . . . . 43 162 C.13. Since draft-ietf-httpbis-cache-11 . . . . . . . . . . . . 44 163 C.14. Since draft-ietf-httpbis-cache-12 . . . . . . . . . . . . 44 164 C.15. Since draft-ietf-httpbis-cache-13 . . . . . . . . . . . . 45 165 C.16. Since draft-ietf-httpbis-cache-14 . . . . . . . . . . . . 45 166 C.17. Since draft-ietf-httpbis-cache-15 . . . . . . . . . . . . 46 167 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 46 168 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 169 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 171 1. Introduction 173 The Hypertext Transfer Protocol (HTTP) is a stateless application- 174 level request/response protocol that uses extensible semantics and 175 self-descriptive messages for flexible interaction with network-based 176 hypertext information systems. It is typically used for distributed 177 information systems, where the use of response caches can improve 178 performance. This document defines aspects of HTTP related to 179 caching and reusing response messages. 181 An HTTP _cache_ is a local store of response messages and the 182 subsystem that controls storage, retrieval, and deletion of messages 183 in it. A cache stores cacheable responses to reduce the response 184 time and network bandwidth consumption on future equivalent requests. 185 Any client or server MAY use a cache, though not when acting as a 186 tunnel. 188 A _shared cache_ is a cache that stores responses for reuse by more 189 than one user; shared caches are usually (but not always) deployed as 190 a part of an intermediary. A _private cache_, in contrast, is 191 dedicated to a single user; often, they are deployed as a component 192 of a user agent. 194 HTTP caching's goal is significantly improving performance by reusing 195 a prior response message to satisfy a current request. A cache 196 considers a stored response "fresh", as defined in Section 4.2, if it 197 can be reused without "validation" (checking with the origin server 198 to see if the cached response remains valid for this request). A 199 fresh response can therefore reduce both latency and network overhead 200 each time the cache reuses it. When a cached response is not fresh, 201 it might still be reusable if validation can freshen it (Section 4.3) 202 or if the origin is unavailable (Section 4.2.4). 204 This document obsoletes RFC 7234, with the changes being summarized 205 in Appendix B. 207 1.1. Requirements Notation 209 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 210 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 211 "OPTIONAL" in this document are to be interpreted as described in BCP 212 14 [RFC2119] [RFC8174] when, and only when, they appear in all 213 capitals, as shown here. 215 Section 2 of [Semantics] defines conformance criteria and contains 216 considerations regarding error handling. 218 1.2. Syntax Notation 220 This specification uses the Augmented Backus-Naur Form (ABNF) 221 notation of [RFC5234], extended with the notation for case- 222 sensitivity in strings defined in [RFC7405]. 224 It also uses a list extension, defined in Section 5.6.1 of 225 [Semantics], that allows for compact definition of comma-separated 226 lists using a '#' operator (similar to how the '*' operator indicates 227 repetition). Appendix A shows the collected grammar with all list 228 operators expanded to standard ABNF notation. 230 The following core rule is included by reference, as defined in 231 [RFC5234], Appendix B.1: DIGIT (decimal 0-9). 233 [Semantics] defines the following rules: 235 HTTP-date = 236 OWS = 237 field-name = 238 quoted-string = 239 token = 241 1.3. Delta Seconds 243 The delta-seconds rule specifies a non-negative integer, representing 244 time in seconds. 246 delta-seconds = 1*DIGIT 248 A recipient parsing a delta-seconds value and converting it to binary 249 form ought to use an arithmetic type of at least 31 bits of non- 250 negative integer range. If a cache receives a delta-seconds value 251 greater than the greatest integer it can represent, or if any of its 252 subsequent calculations overflows, the cache MUST consider the value 253 to be 2147483648 (2^31) or the greatest positive integer it can 254 conveniently represent. 256 | *Note:* The value 2147483648 is here for historical reasons, 257 | represents infinity (over 68 years), and does not need to be 258 | stored in binary form; an implementation could produce it as a 259 | canned string if any overflow occurs, even if the calculations 260 | are performed with an arithmetic type incapable of directly 261 | representing that number. What matters here is that an 262 | overflow be detected and not treated as a negative value in 263 | later calculations. 265 2. Overview of Cache Operation 267 Proper cache operation preserves the semantics of HTTP transfers 268 ([Semantics]) while reducing the transmission of information already 269 held in the cache. Although caching is an entirely OPTIONAL feature 270 of HTTP, it can be assumed that reusing a cached response is 271 desirable and that such reuse is the default behavior when no 272 requirement or local configuration prevents it. Therefore, HTTP 273 cache requirements are focused on preventing a cache from either 274 storing a non-reusable response or reusing a stored response 275 inappropriately, rather than mandating that caches always store and 276 reuse particular responses. 278 The _cache key_ is the information a cache uses to select a response 279 and is comprised of, at a minimum, the request method and target URI 280 used to retrieve the stored response; the method determines under 281 which circumstances that response can be used to satisfy a subsequent 282 request. However, many HTTP caches in common use today only cache 283 GET responses, and therefore only use the URI as the cache key, 284 forwarding other methods. 286 If a request target is subject to content negotiation, the cache 287 might store multiple responses for it. Caches differentiate these 288 responses by incorporating values of the original request's selecting 289 header fields into the cache key as well, using information in the 290 Vary response header field, as per Section 4.1. 292 Caches might incorporate additional material into the cache key. For 293 example, user agent caches might include the referring site's 294 identity, thereby "double keying" the cache to avoid some privacy 295 risks (see Section 7.2). 297 Most commonly, caches store the successful result of a retrieval 298 request: i.e., a 200 (OK) response to a GET request, which contains a 299 representation of the target resource (Section 9.3.1 of [Semantics]). 300 However, it is also possible to store redirects, negative results 301 (e.g., 404 (Not Found)), incomplete results (e.g., 206 (Partial 302 Content)), and responses to methods other than GET if the method's 303 definition allows such caching and defines something suitable for use 304 as a cache key. 306 A cache is _disconnected_ when it cannot contact the origin server or 307 otherwise find a forward path for a request. A disconnected cache 308 can serve stale responses in some circumstances (Section 4.2.4). 310 3. Storing Responses in Caches 312 A cache MUST NOT store a response to a request unless: 314 * the request method is understood by the cache; 316 * the response status code is final (see Section 15 of [Semantics]); 318 * if the response status code is 206 or 304, or the "must- 319 understand" cache directive (see Section 5.2.2.3) is present: the 320 cache understands the response status code; 322 * the "no-store" cache directive is not present in the response (see 323 Section 5.2.2.5); 325 * if the cache is shared: the "private" response directive is either 326 not present or allows a shared cache to store a modified response; 327 see Section 5.2.2.7); 329 * if the cache is shared: the Authorization header field is not 330 present in the request (see Section 11.6.2 of [Semantics]) or a 331 response directive is present that explicitly allows shared 332 caching (see Section 3.5); and, 334 * the response contains at least one of: 336 - a public response directive (see Section 5.2.2.9); 338 - a private response directive, if the cache is not shared (see 339 Section 5.2.2.7); 341 - an Expires header field (see Section 5.3); 343 - a max-age response directive (see Section 5.2.2.1); 345 - if the cache is shared: an s-maxage response directive (see 346 Section 5.2.2.10); 348 - a Cache Control Extension that allows it to be cached (see 349 Section 5.2.3); or, 351 - a status code that is defined as heuristically cacheable (see 352 Section 4.2.2). 354 Note that a cache-control extension can override any of the 355 requirements listed; see Section 5.2.3. 357 In this context, a cache has "understood" a request method or a 358 response status code if it recognizes it and implements all specified 359 caching-related behavior. 361 Note that, in normal operation, some caches will not store a response 362 that has neither a cache validator nor an explicit expiration time, 363 as such responses are not usually useful to store. However, caches 364 are not prohibited from storing such responses. 366 3.1. Storing Header and Trailer Fields 368 Caches MUST include all received response header fields - including 369 unrecognised ones - when storing a response; this assures that new 370 HTTP header fields can be successfully deployed. However, the 371 following exceptions are made: 373 * The Connection header field and fields whose names are listed in 374 it are required by Section 7.6.1 of [Semantics] to be removed 375 before forwarding the message. This MAY be implemented by doing 376 so before storage. 378 * Likewise, some fields' semantics require them to be removed before 379 forwarding the message, and this MAY be implemented by doing so 380 before storage; see Section 7.6.1 of [Semantics] for some 381 examples. 383 * The no-cache (Section 5.2.2.4) and private (Section 5.2.2.7) cache 384 directives can have arguments that prevent storage of header 385 fields by all caches and shared caches, respectively. 387 * Header fields that are specific to the proxy that a cache uses 388 when forwarding a request MUST NOT be stored, unless the cache 389 incorporates the identity of the proxy into the cache key. 390 Effectively, this is limited to Proxy-Authenticate (Section 11.7.1 391 of [Semantics]), Proxy-Authentication-Info (Section 11.7.3 of 392 [Semantics]), and Proxy-Authorization (Section 11.7.2 of 393 [Semantics]). 395 Caches MAY either store trailer fields separate from header fields, 396 or discard them. Caches MUST NOT combine trailer fields with header 397 fields. 399 3.2. Updating Stored Header Fields 401 Caches are required to update a stored response's header fields from 402 another (typically newer) response in several situations; for 403 example, see Section 3.4, Section 4.3.4 and Section 4.3.5. 405 When doing so, the cache MUST add each header field in the provided 406 response to the stored response, replacing field values that are 407 already present, with the following exceptions: 409 * Header fields excepted from storage in Section 3.1, 411 * Header fields that the cache's stored response depends upon, as 412 described below, 414 * Header fields that are automatically processed and removed by the 415 recipient, as described below, and 417 * The Content-Length header field. 419 In some cases, caches (especially in user agents) store the results 420 of processing the received response, rather than the response itself, 421 and updating header fields that affect that processing can result in 422 inconsistent behavior and security issues. Caches in this situation 423 MAY omit these header fields from updating stored responses on an 424 exceptional basis, but SHOULD limit such omission to those fields 425 necessary to assure integrity of the stored response. 427 For example, a browser might decode the content coding of a response 428 while it is being received, creating a disconnect between the data it 429 has stored and the response's original metadata. Updating that 430 stored metadata with a different Content-Encoding header field would 431 be problematic. Likewise, a browser might store a post-parse HTML 432 tree, rather than the content received in the response; updating the 433 Content-Type header field would not be workable in this case, because 434 any assumptions about the format made in parsing would now be 435 invalid. 437 Furthermore, some fields are automatically processed and removed by 438 the HTTP implementation; for example, the Content-Range header field. 439 Implementations MAY automatically omit such header fields from 440 updates, even when the processing does not actually occur. 442 Note that the Content-* prefix is not a signal that a header field is 443 omitted from update; it is a convention for MIME header fields, not 444 HTTP. 446 3.3. Storing Incomplete Responses 448 If the request method is GET, the response status code is 200 (OK), 449 and the entire response header section has been received, a cache MAY 450 store a response body that is not complete (Section 3.4 of 451 [Semantics]) if the stored response is recorded as being incomplete. 452 Likewise, a 206 (Partial Content) response MAY be stored as if it 453 were an incomplete 200 (OK) response. However, a cache MUST NOT 454 store incomplete or partial-content responses if it does not support 455 the Range and Content-Range header fields or if it does not 456 understand the range units used in those fields. 458 A cache MAY complete a stored incomplete response by making a 459 subsequent range request (Section 14.2 of [Semantics]) and combining 460 the successful response with the stored response, as defined in 461 Section 3.4. A cache MUST NOT use an incomplete response to answer 462 requests unless the response has been made complete, or the request 463 is partial and specifies a range wholly within the incomplete 464 response. A cache MUST NOT send a partial response to a client 465 without explicitly marking it using the 206 (Partial Content) status 466 code. 468 3.4. Combining Partial Content 470 A response might transfer only a partial representation if the 471 connection closed prematurely or if the request used one or more 472 Range specifiers (Section 14.2 of [Semantics]). After several such 473 transfers, a cache might have received several ranges of the same 474 representation. A cache MAY combine these ranges into a single 475 stored response, and reuse that response to satisfy later requests, 476 if they all share the same strong validator and the cache complies 477 with the client requirements in Section 15.3.7.3 of [Semantics]. 479 When combining the new response with one or more stored responses, a 480 cache MUST update the stored response header fields using the header 481 fields provided in the new response, as per Section 3.2. 483 3.5. Storing Responses to Authenticated Requests 485 A shared cache MUST NOT use a cached response to a request with an 486 Authorization header field (Section 11.6.2 of [Semantics]) to satisfy 487 any subsequent request unless the response contains a Cache-Control 488 field with a response directive (Section 5.2.2) that allows it to be 489 stored by a shared cache and the cache conforms to the requirements 490 of that directive for that response. 492 In this specification, the following response directives have such an 493 effect: must-revalidate (Section 5.2.2.2), public (Section 5.2.2.9), 494 and s-maxage (Section 5.2.2.10). 496 4. Constructing Responses from Caches 498 When presented with a request, a cache MUST NOT reuse a stored 499 response, unless: 501 * The presented target URI (Section 7.1 of [Semantics]) and that of 502 the stored response match, and 504 * the request method associated with the stored response allows it 505 to be used for the presented request, and 507 * selecting header fields nominated by the stored response (if any) 508 match those presented (see Section 4.1), and 510 * the stored response does not contain the no-cache cache directive 511 (Section 5.2.2.4), unless it is successfully validated 512 (Section 4.3), and 514 * the stored response is either: 516 - fresh (see Section 4.2), or 518 - allowed to be served stale (see Section 4.2.4), or 520 - successfully validated (see Section 4.3). 522 Note that a cache-control extension can override any of the 523 requirements listed; see Section 5.2.3. 525 When a stored response is used to satisfy a request without 526 validation, a cache MUST generate an Age header field (Section 5.1), 527 replacing any present in the response with a value equal to the 528 stored response's current_age; see Section 4.2.3. 530 A cache MUST write through requests with methods that are unsafe 531 (Section 9.2.1 of [Semantics]) to the origin server; i.e., a cache is 532 not allowed to generate a reply to such a request before having 533 forwarded the request and having received a corresponding response. 535 Also, note that unsafe requests might invalidate already-stored 536 responses; see Section 4.4. 538 A response that is stored or storable can be used to satisfy multiple 539 requests, provided that it is allowed to reuse that response for the 540 requests in question. This enables caches to _collapse requests_ - 541 or combine multiple incoming requests into a single forward one upon 542 a cache miss - thereby reducing load on the origin server and 543 network. However, note that if the response returned is not able to 544 be used for some or all of the collapsed requests, additional latency 545 might be introduced, because they will need to be forwarded to be 546 satisfied. 548 When more than one suitable response is stored, a cache MUST use the 549 most recent one (as determined by the Date header field). It can 550 also forward the request with "Cache-Control: max-age=0" or "Cache- 551 Control: no-cache" to disambiguate which response to use. 553 A cache that does not have a clock available MUST NOT use stored 554 responses without revalidating them upon every use. 556 4.1. Calculating Cache Keys with Vary 558 When a cache receives a request that can be satisfied by a stored 559 response that has a Vary header field (Section 12.5.5 of 560 [Semantics]), it MUST NOT use that response unless all the selecting 561 header fields nominated by the Vary header field match in both the 562 original request (i.e., that associated with the stored response), 563 and the presented request. 565 The selecting header fields from two requests are defined to match if 566 and only if those in the first request can be transformed to those in 567 the second request by applying any of: 569 * adding or removing whitespace, where allowed in the header field's 570 syntax 572 * combining multiple header field lines with the same field name 573 (see Section 5.2 of [Semantics]) 575 * normalizing both header field values in a way that is known to 576 have identical semantics, according to the header field's 577 specification (e.g., reordering field values when order is not 578 significant; case-normalization, where values are defined to be 579 case-insensitive) 581 If (after any normalization that might take place) a header field is 582 absent from a request, it can only match another request if it is 583 also absent there. 585 A Vary header field value containing a member "*" always fails to 586 match. 588 The stored response with matching selecting header fields is known as 589 the _selected response_. 591 If multiple selected responses are available (potentially including 592 responses without a Vary header field), the cache will need to choose 593 one to use. When a selecting header field has a known mechanism for 594 doing so (e.g., qvalues on Accept and similar request header fields), 595 that mechanism MAY be used to select a preferred response. If such a 596 mechanism is not available, or leads to equally preferred responses, 597 the most recent response (as determined by the Date header field) is 598 used, as per Section 4. 600 Some resources mistakenly omit the Vary header field from their 601 default response (i.e., the one sent when no more preferable response 602 is available), with the effect of selecting it for requests to that 603 resource even when more preferable responses are available. When a 604 cache has multiple responses for a target URI and one or more omits 605 the Vary header field, it SHOULD use the most recent (see 606 Section 4.2.3) valid Vary field value available to select an 607 appropriate response for the request. 609 If no selected response is available, the cache cannot satisfy the 610 presented request. Typically, it is forwarded to the origin server 611 in a (possibly conditional; see Section 4.3) request. 613 4.2. Freshness 615 A _fresh_ response is one whose age has not yet exceeded its 616 freshness lifetime. Conversely, a _stale_ response is one where it 617 has. 619 A response's _freshness lifetime_ is the length of time between its 620 generation by the origin server and its expiration time. An 621 _explicit expiration time_ is the time at which the origin server 622 intends that a stored response can no longer be used by a cache 623 without further validation, whereas a _heuristic expiration time_ is 624 assigned by a cache when no explicit expiration time is available. 626 A response's _age_ is the time that has passed since it was generated 627 by, or successfully validated with, the origin server. 629 When a response is fresh, it can be used to satisfy subsequent 630 requests without contacting the origin server, thereby improving 631 efficiency. 633 The primary mechanism for determining freshness is for an origin 634 server to provide an explicit expiration time in the future, using 635 either the Expires header field (Section 5.3) or the max-age response 636 directive (Section 5.2.2.1). Generally, origin servers will assign 637 future explicit expiration times to responses in the belief that the 638 representation is not likely to change in a semantically significant 639 way before the expiration time is reached. 641 If an origin server wishes to force a cache to validate every 642 request, it can assign an explicit expiration time in the past to 643 indicate that the response is already stale. Compliant caches will 644 normally validate a stale cached response before reusing it for 645 subsequent requests (see Section 4.2.4). 647 Since origin servers do not always provide explicit expiration times, 648 caches are also allowed to use a heuristic to determine an expiration 649 time under certain circumstances (see Section 4.2.2). 651 The calculation to determine if a response is fresh is: 653 response_is_fresh = (freshness_lifetime > current_age) 655 freshness_lifetime is defined in Section 4.2.1; current_age is 656 defined in Section 4.2.3. 658 Clients can send the max-age or min-fresh request directives 659 (Section 5.2.1) to constrain or relax freshness calculations for the 660 corresponding response. However, caches are not required to honor 661 them. 663 When calculating freshness, to avoid common problems in date parsing: 665 * Although all date formats are specified to be case-sensitive, a 666 cache recipient SHOULD match the field value case-insensitively. 668 * If a cache recipient's internal implementation of time has less 669 resolution than the value of an HTTP-date, the recipient MUST 670 internally represent a parsed Expires date as the nearest time 671 equal to or earlier than the received value. 673 * A cache recipient MUST NOT allow local time zones to influence the 674 calculation or comparison of an age or expiration time. 676 * A cache recipient SHOULD consider a date with a zone abbreviation 677 other than "GMT" to be invalid for calculating expiration. 679 Note that freshness applies only to cache operation; it cannot be 680 used to force a user agent to refresh its display or reload a 681 resource. See Section 6 for an explanation of the difference between 682 caches and history mechanisms. 684 4.2.1. Calculating Freshness Lifetime 686 A cache can calculate the freshness lifetime (denoted as 687 freshness_lifetime) of a response by using the first match of: 689 * If the cache is shared and the s-maxage response directive 690 (Section 5.2.2.10) is present, use its value, or 692 * If the max-age response directive (Section 5.2.2.1) is present, 693 use its value, or 695 * If the Expires response header field (Section 5.3) is present, use 696 its value minus the value of the Date response header field (using 697 the time the message was received if it is not present, as per 698 Section 10.2.2 of [Semantics]), or 700 * Otherwise, no explicit expiration time is present in the response. 701 A heuristic freshness lifetime might be applicable; see 702 Section 4.2.2. 704 Note that this calculation is not vulnerable to clock skew, since all 705 of the information comes from the origin server. 707 When there is more than one value present for a given directive 708 (e.g., two Expires header field lines or multiple Cache-Control: max- 709 age directives), either the first occurrence should be used, or the 710 response should be considered stale. If directives conflict (e.g., 711 both max-age and no-cache are present), the most restrictive 712 directive should be honored. Caches are encouraged to consider 713 responses that have invalid freshness information (e.g., a max-age 714 directive with non-integer content) to be stale. 716 4.2.2. Calculating Heuristic Freshness 718 Since origin servers do not always provide explicit expiration times, 719 a cache MAY assign a heuristic expiration time when an explicit time 720 is not specified, employing algorithms that use other field values 721 (such as the Last-Modified time) to estimate a plausible expiration 722 time. This specification does not provide specific algorithms, but 723 does impose worst-case constraints on their results. 725 A cache MUST NOT use heuristics to determine freshness when an 726 explicit expiration time is present in the stored response. Because 727 of the requirements in Section 3, this means that heuristics can only 728 be used on responses without explicit freshness whose status codes 729 are defined as _heuristically cacheable_ (e.g., see Section 15.1 of 730 [Semantics]), and those responses without explicit freshness that 731 have been marked as explicitly cacheable (e.g., with a "public" 732 response directive). 734 Note that in previous specifications heuristically cacheable response 735 status codes were called "cacheable by default." 737 If the response has a Last-Modified header field (Section 8.8.2 of 738 [Semantics]), caches are encouraged to use a heuristic expiration 739 value that is no more than some fraction of the interval since that 740 time. A typical setting of this fraction might be 10%. 742 | *Note:* Section 13.9 of [RFC2616] prohibited caches from 743 | calculating heuristic freshness for URIs with query components 744 | (i.e., those containing '?'). In practice, this has not been 745 | widely implemented. Therefore, origin servers are encouraged 746 | to send explicit directives (e.g., Cache-Control: no-cache) if 747 | they wish to prevent caching. 749 4.2.3. Calculating Age 751 The Age header field is used to convey an estimated age of the 752 response message when obtained from a cache. The Age field value is 753 the cache's estimate of the number of seconds since the origin server 754 generated or validated the response. The Age value is therefore the 755 sum of the time that the response has been resident in each of the 756 caches along the path from the origin server, plus the time it has 757 been in transit along network paths. 759 Age calculation uses the following data: 761 _age_value_ The term "age_value" denotes the value of the Age header 762 field (Section 5.1), in a form appropriate for arithmetic 763 operation; or 0, if not available. 765 _date_value_ The term "date_value" denotes the value of the Date 766 header field, in a form appropriate for arithmetic operations. 767 See Section 10.2.2 of [Semantics] for the definition of the Date 768 header field, and for requirements regarding responses without it. 770 _now_ The term "now" means "the current value of the clock at the 771 host performing the calculation". A host ought to use NTP 772 ([RFC5905]) or some similar protocol to synchronize its clocks to 773 Coordinated Universal Time. 775 _request_time_ The current value of the clock at the host at the 776 time the request resulting in the stored response was made. 778 _response_time_ The current value of the clock at the host at the 779 time the response was received. 781 A response's age can be calculated in two entirely independent ways: 783 1. the "apparent_age": response_time minus date_value, if the local 784 clock is reasonably well synchronized to the origin server's 785 clock. If the result is negative, the result is replaced by 786 zero. 788 2. the "corrected_age_value", if all of the caches along the 789 response path implement HTTP/1.1 or greater. A cache MUST 790 interpret this value relative to the time the request was 791 initiated, not the time that the response was received. 793 apparent_age = max(0, response_time - date_value); 795 response_delay = response_time - request_time; 796 corrected_age_value = age_value + response_delay; 798 The corrected_age_value MAY be used as the corrected_initial_age. In 799 circumstances where very old cache implementations that might not 800 correctly insert Age are present, corrected_initial_age can be 801 calculated more conservatively as 803 corrected_initial_age = max(apparent_age, corrected_age_value); 805 The current_age of a stored response can then be calculated by adding 806 the time (in seconds) since the stored response was last validated by 807 the origin server to the corrected_initial_age. 809 resident_time = now - response_time; 810 current_age = corrected_initial_age + resident_time; 812 4.2.4. Serving Stale Responses 814 A "stale" response is one that either has explicit expiry information 815 or is allowed to have heuristic expiry calculated, but is not fresh 816 according to the calculations in Section 4.2. 818 A cache MUST NOT generate a stale response if it is prohibited by an 819 explicit in-protocol directive (e.g., by a "no-cache" cache 820 directive, a "must-revalidate" cache-response-directive, or an 821 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 822 see Section 5.2.2). 824 A cache MUST NOT generate a stale response unless it is disconnected 825 or doing so is explicitly permitted by the client or origin server 826 (e.g., by the max-stale request directive in Section 5.2.1, by 827 extension directives such as those defined in [RFC5861], or by 828 configuration in accordance with an out-of-band contract). 830 4.3. Validation 832 When a cache has one or more stored responses for a requested URI, 833 but cannot serve any of them (e.g., because they are not fresh, or 834 one cannot be selected; see Section 4.1), it can use the conditional 835 request mechanism (Section 13.1 of [Semantics]) in the forwarded 836 request to give the next inbound server an opportunity to select a 837 valid stored response to use, updating the stored metadata in the 838 process, or to replace the stored response(s) with a new response. 839 This process is known as _validating_ or _revalidating_ the stored 840 response. 842 4.3.1. Sending a Validation Request 844 When generating a conditional request for validation, a cache starts 845 with either a request it is attempting to satisfy, or - if it is 846 initiating the request independently - it synthesises a request using 847 a stored response by copying the method, target URI, and request 848 header fields identified by the Vary header field (Section 4.1). 850 It then updates that request with one or more precondition header 851 fields. These contain validator metadata sourced from stored 852 response(s) that have the same URI. Typically, this will include 853 only those stored responses(s) that have the same cache key, although 854 a cache is allowed to validate a response that it cannot select with 855 the request header fields it is sending. 857 The precondition header fields are then compared by recipients to 858 determine whether any stored response is equivalent to a current 859 representation of the resource. 861 One such validator is the timestamp given in a Last-Modified header 862 field (Section 8.8.2 of [Semantics]), which can be used in an If- 863 Modified-Since header field for response validation, or in an If- 864 Unmodified-Since or If-Range header field for representation 865 selection (i.e., the client is referring specifically to a previously 866 obtained representation with that timestamp). 868 Another validator is the entity-tag given in an ETag field 869 (Section 8.8.3 of [Semantics]). One or more entity-tags, indicating 870 one or more stored responses, can be used in an If-None-Match header 871 field for response validation, or in an If-Match or If-Range header 872 field for representation selection (i.e., the client is referring 873 specifically to one or more previously obtained representations with 874 the listed entity-tags). 876 4.3.2. Handling a Received Validation Request 878 Each client in the request chain may have its own cache, so it is 879 common for a cache at an intermediary to receive conditional requests 880 from other (outbound) caches. Likewise, some user agents make use of 881 conditional requests to limit data transfers to recently modified 882 representations or to complete the transfer of a partially retrieved 883 representation. 885 If a cache receives a request that can be satisfied by reusing a 886 stored 200 (OK) or 206 (Partial Content) response, as per Section 4, 887 the cache SHOULD evaluate any applicable conditional header field 888 preconditions received in that request with respect to the 889 corresponding validators contained within the selected response. 891 A cache MUST NOT evaluate conditional header fields that only apply 892 to an origin server, occur in a request with semantics that cannot be 893 satisfied with a cached response, or occur in a request with a target 894 resource for which it has no stored responses; such preconditions are 895 likely intended for some other (inbound) server. 897 The proper evaluation of conditional requests by a cache depends on 898 the received precondition header fields and their precedence. In 899 summary, the If-Match and If-Unmodified-Since conditional header 900 fields are not applicable to a cache, and If-None-Match takes 901 precedence over If-Modified-Since. See Section 13.2.2 of [Semantics] 902 for a complete specification of precondition precedence. 904 A request containing an If-None-Match header field (Section 13.1.2 of 905 [Semantics]) indicates that the client wants to validate one or more 906 of its own stored responses in comparison to the stored response 907 selected by the cache (as per Section 4). 909 If an If-None-Match header field is not present, a request containing 910 an If-Modified-Since header field (Section 13.1.3 of [Semantics]) 911 indicates that the client wants to validate one or more of its own 912 stored responses by modification date. 914 If a request contains an If-Modified-Since header field and the Last- 915 Modified header field is not present in a selected stored response, a 916 cache SHOULD use the stored response's Date field value (or, if no 917 Date field is present, the time that the stored response was 918 received) to evaluate the conditional. 920 A cache that implements partial responses to range requests, as 921 defined in Section 14.2 of [Semantics], also needs to evaluate a 922 received If-Range header field (Section 13.1.5 of [Semantics]) 923 regarding its selected stored response. 925 When a cache decides to forward a request to revalidate its own 926 stored responses for a request that contains an If-None-Match list of 927 entity-tags, the cache MAY combine the received list with a list of 928 entity-tags from its own stored set of responses (fresh or stale) and 929 send the union of the two lists as a replacement If-None-Match header 930 field value in the forwarded request. If a stored response contains 931 only partial content, the cache MUST NOT include its entity-tag in 932 the union unless the request is for a range that would be fully 933 satisfied by that partial stored response. If the response to the 934 forwarded request is 304 (Not Modified) and has an ETag field value 935 with an entity-tag that is not in the client's list, the cache MUST 936 generate a 200 (OK) response for the client by reusing its 937 corresponding stored response, as updated by the 304 response 938 metadata (Section 4.3.4). 940 4.3.3. Handling a Validation Response 942 Cache handling of a response to a conditional request depends upon 943 its status code: 945 * A 304 (Not Modified) response status code indicates that the 946 stored response can be updated and reused; see Section 4.3.4. 948 * A full response (i.e., one containing content) indicates that none 949 of the stored responses nominated in the conditional request is 950 suitable. Instead, the cache MUST use the full response to 951 satisfy the request. The cache MAY store such a full response, 952 subject to its constraints (see Section 3). 954 * However, if a cache receives a 5xx (Server Error) response while 955 attempting to validate a response, it can either forward this 956 response to the requesting client, or act as if the server failed 957 to respond. In the latter case, the cache can send a previously 958 stored response, subject to its constraints on doing so (see 959 Section 4.2.4), or retry the validation request. 961 4.3.4. Freshening Stored Responses upon Validation 963 When a cache receives a 304 (Not Modified) response and already has 964 one or more stored 200 (OK) responses for the applicable request URI, 965 the cache needs to identify which (if any) are to be updated by the 966 new information provided, and then do so. 968 The stored response(s) to update are identified by using the first 969 match (if any) of: 971 * If the new response contains one or more _strong validators_ (see 972 Section 8.8.1 of [Semantics]), then each of those strong 973 validators identify the selected representation for update. All 974 the stored responses with one of those same strong validators are 975 identified for update. If none of the stored responses contain at 976 least one of the same strong validators, then the cache MUST NOT 977 use the new response to update any stored responses. 979 * If the new response contains no strong validators but does contain 980 one or more _weak validators_, and those validators correspond to 981 one of the cache's stored responses, then the most recent of those 982 matching stored responses is identified for update. 984 * If the new response does not include any form of validator (such 985 as where a client generates an If-Modified-Since request from a 986 source other than the Last-Modified response header field), and 987 there is only one stored response, and that stored response also 988 lacks a validator, then that stored response is identified for 989 update. 991 For each stored response identified, the cache MUST update its header 992 fields with the header fields provided in the 304 (Not Modified) 993 response, as per Section 3.2. 995 4.3.5. Freshening Responses with HEAD 997 A response to the HEAD method is identical to what an equivalent 998 request made with a GET would have been, without sending the content. 999 This property of HEAD responses can be used to invalidate or update a 1000 cached GET response if the more efficient conditional GET request 1001 mechanism is not available (due to no validators being present in the 1002 stored response) or if transmission of the content is not desired 1003 even if it has changed. 1005 When a cache makes an inbound HEAD request for a target URI and 1006 receives a 200 (OK) response, the cache SHOULD update or invalidate 1007 each of its stored GET responses that could have been selected for 1008 that request (see Section 4.1). 1010 For each of the stored responses that could have been selected, if 1011 the stored response and HEAD response have matching values for any 1012 received validator fields (ETag and Last-Modified) and, if the HEAD 1013 response has a Content-Length header field, the value of Content- 1014 Length matches that of the stored response, the cache SHOULD update 1015 the stored response as described below; otherwise, the cache SHOULD 1016 consider the stored response to be stale. 1018 If a cache updates a stored response with the metadata provided in a 1019 HEAD response, the cache MUST use the header fields provided in the 1020 HEAD response to update the stored response (see Section 3.2). 1022 4.4. Invalidating Stored Responses 1024 Because unsafe request methods (Section 9.2.1 of [Semantics]) such as 1025 PUT, POST or DELETE have the potential for changing state on the 1026 origin server, intervening caches are required to invalidate stored 1027 responses to keep their contents up to date. 1029 A cache MUST invalidate the target URI (Section 7.1 of [Semantics]) 1030 when it receives a non-error status code in response to an unsafe 1031 request method (including methods whose safety is unknown). 1033 A cache MAY invalidate other URIs when it receives a non-error status 1034 code in response to an unsafe request method (including methods whose 1035 safety is unknown). In particular, the URI(s) in the Location and 1036 Content-Location response header fields (if present) are candidates 1037 for invalidation; other URIs might be discovered through mechanisms 1038 not specified in this document. However, a cache MUST NOT trigger an 1039 invalidation under these conditions if the origin (Section 4.3.1 of 1040 [Semantics]) of the URI to be invalidated differs from that of the 1041 target URI (Section 7.1 of [Semantics]). This helps prevent denial- 1042 of-service attacks. 1044 _Invalidate_ means that the cache will either remove all stored 1045 responses whose target URI matches the given URI, or will mark them 1046 as "invalid" and in need of a mandatory validation before they can be 1047 sent in response to a subsequent request. 1049 A "non-error response" is one with a 2xx (Successful) or 3xx 1050 (Redirection) status code. 1052 Note that this does not guarantee that all appropriate responses are 1053 invalidated globally; a state-changing request would only invalidate 1054 responses in the caches it travels through. 1056 5. Field Definitions 1058 This section defines the syntax and semantics of HTTP fields related 1059 to caching. 1061 5.1. Age 1063 The "Age" response header field conveys the sender's estimate of the 1064 time since the response was generated or successfully validated at 1065 the origin server. Age values are calculated as specified in 1066 Section 4.2.3. 1068 Age = delta-seconds 1070 The Age field value is a non-negative integer, representing time in 1071 seconds (see Section 1.3). 1073 Although it is defined as a singleton header field, a cache 1074 encountering a message with a list-based Age field value SHOULD use 1075 the first member of the field value, discarding subsequent ones. 1077 If the field value (after discarding additional members, as per 1078 above) is invalid (e.g., it contains something other than a non- 1079 negative integer), a cache SHOULD ignore the field. 1081 The presence of an Age header field implies that the response was not 1082 generated or validated by the origin server for this request. 1083 However, lack of an Age header field does not imply the origin was 1084 contacted. 1086 5.2. Cache-Control 1088 The "Cache-Control" header field is used to list directives for 1089 caches along the request/response chain. Such cache directives are 1090 unidirectional in that the presence of a directive in a request does 1091 not imply that the same directive is present in the response, or to 1092 be repeated in it. 1094 See Section 5.2.3 for information about how Cache-Control directives 1095 defined elsewhere are handled. 1097 A proxy, whether or not it implements a cache, MUST pass cache 1098 directives through in forwarded messages, regardless of their 1099 significance to that application, since the directives might apply to 1100 all recipients along the request/response chain. It is not possible 1101 to target a directive to a specific cache. 1103 Cache directives are identified by a token, to be compared case- 1104 insensitively, and have an optional argument that can use both token 1105 and quoted-string syntax. For the directives defined below that 1106 define arguments, recipients ought to accept both forms, even if a 1107 specific form is required for generation. 1109 Cache-Control = #cache-directive 1111 cache-directive = token [ "=" ( token / quoted-string ) ] 1113 For the cache directives defined below, no argument is defined (nor 1114 allowed) unless stated otherwise. 1116 5.2.1. Request Cache-Control Directives 1118 This section defines cache request directives. They are advisory; 1119 caches MAY implement them, but are not required to. 1121 5.2.1.1. max-age 1123 Argument syntax: 1125 delta-seconds (see Section 1.3) 1127 The "max-age" request directive indicates that the client prefers a 1128 response whose age is less than or equal to the specified number of 1129 seconds. Unless the max-stale request directive is also present, the 1130 client does not wish to receive a stale response. 1132 This directive uses the token form of the argument syntax: e.g., 1133 'max-age=5' not 'max-age="5"'. A sender MUST NOT generate the 1134 quoted-string form. 1136 5.2.1.2. max-stale 1138 Argument syntax: 1140 delta-seconds (see Section 1.3) 1142 The "max-stale" request directive indicates that the client will 1143 accept a response that has exceeded its freshness lifetime. If a 1144 value is present, then the client is willing to accept a response 1145 that has exceeded its freshness lifetime by no more than the 1146 specified number of seconds. If no value is assigned to max-stale, 1147 then the client will accept a stale response of any age. 1149 This directive uses the token form of the argument syntax: e.g., 1150 'max-stale=10' not 'max-stale="10"'. A sender MUST NOT generate the 1151 quoted-string form. 1153 5.2.1.3. min-fresh 1155 Argument syntax: 1157 delta-seconds (see Section 1.3) 1159 The "min-fresh" request directive indicates that the client prefers a 1160 response whose freshness lifetime is no less than its current age 1161 plus the specified time in seconds. That is, the client wants a 1162 response that will still be fresh for at least the specified number 1163 of seconds. 1165 This directive uses the token form of the argument syntax: e.g., 1166 'min-fresh=20' not 'min-fresh="20"'. A sender MUST NOT generate the 1167 quoted-string form. 1169 5.2.1.4. no-cache 1171 The "no-cache" request directive indicates that the client prefers 1172 stored response not be used to satisfy the request without successful 1173 validation on the origin server. 1175 5.2.1.5. no-store 1177 The "no-store" request directive indicates that a cache MUST NOT 1178 store any part of either this request or any response to it. This 1179 directive applies to both private and shared caches. "MUST NOT 1180 store" in this context means that the cache MUST NOT intentionally 1181 store the information in non-volatile storage, and MUST make a best- 1182 effort attempt to remove the information from volatile storage as 1183 promptly as possible after forwarding it. 1185 This directive is _not_ a reliable or sufficient mechanism for 1186 ensuring privacy. In particular, malicious or compromised caches 1187 might not recognize or obey this directive, and communications 1188 networks might be vulnerable to eavesdropping. 1190 Note that if a request containing this directive is satisfied from a 1191 cache, the no-store request directive does not apply to the already 1192 stored response. 1194 5.2.1.6. no-transform 1196 The "no-transform" request directive indicates that the client is 1197 asking for intermediaries to avoid transforming the content, as 1198 defined in Section 7.7 of [Semantics]. 1200 5.2.1.7. only-if-cached 1202 The "only-if-cached" request directive indicates that the client only 1203 wishes to obtain a stored response. Caches that honor this request 1204 directive SHOULD, upon receiving it, either respond using a stored 1205 response consistent with the other constraints of the request, or 1206 respond with a 504 (Gateway Timeout) status code. 1208 5.2.2. Response Cache-Control Directives 1210 This section defines cache response directives. A cache MUST obey 1211 the Cache-Control directives defined in this section. 1213 5.2.2.1. max-age 1215 Argument syntax: 1217 delta-seconds (see Section 1.3) 1219 The "max-age" response directive indicates that the response is to be 1220 considered stale after its age is greater than the specified number 1221 of seconds. 1223 This directive uses the token form of the argument syntax: e.g., 1224 'max-age=5' not 'max-age="5"'. A sender MUST NOT generate the 1225 quoted-string form. 1227 5.2.2.2. must-revalidate 1229 The "must-revalidate" response directive indicates that once the 1230 response has become stale, a cache MUST NOT reuse that response to 1231 satisfy another request until it has been successfully validated by 1232 the origin, as defined by Section 4.3. 1234 The must-revalidate directive is necessary to support reliable 1235 operation for certain protocol features. In all circumstances a 1236 cache MUST NOT ignore the must-revalidate directive; in particular, 1237 if a cache is disconnected, the cache MUST generate an error response 1238 rather than reuse the stale response. The generated status code 1239 SHOULD be 504 (Gateway Timeout) unless another error status code is 1240 more applicable. 1242 The must-revalidate directive ought to be used by servers if and only 1243 if failure to validate a request could cause incorrect operation, 1244 such as a silently unexecuted financial transaction. 1246 The must-revalidate directive also permits a shared cache to reuse a 1247 response to a request containing an Authorization header field 1248 (Section 11.6.2 of [Semantics]), subject to the above requirement on 1249 revalidation (Section 3.5). 1251 5.2.2.3. must-understand 1253 The "must-understand" response directive limits caching of the 1254 response to a cache that understands and conforms to the requirements 1255 for that response's status code. 1257 Responses containing "must-understand" SHOULD also contain the "no- 1258 store" directive; caches that implement "must-understand" SHOULD 1259 ignore the "no-store" directive in responses that contain both 1260 directives and a status code that the cache understands and conforms 1261 to any related caching requirements. 1263 5.2.2.4. no-cache 1265 Argument syntax: 1267 #field-name 1269 The "no-cache" response directive, in its unqualified form (without 1270 an argument), indicates that the response MUST NOT be used to satisfy 1271 any other request without forwarding it for validation and receiving 1272 a successful response; see Section 4.3. 1274 This allows an origin server to prevent a cache from using the 1275 response to satisfy a request without contacting it, even by caches 1276 that have been configured to send stale responses. 1278 The qualified form of no-cache response directive, with an argument 1279 that lists one or more field names, indicates that a cache MAY use 1280 the response to satisfy a subsequent request, subject to any other 1281 restrictions on caching, if the listed header fields are excluded 1282 from the subsequent response or the subsequent response has been 1283 successfully revalidated with the origin server (updating or removing 1284 those fields). This allows an origin server to prevent the re-use of 1285 certain header fields in a response, while still allowing caching of 1286 the rest of the response. 1288 The field names given are not limited to the set of header fields 1289 defined by this specification. Field names are case-insensitive. 1291 This directive uses the quoted-string form of the argument syntax. A 1292 sender SHOULD NOT generate the token form (even if quoting appears 1293 not to be needed for single-entry lists). 1295 | *Note:* The qualified form of the directive is often handled by 1296 | caches as if an unqualified no-cache directive was received; 1297 | i.e., the special handling for the qualified form is not widely 1298 | implemented. 1300 5.2.2.5. no-store 1302 The "no-store" response directive indicates that a cache MUST NOT 1303 store any part of either the immediate request or response, and MUST 1304 NOT use the response to satisfy any other request. 1306 This directive applies to both private and shared caches. "MUST NOT 1307 store" in this context means that the cache MUST NOT intentionally 1308 store the information in non-volatile storage, and MUST make a best- 1309 effort attempt to remove the information from volatile storage as 1310 promptly as possible after forwarding it. 1312 This directive is _not_ a reliable or sufficient mechanism for 1313 ensuring privacy. In particular, malicious or compromised caches 1314 might not recognize or obey this directive, and communications 1315 networks might be vulnerable to eavesdropping. 1317 Note that the "must-understand" cache directive overrides "no-store" 1318 in certain circumstances; see Section 5.2.2.3. 1320 5.2.2.6. no-transform 1322 The "no-transform" response directive indicates that an intermediary 1323 (regardless of whether it implements a cache) MUST NOT transform the 1324 content, as defined in Section 7.7 of [Semantics]. 1326 5.2.2.7. private 1328 Argument syntax: 1330 #field-name 1332 The unqualified "private" response directive indicates that a shared 1333 cache MUST NOT store the response (i.e., the response is intended for 1334 a single user). It also indicates that a private cache MAY store the 1335 response, subject the constraints defined in Section 3, even if the 1336 response would not otherwise be heuristically cacheable by a private 1337 cache. 1339 If a qualified private response directive is present, with an 1340 argument that lists one or more field names, then only the listed 1341 header fields are limited to a single user: a shared cache MUST NOT 1342 store the listed header fields if they are present in the original 1343 response, but MAY store the remainder of the response message without 1344 those header fields, subject the constraints defined in Section 3. 1346 The field names given are not limited to the set of header fields 1347 defined by this specification. Field names are case-insensitive. 1349 This directive uses the quoted-string form of the argument syntax. A 1350 sender SHOULD NOT generate the token form (even if quoting appears 1351 not to be needed for single-entry lists). 1353 | *Note:* This usage of the word "private" only controls where 1354 | the response can be stored; it cannot ensure the privacy of the 1355 | message content. Also, the qualified form of the directive is 1356 | often handled by caches as if an unqualified private directive 1357 | was received; i.e., the special handling for the qualified form 1358 | is not widely implemented. 1360 5.2.2.8. proxy-revalidate 1362 The "proxy-revalidate" response directive indicates that once the 1363 response has become stale, a shared cache MUST NOT reuse that 1364 response to satisfy another request until it has been successfully 1365 validated by the origin, as defined by Section 4.3. This is 1366 analogous to must-revalidate (Section 5.2.2.2), except that proxy- 1367 revalidate does not apply to private caches. 1369 Note that "proxy-revalidate" on its own does not imply that a 1370 response is cacheable. For example, it might be combined with the 1371 public directive (Section 5.2.2.9), allowing the response to be 1372 cached while requiring only a shared cache to revalidate when stale. 1374 5.2.2.9. public 1376 The "public" response directive indicates that a cache MAY store the 1377 response even if it would otherwise be prohibited, subject to the 1378 constraints defined in Section 3. In other words, public explicitly 1379 marks the response as cacheable. For example, public permits a 1380 shared cache to reuse a response to a request containing an 1381 Authorization header field (Section 3.5). 1383 Note that it is unnecessary to add the public directive to a response 1384 that is already cacheable according to Section 3. 1386 If a response with the public directive has no explicit freshness 1387 information, it is heuristically cacheable (Section 4.2.2). 1389 5.2.2.10. s-maxage 1391 Argument syntax: 1393 delta-seconds (see Section 1.3) 1395 The "s-maxage" response directive indicates that, for a shared cache, 1396 the maximum age specified by this directive overrides the maximum age 1397 specified by either the max-age directive or the Expires header 1398 field. 1400 The s-maxage directive incorporates the proxy-revalidate 1401 (Section 5.2.2.8) response directive's semantics for a shared cache. 1402 A shared cache MUST NOT reuse a stale response with s-maxage to 1403 satisfy another request until it has been successfully validated by 1404 the origin, as defined by Section 4.3. This directive also permits a 1405 shared cache to reuse a response to a request containing an 1406 Authorization header field, subject to the above requirements on 1407 maximum age and revalidation (Section 3.5). 1409 This directive uses the token form of the argument syntax: e.g., 1410 's-maxage=10' not 's-maxage="10"'. A sender MUST NOT generate the 1411 quoted-string form. 1413 5.2.3. Cache Control Extensions 1415 The Cache-Control header field can be extended through the use of one 1416 or more cache-extension tokens, each with an optional value. A cache 1417 MUST ignore unrecognized cache directives. 1419 Informational extensions (those that do not require a change in cache 1420 behavior) can be added without changing the semantics of other 1421 directives. 1423 Behavioral extensions are designed to work by acting as modifiers to 1424 the existing base of cache directives. Both the new directive and 1425 the old directive are supplied, such that applications that do not 1426 understand the new directive will default to the behavior specified 1427 by the old directive, and those that understand the new directive 1428 will recognize it as modifying the requirements associated with the 1429 old directive. In this way, extensions to the existing cache-control 1430 directives can be made without breaking deployed caches. 1432 For example, consider a hypothetical new response directive called 1433 "community" that acts as a modifier to the private directive: in 1434 addition to private caches, any cache that is shared only by members 1435 of the named community is allowed to cache the response. An origin 1436 server wishing to allow the UCI community to use an otherwise private 1437 response in their shared cache(s) could do so by including 1439 Cache-Control: private, community="UCI" 1441 A cache that recognizes such a community cache-extension could 1442 broaden its behavior in accordance with that extension. A cache that 1443 does not recognize the community cache-extension would ignore it and 1444 adhere to the private directive. 1446 New extension directives ought to consider defining: 1448 * What it means for a directive to be specified multiple times, 1450 * When the directive does not take an argument, what it means when 1451 an argument is present, 1453 * When the directive requires an argument, what it means when it is 1454 missing, 1456 * Whether the directive is specific to requests, responses, or able 1457 to be used in either. 1459 5.2.4. Cache Directive Registry 1461 The "Hypertext Transfer Protocol (HTTP) Cache Directive Registry" 1462 defines the namespace for the cache directives. It has been created 1463 and is now maintained at . 1466 A registration MUST include the following fields: 1468 * Cache Directive Name 1470 * Pointer to specification text 1472 Values to be added to this namespace require IETF Review (see 1473 [RFC8126], Section 4.8). 1475 5.3. Expires 1477 The "Expires" response header field gives the date/time after which 1478 the response is considered stale. See Section 4.2 for further 1479 discussion of the freshness model. 1481 The presence of an Expires header field does not imply that the 1482 original resource will change or cease to exist at, before, or after 1483 that time. 1485 The Expires field value is an HTTP-date timestamp, as defined in 1486 Section 5.6.7 of [Semantics]. See also Section 4.2 for parsing 1487 requirements specific to caches. 1489 Expires = HTTP-date 1491 For example 1493 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1495 A cache recipient MUST interpret invalid date formats, especially the 1496 value "0", as representing a time in the past (i.e., "already 1497 expired"). 1499 If a response includes a Cache-Control header field with the max-age 1500 directive (Section 5.2.2.1), a recipient MUST ignore the Expires 1501 header field. Likewise, if a response includes the s-maxage 1502 directive (Section 5.2.2.10), a shared cache recipient MUST ignore 1503 the Expires header field. In both these cases, the value in Expires 1504 is only intended for recipients that have not yet implemented the 1505 Cache-Control header field. 1507 An origin server without a clock MUST NOT generate an Expires header 1508 field unless its value represents a fixed time in the past (always 1509 expired) or its value has been associated with the resource by a 1510 system or user with a reliable clock. 1512 Historically, HTTP required the Expires field value to be no more 1513 than a year in the future. While longer freshness lifetimes are no 1514 longer prohibited, extremely large values have been demonstrated to 1515 cause problems (e.g., clock overflows due to use of 32-bit integers 1516 for time values), and many caches will evict a response far sooner 1517 than that. 1519 5.4. Pragma 1521 The "Pragma" request header field was defined for HTTP/1.0 caches, so 1522 that clients could specify a "no-cache" request (as Cache-Control was 1523 not defined until HTTP/1.1). 1525 However, support for Cache-Control is now widespread. As a result, 1526 this specification deprecates Pragma. 1528 | *Note:* Because the meaning of "Pragma: no-cache" in responses 1529 | was never specified, it does not provide a reliable replacement 1530 | for "Cache-Control: no-cache" in them. 1532 5.5. Warning 1534 The "Warning" header field was used to carry additional information 1535 about the status or transformation of a message that might not be 1536 reflected in the status code. This specification obsoletes it, as it 1537 is not widely generated or surfaced to users. The information it 1538 carried can be gleaned from examining other header fields, such as 1539 Age. 1541 6. Relationship to Applications and Other Caches 1543 Applications using HTTP often specify additional forms of caching. 1544 For example, Web browsers often have history mechanisms such as 1545 "Back" buttons that can be used to redisplay a representation 1546 retrieved earlier in a session. 1548 Likewise, some Web browsers implement caching of images and other 1549 assets within a page view; they may or may not honor HTTP caching 1550 semantics. 1552 The requirements in this specification do not necessarily apply to 1553 how applications use data after it is retrieved from an HTTP cache. 1554 For example, a history mechanism can display a previous 1555 representation even if it has expired, and an application can use 1556 cached data in other ways beyond its freshness lifetime. 1558 This specification does not prohibit the application from taking HTTP 1559 caching into account; for example, a history mechanism might tell the 1560 user that a view is stale, or it might honor cache directives (e.g., 1561 Cache-Control: no-store). 1563 However, when an application caches data and does not make this 1564 apparent to or easily controllable by the user, it is strongly 1565 encouraged to define its operation with respect to HTTP cache 1566 directives, so as not to surprise authors who expect caching 1567 semantics to be honoured. For example, while it might be reasonable 1568 to define an application cache "above" HTTP that allows a response 1569 containing Cache-Control: no-store to be reused for requests that are 1570 directly related to the request that fetched it (such as those 1571 created during the same page load), it would likely be surprising and 1572 confusing to users and authors if it were allowed to be reused for 1573 requests unrelated in any way to the one from which it was obtained. 1575 7. Security Considerations 1577 This section is meant to inform developers, information providers, 1578 and users of known security concerns specific to HTTP caching. More 1579 general security considerations are addressed in "HTTP/1.1" 1580 (Section 11 of [Messaging]) and "HTTP Semantics" (Section 17 of 1581 [Semantics]). 1583 Caches expose additional potential vulnerabilities, since the 1584 contents of the cache represent an attractive target for malicious 1585 exploitation. Because cache contents persist after an HTTP request 1586 is complete, an attack on the cache can reveal information long after 1587 a user believes that the information has been removed from the 1588 network. Therefore, cache contents need to be protected as sensitive 1589 information. 1591 7.1. Cache Poisoning 1593 Various attacks might be amplified by being stored in a cache. Such 1594 "cache poisoning" attacks happen when an attacker uses implementation 1595 flaws, elevated privileges, or other techniques to insert a response 1596 into a cache. This is especially effective when shared caches are 1597 used to distribute malicious content to many clients. 1599 One common attack vector for cache poisoning is to exploit 1600 differences in message parsing on proxies and in user agents; see 1601 Section 6.3 of [Messaging] for the relevant requirements regarding 1602 HTTP/1.1. 1604 7.2. Timing Attacks 1606 Because one of the primary uses of a cache is to optimise 1607 performance, its use can "leak" information about what resources have 1608 been previously requested. 1610 For example, if a user visits a site and their browser caches some of 1611 its responses, and then navigates to a second site, that site can 1612 attempt to load responses it knows exists on the first site. If they 1613 load quickly, it can be assumed that the user has visited that site, 1614 or even a specific page on it. 1616 Such "timing attacks" can be mitigated by adding more information to 1617 the cache key, such as the identity of the referring site (to prevent 1618 the attack described above). This is sometimes called "double 1619 keying." 1621 7.3. Caching of Sensitive Information 1623 Implementation and deployment flaws (as well as misunderstanding of 1624 cache operation) might lead to caching of sensitive information 1625 (e.g., authentication credentials) that is thought to be private, 1626 exposing it to unauthorized parties. 1628 Note that the Set-Cookie response header field [RFC6265] does not 1629 inhibit caching; a cacheable response with a Set-Cookie header field 1630 can be (and often is) used to satisfy subsequent requests to caches. 1631 Servers who wish to control caching of these responses are encouraged 1632 to emit appropriate Cache-Control response header fields. 1634 8. IANA Considerations 1636 The change controller for the following registrations is: "IETF 1637 (iesg@ietf.org) - Internet Engineering Task Force". 1639 8.1. Field Name Registration 1641 First, introduce the new "Hypertext Transfer Protocol (HTTP) Field 1642 Name Registry" at as 1643 described in Section 18.4 of [Semantics]. 1645 Then, please update the registry with the field names listed in the 1646 table below: 1648 +===============+===========+======+==========+ 1649 | Field Name | Status | Ref. | Comments | 1650 +===============+===========+======+==========+ 1651 | Age | standard | 5.1 | | 1652 +---------------+-----------+------+----------+ 1653 | Cache-Control | standard | 5.2 | | 1654 +---------------+-----------+------+----------+ 1655 | Expires | standard | 5.3 | | 1656 +---------------+-----------+------+----------+ 1657 | Pragma | standard | 5.4 | | 1658 +---------------+-----------+------+----------+ 1659 | Warning | obsoleted | 5.5 | | 1660 +---------------+-----------+------+----------+ 1662 Table 1 1664 8.2. Cache Directive Registration 1666 Please update the "Hypertext Transfer Protocol (HTTP) Cache Directive 1667 Registry" at 1668 with the registration procedure of Section 5.2.4 and the cache 1669 directive names summarized in the table below. 1671 +==================+==================================+ 1672 | Cache Directive | Reference | 1673 +==================+==================================+ 1674 | max-age | Section 5.2.1.1, Section 5.2.2.1 | 1675 +------------------+----------------------------------+ 1676 | max-stale | Section 5.2.1.2 | 1677 +------------------+----------------------------------+ 1678 | min-fresh | Section 5.2.1.3 | 1679 +------------------+----------------------------------+ 1680 | must-revalidate | Section 5.2.2.2 | 1681 +------------------+----------------------------------+ 1682 | must-understand | Section 5.2.2.3 | 1683 +------------------+----------------------------------+ 1684 | no-cache | Section 5.2.1.4, Section 5.2.2.4 | 1685 +------------------+----------------------------------+ 1686 | no-store | Section 5.2.1.5, Section 5.2.2.5 | 1687 +------------------+----------------------------------+ 1688 | no-transform | Section 5.2.1.6, Section 5.2.2.6 | 1689 +------------------+----------------------------------+ 1690 | only-if-cached | Section 5.2.1.7 | 1691 +------------------+----------------------------------+ 1692 | private | Section 5.2.2.7 | 1693 +------------------+----------------------------------+ 1694 | proxy-revalidate | Section 5.2.2.8 | 1695 +------------------+----------------------------------+ 1696 | public | Section 5.2.2.9 | 1697 +------------------+----------------------------------+ 1698 | s-maxage | Section 5.2.2.10 | 1699 +------------------+----------------------------------+ 1701 Table 2 1703 8.3. Warn Code Registry 1705 Please add a note to the "Hypertext Transfer Protocol (HTTP) Warn 1706 Codes" registry at 1707 to the effect that Warning is obsoleted. 1709 9. References 1711 9.1. Normative References 1713 [Messaging] 1714 Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 1715 Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft- 1716 ietf-httpbis-messaging-16, 27 May 2021, 1717 . 1720 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1721 Requirement Levels", BCP 14, RFC 2119, 1722 DOI 10.17487/RFC2119, March 1997, 1723 . 1725 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1726 Specifications: ABNF", STD 68, RFC 5234, 1727 DOI 10.17487/RFC5234, January 2008, 1728 . 1730 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 1731 RFC 7405, DOI 10.17487/RFC7405, December 2014, 1732 . 1734 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1735 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1736 May 2017, . 1738 [Semantics] 1739 Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 1740 Ed., "HTTP Semantics", Work in Progress, Internet-Draft, 1741 draft-ietf-httpbis-semantics-16, 27 May 2021, 1742 . 1745 9.2. Informative References 1747 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1748 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1749 Transfer Protocol -- HTTP/1.1", RFC 2616, 1750 DOI 10.17487/RFC2616, June 1999, 1751 . 1753 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1754 Content", RFC 5861, DOI 10.17487/RFC5861, April 2010, 1755 . 1757 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 1758 "Network Time Protocol Version 4: Protocol and Algorithms 1759 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 1760 . 1762 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1763 DOI 10.17487/RFC6265, April 2011, 1764 . 1766 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. F. Reschke, 1767 Ed., "Hypertext Transfer Protocol (HTTP): Caching", 1768 RFC 7234, DOI 10.17487/RFC7234, June 2014, 1769 . 1771 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1772 Writing an IANA Considerations Section in RFCs", BCP 26, 1773 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1774 . 1776 Appendix A. Collected ABNF 1778 In the collected ABNF below, list rules are expanded as per 1779 Section 5.6.1.1 of [Semantics]. 1781 Age = delta-seconds 1783 Cache-Control = [ cache-directive *( OWS "," OWS cache-directive ) ] 1785 Expires = HTTP-date 1787 HTTP-date = 1789 OWS = 1791 cache-directive = token [ "=" ( token / quoted-string ) ] 1793 delta-seconds = 1*DIGIT 1795 field-name = 1797 quoted-string = 1799 token = 1801 Appendix B. Changes from RFC 7234 1803 Handling of duplicate and conflicting cache directives has been 1804 clarified. (Section 4.2.1) 1806 Cache invalidation of the URIs in the Location and Content-Location 1807 header fields is no longer required, but still allowed. 1808 (Section 4.4) 1810 Cache invalidation of the URIs in the Location and Content-Location 1811 header fields is disallowed when the origin is different; previously, 1812 it was the host. (Section 4.4) 1813 Handling invalid and multiple Age header field values has been 1814 clarified. (Section 5.1) 1816 Some cache directives defined by this specification now have stronger 1817 prohibitions against generating the quoted form of their values, 1818 since this has been found to create interoperability problems. 1819 Consumers of extension cache directives are no longer required to 1820 accept both token and quoted-string forms, but they still need to 1821 parse them properly for unknown extensions. (Section 5.2) 1823 The "public" and "private" cache directives were clarified, so that 1824 they do not make responses reusable under any condition. 1825 (Section 5.2.2) 1827 The "must-understand" cache directive was introduced; caches are no 1828 longer required to understand the semantics of new response status 1829 codes unless it is present. (Section 5.2.2.3) 1831 The Warning response header was obsoleted. Much of the information 1832 supported by Warning could be gleaned by examining the response, and 1833 the remaining warn-codes - although potentially useful - were 1834 entirely advisory. In practice, Warning was not added by caches or 1835 intermediaries. (Section 5.5) 1837 Appendix C. Change Log 1839 This section is to be removed before publishing as an RFC. 1841 C.1. Between RFC7234 and draft 00 1843 The changes were purely editorial: 1845 * Change boilerplate and abstract to indicate the "draft" status, 1846 and update references to ancestor specifications. 1848 * Remove version "1.1" from document title, indicating that this 1849 specification applies to all HTTP versions. 1851 * Adjust historical notes. 1853 * Update links to sibling specifications. 1855 * Replace sections listing changes from RFC 2616 by new empty 1856 sections referring to RFC 723x. 1858 * Remove acknowledgements specific to RFC 723x. 1860 * Move "Acknowledgements" to the very end and make them unnumbered. 1862 C.2. Since draft-ietf-httpbis-cache-00 1864 The changes are purely editorial: 1866 * Moved all extensibility tips, registration procedures, and 1867 registry tables from the IANA considerations to normative 1868 sections, reducing the IANA considerations to just instructions 1869 that will be removed prior to publication as an RFC. 1871 C.3. Since draft-ietf-httpbis-cache-01 1873 * Cite RFC 8126 instead of RFC 5226 () 1876 * In Section 5.4, misleading statement about the relation between 1877 Pragma and Cache-Control (, ) 1880 C.4. Since draft-ietf-httpbis-cache-02 1882 * In Section 3, explain that only final responses are cacheable 1883 () 1885 * In Section 5.2.2, clarify what responses various directives apply 1886 to () 1888 * In Section 4.3.1, clarify the source of validators in conditional 1889 requests () 1891 * Revise Section 6 to apply to more than just History Lists 1892 () 1894 * In Section 5.5, deprecated "Warning" header field 1895 () 1897 * In Section 3.5, remove a spurious note 1898 () 1900 C.5. Since draft-ietf-httpbis-cache-03 1902 * In Section 2, define what a disconnected cache is 1903 () 1905 * In Section 4, clarify language around how to select a response 1906 when more than one matches () 1909 * in Section 4.2.4, mention stale-while-revalidate and stale-if- 1910 error () 1912 * Remove requirements around cache request directives 1913 () 1915 * Deprecate Pragma () 1918 * In Section 3.5 and Section 5.2.2, note effect of some directives 1919 on authenticated requests () 1922 C.6. Since draft-ietf-httpbis-cache-04 1924 * In Section 5.2, remove the registrations for stale-if-error and 1925 stale-while-revalidate which happened in RFC 7234 1926 () 1928 C.7. Since draft-ietf-httpbis-cache-05 1930 * In Section 3.3, clarify how weakly framed content is considered 1931 for purposes of completeness () 1934 * Throughout, describe Vary and cache key operations more clearly 1935 () 1937 * In Section 3, remove concept of "cacheable methods" in favor of 1938 prose (, 1939 ) 1941 * Refactored Section 7, and added a section on timing attacks 1942 () 1944 * Changed "cacheable by default" to "heuristically cacheable" 1945 throughout () 1947 C.8. Since draft-ietf-httpbis-cache-06 1949 * In Section 3 and Section 5.2.2.3, change response cacheability to 1950 only require understanding the response status code if the must- 1951 understand cache directive is present () 1954 * Change requirements for handling different forms of cache 1955 directives in Section 5.2 () 1958 * Fix typo in Section 5.2.2.10 () 1961 * In Section 5.2.2.9 and Section 5.2.2.7, clarify "private" and 1962 "public" so that they do not override all other cache directives 1963 () 1965 * In Section 3, distinguish between private with and without 1966 qualifying headers () 1969 * In Section 4.1, clarify that any "*" as a member of Vary will 1970 disable caching () 1972 * In Section 1.1, reference RFC 8174 as well 1973 () 1975 C.9. Since draft-ietf-httpbis-cache-07 1977 * Throughout, replace "effective request URI", "request-target" and 1978 similar with "target URI" () 1981 * In Section 5.2.2.9 and Section 5.2.2.7, make it clear that these 1982 directives do not ignore other requirements for caching 1983 () 1985 * In Section 3.3, move definition of "complete" into semantics 1986 () 1988 C.10. Since draft-ietf-httpbis-cache-08 1990 * Appendix A now uses the sender variant of the "#" list expansion 1991 () 1993 C.11. Since draft-ietf-httpbis-cache-09 1995 * In Section 5.1, discuss handling of invalid and multiple Age 1996 header field values () 1999 * Switch to xml2rfc v3 mode for draft generation 2000 () 2002 C.12. Since draft-ietf-httpbis-cache-10 2004 * In Section 5.2 (Cache-Control), adjust ABNF to allow empty lists 2005 () 2007 C.13. Since draft-ietf-httpbis-cache-11 2009 * None. 2011 C.14. Since draft-ietf-httpbis-cache-12 2013 * In Section 4.2.4, remove 'no-store', as it won't be in cache in 2014 the first place (, 2015 ) 2017 * In Section 3.1, make it clear that only response headers need be 2018 stored () 2020 * Rewrote "Updating Stored Header Fields" Section 3.2 2021 () 2023 * In Section 4.2.1 clarify how to handle invalid and conflicting 2024 directives () 2026 * In Section 4.3.3, mention retry of failed validation requests 2027 () 2029 * In Section 4.3.3, clarify requirement on storing a full response 2030 to a conditional request () 2033 * In Section 5.1, clarify error handling 2034 () 2036 * In Section 4.2, remove spurious "UTC" () 2039 * In Section 4.2, correct the date-related rule names to consider 2040 case-insensitive () 2043 * In Section 6, strengthen recommendation for application caches to 2044 pay attention to cache directives () 2047 * In Section 4, mention collapsed requests 2048 () 2050 * In Section 4.4, relax requirements on Content-Location and 2051 Location invalidation () 2054 * In Section 4.3.4, refine the exceptions to update on a 304 2055 () 2057 * Moved table of Cache-Control directives into Section 8.2 2058 () 2060 * In Section 1.2, remove unused core ABNF rules 2061 () 2063 * Changed to using "payload data" when defining requirements about 2064 the data being conveyed within a message, instead of the terms 2065 "payload body" or "response body" or "representation body", since 2066 they often get confused with the HTTP/1.1 message body (which 2067 includes transfer coding) () 2070 C.15. Since draft-ietf-httpbis-cache-13 2072 * In Section 5.2.2.2, clarify requirements around generating an 2073 error response () 2075 * Changed to using "content" instead of "payload" or "payload data" 2076 to avoid confusion with the payload of version-specific messaging 2077 frames () 2079 * In Section 4.3.4, clarify how multiple validators are handled 2080 () 2082 * In Section 4.2.3, Section 5.2, and Section 5.2.2.4, remove notes 2083 about very old HTTP/1.0 behaviours () 2086 * In Section 5.2.2.3, modify operation to be more backwards- 2087 compatible with existing implementations 2088 () 2090 C.16. Since draft-ietf-httpbis-cache-14 2092 * Fix subsection ordering in Section 5.2.2 2093 () 2095 * In Section 2, define what a cache key is 2096 () 2098 * In Section 3.1, clarify what cache proxy headers apply to 2099 () 2101 * In Section 7.1, cache poisoning can affect private caches too 2102 () 2104 * In Section 5.1, adjust handling of invalid values to match most 2105 deployed caches () 2107 * In Section 5.3, mention parsing requirement relaxation 2108 () 2110 C.17. Since draft-ietf-httpbis-cache-15 2112 * In Section 4.3.1, tune description of relation between cache keys 2113 and validators () 2115 Acknowledgments 2117 See Appendix "Acknowledgments" of [Semantics]. 2119 Index 2121 A C E F G H M N O P S V W 2123 A 2125 Age header field Section 5.1 2126 age Section 4.2 2128 C 2130 Cache-Control header field Section 5.2 2131 cache Section 1 2132 cache key Section 2; Section 2 2133 collapsed requests Section 4 2135 E 2137 Expires header field Section 5.3 2138 explicit expiration time Section 4.2 2140 F 2142 Fields 2143 Age Section 5.1; Section 5.1 2144 Cache-Control Section 5.2 2145 Expires Section 5.3; Section 5.3 2146 Pragma Section 5.4; Section 5.4 2147 Warning Section 5.5 2148 fresh Section 4.2 2149 freshness lifetime Section 4.2 2151 G 2153 Grammar 2154 Age Section 5.1 2155 Cache-Control Section 5.2 2156 DIGIT Section 1.2 2157 Expires Section 5.3 2158 cache-directive Section 5.2 2159 delta-seconds Section 1.3 2161 H 2163 Header Fields 2164 Age Section 5.1; Section 5.1 2165 Cache-Control Section 5.2 2166 Expires Section 5.3; Section 5.3 2167 Pragma Section 5.4; Section 5.4 2168 Warning Section 5.5 2169 heuristic expiration time Section 4.2 2170 heuristically cacheable Section 4.2.2 2172 M 2174 max-age (cache directive) Section 5.2.1.1; Section 5.2.2.1 2175 max-stale (cache directive) Section 5.2.1.2 2176 min-fresh (cache directive) Section 5.2.1.3 2177 must-revalidate (cache directive) Section 5.2.2.2 2178 must-understand (cache directive) Section 5.2.2.3 2180 N 2182 no-cache (cache directive) Section 5.2.1.4; Section 5.2.2.4 2183 no-store (cache directive) Section 5.2.1.5; Section 5.2.2.5 2184 no-transform (cache directive) Section 5.2.1.6; 2185 Section 5.2.2.6 2187 O 2189 only-if-cached (cache directive) Section 5.2.1.7 2191 P 2193 Pragma header field Section 5.4 2194 private (cache directive) Section 5.2.2.7 2195 private cache Section 1 2196 proxy-revalidate (cache directive) Section 5.2.2.8 2197 public (cache directive) Section 5.2.2.9 2199 S 2201 s-maxage (cache directive) Section 5.2.2.10 2202 selected response Section 4.1 2203 shared cache Section 1 2204 stale Section 4.2 2205 strong validator Section 4.3.4 2207 V 2209 validator Section 4.3.1 2211 W 2213 Warning header field Section 5.5 2215 Authors' Addresses 2217 Roy T. Fielding (editor) 2218 Adobe 2219 345 Park Ave 2220 San Jose, CA 95110 2221 United States of America 2223 Email: fielding@gbiv.com 2224 URI: https://roy.gbiv.com/ 2226 Mark Nottingham (editor) 2227 Fastly 2228 Prahran VIC 2229 Australia 2231 Email: mnot@mnot.net 2232 URI: https://www.mnot.net/ 2234 Julian Reschke (editor) 2235 greenbytes GmbH 2236 Hafenweg 16 2237 48155 Münster 2238 Germany 2240 Email: julian.reschke@greenbytes.de 2241 URI: https://greenbytes.de/tech/webdav/