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 |
GENART Last Call review
(of
-16)
by Mohit Sethi
Ready w/nits
|
||
Additional resources | Mailing list discussion | ||
Stream | WG state | WG Document | |
Associated WG milestone |
|
||
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]