idnits 2.17.1 draft-ietf-httpbis-cache-header-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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** 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 (January 27, 2019) is 1915 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 289 -- Looks like a reference, but probably isn't: '2' on line 291 -- Looks like a reference, but probably isn't: '3' on line 293 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-header-structure-09 ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP Working Group M. Nottingham 3 Internet-Draft Fastly 4 Intended status: Standards Track January 27, 2019 5 Expires: July 31, 2019 7 The Cache HTTP Response Header 8 draft-ietf-httpbis-cache-header-00 10 Abstract 12 To aid debugging, HTTP caches often append headers to a response 13 detailing how they handled the request. This specification codifies 14 that practice and updates it for HTTP's current caching model. 16 Note to Readers 18 _RFC EDITOR: please remove this section before publication_ 20 Discussion of this draft takes place on the HTTP working group 21 mailing list (ietf-http-wg@w3.org), which is archived at 22 https://lists.w3.org/Archives/Public/ietf-http-wg/ [1]. 24 Working Group information can be found at https://httpwg.org/ [2]; 25 source code and issues list for this draft can be found at 26 https://github.com/httpwg/http-extensions/labels/cache-header [3]. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on July 31, 2019. 45 Copyright Notice 47 Copyright (c) 2019 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 63 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 64 2. The Cache HTTP Response Header . . . . . . . . . . . . . . . 3 65 3. Security Considerations . . . . . . . . . . . . . . . . . . . 6 66 4. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 4.1. Normative References . . . . . . . . . . . . . . . . . . 6 68 4.2. Informative References . . . . . . . . . . . . . . . . . 7 69 4.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 7 70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 72 1. Introduction 74 To aid debugging, HTTP caches often append headers to a response 75 detailing how they handled the request. 77 Unfortunately, the semantics of these headers are often unclear, and 78 both the semantics and syntax used vary greatly between 79 implementations. 81 This specification defines a single, new HTTP response header field, 82 "Cache" for this purpose. 84 For example: 86 Cache: HIT_FRESH; node="reverse-proxy.example.com:80"; 87 key="https://example.com/foo|Accept-Encoding:gzip", 88 HIT_STALE; node="FooCDN parent"; fresh=-45; age=200; latency=3, 89 MISS; node="FooCDN edge"; fresh=-45; age=200; latency=98 91 1.1. Notational Conventions 93 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 94 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 95 "OPTIONAL" in this document are to be interpreted as described in BCP 96 14 [RFC2119] [RFC8174] when, and only when, they appear in all 97 capitals, as shown here. 99 This document uses ABNF as defined in [RFC5234], along with the "%s" 100 extension for case sensitivity defined in [RFC7405]. 102 2. The Cache HTTP Response Header 104 The Cache HTTP response header indicates the handling of the request 105 corresponding to the response it occurs within by caches along the 106 path. 108 Its value is a Parameterised List 109 [I-D.ietf-httpbis-header-structure]: 111 Cache = sh-param-list 113 Each member of the parameterised list represents a cache that has 114 handled the request. 116 The first member of the list represents the cache closest to the 117 origin server, and the last member of the list represents the cache 118 closest to the user agent (possibly including the user agent's cache 119 itself, if it chooses to append a value). 121 Caches determine when it is appropriate to add the Cache header field 122 to a response. Some might decide to add it to all responses, whereas 123 others might only do so when specifically configured to, or when the 124 request contains a header that activates a debugging mode. 126 When adding a value to the Cache header field, caches SHOULD preserve 127 the existing contents of the header, to allow debugging of the entire 128 chain of caches handling the request. 130 Identifiers in the parameterised list members are expected to be 131 cache-actions: 133 cache-action = %s"HIT_FRESH" 134 / %s"HIT_STALE" 135 / %s"HIT_REFRESH_MODIFIED" 136 / %s"HIT_REFRESH_NOT_MODIFIED" 137 / %s"HIT_REFRESH_STALE" 138 / %s"MISS" 139 / %s"MISS_CLIENT" 140 / %s"BYPASS" 141 / %s"ERROR" 143 The semantics of cache-actions are: 145 o HIT_FRESH - The cache used a fresh stored response to satisfy the 146 request without going forward 148 o HIT_STALE - The cache used a stale stored response to satisfy the 149 request without going forward 151 o HIT_REFRESH_MODIFIED - The cache had a stale stored response, went 152 forward to validate it, and used the new response to satisfy the 153 request 155 o HIT_REFRESH_NOT_MODIFIED - The cache had a stale stored response, 156 went forward to validate it, and used the stored response to 157 satisfy the request 159 o HIT_REFRESH_STALE - The cache had a stale stored response, went 160 forward to validate it, and encountered a problem, so the stored 161 response was used to satisfy the request 163 o MISS - The cache did not have a stored response, so the request 164 was forwarded 166 o MISS_CLIENT - The client included request directives (e.g., 167 Pragma, Cache-Control) that prevented the cache from returning a 168 response, so the request was forwarded 170 o BYPASS - The cache was configured to forward the request without 171 attempting to use a stored response 173 o ERROR - The cache was unable to use a stored response or obtain 174 one by going forward 176 Caches SHOULD use the most specific cache-action to a given response, 177 but are not required to use all cache-actions. Future updates to 178 this specification can add additional cache-actions. 180 Each member of the Cache header can also have any (or all, or none) 181 of the following parameters: 183 node = sh-string 184 fresh = sh-integer 185 age = sh-integer 186 cacheable = sh-boolean 187 key = sh-string 188 latency = sh-integer 189 cl_nm = sh-boolean 191 Their semantics are: 193 o "node" - a string identifying for the cache node. MAY be a 194 hostname, IP address, or alias. 196 o "fresh" - an integer indicating the cache's estimation of the 197 freshness lifetime ([RFC7234], Section 4.2.1) of this response in 198 seconds, including any locally applied configuration. MAY be 199 negative. 201 o "age" - an integer indicating the cache's estimation of the age 202 ([RFC7234], Section 4.2.3) of this response in seconds. MUST be 0 203 or greater. 205 o "cacheable" - a boolean indicating whether the cache can store 206 this response, according to [RFC7234], Section 3 and any locally 207 applied configuration. 209 o "key" - a string representing the key that the cache has 210 associated with this response. This might include the request 211 URL, request headers, and other values. 213 o "latency" - an integer indicating the amount of time in 214 milliseconds between the receipt of a complete set of request 215 headers and sending the complete set of response headers of this 216 response, from the viewpoint of the cache. Note that this may not 217 include buffering time in transport protocols and similar delays. 219 o "cl_nm" - a boolean indicating whether the response to the client 220 had a 304 Not Modified status code. 222 While all of these parameters are OPTIONAL, caches are encouraged to 223 use the 'node' parameter to identify themselves. 225 3. Security Considerations 227 Information about a cache's content can be used to infer the activity 228 of those using it. Generally, access to sensitive information in a 229 cache is limited to those who are authorised to access that 230 information (using a variety of techniques), so this does not 231 represent an attack vector in the general sense. 233 However, if the Cache header is exposed to parties who are not 234 authorised to obtain the response it occurs within, it could expose 235 information about that data. 237 For example, if an attacker were able to obtain the Cache header from 238 a response containing sensitive information and access were limited 239 to one person (or limited set of people), they could determine 240 whether that information had been accessed before. This is similar 241 to the information exposed by various timing attacks, but is arguably 242 more reliable, since the cache is directly reporting its state. 244 Mitigations include use of encryption (e.g., TLS [RFC8446])) to 245 protect the response, and careful controls over access to response 246 headers (as are present in the Web platform). When in doubt, the 247 Cache header field can be omitted. 249 4. References 251 4.1. Normative References 253 [I-D.ietf-httpbis-header-structure] 254 Nottingham, M. and P. Kamp, "Structured Headers for HTTP", 255 draft-ietf-httpbis-header-structure-09 (work in progress), 256 December 2018. 258 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 259 Requirement Levels", BCP 14, RFC 2119, 260 DOI 10.17487/RFC2119, March 1997, 261 . 263 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 264 Specifications: ABNF", STD 68, RFC 5234, 265 DOI 10.17487/RFC5234, January 2008, 266 . 268 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 269 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 270 RFC 7234, DOI 10.17487/RFC7234, June 2014, 271 . 273 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 274 RFC 7405, DOI 10.17487/RFC7405, December 2014, 275 . 277 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 278 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 279 May 2017, . 281 4.2. Informative References 283 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 284 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 285 . 287 4.3. URIs 289 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 291 [2] https://httpwg.org/ 293 [3] https://github.com/httpwg/http-extensions/labels/cache-header 295 Author's Address 297 Mark Nottingham 298 Fastly 300 Email: mnot@mnot.net 301 URI: https://www.mnot.net/