source: draft-ietf-httpbis/latest/auth48/rfc7234-to-be.unpg.txt @ 2698

Last change on this file since 2698 was 2698, checked in by julian.reschke@…, 6 years ago

updated AUTH48 version of RFC7234 (#553)

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