HTTP                                                            S. Ludin
Internet-Draft                                                    Akamai
Intended status: Standards Track                           M. Nottingham
Expires: 27 January 2022                                          Fastly
                                                                   Y. Wu
                                                            26 July 2021

                      Targeted HTTP Cache Control


   This specification defines a convention for HTTP response header
   fields that allow directives controlling caching to be targeted at
   specific caches or classes of caches.  It also defines one such
   header field, targeted at Content Delivery Network (CDN) caches.

Note to Readers

   _RFC EDITOR: please remove this section before publication_

   The issues list for this draft can be found at

   The most recent (often, unpublished) draft is at

   See also the draft's current status in the IETF datatracker, at
   control/ (

Status of This Memo

   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 at

Ludin, et al.            Expires 27 January 2022                [Page 1]

Internet-Draft         Targeted HTTP Cache Control             July 2021

   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 27 January 2022.

Copyright Notice

   Copyright (c) 2021 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 (
   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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   3
   2.  Targeted Cache-Control Header Fields  . . . . . . . . . . . .   3
     2.1.  Cache Behavior  . . . . . . . . . . . . . . . . . . . . .   3
     2.2.  Parsing Targeted Fields . . . . . . . . . . . . . . . . .   4
     2.3.  Defining Targeted Fields  . . . . . . . . . . . . . . . .   5
   3.  The CDN-Cache-Control Targeted Field  . . . . . . . . . . . .   5
     3.1.  Examples  . . . . . . . . . . . . . . . . . . . . . . . .   6
   4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .   7
   6.  Normative References  . . . . . . . . . . . . . . . . . . . .   7
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   8

1.  Introduction

   Modern deployments of HTTP often use multiple layers of caching with
   varying properties.  For example, a Web site might use a cache on the
   origin server itself; it might deploy a caching layer in the same
   network as the origin server, it might use one or more Content
   Delivery Networks (CDNs) that are distributed throughout the
   Internet, and it might utilise browser caching as well.

   Because it is often desirable to control these different classes of
   caches separately, some means of targeting directives at them is

Ludin, et al.            Expires 27 January 2022                [Page 2]

Internet-Draft         Targeted HTTP Cache Control             July 2021

   The HTTP Cache-Control response header field is widely used to direct
   caching behavior.  However, it is relatively undifferentiated; while
   some directives (e.g., s-maxage) are targeted at a specific class of
   caches (for s-maxage, shared caches), that is not consistently
   available across all existing cache directives (e.g., stale-while-
   revalidate).  This is problematic, especially as the number of
   caching extensions grows, along with the number of potential targets.

   Some caches have defined ad hoc control mechanisms to overcome this
   issue, but interoperability is low.  Section 2 defines a standard
   framework for targeted cache control using HTTP response headers, and
   Section 3 defines one such header: the CDN-Cache-Control response
   header field.

1.1.  Notational Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

2.  Targeted Cache-Control Header Fields

   A Targeted Cache-Control Header Field (hereafter, "targeted field")
   is a HTTP response header field that has the same syntax and
   semantics as the Cache-Control response header field
   [I-D.ietf-httpbis-cache], Section 5.2.  However, it has a distinct
   field name that indicates the target for its directives.

   For example:

   CDN-Cache-Control: max-age=60

   is a targeted field that applies to Content Delivery Networks (CDNs),
   as defined in Section 3.

2.1.  Cache Behavior

   A cache that implement this specification has a _target list_ - an
   ordered list of the targeted field names that it uses for caching
   policy, with the order reflecting priority from most applicable to
   least.  The target list might be fixed, user-configurable, or
   generated per request, depending upon the implementation.

   For example, a CDN cache might support both CDN-Cache-Control and a
   header specific to that CDN, ExampleCDN-Cache-Control, with the
   latter overriding the former.  Its target list would be:

Ludin, et al.            Expires 27 January 2022                [Page 3]

Internet-Draft         Targeted HTTP Cache Control             July 2021

     [ExampleCDN-Cache-Control, CDN-Cache-Control]

   When a cache that implements this specification receives a response
   with one or more of of the header field names on its target list, the
   cache MUST select the first (in target list order) field with a
   valid, non-empty value and use that to determine the caching policy
   for the response, and MUST ignore the Cache-Control and Expires
   header fields in that response, unless no valid, non-empty value is
   available from the listed header fields.

   Note that this is on a response-by-response basis; if no applicable
   targeted field is present, valid and non-empty, a cache falls back to
   other cache control mechanisms as required by HTTP

   Targeted fields that are not on a cache's target list MUST NOT change
   that cache's behaviour, and MUST be passed through.

   Caches that use a targeted field MUST implement the semantics of the
   following cache directives:

   *  max-age

   *  must-revalidate

   *  no-store

   *  no-cache

   *  private

   Furthermore, they SHOULD implement other cache directives (including
   extension cache directives) that they support in the Cache-Control
   response header field.

   The semantics and precedence of cache directives in a targeted field
   are the same as those in Cache-Control.  In particular, no-store and
   no-cache make max-age inoperative.

2.2.  Parsing Targeted Fields

   Targeted fields MAY be parsed as a Dictionary Structured Field
   [RFC8941], and implementations are encouraged to use a parser for
   that format in the interests of robustness, interoperability and

Ludin, et al.            Expires 27 January 2022                [Page 4]

Internet-Draft         Targeted HTTP Cache Control             July 2021

   When an implementation parses a targeted field as a Structured Field,
   each cache directive will be assigned a value.  For example, max-age
   has an integer value; no-store's value is boolean true, and no-
   cache's value can either be boolean true or a list of field names.
   Implementations SHOULD NOT accept other values (e.g. coerce a max-age
   with a decimal value into an integer).  Likewise, implementations
   SHOULD ignore parameters on directives, unless otherwise specified.

   However, implementers MAY reuse a Cache-Control parser for
   simplicity.  If they do so, they SHOULD observe the following points,
   to aid in a smooth transition to a full Structured Field parser and
   prevent interoperability issues:

   *  If a directive is repeated in the field value (e.g., "max-age=30,
      max-age=60"), the last value 'wins' (60, in this case)

   *  Members of the directives can have parameters (e.g., "max-
      age=30;a=b;c=d"), which should be ignored unless specified.

   If a targeted field in a given response is empty, or a parsing error
   is encountered (when being parsed as a Structured Field), that field
   SHOULD be ignored by the cache (i.e., it should behave as if the
   field were not present, likely falling back to other cache control
   mechanisms present).

2.3.  Defining Targeted Fields

   A targeted field for a particular class of cache can be defined by
   requesting registration in the Hypertext Transfer Protocol (HTTP)
   Field Name Registry
   (, listing this
   specification as the specification document.  The Comments field of
   the registration SHOULD clearly define the class of caches that the
   targeted field applies to.

   By convention, targeted fields SHOULD have the suffix "-Cache-
   Control": e.g., "ExampleCDN-Cache-Control".  However, this suffix
   MUST NOT be used on its own to identify targeted fields; it is only a

3.  The CDN-Cache-Control Targeted Field

   The CDN-Cache-Control response header field is a targeted field
   Section 2 that allows origin servers to control the behaviour of CDN
   caches interposed between them and clients, separately from other
   caches that might handle the response.

Ludin, et al.            Expires 27 January 2022                [Page 5]

Internet-Draft         Targeted HTTP Cache Control             July 2021

   It applies to caches that are part of a distributed network that
   operate on behalf of an origin server (commonly called a Content
   Delivery Network or CDN).

   CDN caches that use CDN-Cache-Control MAY forward this header so that
   downstream CDN caches can use it as well.  However, doing so exposes
   its value to all downstream clients, which might be undesirable.  As
   a result, CDN caches that process this header field MAY remove it
   (for example, when configured to do so because it is known not to be
   used downstream).

3.1.  Examples

   For example, the following header fields would instruct a CDN cache
   to consider the response fresh for 600 seconds, other shared caches
   for 120 seconds and any remaining caches for 60 seconds:

   Cache-Control: max-age=60, s-maxage=120
   CDN-Cache-Control: max-age=600

   These header fields would instruct a CDN cache to consider the
   response fresh for 600 seconds, while all other caches would be
   prevented from storing it:

   Cache-Control: no-store
   CDN-Cache-Control: max-age=600

   Because CDN-Cache-Control is not present, this header field would
   prevent all caches from storing the response:

   Cache-Control: no-store

   Whereas these would prevent all caches except for CDN caches from
   storing the response:

   Cache-Control: no-store
   CDN-Cache-Control: none

   (note that 'none' is not a registered cache directive; it is here to
   avoid sending a header field with an empty value, because such a
   header might not be preserved in all cases)

4.  IANA Considerations

   Please register the following entry in the Hypertext Transfer
   Protocol (HTTP) Field Name Registry defined by

Ludin, et al.            Expires 27 January 2022                [Page 6]

Internet-Draft         Targeted HTTP Cache Control             July 2021

   *  Field Name: CDN-Cache-Control

   *  Status: permanent

   *  Specification Document: [this document]

   *  Comments: Cache-Control directives targeted at Content Delivery

5.  Security Considerations

   The security considerations of HTTP caching [I-D.ietf-httpbis-cache]

   The ability to carry multiple caching policies on a response can
   result in confusion about how a response will be cached in different
   systems, if not used carefully.  This might result in unintentional
   reuse of responses with sensitive information.

6.  Normative References

              Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP
              Caching", Work in Progress, Internet-Draft, draft-ietf-
              httpbis-cache-17, 25 July 2021,

              Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP
              Semantics", Work in Progress, Internet-Draft, draft-ietf-
              httpbis-semantics-17, 25 July 2021,

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <>.

   [RFC8941]  Nottingham, M. and P-H. Kamp, "Structured Field Values for
              HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,

Ludin, et al.            Expires 27 January 2022                [Page 7]

Internet-Draft         Targeted HTTP Cache Control             July 2021

Authors' Addresses

   Stephen Ludin


   Mark Nottingham


   Yuchen Wu


Ludin, et al.            Expires 27 January 2022                [Page 8]