idnits 2.17.1 draft-cdn-control-header-01.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 (17 March 2021) is 1136 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'ExampleCDN-Cache-Control' is mentioned on line 148, but not defined == Missing Reference: 'CDN-Cache-Control' is mentioned on line 148, but not defined == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-cache-14 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). 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: Informational M. Nottingham 5 Expires: 18 September 2021 Fastly 6 Y. Wu 7 Cloudflare 8 17 March 2021 10 Targeted HTTP Response Header Fields for Cache Control 11 draft-cdn-control-header-01 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 https://github.com/ 25 cdn-specs/control-header/issues (https://github.com/cdn-specs/ 26 control-header/issues). 28 The most recent (often, unpublished) draft is at https://cdn- 29 specs.github.io/control-header/ (https://cdn-specs.github.io/control- 30 header/). 32 Recent changes are listed at https://github.com/cdn-specs/control- 33 header/commits/main (https://github.com/cdn-specs/control- 34 header/commits/main). 36 See also the draft's current status in the IETF datatracker, at 37 https://datatracker.ietf.org/doc/draft-cdn-control-header/ 38 (https://datatracker.ietf.org/doc/draft-cdn-control-header/). 40 Status of This Memo 42 This Internet-Draft is submitted in full conformance with the 43 provisions of BCP 78 and BCP 79. 45 Internet-Drafts are working documents of the Internet Engineering 46 Task Force (IETF). Note that other groups may also distribute 47 working documents as Internet-Drafts. The list of current Internet- 48 Drafts is at https://datatracker.ietf.org/drafts/current/. 50 Internet-Drafts are draft documents valid for a maximum of six months 51 and may be updated, replaced, or obsoleted by other documents at any 52 time. It is inappropriate to use Internet-Drafts as reference 53 material or to cite them other than as "work in progress." 55 This Internet-Draft will expire on 18 September 2021. 57 Copyright Notice 59 Copyright (c) 2021 IETF Trust and the persons identified as the 60 document authors. All rights reserved. 62 This document is subject to BCP 78 and the IETF Trust's Legal 63 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 64 license-info) in effect on the date of publication of this document. 65 Please review these documents carefully, as they describe your rights 66 and restrictions with respect to this document. Code Components 67 extracted from this document must include Simplified BSD License text 68 as described in Section 4.e of the Trust Legal Provisions and are 69 provided without warranty as described in the Simplified BSD License. 71 Table of Contents 73 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 74 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 75 2. Targeted Cache-Control Header Fields . . . . . . . . . . . . 3 76 2.1. Cache Behavior . . . . . . . . . . . . . . . . . . . . . 3 77 2.2. Parsing Targeted Fields . . . . . . . . . . . . . . . . . 4 78 2.3. Defining Targeted Fields . . . . . . . . . . . . . . . . 5 79 3. The CDN-Cache-Control Targeted Field . . . . . . . . . . . . 5 80 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 6 81 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 82 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 83 6. Normative References . . . . . . . . . . . . . . . . . . . . 7 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 86 1. Introduction 88 Modern deployments of HTTP often use multiple layers of caching with 89 varying properties. For example, a Web site might use a cache on the 90 origin server itself; it might deploy a caching layer in the same 91 network as the origin server, it might use one or more Content 92 Delivery Networks (CDNs) that are distributed throughout the 93 Internet, and it might utilise browser caching as well. 95 Because it is often desirable to control these different classes of 96 caches separately, some means of targeting directives at them is 97 necessary. 99 The HTTP Cache-Control response header field is widely used to direct 100 caching behavior. However, it is relatively undifferentiated; while 101 some directives (e.g., s-maxage) are targeted at a specific class of 102 caches (for s-maxage, shared caches), that is not consistently 103 available across all existing cache directives (e.g., stale-while- 104 revalidate). This is problematic, especially as the number of 105 caching extensions grows, along with the number of potential targets. 107 Some caches have defined ad hoc control mechanisms to overcome this 108 issue, but interoperability is low. Section 2 defines a standard 109 framework for targeted cache control using HTTP response headers, and 110 Section 3 defines one such header: the CDN-Cache-Control response 111 header field. 113 1.1. Notational Conventions 115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 117 "OPTIONAL" in this document are to be interpreted as described in BCP 118 14 [RFC2119] [RFC8174] when, and only when, they appear in all 119 capitals, as shown here. 121 2. Targeted Cache-Control Header Fields 123 A Targeted Cache-Control Header Field (hereafter, "targeted field") 124 is a HTTP response header field that has the same syntax and 125 semantics as the Cache-Control response header field 126 [I-D.ietf-httpbis-cache], Section 5.2. However, it has a distinct 127 field name that indicates the target for its directives. 129 For example: 131 CDN-Cache-Control: max-age=60 133 is a targeted field that applies to Content Delivery Networks (CDNs), 134 as defined in Section 3. 136 2.1. Cache Behavior 138 A cache that implement this specification has a _target list_ - an 139 ordered list of the targeted field names that it uses for caching 140 policy, with the order reflecting priority from most applicable to 141 least. The target list might be fixed, user-configurable, or 142 generated per request, depending upon the implementation. 144 For example, a CDN cache might support both CDN-Cache-Control and a 145 header specific to that CDN, ExampleCDN-Cache-Control, with the 146 latter overriding the former. Its target list would be: 148 [ExampleCDN-Cache-Control, CDN-Cache-Control] 150 When a cache that implements this specification receives a response 151 with one or more of of the header field names on its target list, the 152 cache MUST select the first (in target list order) field with a 153 valid, non-empty value and use that to determine the caching policy 154 for the response, and MUST ignore the Cache-Control and Expires 155 header fields in that response, unless no valid, non-empty value is 156 available from the listed header fields. 158 Note that this is on a response-by-response basis; if no applicable 159 targeted field is present, valid and non-empty, a cache falls back to 160 other cache control mechanisms as required by HTTP 161 [I-D.ietf-httpbis-cache]. 163 Targeted fields that are not on a cache's target list MUST NOT change 164 that cache's behaviour, and MUST be passed through. 166 Caches that use a targeted field MUST implement the semantics of the 167 following cache directives: 169 * max-age 171 * must-revalidate 173 * no-store 175 * no-cache 177 * private 179 Furthermore, they SHOULD implement other cache directives (including 180 extension cache directives) that they support in the Cache-Control 181 response header field. 183 The semantics and precedence of cache directives in a targeted field 184 are the same as those in Cache-Control. In particular, no-store and 185 no-cache make max-age inoperative. 187 2.2. Parsing Targeted Fields 189 Targeted fields MAY be parsed as a Dictionary Structured Field 190 [RFC8941], and implementations are encouraged to use a parser for 191 that format in the interests of robustness, interoperability and 192 security. 194 When an implementation parses a targeted field as a Structured Field, 195 each cache directive will be assigned a value. For example, max-age 196 has an integer value; no-store's value is boolean true, and no- 197 cache's value can either be boolean true or a list of field names. 198 Implementations SHOULD NOT accept other values (e.g. coerce a max-age 199 with a decimal value into an integer). Likewise, implementations 200 SHOULD ignore parameters on directives, unless otherwise specified. 202 However, implementers MAY reuse a Cache-Control parser for 203 simplicity. If they do so, they SHOULD observe the following points, 204 to aid in a smooth transition to a full Structured Field parser and 205 prevent interoperability issues: 207 * If a directive is repeated in the field value (e.g., "max-age=30, 208 max-age=60"), the last value 'wins' (60, in this case) 210 * Members of the directives can have parameters (e.g., "max- 211 age=30;a=b;c=d"), which should be ignored unless specified. 213 If a targeted field in a given response is empty, or a parsing error 214 is encountered (when being parsed as a Structured Field), that field 215 SHOULD be ignored by the cache (i.e., it should behave as if the 216 field were not present, likely falling back to other cache control 217 mechanisms present). 219 2.3. Defining Targeted Fields 221 A targeted field for a particular class of cache can be defined by 222 requesting registration in the Hypertext Transfer Protocol (HTTP) 223 Field Name Registry https://www.iana.org/assignments/http-fields/ 224 (https://www.iana.org/assignments/http-fields/), listing this 225 specification as the specification document. The Comments field of 226 the registration SHOULD clearly define the class of caches that the 227 targeted field applies to. 229 By convention, targeted fields SHOULD have the suffix "-Cache- 230 Control": e.g., "ExampleCDN-Cache-Control". However, this suffix 231 MUST NOT be used on its own to identify targeted fields; it is only a 232 convention. 234 3. The CDN-Cache-Control Targeted Field 236 The CDN-Cache-Control response header field is a targeted field 237 Section 2 that allows origin servers to control the behaviour of CDN 238 caches interposed between them and clients, separately from other 239 caches that might handle the response. 241 It applies to caches that are part of a distributed network that 242 operate on behalf of an origin server (commonly called a Content 243 Delivery Network or CDN). 245 CDN caches that use CDN-Cache-Control MAY forward this header so that 246 downstream CDN caches can use it as well. However, doing so exposes 247 its value to all downstream clients, which might be undesirable. As 248 a result, CDN caches that process this header field MAY remove it 249 (for example, when configured to do so because it is known not to be 250 used downstream). 252 3.1. Examples 254 For example, the following header fields would instruct a CDN cache 255 to consider the response fresh for 600 seconds, other shared caches 256 for 120 seconds and any remaining caches for 60 seconds: 258 Cache-Control: max-age=60, s-maxage=120 259 CDN-Cache-Control: max-age=600 261 These header fields would instruct a CDN cache to consider the 262 response fresh for 600 seconds, while all other caches would be 263 prevented from storing it: 265 Cache-Control: no-store 266 CDN-Cache-Control: max-age=600 268 Because CDN-Cache-Control is not present, this header field would 269 prevent all caches from storing the response: 271 Cache-Control: no-store 273 Whereas these would prevent all caches except for CDN caches from 274 storing the response: 276 Cache-Control: no-store 277 CDN-Cache-Control: none 279 (note that 'none' is not a registered cache directive; it is here to 280 avoid sending a header field with an empty value, because such a 281 header might not be preserved in all cases) 283 4. IANA Considerations 285 _TBD_ 287 5. Security Considerations 289 The security considerations of HTTP caching [I-D.ietf-httpbis-cache] 290 apply. 292 The ability to carry multiple caching policies on a response can 293 result in confusion about how a response will be cached in different 294 systems, if not used carefully. This might result in unintentional 295 reuse of responses with sensitive information. 297 6. Normative References 299 [I-D.ietf-httpbis-cache] 300 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 301 Caching", Work in Progress, Internet-Draft, draft-ietf- 302 httpbis-cache-14, 12 January 2021, 303 . 305 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 306 Requirement Levels", BCP 14, RFC 2119, 307 DOI 10.17487/RFC2119, March 1997, 308 . 310 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 311 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 312 May 2017, . 314 [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for 315 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 316 . 318 Authors' Addresses 320 Stephen Ludin 321 Akamai 323 Email: sludin@ludin.org 325 Mark Nottingham 326 Fastly 327 Prahran VIC 328 Australia 330 Email: mnot@mnot.net 331 URI: https://www.mnot.net/ 332 Yuchen Wu 333 Cloudflare 335 Email: me@yuchenwu.net