idnits 2.17.1 draft-ietf-httpbis-cache-header-08.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 (20 April 2021) is 1074 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP M. Nottingham 3 Internet-Draft Fastly 4 Intended status: Standards Track 20 April 2021 5 Expires: 22 October 2021 7 The Cache-Status HTTP Response Header Field 8 draft-ietf-httpbis-cache-header-08 10 Abstract 12 To aid debugging, HTTP caches often append header fields to a 13 response explaining how they handled the request. This specification 14 codifies that practice and updates it to align with HTTP's current 15 caching model. 17 Note to Readers 19 _RFC EDITOR: please remove this section before publication_ 21 Discussion of this draft takes place on the HTTP working group 22 mailing list (ietf-http-wg@w3.org), which is archived at 23 https://lists.w3.org/Archives/Public/ietf-http-wg/ 24 (https://lists.w3.org/Archives/Public/ietf-http-wg/). 26 Working Group information can be found at https://httpwg.org/ 27 (https://httpwg.org/); source code and issues list for this draft can 28 be found at https://github.com/httpwg/http-extensions/labels/cache- 29 header (https://github.com/httpwg/http-extensions/labels/cache- 30 header). 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on 22 October 2021. 49 Copyright Notice 51 Copyright (c) 2021 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 56 license-info) in effect on the date of publication of this document. 57 Please review these documents carefully, as they describe your rights 58 and restrictions with respect to this document. Code Components 59 extracted from this document must include Simplified BSD License text 60 as described in Section 4.e of the Trust Legal Provisions and are 61 provided without warranty as described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 66 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 67 2. The Cache-Status HTTP Response Header Field . . . . . . . . . 3 68 2.1. The hit parameter . . . . . . . . . . . . . . . . . . . . 4 69 2.2. The fwd parameter . . . . . . . . . . . . . . . . . . . . 4 70 2.3. The fwd-status parameter . . . . . . . . . . . . . . . . 5 71 2.4. The ttl parameter . . . . . . . . . . . . . . . . . . . . 5 72 2.5. The stored parameter . . . . . . . . . . . . . . . . . . 5 73 2.6. The collapsed parameter . . . . . . . . . . . . . . . . . 6 74 2.7. The key parameter . . . . . . . . . . . . . . . . . . . . 6 75 2.8. The detail parameter . . . . . . . . . . . . . . . . . . 6 76 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6 77 4. Defining New Cache-Status Parameters . . . . . . . . . . . . 7 78 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 79 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 80 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 81 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 82 7.2. Informative References . . . . . . . . . . . . . . . . . 9 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 85 1. Introduction 87 To aid debugging, HTTP caches often append header fields to a 88 response explaining how they handled the request. Unfortunately, the 89 semantics of these headers are often unclear, and both the semantics 90 and syntax used vary between implementations. 92 This specification defines a new HTTP response header field, "Cache- 93 Status" for this purpose. 95 1.1. Notational Conventions 97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 99 "OPTIONAL" in this document are to be interpreted as described in BCP 100 14 [RFC2119] [RFC8174] when, and only when, they appear in all 101 capitals, as shown here. 103 This document uses ABNF as defined in [RFC5234]. 105 2. The Cache-Status HTTP Response Header Field 107 The Cache-Status HTTP response header field indicates caches' 108 handling of the request corresponding to the response it occurs 109 within. 111 Its value is a List [RFC8941], Section 3.1: 113 Cache-Status = sf-list 115 Each member of the list represents a cache that has handled the 116 request. The first member of the list represents the cache closest 117 to the origin server, and the last member of the list represents the 118 cache closest to the user (possibly including the user agent's cache 119 itself, if it appends a value). 121 The Cache-Status header field is only applicable to responses that 122 are generated by an origin server. An intermediary SHOULD NOT append 123 a Cache-Status member to responses that it generates, even if that 124 intermediary contains a cache, except when the generated response is 125 based upon a stored response (e.g., a 304 Not Modified or 206 Partial 126 Content). 128 Caches determine when it is appropriate to add the Cache-Status 129 header field to a response. Some might add it to all responses, 130 whereas others might only do so when specifically configured to, or 131 when the request contains a header field that activates a debugging 132 mode. 134 When adding a value to the Cache-Status header field, caches SHOULD 135 preserve the existing field value, to allow debugging of the entire 136 chain of caches handling the request. 138 Each list member identifies the cache that inserted it and MUST be a 139 String or Token. Depending on the deployment, this might be a 140 product or service name (e.g., ExampleCache or "Example CDN"), a 141 hostname ("cache-3.example.com"), an IP address, or a generated 142 string. 144 Each member of the list can have parameters that describe that 145 cache's handling of the request. While these parameters are 146 OPTIONAL, caches are encouraged to provide as much information as 147 possible. 149 This specification defines the following parameters: 151 hit = sf-boolean 152 fwd = sf-token 153 fwd-status = sf-integer 154 ttl = sf-integer 155 stored = sf-boolean 156 collapsed = sf-boolean 157 key = sf-string 158 detail = sf-token / sf-string 160 2.1. The hit parameter 162 "hit", when true, indicates that the request was satisfied by the 163 cache; i.e., it was not forwarded, and the response was obtained from 164 the cache. 166 A response that was originally produced by the origin but was 167 modified by the cache (for example, a 304 or 206 status code) is 168 still considered a hit, as long as it did not go forward (e.g., for 169 validation). 171 A response that was in cache but not able to be used without going 172 forward (e.g., because it was stale, or partial) is not considered a 173 hit. Note that a stale response that is used without going forward 174 (e.g., because the origin server is not available) can be considered 175 a hit. 177 "hit" and "fwd" are exclusive; only one of them should appear on each 178 list member. 180 2.2. The fwd parameter 182 "fwd" indicates that the request went forward towards the origin, and 183 why. 185 The following parameter values are defined to explain why the request 186 went forward, from most specific to least: 188 * bypass - The cache was configured to not handle this request 190 * method - The request method's semantics require the request to be 191 forwarded 193 * uri-miss - The cache did not contain any responses that matched 194 the request URI 196 * vary-miss - The cache contained a response that matched the 197 request URI, but could not select a response based upon this 198 request's headers and stored Vary headers. 200 * miss - The cache did not contain any responses that could be used 201 to satisfy this request (to be used when an implementation cannot 202 distinguish between uri-miss and vary-miss) 204 * request - The cache was able to select a fresh response for the 205 request, but the request's semantics (e.g., Cache-Control request 206 directives) did not allow its use 208 * stale - The cache was able to select a response for the request, 209 but it was stale 211 * partial - The cache was able to select a partial response for the 212 request, but it did not contain all of the requested ranges (or 213 the request was for the complete response) 215 The most specific reason that the cache is aware of SHOULD be used. 217 2.3. The fwd-status parameter 219 "fwd-status" indicates what status code the next hop server returned 220 in response to the request. Only meaningful when "fwd" is present; 221 if "fwd-status" is not present but "fwd" is, it defaults to the 222 status code sent in the response. 224 This parameter is useful to distinguish cases when the next hop 225 server sends a 304 Not Modified response to a conditional request, or 226 a 206 Partial Response because of a range request. 228 2.4. The ttl parameter 230 "ttl" indicates the response's remaining freshness lifetime as 231 calculated by the cache, as an integer number of seconds, measured 232 when the response header section is sent by the cache. This includes 233 freshness assigned by the cache; e.g., through heuristics, local 234 configuration, or other factors. May be negative, to indicate 235 staleness. 237 2.5. The stored parameter 239 "stored" indicates whether the cache stored the response; a true 240 value indicates that it did. Only meaningful when fwd is present. 242 2.6. The collapsed parameter 244 "collapsed" indicates whether this request was collapsed together 245 with one or more other forward requests; if true, the response was 246 successfully reused; if not, a new request had to be made. If not 247 present, the request was not collapsed with others. Only meaningful 248 when fwd is present. 250 2.7. The key parameter 252 "key" conveys a representation of the cache key used for the 253 response. Note that this may be implementation-specific. 255 2.8. The detail parameter 257 "detail" allows implementations to convey additional information not 258 captured in other parameters; for example, implementation-specific 259 states, or other caching-related metrics. 261 For example: 263 Cache-Status: ExampleCache; hit; detail=MEMORY 265 The semantics of a detail parameter are always specific to the cache 266 that sent it; even if a member of details from another cache shares 267 the same name, it might not mean the same thing. 269 This parameter is intentionally limited. If an implementation's 270 developer or operator needs to convey additional information in an 271 interoperable fashion, they are encouraged to register extension 272 parameters (see Section 4) or define another header field. 274 3. Examples 276 The most minimal cache hit: 278 Cache-Status: ExampleCache; hit 280 ... but a polite cache will give some more information, e.g.: 282 Cache-Status: ExampleCache; hit; ttl=376 284 A stale hit just has negative freshness: 286 Cache-Status: ExampleCache; hit; ttl=-412 288 Whereas a complete miss is: 290 Cache-Status: ExampleCache; fwd=uri-miss 292 A miss that successfully validated on the back-end server: 294 Cache-Status: ExampleCache; fwd=stale; fwd-status=304 296 A miss that was collapsed with another request: 298 Cache-Status: ExampleCache; fwd=uri-miss; collapsed 300 A miss that the cache attempted to collapse, but couldn't: 302 Cache-Status: ExampleCache; fwd=uri-miss; collapsed=?0 304 Going through two separate layers of caching, where the cache closest 305 to the origin responded to an earlier request with a stored response, 306 and a second cache stored that response and later reused it to 307 satisfy the current request: 309 Cache-Status: OriginCache; hit; ttl=1100, 310 "CDN Company Here"; hit; ttl=545 312 4. Defining New Cache-Status Parameters 314 New Cache-Status Parameters can be defined by registering them in the 315 HTTP Cache-Status Parameters registry. 317 Registration requests are reviewed and approved by a Designated 318 Expert, as per [RFC8126], Section 4.5. A specification document is 319 appreciated, but not required. 321 The Expert(s) should consider the following factors when evaluating 322 requests: 324 * Community feedback 326 * If the value is sufficiently well-defined 328 * Generic parameters are preferred over vendor-specific, 329 application-specific, or deployment-specific values. If a generic 330 value cannot be agreed upon in the community, the parameter's name 331 should be correspondingly specific (e.g., with a prefix that 332 identifies the vendor, application or deployment). 334 Registration requests should use the following template: 336 * Name: [a name for the Cache-Status Parameter that matches key] 337 * Description: [a description of the parameter semantics and value] 339 * Reference: [to a specification defining this parameter] 341 See the registry at https://iana.org/assignments/http-cache-status 342 (https://iana.org/assignments/http-cache-status) for details on where 343 to send registration requests. 345 5. IANA Considerations 347 Upon publication, please create the HTTP Cache-Status Parameters 348 registry at https://iana.org/assignments/http-cache-status 349 (https://iana.org/assignments/http-cache-status) and populate it with 350 the types defined in Section 2; see Section 4 for its associated 351 procedures. 353 6. Security Considerations 355 Attackers can use the information in Cache-Status to probe the 356 behaviour of the cache (and other components), and infer the activity 357 of those using the cache. The Cache-Status header field may not 358 create these risks on its own, but can assist attackers in exploiting 359 them. 361 For example, knowing if a cache has stored a response can help an 362 attacker execute a timing attack on sensitive data. Exposing the 363 cache key can help an attacker understand modifications to the cache 364 key, which may assist cache poisoning attacks. See [ENTANGLE] for 365 details. 367 The underlying risks can be mitigated with a variety of techniques 368 (e.g., use of encryption and authentication; avoiding the inclusion 369 of attacker-controlled data in the cache key), depending on their 370 exact nature. 372 To avoid assisting such attacks, the Cache-Status header field can be 373 omitted, only sent when the client is authorized to receive it, or 374 only send sensitive information (e.g., the key parameter) when the 375 client is authorized. 377 7. References 379 7.1. Normative References 381 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 382 Requirement Levels", BCP 14, RFC 2119, 383 DOI 10.17487/RFC2119, March 1997, 384 . 386 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 387 Writing an IANA Considerations Section in RFCs", BCP 26, 388 RFC 8126, DOI 10.17487/RFC8126, June 2017, 389 . 391 [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for 392 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 393 . 395 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 396 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 397 May 2017, . 399 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 400 Specifications: ABNF", STD 68, RFC 5234, 401 DOI 10.17487/RFC5234, January 2008, 402 . 404 7.2. Informative References 406 [ENTANGLE] Kettle, J., "Web Cache Entanglement: Novel Pathways to 407 Poisoning", 2020, . 411 Author's Address 413 Mark Nottingham 414 Fastly 415 Prahran VIC 416 Australia 418 Email: mnot@mnot.net 419 URI: https://www.mnot.net/