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