Skip to main content

HTTP Caching
draft-ietf-httpbis-cache-02

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft that was ultimately published as RFC 9111.
Authors Roy T. Fielding , Mark Nottingham , Julian Reschke
Last updated 2018-07-02
Replaces draft-fielding-httpbis-http-cache
RFC stream Internet Engineering Task Force (IETF)
Formats
Reviews
Additional resources Mailing list discussion
Stream WG state WG Document
Associated WG milestone
Jun 2020
Submit the "core" HTTP documents for consideration as Internet Standards
Document shepherd (None)
IESG IESG state Became RFC 9111 (Internet Standard)
Consensus boilerplate Unknown
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-ietf-httpbis-cache-02
quot; response directive indicates that, in shared caches,
   the maximum age specified by this directive overrides the maximum age
   specified by either the max-age directive or the Expires header
   field.  The s-maxage directive also implies the semantics of the
   proxy-revalidate response directive.

   This directive uses the token form of the argument syntax: e.g.,
   's-maxage=10' not 's-maxage="10"'.  A sender SHOULD NOT generate the
   quoted-string form.

5.2.3.  Cache Control Extensions

   The Cache-Control header field can be extended through the use of one
   or more cache-extension tokens, each with an optional value.  A cache
   MUST ignore unrecognized cache directives.

   Informational extensions (those that do not require a change in cache
   behavior) can be added without changing the semantics of other
   directives.

   Behavioral extensions are designed to work by acting as modifiers to
   the existing base of cache directives.  Both the new directive and
   the old directive are supplied, such that applications that do not
   understand the new directive will default to the behavior specified
   by the old directive, and those that understand the new directive
   will recognize it as modifying the requirements associated with the
   old directive.  In this way, extensions to the existing cache-control
   directives can be made without breaking deployed caches.

Fielding, et al.         Expires January 3, 2019               [Page 28]
Internet-Draft                HTTP Caching                     July 2018

   For example, consider a hypothetical new response directive called
   "community" that acts as a modifier to the private directive: in
   addition to private caches, any cache that is shared only by members
   of the named community is allowed to cache the response.  An origin
   server wishing to allow the UCI community to use an otherwise private
   response in their shared cache(s) could do so by including

     Cache-Control: private, community="UCI"

   A cache that recognizes such a community cache-extension could
   broaden its behavior in accordance with that extension.  A cache that
   does not recognize the community cache-extension would ignore it and
   adhere to the private directive.

   New extension directives ought to consider defining:

   o  What it means for a directive to be specified multiple times,

   o  When the directive does not take an argument, what it means when
      an argument is present,

   o  When the directive requires an argument, what it means when it is
      missing,

   o  Whether the directive is specific to requests, responses, or able
      to be used in either.

5.2.4.  Cache Directive Registry

   The "Hypertext Transfer Protocol (HTTP) Cache Directive Registry"
   defines the namespace for the cache directives.  It has been created
   and is now maintained at <https://www.iana.org/assignments/http-
   cache-directives>.

   A registration MUST include the following fields:

   o  Cache Directive Name

   o  Pointer to specification text

   Values to be added to this namespace require IETF Review (see
   [RFC8126], Section 4.8).

5.3.  Expires

   The "Expires" header field gives the date/time after which the
   response is considered stale.  See Section 4.2 for further discussion
   of the freshness model.

