rfc9111v1.txt   rfc9111.txt 
Internet Engineering Task Force (IETF) R. Fielding, Ed. Internet Engineering Task Force (IETF) R. Fielding, Ed.
Request for Comments: 9111 Adobe Request for Comments: 9111 Adobe
STD: 97 M. Nottingham, Ed. STD: 97 M. Nottingham, Ed.
Obsoletes: 7234 Fastly Obsoletes: 7234 Fastly
Category: Standards Track J. Reschke, Ed. Category: Standards Track J. Reschke, Ed.
ISSN: 2070-1721 greenbytes ISSN: 2070-1721 greenbytes
December 2021 January 2022
HTTP Caching HTTP Caching
Abstract Abstract
The Hypertext Transfer Protocol (HTTP) is a stateless application- The Hypertext Transfer Protocol (HTTP) is a stateless application-
level protocol for distributed, collaborative, hypertext information level protocol for distributed, collaborative, hypertext information
systems. This document defines HTTP caches and the associated header systems. This document defines HTTP caches and the associated header
fields that control cache behavior or indicate cacheable response fields that control cache behavior or indicate cacheable response
messages. messages.
skipping to change at line 38 skipping to change at line 38
received public review and has been approved for publication by the received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841. Internet Standards is available in Section 2 of RFC 7841.
Information about the current status of this document, any errata, Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9111. https://www.rfc-editor.org/info/rfc9111.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2022 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Revised BSD License text as described in Section 4.e of the include Revised BSD License text as described in Section 4.e of the
Trust Legal Provisions and are provided without warranty as described Trust Legal Provisions and are provided without warranty as described
skipping to change at line 94 skipping to change at line 94
4.3. Validation 4.3. Validation
4.3.1. Sending a Validation Request 4.3.1. Sending a Validation Request
4.3.2. Handling a Received Validation Request 4.3.2. Handling a Received Validation Request
4.3.3. Handling a Validation Response 4.3.3. Handling a Validation Response
4.3.4. Freshening Stored Responses upon Validation 4.3.4. Freshening Stored Responses upon Validation
4.3.5. Freshening Responses with HEAD 4.3.5. Freshening Responses with HEAD
4.4. Invalidating Stored Responses 4.4. Invalidating Stored Responses
5. Field Definitions 5. Field Definitions
5.1. Age 5.1. Age
5.2. Cache-Control 5.2. Cache-Control
5.2.1. Request Cache-Control Directives 5.2.1. Request Directives
5.2.1.1. max-age 5.2.1.1. max-age
5.2.1.2. max-stale 5.2.1.2. max-stale
5.2.1.3. min-fresh 5.2.1.3. min-fresh
5.2.1.4. no-cache 5.2.1.4. no-cache
5.2.1.5. no-store 5.2.1.5. no-store
5.2.1.6. no-transform 5.2.1.6. no-transform
5.2.1.7. only-if-cached 5.2.1.7. only-if-cached
5.2.2. Response Cache-Control Directives 5.2.2. Response Directives
5.2.2.1. max-age 5.2.2.1. max-age
5.2.2.2. must-revalidate 5.2.2.2. must-revalidate
5.2.2.3. must-understand 5.2.2.3. must-understand
5.2.2.4. no-cache 5.2.2.4. no-cache
5.2.2.5. no-store 5.2.2.5. no-store
5.2.2.6. no-transform 5.2.2.6. no-transform
5.2.2.7. private 5.2.2.7. private
5.2.2.8. proxy-revalidate 5.2.2.8. proxy-revalidate
5.2.2.9. public 5.2.2.9. public
5.2.2.10. s-maxage 5.2.2.10. s-maxage
5.2.3. Cache Control Extensions 5.2.3. Extension Directives
5.2.4. Cache Directive Registry 5.2.4. Cache Directive Registry
5.3. Expires 5.3. Expires
5.4. Pragma 5.4. Pragma
5.5. Warning 5.5. Warning
6. Relationship to Applications and Other Caches 6. Relationship to Applications and Other Caches
7. Security Considerations 7. Security Considerations
7.1. Cache Poisoning 7.1. Cache Poisoning
7.2. Timing Attacks 7.2. Timing Attacks
7.3. Caching of Sensitive Information 7.3. Caching of Sensitive Information
8. IANA Considerations 8. IANA Considerations
skipping to change at line 150 skipping to change at line 150
self-descriptive messages for flexible interaction with network-based self-descriptive messages for flexible interaction with network-based
hypertext information systems. It is typically used for distributed hypertext information systems. It is typically used for distributed
information systems, where the use of response caches can improve information systems, where the use of response caches can improve
performance. This document defines aspects of HTTP related to performance. This document defines aspects of HTTP related to
caching and reusing response messages. caching and reusing response messages.
An HTTP _cache_ is a local store of response messages and the An HTTP _cache_ is a local store of response messages and the
subsystem that controls storage, retrieval, and deletion of messages subsystem that controls storage, retrieval, and deletion of messages
in it. A cache stores cacheable responses to reduce the response in it. A cache stores cacheable responses to reduce the response
time and network bandwidth consumption on future equivalent requests. time and network bandwidth consumption on future equivalent requests.
Any client or server MAY use a cache but not when acting as a tunnel Any client or server MAY use a cache, though not when acting as a
(Section 3.7 of [HTTP]). tunnel (Section 3.7 of [HTTP]).
A _shared cache_ is a cache that stores responses for reuse by more A _shared cache_ is a cache that stores responses for reuse by more
than one user; shared caches are usually (but not always) deployed as than one user; shared caches are usually (but not always) deployed as
a part of an intermediary. A _private cache_, in contrast, is a part of an intermediary. A _private cache_, in contrast, is
dedicated to a single user; often, they are deployed as a component dedicated to a single user; often, they are deployed as a component
of a user agent. of a user agent.
The goal of HTTP caching is significantly improving performance by The goal of HTTP caching is significantly improving performance by
reusing a prior response message to satisfy a current request. A reusing a prior response message to satisfy a current request. A
cache considers a stored response "fresh", as defined in Section 4.2, cache considers a stored response "fresh", as defined in Section 4.2,
skipping to change at line 244 skipping to change at line 244
Proper cache operation preserves the semantics of HTTP transfers Proper cache operation preserves the semantics of HTTP transfers
while reducing the transmission of information already held in the while reducing the transmission of information already held in the
cache. See Section 3 of [HTTP] for the general terminology and core cache. See Section 3 of [HTTP] for the general terminology and core
concepts of HTTP. concepts of HTTP.
Although caching is an entirely OPTIONAL feature of HTTP, it can be Although caching is an entirely OPTIONAL feature of HTTP, it can be
assumed that reusing a cached response is desirable and that such assumed that reusing a cached response is desirable and that such
reuse is the default behavior when no requirement or local reuse is the default behavior when no requirement or local
configuration prevents it. Therefore, HTTP cache requirements are configuration prevents it. Therefore, HTTP cache requirements are
focused on preventing a cache from either storing a non-reusable focused on preventing a cache from either storing a non-reusable
response or reusing a stored response inappropriately rather than response or reusing a stored response inappropriately, rather than
mandating that caches always store and reuse particular responses. mandating that caches always store and reuse particular responses.
The _cache key_ is the information a cache uses to choose a response The _cache key_ is the information a cache uses to choose a response
and is composed from, at a minimum, the request method and target URI and is composed from, at a minimum, the request method and target URI
used to retrieve the stored response; the method determines under used to retrieve the stored response; the method determines under
which circumstances that response can be used to satisfy a subsequent which circumstances that response can be used to satisfy a subsequent
request. However, many HTTP caches in common use today only cache request. However, many HTTP caches in common use today only cache
GET responses and therefore only use the URI as the cache key, GET responses and therefore only use the URI as the cache key,
forwarding other methods. forwarding other methods.
skipping to change at line 305 skipping to change at line 305
not present or allows a shared cache to store a modified response; not present or allows a shared cache to store a modified response;
see Section 5.2.2.7); see Section 5.2.2.7);
* if the cache is shared: the Authorization header field is not * if the cache is shared: the Authorization header field is not
present in the request (see Section 11.6.2 of [HTTP]) or a present in the request (see Section 11.6.2 of [HTTP]) or a
response directive is present that explicitly allows shared response directive is present that explicitly allows shared
caching (see Section 3.5); and caching (see Section 3.5); and
* the response contains at least one of the following: * the response contains at least one of the following:
- a public response directive (see Section 5.2.2.9); - a "public" response directive (see Section 5.2.2.9);
- a private response directive, if the cache is not shared (see - a "private" response directive, if the cache is not shared (see
Section 5.2.2.7); Section 5.2.2.7);
- an Expires header field (see Section 5.3); - an Expires header field (see Section 5.3);
- a max-age response directive (see Section 5.2.2.1); - a "max-age" response directive (see Section 5.2.2.1);
- if the cache is shared: a s-maxage response directive (see - if the cache is shared: an "s-maxage" response directive (see
Section 5.2.2.10); Section 5.2.2.10);
- a Cache-Control extension that allows it to be cached (see - a Cache-Control extension that allows it to be cached (see
Section 5.2.3); or Section 5.2.3); or
- a status code that is defined as heuristically cacheable (see - a status code that is defined as heuristically cacheable (see
Section 4.2.2). Section 4.2.2).
Note that a Cache-Control extension can override any of the Note that a Cache-Control extension can override any of the
requirements listed; see Section 5.2.3. requirements listed; see Section 5.2.3.
skipping to change at line 351 skipping to change at line 351
* The Connection header field and fields whose names are listed in * The Connection header field and fields whose names are listed in
it are required by Section 7.6.1 of [HTTP] to be removed before it are required by Section 7.6.1 of [HTTP] to be removed before
forwarding the message. This MAY be implemented by doing so forwarding the message. This MAY be implemented by doing so
before storage. before storage.
* Likewise, some fields' semantics require them to be removed before * Likewise, some fields' semantics require them to be removed before
forwarding the message, and this MAY be implemented by doing so forwarding the message, and this MAY be implemented by doing so
before storage; see Section 7.6.1 of [HTTP] for some examples. before storage; see Section 7.6.1 of [HTTP] for some examples.
* The no-cache (Section 5.2.2.4) and private (Section 5.2.2.7) cache * The "no-cache" (Section 5.2.2.4) and private (Section 5.2.2.7)
directives can have arguments that prevent storage of header cache directives can have arguments that prevent storage of header
fields by all caches and shared caches, respectively. fields by all caches and shared caches, respectively.
* Header fields that are specific to the proxy that a cache uses * Header fields that are specific to the proxy that a cache uses
when forwarding a request MUST NOT be stored, unless the cache when forwarding a request MUST NOT be stored, unless the cache
incorporates the identity of the proxy into the cache key. incorporates the identity of the proxy into the cache key.
Effectively, this is limited to Proxy-Authenticate (Section 11.7.1 Effectively, this is limited to Proxy-Authenticate (Section 11.7.1
of [HTTP]), Proxy-Authentication-Info (Section 11.7.3 of [HTTP]), of [HTTP]), Proxy-Authentication-Info (Section 11.7.3 of [HTTP]),
and Proxy-Authorization (Section 11.7.2 of [HTTP]). and Proxy-Authorization (Section 11.7.2 of [HTTP]).
Caches MAY either store trailer fields separate from header fields or Caches MAY either store trailer fields separate from header fields or
skipping to change at line 417 skipping to change at line 417
updates, even when the processing does not actually occur. updates, even when the processing does not actually occur.
Note that the Content-* prefix is not a signal that a header field is Note that the Content-* prefix is not a signal that a header field is
omitted from update; it is a convention for MIME header fields, not omitted from update; it is a convention for MIME header fields, not
HTTP. HTTP.
3.3. Storing Incomplete Responses 3.3. Storing Incomplete Responses
If the request method is GET, the response status code is 200 (OK), If the request method is GET, the response status code is 200 (OK),
and the entire response header section has been received, a cache MAY and the entire response header section has been received, a cache MAY
store a response body that is not complete (Section 3.4 of [HTTP]) if store a response body that is not complete (Section 6.1 of [HTTP]) if
the stored response is recorded as being incomplete. Likewise, a 206 the stored response is recorded as being incomplete. Likewise, a 206
(Partial Content) response MAY be stored as if it were an incomplete (Partial Content) response MAY be stored as if it were an incomplete
200 (OK) response. However, a cache MUST NOT store incomplete or 200 (OK) response. However, a cache MUST NOT store incomplete or
partial-content responses if it does not support the Range and partial-content responses if it does not support the Range and
Content-Range header fields or if it does not understand the range Content-Range header fields or if it does not understand the range
units used in those fields. units used in those fields.
A cache MAY complete a stored incomplete response by making a A cache MAY complete a stored incomplete response by making a
subsequent range request (Section 14.2 of [HTTP]) and combining the subsequent range request (Section 14.2 of [HTTP]) and combining the
successful response with the stored response, as defined in successful response with the stored response, as defined in
skipping to change at line 460 skipping to change at line 460
3.5. Storing Responses to Authenticated Requests 3.5. Storing Responses to Authenticated Requests
A shared cache MUST NOT use a cached response to a request with an A shared cache MUST NOT use a cached response to a request with an
Authorization header field (Section 11.6.2 of [HTTP]) to satisfy any Authorization header field (Section 11.6.2 of [HTTP]) to satisfy any
subsequent request unless the response contains a Cache-Control field subsequent request unless the response contains a Cache-Control field
with a response directive (Section 5.2.2) that allows it to be stored with a response directive (Section 5.2.2) that allows it to be stored
by a shared cache, and the cache conforms to the requirements of that by a shared cache, and the cache conforms to the requirements of that
directive for that response. directive for that response.
In this specification, the following response directives have such an In this specification, the following response directives have such an
effect: must-revalidate (Section 5.2.2.2), public (Section 5.2.2.9), effect: "must-revalidate" (Section 5.2.2.2), public
and s-maxage (Section 5.2.2.10). (Section 5.2.2.9), and s-maxage (Section 5.2.2.10).
4. Constructing Responses from Caches 4. Constructing Responses from Caches
When presented with a request, a cache MUST NOT reuse a stored When presented with a request, a cache MUST NOT reuse a stored
response unless: response unless:
* the presented target URI (Section 7.1 of [HTTP]) and that of the * the presented target URI (Section 7.1 of [HTTP]) and that of the
stored response match, and stored response match, and
* the request method associated with the stored response allows it * the request method associated with the stored response allows it
to be used for the presented request, and to be used for the presented request, and
* request header fields nominated by the stored response (if any) * request header fields nominated by the stored response (if any)
match those presented (see Section 4.1), and match those presented (see Section 4.1), and
* the stored response does not contain the no-cache cache directive * the stored response does not contain the no-cache cache directive
(Section 5.2.2.4), unless it is successfully validated (Section 5.2.2.4), unless it is successfully validated
(Section 4.3), and (Section 4.3), and
* the stored response is either: * the stored response is one of the following:
- fresh (see Section 4.2), or - fresh (see Section 4.2), or
- allowed to be served stale (see Section 4.2.4), or - allowed to be served stale (see Section 4.2.4), or
- successfully validated (see Section 4.3). - successfully validated (see Section 4.3).
Note that a Cache-Control extension can override any of the Note that a Cache-Control extension can override any of the
requirements listed; see Section 5.2.3. requirements listed; see Section 5.2.3.
skipping to change at line 505 skipping to change at line 505
stored response's current_age; see Section 4.2.3. stored response's current_age; see Section 4.2.3.
A cache MUST write through requests with methods that are unsafe A cache MUST write through requests with methods that are unsafe
(Section 9.2.1 of [HTTP]) to the origin server; i.e., a cache is not (Section 9.2.1 of [HTTP]) to the origin server; i.e., a cache is not
allowed to generate a reply to such a request before having forwarded allowed to generate a reply to such a request before having forwarded
the request and having received a corresponding response. the request and having received a corresponding response.
Also, note that unsafe requests might invalidate already-stored Also, note that unsafe requests might invalidate already-stored
responses; see Section 4.4. responses; see Section 4.4.
A response that is stored or storable can be used to satisfy multiple A cache can use a response that is stored or storable to satisfy
requests, provided that it is allowed to reuse that response for the multiple requests, provided that it is allowed to reuse that response
requests in question. This enables caches to _collapse requests_ -- for the requests in question. This enables a cache to _collapse
or combine multiple incoming requests into a single forward request requests_ -- or combine multiple incoming requests into a single
upon a cache miss -- thereby reducing load on the origin server and forward request upon a cache miss -- thereby reducing load on the
network. However, note that if the response returned is not able to origin server and network. Note, however, that if the cache cannot
be used for some or all of the collapsed requests, additional latency use the returned response for some or all of the collapsed requests,
might be introduced, because they will need to be forwarded to be it will need to forward the requests in order to satisfy them,
satisfied. potentially introducing additional latency.
When more than one suitable response is stored, a cache MUST use the When more than one suitable response is stored, a cache MUST use the
most recent one (as determined by the Date header field). It can most recent one (as determined by the Date header field). It can
also forward the request with "Cache-Control: max-age=0" or "Cache- also forward the request with "Cache-Control: max-age=0" or "Cache-
Control: no-cache" to disambiguate which response to use. Control: no-cache" to disambiguate which response to use.
A cache without a clock (Section 5.6.7 of [HTTP]) MUST revalidate A cache without a clock (Section 5.6.7 of [HTTP]) MUST revalidate
stored responses upon every use. stored responses upon every use.
4.1. Calculating Cache Keys with the Vary Header Field 4.1. Calculating Cache Keys with the Vary Header Field
skipping to change at line 623 skipping to change at line 623
caches are also allowed to use a heuristic to determine an expiration caches are also allowed to use a heuristic to determine an expiration
time under certain circumstances (see Section 4.2.2). time under certain circumstances (see Section 4.2.2).
The calculation to determine if a response is fresh is: The calculation to determine if a response is fresh is:
response_is_fresh = (freshness_lifetime > current_age) response_is_fresh = (freshness_lifetime > current_age)
freshness_lifetime is defined in Section 4.2.1; current_age is freshness_lifetime is defined in Section 4.2.1; current_age is
defined in Section 4.2.3. defined in Section 4.2.3.
Clients can send the max-age or min-fresh request directives Clients can send the max-age or "min-fresh" request directives
(Section 5.2.1) to suggest limits on the freshness calculations for (Section 5.2.1) to suggest limits on the freshness calculations for
the corresponding response. However, caches are not required to the corresponding response. However, caches are not required to
honor them. honor them.
When calculating freshness, to avoid common problems in date parsing: When calculating freshness, to avoid common problems in date parsing:
* Although all date formats are specified to be case-sensitive, a * Although all date formats are specified to be case-sensitive, a
cache recipient SHOULD match the field value case-insensitively. cache recipient SHOULD match the field value case-insensitively.
* If a cache recipient's internal implementation of time has less * If a cache recipient's internal implementation of time has less
skipping to change at line 698 skipping to change at line 698
(such as the Last-Modified time) to estimate a plausible expiration (such as the Last-Modified time) to estimate a plausible expiration
time. This specification does not provide specific algorithms, but time. This specification does not provide specific algorithms, but
it does impose worst-case constraints on their results. it does impose worst-case constraints on their results.
A cache MUST NOT use heuristics to determine freshness when an A cache MUST NOT use heuristics to determine freshness when an
explicit expiration time is present in the stored response. Because explicit expiration time is present in the stored response. Because
of the requirements in Section 3, heuristics can only be used on of the requirements in Section 3, heuristics can only be used on
responses without explicit freshness whose status codes are defined responses without explicit freshness whose status codes are defined
as _heuristically cacheable_ (e.g., see Section 15.1 of [HTTP]) and as _heuristically cacheable_ (e.g., see Section 15.1 of [HTTP]) and
on responses without explicit freshness that have been marked as on responses without explicit freshness that have been marked as
explicitly cacheable (e.g., with a "public" response directive). explicitly cacheable (e.g., with a public response directive).
Note that in previous specifications, heuristically cacheable Note that in previous specifications, heuristically cacheable
response status codes were called "cacheable by default". response status codes were called "cacheable by default".
If the response has a Last-Modified header field (Section 8.8.2 of If the response has a Last-Modified header field (Section 8.8.2 of
[HTTP]), caches are encouraged to use a heuristic expiration value [HTTP]), caches are encouraged to use a heuristic expiration value
that is no more than some fraction of the interval since that time. that is no more than some fraction of the interval since that time.
A typical setting of this fraction might be 10%. A typical setting of this fraction might be 10%.
| *Note:* Section 13.9 of [RFC2616] prohibits caches from | *Note:* A previous version of the HTTP specification
| calculating heuristic freshness for URIs with query components | (Section 13.9 of [RFC2616]) prohibited caches from calculating
| (i.e., those containing "?"). In practice, this has not been | heuristic freshness for URIs with query components (i.e., those
| widely implemented. Therefore, origin servers are encouraged | containing "?"). In practice, this has not been widely
| to send explicit directives (e.g., Cache-Control: no-cache) if | implemented. Therefore, origin servers are encouraged to send
| they wish to prevent caching. | explicit directives (e.g., Cache-Control: no-cache) if they
| wish to prevent caching.
4.2.3. Calculating Age 4.2.3. Calculating Age
The Age header field is used to convey an estimated age of the The Age header field is used to convey an estimated age of the
response message when obtained from a cache. The Age field value is response message when obtained from a cache. The Age field value is
the cache's estimate of the number of seconds since the origin server the cache's estimate of the number of seconds since the origin server
generated or validated the response. The Age value is therefore the generated or validated the response. The Age value is therefore the
sum of the time that the response has been resident in each of 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 time it has caches along the path from the origin server, plus the time it has
been in transit along network paths. been in transit along network paths.
skipping to change at line 787 skipping to change at line 788
resident_time = now - response_time; resident_time = now - response_time;
current_age = corrected_initial_age + resident_time; current_age = corrected_initial_age + resident_time;
4.2.4. Serving Stale Responses 4.2.4. Serving Stale Responses
A "stale" response is one that either has explicit expiry information A "stale" response is one that either has explicit expiry information
or is allowed to have heuristic expiry calculated, but is not fresh or is allowed to have heuristic expiry calculated, but is not fresh
according to the calculations in Section 4.2. according to the calculations in Section 4.2.
A cache MUST NOT generate a stale response if it is prohibited by an A cache MUST NOT generate a stale response if it is prohibited by an
explicit in-protocol directive (e.g., by a "no-cache" cache explicit in-protocol directive (e.g., by a no-cache cache directive,
directive, a "must-revalidate" cache-response-directive, or an a must-revalidate response directive, or an applicable s-maxage or
applicable "s-maxage" or "proxy-revalidate" cache-response-directive; "proxy-revalidate" response directive; see Section 5.2.2).
see Section 5.2.2).
A cache MUST NOT generate a stale response unless it is disconnected A cache MUST NOT generate a stale response unless it is disconnected
or doing so is explicitly permitted by the client or origin server or doing so is explicitly permitted by the client or origin server
(e.g., by the max-stale request directive in Section 5.2.1, extension (e.g., by the "max-stale" request directive in Section 5.2.1,
directives such as those defined in [RFC5861], or configuration in extension directives such as those defined in [RFC5861], or
accordance with an out-of-band contract). configuration in accordance with an out-of-band contract).
4.3. Validation 4.3. Validation
When a cache has one or more stored responses for a requested URI, 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 but cannot serve any of them (e.g., because they are not fresh, or
one cannot be chosen; see Section 4.1), it can use the conditional one cannot be chosen; see Section 4.1), it can use the conditional
request mechanism (Section 13.1 of [HTTP]) in the forwarded request request mechanism (Section 13 of [HTTP]) in the forwarded request to
to give the next inbound server an opportunity to choose a valid give the next inbound server an opportunity to choose a valid stored
stored response to use, updating the stored metadata in the process, response to use, updating the stored metadata in the process, or to
or to replace the stored response(s) with a new response. This replace the stored response(s) with a new response. This process is
process is known as _validating_ or _revalidating_ the stored known as _validating_ or _revalidating_ the stored response.
response.
4.3.1. Sending a Validation Request 4.3.1. Sending a Validation Request
When generating a conditional request for validation, a cache either When generating a conditional request for validation, a cache either
starts with a request it is attempting to satisfy or -- if it is starts with a request it is attempting to satisfy or -- if it is
initiating the request independently -- synthesizes a request using a initiating the request independently -- synthesizes a request using a
stored response by copying the method, target URI, and request header stored response by copying the method, target URI, and request header
fields identified by the Vary header field (Section 4.1). fields identified by the Vary header field (Section 4.1).
It then updates that request with one or more precondition header It then updates that request with one or more precondition header
skipping to change at line 960 skipping to change at line 959
When a cache receives a 304 (Not Modified) response, it needs to When a cache receives a 304 (Not Modified) response, it needs to
identify stored responses that are suitable for updating with the new identify stored responses that are suitable for updating with the new
information provided, and then do so. information provided, and then do so.
The initial set of stored responses to update are those that could The initial set of stored responses to update are those that could
have been chosen for that request -- i.e., those that meet the have been chosen for that request -- i.e., those that meet the
requirements in Section 4, except the last requirement to be fresh, requirements in Section 4, except the last requirement to be fresh,
served stale, or just validated. served stale, or just validated.
Then, that initial set of stored response(s) is further filtered by Then, that initial set of stored response is further filtered by the
the first match of: first match of:
* If the new response contains one or more _strong validators_ (see * If the new response contains one or more _strong validators_ (see
Section 8.8.1 of [HTTP]), then each of those strong validators Section 8.8.1 of [HTTP]), then each of those strong validators
identifies a selected representation for update. All the stored identifies a selected representation for update. All the stored
responses in the initial set with one of those same strong responses in the initial set with one of those same strong
validators are identified for update. If none of the initial set validators are identified for update. If none of the initial set
contains at least one of the same strong validators, then the contains at least one of the same strong validators, then the
cache MUST NOT use the new response to update any stored cache MUST NOT use the new response to update any stored
responses. responses.
skipping to change at line 1082 skipping to change at line 1081
negative integer), a cache SHOULD ignore the field. negative integer), a cache SHOULD ignore the field.
The presence of an Age header field implies that the response was not The presence of an Age header field implies that the response was not
generated or validated by the origin server for this request. generated or validated by the origin server for this request.
However, lack of an Age header field does not imply the origin was However, lack of an Age header field does not imply the origin was
contacted. contacted.
5.2. Cache-Control 5.2. Cache-Control
The "Cache-Control" header field is used to list directives for The "Cache-Control" header field is used to list directives for
caches along the request/response chain. Such cache directives are caches along the request/response chain. Cache directives are
unidirectional in that the presence of a directive in a request does unidirectional, in that the presence of a directive in a request does
not imply that the same directive is present in the response, or to not imply that the same directive is present or copied in the
be repeated in it. response.
See Section 5.2.3 for information about how Cache-Control directives See Section 5.2.3 for information about how Cache-Control directives
defined elsewhere are handled. defined elsewhere are handled.
A proxy, whether or not it implements a cache, MUST pass cache A proxy, whether or not it implements a cache, MUST pass cache
directives through in forwarded messages, regardless of their directives through in forwarded messages, regardless of their
significance to that application, since the directives might apply to significance to that application, since the directives might apply to
all recipients along the request/response chain. It is not possible all recipients along the request/response chain. It is not possible
to target a directive to a specific cache. to target a directive to a specific cache.
skipping to change at line 1109 skipping to change at line 1108
define arguments, recipients ought to accept both forms, even if a define arguments, recipients ought to accept both forms, even if a
specific form is required for generation. specific form is required for generation.
Cache-Control = #cache-directive Cache-Control = #cache-directive
cache-directive = token [ "=" ( token / quoted-string ) ] cache-directive = token [ "=" ( token / quoted-string ) ]
For the cache directives defined below, no argument is defined (nor For the cache directives defined below, no argument is defined (nor
allowed) unless stated otherwise. allowed) unless stated otherwise.
5.2.1. Request Cache-Control Directives 5.2.1. Request Directives
This section defines cache request directives. They are advisory; This section defines cache request directives. They are advisory;
caches MAY implement them, but are not required to. caches MAY implement them, but are not required to.
5.2.1.1. max-age 5.2.1.1. max-age
Argument syntax: Argument syntax:
delta-seconds (see Section 1.2.2) delta-seconds (see Section 1.2.2)
skipping to change at line 1201 skipping to change at line 1200
defined in Section 7.7 of [HTTP]. defined in Section 7.7 of [HTTP].
5.2.1.7. only-if-cached 5.2.1.7. only-if-cached
The "only-if-cached" request directive indicates that the client only The "only-if-cached" request directive indicates that the client only
wishes to obtain a stored response. Caches that honor this request wishes to obtain a stored response. Caches that honor this request
directive SHOULD, upon receiving it, respond with either a stored directive SHOULD, upon receiving it, respond with either a stored
response consistent with the other constraints of the request or a response consistent with the other constraints of the request or a
504 (Gateway Timeout) status code. 504 (Gateway Timeout) status code.
5.2.2. Response Cache-Control Directives 5.2.2. Response Directives
This section defines cache response directives. A cache MUST obey This section defines cache response directives. A cache MUST obey
the Cache-Control directives defined in this section. the Cache-Control directives defined in this section.
5.2.2.1. max-age 5.2.2.1. max-age
Argument syntax: Argument syntax:
delta-seconds (see Section 1.2.2) delta-seconds (see Section 1.2.2)
skipping to change at line 1250 skipping to change at line 1249
response to a request containing an Authorization header field response to a request containing an Authorization header field
(Section 11.6.2 of [HTTP]), subject to the above requirement on (Section 11.6.2 of [HTTP]), subject to the above requirement on
revalidation (Section 3.5). revalidation (Section 3.5).
5.2.2.3. must-understand 5.2.2.3. must-understand
The "must-understand" response directive limits caching of the The "must-understand" response directive limits caching of the
response to a cache that understands and conforms to the requirements response to a cache that understands and conforms to the requirements
for that response's status code. for that response's status code.
Responses containing "must-understand" SHOULD also contain the "no- A response that contains the must-understand directive SHOULD also
store" directive; caches that implement "must-understand" SHOULD contain the no-store directive. When a cache that implements the
ignore the "no-store" directive in responses that contain both must-understand directive receives a response that includes it, the
directives and a status code that the cache understands and conforms cache SHOULD ignore the no-store directive if it understands and
to any related caching requirements. implements the status code's caching requirements.
5.2.2.4. no-cache 5.2.2.4. no-cache
Argument syntax: Argument syntax:
#field-name #field-name
The "no-cache" response directive, in its unqualified form (without The "no-cache" response directive, in its unqualified form (without
an argument), indicates that the response MUST NOT be used to satisfy an argument), indicates that the response MUST NOT be used to satisfy
any other request without forwarding it for validation and receiving any other request without forwarding it for validation and receiving
skipping to change at line 1310 skipping to change at line 1309
store" in this context means that the cache MUST NOT intentionally store" in this context means that the cache MUST NOT intentionally
store the information in non-volatile storage and MUST make a best- store the information in non-volatile storage and MUST make a best-
effort attempt to remove the information from volatile storage as effort attempt to remove the information from volatile storage as
promptly as possible after forwarding it. promptly as possible after forwarding it.
This directive is _not_ a reliable or sufficient mechanism for This directive is _not_ a reliable or sufficient mechanism for
ensuring privacy. In particular, malicious or compromised caches ensuring privacy. In particular, malicious or compromised caches
might not recognize or obey this directive, and communications might not recognize or obey this directive, and communications
networks might be vulnerable to eavesdropping. networks might be vulnerable to eavesdropping.
Note that the "must-understand" cache directive overrides "no-store" Note that the must-understand cache directive overrides no-store in
in certain circumstances; see Section 5.2.2.3. certain circumstances; see Section 5.2.2.3.
5.2.2.6. no-transform 5.2.2.6. no-transform
The "no-transform" response directive indicates that an intermediary The "no-transform" response directive indicates that an intermediary
(regardless of whether it implements a cache) MUST NOT transform the (regardless of whether it implements a cache) MUST NOT transform the
content, as defined in Section 7.7 of [HTTP]. content, as defined in Section 7.7 of [HTTP].
5.2.2.7. private 5.2.2.7. private
Argument syntax: Argument syntax:
skipping to change at line 1362 skipping to change at line 1361
5.2.2.8. proxy-revalidate 5.2.2.8. proxy-revalidate
The "proxy-revalidate" response directive indicates that once the The "proxy-revalidate" response directive indicates that once the
response has become stale, a shared cache MUST NOT reuse that response has become stale, a shared cache MUST NOT reuse that
response to satisfy another request until it has been successfully response to satisfy another request until it has been successfully
validated by the origin, as defined by Section 4.3. This is validated by the origin, as defined by Section 4.3. This is
analogous to must-revalidate (Section 5.2.2.2), except that proxy- analogous to must-revalidate (Section 5.2.2.2), except that proxy-
revalidate does not apply to private caches. revalidate does not apply to private caches.
Note that "proxy-revalidate" on its own does not imply that a Note that proxy-revalidate on its own does not imply that a response
response is cacheable. For example, it might be combined with the is cacheable. For example, it might be combined with the public
public directive (Section 5.2.2.9), allowing the response to be directive (Section 5.2.2.9), allowing the response to be cached while
cached while requiring only a shared cache to revalidate when stale. requiring only a shared cache to revalidate when stale.
5.2.2.9. public 5.2.2.9. public
The "public" response directive indicates that a cache MAY store the The "public" response directive indicates that a cache MAY store the
response even if it would otherwise be prohibited, subject to the response even if it would otherwise be prohibited, subject to the
constraints defined in Section 3. In other words, public explicitly constraints defined in Section 3. In other words, public explicitly
marks the response as cacheable. For example, public permits a marks the response as cacheable. For example, public permits a
shared cache to reuse a response to a request containing an shared cache to reuse a response to a request containing an
Authorization header field (Section 3.5). Authorization header field (Section 3.5).
skipping to change at line 1393 skipping to change at line 1392
Argument syntax: Argument syntax:
delta-seconds (see Section 1.2.2) delta-seconds (see Section 1.2.2)
The "s-maxage" response directive indicates that, for a shared cache, The "s-maxage" response directive indicates that, for a shared cache,
the maximum age specified by this directive overrides the maximum age the maximum age specified by this directive overrides the maximum age
specified by either the max-age directive or the Expires header specified by either the max-age directive or the Expires header
field. field.
The s-maxage directive incorporates the semantics of the proxy- The s-maxage directive incorporates the semantics of the
revalidate response directive (Section 5.2.2.8) for a shared cache. proxy-revalidate response directive (Section 5.2.2.8) for a shared
A shared cache MUST NOT reuse a stale response with s-maxage to cache. A shared cache MUST NOT reuse a stale response with s-maxage
satisfy another request until it has been successfully validated by to satisfy another request until it has been successfully validated
the origin, as defined by Section 4.3. This directive also permits a by the origin, as defined by Section 4.3. This directive also
shared cache to reuse a response to a request containing an permits a shared cache to reuse a response to a request containing an
Authorization header field, subject to the above requirements on Authorization header field, subject to the above requirements on
maximum age and revalidation (Section 3.5). maximum age and revalidation (Section 3.5).
This directive uses the token form of the argument syntax: e.g., This directive uses the token form of the argument syntax: e.g.,
's-maxage=10' not 's-maxage="10"'. A sender MUST NOT generate the 's-maxage=10' not 's-maxage="10"'. A sender MUST NOT generate the
quoted-string form. quoted-string form.
5.2.3. Cache Control Extensions 5.2.3. Extension Directives
The Cache-Control header field can be extended through the use of one The Cache-Control header field can be extended through the use of one
or more extension cache directives. A cache MUST ignore unrecognized or more extension cache directives. A cache MUST ignore unrecognized
cache directives. cache directives.
Informational extensions (those that do not require a change in cache Informational extensions (those that do not require a change in cache
behavior) can be added without changing the semantics of other behavior) can be added without changing the semantics of other
directives. directives.
Behavioral extensions are designed to work by acting as modifiers to Behavioral extensions are designed to work by acting as modifiers to
the existing base of cache directives. Both the new directive and the existing base of cache directives. Both the new directive and
the old directive are supplied, such that applications that do not the old directive are supplied, such that applications that do not
understand the new directive will default to the behavior specified understand the new directive will default to the behavior specified
by the old directive, and those that understand the new directive by the old directive, and those that understand the new directive
will recognize it as modifying the requirements associated with the will recognize it as modifying the requirements associated with the
old directive. In this way, extensions to the existing Cache-Control old directive. In this way, extensions to the existing Cache-Control
directives can be made without breaking deployed caches. directives can be made without breaking deployed caches.
For example, consider a hypothetical new response directive called For example, consider a hypothetical new response directive called
"community" that acts as a modifier to the private directive: in "community" that acts as a modifier to the private directive: in
addition to private caches, any cache that is shared only by members addition to private caches, only a cache that is shared by members of
of the named community is allowed to cache the response. An origin the named community is allowed to cache the response. An origin
server wishing to allow the UCI community to use an otherwise private server wishing to allow the UCI community to use an otherwise private
response in their shared cache(s) could do so by including response in their shared cache(s) could do so by including
Cache-Control: private, community="UCI" Cache-Control: private, community="UCI"
A cache that recognizes such a community cache directive could A cache that recognizes such a community cache directive could
broaden its behavior in accordance with that extension. A cache that broaden its behavior in accordance with that extension. A cache that
does not recognize the community cache directive would ignore it and does not recognize the community cache directive would ignore it and
adhere to the private directive. adhere to the private directive.
skipping to change at line 1622 skipping to change at line 1621
load quickly, it can be assumed that the user has visited that site, load quickly, it can be assumed that the user has visited that site,
or even a specific page on it. or even a specific page on it.
Such "timing attacks" can be mitigated by adding more information to Such "timing attacks" can be mitigated by adding more information to
the cache key, such as the identity of the referring site (to prevent the cache key, such as the identity of the referring site (to prevent
the attack described above). This is sometimes called "double the attack described above). This is sometimes called "double
keying". keying".
7.3. Caching of Sensitive Information 7.3. Caching of Sensitive Information
Implementation and deployment flaws (as well as the misunderstanding Implementation and deployment flaws (often led to by the
of cache operation) might lead to the caching of sensitive misunderstanding of cache operation) might lead to the caching of
information (e.g., authentication credentials) that is thought to be sensitive information (e.g., authentication credentials) that is
private, exposing it to unauthorized parties. thought to be private, exposing it to unauthorized parties.
Note that the Set-Cookie response header field [COOKIE] does not Note that the Set-Cookie response header field [COOKIE] does not
inhibit caching; a cacheable response with a Set-Cookie header field inhibit caching; a cacheable response with a Set-Cookie header field
can be (and often is) used to satisfy subsequent requests to caches. can be (and often is) used to satisfy subsequent requests to caches.
Servers that wish to control caching of these responses are Servers that wish to control caching of these responses are
encouraged to emit appropriate Cache-Control response header fields. encouraged to emit appropriate Cache-Control response header fields.
8. IANA Considerations 8. IANA Considerations
The change controller for the following registrations is: "IETF The change controller for the following registrations is: "IETF
(iesg@ietf.org) -- Internet Engineering Task Force". (iesg@ietf.org) - Internet Engineering Task Force".
8.1. Field Name Registration 8.1. Field Name Registration
IANA has updated the "Hypertext Transfer Protocol (HTTP) Field Name IANA has updated the "Hypertext Transfer Protocol (HTTP) Field Name
Registry" at <https://www.iana.org/assignments/http-fields>, as Registry" at <https://www.iana.org/assignments/http-fields>, as
described in Section 18.4 of [HTTP], with the field names listed in described in Section 18.4 of [HTTP], with the field names listed in
the table below: the table below:
+===============+===========+======+==========+ +===============+===========+======+==========+
| Field Name | Status | Ref. | Comments | | Field Name | Status | Ref. | Comments |
+===============+===========+======+==========+ +===============+===========+======+==========+
| Age | standard | 5.1 | | | Age | permanent | 5.1 | |
+---------------+-----------+------+----------+ +---------------+-----------+------+----------+
| Cache-Control | standard | 5.2 | | | Cache-Control | permanent | 5.2 | |
+---------------+-----------+------+----------+ +---------------+-----------+------+----------+
| Expires | standard | 5.3 | | | Expires | permanent | 5.3 | |
+---------------+-----------+------+----------+ +---------------+-----------+------+----------+
| Pragma | standard | 5.4 | | | Pragma | permanent | 5.4 | |
+---------------+-----------+------+----------+ +---------------+-----------+------+----------+
| Warning | obsoleted | 5.5 | | | Warning | obsoleted | 5.5 | |
+---------------+-----------+------+----------+ +---------------+-----------+------+----------+
Table 1 Table 1
8.2. Cache Directive Registration 8.2. Cache Directive Registration
IANA has updated the "Hypertext Transfer Protocol (HTTP) Cache IANA has updated the "Hypertext Transfer Protocol (HTTP) Cache
Directive Registry" at <https://www.iana.org/assignments/http-cache- Directive Registry" at <https://www.iana.org/assignments/http-cache-
skipping to change at line 1702 skipping to change at line 1701
+------------------+----------------------------------+ +------------------+----------------------------------+
| public | Section 5.2.2.9 | | public | Section 5.2.2.9 |
+------------------+----------------------------------+ +------------------+----------------------------------+
| s-maxage | Section 5.2.2.10 | | s-maxage | Section 5.2.2.10 |
+------------------+----------------------------------+ +------------------+----------------------------------+
Table 2 Table 2
8.3. Warn Code Registry 8.3. Warn Code Registry
IANA has the following note to the "Hypertext Transfer Protocol IANA has added the following note to the "Hypertext Transfer Protocol
(HTTP) Warn Codes" registry at <https://www.iana.org/assignments/ (HTTP) Warn Codes" registry at <https://www.iana.org/assignments/
http-warn-codes> stating that "Warning" has been obsoleted: http-warn-codes> stating that "Warning" has been obsoleted:
| The Warning header field (and the warn codes that it uses) has | The Warning header field (and the warn codes that it uses) has
| been obsoleted for HTTP per [RFC9111]. | been obsoleted for HTTP per [RFC9111].
9. References 9. References
9.1. Normative References 9.1. Normative References
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", RFC 9110, DOI 10.17487/RFC9110, Ed., "HTTP Semantics", RFC 9110, DOI 10.17487/RFC9110,
December 2021, <https://www.rfc-editor.org/info/rfc9110>. January 2022, <https://www.rfc-editor.org/info/rfc9110>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>. <https://www.rfc-editor.org/info/rfc5234>.
skipping to change at line 1742 skipping to change at line 1741
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
9.2. Informative References 9.2. Informative References
[COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265, [COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265,
DOI 10.17487/RFC6265, April 2011, DOI 10.17487/RFC6265, April 2011,
<https://www.rfc-editor.org/info/rfc6265>. <https://www.rfc-editor.org/info/rfc6265>.
[HTTP/1.1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [HTTP/1.1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP/1.1", RFC 9112, DOI 10.17487/RFC9112, December Ed., "HTTP/1.1", RFC 9112, DOI 10.17487/RFC9112, January
2021, <https://www.rfc-editor.org/info/rfc9112>. 2022, <https://www.rfc-editor.org/info/rfc9112>.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, Transfer Protocol -- HTTP/1.1", RFC 2616,
DOI 10.17487/RFC2616, June 1999, DOI 10.17487/RFC2616, June 1999,
<https://www.rfc-editor.org/info/rfc2616>. <https://www.rfc-editor.org/info/rfc2616>.
[RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale
Content", RFC 5861, DOI 10.17487/RFC5861, May 2010, Content", RFC 5861, DOI 10.17487/RFC5861, May 2010,
<https://www.rfc-editor.org/info/rfc5861>. <https://www.rfc-editor.org/info/rfc5861>.
skipping to change at line 1813 skipping to change at line 1812
Handling invalid and multiple Age header field values has been Handling invalid and multiple Age header field values has been
clarified (Section 5.1). clarified (Section 5.1).
Some cache directives defined by this specification now have stronger Some cache directives defined by this specification now have stronger
prohibitions against generating the quoted form of their values, prohibitions against generating the quoted form of their values,
since this has been found to create interoperability problems. since this has been found to create interoperability problems.
Consumers of extension cache directives are no longer required to Consumers of extension cache directives are no longer required to
accept both token and quoted-string forms, but they still need to accept both token and quoted-string forms, but they still need to
parse them properly for unknown extensions (Section 5.2). parse them properly for unknown extensions (Section 5.2).
The "public" and "private" cache directives were clarified, so that The public and private cache directives were clarified, so that they
they do not make responses reusable under any condition do not make responses reusable under any condition (Section 5.2.2).
(Section 5.2.2).
The "must-understand" cache directive was introduced; caches are no The must-understand cache directive was introduced; caches are no
longer required to understand the semantics of new response status longer required to understand the semantics of new response status
codes unless it is present (Section 5.2.2.3). codes unless it is present (Section 5.2.2.3).
The Warning response header was obsoleted. Much of the information The Warning response header was obsoleted. Much of the information
supported by Warning could be gleaned by examining the response, and supported by Warning could be gleaned by examining the response, and
the remaining warn codes -- although potentially useful -- were the remaining information -- although potentially useful -- was
entirely advisory. In practice, Warning was not added by caches or entirely advisory. In practice, Warning was not added by caches or
intermediaries (Section 5.5). intermediaries (Section 5.5).
Acknowledgements Acknowledgements
See the "Acknowledgements" section in [HTTP], which applies to this See the "Acknowledgements" section in [HTTP], which applies to this
document. document.
Index Index
 End of changes. 44 change blocks. 
94 lines changed or deleted 92 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/