idnits 2.17.1 draft-ietf-httpbis-cache-header-04.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 5, 2020) is 1331 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 5, 2020 5 Expires: February 6, 2021 7 The Cache-Status HTTP Response Header Field 8 draft-ietf-httpbis-cache-header-04 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 6, 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 decide to add it to all 122 responses, whereas others might only do so when specifically 123 configured to, or when the request contains a header that activates a 124 debugging mode. 126 When adding a value to the Cache-Status header field, caches SHOULD 127 preserve the existing contents of the header field, to allow 128 debugging of the entire chain of caches handling the request. 130 Each list member identifies the cache that inserted that value, and 131 MUST be a String or Token. Depending on the deployment, this might 132 be a product or service name (e.g., ExampleCache or "Example CDN"), a 133 hostname ("cache-3.example.com"), and IP address, or a generated 134 string. 136 Each member of the list can also have parameters that describe that 137 cache's handling of the request. While all of these parameters are 138 OPTIONAL, caches are encouraged to provide as much information as 139 possible. 141 This specification defines these parameters: 143 hit = sf-boolean 144 fwd = sf-token 145 fwd-status = sf-integer 146 ttl = sf-integer 147 stored = sf-boolean 148 collapsed = sf-boolean 149 key = sf-string 150 detail = sf-token / sf-string 152 2.1. The hit parameter 154 "hit", when true, indicates that the request was satisfied by the 155 cache; i.e., it did not go forward and the response was obtained from 156 the cache. A response that originally was produced by the origin but 157 was modified by the cache (for example, a 304 or 206 status code) is 158 still considered a hit. 160 "hit" and "fwd" are exclusive; only one of them should appear on each 161 list member. 163 2.2. The fwd parameter 165 "fwd" indicates that the request went forward towards the origin, and 166 why. 168 The following values are defined to explain why the request went 169 forward: 171 o uri-miss - The cache did not contain any responses that matched 172 the request URI 174 o vary-miss - The cache contained a response that matched the 175 request URI, but could not select a response based upon this 176 request's headers and stored Vary headers. 178 o miss - The cache did not contain any responses that could be used 179 to satisfy this request (to be used when an implementation cannot 180 distinguish between uri-miss and vary-miss) 182 o stale - The cache was able to select a response for the request, 183 but it was stale 185 o request - The cache was able to select a fresh response for the 186 request, but client request headers (e.g., Cache-Control request 187 directives) did not allow its use 189 o bypass - The cache was configured to not handle this request 191 2.3. The fwd-status parameter 193 "fwd-status" indicates what status code the next hop server returned 194 in response to the request. Only meaningful when "fwd" is present; 195 if "fwd-status" is not present but "fwd" is, it defaults to the 196 status code sent in the response. 198 This parameter is useful to distinguish cases when the next hop 199 server sends a 304 Not Modified response to a conditional request, or 200 a 206 Partial Response due to a range request. 202 2.4. The ttl parameter 204 "ttl" indicates the response's remaining freshness lifetime as 205 calculated by the cache, as an integer number of seconds, measured 206 when the response is sent by the cache. This includes freshness 207 assigned by the cache; e.g., through heuristics, local configuration, 208 or other factors. May be negative, to indicate staleness. 210 2.5. The stored parameter 212 "stored" indicates whether the cache stored the response; a true 213 value indicates that it did. Only meaningful when fwd is present. 215 2.6. The collapsed parameter 217 "collapsed" indicates whether this request was collapsed together 218 with one or more other forward requests; if true, the response was 219 successfully reused; if not, a new request had to be made. If not 220 present, the request was not collapsed with others. Only meaningful 221 when fwd is present. 223 2.7. The key parameter 225 "key" conveys a representation of the cache key used for the 226 response. Note that this may be implementation-specific. 228 2.8. The detail parameter 230 "detail" allows implementations to convey additional information not 231 captured in other parameters; for example, implementation-specific 232 states, or other caching-related metrics. 234 For example: 236 Cache-Status: ExampleCache; hit; detail=MEMORY 237 The semantics of a detail parameter are always specific to the cache 238 that sent it; even if a member of details from another cache shares 239 the same name, it might not mean the same thing. 241 This parameter is intentionally limited. If an implementation needs 242 to convey additional information, they are encouraged to register 243 extension parameters (see Section 4) or define another header field. 245 3. Examples 247 The most minimal cache hit: 249 Cache-Status: ExampleCache; hit 251 ... but a polite cache will give some more information, e.g.: 253 Cache-Status: ExampleCache; hit; ttl=376 255 A stale hit just has negative freshness: 257 Cache-Status: ExampleCache; hit; ttl=-412 259 Whereas a complete miss is: 261 Cache-Status: ExampleCache; fwd=uri-miss 263 A miss that successfully validated on the back-end server: 265 Cache-Status: ExampleCache; fwd=stale; fwd-status=304 267 A miss that was collapsed with another request: 269 Cache-Status: ExampleCache; fwd=uri-miss; collapsed 271 A miss that the cache attempted to collapse, but couldn't: 273 Cache-Status: ExampleCache; fwd=uri-miss; collapsed=?0 275 Going through two layers of caching, both of which were hits, and the 276 second collapsed with other requests: 278 Cache-Status: OriginCache; hit; ttl=1100; collapsed, 279 "CDN Company Here"; hit; ttl=545 281 4. Defining New Proxy-Status Parameters 283 New Cache-Status Parameters can be defined by registering them in the 284 HTTP Cache-Status Parameters registry. 286 Registration requests are reviewed and approved by a Designated 287 Expert, as per [RFC8126], Section 4.5. A specification document is 288 appreciated, but not required. 290 The Expert(s) should consider the following factors when evaluating 291 requests: 293 o Community feedback 295 o If the value is sufficiently well-defined 297 o Generic parameters are preferred over vendor-specific, 298 application-specific or deployment-specific values. If a generic 299 value cannot be agreed upon in the community, the parameter's name 300 should be correspondingly specific (e.g., with a prefix that 301 identifies the vendor, application or deployment). 303 Registration requests should use the following template: 305 o Name: [a name for the Cache-Status Parameter that matches key] 307 o Description: [a description of the parameter semantics and value] 309 o Reference: [to a specification defining this parameter] 311 See the registry at https://iana.org/assignments/http-cache-status 312 [4] for details on where to send registration requests. 314 5. IANA Considerations 316 Upon publication, please create the HTTP Cache-Status Parameters 317 registry at https://iana.org/assignments/http-cache-statuses [5] and 318 populate it with the types defined in Section 2; see Section 4 for 319 its associated procedures. 321 6. Security Considerations 323 Information about a cache's content can be used to infer the activity 324 of those using it. Generally, access to sensitive information in a 325 cache is limited to those who are authorised to access that 326 information (using a variety of techniques), so this does not 327 represent an attack vector in the general sense. 329 However, if the Cache-Status header field is exposed to parties who 330 are not authorised to obtain the response it occurs within, it could 331 expose information about that data. 333 For example, if an attacker were able to obtain the Cache-Status 334 header field from a response containing sensitive information and 335 access were limited to one person (or limited set of people), they 336 could determine whether that information had been accessed before. 337 This is similar to the information exposed by various timing attacks, 338 but is arguably more reliable, since the cache is directly reporting 339 its state. 341 Mitigations include use of encryption (e.g., TLS [RFC8446])) to 342 protect the response, and careful controls over access to response 343 header fields (as are present in the Web platform). When in doubt, 344 the Cache-Status header field can be omitted. 346 7. References 348 7.1. Normative References 350 [I-D.ietf-httpbis-header-structure] 351 Nottingham, M. and P. Kamp, "Structured Field Values for 352 HTTP", draft-ietf-httpbis-header-structure-19 (work in 353 progress), June 2020. 355 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 356 Requirement Levels", BCP 14, RFC 2119, 357 DOI 10.17487/RFC2119, March 1997, 358 . 360 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 361 Specifications: ABNF", STD 68, RFC 5234, 362 DOI 10.17487/RFC5234, January 2008, 363 . 365 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 366 RFC 7405, DOI 10.17487/RFC7405, December 2014, 367 . 369 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 370 Writing an IANA Considerations Section in RFCs", BCP 26, 371 RFC 8126, DOI 10.17487/RFC8126, June 2017, 372 . 374 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 375 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 376 May 2017, . 378 7.2. Informative References 380 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 381 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 382 . 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-statuses 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/