Fielding, et al.         Expires January 3, 2019               [Page 29]
Internet-Draft                HTTP Caching                     July 2018

   The presence of an Expires field does not imply that the original
   resource will change or cease to exist at, before, or after that
   time.

   The Expires value is an HTTP-date timestamp, as defined in
   Section 10.1.1.1 of [Semantics].

     Expires = HTTP-date

   For example

     Expires: Thu, 01 Dec 1994 16:00:00 GMT

   A cache recipient MUST interpret invalid date formats, especially the
   value "0", as representing a time in the past (i.e., "already
   expired").

   If a response includes a Cache-Control field with the max-age
   directive (Section 5.2.2.8), a recipient MUST ignore the Expires
   field.  Likewise, if a response includes the s-maxage directive
   (Section 5.2.2.9), a shared cache recipient MUST ignore the Expires
   field.  In both these cases, the value in Expires is only intended
   for recipients that have not yet implemented the Cache-Control field.

   An origin server without a clock MUST NOT generate an Expires field
   unless its value represents a fixed time in the past (always expired)
   or its value has been associated with the resource by a system or
   user with a reliable clock.

   Historically, HTTP required the Expires field-value to be no more
   than a year in the future.  While longer freshness lifetimes are no
   longer prohibited, extremely large values have been demonstrated to
   cause problems (e.g., clock overflows due to use of 32-bit integers
   for time values), and many caches will evict a response far sooner
   than that.

5.4.  Pragma

   The "Pragma" header field allows backwards compatibility with
   HTTP/1.0 caches, so that clients can specify a "no-cache" request
   that they will understand (as Cache-Control was not defined until
   HTTP/1.1).  When the Cache-Control header field is also present and
   understood in a request, Pragma is ignored.

   In HTTP/1.0, Pragma was defined as an extensible field for
   implementation-specified directives for recipients.  This
   specification deprecates such extensions to improve interoperability.

Fielding, et al.         Expires January 3, 2019               [Page 30]
Internet-Draft                HTTP Caching                     July 2018

     Pragma           = 1#pragma-directive
     pragma-directive = "no-cache" / extension-pragma
     extension-pragma = token [ "=" ( token / quoted-string ) ]

   When the Cache-Control header field is not present in a request,
   caches MUST consider the no-cache request pragma-directive as having
   the same effect as if "Cache-Control: no-cache" were present (see
   Section 5.2.1).

   When sending a no-cache request, a client ought to include both the
   pragma and cache-control directives, unless Cache-Control: no-cache
   is purposefully omitted to target other Cache-Control request
   directives at HTTP/1.1 caches.  For example:

     GET / HTTP/1.1
     Host: www.example.com
     Cache-Control: max-age=30
     Pragma: no-cache

   will constrain HTTP/1.1 caches to serve a response no older than 30
   seconds, while precluding implementations that do not understand
   Cache-Control from serving a cached response.

      Note: Because the meaning of "Pragma: no-cache" in responses is
      not specified, it does not provide a reliable replacement for
      "Cache-Control: no-cache" in them.

5.5.  Warning

   The "Warning" header field is used to carry additional information
   about the status or transformation of a message that might not be
   reflected in the status code.  This information is typically used to
   warn about possible incorrectness introduced by caching operations or
   transformations applied to the payload of the message.

   Warnings can be used for other purposes, both cache-related and
   otherwise.  The use of a warning, rather than an error status code,
   distinguishes these responses from true failures.

   Warning header fields can in general be applied to any message,
   however some warn-codes are specific to caches and can only be
   applied to response messages.

Fielding, et al.         Expires January 3, 2019               [Page 31]
Internet-Draft                HTTP Caching                     July 2018

     Warning       = 1#warning-value

     warning-value = warn-code SP warn-agent SP warn-text
                                           [ SP warn-date ]

     warn-code  = 3DIGIT
     warn-agent = ( uri-host [ ":" port ] ) / pseudonym
                     ; the name or pseudonym of the server adding
                     ; the Warning header field, for use in debugging
                     ; a single "-" is recommended when agent unknown
     warn-text  = quoted-string
     warn-date  = DQUOTE HTTP-date DQUOTE

   Multiple warnings can be generated in a response (either by the
   origin server or by a cache), including multiple warnings with the
   same warn-code number that only differ in warn-text.

   A user agent that receives one or more Warning header fields SHOULD
   inform the user of as many of them as possible, in the order that
   they appear in the response.  Senders that generate multiple Warning
   header fields are encouraged to order them with this user agent
   behavior in mind.  A sender that generates new Warning header fields
   MUST append them after any existing Warning header fields.

   Warnings are assigned three digit warn-codes.  The first digit
   indicates whether the Warning is required to be deleted from a stored
   response after validation:

   o  1xx warn-codes describe the freshness or validation status of the
      response, and so they MUST be deleted by a cache after validation.
      They can only be generated by a cache when validating a cached
      entry, and MUST NOT be generated in any other situation.

   o  2xx warn-codes describe some aspect of the representation that is
      not rectified by a validation (for example, a lossy compression of
      the representation) and they MUST NOT be deleted by a cache after
      validation, unless a full response is sent, in which case they
      MUST be.

   If a sender generates one or more 1xx warn-codes in a message to be
   sent to a recipient known to implement only HTTP/1.0, the sender MUST
   include in each corresponding warning-value a warn-date that matches
   the Date header field in the message.  For example:

     HTTP/1.1 200 OK
     Date: Sat, 25 Aug 2012 23:34:45 GMT
     Warning: 112 - "network down" "Sat, 25 Aug 2012 23:34:45 GMT"

Fielding, et al.         Expires January 3, 2019               [Page 32]
Internet-Draft                HTTP Caching                     July 2018

   Warnings have accompanying warn-text that describes the error, e.g.,
   for logging.  It is advisory only, and its content does not affect
   interpretation of the warn-code.

   If a recipient that uses, evaluates, or displays Warning header
   fields receives a warn-date that is different from the Date value in
   the same message, the recipient MUST exclude the warning-value
   containing that warn-date before storing, forwarding, or using the
   message.  This allows recipients to exclude warning-values that were
   improperly retained after a cache validation.  If all of the warning-
   values are excluded, the recipient MUST exclude the Warning header
   field as well.

   The following warn-codes are defined by this specification, each with
   a recommended warn-text in English, and a description of its meaning.
   The procedure for defining additional warn codes is described in
   Section 5.5.8.

   +-----------+----------------------------------+----------------+
   | Warn Code | Short Description                | Reference      |
   +-----------+----------------------------------+----------------+
   | 110       | Response is Stale                | Section 5.5.1  |
   | 111       | Revalidation Failed              | Section 5.5.2  |
   | 112       | Disconnected Operation           | Section 5.5.3  |
   | 113       | Heuristic Expiration             | Section 5.5.4  |
   | 199       | Miscellaneous Warning            | Section 5.5.5  |
   | 214       | Transformation Applied           | Section 5.5.6  |
   | 299       | Miscellaneous Persistent Warning | Section 5.5.7  |
   +-----------+----------------------------------+----------------+

5.5.1.  Warning: 110 - "Response is Stale"

   A cache SHOULD generate this whenever the sent response is stale.

5.5.2.  Warning: 111 - "Revalidation Failed"

   A cache SHOULD generate this when sending a stale response because an
   attempt to validate the response failed, due to an inability to reach
   the server.

5.5.3.  Warning: 112 - "Disconnected Operation"

   A cache SHOULD generate this if it is intentionally disconnected from
   the rest of the network for a period of time.

Fielding, et al.         Expires January 3, 2019               [Page 33]
Internet-Draft                HTTP Caching                     July 2018

5.5.4.  Warning: 113 - "Heuristic Expiration"

   A cache SHOULD generate this if it heuristically chose a freshness
   lifetime greater than 24 hours and the response's age is greater than
   24 hours.

5.5.5.  Warning: 199 - "Miscellaneous Warning"

   The warning text can include arbitrary information to be presented to
   a human user or logged.  A system receiving this warning MUST NOT
   take any automated action, besides presenting the warning to the
   user.

5.5.6.  Warning: 214 - "Transformation Applied"

   This Warning code MUST be added by a proxy if it applies any
   transformation to the representation, such as changing the content-
   coding, media-type, or modifying the representation data, unless this
   Warning code already appears in the response.

5.5.7.  Warning: 299 - "Miscellaneous Persistent Warning"

   The warning text can include arbitrary information to be presented to
   a human user or logged.  A system receiving this warning MUST NOT
   take any automated action.

5.5.8.  Warn Code Registry

   The "Hypertext Transfer Protocol (HTTP) Warn Codes" registry defines
   the namespace for warn codes.  It has been created and is now
   maintained at <https://www.iana.org/assignments/http-warn-codes>.

   A registration MUST include the following fields:

   o  Warn Code (3 digits)

   o  Short Description

   o  Pointer to specification text

   Values to be added to this namespace require IETF Review (see
   [RFC8126], Section 4.8).

6.  History Lists

   User agents often have history mechanisms, such as "Back" buttons and
   history lists, that can be used to redisplay a representation
   retrieved earlier in a session.

Fielding, et al.         Expires January 3, 2019               [Page 34]
Internet-Draft                HTTP Caching                     July 2018

   The freshness model (Section 4.2) does not necessarily apply to
   history mechanisms.  That is, a history mechanism can display a
   previous representation even if it has expired.

   This does not prohibit the history mechanism from telling the user
   that a view might be stale or from honoring cache directives (e.g.,
   Cache-Control: no-store).

7.  Security Considerations

   This section is meant to inform developers, information providers,
   and users of known security concerns specific to HTTP caching.  More
   general security considerations are addressed in HTTP messaging
   [Messaging] and semantics [Semantics].

   Caches expose additional potential vulnerabilities, since the
   contents of the cache represent an attractive target for malicious
   exploitation.  Because cache contents persist after an HTTP request
   is complete, an attack on the cache can reveal information long after
   a user believes that the information has been removed from the
   network.  Therefore, cache contents need to be protected as sensitive
   information.

   In particular, various attacks might be amplified by being stored in
   a shared cache; such "cache poisoning" attacks use the cache to
   distribute a malicious payload to many clients, and are especially
   effective when an attacker can use implementation flaws, elevated
   privileges, or other techniques to insert such a response into a
   cache.  One common attack vector for cache poisoning is to exploit
   differences in message parsing on proxies and in user agents; see
   Section 6.3 of [Messaging] for the relevant requirements.

   Likewise, implementation flaws (as well as misunderstanding of cache
   operation) might lead to caching of sensitive information (e.g.,
   authentication credentials) that is thought to be private, exposing
   it to unauthorized parties.

   Furthermore, the very use of a cache can bring about privacy
   concerns.  For example, if two users share a cache, and the first one
   browses to a site, the second may be able to detect that the other
   has been to that site, because the resources from it load more
   quickly, thanks to the cache.

   Note that the Set-Cookie response header field [RFC6265] does not
   inhibit caching; a cacheable response with a Set-Cookie header field
   can be (and often is) used to satisfy subsequent requests to caches.
   Servers who wish to control caching of these responses are encouraged
   to emit appropriate Cache-Control response header fields.

Fielding, et al.         Expires January 3, 2019               [Page 35]
Internet-Draft                HTTP Caching                     July 2018

8.  IANA Considerations

   The change controller for the following registrations is: "IETF
   (iesg@ietf.org) - Internet Engineering Task Force".

8.1.  Header Field Registration

   Please update the "Message Headers" registry of "Permanent Message
   Header Field Names" at <https://www.iana.org/assignments/message-
   headers> with the header field names listed in the table of
   Section 5.

8.2.  Cache Directive Registration

   Please update the "Hypertext Transfer Protocol (HTTP) Cache Directive
   Registry" at <https://www.iana.org/assignments/http-cache-directives>
   with the registration procedure of Section 5.2.4 and the cache
   directive names summarized in the table of Section 5.2.

8.3.  Warn Code Registration

   Please update the "Hypertext Transfer Protocol (HTTP) Warn Codes"
   registry at <https://www.iana.org/assignments/http-warn-codes> with
   the registration procedure of Section 5.5.8 and the warn code values
   summarized in the table of Section 5.5.

9.  References

9.1.  Normative References

   [Messaging]
              Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP/1.1 Messaging", draft-ietf-httpbis-messaging-02
              (work in progress), July 2018.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, DOI 10.17487/RFC3986, January 2005,
              <https://www.rfc-editor.org/info/rfc3986>.

Fielding, et al.         Expires January 3, 2019               [Page 36]
Internet-Draft                HTTP Caching                     July 2018

   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", STD 68, RFC 5234,
              DOI 10.17487/RFC5234, January 2008,
              <https://www.rfc-editor.org/info/rfc5234>.

   [Semantics]
              Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP Semantics", draft-ietf-httpbis-semantics-02
              (work in progress), July 2018.

   [USASCII]  American National Standards Institute, "Coded Character
              Set -- 7-bit American Standard Code for Information
              Interchange", ANSI X3.4, 1986.

9.2.  Informative References

   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
              Transfer Protocol -- HTTP/1.1", RFC 2616,
              DOI 10.17487/RFC2616, June 1999,
              <https://www.rfc-editor.org/info/rfc2616>.

   [RFC5861]  Nottingham, M., "HTTP Cache-Control Extensions for Stale
              Content", RFC 5861, DOI 10.17487/RFC5861, April 2010,
              <https://www.rfc-editor.org/info/rfc5861>.

   [RFC5905]  Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch,
              "Network Time Protocol Version 4: Protocol and Algorithms
              Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010,
              <https://www.rfc-editor.org/info/rfc5905>.

   [RFC6265]  Barth, A., "HTTP State Management Mechanism", RFC 6265,
              DOI 10.17487/RFC6265, April 2011,
              <https://www.rfc-editor.org/info/rfc6265>.

   [RFC7234]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "Hypertext Transfer Protocol (HTTP): Caching",
              RFC 7234, DOI 10.17487/RFC7234, June 2014,
              <https://www.rfc-editor.org/info/rfc7234>.

   [RFC8126]  Cotton, M., Leiba, B., and T. Narten, "Guidelines for
              Writing an IANA Considerations Section in RFCs", BCP 26,
              RFC 8126, DOI 10.17487/RFC8126, June 2017,
              <https://www.rfc-editor.org/info/rfc8126>.

Fielding, et al.         Expires January 3, 2019               [Page 37]
Internet-Draft                HTTP Caching                     July 2018

Appendix A.  Collected ABNF

   In the collected ABNF below, list rules are expanded as per
   Section 11 of [Semantics].

   Age = delta-seconds

   Cache-Control = *( "," OWS ) cache-directive *( OWS "," [ OWS
    cache-directive ] )

   Expires = HTTP-date

   HTTP-date = <HTTP-date, see [Semantics], Section 10.1.1.1>

   OWS = <OWS, see [Semantics], Section 4.3>

   Pragma = *( "," OWS ) pragma-directive *( OWS "," [ OWS
    pragma-directive ] )

   Warning = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value ]
    )

   cache-directive = token [ "=" ( token / quoted-string ) ]

   delta-seconds = 1*DIGIT

   extension-pragma = token [ "=" ( token / quoted-string ) ]

   field-name = <field-name, see [Semantics], Section 4.2>

   port = <port, see [RFC3986], Section 3.2.3>
   pragma-directive = "no-cache" / extension-pragma
   pseudonym = <pseudonym, see [Semantics], Section 5.6.1>

   quoted-string = <quoted-string, see [Semantics], Section 4.2.3>

   token = <token, see [Semantics], Section 4.2.3>

   uri-host = <host, see [RFC3986], Section 3.2.2>

   warn-agent = ( uri-host [ ":" port ] ) / pseudonym
   warn-code = 3DIGIT
   warn-date = DQUOTE HTTP-date DQUOTE
   warn-text = quoted-string
   warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date
    ]

