idnits 2.17.1 draft-fielding-http-key-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 : ---------------------------------------------------------------------------- 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 (September 12, 2012) is 4215 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-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-20 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: March 16, 2013 September 12, 2012 7 The Key HTTP Response Header Field 8 draft-fielding-http-key-00 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. Key has the advantage of avoiding an 16 additional round trip for validation whenever a new request differs 17 slightly, but not significantly, from prior requests. Key also 18 informs user agents of the request characteristics that might result 19 in different content, which can be useful if the user agent is not 20 sending Accept* fields in order to reduce the risk of fingerprinting. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on March 16, 2013. 39 Copyright Notice 41 Copyright (c) 2012 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 58 2. The "Key" Response Header Field . . . . . . . . . . . . . . . . 3 59 2.1. Header Matching . . . . . . . . . . . . . . . . . . . . . . 4 60 2.2. Key Modifiers . . . . . . . . . . . . . . . . . . . . . . . 5 61 2.2.1. "w": Word Match Modifier . . . . . . . . . . . . . . . 6 62 2.2.2. "s": Substring Match Modifier . . . . . . . . . . . . . 6 63 2.2.3. "b": Beginning Substring Match Modifier . . . . . . . . 6 64 2.2.4. "c": Case Sensitivity Flag . . . . . . . . . . . . . . 6 65 2.2.5. "n": Not Flag . . . . . . . . . . . . . . . . . . . . . 6 66 2.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 68 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 69 5. Normative References . . . . . . . . . . . . . . . . . . . . . 7 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8 72 1. Introduction 74 In HTTP caching [I-D.ietf-httpbis-p6-cache], the Vary response header 75 field effectively modifies the key used to store and access a 76 response to include information from the request's headers. This 77 allows proactive content negotiation [I-D.ietf-httpbis-p2-semantics] 78 to work with caches. 80 However, Vary's operation is coarse-grained; although caches are 81 allowed to normalise the values of headers based upon their 82 semantics, this requires the cache to understand those semantics, and 83 is still quite limited. 85 For example, if a response is cached with the response header field: 87 Vary: Accept-Encoding 89 and and its associated request is: 91 Accept-Encoding: gzip 93 then a subsequent request with the following header is (in a strict 94 reading of HTTP) not a match, resulting in a cache miss: 96 Accept-Encoding: identity, gzip 98 This document defines a new response header field, "Key", that allows 99 servers to describe the cache key in a much more fine-grained manner, 100 leading to improved cache efficiency. 102 1.1. Notational Conventions 104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 106 document are to be interpreted as described in [RFC2119]. 108 This document uses the Augmented Backus-Naur Form (ABNF) notation of 109 [RFC5234] with the list rule extension defined in 110 [I-D.ietf-httpbis-p1-messaging], Appendix B. It includes by 111 reference the OWS, field-name and quoted-string rules from that 112 document, and the parameter rule from 113 [I-D.ietf-httpbis-p2-semantics]. 115 2. The "Key" Response Header Field 117 The "Key" response header field describes the request attributes that 118 the server has used to select the current representation. 120 As such, its semantics are similar to the "Vary" response header 121 field, but it allows more fine-grained description, using "key 122 modifiers". 124 Caches can use this information as part of determining whether a 125 stored response can be used to satisfy a given request. When a cache 126 fully implements this mechanism, it MAY ignore the Vary response 127 header field. 129 User agents can use this information to discover if additional 130 content negotiation header fields might influence the resulting 131 response. 133 The Key field-value is a comma-delimited list of selecting header 134 fields (similar to Vary), with zero to many modifiers to each, 135 delimited by semicolons. Whitespace is not allowed in the field- 136 value between each field-name and its parameter set. 138 Key = 1#field-name *( ";" parameter ) 140 The following header fields therefore have identical semantics: 142 Vary: Accept-Encoding, Accept-Language 143 Key: Accept-Encoding, Accept-Language 145 However, Key's use of modifiers allows: 147 Key: Accept-Encoding;w="gzip", Accept-Language;b="fr" 149 to indicate that the response it occurs in is allowed to be reused 150 for requests that contain the token "gzip" (in any case) in the 151 Accept-Encoding header field and an Accept-Language header field 152 value that starts with "fr" (in any case). 154 Note that both the field-name and modifier names themselves are case 155 insensitive. 157 2.1. Header Matching 159 When used by a cache to determine whether a stored response can be 160 used to satisfy a presented request, each field-name identifies a 161 potential request header, just as with the Vary response header 162 field. 164 However, each of these can have zero to many "key modifiers" that 165 change how the response selection process (as defined in 166 [I-D.ietf-httpbis-p6-cache], Section 4.3)) works. 168 In particular, a cache that implements the Key header field MUST NOT 169 use a stored response unless all of the selecting header fields 170 nominated by the Key header field match in both the original request 171 (i.e., that associated with the stored response) and the presented 172 request. 174 Modifiers operate on a list of zero to many field-values. This list 175 is constructed by: 177 1. Starting with the field-values of all header fields that have the 178 given field-name. 179 2. Splitting each field-value on commas, excluding any that occur 180 inside of a quoted-string production. 181 3. Flattening the list of lists into a single list that represents 182 the individual header field-values. 183 4. Case-normalising each value in both lists to lowercase. 184 5. Trimming any OWS from the start and end of the field-values. 186 For example, given the set of headers: 188 Foo: 1 189 Bar: z 190 Foo: 2, a="b,c" 192 A modifier for "Foo" would operate on the list of presented values 193 '1', '2', 'a="b,c"'. 195 Once the appropriate header fields from both the original request and 196 the stored request are processed in this manner, the result is two 197 (possibly empty) lists of values for each specified header field. 199 The key modifiers (as specified in the Key header field) are then 200 applied to the lists in the order they appear in Key (left to right). 201 If any modifier does not return a match (as per its definition), the 202 headers are said not to match. If all of the modifiers return a 203 match, the headers are said to match. 205 Note that some types of modifiers are said to always match; they can 206 be used to alter the input lists, or to alter the semantics of 207 subsequent matches. 209 Unrecognised modifiers MUST result in a failure to match. 211 2.2. Key Modifiers 213 This document defines the following key modifiers: 215 2.2.1. "w": Word Match Modifier 217 The "w" modifier matches if the parameter value (after unquoting) 218 matches (character-for-character) any whole value in both lists. 220 2.2.2. "s": Substring Match Modifier 222 The "s" modifier matches if the parameter value (after unquoting) is 223 contained as a sequence of characters within both lists. 225 2.2.3. "b": Beginning Substring Match Modifier 227 The "b" modifier matches if both lists contain a value that begins 228 with the same sequence of characters as the parameter value (after 229 unquoting). 231 2.2.4. "c": Case Sensitivity Flag 233 The "c" modifier always matches, and has the side effect of reverting 234 the case normalisation of the header lists (see #4 in the list 235 above), so that subsequent matches become case sensitive. 237 2.2.5. "n": Not Flag 239 The "n" modifier always matches, and has the side effect of modifying 240 the semantics of subsequent modifiers (i.e., the match modifiers to 241 its right, lexically) so that they will be considered to match if 242 they do not, and likewise they will be considered not to match if 243 they do. 245 For example, given a response with: 247 Key: Foo;w="a";n;w="b" 249 then the presented header: 251 Foo: a, c 253 would match, while 255 Foo: a, b 257 would not (because it contains "b"). 259 2.3. Examples 261 For example, this response header field: 263 Key: cookie;w="_sess=fhd378";c;w="ID=\"Roy\"", 264 Accept-Encoding;w="gzip" 266 would allow the cache to reuse the response it occurs in if the 267 presented request contains: 269 o A Cookie header containing both ID="Roy" (in that case) and 270 _sess=fhd378 (evaluated case insensitively), and 271 o An Accept-Encoding header containing the token "gzip" (evaluated 272 case insensitively). 274 Less convoluted examples include matching any request with a User- 275 Agent field value containing "MSIE" in any combination of case: 277 Key: user-agent;s="MSIE" 279 And an Accept-Language field value for French: 281 Key: accept-language;b="fr" 283 3. IANA Considerations 285 TBD 287 4. Security Considerations 289 TBD 291 5. Normative References 293 [I-D.ietf-httpbis-p1-messaging] 294 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 295 1: Message Routing and Syntax"", 296 draft-ietf-httpbis-p1-messaging-20 (work in progress), 297 July 2012. 299 [I-D.ietf-httpbis-p2-semantics] 300 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 301 2: Semantics and Payloads", 302 draft-ietf-httpbis-p2-semantics-20 (work in progress), 303 July 2012. 305 [I-D.ietf-httpbis-p6-cache] 306 Fielding, R., Lafon, Y., Nottingham, M., and J. Reschke, 307 "HTTP/1.1, part 6: Caching", 308 draft-ietf-httpbis-p6-cache-20 (work in progress), 309 July 2012. 311 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 312 Requirement Levels", BCP 14, RFC 2119, March 1997. 314 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 315 Specifications: ABNF", STD 68, RFC 5234, January 2008. 317 Authors' Addresses 319 Roy T. Fielding 320 Adobe Systems Incorporated 322 Email: fielding@gbiv.com 323 URI: http://roy.gbiv.com/ 325 Mark Nottingham 327 Email: mnot@mnot.net 328 URI: http://www.mnot.net/