| HTTPbis Working Group | R. Fielding, Editor |
| Internet-Draft | Adobe |
| Obsoletes:2616 (if approved) | M. Nottingham, Editor |
| Intended status: Standards Track | Akamai |
| Expires: January 16, 2014 | J. Reschke, Editor |
| greenbytes | |
| July 15, 2013 |
The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypertext information systems. This document defines requirements on HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is athttp://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress”.¶
This Internet-Draft will expire on January 16, 2014.¶
Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English.¶
Discussion of this draft takes place on the HTTPBIS working group mailing list (ietf-http-wg@w3.org), which is archived at <http://lists.w3.org/Archives/Public/ietf-http-wg/>.¶
The current issues list is at <http://tools.ietf.org/wg/httpbis/trac/report/3> and related documents (including fancy diffs) can be found at <http://tools.ietf.org/wg/httpbis/>.¶
The changes in this draft are summarized inAppendix D.4.¶
HTTP is typically used for distributed information systems, where performance can be improved by the use of response caches. This document defines aspects of HTTP/1.1 related to caching and reusing response messages.¶
An HTTPcache is a local store of response messages and the subsystem that controls storage, retrieval, and deletion of messages in it. A cache stores cacheable responses in order to reduce the response time and network bandwidth consumption on future, equivalent requests. Any client or serverMAY employ a cache, though a cache cannot be used by a server that is acting as a tunnel.¶
Ashared cache is a cache that stores responses to be reused by more than one user; shared caches are usually (but not always) deployed as a part of an intermediary. Aprivate cache, in contrast, is dedicated to a single user.¶
The goal of caching in HTTP/1.1 is to significantly improve performance by reusing a prior response message to satisfy a current request. A stored response is considered "fresh", as defined inSection 4.1, if the response can be reused without "validation" (checking with the origin server to see if the cached response remains valid for this request). A fresh response can therefore reduce both latency and network overhead each time it is reused. When a cached response is not fresh, it might still be reusable if it can be freshened by validation (Section 4.2) or if the origin is unavailable (Section 4.1.4).¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in[RFC2119].¶
Conformance criteria and considerations regarding error handling are defined inSection 2.5 of[Part1].¶
This specification uses the Augmented Backus-Naur Form (ABNF) notation of[RFC5234] with the list rule extension defined inSection 1.2 of[Part1].Appendix B describes rules imported from other documents.Appendix C shows the collected ABNF with the list rule expanded.¶
The delta-seconds rule specifies a non-negative integer, representing time in seconds.¶
delta-seconds = 1*DIGIT
If a cache receives a delta-seconds value larger than the largest positive integer it can represent, or if any of its subsequent calculations overflows, itMUST consider the value to be 2147483648 (231). Recipients parsing a delta-seconds valueMUST use an arithmetic type of at least 31 bits of range, and sendersMUST NOT generate delta-seconds with a value greater than 2147483648.¶
Proper cache operation preserves the semantics of HTTP transfers ([Part2]) while eliminating the transfer of information already held in the cache. Although caching is an entirelyOPTIONAL feature of HTTP, we assume that reusing the cached response is desirable and that such reuse is the default behavior when no requirement or local configuration prevents it. Therefore, HTTP cache requirements are focused on preventing a cache from either storing a non-reusable response or reusing a stored response inappropriately, rather than mandating that caches always store and reuse particular responses.¶
Eachcache entry consists of a cache key and one or more HTTP responses corresponding to prior requests that used the same key. The most common form of cache entry is a successful result of a retrieval request: i.e., a200 (OK) response to a GET request, which contains a representation of the resource identified by the request target (Section 4.3.1 of[Part2]). However, it is also possible to cache permanent redirects, negative results (e.g.,404 (Not Found)), incomplete results (e.g.,206 (Partial Content)), and responses to methods other than GET if the method's definition allows such caching and defines something suitable for use as a cache key.¶
The primarycache key consists of the request method and target URI. However, since HTTP caches in common use today are typically limited to caching responses to GET, many caches simply decline other methods and use only the URI as the primary cache key.¶
If a request target is subject to content negotiation, its cache entry might consist of multiple stored responses, each differentiated by a secondary key for the values of the original request's selecting header fields (Section 4.3).¶
A cacheMUST NOT store a response to any request, unless:¶
Note that any of the requirements listed above can be overridden by a cache-control extension; seeSection 7.2.3.¶
In this context, a cache has "understood" a request method or a response status code if it recognizes it and implements all specified caching-related behavior.¶
Note that, in normal operation, some caches will not store a response that has neither a cache validator nor an explicit expiration time, as such responses are not usually useful to store. However, caches are not prohibited from storing such responses.¶
A response message is considered complete when all of the octets indicated by the message framing ([Part1]) are received prior to the connection being closed. If the request is GET, the response status is200 (OK), and the entire response header block has been received, a cacheMAY store an incomplete response message body if the cache entry is recorded as incomplete. Likewise, a206 (Partial Content) responseMAY be stored as if it were an incomplete200 (OK) cache entry. However, a cacheMUST NOT store incomplete or partial content responses if it does not support theRange andContent-Range header fields or if it does not understand the range units used in those fields.¶
A cacheMAY complete a stored incomplete response by making a subsequent range request ([Part5]) and combining the successful response with the stored entry, as defined inSection 3.3. A cacheMUST NOT use an incomplete response to answer requests unless the response has been made complete or the request is partial and specifies a range that is wholly within the incomplete response. A cacheMUST NOT send a partial response to a client without explicitly marking it as such using the206 (Partial Content) status code.¶
A shared cacheMUST NOT use a cached response to a request with anAuthorization header field (Section 4.1 of[Part7]) to satisfy any subsequent request unless a cache directive that allows such responses to be stored is present in the response.¶
In this specification, the followingCache-Control response directives (Section 7.2.2) have such an effect: must-revalidate, public, s-maxage.¶
Note that cached responses that contain the "must-revalidate" and/or "s-maxage" response directives are not allowed to be served stale (Section 4.1.4) by shared caches. In particular, a response with either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to satisfy a subsequent request without revalidating it on the origin server.¶
A response might transfer only a partial representation if the connection closed prematurely or if the request used one or more Range specifiers ([Part5]). After several such transfers, a cache might have received several ranges of the same representation. A cacheMAY combine these ranges into a single stored response, and reuse that response to satisfy later requests, if they all share the same strong validator and the cache complies with the client requirements inSection 4.3 of[Part5].¶
When combining the new response with one or more stored responses, a cacheMUST:¶
When presented with a request, a cacheMUST NOT reuse a stored response, unless:¶
Note that any of the requirements listed above can be overridden by a cache-control extension; seeSection 7.2.3.¶
When a stored response is used to satisfy a request without validation, a cacheMUST generate anAge header field (Section 7.1), replacing any present in the response with a value equal to the stored response's current_age; seeSection 4.1.3.¶
A cacheMUST write through requests with methods that are unsafe (Section 4.2.1 of[Part2]) to the origin server; i.e., a cache is not allowed to generate a reply to such a request before having forwarded the request and having received a corresponding response.¶
When more than one suitable response is stored, a cacheMUST use the most recent response (as determined by theDate header field). It can also forward the request with "Cache-Control: max-age=0" or "Cache-Control: no-cache" to disambiguate which response to use.¶
A cache that does not have a clock availableMUST NOT use stored responses without revalidating them upon every use.¶
Afresh response is one whose age has not yet exceeded its freshness lifetime. Conversely, astale response is one where it has.¶
A response'sfreshness lifetime is the length of time between its generation by the origin server and its expiration time. Anexplicit expiration time is the time at which the origin server intends that a stored response can no longer be used by a cache without further validation, whereas aheuristic expiration time is assigned by a cache when no explicit expiriation time is available.¶
A response'sage is the time that has passed since it was generated by, or successfully validated with, the origin server.¶
When a response is "fresh" in the cache, it can be used to satisfy subsequent requests without contacting the origin server, thereby improving efficiency.¶
The primary mechanism for determining freshness is for an origin server to provide an explicit expiration time in the future, using either theExpires header field (Section 7.3) or the max-age response cache directive (Section 7.2.2.8). Generally, origin servers will assign future explicit expiration times to responses in the belief that the representation is not likely to change in a semantically significant way before the expiration time is reached.¶
If an origin server wishes to force a cache to validate every request, it can assign an explicit expiration time in the past to indicate that the response is already stale. Compliant caches will normally validate a stale cached response before reusing it for subsequent requests (seeSection 4.1.4).¶
Since origin servers do not always provide explicit expiration times, caches are also allowed to use a heuristic to determine an expiration time under certain circumstances (seeSection 4.1.2).¶
The calculation to determine if a response is fresh is:
response_is_fresh = (freshness_lifetime > current_age)
freshness_lifetime is defined inSection 4.1.1; current_age is defined inSection 4.1.3.¶
Clients can send the max-age or min-fresh cache directives in a request to constrain or relax freshness calculations for the corresponding response (Section 7.2.1).¶
When calculating freshness, to avoid common problems in date parsing:¶
Note that freshness applies only to cache operation; it cannot be used to force a user agent to refresh its display or reload a resource. SeeSection 8 for an explanation of the difference between caches and history mechanisms.¶
A cache can calculate the freshness lifetime (denoted as freshness_lifetime) of a response by using the first match of:¶
Note that this calculation is not vulnerable to clock skew, since all of the information comes from the origin server.¶
Since origin servers do not always provide explicit expiration times, a cacheMAY assign a heuristic expiration time when an explicit time is not specified, employing algorithms that use other header field values (such as theLast-Modified time) to estimate a plausible expiration time. This specification does not provide specific algorithms, but does impose worst-case constraints on their results.¶
A cacheMUST NOT use heuristics to determine freshness when an explicit expiration time is present in the stored response. Because of the requirements inSection 3, this means that, effectively, heuristics can only be used on responses without explicit freshness whose status codes are defined as cacheable, and responses without explicit freshness that have been marked as explicitly cacheable (e.g., with a "public" response cache directive).¶
If the response has aLast-Modified header field (Section 2.2 of[Part4]), caches are encouraged to use a heuristic expiration value that is no more than some fraction of the interval since that time. A typical setting of this fraction might be 10%.¶
When a heuristic is used to calculate freshness lifetime, a cacheSHOULD attach aWarning header field with a 113 warn-code to the response if its current_age is more than 24 hours and such a warning is not already present.¶
Note:Section 13.9 of[RFC2616] prohibited caches from calculating heuristic freshness for URIs with query components (i.e., those containing '?'). In practice, this has not been widely implemented. Therefore, origin servers are encouraged to send explicit directives (e.g., Cache-Control: no-cache) if they wish to preclude caching.¶
TheAge header field is used to convey an estimated age of the response message when obtained from a cache. The Age field value is the cache's estimate of the number of seconds since the response was generated or validated by the origin server. In essence, the Age value is the sum of the time that the response has been resident in each of the caches along the path from the origin server, plus the amount of time it has been in transit along network paths.¶
The following data is used for the age calculation:¶
age_value¶
date_value¶
now¶
request_time¶
response_time¶
A response's age can be calculated in two entirely independent ways:¶
apparent_age = max(0, response_time - date_value); response_delay = response_time - request_time; corrected_age_value = age_value + response_delay;
These are combined as
corrected_initial_age = max(apparent_age, corrected_age_value);
unless the cache is confident in the value of theAge header field (e.g., because there are no HTTP/1.0 hops in theVia header field), in which case the corrected_age_valueMAY be used as the corrected_initial_age.¶
The current_age of a stored response can then be calculated by adding the amount of time (in seconds) since the stored response was last validated by the origin server to the corrected_initial_age.¶
resident_time = now - response_time; current_age = corrected_initial_age + resident_time;
A "stale" response is one that either has explicit expiry information or is allowed to have heuristic expiry calculated, but is not fresh according to the calculations inSection 4.1.¶
A cacheMUST NOT generate a stale response if it is prohibited by an explicit in-protocol directive (e.g., by a "no-store" or "no-cache" cache directive, a "must-revalidate" cache-response-directive, or an applicable "s-maxage" or "proxy-revalidate" cache-response-directive; seeSection 7.2.2).¶
A cacheMUST NOT send stale responses unless it is disconnected (i.e., it cannot contact the origin server or otherwise find a forward path) or doing so is explicitly allowed (e.g., by the max-stale request directive; seeSection 7.2.1).¶
A cacheSHOULD append aWarning header field with the 110 warn-code (seeSection 7.5) to stale responses. Likewise, a cacheSHOULD add the 112 warn-code to stale responses if the cache is disconnected.¶
Note that if a cache receives afirst-hand response (one where the freshness model is not in use; i.e., its age is 0, whether it is an entire response, or a304 (Not Modified) response) that it would normally forward to the requesting client, and the received response is no longer fresh, the cacheMAY forward it to the requesting client without adding a newWarning (but without removing any existing Warning header fields). A cache ought not attempt to validate a response simply because that response became stale in transit.¶
When a cache has one or more stored responses for a requested URI, but cannot serve any of them (e.g., because they are not fresh, or one cannot be selected; seeSection 4.3), it can use the conditional request mechanism[Part4] in the forwarded request to give the origin server an opportunity to both select a valid stored response to be used, and to update it. This process is known as "validating" or "revalidating" the stored response.¶
When sending such a conditional request, a cache adds avalidator (or more than one), that is used to find out whether a stored response is an equivalent copy of a current representation of the resource.¶
One such validator is theIf-Modified-Since header field, whose value is that of theLast-Modified header field from the selected (seeSection 4.3) stored response, if available.¶
Another is theIf-None-Match header field, whose value is that of theETag header field(s) from relevant responses stored for the primary cache key, if present. However, if any of the stored responses contains only partial content, the cache ought not include its entity-tag in the If-None-Match header field unless the request is for a range that would be fully satisfied by that stored response.¶
Cache handling of a response to a conditional request is dependent upon its status code:¶
When a cache receives a304 (Not Modified) response and already has one or more stored200 (OK) responses for the same cache key, the cache needs to identify which of the stored responses are updated by this new response and then update the stored response(s) with the new information provided in the304 response.¶
The stored response to update is identified by using the first match (if any) of:¶
If a stored response is selected for update, the cacheMUST:¶
When a cache receives a request that can be satisfied by a stored response that has aVary header field (Section 7.1.4 of[Part2]), itMUST NOT use that response unless all of the selecting header fields nominated by the Vary header field match in both the original request (i.e., that associated with the stored response), and the presented request.¶
The selecting header fields from two requests are defined to match if and only if those in the first request can be transformed to those in the second request by applying any of the following:¶
If (after any normalization that might take place) a header field is absent from a request, it can only match another request if it is also absent there.¶
The stored response with matching selecting header fields is known as the selected response.¶
If multiple selected responses are available (potentially including responses without a Vary header field), the cache will need to choose one to use. When a selecting header field has a known mechanism for doing so (e.g., qvalues onAccept and similar request header fields), that mechanismMAY be used to select preferred responses; of the remainder, the most recent response (as determined by theDate header field) is used, as perSection 4.¶
If no selected response is available, the cache cannot satisfy the presented request. Typically, it is forwarded to the origin server in a (possibly conditional; seeSection 4.2) request.¶
A response to the HEAD method is identical to what an equivalent request made with a GET would have been, except it lacks a body. This property of HEAD responses is used to both invalidate and update cached GET responses.¶
If one or more stored GET responses can be selected (as perSection 4.3) for a HEAD request, and theContent-Length,ETag orLast-Modified value of a HEAD response differs from that in a selected GET response, the cacheMUST consider that selected response to be stale.¶
If theContent-Length,ETag andLast-Modified values of a HEAD response (when present) are the same as that in a selected GET response (as perSection 4.3), the cacheSHOULD update the remaining header fields in the stored response using the following rules:¶
Because unsafe request methods (Section 4.2.1 of[Part2]) such as PUT, POST or DELETE have the potential for changing state on the origin server, intervening caches can use them to keep their contents up-to-date.¶
A cacheMUST invalidate the effective Request URI (Section 5.5 of[Part1]) as well as the URI(s) in theLocation andContent-Location response header fields (if present) when a non-error response to a request with an unsafe method is received.¶
However, a cacheMUST NOT invalidate a URI from aLocation orContent-Location response header field if the host part of that URI differs from the host part in the effective request URI (Section 5.5 of[Part1]). This helps prevent denial of service attacks.¶
A cacheMUST invalidate the effective request URI (Section 5.5 of[Part1]) when it receives a non-error response to a request with a method whose safety is unknown.¶
Here, a "non-error response" is one with a2xx (Successful) or3xx (Redirection) status code. "Invalidate" means that the cache will either remove all stored responses related to the effective request URI, or will mark these as "invalid" and in need of a mandatory validation before they can be sent in response to a subsequent request.¶
Note that this does not guarantee that all appropriate responses are invalidated. For example, a state-changing request might invalidate responses in the caches it travels through, but relevant responses still might be stored in other caches that it has not.¶
This section defines the syntax and semantics of HTTP/1.1 header fields related to caching.¶
The "Age" header field conveys the sender's estimate of the amount of time since the response was generated or successfully validated at the origin server. Age values are calculated as specified inSection 4.1.3.¶
Age field-values are non-negative integers, representing time in seconds (seeSection 1.2.1).¶
The presence of an Age header field in a response implies that a response is not first-hand. However, the converse is not true, since HTTP/1.0 caches might not implement the Age header field.¶
The "Cache-Control" header field is used to specify directives for caches along the request/response chain. Such cache directives are unidirectional in that the presence of a directive in a request does not imply that the same directive is to be given in the response.¶
A cacheMUST obey the requirements of the Cache-Control directives defined in this section. SeeSection 7.2.3 for information about how Cache-Control directives defined elsewhere are handled.¶
A proxy, whether or not it implements a cache,MUST pass cache directives through in forwarded messages, regardless of their significance to that application, since the directives might be applicable to all recipients along the request/response chain. It is not possible to target a directive to a specific cache.¶
Cache directives are identified by a token, to be compared case-insensitively, and have an optional argument, that can use both token and quoted-string syntax. For the directives defined below that define arguments, recipients ought to accept both forms, even if one is documented to be preferred. For any directive not defined by this specification, recipientsMUST accept both forms.¶
Cache-Control = 1#cache-directivecache-directive =token [ "=" (token /quoted-string ) ]
For the cache directives defined below, no argument is defined (nor allowed) unless stated otherwise.¶
Argument syntax:¶
The "max-age" request directive indicates that the client is unwilling to accept a response whose age is greater than the specified number of seconds. Unless the max-stale request directive is also present, the client is not willing to accept a stale response.¶
Note: This directive uses the token form of the argument syntax; e.g., 'max-age=5', not 'max-age="5"'. SendersSHOULD NOT use the quoted-string form.¶
Argument syntax:¶
The "max-stale" request directive indicates that the client is willing to accept a response that has exceeded its freshness lifetime. If max-stale is assigned a value, then the client is willing to accept a response that has exceeded its freshness lifetime by no more than the specified number of seconds. If no value is assigned to max-stale, then the client is willing to accept a stale response of any age.¶
Note: This directive uses the token form of the argument syntax; e.g., 'max-stale=10', not 'max-stale="10"'. SendersSHOULD NOT use the quoted-string form.¶
Argument syntax:¶
The "min-fresh" request directive indicates that the client is willing to accept a response whose freshness lifetime is no less than its current age plus the specified time in seconds. That is, the client wants a response that will still be fresh for at least the specified number of seconds.¶
Note: This directive uses the token form of the argument syntax; e.g., 'min-fresh=20', not 'min-fresh="20"'. SendersSHOULD NOT use the quoted-string form.¶
The "no-cache" request directive indicates that a cacheMUST NOT use a stored response to satisfy the request without successful validation on the origin server.¶
The "no-store" request directive indicates that a cacheMUST NOT store any part of either this request or any response to it. This directive applies to both private and shared caches. "MUST NOT store" in this context means that the cacheMUST NOT intentionally store the information in non-volatile storage, andMUST make a best-effort attempt to remove the information from volatile storage as promptly as possible after forwarding it.¶
This directive is NOT a reliable or sufficient mechanism for ensuring privacy. In particular, malicious or compromised caches might not recognize or obey this directive, and communications networks might be vulnerable to eavesdropping.¶
Note that if a request containing this directive is satisfied from a cache, the no-store request directive does not apply to the already stored response.¶
The "no-transform" request directive indicates that an intermediary (whether or not it implements a cache)MUST NOT transform the payload, as defined inSection 5.7.2 of[Part1].¶
The "only-if-cached" request directive indicates that the client only wishes to obtain a stored response. If it receives this directive, a cacheSHOULD either respond using a stored response that is consistent with the other constraints of the request, or respond with a504 (Gateway Timeout) status code. If a group of caches is being operated as a unified system with good internal connectivity, a member cacheMAY forward such a request within that group of caches.¶
The "must-revalidate" response directive indicates that once it has become stale, a cacheMUST NOT use the response to satisfy subsequent requests without successful validation on the origin server.¶
The must-revalidate directive is necessary to support reliable operation for certain protocol features. In all circumstances a cacheMUST obey the must-revalidate directive; in particular, if a cache cannot reach the origin server for any reason, itMUST generate a504 (Gateway Timeout) response.¶
The must-revalidate directive ought to be used by servers if and only if failure to validate a request on the representation could result in incorrect operation, such as a silently unexecuted financial transaction.¶
Argument syntax:¶
The "no-cache" response directive indicates that the responseMUST NOT be used to satisfy a subsequent request without successful validation on the origin server. This allows an origin server to prevent a cache from using it to satisfy a request without contacting it, even by caches that have been configured to send stale responses.¶
If the no-cache response directive specifies one or more field-names, then a cacheMAY use the response to satisfy a subsequent request, subject to any other restrictions on caching. However, any header fields in the response that have the field-name(s) listedMUST NOT be sent in the response to a subsequent request without successful revalidation with the origin server. This allows an origin server to prevent the re-use of certain header fields in a response, while still allowing caching of the rest of the response.¶
The field-names given are not limited to the set of header fields defined by this specification. Field names are case-insensitive.¶
Note: Although it has been back-ported to many implementations, some HTTP/1.0 caches will not recognize or obey this directive. Also, no-cache response directives with field-names are often handled by caches as if an unqualified no-cache directive was received; i.e., the special handling for the qualified form is not widely implemented.¶
Note: This directive uses the quoted-string form of the argument syntax. SendersSHOULD NOT use the token form (even if quoting appears not to be needed for single-entry lists).¶
The "no-store" response directive indicates that a cacheMUST NOT store any part of either the immediate request or response. This directive applies to both private and shared caches. "MUST NOT store" in this context means that the cacheMUST NOT intentionally store the information in non-volatile storage, andMUST make a best-effort attempt to remove the information from volatile storage as promptly as possible after forwarding it.¶
This directive is NOT a reliable or sufficient mechanism for ensuring privacy. In particular, malicious or compromised caches might not recognize or obey this directive, and communications networks might be vulnerable to eavesdropping.¶
The "no-transform" response directive indicates that an intermediary (regardless of whether it implements a cache)MUST NOT transform the payload, as defined inSection 5.7.2 of[Part1].¶
The "public" response directive indicates that any cacheMAY store the response, even if the response would normally be non-cacheable or cacheable only within a non-shared cache. (SeeSection 3.2 for additional details related to the use of public in response to a request containingAuthorization, andSection 3 for details of how public affects responses that would normally not be stored, due to their status codes not being defined as cacheable.)¶
Argument syntax:¶
The "private" response directive indicates that the response message is intended for a single user andMUST NOT be stored by a shared cache. A private cacheMAY store the response and reuse it for later requests, even if the response would normally be non-cacheable.¶
If the private response directive specifies one or more field-names, this requirement is limited to the field-values associated with the listed response header fields. That is, a shared cacheMUST NOT store the specified field-names(s), whereas itMAY store the remainder of the response message.¶
The field-names given are not limited to the set of header fields defined by this specification. Field names are case-insensitive.¶
Note: This usage of the word "private" only controls where the response can be stored; it cannot ensure the privacy of the message content. Also, private response directives with field-names are often handled by caches as if an unqualified private directive was received; i.e., the special handling for the qualified form is not widely implemented.¶
Note: This directive uses the quoted-string form of the argument syntax. SendersSHOULD NOT use the token form (even if quoting appears not to be needed for single-entry lists).¶
The "proxy-revalidate" response directive has the same meaning as the must-revalidate response directive, except that it does not apply to private caches.¶
Argument syntax:¶
The "max-age" response directive indicates that the response is to be considered stale after its age is greater than the specified number of seconds.¶
Note: This directive uses the token form of the argument syntax; e.g., 'max-age=5', not 'max-age="5"'. SendersSHOULD NOT use the quoted-string form.¶
Argument syntax:¶
The "s-maxage" 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 theExpires header field. The s-maxage directive also implies the semantics of the proxy-revalidate response directive.¶
Note: This directive uses the token form of the argument syntax; e.g., 's-maxage=10', not 's-maxage="10"'. SendersSHOULD NOT use the quoted-string form.¶
The Cache-Control header field can be extended through the use of one or more cache-extension tokens, each with an optional value.¶
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 standard directive are supplied, such that applications that do not understand the new directive will default to the behavior specified by the standard directive, and those that understand the new directive will recognize it as modifying the requirements associated with the standard directive. In this way, extensions to the cache-control directives can be made without requiring changes to the base protocol.¶
This extension mechanism depends on an HTTP cache obeying all of the cache-control directives defined for its native HTTP-version, obeying certain extensions, and ignoring all directives that it does not understand.¶
For example, consider a hypothetical new response directive called "community" that acts as a modifier to the private directive. We define this new directive to mean that, in addition to any private cache, any cache that is shared only by members of the community named within its value 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 seeing this header field will act correctly even if the cache does not understand the community cache-extension, since it will also see and understand the private directive and thus default to the safe behavior.¶
A cacheMUST ignore unrecognized cache directives; it is assumed that any cache directive likely to be unrecognized by an HTTP/1.1 cache will be combined with standard directives (or the response's default cacheability) such that the cache behavior will remain minimally correct even if the cache does not understand the extension(s).¶
The "Expires" header field gives the date/time after which the response is considered stale. SeeSection 4.1 for further discussion of the freshness model.¶
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 inSection 7.1.1.1 of[Part2].¶
For example
Expires: Thu, 01 Dec 1994 16:00:00 GMT
A cache recipientMUST interpret invalid date formats, especially the value "0", as representing a time in the past (i.e., "already expired").¶
If a response includes aCache-Control field with the max-age directive (Section 7.2.2.8), a recipientMUST ignore the Expires field. Likewise, if a response includes the s-maxage directive (Section 7.2.2.9), a shared cache recipientMUST 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 clockMUST 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.¶
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 (asCache-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.¶
Pragma = 1#pragma-directivepragma-directive = "no-cache" /extension-pragmaextension-pragma =token [ "=" (token /quoted-string ) ]
When theCache-Control header field is not present in a request, cachesMUST consider the no-cache request pragma-directive as having the same effect as if "Cache-Control: no-cache" were present (seeSection 7.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 otherCache-Control response directives at HTTP/1.1 caches. For example:¶
GET / HTTP/1.1Host: www.example.comCache-Control: max-age=30Pragma: no-cache
will constrain HTTP/1.1 caches to serve a response no older than 30 seconds, while precluding implementations that do not understandCache-Control from serving a cached response.¶
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 message. 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.¶
Warning = 1#warning-valuewarning-value =warn-codeSPwarn-agentSPwarn-text [SPwarn-date]warn-code = 3DIGITwarn-agent = (uri-host [ ":"port ] ) /pseudonym ; the name or pseudonym of the server adding ; the Warning header field, for use in debuggingwarn-text =quoted-stringwarn-date =DQUOTEHTTP-dateDQUOTE
Multiple warnings can be attached to a response (either by the origin server or by a cache), including multiple warnings with the same code number, only differing in warn-text.¶
When this occurs, the user agentSHOULD inform the user of as many of them as possible, in the order that they appear in the response.¶
Systems that generate multiple Warning header fields are encouraged to order them with this user agent behavior in mind. New Warning header fields are added 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:¶
If an implementation sends a message with one or more Warning header fields to a receiver whose version is HTTP/1.0 or lower, then the senderMUST include in each warning-value a warn-date that matches theDate header field in the message.¶
If a system receives a message with a warning-value that includes a warn-date, and that warn-date is different from theDate value in the response, then that warning-valueMUST be deleted from the message before storing, forwarding, or using it. (preventing the consequences of naive caching of Warning header fields.) If all of the warning-values are deleted for this reason, the Warning header fieldMUST be deleted 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.¶
A cacheSHOULD generate this whenever the sent response is stale.¶
A cacheSHOULD generate this when sending a stale response because an attempt to validate the response failed, due to an inability to reach the server.¶
A cacheSHOULD generate this if it is intentionally disconnected from the rest of the network for a period of time.¶
A cacheSHOULD generate this if it heuristically chose a freshness lifetime greater than 24 hours and the response's age is greater than 24 hours.¶
The warning text can include arbitrary information to be presented to a human user, or logged. A system receiving this warningMUST NOT take any automated action, besides presenting the warning to the user.¶
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.¶
The warning text can include arbitrary information to be presented to a human user, or logged. A system receiving this warningMUST NOT take any automated action.¶
Extension warn codes can be defined; seeSection 9.2.1 for details.¶
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.¶
The freshness model (Section 4.1) does not necessarily apply to history mechanisms. I.e., 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).¶
The HTTP Cache Directive Registry defines the name space for the cache directives. It will be created and maintained at <http://www.iana.org/assignments/http-cache-directives>.¶
A registrationMUST include the following fields:¶
Values to be added to this name space require IETF Review (see[RFC5226],Section 4.1).¶
New extension directives ought to consider defining:¶
See alsoSection 7.2.3.¶
The HTTP Cache Directive Registry shall be populated with the registrations below:¶
| Cache Directive | Reference |
|---|---|
| max-age | Section 7.2.1.1,Section 7.2.2.8 |
| max-stale | Section 7.2.1.2 |
| min-fresh | Section 7.2.1.3 |
| must-revalidate | Section 7.2.2.1 |
| no-cache | Section 7.2.1.4,Section 7.2.2.2 |
| no-store | Section 7.2.1.5,Section 7.2.2.3 |
| no-transform | Section 7.2.1.6,Section 7.2.2.4 |
| only-if-cached | Section 7.2.1.7 |
| private | Section 7.2.2.6 |
| proxy-revalidate | Section 7.2.2.7 |
| public | Section 7.2.2.5 |
| s-maxage | Section 7.2.2.9 |
| stale-if-error | [RFC5861],Section 4 |
| stale-while-revalidate | [RFC5861],Section 3 |
The HTTP Warn Code Registry defines the name space for warn codes. It will be created and maintained at <http://www.iana.org/assignments/http-warn-codes>.¶
A registrationMUST include the following fields:¶
Values to be added to this name space require IETF Review (see[RFC5226],Section 4.1).¶
The HTTP Warn Code Registry shall be populated with the registrations below:¶
| Warn Code | Short Description | Reference |
|---|---|---|
| 110 | Response is Stale | Section 7.5.1 |
| 111 | Revalidation Failed | Section 7.5.2 |
| 112 | Disconnected Operation | Section 7.5.3 |
| 113 | Heuristic Expiration | Section 7.5.4 |
| 199 | Miscellaneous Warning | Section 7.5.5 |
| 214 | Transformation Applied | Section 7.5.6 |
| 299 | Miscellaneous Persistent Warning | Section 7.5.7 |
HTTP header fields are registered within the Message Header Field Registry maintained at <http://www.iana.org/assignments/message-headers/message-header-index.html>.¶
This document defines the following HTTP header fields, so their associated registry entries shall be updated according to the permanent registrations below (see[BCP90]):¶
| Header Field Name | Protocol | Status | Reference |
|---|---|---|---|
| Age | http | standard | Section 7.1 |
| Cache-Control | http | standard | Section 7.2 |
| Expires | http | standard | Section 7.3 |
| Pragma | http | standard | Section 7.4 |
| Warning | http | standard | Section 7.5 |
The change controller is: "IETF (iesg@ietf.org) - Internet Engineering Task Force".¶
This section is meant to inform developers, information providers, and users of known security concerns specific to HTTP/1.1 caching. More general security considerations are addressed in HTTP messaging[Part1] and semantics[Part2].¶
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.¶
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.¶
Implementation flaws might allow attackers to insert content into a cache ("cache poisoning"), leading to compromise of clients that trust that content. Because of their nature, these attacks are difficult to mitigate.¶
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.¶
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.¶
Caching-related text has been substantially rewritten for clarity.¶
The algorithm for calculating age is now less conservative. (Section 4.1.3)¶
Caches are now required to handle dates with timezones as if they're invalid, because it's not possible to accurately guess. (Section 4.1.3)¶
TheContent-Location response header field is no longer used to determine the appropriate response to use when validating. (Section 4.2)¶
The algorithm for selecting a cached negotiated response to use has been clarified in several ways. In particular, it now explicitly allows header-specific canonicalization when processing selecting header fields. (Section 4.3)¶
Requirements regarding denial of service attack avoidance when performing invalidation have been clarified. (Section 6)¶
The conditions under which an authenticated response can be cached have been clarified. (Section 3.2)¶
The one-year limit on Expires header field values has been removed; instead, the reasoning for using a sensible value is given. (Section 7.3)¶
The Pragma header field is now only defined for backwards compatibility; future pragmas are deprecated. (Section 7.4)¶
Cache directives are explicitly defined to be case-insensitive. (Section 7.2)¶
Handling of multiple instances of cache directives when only one is expected is now defined. (Section 7.2)¶
The qualified forms of the private and no-cache cache directives are noted to not be widely implemented; e.g., "private=foo" is interpreted by many caches as simply "private". Additionally, the meaning of the qualified form of no-cache has been clarified. (Section 7.2.2)¶
The "no-store" cache request directive doesn't apply to responses; i.e., a cache can satisfy a request with no-store on it, and does not invalidate it. (Section 7.2.1.5)¶
The "no-cache" response cache directive's meaning has been clarified. (Section 7.2.2.2)¶
New status codes can now define that caches are allowed to use heuristic freshness with them. (Section 4.1.2)¶
Caches are now allow to calculate heuristic freshness for URLs with query components. (Section 4.1.2)¶
Some requirements regarding production of theWarning header fields have been relaxed, as it is not widely implemented. Furthermore, theWarning header field no longer uses RFC 2047 encoding, nor allows multiple languages, as these aspects were not implemented. (Section 7.5)¶
This specification introduces the Cache Directive and Warn Code Registries, and defines considerations for new cache directives. (Section 7.2.3 andSection 7.5.8)¶
The following core rules are included by reference, as defined inAppendix B.1 of[RFC5234]: ALPHA (letters), CR (carriage return), CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII character).¶
OWS = <OWS, defined in[Part1],Section 3.2.3>field-name = <field-name, defined in[Part1],Section 3.2>quoted-string = <quoted-string, defined in[Part1],Section 3.2.6>token = <token, defined in[Part1],Section 3.2.6>port = <port, defined in[Part1],Section 2.7>pseudonym = <pseudonym, defined in[Part1],Section 5.7.1>uri-host = <uri-host, defined in[Part1],Section 2.7>
The rules below are defined in other parts:¶
HTTP-date = <HTTP-date, defined in[Part2],Section 7.1.1.1>
In the collected ABNF below, list rules are expanded as perSection 1.2 of[Part1].¶
Age = delta-secondsCache-Control = *( "," OWS ) cache-directive *( OWS "," [ OWS cache-directive ] )Expires = HTTP-dateHTTP-date = <HTTP-date, defined in [Part2], Section 7.1.1.1>OWS = <OWS, defined in [Part1], Section 3.2.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*DIGITextension-pragma = token [ "=" ( token / quoted-string ) ]field-name = <field-name, defined in [Part1], Section 3.2>port = <port, defined in [Part1], Section 2.7>pragma-directive = "no-cache" / extension-pragmapseudonym = <pseudonym, defined in [Part1], Section 5.7.1>quoted-string = <quoted-string, defined in [Part1], Section 3.2.6>token = <token, defined in [Part1], Section 3.2.6>uri-host = <uri-host, defined in [Part1], Section 2.7>warn-agent = ( uri-host [ ":" port ] ) / pseudonymwarn-code = 3DIGITwarn-date = DQUOTE HTTP-date DQUOTEwarn-text = quoted-stringwarning-value = warn-code SP warn-agent SP warn-text [ SP warn-date ]
Changes up to the first Working Group Last Call draft are summarized in <http://trac.tools.ietf.org/html/draft-ietf-httpbis-p6-cache-19#appendix-C>.¶
Closed issues:¶
Closed issues:¶
Other changes:¶
Closed issues:¶
Closed issues:¶