idnits 2.17.1 draft-ietf-httpbis-cache-header-05.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [3], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 11, 2020) is 1347 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) -- Looks like a reference, but probably isn't: '1' on line 386 -- Looks like a reference, but probably isn't: '2' on line 388 -- Looks like a reference, but probably isn't: '3' on line 390 -- Looks like a reference, but probably isn't: '4' on line 392 -- Looks like a reference, but probably isn't: '5' on line 394 Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 6 comments (--). 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 August 11, 2020 5 Expires: February 12, 2021 7 The Cache-Status HTTP Response Header Field 8 draft-ietf-httpbis-cache-header-05 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/ [1]. 25 Working Group information can be found at https://httpwg.org/ [2]; 26 source code and issues list for this draft can be found at 27 https://github.com/httpwg/http-extensions/labels/cache-header [3]. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on February 12, 2021. 46 Copyright Notice 48 Copyright (c) 2020 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 64 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 65 2. The Cache-Status HTTP Response Header Field . . . . . . . . . 3 66 2.1. The hit parameter . . . . . . . . . . . . . . . . . . . . 4 67 2.2. The fwd parameter . . . . . . . . . . . . . . . . . . . . 4 68 2.3. The fwd-status parameter . . . . . . . . . . . . . . . . 5 69 2.4. The ttl parameter . . . . . . . . . . . . . . . . . . . . 5 70 2.5. The stored parameter . . . . . . . . . . . . . . . . . . 5 71 2.6. The collapsed parameter . . . . . . . . . . . . . . . . . 5 72 2.7. The key parameter . . . . . . . . . . . . . . . . . . . . 5 73 2.8. The detail parameter . . . . . . . . . . . . . . . . . . 5 74 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6 75 4. Defining New Proxy-Status Parameters . . . . . . . . . . . . 7 76 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 77 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 78 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 79 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 80 7.2. Informative References . . . . . . . . . . . . . . . . . 9 81 7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 9 82 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 84 1. Introduction 86 To aid debugging, HTTP caches often append header fields to a 87 response explaining how they handled the request. Unfortunately, the 88 semantics of these headers are often unclear, and both the semantics 89 and syntax used vary greatly between implementations. 91 This specification defines a single, new HTTP response header field, 92 "Cache-Status" for this purpose. 94 1.1. Notational Conventions 96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 98 "OPTIONAL" in this document are to be interpreted as described in BCP 99 14 [RFC2119] [RFC8174] when, and only when, they appear in all 100 capitals, as shown here. 102 This document uses ABNF as defined in [RFC5234], along with the "%s" 103 extension for case sensitivity defined in [RFC7405]. 105 2. The Cache-Status HTTP Response Header Field 107 The Cache-Status HTTP response header indicates caches' handling of 108 the request corresponding to the response it occurs within. 110 Its value is a List [I-D.ietf-httpbis-header-structure]: 112 Cache-Status = sf-list 114 Each member of the list represents a cache that has handled the 115 request. The first member of the list represents the cache closest 116 to the origin server, and the last member of the list represents the 117 cache closest to the client (possibly including the user agent's 118 cache itself, if it chooses to append a value). 120 Caches determine when it is appropriate to add the Cache-Status 121 header field to a response. Some might add it to all responses, 122 whereas others might only do so when specifically configured to, or 123 when the request contains a header that activates a debugging mode. 125 When adding a value to the Cache-Status header field, caches SHOULD 126 preserve the existing contents of the header field, to allow 127 debugging of the entire chain of caches handling the request. 129 Each list member identifies the cache that inserted that value, and 130 MUST be a String or Token. Depending on the deployment, this might 131 be a product or service name (e.g., ExampleCache or "Example CDN"), a 132 hostname ("cache-3.example.com"), and IP address, or a generated 133 string. 135 Each member of the list can also have parameters that describe that 136 cache's handling of the request. While all of these parameters are 137 OPTIONAL, caches are encouraged to provide as much information as 138 possible. 140 This specification defines these parameters: 142 hit = sf-boolean 143 fwd = sf-token 144 fwd-status = sf-integer 145 ttl = sf-integer 146 stored = sf-boolean 147 collapsed = sf-boolean 148 key = sf-string 149 detail = sf-token / sf-string 151 2.1. The hit parameter 153 "hit", when true, indicates that the request was satisfied by the 154 cache; i.e., it did not go forward, and the response was obtained 155 from the cache. A response that originally was produced by the 156 origin but was modified by the cache (for example, a 304 or 206 157 status code) is still considered a hit. 159 "hit" and "fwd" are exclusive; only one of them should appear on each 160 list member. 162 2.2. The fwd parameter 164 "fwd" indicates that the request went forward towards the origin, and 165 why. 167 The following values are defined to explain why the request went 168 forward: 170 o uri-miss - The cache did not contain any responses that matched 171 the request URI 173 o vary-miss - The cache contained a response that matched the 174 request URI, but could not select a response based upon this 175 request's headers and stored Vary headers. 177 o miss - The cache did not contain any responses that could be used 178 to satisfy this request (to be used when an implementation cannot 179 distinguish between uri-miss and vary-miss) 181 o stale - The cache was able to select a response for the request, 182 but it was stale 184 o request - The cache was able to select a fresh response for the 185 request, but client request headers (e.g., Cache-Control request 186 directives) did not allow its use 188 o bypass - The cache was configured to not handle this request 190 2.3. The fwd-status parameter 192 "fwd-status" indicates what status code the next hop server returned 193 in response to the request. Only meaningful when "fwd" is present; 194 if "fwd-status" is not present but "fwd" is, it defaults to the 195 status code sent in the response. 197 This parameter is useful to distinguish cases when the next hop 198 server sends a 304 Not Modified response to a conditional request, or 199 a 206 Partial Response because of a range request. 201 2.4. The ttl parameter 203 "ttl" indicates the response's remaining freshness lifetime as 204 calculated by the cache, as an integer number of seconds, measured 205 when the response is sent by the cache. This includes freshness 206 assigned by the cache; e.g., through heuristics, local configuration, 207 or other factors. May be negative, to indicate staleness. 209 2.5. The stored parameter 211 "stored" indicates whether the cache stored the response; a true 212 value indicates that it did. Only meaningful when fwd is present. 214 2.6. The collapsed parameter 216 "collapsed" indicates whether this request was collapsed together 217 with one or more other forward requests; if true, the response was 218 successfully reused; if not, a new request had to be made. If not 219 present, the request was not collapsed with others. Only meaningful 220 when fwd is present. 222 2.7. The key parameter 224 "key" conveys a representation of the cache key used for the 225 response. Note that this may be implementation-specific. 227 2.8. The detail parameter 229 "detail" allows implementations to convey additional information not 230 captured in other parameters; for example, implementation-specific 231 states, or other caching-related metrics. 233 For example: 235 Cache-Status: ExampleCache; hit; detail=MEMORY 236 The semantics of a detail parameter are always specific to the cache 237 that sent it; even if a member of details from another cache shares 238 the same name, it might not mean the same thing. 240 This parameter is intentionally limited. If an implementation needs 241 to convey additional information, they are encouraged to register 242 extension parameters (see Section 4) or define another header field. 244 3. Examples 246 The most minimal cache hit: 248 Cache-Status: ExampleCache; hit 250 ... but a polite cache will give some more information, e.g.: 252 Cache-Status: ExampleCache; hit; ttl=376 254 A stale hit just has negative freshness: 256 Cache-Status: ExampleCache; hit; ttl=-412 258 Whereas a complete miss is: 260 Cache-Status: ExampleCache; fwd=uri-miss 262 A miss that successfully validated on the back-end server: 264 Cache-Status: ExampleCache; fwd=stale; fwd-status=304 266 A miss that was collapsed with another request: 268 Cache-Status: ExampleCache; fwd=uri-miss; collapsed 270 A miss that the cache attempted to collapse, but couldn't: 272 Cache-Status: ExampleCache; fwd=uri-miss; collapsed=?0 274 Going through two layers of caching, both of which were hits, and the 275 second collapsed with other requests: 277 Cache-Status: OriginCache; hit; ttl=1100; collapsed, 278 "CDN Company Here"; hit; ttl=545 280 4. Defining New Proxy-Status Parameters 282 New Cache-Status Parameters can be defined by registering them in the 283 HTTP Cache-Status Parameters registry. 285 Registration requests are reviewed and approved by a Designated 286 Expert, as per [RFC8126], Section 4.5. A specification document is 287 appreciated, but not required. 289 The Expert(s) should consider the following factors when evaluating 290 requests: 292 o Community feedback 294 o If the value is sufficiently well-defined 296 o Generic parameters are preferred over vendor-specific, 297 application-specific or deployment-specific values. If a generic 298 value cannot be agreed upon in the community, the parameter's name 299 should be correspondingly specific (e.g., with a prefix that 300 identifies the vendor, application or deployment). 302 Registration requests should use the following template: 304 o Name: [a name for the Cache-Status Parameter that matches key] 306 o Description: [a description of the parameter semantics and value] 308 o Reference: [to a specification defining this parameter] 310 See the registry at https://iana.org/assignments/http-cache-status 311 [4] for details on where to send registration requests. 313 5. IANA Considerations 315 Upon publication, please create the HTTP Cache-Status Parameters 316 registry at https://iana.org/assignments/http-cache-status [5] and 317 populate it with the types defined in Section 2; see Section 4 for 318 its associated procedures. 320 6. Security Considerations 322 Attackers can use the information in Cache-Status to probe the 323 behaviour of the cache (and other components), and infer the activity 324 of those using the cache. The Cache-Status header field may not 325 create these risks on its own, but can assist attackers in exploiting 326 them. 328 For example, knowing if a cache has stored a response can help an 329 attacker execute a timing attack on sensitive data. Exposing the 330 cache key can help an attacker understand modifications to the cache 331 key, which may assist cache poisoning attacks. See [ENTANGLE] for 332 details. 334 The underlying risks can be mitigated with a variety of techniques 335 (e.g., use of encryption and authentication; avoiding the inclusion 336 of attacker-controlled data in the cache key), depending on their 337 exact nature. 339 To avoid assisting such attacks, the Cache-Status header field can be 340 omitted, only sent when the client is authorized to receive it, or 341 only send sensitive information (e.g., the key parameter) when the 342 client is authorized. 344 7. References 346 7.1. Normative References 348 [I-D.ietf-httpbis-header-structure] 349 Nottingham, M. and P. Kamp, "Structured Field Values for 350 HTTP", draft-ietf-httpbis-header-structure-19 (work in 351 progress), June 2020. 353 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 354 Requirement Levels", BCP 14, RFC 2119, 355 DOI 10.17487/RFC2119, March 1997, 356 . 358 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 359 Specifications: ABNF", STD 68, RFC 5234, 360 DOI 10.17487/RFC5234, January 2008, 361 . 363 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 364 RFC 7405, DOI 10.17487/RFC7405, December 2014, 365 . 367 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 368 Writing an IANA Considerations Section in RFCs", BCP 26, 369 RFC 8126, DOI 10.17487/RFC8126, June 2017, 370 . 372 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 373 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 374 May 2017, . 376 7.2. Informative References 378 [ENTANGLE] 379 Kettle, J., "Web Cache Entanglement: Novel Pathways to 380 Poisoning", n.d., . 384 7.3. URIs 386 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 388 [2] https://httpwg.org/ 390 [3] https://github.com/httpwg/http-extensions/labels/cache-header 392 [4] https://iana.org/assignments/http-cache-status 394 [5] https://iana.org/assignments/http-cache-status 396 Author's Address 398 Mark Nottingham 399 Fastly 400 made in 401 Prahran, VIC 402 Australia 404 Email: mnot@mnot.net 405 URI: https://www.mnot.net/