Debian Codegraph @

rfc7234.html

raw
1 <pre>Internet Engineering Task Force (IETF) R. Fielding, Ed.
2 Request for Comments: 7234 Adobe
3 Obsoletes: <a href="./rfc2616">2616</a> M. Nottingham, Ed.
4 Category: Standards Track Akamai
5 ISSN: 2070-1721 J. Reschke, Ed.
6 greenbytes
7 June 2014
8
9
10 <span class="h1">Hypertext Transfer Protocol (HTTP/1.1): Caching</span>
11
12 Abstract
13
14 The Hypertext Transfer Protocol (HTTP) is a stateless application-
15 level protocol for distributed, collaborative, hypertext information
16 systems. This document defines HTTP caches and the associated header
17 fields that control cache behavior or indicate cacheable response
18 messages.
19
20 Status of This Memo
21
22 This is an Internet Standards Track document.
23
24 This document is a product of the Internet Engineering Task Force
25 (IETF). It represents the consensus of the IETF community. It has
26 received public review and has been approved for publication by the
27 Internet Engineering Steering Group (IESG). Further information on
28 Internet Standards is available in <a href="./rfc5741#section-2">Section&nbsp;2 of RFC 5741</a>.
29
30 Information about the current status of this document, any errata,
31 and how to provide feedback on it may be obtained at
32 <a href="http://www.rfc-editor.org/info/rfc7234">http://www.rfc-editor.org/info/rfc7234</a>.
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52 <span class="grey">Fielding, et al. Standards Track [Page 1]</span></pre>
53 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-2" ></span>
54 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
55
56
57 Copyright Notice
58
59 Copyright (c) 2014 IETF Trust and the persons identified as the
60 document authors. All rights reserved.
61
62 This document is subject to <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a> and the IETF Trust's Legal
63 Provisions Relating to IETF Documents
64 (<a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a>) in effect on the date of
65 publication of this document. Please review these documents
66 carefully, as they describe your rights and restrictions with respect
67 to this document. Code Components extracted from this document must
68 include Simplified BSD License text as described in Section 4.e of
69 the Trust Legal Provisions and are provided without warranty as
70 described in the Simplified BSD License.
71
72 This document may contain material from IETF Documents or IETF
73 Contributions published or made publicly available before November
74 10, 2008. The person(s) controlling the copyright in some of this
75 material may not have granted the IETF Trust the right to allow
76 modifications of such material outside the IETF Standards Process.
77 Without obtaining an adequate license from the person(s) controlling
78 the copyright in such materials, this document may not be modified
79 outside the IETF Standards Process, and derivative works of it may
80 not be created outside the IETF Standards Process, except to format
81 it for publication as an RFC or to translate it into languages other
82 than English.
83
84 Table of Contents
85
86 <a href="#section-1">1</a>. Introduction ....................................................<a href="#page-4">4</a>
87 <a href="#section-1.1">1.1</a>. Conformance and Error Handling .............................<a href="#page-4">4</a>
88 <a href="#section-1.2">1.2</a>. Syntax Notation ............................................<a href="#page-4">4</a>
89 <a href="#section-1.2.1">1.2.1</a>. Delta Seconds .......................................<a href="#page-5">5</a>
90 <a href="#section-2">2</a>. Overview of Cache Operation .....................................<a href="#page-5">5</a>
91 <a href="#section-3">3</a>. Storing Responses in Caches .....................................<a href="#page-6">6</a>
92 <a href="#section-3.1">3.1</a>. Storing Incomplete Responses ...............................<a href="#page-7">7</a>
93 <a href="#section-3.2">3.2</a>. Storing Responses to Authenticated Requests ................<a href="#page-7">7</a>
94 <a href="#section-3.3">3.3</a>. Combining Partial Content ..................................<a href="#page-8">8</a>
95 <a href="#section-4">4</a>. Constructing Responses from Caches ..............................<a href="#page-8">8</a>
96 <a href="#section-4.1">4.1</a>. Calculating Secondary Keys with Vary .......................<a href="#page-9">9</a>
97 <a href="#section-4.2">4.2</a>. Freshness .................................................<a href="#page-11">11</a>
98 <a href="#section-4.2.1">4.2.1</a>. Calculating Freshness Lifetime .....................<a href="#page-12">12</a>
99 <a href="#section-4.2.2">4.2.2</a>. Calculating Heuristic Freshness ....................<a href="#page-13">13</a>
100 <a href="#section-4.2.3">4.2.3</a>. Calculating Age ....................................<a href="#page-13">13</a>
101 <a href="#section-4.2.4">4.2.4</a>. Serving Stale Responses ............................<a href="#page-15">15</a>
102 <a href="#section-4.3">4.3</a>. Validation ................................................<a href="#page-16">16</a>
103 <a href="#section-4.3.1">4.3.1</a>. Sending a Validation Request .......................<a href="#page-16">16</a>
104 <a href="#section-4.3.2">4.3.2</a>. Handling a Received Validation Request .............<a href="#page-16">16</a>
105
106
107
108 <span class="grey">Fielding, et al. Standards Track [Page 2]</span></pre>
109 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-3" ></span>
110 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
111
112
113 <a href="#section-4.3.3">4.3.3</a>. Handling a Validation Response .....................<a href="#page-18">18</a>
114 <a href="#section-4.3.4">4.3.4</a>. Freshening Stored Responses upon Validation ........<a href="#page-18">18</a>
115 <a href="#section-4.3.5">4.3.5</a>. Freshening Responses via HEAD ......................<a href="#page-19">19</a>
116 <a href="#section-4.4">4.4</a>. Invalidation ..............................................<a href="#page-20">20</a>
117 <a href="#section-5">5</a>. Header Field Definitions .......................................<a href="#page-21">21</a>
118 <a href="#section-5.1">5.1</a>. Age .......................................................<a href="#page-21">21</a>
119 <a href="#section-5.2">5.2</a>. Cache-Control .............................................<a href="#page-21">21</a>
120 <a href="#section-5.2.1">5.2.1</a>. Request Cache-Control Directives ...................<a href="#page-22">22</a>
121 <a href="#section-5.2.2">5.2.2</a>. Response Cache-Control Directives ..................<a href="#page-24">24</a>
122 <a href="#section-5.2.3">5.2.3</a>. Cache Control Extensions ...........................<a href="#page-27">27</a>
123 <a href="#section-5.3">5.3</a>. Expires ...................................................<a href="#page-28">28</a>
124 <a href="#section-5.4">5.4</a>. Pragma ....................................................<a href="#page-29">29</a>
125 <a href="#section-5.5">5.5</a>. Warning ...................................................<a href="#page-29">29</a>
126 <a href="#section-5.5.1">5.5.1</a>. Warning: 110 - "Response is Stale" .................<a href="#page-31">31</a>
127 <a href="#section-5.5.2">5.5.2</a>. Warning: 111 - "Revalidation Failed" ...............<a href="#page-31">31</a>
128 <a href="#section-5.5.3">5.5.3</a>. Warning: 112 - "Disconnected Operation" ............<a href="#page-31">31</a>
129 <a href="#section-5.5.4">5.5.4</a>. Warning: 113 - "Heuristic Expiration" ..............<a href="#page-31">31</a>
130 <a href="#section-5.5.5">5.5.5</a>. Warning: 199 - "Miscellaneous Warning" .............<a href="#page-32">32</a>
131 <a href="#section-5.5.6">5.5.6</a>. Warning: 214 - "Transformation Applied" ............<a href="#page-32">32</a>
132 <a href="#section-5.5.7">5.5.7</a>. Warning: 299 - "Miscellaneous Persistent Warning" ..32
133 <a href="#section-6">6</a>. History Lists ..................................................<a href="#page-32">32</a>
134 <a href="#section-7">7</a>. IANA Considerations ............................................<a href="#page-32">32</a>
135 <a href="#section-7.1">7.1</a>. Cache Directive Registry ..................................<a href="#page-32">32</a>
136 <a href="#section-7.1.1">7.1.1</a>. Procedure ..........................................<a href="#page-32">32</a>
137 <a href="#section-7.1.2">7.1.2</a>. Considerations for New Cache Control Directives ....<a href="#page-33">33</a>
138 <a href="#section-7.1.3">7.1.3</a>. Registrations ......................................<a href="#page-33">33</a>
139 <a href="#section-7.2">7.2</a>. Warn Code Registry ........................................<a href="#page-34">34</a>
140 <a href="#section-7.2.1">7.2.1</a>. Procedure ..........................................<a href="#page-34">34</a>
141 <a href="#section-7.2.2">7.2.2</a>. Registrations ......................................<a href="#page-34">34</a>
142 <a href="#section-7.3">7.3</a>. Header Field Registration .................................<a href="#page-34">34</a>
143 <a href="#section-8">8</a>. Security Considerations ........................................<a href="#page-35">35</a>
144 <a href="#section-9">9</a>. Acknowledgments ................................................<a href="#page-36">36</a>
145 <a href="#section-10">10</a>. References ....................................................<a href="#page-36">36</a>
146 <a href="#section-10.1">10.1</a>. Normative References .....................................<a href="#page-36">36</a>
147 <a href="#section-10.2">10.2</a>. Informative References ...................................<a href="#page-37">37</a>
148 <a href="#appendix-A">Appendix A</a>. Changes from <a href="./rfc2616">RFC 2616</a> .................................<a href="#page-38">38</a>
149 <a href="#appendix-B">Appendix B</a>. Imported ABNF .........................................<a href="#page-39">39</a>
150 <a href="#appendix-C">Appendix C</a>. Collected ABNF ........................................<a href="#page-39">39</a>
151 Index .............................................................<a href="#page-41">41</a>
152
153
154
155
156
157
158
159
160
161
162
163
164 <span class="grey">Fielding, et al. Standards Track [Page 3]</span></pre>
165 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-4" ></span>
166 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
167
168
169 <span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction</span>
170
171 HTTP is typically used for distributed information systems, where
172 performance can be improved by the use of response caches. This
173 document defines aspects of HTTP/1.1 related to caching and reusing
174 response messages.
175
176 An HTTP cache is a local store of response messages and the subsystem
177 that controls storage, retrieval, and deletion of messages in it. A
178 cache stores cacheable responses in order to reduce the response time
179 and network bandwidth consumption on future, equivalent requests.
180 Any client or server MAY employ a cache, though a cache cannot be
181 used by a server that is acting as a tunnel.
182
183 A shared cache is a cache that stores responses to be reused by more
184 than one user; shared caches are usually (but not always) deployed as
185 a part of an intermediary. A private cache, in contrast, is
186 dedicated to a single user; often, they are deployed as a component
187 of a user agent.
188
189 The goal of caching in HTTP/1.1 is to significantly improve
190 performance by reusing a prior response message to satisfy a current
191 request. A stored response is considered "fresh", as defined in
192 <a href="#section-4.2">Section 4.2</a>, if the response can be reused without "validation"
193 (checking with the origin server to see if the cached response
194 remains valid for this request). A fresh response can therefore
195 reduce both latency and network overhead each time it is reused.
196 When a cached response is not fresh, it might still be reusable if it
197 can be freshened by validation (<a href="#section-4.3">Section 4.3</a>) or if the origin is
198 unavailable (<a href="#section-4.2.4">Section 4.2.4</a>).
199
200 <span class="h3"><a class="selflink" id="section-1.1" href="#section-1.1">1.1</a>. Conformance and Error Handling</span>
201
202 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
203 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
204 document are to be interpreted as described in [<a href="./rfc2119" title="&quot;Key words for use in RFCs to Indicate Requirement Levels&quot;">RFC2119</a>].
205
206 Conformance criteria and considerations regarding error handling are
207 defined in <a href="./rfc7230#section-2.5">Section&nbsp;2.5 of [RFC7230]</a>.
208
209 <span class="h3"><a class="selflink" id="section-1.2" href="#section-1.2">1.2</a>. Syntax Notation</span>
210
211 This specification uses the Augmented Backus-Naur Form (ABNF)
212 notation of [<a href="./rfc5234" title="&quot;Augmented BNF for Syntax Specifications: ABNF&quot;">RFC5234</a>] with a list extension, defined in <a href="./rfc7230#section-7">Section&nbsp;7 of
213 [RFC7230]</a>, that allows for compact definition of comma-separated
214 lists using a '#' operator (similar to how the '*' operator indicates
215
216
217
218
219
220 <span class="grey">Fielding, et al. Standards Track [Page 4]</span></pre>
221 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-5" ></span>
222 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
223
224
225 repetition). <a href="#appendix-B">Appendix B</a> describes rules imported from other
226 documents. <a href="#appendix-C">Appendix C</a> shows the collected grammar with all list
227 operators expanded to standard ABNF notation.
228
229 <span class="h4"><a class="selflink" id="section-1.2.1" href="#section-1.2.1">1.2.1</a>. Delta Seconds</span>
230
231 The delta-seconds rule specifies a non-negative integer, representing
232 time in seconds.
233
234 delta-seconds = 1*DIGIT
235
236 A recipient parsing a delta-seconds value and converting it to binary
237 form ought to use an arithmetic type of at least 31 bits of
238 non-negative integer range. If a cache receives a delta-seconds
239 value greater than the greatest integer it can represent, or if any
240 of its subsequent calculations overflows, the cache MUST consider the
241 value to be either 2147483648 (2^31) or the greatest positive integer
242 it can conveniently represent.
243
244 Note: The value 2147483648 is here for historical reasons,
245 effectively represents infinity (over 68 years), and does not need
246 to be stored in binary form; an implementation could produce it as
247 a canned string if any overflow occurs, even if the calculations
248 are performed with an arithmetic type incapable of directly
249 representing that number. What matters here is that an overflow
250 be detected and not treated as a negative value in later
251 calculations.
252
253 <span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. Overview of Cache Operation</span>
254
255 Proper cache operation preserves the semantics of HTTP transfers
256 ([<a href="./rfc7231" title="&quot;Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content&quot;">RFC7231</a>]) while eliminating the transfer of information already
257 held in the cache. Although caching is an entirely OPTIONAL feature
258 of HTTP, it can be assumed that reusing a cached response is
259 desirable and that such reuse is the default behavior when no
260 requirement or local configuration prevents it. Therefore, HTTP
261 cache requirements are focused on preventing a cache from either
262 storing a non-reusable response or reusing a stored response
263 inappropriately, rather than mandating that caches always store and
264 reuse particular responses.
265
266 Each cache entry consists of a cache key and one or more HTTP
267 responses corresponding to prior requests that used the same key.
268 The most common form of cache entry is a successful result of a
269 retrieval request: i.e., a 200 (OK) response to a GET request, which
270 contains a representation of the resource identified by the request
271 target (<a href="./rfc7231#section-4.3.1">Section&nbsp;4.3.1 of [RFC7231]</a>). However, it is also possible to
272 cache permanent redirects, negative results (e.g., 404 (Not Found)),
273
274
275
276 <span class="grey">Fielding, et al. Standards Track [Page 5]</span></pre>
277 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-6" ></span>
278 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
279
280
281 incomplete results (e.g., 206 (Partial Content)), and responses to
282 methods other than GET if the method's definition allows such caching
283 and defines something suitable for use as a cache key.
284
285 The primary cache key consists of the request method and target URI.
286 However, since HTTP caches in common use today are typically limited
287 to caching responses to GET, many caches simply decline other methods
288 and use only the URI as the primary cache key.
289
290 If a request target is subject to content negotiation, its cache
291 entry might consist of multiple stored responses, each differentiated
292 by a secondary key for the values of the original request's selecting
293 header fields (<a href="#section-4.1">Section 4.1</a>).
294
295 <span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. Storing Responses in Caches</span>
296
297 A cache MUST NOT store a response to any request, unless:
298
299 o The request method is understood by the cache and defined as being
300 cacheable, and
301
302 o the response status code is understood by the cache, and
303
304 o the "no-store" cache directive (see <a href="#section-5.2">Section 5.2</a>) does not appear
305 in request or response header fields, and
306
307 o the "private" response directive (see <a href="#section-5.2.2.6">Section 5.2.2.6</a>) does not
308 appear in the response, if the cache is shared, and
309
310 o the Authorization header field (see <a href="./rfc7235#section-4.2">Section&nbsp;4.2 of [RFC7235]</a>) does
311 not appear in the request, if the cache is shared, unless the
312 response explicitly allows it (see <a href="#section-3.2">Section 3.2</a>), and
313
314 o the response either:
315
316 * contains an Expires header field (see <a href="#section-5.3">Section 5.3</a>), or
317
318 * contains a max-age response directive (see <a href="#section-5.2.2.8">Section 5.2.2.8</a>), or
319
320 * contains a s-maxage response directive (see <a href="#section-5.2.2.9">Section 5.2.2.9</a>)
321 and the cache is shared, or
322
323 * contains a Cache Control Extension (see <a href="#section-5.2.3">Section 5.2.3</a>) that
324 allows it to be cached, or
325
326 * has a status code that is defined as cacheable by default (see
327 <a href="#section-4.2.2">Section 4.2.2</a>), or
328
329
330
331
332 <span class="grey">Fielding, et al. Standards Track [Page 6]</span></pre>
333 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-7" ></span>
334 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
335
336
337 * contains a public response directive (see <a href="#section-5.2.2.5">Section 5.2.2.5</a>).
338
339 Note that any of the requirements listed above can be overridden by a
340 cache-control extension; see <a href="#section-5.2.3">Section 5.2.3</a>.
341
342 In this context, a cache has "understood" a request method or a
343 response status code if it recognizes it and implements all specified
344 caching-related behavior.
345
346 Note that, in normal operation, some caches will not store a response
347 that has neither a cache validator nor an explicit expiration time,
348 as such responses are not usually useful to store. However, caches
349 are not prohibited from storing such responses.
350
351 <span class="h3"><a class="selflink" id="section-3.1" href="#section-3.1">3.1</a>. Storing Incomplete Responses</span>
352
353 A response message is considered complete when all of the octets
354 indicated by the message framing ([<a href="./rfc7230" title="&quot;Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing&quot;">RFC7230</a>]) are received prior to
355 the connection being closed. If the request method is GET, the
356 response status code is 200 (OK), and the entire response header
357 section has been received, a cache MAY store an incomplete response
358 message body if the cache entry is recorded as incomplete. Likewise,
359 a 206 (Partial Content) response MAY be stored as if it were an
360 incomplete 200 (OK) cache entry. However, a cache MUST NOT store
361 incomplete or partial-content responses if it does not support the
362 Range and Content-Range header fields or if it does not understand
363 the range units used in those fields.
364
365 A cache MAY complete a stored incomplete response by making a
366 subsequent range request ([<a href="./rfc7233" title="&quot;Hypertext Transfer Protocol (HTTP/1.1): Range Requests&quot;">RFC7233</a>]) and combining the successful
367 response with the stored entry, as defined in <a href="#section-3.3">Section 3.3</a>. A cache
368 MUST NOT use an incomplete response to answer requests unless the
369 response has been made complete or the request is partial and
370 specifies a range that is wholly within the incomplete response. A
371 cache MUST NOT send a partial response to a client without explicitly
372 marking it as such using the 206 (Partial Content) status code.
373
374 <span class="h3"><a class="selflink" id="section-3.2" href="#section-3.2">3.2</a>. Storing Responses to Authenticated Requests</span>
375
376 A shared cache MUST NOT use a cached response to a request with an
377 Authorization header field (<a href="./rfc7235#section-4.2">Section&nbsp;4.2 of [RFC7235]</a>) to satisfy any
378 subsequent request unless a cache directive that allows such
379 responses to be stored is present in the response.
380
381 In this specification, the following Cache-Control response
382 directives (<a href="#section-5.2.2">Section 5.2.2</a>) have such an effect: must-revalidate,
383 public, and s-maxage.
384
385
386
387
388 <span class="grey">Fielding, et al. Standards Track [Page 7]</span></pre>
389 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-8" ></span>
390 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
391
392
393 Note that cached responses that contain the "must-revalidate" and/or
394 "s-maxage" response directives are not allowed to be served stale
395 (<a href="#section-4.2.4">Section 4.2.4</a>) by shared caches. In particular, a response with
396 either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to
397 satisfy a subsequent request without revalidating it on the origin
398 server.
399
400 <span class="h3"><a class="selflink" id="section-3.3" href="#section-3.3">3.3</a>. Combining Partial Content</span>
401
402 A response might transfer only a partial representation if the
403 connection closed prematurely or if the request used one or more
404 Range specifiers ([<a href="./rfc7233" title="&quot;Hypertext Transfer Protocol (HTTP/1.1): Range Requests&quot;">RFC7233</a>]). After several such transfers, a cache
405 might have received several ranges of the same representation. A
406 cache MAY combine these ranges into a single stored response, and
407 reuse that response to satisfy later requests, if they all share the
408 same strong validator and the cache complies with the client
409 requirements in <a href="./rfc7233#section-4.3">Section&nbsp;4.3 of [RFC7233]</a>.
410
411 When combining the new response with one or more stored responses, a
412 cache MUST:
413
414 o delete any Warning header fields in the stored response with
415 warn-code 1xx (see <a href="#section-5.5">Section 5.5</a>);
416
417 o retain any Warning header fields in the stored response with
418 warn-code 2xx; and,
419
420 o use other header fields provided in the new response, aside from
421 Content-Range, to replace all instances of the corresponding
422 header fields in the stored response.
423
424 <span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. Constructing Responses from Caches</span>
425
426 When presented with a request, a cache MUST NOT reuse a stored
427 response, unless:
428
429 o The presented effective request URI (<a href="./rfc7230#section-5.5">Section&nbsp;5.5 of [RFC7230]</a>) and
430 that of the stored response match, and
431
432 o the request method associated with the stored response allows it
433 to be used for the presented request, and
434
435 o selecting header fields nominated by the stored response (if any)
436 match those presented (see <a href="#section-4.1">Section 4.1</a>), and
437
438
439
440
441
442
443
444 <span class="grey">Fielding, et al. Standards Track [Page 8]</span></pre>
445 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-9" ></span>
446 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
447
448
449 o the presented request does not contain the no-cache pragma
450 (<a href="#section-5.4">Section 5.4</a>), nor the no-cache cache directive (<a href="#section-5.2.1">Section 5.2.1</a>),
451 unless the stored response is successfully validated
452 (<a href="#section-4.3">Section 4.3</a>), and
453
454 o the stored response does not contain the no-cache cache directive
455 (<a href="#section-5.2.2.2">Section 5.2.2.2</a>), unless it is successfully validated
456 (<a href="#section-4.3">Section 4.3</a>), and
457
458 o the stored response is either:
459
460 * fresh (see <a href="#section-4.2">Section 4.2</a>), or
461
462 * allowed to be served stale (see <a href="#section-4.2.4">Section 4.2.4</a>), or
463
464 * successfully validated (see <a href="#section-4.3">Section 4.3</a>).
465
466 Note that any of the requirements listed above can be overridden by a
467 cache-control extension; see <a href="#section-5.2.3">Section 5.2.3</a>.
468
469 When a stored response is used to satisfy a request without
470 validation, a cache MUST generate an Age header field (<a href="#section-5.1">Section 5.1</a>),
471 replacing any present in the response with a value equal to the
472 stored response's current_age; see <a href="#section-4.2.3">Section 4.2.3</a>.
473
474 A cache MUST write through requests with methods that are unsafe
475 (<a href="./rfc7231#section-4.2.1">Section&nbsp;4.2.1 of [RFC7231]</a>) to the origin server; i.e., a cache is
476 not allowed to generate a reply to such a request before having
477 forwarded the request and having received a corresponding response.
478
479 Also, note that unsafe requests might invalidate already-stored
480 responses; see <a href="#section-4.4">Section 4.4</a>.
481
482 When more than one suitable response is stored, a cache MUST use the
483 most recent response (as determined by the Date header field). It
484 can also forward the request with "Cache-Control: max-age=0" or
485 "Cache-Control: no-cache" to disambiguate which response to use.
486
487 A cache that does not have a clock available MUST NOT use stored
488 responses without revalidating them upon every use.
489
490 <span class="h3"><a class="selflink" id="section-4.1" href="#section-4.1">4.1</a>. Calculating Secondary Keys with Vary</span>
491
492 When a cache receives a request that can be satisfied by a stored
493 response that has a Vary header field (<a href="./rfc7231#section-7.1.4">Section&nbsp;7.1.4 of [RFC7231]</a>),
494 it MUST NOT use that response unless all of the selecting header
495
496
497
498
499
500 <span class="grey">Fielding, et al. Standards Track [Page 9]</span></pre>
501 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-10" ></span>
502 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
503
504
505 fields nominated by the Vary header field match in both the original
506 request (i.e., that associated with the stored response), and the
507 presented request.
508
509 The selecting header fields from two requests are defined to match if
510 and only if those in the first request can be transformed to those in
511 the second request by applying any of the following:
512
513 o adding or removing whitespace, where allowed in the header field's
514 syntax
515
516 o combining multiple header fields with the same field name (see
517 <a href="./rfc7230#section-3.2">Section&nbsp;3.2 of [RFC7230]</a>)
518
519 o normalizing both header field values in a way that is known to
520 have identical semantics, according to the header field's
521 specification (e.g., reordering field values when order is not
522 significant; case-normalization, where values are defined to be
523 case-insensitive)
524
525 If (after any normalization that might take place) a header field is
526 absent from a request, it can only match another request if it is
527 also absent there.
528
529 A Vary header field-value of "*" always fails to match.
530
531 The stored response with matching selecting header fields is known as
532 the selected response.
533
534 If multiple selected responses are available (potentially including
535 responses without a Vary header field), the cache will need to choose
536 one to use. When a selecting header field has a known mechanism for
537 doing so (e.g., qvalues on Accept and similar request header fields),
538 that mechanism MAY be used to select preferred responses; of the
539 remainder, the most recent response (as determined by the Date header
540 field) is used, as per <a href="#section-4">Section 4</a>.
541
542 If no selected response is available, the cache cannot satisfy the
543 presented request. Typically, it is forwarded to the origin server
544 in a (possibly conditional; see <a href="#section-4.3">Section 4.3</a>) request.
545
546
547
548
549
550
551
552
553
554
555
556 <span class="grey">Fielding, et al. Standards Track [Page 10]</span></pre>
557 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-11" ></span>
558 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
559
560
561 <span class="h3"><a class="selflink" id="section-4.2" href="#section-4.2">4.2</a>. Freshness</span>
562
563 A fresh response is one whose age has not yet exceeded its freshness
564 lifetime. Conversely, a stale response is one where it has.
565
566 A response's freshness lifetime is the length of time between its
567 generation by the origin server and its expiration time. An explicit
568 expiration time is the time at which the origin server intends that a
569 stored response can no longer be used by a cache without further
570 validation, whereas a heuristic expiration time is assigned by a
571 cache when no explicit expiration time is available.
572
573 A response's age is the time that has passed since it was generated
574 by, or successfully validated with, the origin server.
575
576 When a response is "fresh" in the cache, it can be used to satisfy
577 subsequent requests without contacting the origin server, thereby
578 improving efficiency.
579
580 The primary mechanism for determining freshness is for an origin
581 server to provide an explicit expiration time in the future, using
582 either the Expires header field (<a href="#section-5.3">Section 5.3</a>) or the max-age response
583 directive (<a href="#section-5.2.2.8">Section 5.2.2.8</a>). Generally, origin servers will assign
584 future explicit expiration times to responses in the belief that the
585 representation is not likely to change in a semantically significant
586 way before the expiration time is reached.
587
588 If an origin server wishes to force a cache to validate every
589 request, it can assign an explicit expiration time in the past to
590 indicate that the response is already stale. Compliant caches will
591 normally validate a stale cached response before reusing it for
592 subsequent requests (see <a href="#section-4.2.4">Section 4.2.4</a>).
593
594 Since origin servers do not always provide explicit expiration times,
595 caches are also allowed to use a heuristic to determine an expiration
596 time under certain circumstances (see <a href="#section-4.2.2">Section 4.2.2</a>).
597
598 The calculation to determine if a response is fresh is:
599
600 response_is_fresh = (freshness_lifetime &gt; current_age)
601
602 freshness_lifetime is defined in <a href="#section-4.2.1">Section 4.2.1</a>; current_age is
603 defined in <a href="#section-4.2.3">Section 4.2.3</a>.
604
605 Clients can send the max-age or min-fresh cache directives in a
606 request to constrain or relax freshness calculations for the
607 corresponding response (<a href="#section-5.2.1">Section 5.2.1</a>).
608
609
610
611
612 <span class="grey">Fielding, et al. Standards Track [Page 11]</span></pre>
613 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-12" ></span>
614 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
615
616
617 When calculating freshness, to avoid common problems in date parsing:
618
619 o Although all date formats are specified to be case-sensitive, a
620 cache recipient SHOULD match day, week, and time-zone names
621 case-insensitively.
622
623 o If a cache recipient's internal implementation of time has less
624 resolution than the value of an HTTP-date, the recipient MUST
625 internally represent a parsed Expires date as the nearest time
626 equal to or earlier than the received value.
627
628 o A cache recipient MUST NOT allow local time zones to influence the
629 calculation or comparison of an age or expiration time.
630
631 o A cache recipient SHOULD consider a date with a zone abbreviation
632 other than GMT or UTC to be invalid for calculating expiration.
633
634 Note that freshness applies only to cache operation; it cannot be
635 used to force a user agent to refresh its display or reload a
636 resource. See <a href="#section-6">Section 6</a> for an explanation of the difference between
637 caches and history mechanisms.
638
639 <span class="h4"><a class="selflink" id="section-4.2.1" href="#section-4.2.1">4.2.1</a>. Calculating Freshness Lifetime</span>
640
641 A cache can calculate the freshness lifetime (denoted as
642 freshness_lifetime) of a response by using the first match of the
643 following:
644
645 o If the cache is shared and the s-maxage response directive
646 (<a href="#section-5.2.2.9">Section 5.2.2.9</a>) is present, use its value, or
647
648 o If the max-age response directive (<a href="#section-5.2.2.8">Section 5.2.2.8</a>) is present,
649 use its value, or
650
651 o If the Expires response header field (<a href="#section-5.3">Section 5.3</a>) is present, use
652 its value minus the value of the Date response header field, or
653
654 o Otherwise, no explicit expiration time is present in the response.
655 A heuristic freshness lifetime might be applicable; see
656 <a href="#section-4.2.2">Section 4.2.2</a>.
657
658 Note that this calculation is not vulnerable to clock skew, since all
659 of the information comes from the origin server.
660
661
662
663
664
665
666
667
668 <span class="grey">Fielding, et al. Standards Track [Page 12]</span></pre>
669 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-13" ></span>
670 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
671
672
673 When there is more than one value present for a given directive
674 (e.g., two Expires header fields, multiple Cache-Control: max-age
675 directives), the directive's value is considered invalid. Caches are
676 encouraged to consider responses that have invalid freshness
677 information to be stale.
678
679 <span class="h4"><a class="selflink" id="section-4.2.2" href="#section-4.2.2">4.2.2</a>. Calculating Heuristic Freshness</span>
680
681 Since origin servers do not always provide explicit expiration times,
682 a cache MAY assign a heuristic expiration time when an explicit time
683 is not specified, employing algorithms that use other header field
684 values (such as the Last-Modified time) to estimate a plausible
685 expiration time. This specification does not provide specific
686 algorithms, but does impose worst-case constraints on their results.
687
688 A cache MUST NOT use heuristics to determine freshness when an
689 explicit expiration time is present in the stored response. Because
690 of the requirements in <a href="#section-3">Section 3</a>, this means that, effectively,
691 heuristics can only be used on responses without explicit freshness
692 whose status codes are defined as cacheable by default (see <a href="./rfc7231#section-6.1">Section</a>
693 <a href="./rfc7231#section-6.1">6.1 of [RFC7231]</a>), and those responses without explicit freshness
694 that have been marked as explicitly cacheable (e.g., with a "public"
695 response directive).
696
697 If the response has a Last-Modified header field (<a href="./rfc7232#section-2.2">Section&nbsp;2.2 of
698 [RFC7232]</a>), caches are encouraged to use a heuristic expiration value
699 that is no more than some fraction of the interval since that time.
700 A typical setting of this fraction might be 10%.
701
702 When a heuristic is used to calculate freshness lifetime, a cache
703 SHOULD generate a Warning header field with a 113 warn-code (see
704 <a href="#section-5.5.4">Section 5.5.4</a>) in the response if its current_age is more than 24
705 hours and such a warning is not already present.
706
707 Note: <a href="./rfc2616#section-13.9">Section&nbsp;13.9 of [RFC2616]</a> prohibited caches from calculating
708 heuristic freshness for URIs with query components (i.e., those
709 containing '?'). In practice, this has not been widely
710 implemented. Therefore, origin servers are encouraged to send
711 explicit directives (e.g., Cache-Control: no-cache) if they wish
712 to preclude caching.
713
714 <span class="h4"><a class="selflink" id="section-4.2.3" href="#section-4.2.3">4.2.3</a>. Calculating Age</span>
715
716 The Age header field is used to convey an estimated age of the
717 response message when obtained from a cache. The Age field value is
718 the cache's estimate of the number of seconds since the response was
719 generated or validated by the origin server. In essence, the Age
720
721
722
723
724 <span class="grey">Fielding, et al. Standards Track [Page 13]</span></pre>
725 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-14" ></span>
726 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
727
728
729 value is the sum of the time that the response has been resident in
730 each of the caches along the path from the origin server, plus the
731 amount of time it has been in transit along network paths.
732
733 The following data is used for the age calculation:
734
735 age_value
736
737 The term "age_value" denotes the value of the Age header field
738 (<a href="#section-5.1">Section 5.1</a>), in a form appropriate for arithmetic operation; or
739 0, if not available.
740
741 date_value
742
743 The term "date_value" denotes the value of the Date header field,
744 in a form appropriate for arithmetic operations. See <a href="./rfc7231#section-7.1.1.2">Section</a>
745 <a href="./rfc7231#section-7.1.1.2">7.1.1.2 of [RFC7231]</a> for the definition of the Date header field,
746 and for requirements regarding responses without it.
747
748 now
749
750 The term "now" means "the current value of the clock at the host
751 performing the calculation". A host ought to use NTP ([<a href="./rfc5905" title="&quot;Network Time Protocol Version 4: Protocol and Algorithms Specification&quot;">RFC5905</a>])
752 or some similar protocol to synchronize its clocks to Coordinated
753 Universal Time.
754
755 request_time
756
757 The current value of the clock at the host at the time the request
758 resulting in the stored response was made.
759
760 response_time
761
762 The current value of the clock at the host at the time the
763 response was received.
764
765 A response's age can be calculated in two entirely independent ways:
766
767 1. the "apparent_age": response_time minus date_value, if the local
768 clock is reasonably well synchronized to the origin server's
769 clock. If the result is negative, the result is replaced by
770 zero.
771
772 2. the "corrected_age_value", if all of the caches along the
773 response path implement HTTP/1.1. A cache MUST interpret this
774 value relative to the time the request was initiated, not the
775 time that the response was received.
776
777
778
779
780 <span class="grey">Fielding, et al. Standards Track [Page 14]</span></pre>
781 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-15" ></span>
782 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
783
784
785 apparent_age = max(0, response_time - date_value);
786
787 response_delay = response_time - request_time;
788 corrected_age_value = age_value + response_delay;
789
790 These are combined as
791
792 corrected_initial_age = max(apparent_age, corrected_age_value);
793
794 unless the cache is confident in the value of the Age header field
795 (e.g., because there are no HTTP/1.0 hops in the Via header field),
796 in which case the corrected_age_value MAY be used as the
797 corrected_initial_age.
798
799 The current_age of a stored response can then be calculated by adding
800 the amount of time (in seconds) since the stored response was last
801 validated by the origin server to the corrected_initial_age.
802
803 resident_time = now - response_time;
804 current_age = corrected_initial_age + resident_time;
805
806 <span class="h4"><a class="selflink" id="section-4.2.4" href="#section-4.2.4">4.2.4</a>. Serving Stale Responses</span>
807
808 A "stale" response is one that either has explicit expiry information
809 or is allowed to have heuristic expiry calculated, but is not fresh
810 according to the calculations in <a href="#section-4.2">Section 4.2</a>.
811
812 A cache MUST NOT generate a stale response if it is prohibited by an
813 explicit in-protocol directive (e.g., by a "no-store" or "no-cache"
814 cache directive, a "must-revalidate" cache-response-directive, or an
815 applicable "s-maxage" or "proxy-revalidate" cache-response-directive;
816 see <a href="#section-5.2.2">Section 5.2.2</a>).
817
818 A cache MUST NOT send stale responses unless it is disconnected
819 (i.e., it cannot contact the origin server or otherwise find a
820 forward path) or doing so is explicitly allowed (e.g., by the
821 max-stale request directive; see <a href="#section-5.2.1">Section 5.2.1</a>).
822
823 A cache SHOULD generate a Warning header field with the 110 warn-code
824 (see <a href="#section-5.5.1">Section 5.5.1</a>) in stale responses. Likewise, a cache SHOULD
825 generate a 112 warn-code (see <a href="#section-5.5.3">Section 5.5.3</a>) in stale responses if
826 the cache is disconnected.
827
828 A cache SHOULD NOT generate a new Warning header field when
829 forwarding a response that does not have an Age header field, even if
830 the response is already stale. A cache need not validate a response
831 that merely became stale in transit.
832
833
834
835
836 <span class="grey">Fielding, et al. Standards Track [Page 15]</span></pre>
837 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-16" ></span>
838 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
839
840
841 <span class="h3"><a class="selflink" id="section-4.3" href="#section-4.3">4.3</a>. Validation</span>
842
843 When a cache has one or more stored responses for a requested URI,
844 but cannot serve any of them (e.g., because they are not fresh, or
845 one cannot be selected; see <a href="#section-4.1">Section 4.1</a>), it can use the conditional
846 request mechanism [<a href="./rfc7232" title="&quot;Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests&quot;">RFC7232</a>] in the forwarded request to give the next
847 inbound server an opportunity to select a valid stored response to
848 use, updating the stored metadata in the process, or to replace the
849 stored response(s) with a new response. This process is known as
850 "validating" or "revalidating" the stored response.
851
852 <span class="h4"><a class="selflink" id="section-4.3.1" href="#section-4.3.1">4.3.1</a>. Sending a Validation Request</span>
853
854 When sending a conditional request for cache validation, a cache
855 sends one or more precondition header fields containing validator
856 metadata from its stored response(s), which is then compared by
857 recipients to determine whether a stored response is equivalent to a
858 current representation of the resource.
859
860 One such validator is the timestamp given in a Last-Modified header
861 field (<a href="./rfc7232#section-2.2">Section&nbsp;2.2 of [RFC7232]</a>), which can be used in an
862 If-Modified-Since header field for response validation, or in an
863 If-Unmodified-Since or If-Range header field for representation
864 selection (i.e., the client is referring specifically to a previously
865 obtained representation with that timestamp).
866
867 Another validator is the entity-tag given in an ETag header field
868 (<a href="./rfc7232#section-2.3">Section&nbsp;2.3 of [RFC7232]</a>). One or more entity-tags, indicating one
869 or more stored responses, can be used in an If-None-Match header
870 field for response validation, or in an If-Match or If-Range header
871 field for representation selection (i.e., the client is referring
872 specifically to one or more previously obtained representations with
873 the listed entity-tags).
874
875 <span class="h4"><a class="selflink" id="section-4.3.2" href="#section-4.3.2">4.3.2</a>. Handling a Received Validation Request</span>
876
877 Each client in the request chain may have its own cache, so it is
878 common for a cache at an intermediary to receive conditional requests
879 from other (outbound) caches. Likewise, some user agents make use of
880 conditional requests to limit data transfers to recently modified
881 representations or to complete the transfer of a partially retrieved
882 representation.
883
884 If a cache receives a request that can be satisfied by reusing one of
885 its stored 200 (OK) or 206 (Partial Content) responses, the cache
886 SHOULD evaluate any applicable conditional header field preconditions
887 received in that request with respect to the corresponding validators
888 contained within the selected response. A cache MUST NOT evaluate
889
890
891
892 <span class="grey">Fielding, et al. Standards Track [Page 16]</span></pre>
893 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-17" ></span>
894 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
895
896
897 conditional header fields that are only applicable to an origin
898 server, found in a request with semantics that cannot be satisfied
899 with a cached response, or applied to a target resource for which it
900 has no stored responses; such preconditions are likely intended for
901 some other (inbound) server.
902
903 The proper evaluation of conditional requests by a cache depends on
904 the received precondition header fields and their precedence, as
905 defined in <a href="./rfc7232#section-6">Section&nbsp;6 of [RFC7232]</a>. The If-Match and
906 If-Unmodified-Since conditional header fields are not applicable to a
907 cache.
908
909 A request containing an If-None-Match header field (<a href="./rfc7232#section-3.2">Section&nbsp;3.2 of
910 [RFC7232]</a>) indicates that the client wants to validate one or more of
911 its own stored responses in comparison to whichever stored response
912 is selected by the cache. If the field-value is "*", or if the
913 field-value is a list of entity-tags and at least one of them matches
914 the entity-tag of the selected stored response, a cache recipient
915 SHOULD generate a 304 (Not Modified) response (using the metadata of
916 the selected stored response) instead of sending that stored
917 response.
918
919 When a cache decides to revalidate its own stored responses for a
920 request that contains an If-None-Match list of entity-tags, the cache
921 MAY combine the received list with a list of entity-tags from its own
922 stored set of responses (fresh or stale) and send the union of the
923 two lists as a replacement If-None-Match header field value in the
924 forwarded request. If a stored response contains only partial
925 content, the cache MUST NOT include its entity-tag in the union
926 unless the request is for a range that would be fully satisfied by
927 that partial stored response. If the response to the forwarded
928 request is 304 (Not Modified) and has an ETag header field value with
929 an entity-tag that is not in the client's list, the cache MUST
930 generate a 200 (OK) response for the client by reusing its
931 corresponding stored response, as updated by the 304 response
932 metadata (<a href="#section-4.3.4">Section 4.3.4</a>).
933
934 If an If-None-Match header field is not present, a request containing
935 an If-Modified-Since header field (<a href="./rfc7232#section-3.3">Section&nbsp;3.3 of [RFC7232]</a>)
936 indicates that the client wants to validate one or more of its own
937 stored responses by modification date. A cache recipient SHOULD
938 generate a 304 (Not Modified) response (using the metadata of the
939 selected stored response) if one of the following cases is true: 1)
940 the selected stored response has a Last-Modified field-value that is
941 earlier than or equal to the conditional timestamp; 2) no
942 Last-Modified field is present in the selected stored response, but
943 it has a Date field-value that is earlier than or equal to the
944 conditional timestamp; or, 3) neither Last-Modified nor Date is
945
946
947
948 <span class="grey">Fielding, et al. Standards Track [Page 17]</span></pre>
949 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-18" ></span>
950 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
951
952
953 present in the selected stored response, but the cache recorded it as
954 having been received at a time earlier than or equal to the
955 conditional timestamp.
956
957 A cache that implements partial responses to range requests, as
958 defined in [<a href="./rfc7233" title="&quot;Hypertext Transfer Protocol (HTTP/1.1): Range Requests&quot;">RFC7233</a>], also needs to evaluate a received If-Range
959 header field (<a href="./rfc7233#section-3.2">Section&nbsp;3.2 of [RFC7233]</a>) with respect to its selected
960 stored response.
961
962 <span class="h4"><a class="selflink" id="section-4.3.3" href="#section-4.3.3">4.3.3</a>. Handling a Validation Response</span>
963
964 Cache handling of a response to a conditional request is dependent
965 upon its status code:
966
967 o A 304 (Not Modified) response status code indicates that the
968 stored response can be updated and reused; see <a href="#section-4.3.4">Section 4.3.4</a>.
969
970 o A full response (i.e., one with a payload body) indicates that
971 none of the stored responses nominated in the conditional request
972 is suitable. Instead, the cache MUST use the full response to
973 satisfy the request and MAY replace the stored response(s).
974
975 o However, if a cache receives a 5xx (Server Error) response while
976 attempting to validate a response, it can either forward this
977 response to the requesting client, or act as if the server failed
978 to respond. In the latter case, the cache MAY send a previously
979 stored response (see <a href="#section-4.2.4">Section 4.2.4</a>).
980
981 <span class="h4"><a class="selflink" id="section-4.3.4" href="#section-4.3.4">4.3.4</a>. Freshening Stored Responses upon Validation</span>
982
983 When a cache receives a 304 (Not Modified) response and already has
984 one or more stored 200 (OK) responses for the same cache key, the
985 cache needs to identify which of the stored responses are updated by
986 this new response and then update the stored response(s) with the new
987 information provided in the 304 response.
988
989 The stored response to update is identified by using the first match
990 (if any) of the following:
991
992 o If the new response contains a strong validator (see <a href="./rfc7232#section-2.1">Section&nbsp;2.1
993 of [RFC7232]</a>), then that strong validator identifies the selected
994 representation for update. All of the stored responses with the
995 same strong validator are selected. If none of the stored
996 responses contain the same strong validator, then the cache MUST
997 NOT use the new response to update any stored responses.
998
999
1000
1001
1002
1003
1004 <span class="grey">Fielding, et al. Standards Track [Page 18]</span></pre>
1005 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-19" ></span>
1006 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1007
1008
1009 o If the new response contains a weak validator and that validator
1010 corresponds to one of the cache's stored responses, then the most
1011 recent of those matching stored responses is selected for update.
1012
1013 o If the new response does not include any form of validator (such
1014 as in the case where a client generates an If-Modified-Since
1015 request from a source other than the Last-Modified response header
1016 field), and there is only one stored response, and that stored
1017 response also lacks a validator, then that stored response is
1018 selected for update.
1019
1020 If a stored response is selected for update, the cache MUST:
1021
1022 o delete any Warning header fields in the stored response with
1023 warn-code 1xx (see <a href="#section-5.5">Section 5.5</a>);
1024
1025 o retain any Warning header fields in the stored response with
1026 warn-code 2xx; and,
1027
1028 o use other header fields provided in the 304 (Not Modified)
1029 response to replace all instances of the corresponding header
1030 fields in the stored response.
1031
1032 <span class="h4"><a class="selflink" id="section-4.3.5" href="#section-4.3.5">4.3.5</a>. Freshening Responses via HEAD</span>
1033
1034 A response to the HEAD method is identical to what an equivalent
1035 request made with a GET would have been, except it lacks a body.
1036 This property of HEAD responses can be used to invalidate or update a
1037 cached GET response if the more efficient conditional GET request
1038 mechanism is not available (due to no validators being present in the
1039 stored response) or if transmission of the representation body is not
1040 desired even if it has changed.
1041
1042 When a cache makes an inbound HEAD request for a given request target
1043 and receives a 200 (OK) response, the cache SHOULD update or
1044 invalidate each of its stored GET responses that could have been
1045 selected for that request (see <a href="#section-4.1">Section 4.1</a>).
1046
1047 For each of the stored responses that could have been selected, if
1048 the stored response and HEAD response have matching values for any
1049 received validator fields (ETag and Last-Modified) and, if the HEAD
1050 response has a Content-Length header field, the value of
1051 Content-Length matches that of the stored response, the cache SHOULD
1052 update the stored response as described below; otherwise, the cache
1053 SHOULD consider the stored response to be stale.
1054
1055
1056
1057
1058
1059
1060 <span class="grey">Fielding, et al. Standards Track [Page 19]</span></pre>
1061 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-20" ></span>
1062 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1063
1064
1065 If a cache updates a stored response with the metadata provided in a
1066 HEAD response, the cache MUST:
1067
1068 o delete any Warning header fields in the stored response with
1069 warn-code 1xx (see <a href="#section-5.5">Section 5.5</a>);
1070
1071 o retain any Warning header fields in the stored response with
1072 warn-code 2xx; and,
1073
1074 o use other header fields provided in the HEAD response to replace
1075 all instances of the corresponding header fields in the stored
1076 response and append new header fields to the stored response's
1077 header section unless otherwise restricted by the Cache-Control
1078 header field.
1079
1080 <span class="h3"><a class="selflink" id="section-4.4" href="#section-4.4">4.4</a>. Invalidation</span>
1081
1082 Because unsafe request methods (<a href="./rfc7231#section-4.2.1">Section&nbsp;4.2.1 of [RFC7231]</a>) such as
1083 PUT, POST or DELETE have the potential for changing state on the
1084 origin server, intervening caches can use them to keep their contents
1085 up to date.
1086
1087 A cache MUST invalidate the effective Request URI (<a href="./rfc7230#section-5.5">Section&nbsp;5.5 of
1088 [RFC7230]</a>) as well as the URI(s) in the Location and Content-Location
1089 response header fields (if present) when a non-error status code is
1090 received in response to an unsafe request method.
1091
1092 However, a cache MUST NOT invalidate a URI from a Location or
1093 Content-Location response header field if the host part of that URI
1094 differs from the host part in the effective request URI (<a href="./rfc7230#section-5.5">Section&nbsp;5.5
1095 of [RFC7230]</a>). This helps prevent denial-of-service attacks.
1096
1097 A cache MUST invalidate the effective request URI (<a href="./rfc7230#section-5.5">Section&nbsp;5.5 of
1098 [RFC7230]</a>) when it receives a non-error response to a request with a
1099 method whose safety is unknown.
1100
1101 Here, a "non-error response" is one with a 2xx (Successful) or 3xx
1102 (Redirection) status code. "Invalidate" means that the cache will
1103 either remove all stored responses related to the effective request
1104 URI or will mark these as "invalid" and in need of a mandatory
1105 validation before they can be sent in response to a subsequent
1106 request.
1107
1108 Note that this does not guarantee that all appropriate responses are
1109 invalidated. For example, a state-changing request might invalidate
1110 responses in the caches it travels through, but relevant responses
1111 still might be stored in other caches that it has not.
1112
1113
1114
1115
1116 <span class="grey">Fielding, et al. Standards Track [Page 20]</span></pre>
1117 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-21" ></span>
1118 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1119
1120
1121 <span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>. Header Field Definitions</span>
1122
1123 This section defines the syntax and semantics of HTTP/1.1 header
1124 fields related to caching.
1125
1126 <span class="h3"><a class="selflink" id="section-5.1" href="#section-5.1">5.1</a>. Age</span>
1127
1128 The "Age" header field conveys the sender's estimate of the amount of
1129 time since the response was generated or successfully validated at
1130 the origin server. Age values are calculated as specified in
1131 <a href="#section-4.2.3">Section 4.2.3</a>.
1132
1133 Age = delta-seconds
1134
1135 The Age field-value is a non-negative integer, representing time in
1136 seconds (see <a href="#section-1.2.1">Section 1.2.1</a>).
1137
1138 The presence of an Age header field implies that the response was not
1139 generated or validated by the origin server for this request.
1140 However, lack of an Age header field does not imply the origin was
1141 contacted, since the response might have been received from an
1142 HTTP/1.0 cache that does not implement Age.
1143
1144 <span class="h3"><a class="selflink" id="section-5.2" href="#section-5.2">5.2</a>. Cache-Control</span>
1145
1146 The "Cache-Control" header field is used to specify directives for
1147 caches along the request/response chain. Such cache directives are
1148 unidirectional in that the presence of a directive in a request does
1149 not imply that the same directive is to be given in the response.
1150
1151 A cache MUST obey the requirements of the Cache-Control directives
1152 defined in this section. See <a href="#section-5.2.3">Section 5.2.3</a> for information about how
1153 Cache-Control directives defined elsewhere are handled.
1154
1155 Note: Some HTTP/1.0 caches might not implement Cache-Control.
1156
1157 A proxy, whether or not it implements a cache, MUST pass cache
1158 directives through in forwarded messages, regardless of their
1159 significance to that application, since the directives might be
1160 applicable to all recipients along the request/response chain. It is
1161 not possible to target a directive to a specific cache.
1162
1163 Cache directives are identified by a token, to be compared
1164 case-insensitively, and have an optional argument, that can use both
1165 token and quoted-string syntax. For the directives defined below
1166 that define arguments, recipients ought to accept both forms, even if
1167 one is documented to be preferred. For any directive not defined by
1168 this specification, a recipient MUST accept both forms.
1169
1170
1171
1172 <span class="grey">Fielding, et al. Standards Track [Page 21]</span></pre>
1173 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-22" ></span>
1174 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1175
1176
1177 Cache-Control = 1#cache-directive
1178
1179 cache-directive = token [ "=" ( token / quoted-string ) ]
1180
1181 For the cache directives defined below, no argument is defined (nor
1182 allowed) unless stated otherwise.
1183
1184 <span class="h4"><a class="selflink" id="section-5.2.1" href="#section-5.2.1">5.2.1</a>. Request Cache-Control Directives</span>
1185
1186 <span class="h5"><a class="selflink" id="section-5.2.1.1" href="#section-5.2.1.1">5.2.1.1</a>. max-age</span>
1187
1188 Argument syntax:
1189
1190 delta-seconds (see <a href="#section-1.2.1">Section 1.2.1</a>)
1191
1192 The "max-age" request directive indicates that the client is
1193 unwilling to accept a response whose age is greater than the
1194 specified number of seconds. Unless the max-stale request directive
1195 is also present, the client is not willing to accept a stale
1196 response.
1197
1198 This directive uses the token form of the argument syntax: e.g.,
1199 'max-age=5' not 'max-age="5"'. A sender SHOULD NOT generate the
1200 quoted-string form.
1201
1202 <span class="h5"><a class="selflink" id="section-5.2.1.2" href="#section-5.2.1.2">5.2.1.2</a>. max-stale</span>
1203
1204 Argument syntax:
1205
1206 delta-seconds (see <a href="#section-1.2.1">Section 1.2.1</a>)
1207
1208 The "max-stale" request directive indicates that the client is
1209 willing to accept a response that has exceeded its freshness
1210 lifetime. If max-stale is assigned a value, then the client is
1211 willing to accept a response that has exceeded its freshness lifetime
1212 by no more than the specified number of seconds. If no value is
1213 assigned to max-stale, then the client is willing to accept a stale
1214 response of any age.
1215
1216 This directive uses the token form of the argument syntax: e.g.,
1217 'max-stale=10' not 'max-stale="10"'. A sender SHOULD NOT generate
1218 the quoted-string form.
1219
1220 <span class="h5"><a class="selflink" id="section-5.2.1.3" href="#section-5.2.1.3">5.2.1.3</a>. min-fresh</span>
1221
1222 Argument syntax:
1223
1224 delta-seconds (see <a href="#section-1.2.1">Section 1.2.1</a>)
1225
1226
1227
1228 <span class="grey">Fielding, et al. Standards Track [Page 22]</span></pre>
1229 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-23" ></span>
1230 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1231
1232
1233 The "min-fresh" request directive indicates that the client is
1234 willing to accept a response whose freshness lifetime is no less than
1235 its current age plus the specified time in seconds. That is, the
1236 client wants a response that will still be fresh for at least the
1237 specified number of seconds.
1238
1239 This directive uses the token form of the argument syntax: e.g.,
1240 'min-fresh=20' not 'min-fresh="20"'. A sender SHOULD NOT generate
1241 the quoted-string form.
1242
1243 <span class="h5"><a class="selflink" id="section-5.2.1.4" href="#section-5.2.1.4">5.2.1.4</a>. no-cache</span>
1244
1245 The "no-cache" request directive indicates that a cache MUST NOT use
1246 a stored response to satisfy the request without successful
1247 validation on the origin server.
1248
1249 <span class="h5"><a class="selflink" id="section-5.2.1.5" href="#section-5.2.1.5">5.2.1.5</a>. no-store</span>
1250
1251 The "no-store" request directive indicates that a cache MUST NOT
1252 store any part of either this request or any response to it. This
1253 directive applies to both private and shared caches. "MUST NOT
1254 store" in this context means that the cache MUST NOT intentionally
1255 store the information in non-volatile storage, and MUST make a
1256 best-effort attempt to remove the information from volatile storage
1257 as promptly as possible after forwarding it.
1258
1259 This directive is NOT a reliable or sufficient mechanism for ensuring
1260 privacy. In particular, malicious or compromised caches might not
1261 recognize or obey this directive, and communications networks might
1262 be vulnerable to eavesdropping.
1263
1264 Note that if a request containing this directive is satisfied from a
1265 cache, the no-store request directive does not apply to the already
1266 stored response.
1267
1268 <span class="h5"><a class="selflink" id="section-5.2.1.6" href="#section-5.2.1.6">5.2.1.6</a>. no-transform</span>
1269
1270 The "no-transform" request directive indicates that an intermediary
1271 (whether or not it implements a cache) MUST NOT transform the
1272 payload, as defined in <a href="./rfc7230#section-5.7.2">Section&nbsp;5.7.2 of [RFC7230]</a>.
1273
1274 <span class="h5"><a class="selflink" id="section-5.2.1.7" href="#section-5.2.1.7">5.2.1.7</a>. only-if-cached</span>
1275
1276 The "only-if-cached" request directive indicates that the client only
1277 wishes to obtain a stored response. If it receives this directive, a
1278 cache SHOULD either respond using a stored response that is
1279 consistent with the other constraints of the request, or respond with
1280
1281
1282
1283
1284 <span class="grey">Fielding, et al. Standards Track [Page 23]</span></pre>
1285 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-24" ></span>
1286 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1287
1288
1289 a 504 (Gateway Timeout) status code. If a group of caches is being
1290 operated as a unified system with good internal connectivity, a
1291 member cache MAY forward such a request within that group of caches.
1292
1293 <span class="h4"><a class="selflink" id="section-5.2.2" href="#section-5.2.2">5.2.2</a>. Response Cache-Control Directives</span>
1294
1295 <span class="h5"><a class="selflink" id="section-5.2.2.1" href="#section-5.2.2.1">5.2.2.1</a>. must-revalidate</span>
1296
1297 The "must-revalidate" response directive indicates that once it has
1298 become stale, a cache MUST NOT use the response to satisfy subsequent
1299 requests without successful validation on the origin server.
1300
1301 The must-revalidate directive is necessary to support reliable
1302 operation for certain protocol features. In all circumstances a
1303 cache MUST obey the must-revalidate directive; in particular, if a
1304 cache cannot reach the origin server for any reason, it MUST generate
1305 a 504 (Gateway Timeout) response.
1306
1307 The must-revalidate directive ought to be used by servers if and only
1308 if failure to validate a request on the representation could result
1309 in incorrect operation, such as a silently unexecuted financial
1310 transaction.
1311
1312 <span class="h5"><a class="selflink" id="section-5.2.2.2" href="#section-5.2.2.2">5.2.2.2</a>. no-cache</span>
1313
1314 Argument syntax:
1315
1316 #field-name
1317
1318 The "no-cache" response directive indicates that the response MUST
1319 NOT be used to satisfy a subsequent request without successful
1320 validation on the origin server. This allows an origin server to
1321 prevent a cache from using it to satisfy a request without contacting
1322 it, even by caches that have been configured to send stale responses.
1323
1324 If the no-cache response directive specifies one or more field-names,
1325 then a cache MAY use the response to satisfy a subsequent request,
1326 subject to any other restrictions on caching. However, any header
1327 fields in the response that have the field-name(s) listed MUST NOT be
1328 sent in the response to a subsequent request without successful
1329 revalidation with the origin server. This allows an origin server to
1330 prevent the re-use of certain header fields in a response, while
1331 still allowing caching of the rest of the response.
1332
1333 The field-names given are not limited to the set of header fields
1334 defined by this specification. Field names are case-insensitive.
1335
1336
1337
1338
1339
1340 <span class="grey">Fielding, et al. Standards Track [Page 24]</span></pre>
1341 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-25" ></span>
1342 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1343
1344
1345 This directive uses the quoted-string form of the argument syntax. A
1346 sender SHOULD NOT generate the token form (even if quoting appears
1347 not to be needed for single-entry lists).
1348
1349 Note: Although it has been back-ported to many implementations, some
1350 HTTP/1.0 caches will not recognize or obey this directive. Also,
1351 no-cache response directives with field-names are often handled by
1352 caches as if an unqualified no-cache directive was received; i.e.,
1353 the special handling for the qualified form is not widely
1354 implemented.
1355
1356 <span class="h5"><a class="selflink" id="section-5.2.2.3" href="#section-5.2.2.3">5.2.2.3</a>. no-store</span>
1357
1358 The "no-store" response directive indicates that a cache MUST NOT
1359 store any part of either the immediate request or response. This
1360 directive applies to both private and shared caches. "MUST NOT
1361 store" in this context means that the cache MUST NOT intentionally
1362 store the information in non-volatile storage, and MUST make a
1363 best-effort attempt to remove the information from volatile storage
1364 as promptly as possible after forwarding it.
1365
1366 This directive is NOT a reliable or sufficient mechanism for ensuring
1367 privacy. In particular, malicious or compromised caches might not
1368 recognize or obey this directive, and communications networks might
1369 be vulnerable to eavesdropping.
1370
1371 <span class="h5"><a class="selflink" id="section-5.2.2.4" href="#section-5.2.2.4">5.2.2.4</a>. no-transform</span>
1372
1373 The "no-transform" response directive indicates that an intermediary
1374 (regardless of whether it implements a cache) MUST NOT transform the
1375 payload, as defined in <a href="./rfc7230#section-5.7.2">Section&nbsp;5.7.2 of [RFC7230]</a>.
1376
1377 <span class="h5"><a class="selflink" id="section-5.2.2.5" href="#section-5.2.2.5">5.2.2.5</a>. public</span>
1378
1379 The "public" response directive indicates that any cache MAY store
1380 the response, even if the response would normally be non-cacheable or
1381 cacheable only within a private cache. (See <a href="#section-3.2">Section 3.2</a> for
1382 additional details related to the use of public in response to a
1383 request containing Authorization, and <a href="#section-3">Section 3</a> for details of how
1384 public affects responses that would normally not be stored, due to
1385 their status codes not being defined as cacheable by default; see
1386 <a href="#section-4.2.2">Section 4.2.2</a>.)
1387
1388 <span class="h5"><a class="selflink" id="section-5.2.2.6" href="#section-5.2.2.6">5.2.2.6</a>. private</span>
1389
1390 Argument syntax:
1391
1392 #field-name
1393
1394
1395
1396 <span class="grey">Fielding, et al. Standards Track [Page 25]</span></pre>
1397 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-26" ></span>
1398 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1399
1400
1401 The "private" response directive indicates that the response message
1402 is intended for a single user and MUST NOT be stored by a shared
1403 cache. A private cache MAY store the response and reuse it for later
1404 requests, even if the response would normally be non-cacheable.
1405
1406 If the private response directive specifies one or more field-names,
1407 this requirement is limited to the field-values associated with the
1408 listed response header fields. That is, a shared cache MUST NOT
1409 store the specified field-names(s), whereas it MAY store the
1410 remainder of the response message.
1411
1412 The field-names given are not limited to the set of header fields
1413 defined by this specification. Field names are case-insensitive.
1414
1415 This directive uses the quoted-string form of the argument syntax. A
1416 sender SHOULD NOT generate the token form (even if quoting appears
1417 not to be needed for single-entry lists).
1418
1419 Note: This usage of the word "private" only controls where the
1420 response can be stored; it cannot ensure the privacy of the message
1421 content. Also, private response directives with field-names are
1422 often handled by caches as if an unqualified private directive was
1423 received; i.e., the special handling for the qualified form is not
1424 widely implemented.
1425
1426 <span class="h5"><a class="selflink" id="section-5.2.2.7" href="#section-5.2.2.7">5.2.2.7</a>. proxy-revalidate</span>
1427
1428 The "proxy-revalidate" response directive has the same meaning as the
1429 must-revalidate response directive, except that it does not apply to
1430 private caches.
1431
1432 <span class="h5"><a class="selflink" id="section-5.2.2.8" href="#section-5.2.2.8">5.2.2.8</a>. max-age</span>
1433
1434 Argument syntax:
1435
1436 delta-seconds (see <a href="#section-1.2.1">Section 1.2.1</a>)
1437
1438 The "max-age" response directive indicates that the response is to be
1439 considered stale after its age is greater than the specified number
1440 of seconds.
1441
1442 This directive uses the token form of the argument syntax: e.g.,
1443 'max-age=5' not 'max-age="5"'. A sender SHOULD NOT generate the
1444 quoted-string form.
1445
1446
1447
1448
1449
1450
1451
1452 <span class="grey">Fielding, et al. Standards Track [Page 26]</span></pre>
1453 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-27" ></span>
1454 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1455
1456
1457 <span class="h5"><a class="selflink" id="section-5.2.2.9" href="#section-5.2.2.9">5.2.2.9</a>. s-maxage</span>
1458
1459 Argument syntax:
1460
1461 delta-seconds (see <a href="#section-1.2.1">Section 1.2.1</a>)
1462
1463 The "s-maxage" response directive indicates that, in shared caches,
1464 the maximum age specified by this directive overrides the maximum age
1465 specified by either the max-age directive or the Expires header
1466 field. The s-maxage directive also implies the semantics of the
1467 proxy-revalidate response directive.
1468
1469 This directive uses the token form of the argument syntax: e.g.,
1470 's-maxage=10' not 's-maxage="10"'. A sender SHOULD NOT generate the
1471 quoted-string form.
1472
1473 <span class="h4"><a class="selflink" id="section-5.2.3" href="#section-5.2.3">5.2.3</a>. Cache Control Extensions</span>
1474
1475 The Cache-Control header field can be extended through the use of one
1476 or more cache-extension tokens, each with an optional value. A cache
1477 MUST ignore unrecognized cache directives.
1478
1479 Informational extensions (those that do not require a change in cache
1480 behavior) can be added without changing the semantics of other
1481 directives.
1482
1483 Behavioral extensions are designed to work by acting as modifiers to
1484 the existing base of cache directives. Both the new directive and
1485 the old directive are supplied, such that applications that do not
1486 understand the new directive will default to the behavior specified
1487 by the old directive, and those that understand the new directive
1488 will recognize it as modifying the requirements associated with the
1489 old directive. In this way, extensions to the existing cache-control
1490 directives can be made without breaking deployed caches.
1491
1492 For example, consider a hypothetical new response directive called
1493 "community" that acts as a modifier to the private directive: in
1494 addition to private caches, any cache that is shared only by members
1495 of the named community is allowed to cache the response. An origin
1496 server wishing to allow the UCI community to use an otherwise private
1497 response in their shared cache(s) could do so by including
1498
1499 Cache-Control: private, community="UCI"
1500
1501 A cache that recognizes such a community cache-extension could
1502 broaden its behavior in accordance with that extension. A cache that
1503 does not recognize the community cache-extension would ignore it and
1504 adhere to the private directive.
1505
1506
1507
1508 <span class="grey">Fielding, et al. Standards Track [Page 27]</span></pre>
1509 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-28" ></span>
1510 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1511
1512
1513 <span class="h3"><a class="selflink" id="section-5.3" href="#section-5.3">5.3</a>. Expires</span>
1514
1515 The "Expires" header field gives the date/time after which the
1516 response is considered stale. See <a href="#section-4.2">Section 4.2</a> for further discussion
1517 of the freshness model.
1518
1519 The presence of an Expires field does not imply that the original
1520 resource will change or cease to exist at, before, or after that
1521 time.
1522
1523 The Expires value is an HTTP-date timestamp, as defined in <a href="./rfc7231#section-7.1.1.1">Section</a>
1524 <a href="./rfc7231#section-7.1.1.1">7.1.1.1 of [RFC7231]</a>.
1525
1526 Expires = HTTP-date
1527
1528 For example
1529
1530 Expires: Thu, 01 Dec 1994 16:00:00 GMT
1531
1532 A cache recipient MUST interpret invalid date formats, especially the
1533 value "0", as representing a time in the past (i.e., "already
1534 expired").
1535
1536 If a response includes a Cache-Control field with the max-age
1537 directive (<a href="#section-5.2.2.8">Section 5.2.2.8</a>), a recipient MUST ignore the Expires
1538 field. Likewise, if a response includes the s-maxage directive
1539 (<a href="#section-5.2.2.9">Section 5.2.2.9</a>), a shared cache recipient MUST ignore the Expires
1540 field. In both these cases, the value in Expires is only intended
1541 for recipients that have not yet implemented the Cache-Control field.
1542
1543 An origin server without a clock MUST NOT generate an Expires field
1544 unless its value represents a fixed time in the past (always expired)
1545 or its value has been associated with the resource by a system or
1546 user with a reliable clock.
1547
1548 Historically, HTTP required the Expires field-value to be no more
1549 than a year in the future. While longer freshness lifetimes are no
1550 longer prohibited, extremely large values have been demonstrated to
1551 cause problems (e.g., clock overflows due to use of 32-bit integers
1552 for time values), and many caches will evict a response far sooner
1553 than that.
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564 <span class="grey">Fielding, et al. Standards Track [Page 28]</span></pre>
1565 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-29" ></span>
1566 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1567
1568
1569 <span class="h3"><a class="selflink" id="section-5.4" href="#section-5.4">5.4</a>. Pragma</span>
1570
1571 The "Pragma" header field allows backwards compatibility with
1572 HTTP/1.0 caches, so that clients can specify a "no-cache" request
1573 that they will understand (as Cache-Control was not defined until
1574 HTTP/1.1). When the Cache-Control header field is also present and
1575 understood in a request, Pragma is ignored.
1576
1577 In HTTP/1.0, Pragma was defined as an extensible field for
1578 implementation-specified directives for recipients. This
1579 specification deprecates such extensions to improve interoperability.
1580
1581 Pragma = 1#pragma-directive
1582 pragma-directive = "no-cache" / extension-pragma
1583 extension-pragma = token [ "=" ( token / quoted-string ) ]
1584
1585 When the Cache-Control header field is not present in a request,
1586 caches MUST consider the no-cache request pragma-directive as having
1587 the same effect as if "Cache-Control: no-cache" were present (see
1588 <a href="#section-5.2.1">Section 5.2.1</a>).
1589
1590 When sending a no-cache request, a client ought to include both the
1591 pragma and cache-control directives, unless Cache-Control: no-cache
1592 is purposefully omitted to target other Cache-Control response
1593 directives at HTTP/1.1 caches. For example:
1594
1595 GET / HTTP/1.1
1596 Host: www.example.com
1597 Cache-Control: max-age=30
1598 Pragma: no-cache
1599
1600 will constrain HTTP/1.1 caches to serve a response no older than 30
1601 seconds, while precluding implementations that do not understand
1602 Cache-Control from serving a cached response.
1603
1604 Note: Because the meaning of "Pragma: no-cache" in responses is
1605 not specified, it does not provide a reliable replacement for
1606 "Cache-Control: no-cache" in them.
1607
1608 <span class="h3"><a class="selflink" id="section-5.5" href="#section-5.5">5.5</a>. Warning</span>
1609
1610 The "Warning" header field is used to carry additional information
1611 about the status or transformation of a message that might not be
1612 reflected in the status code. This information is typically used to
1613 warn about possible incorrectness introduced by caching operations or
1614 transformations applied to the payload of the message.
1615
1616
1617
1618
1619
1620 <span class="grey">Fielding, et al. Standards Track [Page 29]</span></pre>
1621 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-30" ></span>
1622 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1623
1624
1625 Warnings can be used for other purposes, both cache-related and
1626 otherwise. The use of a warning, rather than an error status code,
1627 distinguishes these responses from true failures.
1628
1629 Warning header fields can in general be applied to any message,
1630 however some warn-codes are specific to caches and can only be
1631 applied to response messages.
1632
1633 Warning = 1#warning-value
1634
1635 warning-value = warn-code SP warn-agent SP warn-text
1636 [ SP warn-date ]
1637
1638 warn-code = 3DIGIT
1639 warn-agent = ( uri-host [ ":" port ] ) / pseudonym
1640 ; the name or pseudonym of the server adding
1641 ; the Warning header field, for use in debugging
1642 ; a single "-" is recommended when agent unknown
1643 warn-text = quoted-string
1644 warn-date = DQUOTE HTTP-date DQUOTE
1645
1646 Multiple warnings can be generated in a response (either by the
1647 origin server or by a cache), including multiple warnings with the
1648 same warn-code number that only differ in warn-text.
1649
1650 A user agent that receives one or more Warning header fields SHOULD
1651 inform the user of as many of them as possible, in the order that
1652 they appear in the response. Senders that generate multiple Warning
1653 header fields are encouraged to order them with this user agent
1654 behavior in mind. A sender that generates new Warning header fields
1655 MUST append them after any existing Warning header fields.
1656
1657 Warnings are assigned three digit warn-codes. The first digit
1658 indicates whether the Warning is required to be deleted from a stored
1659 response after validation:
1660
1661 o 1xx warn-codes describe the freshness or validation status of the
1662 response, and so they MUST be deleted by a cache after validation.
1663 They can only be generated by a cache when validating a cached
1664 entry, and MUST NOT be generated in any other situation.
1665
1666 o 2xx warn-codes describe some aspect of the representation that is
1667 not rectified by a validation (for example, a lossy compression of
1668 the representation) and they MUST NOT be deleted by a cache after
1669 validation, unless a full response is sent, in which case they
1670 MUST be.
1671
1672
1673
1674
1675
1676 <span class="grey">Fielding, et al. Standards Track [Page 30]</span></pre>
1677 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-31" ></span>
1678 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1679
1680
1681 If a sender generates one or more 1xx warn-codes in a message to be
1682 sent to a recipient known to implement only HTTP/1.0, the sender MUST
1683 include in each corresponding warning-value a warn-date that matches
1684 the Date header field in the message. For example:
1685
1686 HTTP/1.1 200 OK
1687 Date: Sat, 25 Aug 2012 23:34:45 GMT
1688 Warning: 112 - "network down" "Sat, 25 Aug 2012 23:34:45 GMT"
1689
1690
1691 Warnings have accompanying warn-text that describes the error, e.g.,
1692 for logging. It is advisory only, and its content does not affect
1693 interpretation of the warn-code.
1694
1695 If a recipient that uses, evaluates, or displays Warning header
1696 fields receives a warn-date that is different from the Date value in
1697 the same message, the recipient MUST exclude the warning-value
1698 containing that warn-date before storing, forwarding, or using the
1699 message. This allows recipients to exclude warning-values that were
1700 improperly retained after a cache validation. If all of the
1701 warning-values are excluded, the recipient MUST exclude the Warning
1702 header field as well.
1703
1704 The following warn-codes are defined by this specification, each with
1705 a recommended warn-text in English, and a description of its meaning.
1706 The procedure for defining additional warn codes is described in
1707 <a href="#section-7.2.1">Section 7.2.1</a>.
1708
1709 <span class="h4"><a class="selflink" id="section-5.5.1" href="#section-5.5.1">5.5.1</a>. Warning: 110 - "Response is Stale"</span>
1710
1711 A cache SHOULD generate this whenever the sent response is stale.
1712
1713 <span class="h4"><a class="selflink" id="section-5.5.2" href="#section-5.5.2">5.5.2</a>. Warning: 111 - "Revalidation Failed"</span>
1714
1715 A cache SHOULD generate this when sending a stale response because an
1716 attempt to validate the response failed, due to an inability to reach
1717 the server.
1718
1719 <span class="h4"><a class="selflink" id="section-5.5.3" href="#section-5.5.3">5.5.3</a>. Warning: 112 - "Disconnected Operation"</span>
1720
1721 A cache SHOULD generate this if it is intentionally disconnected from
1722 the rest of the network for a period of time.
1723
1724 <span class="h4"><a class="selflink" id="section-5.5.4" href="#section-5.5.4">5.5.4</a>. Warning: 113 - "Heuristic Expiration"</span>
1725
1726 A cache SHOULD generate this if it heuristically chose a freshness
1727 lifetime greater than 24 hours and the response's age is greater than
1728 24 hours.
1729
1730
1731
1732 <span class="grey">Fielding, et al. Standards Track [Page 31]</span></pre>
1733 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-32" ></span>
1734 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1735
1736
1737 <span class="h4"><a class="selflink" id="section-5.5.5" href="#section-5.5.5">5.5.5</a>. Warning: 199 - "Miscellaneous Warning"</span>
1738
1739 The warning text can include arbitrary information to be presented to
1740 a human user or logged. A system receiving this warning MUST NOT
1741 take any automated action, besides presenting the warning to the
1742 user.
1743
1744 <span class="h4"><a class="selflink" id="section-5.5.6" href="#section-5.5.6">5.5.6</a>. Warning: 214 - "Transformation Applied"</span>
1745
1746 This Warning code MUST be added by a proxy if it applies any
1747 transformation to the representation, such as changing the
1748 content-coding, media-type, or modifying the representation data,
1749 unless this Warning code already appears in the response.
1750
1751 <span class="h4"><a class="selflink" id="section-5.5.7" href="#section-5.5.7">5.5.7</a>. Warning: 299 - "Miscellaneous Persistent Warning"</span>
1752
1753 The warning text can include arbitrary information to be presented to
1754 a human user or logged. A system receiving this warning MUST NOT
1755 take any automated action.
1756
1757 <span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>. History Lists</span>
1758
1759 User agents often have history mechanisms, such as "Back" buttons and
1760 history lists, that can be used to redisplay a representation
1761 retrieved earlier in a session.
1762
1763 The freshness model (<a href="#section-4.2">Section 4.2</a>) does not necessarily apply to
1764 history mechanisms. That is, a history mechanism can display a
1765 previous representation even if it has expired.
1766
1767 This does not prohibit the history mechanism from telling the user
1768 that a view might be stale or from honoring cache directives (e.g.,
1769 Cache-Control: no-store).
1770
1771 <span class="h2"><a class="selflink" id="section-7" href="#section-7">7</a>. IANA Considerations</span>
1772
1773 <span class="h3"><a class="selflink" id="section-7.1" href="#section-7.1">7.1</a>. Cache Directive Registry</span>
1774
1775 The "Hypertext Transfer Protocol (HTTP) Cache Directive Registry"
1776 defines the namespace for the cache directives. It has been created
1777 and is now maintained at
1778 &lt;<a href="http://www.iana.org/assignments/http-cache-directives">http://www.iana.org/assignments/http-cache-directives</a>&gt;.
1779
1780 <span class="h4"><a class="selflink" id="section-7.1.1" href="#section-7.1.1">7.1.1</a>. Procedure</span>
1781
1782 A registration MUST include the following fields:
1783
1784 o Cache Directive Name
1785
1786
1787
1788 <span class="grey">Fielding, et al. Standards Track [Page 32]</span></pre>
1789 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-33" ></span>
1790 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1791
1792
1793 o Pointer to specification text
1794
1795 Values to be added to this namespace require IETF Review (see
1796 <a href="./rfc5226#section-4.1">[RFC5226], Section&nbsp;4.1</a>).
1797
1798 <span class="h4"><a class="selflink" id="section-7.1.2" href="#section-7.1.2">7.1.2</a>. Considerations for New Cache Control Directives</span>
1799
1800 New extension directives ought to consider defining:
1801
1802 o What it means for a directive to be specified multiple times,
1803
1804 o When the directive does not take an argument, what it means when
1805 an argument is present,
1806
1807 o When the directive requires an argument, what it means when it is
1808 missing,
1809
1810 o Whether the directive is specific to requests, responses, or able
1811 to be used in either.
1812
1813 See also <a href="#section-5.2.3">Section 5.2.3</a>.
1814
1815 <span class="h4"><a class="selflink" id="section-7.1.3" href="#section-7.1.3">7.1.3</a>. Registrations</span>
1816
1817 The registry has been populated with the registrations below:
1818
1819 +------------------------+----------------------------------+
1820 | Cache Directive | Reference |
1821 +------------------------+----------------------------------+
1822 | max-age | <a href="#section-5.2.1.1">Section 5.2.1.1</a>, <a href="#section-5.2.2.8">Section 5.2.2.8</a> |
1823 | max-stale | <a href="#section-5.2.1.2">Section 5.2.1.2</a> |
1824 | min-fresh | <a href="#section-5.2.1.3">Section 5.2.1.3</a> |
1825 | must-revalidate | <a href="#section-5.2.2.1">Section 5.2.2.1</a> |
1826 | no-cache | <a href="#section-5.2.1.4">Section 5.2.1.4</a>, <a href="#section-5.2.2.2">Section 5.2.2.2</a> |
1827 | no-store | <a href="#section-5.2.1.5">Section 5.2.1.5</a>, <a href="#section-5.2.2.3">Section 5.2.2.3</a> |
1828 | no-transform | <a href="#section-5.2.1.6">Section 5.2.1.6</a>, <a href="#section-5.2.2.4">Section 5.2.2.4</a> |
1829 | only-if-cached | <a href="#section-5.2.1.7">Section 5.2.1.7</a> |
1830 | private | <a href="#section-5.2.2.6">Section 5.2.2.6</a> |
1831 | proxy-revalidate | <a href="#section-5.2.2.7">Section 5.2.2.7</a> |
1832 | public | <a href="#section-5.2.2.5">Section 5.2.2.5</a> |
1833 | s-maxage | <a href="#section-5.2.2.9">Section 5.2.2.9</a> |
1834 | stale-if-error | <a href="./rfc5861#section-4">[RFC5861], Section&nbsp;4</a> |
1835 | stale-while-revalidate | <a href="./rfc5861#section-3">[RFC5861], Section&nbsp;3</a> |
1836 +------------------------+----------------------------------+
1837
1838
1839
1840
1841
1842
1843
1844 <span class="grey">Fielding, et al. Standards Track [Page 33]</span></pre>
1845 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-34" ></span>
1846 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1847
1848
1849 <span class="h3"><a class="selflink" id="section-7.2" href="#section-7.2">7.2</a>. Warn Code Registry</span>
1850
1851 The "Hypertext Transfer Protocol (HTTP) Warn Codes" registry defines
1852 the namespace for warn codes. It has been created and is now
1853 maintained at &lt;<a href="http://www.iana.org/assignments/http-warn-codes">http://www.iana.org/assignments/http-warn-codes</a>&gt;.
1854
1855 <span class="h4"><a class="selflink" id="section-7.2.1" href="#section-7.2.1">7.2.1</a>. Procedure</span>
1856
1857 A registration MUST include the following fields:
1858
1859 o Warn Code (3 digits)
1860
1861 o Short Description
1862
1863 o Pointer to specification text
1864
1865 Values to be added to this namespace require IETF Review (see
1866 <a href="./rfc5226#section-4.1">[RFC5226], Section&nbsp;4.1</a>).
1867
1868 <span class="h4"><a class="selflink" id="section-7.2.2" href="#section-7.2.2">7.2.2</a>. Registrations</span>
1869
1870 The registry has been populated with the registrations below:
1871
1872 +-----------+----------------------------------+---------------+
1873 | Warn Code | Short Description | Reference |
1874 +-----------+----------------------------------+---------------+
1875 | 110 | Response is Stale | <a href="#section-5.5.1">Section 5.5.1</a> |
1876 | 111 | Revalidation Failed | <a href="#section-5.5.2">Section 5.5.2</a> |
1877 | 112 | Disconnected Operation | <a href="#section-5.5.3">Section 5.5.3</a> |
1878 | 113 | Heuristic Expiration | <a href="#section-5.5.4">Section 5.5.4</a> |
1879 | 199 | Miscellaneous Warning | <a href="#section-5.5.5">Section 5.5.5</a> |
1880 | 214 | Transformation Applied | <a href="#section-5.5.6">Section 5.5.6</a> |
1881 | 299 | Miscellaneous Persistent Warning | <a href="#section-5.5.7">Section 5.5.7</a> |
1882 +-----------+----------------------------------+---------------+
1883
1884 <span class="h3"><a class="selflink" id="section-7.3" href="#section-7.3">7.3</a>. Header Field Registration</span>
1885
1886 HTTP header fields are registered within the "Message Headers"
1887 registry maintained at
1888 &lt;<a href="http://www.iana.org/assignments/message-headers/">http://www.iana.org/assignments/message-headers/</a>&gt;.
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900 <span class="grey">Fielding, et al. Standards Track [Page 34]</span></pre>
1901 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-35" ></span>
1902 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1903
1904
1905 This document defines the following HTTP header fields, so the
1906 "Permanent Message Header Field Names" registry has been updated
1907 accordingly (see [<a href="#ref-BCP90" title="&quot;Registration Procedures for Message Header Fields&quot;">BCP90</a>]).
1908
1909 +-------------------+----------+----------+-------------+
1910 | Header Field Name | Protocol | Status | Reference |
1911 +-------------------+----------+----------+-------------+
1912 | Age | http | standard | <a href="#section-5.1">Section 5.1</a> |
1913 | Cache-Control | http | standard | <a href="#section-5.2">Section 5.2</a> |
1914 | Expires | http | standard | <a href="#section-5.3">Section 5.3</a> |
1915 | Pragma | http | standard | <a href="#section-5.4">Section 5.4</a> |
1916 | Warning | http | standard | <a href="#section-5.5">Section 5.5</a> |
1917 +-------------------+----------+----------+-------------+
1918
1919 The change controller is: "IETF ([email protected]) - Internet
1920 Engineering Task Force".
1921
1922 <span class="h2"><a class="selflink" id="section-8" href="#section-8">8</a>. Security Considerations</span>
1923
1924 This section is meant to inform developers, information providers,
1925 and users of known security concerns specific to HTTP caching. More
1926 general security considerations are addressed in HTTP messaging
1927 [<a href="./rfc7230" title="&quot;Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing&quot;">RFC7230</a>] and semantics [<a href="./rfc7231" title="&quot;Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content&quot;">RFC7231</a>].
1928
1929 Caches expose additional potential vulnerabilities, since the
1930 contents of the cache represent an attractive target for malicious
1931 exploitation. Because cache contents persist after an HTTP request
1932 is complete, an attack on the cache can reveal information long after
1933 a user believes that the information has been removed from the
1934 network. Therefore, cache contents need to be protected as sensitive
1935 information.
1936
1937 In particular, various attacks might be amplified by being stored in
1938 a shared cache; such "cache poisoning" attacks use the cache to
1939 distribute a malicious payload to many clients, and are especially
1940 effective when an attacker can use implementation flaws, elevated
1941 privileges, or other techniques to insert such a response into a
1942 cache. One common attack vector for cache poisoning is to exploit
1943 differences in message parsing on proxies and in user agents; see
1944 <a href="./rfc7230#section-3.3.3">Section&nbsp;3.3.3 of [RFC7230]</a> for the relevant requirements.
1945
1946 Likewise, implementation flaws (as well as misunderstanding of cache
1947 operation) might lead to caching of sensitive information (e.g.,
1948 authentication credentials) that is thought to be private, exposing
1949 it to unauthorized parties.
1950
1951
1952
1953
1954
1955
1956 <span class="grey">Fielding, et al. Standards Track [Page 35]</span></pre>
1957 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-36" ></span>
1958 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
1959
1960
1961 Furthermore, the very use of a cache can bring about privacy
1962 concerns. For example, if two users share a cache, and the first one
1963 browses to a site, the second may be able to detect that the other
1964 has been to that site, because the resources from it load more
1965 quickly, thanks to the cache.
1966
1967 Note that the Set-Cookie response header field [<a href="./rfc6265" title="&quot;HTTP State Management Mechanism&quot;">RFC6265</a>] does not
1968 inhibit caching; a cacheable response with a Set-Cookie header field
1969 can be (and often is) used to satisfy subsequent requests to caches.
1970 Servers who wish to control caching of these responses are encouraged
1971 to emit appropriate Cache-Control response header fields.
1972
1973 <span class="h2"><a class="selflink" id="section-9" href="#section-9">9</a>. Acknowledgments</span>
1974
1975 See <a href="./rfc7230#section-10">Section&nbsp;10 of [RFC7230]</a>.
1976
1977 <span class="h2"><a class="selflink" id="section-10" href="#section-10">10</a>. References</span>
1978
1979 <span class="h3"><a class="selflink" id="section-10.1" href="#section-10.1">10.1</a>. Normative References</span>
1980
1981 [<a id="ref-RFC2119">RFC2119</a>] Bradner, S., "Key words for use in RFCs to Indicate
1982 Requirement Levels", <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>, March 1997.
1983
1984 [<a id="ref-RFC5234">RFC5234</a>] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
1985 Specifications: ABNF", STD 68, <a href="./rfc5234">RFC 5234</a>, January 2008.
1986
1987 [<a id="ref-RFC7230">RFC7230</a>] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
1988 Protocol (HTTP/1.1): Message Syntax and Routing",
1989 <a href="./rfc7230">RFC 7230</a>, June 2014.
1990
1991 [<a id="ref-RFC7231">RFC7231</a>] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
1992 Protocol (HTTP/1.1): Semantics and Content", <a href="./rfc7231">RFC 7231</a>,
1993 June 2014.
1994
1995 [<a id="ref-RFC7232">RFC7232</a>] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
1996 Protocol (HTTP/1.1): Conditional Requests", <a href="./rfc7232">RFC 7232</a>,
1997 June 2014.
1998
1999 [<a id="ref-RFC7233">RFC7233</a>] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
2000 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests",
2001 <a href="./rfc7233">RFC 7233</a>, June 2014.
2002
2003 [<a id="ref-RFC7235">RFC7235</a>] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
2004 Protocol (HTTP/1.1): Authentication", <a href="./rfc7235">RFC 7235</a>, June 2014.
2005
2006
2007
2008
2009
2010
2011
2012 <span class="grey">Fielding, et al. Standards Track [Page 36]</span></pre>
2013 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-37" ></span>
2014 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
2015
2016
2017 <span class="h3"><a class="selflink" id="section-10.2" href="#section-10.2">10.2</a>. Informative References</span>
2018
2019 [<a id="ref-BCP90">BCP90</a>] Klyne, G., Nottingham, M., and J. Mogul, "Registration
2020 Procedures for Message Header Fields", <a href="https://www.rfc-editor.org/bcp/bcp90">BCP 90</a>, <a href="./rfc3864">RFC 3864</a>,
2021 September 2004.
2022
2023 [<a id="ref-RFC2616">RFC2616</a>] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
2024 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
2025 Transfer Protocol -- HTTP/1.1", <a href="./rfc2616">RFC 2616</a>, June 1999.
2026
2027 [<a id="ref-RFC5226">RFC5226</a>] Narten, T. and H. Alvestrand, "Guidelines for Writing an
2028 IANA Considerations Section in RFCs", <a href="https://www.rfc-editor.org/bcp/bcp26">BCP 26</a>, <a href="./rfc5226">RFC 5226</a>,
2029 May 2008.
2030
2031 [<a id="ref-RFC5861">RFC5861</a>] Nottingham, M., "HTTP Cache-Control Extensions for Stale
2032 Content", <a href="./rfc5861">RFC 5861</a>, April 2010.
2033
2034 [<a id="ref-RFC5905">RFC5905</a>] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch,
2035 "Network Time Protocol Version 4: Protocol and Algorithms
2036 Specification", <a href="./rfc5905">RFC 5905</a>, June 2010.
2037
2038 [<a id="ref-RFC6265">RFC6265</a>] Barth, A., "HTTP State Management Mechanism", <a href="./rfc6265">RFC 6265</a>,
2039 April 2011.
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068 <span class="grey">Fielding, et al. Standards Track [Page 37]</span></pre>
2069 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-38" ></span>
2070 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
2071
2072
2073 <span class="h2"><a class="selflink" id="appendix-A" href="#appendix-A">Appendix A</a>. Changes from <a href="./rfc2616">RFC 2616</a></span>
2074
2075 The specification has been substantially rewritten for clarity.
2076
2077 The conditions under which an authenticated response can be cached
2078 have been clarified. (<a href="#section-3.2">Section 3.2</a>)
2079
2080 New status codes can now define that caches are allowed to use
2081 heuristic freshness with them. Caches are now allowed to calculate
2082 heuristic freshness for URIs with query components. (<a href="#section-4.2.2">Section 4.2.2</a>)
2083
2084 The algorithm for calculating age is now less conservative. Caches
2085 are now required to handle dates with time zones as if they're
2086 invalid, because it's not possible to accurately guess.
2087 (<a href="#section-4.2.3">Section 4.2.3</a>)
2088
2089 The Content-Location response header field is no longer used to
2090 determine the appropriate response to use when validating.
2091 (<a href="#section-4.3">Section 4.3</a>)
2092
2093 The algorithm for selecting a cached negotiated response to use has
2094 been clarified in several ways. In particular, it now explicitly
2095 allows header-specific canonicalization when processing selecting
2096 header fields. (<a href="#section-4.1">Section 4.1</a>)
2097
2098 Requirements regarding denial-of-service attack avoidance when
2099 performing invalidation have been clarified. (<a href="#section-4.4">Section 4.4</a>)
2100
2101 Cache invalidation only occurs when a successful response is
2102 received. (<a href="#section-4.4">Section 4.4</a>)
2103
2104 Cache directives are explicitly defined to be case-insensitive.
2105 Handling of multiple instances of cache directives when only one is
2106 expected is now defined. (<a href="#section-5.2">Section 5.2</a>)
2107
2108 The "no-store" request directive doesn't apply to responses; i.e., a
2109 cache can satisfy a request with no-store on it and does not
2110 invalidate it. (<a href="#section-5.2.1.5">Section 5.2.1.5</a>)
2111
2112 The qualified forms of the private and no-cache cache directives are
2113 noted to not be widely implemented; for example, "private=foo" is
2114 interpreted by many caches as simply "private". Additionally, the
2115 meaning of the qualified form of no-cache has been clarified.
2116 (<a href="#section-5.2.2">Section 5.2.2</a>)
2117
2118 The "no-cache" response directive's meaning has been clarified.
2119 (<a href="#section-5.2.2.2">Section 5.2.2.2</a>)
2120
2121
2122
2123
2124 <span class="grey">Fielding, et al. Standards Track [Page 38]</span></pre>
2125 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-39" ></span>
2126 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
2127
2128
2129 The one-year limit on Expires header field values has been removed;
2130 instead, the reasoning for using a sensible value is given.
2131 (<a href="#section-5.3">Section 5.3</a>)
2132
2133 The Pragma header field is now only defined for backwards
2134 compatibility; future pragmas are deprecated. (<a href="#section-5.4">Section 5.4</a>)
2135
2136 Some requirements regarding production and processing of the Warning
2137 header fields have been relaxed, as it is not widely implemented.
2138 Furthermore, the Warning header field no longer uses <a href="./rfc2047">RFC 2047</a>
2139 encoding, nor does it allow multiple languages, as these aspects were
2140 not implemented. (<a href="#section-5.5">Section 5.5</a>)
2141
2142 This specification introduces the Cache Directive and Warn Code
2143 Registries, and defines considerations for new cache directives.
2144 (<a href="#section-7.1">Section 7.1</a> and <a href="#section-7.2">Section 7.2</a>)
2145
2146 <span class="h2"><a class="selflink" id="appendix-B" href="#appendix-B">Appendix B</a>. Imported ABNF</span>
2147
2148 The following core rules are included by reference, as defined in
2149 <a href="./rfc5234#appendix-B.1">Appendix&nbsp;B.1 of [RFC5234]</a>: ALPHA (letters), CR (carriage return),
2150 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double
2151 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any
2152 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII
2153 character).
2154
2155 The rules below are defined in [<a href="./rfc7230" title="&quot;Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing&quot;">RFC7230</a>]:
2156
2157 OWS = &lt;OWS, see <a href="./rfc7230#section-3.2.3">[RFC7230], Section&nbsp;3.2.3</a>&gt;
2158 field-name = &lt;field-name, see <a href="./rfc7230#section-3.2">[RFC7230], Section&nbsp;3.2</a>&gt;
2159 quoted-string = &lt;quoted-string, see <a href="./rfc7230#section-3.2.6">[RFC7230], Section&nbsp;3.2.6</a>&gt;
2160 token = &lt;token, see <a href="./rfc7230#section-3.2.6">[RFC7230], Section&nbsp;3.2.6</a>&gt;
2161
2162 port = &lt;port, see <a href="./rfc7230#section-2.7">[RFC7230], Section&nbsp;2.7</a>&gt;
2163 pseudonym = &lt;pseudonym, see <a href="./rfc7230#section-5.7.1">[RFC7230], Section&nbsp;5.7.1</a>&gt;
2164 uri-host = &lt;uri-host, see <a href="./rfc7230#section-2.7">[RFC7230], Section&nbsp;2.7</a>&gt;
2165
2166 The rules below are defined in other parts:
2167
2168 HTTP-date = &lt;HTTP-date, see <a href="./rfc7231#section-7.1.1.1">[RFC7231], Section&nbsp;7.1.1.1</a>&gt;
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180 <span class="grey">Fielding, et al. Standards Track [Page 39]</span></pre>
2181 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-40" ></span>
2182 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
2183
2184
2185 <span class="h2"><a class="selflink" id="appendix-C" href="#appendix-C">Appendix C</a>. Collected ABNF</span>
2186
2187 In the collected ABNF below, list rules are expanded as per <a href="./rfc7230#section-1.2">Section</a>
2188 <a href="./rfc7230#section-1.2">1.2 of [RFC7230]</a>.
2189
2190 Age = delta-seconds
2191
2192 Cache-Control = *( "," OWS ) cache-directive *( OWS "," [ OWS
2193 cache-directive ] )
2194
2195 Expires = HTTP-date
2196
2197 HTTP-date = &lt;HTTP-date, see <a href="./rfc7231#section-7.1.1.1">[RFC7231], Section&nbsp;7.1.1.1</a>&gt;
2198
2199 OWS = &lt;OWS, see <a href="./rfc7230#section-3.2.3">[RFC7230], Section&nbsp;3.2.3</a>&gt;
2200
2201 Pragma = *( "," OWS ) pragma-directive *( OWS "," [ OWS
2202 pragma-directive ] )
2203
2204 Warning = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value ]
2205 )
2206
2207 cache-directive = token [ "=" ( token / quoted-string ) ]
2208
2209 delta-seconds = 1*DIGIT
2210
2211 extension-pragma = token [ "=" ( token / quoted-string ) ]
2212
2213 field-name = &lt;field-name, see <a href="./rfc7230#section-3.2">[RFC7230], Section&nbsp;3.2</a>&gt;
2214
2215 port = &lt;port, see <a href="./rfc7230#section-2.7">[RFC7230], Section&nbsp;2.7</a>&gt;
2216 pragma-directive = "no-cache" / extension-pragma
2217 pseudonym = &lt;pseudonym, see <a href="./rfc7230#section-5.7.1">[RFC7230], Section&nbsp;5.7.1</a>&gt;
2218
2219 quoted-string = &lt;quoted-string, see <a href="./rfc7230#section-3.2.6">[RFC7230], Section&nbsp;3.2.6</a>&gt;
2220
2221 token = &lt;token, see <a href="./rfc7230#section-3.2.6">[RFC7230], Section&nbsp;3.2.6</a>&gt;
2222
2223 uri-host = &lt;uri-host, see <a href="./rfc7230#section-2.7">[RFC7230], Section&nbsp;2.7</a>&gt;
2224
2225 warn-agent = ( uri-host [ ":" port ] ) / pseudonym
2226 warn-code = 3DIGIT
2227 warn-date = DQUOTE HTTP-date DQUOTE
2228 warn-text = quoted-string
2229 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date
2230 ]
2231
2232
2233
2234
2235
2236 <span class="grey">Fielding, et al. Standards Track [Page 40]</span></pre>
2237 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-41" ></span>
2238 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
2239
2240
2241 Index
2242
2243 1
2244 110 (warn-code) 31
2245 111 (warn-code) 31
2246 112 (warn-code) 31
2247 113 (warn-code) 31
2248 199 (warn-code) 32
2249
2250 2
2251 214 (warn-code) 32
2252 299 (warn-code) 32
2253
2254 A
2255 age 11
2256 Age header field 21
2257
2258 C
2259 cache 4
2260 cache entry 5
2261 cache key 5-6
2262 Cache-Control header field 21
2263
2264 D
2265 Disconnected Operation (warn-text) 31
2266
2267 E
2268 Expires header field 28
2269 explicit expiration time 11
2270
2271 F
2272 fresh 11
2273 freshness lifetime 11
2274
2275 G
2276 Grammar
2277 Age 21
2278 Cache-Control 22
2279 cache-directive 22
2280 delta-seconds 5
2281 Expires 28
2282 extension-pragma 29
2283 Pragma 29
2284 pragma-directive 29
2285 warn-agent 29
2286 warn-code 29
2287 warn-date 29
2288 warn-text 29
2289
2290
2291
2292 <span class="grey">Fielding, et al. Standards Track [Page 41]</span></pre>
2293 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-42" ></span>
2294 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
2295
2296
2297 Warning 29
2298 warning-value 29
2299
2300 H
2301 Heuristic Expiration (warn-text) 31
2302 heuristic expiration time 11
2303 M
2304 max-age (cache directive) 22, 26
2305 max-stale (cache directive) 22
2306 min-fresh (cache directive) 22
2307 Miscellaneous Persistent Warning (warn-text) 32
2308 Miscellaneous Warning (warn-text) 32
2309 must-revalidate (cache directive) 24
2310
2311 N
2312 no-cache (cache directive) 23, 25
2313 no-store (cache directive) 23, 24
2314 no-transform (cache directive) 23, 25
2315
2316 O
2317 only-if-cached (cache directive) 23
2318
2319 P
2320 Pragma header field 29
2321 private (cache directive) 25
2322 private cache 4
2323 proxy-revalidate (cache directive) 26
2324 public (cache directive) 25
2325
2326 R
2327 Response is Stale (warn-text) 30
2328 Revalidation Failed (warn-text) 31
2329
2330 S
2331 s-maxage (cache directive) 27
2332 shared cache 4
2333 stale 11
2334 strong validator 18
2335
2336 T
2337 Transformation Applied (warn-text) 32
2338
2339 V
2340 validator 16
2341
2342 W
2343 Warning header field 29
2344
2345
2346
2347
2348 <span class="grey">Fielding, et al. Standards Track [Page 42]</span></pre>
2349 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-43" ></span>
2350 <span class="grey"><a href="./rfc7234">RFC 7234</a> HTTP/1.1 Caching June 2014</span>
2351
2352
2353 Authors' Addresses
2354
2355 Roy T. Fielding (editor)
2356 Adobe Systems Incorporated
2357 345 Park Ave
2358 San Jose, CA 95110
2359 USA
2360
2361 EMail: [email protected]
2362 URI: <a href="http://roy.gbiv.com/">http://roy.gbiv.com/</a>
2363
2364
2365 Mark Nottingham (editor)
2366 Akamai
2367
2368 EMail: [email protected]
2369 URI: <a href="http://www.mnot.net/">http://www.mnot.net/</a>
2370
2371
2372 Julian F. Reschke (editor)
2373 greenbytes GmbH
2374 Hafenweg 16
2375 Muenster, NW 48155
2376 Germany
2377
2378 EMail: [email protected]
2379 URI: <a href="http://greenbytes.de/tech/webdav/">http://greenbytes.de/tech/webdav/</a>
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404 Fielding, et al. Standards Track [Page 43]
2405 </pre>