idnits 2.17.1 draft-fielding-http-key-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 (October 15, 2012) is 4208 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-21 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-21 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-21 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Fielding 3 Internet-Draft Adobe Systems Incorporated 4 Intended status: Informational M. Nottingham 5 Expires: April 18, 2013 October 15, 2012 7 The Key HTTP Response Header Field 8 draft-fielding-http-key-01 10 Abstract 12 The 'Key' header field for HTTP responses allows an origin server to 13 describe the cache key for a negotiated response: a short algorithm 14 that can be used upon later requests to determine if the same 15 response is reusable. 17 Key has the advantage of avoiding an additional round trip for 18 validation whenever a new request differs slightly, but not 19 significantly, from prior requests. 21 Key also informs user agents of the request characteristics that 22 might result in different content, which can be useful if the user 23 agent is not sending Accept* fields in order to reduce the risk of 24 fingerprinting. 26 Status of this Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on April 18, 2013. 43 Copyright Notice 45 Copyright (c) 2012 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 62 2. The "Key" Response Header Field . . . . . . . . . . . . . . . . 3 63 2.1. Header Matching . . . . . . . . . . . . . . . . . . . . . . 4 64 2.2. Key Modifiers . . . . . . . . . . . . . . . . . . . . . . . 6 65 2.2.1. "w": Word Match Modifier . . . . . . . . . . . . . . . 6 66 2.2.2. "s": Substring Match Modifier . . . . . . . . . . . . . 6 67 2.2.3. "b": Beginning Substring Match Modifier . . . . . . . . 6 68 2.2.4. "p": Parameter Prefix Match Modifier . . . . . . . . . 6 69 2.2.5. "c": Case Sensitivity Flag . . . . . . . . . . . . . . 6 70 2.2.6. "n": Not Flag . . . . . . . . . . . . . . . . . . . . . 6 71 2.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 7 72 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 73 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 8 74 5. Normative References . . . . . . . . . . . . . . . . . . . . . 8 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8 77 1. Introduction 79 In HTTP caching [I-D.ietf-httpbis-p6-cache], the Vary response header 80 field effectively modifies the key used to store and access a 81 response to include information from the request's headers. This 82 allows proactive content negotiation [I-D.ietf-httpbis-p2-semantics] 83 to work with caches. 85 However, Vary's operation is coarse-grained; although caches are 86 allowed to normalise the values of headers based upon their 87 semantics, doing so requires the cache to understand those semantics, 88 and is still quite limited. 90 For example, if a response is cached with the response header field: 92 Vary: Accept-Encoding 94 and and its associated request is: 96 Accept-Encoding: gzip 98 then a subsequent request with the following header is (in a strict 99 reading of HTTP) not a match, resulting in a cache miss: 101 Accept-Encoding: identity, gzip 103 This document defines a new response header field, "Key", that allows 104 servers to describe the cache key in a much more fine-grained manner, 105 leading to improved cache efficiency. 107 1.1. Notational Conventions 109 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 110 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 111 document are to be interpreted as described in [RFC2119]. 113 This document uses the Augmented Backus-Naur Form (ABNF) notation of 114 [RFC5234] with the list rule extension defined in 115 [I-D.ietf-httpbis-p1-messaging], Appendix B. It includes by 116 reference the OWS, field-name and quoted-string rules from that 117 document, and the parameter rule from 118 [I-D.ietf-httpbis-p2-semantics]. 120 2. The "Key" Response Header Field 122 The "Key" response header field describes the request attributes that 123 the server has used to select the current representation. 125 As such, its semantics are similar to the "Vary" response header 126 field, but it allows more fine-grained description, using "key 127 modifiers". 129 Caches can use this information as part of determining whether a 130 stored response can be used to satisfy a given request. When a cache 131 fully implements this mechanism, it MAY ignore the Vary response 132 header field. 134 Additionally, user agents can use this information to discover if 135 additional request header fields might influence the resulting 136 response. 138 The Key field-value is a comma-delimited list of selecting header 139 fields (similar to Vary), with zero to many modifiers to each, 140 delimited by semicolons. Whitespace is not allowed in the field- 141 value between each field-name and its parameter set. 143 Key = 1#field-name *( ";" parameter ) 145 The following header fields therefore have identical semantics: 147 Vary: Accept-Encoding, Accept-Language 148 Key: Accept-Encoding, Accept-Language 150 However, Key's use of modifiers allows: 152 Key: Accept-Encoding;w="gzip", Accept-Language;b="fr" 154 to indicate that the response it occurs in is allowed to be reused 155 for requests that contain the token "gzip" (in any case) in the 156 Accept-Encoding header field and an Accept-Language header field 157 value that starts with "fr" (in any case). 159 Note that both the field-name and modifier names themselves are case 160 insensitive. 162 2.1. Header Matching 164 When used by a cache to determine whether a stored response can be 165 used to satisfy a presented request, each field-name identifies a 166 potential request header, just as with the Vary response header 167 field. 169 However, each of these can have zero to many "key modifiers" that 170 change how the response selection process (as defined in 171 [I-D.ietf-httpbis-p6-cache], Section 4.3)) works. 173 In particular, a cache that implements the Key header field MUST NOT 174 use a stored response unless all of the selecting header fields 175 nominated by the Key header field match in both the original request 176 (i.e., that associated with the stored response) and the presented 177 request. 179 Modifiers operate on a list of zero to many field-values. This list 180 is constructed by: 182 1. Starting with the field-values of all header fields that have the 183 given field-name. 184 2. Splitting each field-value on commas, excluding any that occur 185 inside of a quoted-string production. 186 3. Flattening the list of lists into a single list that represents 187 the individual header field-values. 188 4. Case-normalising each value in both lists to lowercase. 189 5. Trimming any OWS from the start and end of the field-values. 191 For example, given the set of headers: 193 Foo: 1 194 Bar: z 195 Foo: 2, a="b,c" 197 A modifier for "Foo" would operate on the list of presented values 198 '1', '2', 'a="b,c"'. 200 Note that step 2 of this algorithm optimistically assumes that 201 double-quotes in a header field value denote the use of the quoted- 202 string as defined by [I-D.ietf-httpbis-p1-messaging]; the cache does 203 not need to "understand" the specific header field. 205 Once the appropriate header fields from both the original request and 206 the stored request are processed in this manner, the result is two 207 (possibly empty) lists of values for each specified header field. 209 The key modifiers (as specified in the Key header field) are then 210 applied to the lists in the order they appear in Key (left to right). 211 If any modifier does not return a match (as per its definition), the 212 headers are said not to match. If all of the modifiers return a 213 match, the headers are said to match. 215 Note that some types of modifiers are said to always match; they can 216 be used to alter the input lists, or to alter the semantics of 217 subsequent matches. 219 Unrecognised modifiers MUST result in a failure to match. 221 2.2. Key Modifiers 223 This document defines the following key modifiers: 225 2.2.1. "w": Word Match Modifier 227 The "w" modifier matches if the parameter value (after unquoting) 228 matches (character-for-character) any whole value in both lists. 230 2.2.2. "s": Substring Match Modifier 232 The "s" modifier matches if the parameter value (after unquoting) is 233 contained as a sequence of characters within both lists. 235 2.2.3. "b": Beginning Substring Match Modifier 237 The "b" modifier matches if both lists contain a value that begins 238 with the same sequence of characters as the parameter value (after 239 unquoting). 241 2.2.4. "p": Parameter Prefix Match Modifier 243 The "p" modifier matches if the parameter value (after unquoting) 244 matches (character-for-character) the sequence of characters up to 245 (but not including) the first semi-colon (";") in both lists, after 246 any whitespace is removed. 248 For example, given the key: 250 Key: Accept;p="text/html" 252 then each of the following header fields is a match: 254 Accept: text/html 255 Accept: text/html; q=0.5 256 Accept: text/html;q=0.1 257 Accept: text/html; foo="bar" 259 2.2.5. "c": Case Sensitivity Flag 261 The "c" modifier always matches, and has the side effect of reverting 262 the case normalisation of the header lists (see #4 in the list 263 above), so that subsequent matches become case sensitive. 265 2.2.6. "n": Not Flag 267 The "n" modifier always matches, and has the side effect of modifying 268 the semantics of subsequent modifiers (i.e., the match modifiers to 269 its right, lexically) so that they will be considered to match if 270 they do not, and likewise they will be considered not to match if 271 they do. 273 For example, given a response with: 275 Key: Foo;w="a";n;w="b" 277 then the presented header: 279 Foo: a, c 281 would match, while 283 Foo: a, b 285 would not (because it contains "b"). 287 2.3. Examples 289 For example, this response header field: 291 Key: cookie;w="_sess=fhd378";c;w="ID=\"Roy\"", 292 Accept-Encoding;w="gzip" 294 would allow the cache to reuse the response it occurs in if the 295 presented request contains: 297 o A Cookie header containing both ID="Roy" (in that case) and 298 _sess=fhd378 (evaluated case insensitively), and 299 o An Accept-Encoding header containing the token "gzip" (evaluated 300 case insensitively). 302 Less convoluted examples include matching any request with a User- 303 Agent field value containing "MSIE" in any combination of case: 305 Key: user-agent;s="MSIE" 307 And an Accept-Language field value for French: 309 Key: accept-language;b="fr" 311 3. IANA Considerations 313 TBD 315 4. Security Considerations 317 TBD 319 5. Normative References 321 [I-D.ietf-httpbis-p1-messaging] 322 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 323 (HTTP/1.1): Message Syntax and Routing", 324 draft-ietf-httpbis-p1-messaging-21 (work in progress), 325 October 2012. 327 [I-D.ietf-httpbis-p2-semantics] 328 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 329 (HTTP/1.1): Semantics and Content", 330 draft-ietf-httpbis-p2-semantics-21 (work in progress), 331 October 2012. 333 [I-D.ietf-httpbis-p6-cache] 334 Fielding, R., Nottingham, M., and J. Reschke, "Hypertext 335 Transfer Protocol (HTTP/1.1): Caching", 336 draft-ietf-httpbis-p6-cache-21 (work in progress), 337 October 2012. 339 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 340 Requirement Levels", BCP 14, RFC 2119, March 1997. 342 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 343 Specifications: ABNF", STD 68, RFC 5234, January 2008. 345 Authors' Addresses 347 Roy T. Fielding 348 Adobe Systems Incorporated 350 Email: fielding@gbiv.com 351 URI: http://roy.gbiv.com/ 353 Mark Nottingham 355 Email: mnot@mnot.net 356 URI: http://www.mnot.net/