Fielding, et al.         Expires January 3, 2019               [Page 38]
Internet-Draft                HTTP Caching                     July 2018

Appendix B.  Changes from RFC 7234

   None yet.

Appendix C.  Change Log

   This section is to be removed before publishing as an RFC.

C.1.  Between RFC7234 and draft 00

   The changes were purely editorial:

   o  Change boilerplate and abstract to indicate the "draft" status,
      and update references to ancestor specifications.

   o  Remove version "1.1" from document title, indicating that this
      specification applies to all HTTP versions.

   o  Adjust historical notes.

   o  Update links to sibling specifications.

   o  Replace sections listing changes from RFC 2616 by new empty
      sections referring to RFC 723x.

   o  Remove acknowledgements specific to RFC 723x.

   o  Move "Acknowledgements" to the very end and make them unnumbered.

C.2.  Since draft-ietf-httpbis-cache-00

   The changes are purely editorial:

   o  Moved all extensibility tips, registration procedures, and
      registry tables from the IANA considerations to normative
      sections, reducing the IANA considerations to just instructions
      that will be removed prior to publication as an RFC.

C.3.  Since draft-ietf-httpbis-cache-01

   o  Cite RFC 8126 instead of RFC 5226 (<https://github.com/httpwg/
      http-core/issues/75>)

   o  In Section 5.4, misleading statement about the relation between
      Pragma and Cache-Control (<https://github.com/httpwg/http-core/
      issues/92>, <https://www.rfc-editor.org/errata/eid4674>)

Fielding, et al.         Expires January 3, 2019               [Page 39]
Internet-Draft                HTTP Caching                     July 2018

Index

   1
      110 (warn-code)  33
      111 (warn-code)  33
      112 (warn-code)  33
      113 (warn-code)  34
      199 (warn-code)  34

   2
      214 (warn-code)  34
      299 (warn-code)  34

   A
      Age header field  21
      age  11

   C
      Cache-Control header field  22
      cache  4
      cache entry  6
      cache key  6

   D
      Disconnected Operation (warn-text)  33

   E
      Expires header field  29
      explicit expiration time  11

   F
      fresh  11
      freshness lifetime  11

   G
      Grammar
         Age  21
         ALPHA  5
         Cache-Control  22
         cache-directive  22
         CR  5
         CRLF  5
         CTL  5
         delta-seconds  5
         DIGIT  5
         DQUOTE  5
         Expires  30
         extension-pragma  31

Fielding, et al.         Expires January 3, 2019               [Page 40]
Internet-Draft                HTTP Caching                     July 2018

         HEXDIG  5
         HTAB  5
         LF  5
         OCTET  5
         Pragma  31
         pragma-directive  31
         SP  5
         VCHAR  5
         warn-agent  32
         warn-code  32
         warn-date  32
         warn-text  32
         Warning  32
         warning-value  32

   H
      Heuristic Expiration (warn-text)  34
      heuristic expiration time  11

   M
      Miscellaneous Persistent Warning (warn-text)  34
      Miscellaneous Warning (warn-text)  34
      max-age (cache directive)  23, 28
      max-stale (cache directive)  23
      min-fresh (cache directive)  24
      must-revalidate (cache directive)  25

   N
      no-cache (cache directive)  24-25
      no-store (cache directive)  24, 26
      no-transform (cache directive)  25-26

   O
      only-if-cached (cache directive)  25

   P
      Pragma header field  30
      private (cache directive)  27
      private cache  4
      proxy-revalidate (cache directive)  27
      public (cache directive)  27

   R
      Response is Stale (warn-text)  33
      Revalidation Failed (warn-text)  33

   S
      s-maxage (cache directive)  28

Fielding, et al.         Expires January 3, 2019               [Page 41]
Internet-Draft                HTTP Caching                     July 2018

      shared cache  4
      stale  11
      strong validator  19

   T
      Transformation Applied (warn-text)  34

   V
      validator  16

   W
      Warning header field  31

Acknowledgments

   See Appendix "Acknowledgments" of [Semantics].

Authors' Addresses

   Roy T. Fielding (editor)
   Adobe
   345 Park Ave
   San Jose, CA  95110
   USA

   EMail: fielding@gbiv.com
   URI:   https://roy.gbiv.com/

   Mark Nottingham (editor)
   Fastly

   EMail: mnot@mnot.net
   URI:   https://www.mnot.net/

   Julian F. Reschke (editor)
   greenbytes GmbH
   Hafenweg 16
   Muenster, NW  48155
   Germany

   EMail: julian.reschke@greenbytes.de
   URI:   https://greenbytes.de/tech/webdav/

Fielding, et al.         Expires January 3, 2019               [Page 42]