idnits 2.17.1 draft-ietf-httpbis-targeted-cache-control-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (26 July 2021) is 1005 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'ExampleCDN-Cache-Control' is mentioned on line 146, but not defined == Missing Reference: 'CDN-Cache-Control' is mentioned on line 146, but not defined == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-cache-17 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-httpbis-cache' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-17 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-httpbis-semantics' Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP S. Ludin 3 Internet-Draft Akamai 4 Intended status: Standards Track M. Nottingham 5 Expires: 27 January 2022 Fastly 6 Y. Wu 7 Cloudflare 8 26 July 2021 10 Targeted HTTP Cache Control 11 draft-ietf-httpbis-targeted-cache-control-00 13 Abstract 15 This specification defines a convention for HTTP response header 16 fields that allow directives controlling caching to be targeted at 17 specific caches or classes of caches. It also defines one such 18 header field, targeted at Content Delivery Network (CDN) caches. 20 Note to Readers 22 _RFC EDITOR: please remove this section before publication_ 24 The issues list for this draft can be found at 25 https://github.com/httpwg/http-extensions/labels/targeted-cc 26 (https://github.com/httpwg/http-extensions/labels/targeted-cc). 28 The most recent (often, unpublished) draft is at https://httpwg.org/ 29 http-extensions/draft-ietf-httpbis-targeted-cache-control.html 30 (https://httpwg.org/http-extensions/draft-ietf-httpbis-targeted- 31 cache-control.html). 33 See also the draft's current status in the IETF datatracker, at 34 https://datatracker.ietf.org/doc/draft-ietf-httpbis-targeted-cache- 35 control/ (https://datatracker.ietf.org/doc/draft-ietf-httpbis- 36 targeted-cache-control/). 38 Status of This Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at https://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on 27 January 2022. 55 Copyright Notice 57 Copyright (c) 2021 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 62 license-info) in effect on the date of publication of this document. 63 Please review these documents carefully, as they describe your rights 64 and restrictions with respect to this document. Code Components 65 extracted from this document must include Simplified BSD License text 66 as described in Section 4.e of the Trust Legal Provisions and are 67 provided without warranty as described in the Simplified BSD License. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 72 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 73 2. Targeted Cache-Control Header Fields . . . . . . . . . . . . 3 74 2.1. Cache Behavior . . . . . . . . . . . . . . . . . . . . . 3 75 2.2. Parsing Targeted Fields . . . . . . . . . . . . . . . . . 4 76 2.3. Defining Targeted Fields . . . . . . . . . . . . . . . . 5 77 3. The CDN-Cache-Control Targeted Field . . . . . . . . . . . . 5 78 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 6 79 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 80 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 81 6. Normative References . . . . . . . . . . . . . . . . . . . . 7 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 84 1. Introduction 86 Modern deployments of HTTP often use multiple layers of caching with 87 varying properties. For example, a Web site might use a cache on the 88 origin server itself; it might deploy a caching layer in the same 89 network as the origin server, it might use one or more Content 90 Delivery Networks (CDNs) that are distributed throughout the 91 Internet, and it might utilise browser caching as well. 93 Because it is often desirable to control these different classes of 94 caches separately, some means of targeting directives at them is 95 necessary. 97 The HTTP Cache-Control response header field is widely used to direct 98 caching behavior. However, it is relatively undifferentiated; while 99 some directives (e.g., s-maxage) are targeted at a specific class of 100 caches (for s-maxage, shared caches), that is not consistently 101 available across all existing cache directives (e.g., stale-while- 102 revalidate). This is problematic, especially as the number of 103 caching extensions grows, along with the number of potential targets. 105 Some caches have defined ad hoc control mechanisms to overcome this 106 issue, but interoperability is low. Section 2 defines a standard 107 framework for targeted cache control using HTTP response headers, and 108 Section 3 defines one such header: the CDN-Cache-Control response 109 header field. 111 1.1. Notational Conventions 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 115 "OPTIONAL" in this document are to be interpreted as described in BCP 116 14 [RFC2119] [RFC8174] when, and only when, they appear in all 117 capitals, as shown here. 119 2. Targeted Cache-Control Header Fields 121 A Targeted Cache-Control Header Field (hereafter, "targeted field") 122 is a HTTP response header field that has the same syntax and 123 semantics as the Cache-Control response header field 124 [I-D.ietf-httpbis-cache], Section 5.2. However, it has a distinct 125 field name that indicates the target for its directives. 127 For example: 129 CDN-Cache-Control: max-age=60 131 is a targeted field that applies to Content Delivery Networks (CDNs), 132 as defined in Section 3. 134 2.1. Cache Behavior 136 A cache that implement this specification has a _target list_ - an 137 ordered list of the targeted field names that it uses for caching 138 policy, with the order reflecting priority from most applicable to 139 least. The target list might be fixed, user-configurable, or 140 generated per request, depending upon the implementation. 142 For example, a CDN cache might support both CDN-Cache-Control and a 143 header specific to that CDN, ExampleCDN-Cache-Control, with the 144 latter overriding the former. Its target list would be: 146 [ExampleCDN-Cache-Control, CDN-Cache-Control] 148 When a cache that implements this specification receives a response 149 with one or more of of the header field names on its target list, the 150 cache MUST select the first (in target list order) field with a 151 valid, non-empty value and use that to determine the caching policy 152 for the response, and MUST ignore the Cache-Control and Expires 153 header fields in that response, unless no valid, non-empty value is 154 available from the listed header fields. 156 Note that this is on a response-by-response basis; if no applicable 157 targeted field is present, valid and non-empty, a cache falls back to 158 other cache control mechanisms as required by HTTP 159 [I-D.ietf-httpbis-cache]. 161 Targeted fields that are not on a cache's target list MUST NOT change 162 that cache's behaviour, and MUST be passed through. 164 Caches that use a targeted field MUST implement the semantics of the 165 following cache directives: 167 * max-age 169 * must-revalidate 171 * no-store 173 * no-cache 175 * private 177 Furthermore, they SHOULD implement other cache directives (including 178 extension cache directives) that they support in the Cache-Control 179 response header field. 181 The semantics and precedence of cache directives in a targeted field 182 are the same as those in Cache-Control. In particular, no-store and 183 no-cache make max-age inoperative. 185 2.2. Parsing Targeted Fields 187 Targeted fields MAY be parsed as a Dictionary Structured Field 188 [RFC8941], and implementations are encouraged to use a parser for 189 that format in the interests of robustness, interoperability and 190 security. 192 When an implementation parses a targeted field as a Structured Field, 193 each cache directive will be assigned a value. For example, max-age 194 has an integer value; no-store's value is boolean true, and no- 195 cache's value can either be boolean true or a list of field names. 196 Implementations SHOULD NOT accept other values (e.g. coerce a max-age 197 with a decimal value into an integer). Likewise, implementations 198 SHOULD ignore parameters on directives, unless otherwise specified. 200 However, implementers MAY reuse a Cache-Control parser for 201 simplicity. If they do so, they SHOULD observe the following points, 202 to aid in a smooth transition to a full Structured Field parser and 203 prevent interoperability issues: 205 * If a directive is repeated in the field value (e.g., "max-age=30, 206 max-age=60"), the last value 'wins' (60, in this case) 208 * Members of the directives can have parameters (e.g., "max- 209 age=30;a=b;c=d"), which should be ignored unless specified. 211 If a targeted field in a given response is empty, or a parsing error 212 is encountered (when being parsed as a Structured Field), that field 213 SHOULD be ignored by the cache (i.e., it should behave as if the 214 field were not present, likely falling back to other cache control 215 mechanisms present). 217 2.3. Defining Targeted Fields 219 A targeted field for a particular class of cache can be defined by 220 requesting registration in the Hypertext Transfer Protocol (HTTP) 221 Field Name Registry https://www.iana.org/assignments/http-fields/ 222 (https://www.iana.org/assignments/http-fields/), listing this 223 specification as the specification document. The Comments field of 224 the registration SHOULD clearly define the class of caches that the 225 targeted field applies to. 227 By convention, targeted fields SHOULD have the suffix "-Cache- 228 Control": e.g., "ExampleCDN-Cache-Control". However, this suffix 229 MUST NOT be used on its own to identify targeted fields; it is only a 230 convention. 232 3. The CDN-Cache-Control Targeted Field 234 The CDN-Cache-Control response header field is a targeted field 235 Section 2 that allows origin servers to control the behaviour of CDN 236 caches interposed between them and clients, separately from other 237 caches that might handle the response. 239 It applies to caches that are part of a distributed network that 240 operate on behalf of an origin server (commonly called a Content 241 Delivery Network or CDN). 243 CDN caches that use CDN-Cache-Control MAY forward this header so that 244 downstream CDN caches can use it as well. However, doing so exposes 245 its value to all downstream clients, which might be undesirable. As 246 a result, CDN caches that process this header field MAY remove it 247 (for example, when configured to do so because it is known not to be 248 used downstream). 250 3.1. Examples 252 For example, the following header fields would instruct a CDN cache 253 to consider the response fresh for 600 seconds, other shared caches 254 for 120 seconds and any remaining caches for 60 seconds: 256 Cache-Control: max-age=60, s-maxage=120 257 CDN-Cache-Control: max-age=600 259 These header fields would instruct a CDN cache to consider the 260 response fresh for 600 seconds, while all other caches would be 261 prevented from storing it: 263 Cache-Control: no-store 264 CDN-Cache-Control: max-age=600 266 Because CDN-Cache-Control is not present, this header field would 267 prevent all caches from storing the response: 269 Cache-Control: no-store 271 Whereas these would prevent all caches except for CDN caches from 272 storing the response: 274 Cache-Control: no-store 275 CDN-Cache-Control: none 277 (note that 'none' is not a registered cache directive; it is here to 278 avoid sending a header field with an empty value, because such a 279 header might not be preserved in all cases) 281 4. IANA Considerations 283 Please register the following entry in the Hypertext Transfer 284 Protocol (HTTP) Field Name Registry defined by 285 [I-D.ietf-httpbis-semantics]: 287 * Field Name: CDN-Cache-Control 289 * Status: permanent 291 * Specification Document: [this document] 293 * Comments: Cache-Control directives targeted at Content Delivery 294 Networks 296 5. Security Considerations 298 The security considerations of HTTP caching [I-D.ietf-httpbis-cache] 299 apply. 301 The ability to carry multiple caching policies on a response can 302 result in confusion about how a response will be cached in different 303 systems, if not used carefully. This might result in unintentional 304 reuse of responses with sensitive information. 306 6. Normative References 308 [I-D.ietf-httpbis-cache] 309 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 310 Caching", Work in Progress, Internet-Draft, draft-ietf- 311 httpbis-cache-17, 25 July 2021, 312 . 315 [I-D.ietf-httpbis-semantics] 316 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 317 Semantics", Work in Progress, Internet-Draft, draft-ietf- 318 httpbis-semantics-17, 25 July 2021, 319 . 322 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 323 Requirement Levels", BCP 14, RFC 2119, 324 DOI 10.17487/RFC2119, March 1997, 325 . 327 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 328 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 329 May 2017, . 331 [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for 332 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 333 . 335 Authors' Addresses 337 Stephen Ludin 338 Akamai 340 Email: sludin@ludin.org 342 Mark Nottingham 343 Fastly 344 Prahran 345 VIC 346 Australia 348 Email: mnot@mnot.net 349 URI: https://www.mnot.net/ 351 Yuchen Wu 352 Cloudflare 354 Email: me@yuchenwu.net