idnits 2.17.1 draft-fielding-http-key-02.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 (February 19, 2013) is 4078 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: August 23, 2013 February 19, 2013 7 The Key HTTP Response Header Field 8 draft-fielding-http-key-02 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 August 23, 2013. 43 Copyright Notice 45 Copyright (c) 2013 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. "pr": Parameter Range Modifier . . . . . . . . . . . . 7 70 2.2.6. "c": Case Sensitivity Flag . . . . . . . . . . . . . . 8 71 2.2.7. "n": Not Flag . . . . . . . . . . . . . . . . . . . . 8 72 2.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 8 73 2.4. Relationship to Vary . . . . . . . . . . . . . . . . . . . 9 74 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 75 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 76 5. Normative References . . . . . . . . . . . . . . . . . . . . . 9 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 79 1. Introduction 81 In HTTP caching [I-D.ietf-httpbis-p6-cache], the Vary response header 82 field effectively modifies the key used to store and access a 83 response to include information from the request's headers. This 84 allows proactive content negotiation [I-D.ietf-httpbis-p2-semantics] 85 to work with caches. 87 However, Vary's operation is coarse-grained; although caches are 88 allowed to normalise the values of headers based upon their 89 semantics, doing so requires the cache to understand those semantics, 90 and is still quite limited. 92 For example, if a response is cached with the response header field: 94 Vary: Accept-Encoding 96 and and its associated request is: 98 Accept-Encoding: gzip 100 then a subsequent request with the following header is (in a strict 101 reading of HTTP) not a match, resulting in a cache miss: 103 Accept-Encoding: identity, gzip 105 This document defines a new response header field, "Key", that allows 106 servers to describe the cache key in a much more fine-grained manner, 107 leading to improved cache efficiency. 109 1.1. Notational Conventions 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in [RFC2119]. 115 This document uses the Augmented Backus-Naur Form (ABNF) notation of 116 [RFC5234] with the list rule extension defined in 117 [I-D.ietf-httpbis-p1-messaging], Appendix B. It includes by 118 reference the OWS, field-name and quoted-string rules from that 119 document, and the parameter and attribute rules from 120 [I-D.ietf-httpbis-p2-semantics]. 122 2. The "Key" Response Header Field 124 The "Key" response header field describes the request attributes that 125 the server has used to select the current representation. 127 As such, its semantics are similar to the "Vary" response header 128 field, but it allows more fine-grained description, using "key 129 modifiers". 131 Caches can use this information as part of determining whether a 132 stored response can be used to satisfy a given request. When a cache 133 fully implements this mechanism, it MAY ignore the Vary response 134 header field. 136 Additionally, user agents can use this information to discover if 137 additional request header fields might influence the resulting 138 response. 140 The Key field-value is a comma-delimited list of selecting header 141 fields (similar to Vary), with zero to many modifiers to each, 142 delimited by semicolons. Whitespace is not allowed in the field- 143 value between each field-name and its parameter set. 145 Key = 1#field-name *( ";" parameter ) 147 The following header fields therefore have identical semantics: 149 Vary: Accept-Encoding, Accept-Language 150 Key: Accept-Encoding, Accept-Language 152 However, Key's use of modifiers allows: 154 Key: Accept-Encoding;w="gzip", Accept-Language;b="fr" 156 to indicate that the response it occurs in is allowed to be reused 157 for requests that contain the token "gzip" (in any case) in the 158 Accept-Encoding header field and an Accept-Language header field 159 value that starts with "fr" (in any case). 161 Note that both the field-name and modifier names themselves are case 162 insensitive. 164 2.1. Header Matching 166 When used by a cache to determine whether a stored response can be 167 used to satisfy a presented request, each field-name identifies a 168 potential request header, just as with the Vary response header 169 field. 171 However, each of these can have zero to many "key modifiers" that 172 change how the response selection process (as defined in 173 [I-D.ietf-httpbis-p6-cache], Section 4.3)) works. 175 In particular, a cache that implements the Key header field MUST NOT 176 use a stored response unless all of the selecting header fields 177 nominated by the Key header field match in both the original request 178 (i.e., that associated with the stored response) and the presented 179 request. 181 Modifiers operate on a list of zero to many field-values. This list 182 is constructed by: 184 1. Starting with the field-values of all header fields that have the 185 given field-name. 186 2. Splitting each field-value on commas, excluding any that occur 187 inside of a quoted-string production. 188 3. Flattening the list of lists into a single list that represents 189 the individual header field-values. 190 4. Case-normalising each value in both lists to lowercase. 191 5. Trimming any OWS from the start and end of the field-values. 193 For example, given the set of headers: 195 Foo: 1 196 Bar: z 197 Foo: 2, a="b,c" 199 A modifier for "Foo" would operate on the list of presented values 200 '1', '2', 'a="b,c"'. 202 Note that step 2 of this algorithm optimistically assumes that 203 double-quotes in a header field value denote the use of the quoted- 204 string as defined by [I-D.ietf-httpbis-p1-messaging]; the cache does 205 not need to "understand" the specific header field. 207 Once the appropriate header fields from both the original request and 208 the stored request are processed in this manner, the result is two 209 (possibly empty) lists of values for each specified header field. 211 The key modifiers (as specified in the Key header field) are then 212 applied to the lists in the order they appear in Key (left to right). 213 If any modifier does not return a match (as per its definition), the 214 headers are said not to match. If all of the modifiers return a 215 match, the headers are said to match. 217 Note that some types of modifiers are said to always match; they can 218 be used to alter the input lists, or to alter the semantics of 219 subsequent matches. 221 Unrecognised modifiers MUST result in a failure to match. 223 2.2. Key Modifiers 225 This document defines the following key modifiers: 227 2.2.1. "w": Word Match Modifier 229 The "w" modifier matches if the parameter value (after unquoting) 230 matches (character-for-character) at least one whole member in both 231 lists. 233 2.2.2. "s": Substring Match Modifier 235 The "s" modifier matches if the parameter value (after unquoting) is 236 contained as a sequence of characters in at least one member of both 237 lists. 239 2.2.3. "b": Beginning Substring Match Modifier 241 The "b" modifier matches if both lists contain at least one member 242 that begins with the same sequence of characters as the parameter 243 value (after unquoting). 245 2.2.4. "p": Parameter Prefix Match Modifier 247 The "p" modifier matches if both lists contain at least one member 248 whose sequence of characters up to (but not including) the first 249 semi-colon (";") matches the parameter value, case insensitively, 250 after whitespace is removed. 252 For example, given the key: 254 Key: Accept;p="text/html" 256 then each of the following header fields is a match: 258 Accept: text/html 259 Accept: text/HTML; q=0.5 260 Accept: text/html;q=0.1 261 Accept: text/html; foo="bar" 263 but does not match: 265 Accept: text/plain 266 Accept: text/plain; type="text/html" 268 2.2.5. "pr": Parameter Range Modifier 270 The "pr" modifier matches if both lists contain at least one member 271 with the indicated attribute, and its value falls within a specified 272 numeric range. 274 This modifier assumes that list members have a "attribute=value" 275 format (following the parameter rule in 276 [I-D.ietf-httpbis-p2-semantics]). 278 In the modifier, the indicated attribute is conveyed using the 279 characters before the colon character in the parameter value; the 280 range is that afterwards. 282 Formally, the syntax is: 284 parameter_range = attribute ":" "[" [ range_num ] ":" [ range_num ] "]" 285 range_num = [ "-" ] 1*DIGIT 287 For example, given the key: 289 Key: Foo;pr=bar[20:30] 291 the indicated attribute is 'bar', and the range is from 20 to 30 292 (inclusive). Thus, each of the following headers would match: 294 Foo: bar=20 295 Foo: BAr=25 296 Foo: bar=30, baz=100 297 Foo: baz=10, bar=50, bar=10 299 whilst the following would not: 301 Foo: bar=19 302 Foo: bar= 303 Foo: bar=-30 304 Foo: bar= 25 305 Foo: thing=100 306 Foo: bar 308 Note that the indicated attribute is always case-insensitive. 310 The range can be incomplete on either side; for example, given: 312 Key: Foo;pr=bar[:30] 314 each of the following headers would match: 316 Foo: bar=20 317 Foo: bar=1, baz=wibble 318 Foo: bar=0 319 Foo: bar=-500 321 2.2.6. "c": Case Sensitivity Flag 323 The "c" modifier always matches, and has the side effect of reverting 324 the case normalisation of the header lists (see #4 in the list 325 above), so that subsequent matches become case sensitive. 327 2.2.7. "n": Not Flag 329 The "n" modifier always matches, and has the side effect of modifying 330 the semantics of subsequent modifiers (i.e., the match modifiers to 331 its right, lexically) so that they will be considered to match if 332 they do not, and likewise they will be considered not to match if 333 they do. 335 For example, given a response with: 337 Key: Foo;w="a";n;w="b" 339 then the presented header: 341 Foo: a, c 343 would match, while 345 Foo: a, b 347 would not (because it contains "b"). 349 2.3. Examples 351 For example, this response header field: 353 Key: cookie;w="_sess=fhd378";c;w="ID=\"Roy\"", 354 Accept-Encoding;w="gzip" 356 would allow the cache to reuse the response it occurs in if the 357 presented request contains: 359 o A Cookie header containing both ID="Roy" (in that case) and 360 _sess=fhd378 (evaluated case insensitively), and 361 o An Accept-Encoding header containing the token "gzip" (evaluated 362 case insensitively). 364 Less convoluted examples include matching any request with a User- 365 Agent field value containing "MSIE" in any combination of case: 367 Key: user-agent;s="MSIE" 369 And an Accept-Language field value for French: 371 Key: accept-language;b="fr" 373 2.4. Relationship to Vary 375 Origin servers SHOULD still send Vary as normal with Key, to 376 accommodate implementations that do not (yet) understand it. For 377 example, 379 Vary: Accept-Encoding 380 Key: Accept-Encoding;w="gzip" 382 3. IANA Considerations 384 TBD 386 4. Security Considerations 388 TBD 390 5. Normative References 392 [I-D.ietf-httpbis-p1-messaging] 393 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 394 (HTTP/1.1): Message Syntax and Routing", 395 draft-ietf-httpbis-p1-messaging-21 (work in progress), 396 October 2012. 398 [I-D.ietf-httpbis-p2-semantics] 399 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 400 (HTTP/1.1): Semantics and Content", 401 draft-ietf-httpbis-p2-semantics-21 (work in progress), 402 October 2012. 404 [I-D.ietf-httpbis-p6-cache] 405 Fielding, R., Nottingham, M., and J. Reschke, "Hypertext 406 Transfer Protocol (HTTP/1.1): Caching", 407 draft-ietf-httpbis-p6-cache-21 (work in progress), 408 October 2012. 410 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 411 Requirement Levels", BCP 14, RFC 2119, March 1997. 413 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 414 Specifications: ABNF", STD 68, RFC 5234, January 2008. 416 Authors' Addresses 418 Roy T. Fielding 419 Adobe Systems Incorporated 421 Email: fielding@gbiv.com 422 URI: http://roy.gbiv.com/ 424 Mark Nottingham 426 Email: mnot@mnot.net 427 URI: http://www.mnot.net/