wdiff draft-fielding-http-key-02.txt draft-fielding-http-key-03.txt

Network Working Group R. Fielding
Internet-Draft Adobe Systems Incorporated
Intended status: Informational M. Nottingham
Expires: August 23, 2013 February 19, 2013 March 27, 2016 September 24, 2015

The Key HTTP Response Header Field
draft-fielding-http-key-02
draft-fielding-http-key-03

Abstract

The 'Key' header field for HTTP responses allows an origin server to
describe the secondary cache key ([RFC7234], section 4.1) for a negotiated response:
resource, by conveying what is effectively a short algorithm that can
be used upon later requests to determine if the same a stored response is reusable.
reusable for a given request.

Key has the advantage of avoiding an additional round trip for
validation whenever a new request differs slightly, but not
significantly, from prior requests.

Key also informs user agents of the request characteristics that
might result in different content, which can be useful if the user
agent is not sending Accept* request header fields in order to reduce the
risk of fingerprinting.

Note to Readers

The issues list for this draft can be found at
https://github.com/mnot/I-D/labels/key .

Status of this This Memo

This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."

This Internet-Draft will expire on August 23, 2013. March 27, 2016.

This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.

Table of Contents

1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.
1.2. Notational Conventions . . . . . . . . . . . . . . . . . . 3 4
2. The "Key" Response Header Field . . . . . . . . . . . . . . . 3 4
2.1. Header Matching Relationship with Vary . . . . . . . . . . . . . . . . . 5
2.2. Calculating a Secondary Cache Key . . . . 4
2.2. Key Modifiers . . . . . . . . 6
2.2.1. Creating a Header Field Value . . . . . . . . . . . . 8
2.2.2. Failing Parameter Processing . . 6
2.2.1. "w": Word Match Modifier . . . . . . . . . . 9
2.3. Key Parameters . . . . . 6
2.2.2. "s": Substring Match Modifier . . . . . . . . . . . . 6
2.2.3. "b": Beginning Substring Match Modifier . . . . 9
2.3.1. div . . . 6
2.2.4. "p": Parameter Prefix Match Modifier . . . . . . . . . 6
2.2.5. "pr": Parameter Range Modifier . . . . . . . . . . . . 7
2.2.6. "c": Case Sensitivity Flag . 9
2.3.2. partition . . . . . . . . . . . . . 8
2.2.7. "n": Not Flag . . . . . . . . . 10
2.3.3. match . . . . . . . . . . . 8
2.3. Examples . . . . . . . . . . . . . 11
2.3.4. substr . . . . . . . . . . . . 8
2.4. Relationship to Vary . . . . . . . . . . . 12
2.3.5. param . . . . . . . . 9 . . . . . . . . . . . . . . . . 13
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 15
3.1. Procedure . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2. Registrations . . . . . . . . . . . . . . . . . . . . . . 15
4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 15
5. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.1. Normative References . . . . . . . . . . . . . . . . . . 16
5.2. Informative References . . . . 9 . . . . . . . . . . . . . 16
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 17
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 17

1. Introduction

In HTTP caching [I-D.ietf-httpbis-p6-cache], [RFC7234], the Vary response header field effectively
modifies the key used to store and access a response to include
information from the request's headers. This "secondary cache key"
allows proactive content negotiation [I-D.ietf-httpbis-p2-semantics] [RFC7231] to work with caches.

However,

Vary's operation is coarse-grained; although generic; it works well when caches are
allowed to normalise understand the values
semantics of headers based upon their
semantics, doing so requires the cache to understand those semantics,
and is still quite limited. selecting headers. For example, if the Accept-Language
request header field has a response is cached with well-defined syntax for expressing the
client's preferences; a cache that understands this header field can
select the appropriate response (based upon its Content-Language
header field:

Vary: Accept-Encoding

and field) and its associated request is:

Accept-Encoding: gzip

then serve it to a subsequent request with client, without any knowledge of the following header is (in
underlying resource.

Vary does not work as well when the criteria for selecting a strict
reading response
are specific to the resource. For example, if the nature of the
response depends upon the presence or absence of HTTP) not a match, resulting particular Cookie
([RFC6265]) in a cache miss:

Accept-Encoding: identity, gzip request, Vary doesn't have a mechanism to offer
enough fine-grained, resource-specific information to aid a cache's
selection of the appropriate response.

This document defines a new response header field, "Key", that allows
servers
resources to describe the secondary cache key in a much more fine-grained fine-grained,
resource-specific manner, leading to improved cache efficiency. efficiency when
responses depend upon such headers.

1.1. Examples

For example, this response header field:

Key: cookie;param=_sess;param=ID

indicates that the selected response depends upon the "_sess" and
"ID" cookie values.

This Key:

Key: user-agent;substr=MSIE

indicates that there are two possible secondary cache keys for this
resource; one for requests whose User-Agent header field contains
"MSIE", and another for those that don't.

A more complex example:

Key: user-agent;substr=MSIE;Substr="mobile", Cookie;param="ID"

indicates that the selected response depends on the presence of two
strings in the User-Agent request header field, as well as the value
of the "ID" cookie request header field.

1.2. Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].

This document uses the Augmented Backus-Naur Form (ABNF) notation of
[RFC5234] with (including the DQUOTE rule), and the list rule extension
defined in
[I-D.ietf-httpbis-p1-messaging], Appendix B. [RFC7230], Section 7. It includes by reference the OWS, field-name and field-
name, quoted-string and quoted-pair rules from that document, and the
parameter and attribute rules rule from
[I-D.ietf-httpbis-p2-semantics]. [RFC7231].

2. The "Key" Response Header Field

The "Key" response header field describes the portions of the request attributes
that the server has used resource currently uses to select the current representation. representations.

As such, its semantics are similar to the "Vary" response header
field, but it allows more fine-grained description, using "key
modifiers".
parameters".

Caches can use this information as part of determining whether a
stored response can be used to satisfy a given request. When a cache
knows and fully implements this mechanism, understands the Key header field for a given
resource, it MAY ignore the Vary response header field. field in any stored
responses for it.

Additionally, user agents can use this information Key to discover if additional
request header fields might influence the resulting
response. resource's selection of
responses.

The Key field-value is a comma-delimited list of selecting header
fields (similar to Vary), with zero to many modifiers to parameters each,
delimited by semicolons. Whitespace is not allowed in the field-
value between each field-name and its parameter set.

Key = 1#field-name *( ";" parameter )

Note that, as per [RFC7231], parameter names are case-insensitive,
and parameter values can be double-quoted strings (potentially with
""-escaped characters inside).

The following header fields therefore have identical semantics: the same effect:

Vary: Accept-Encoding, Accept-Language Cookie
Key: Accept-Encoding, Accept-Language Cookie

However, Key's use of modifiers parameters allows:

Key: Accept-Encoding;w="gzip", Accept-Language;b="fr" Accept-Encoding, Cookie;param=foo

to indicate that the secondary cache key depends upon the Accept-
Encoding header field and the "foo" Cookie.

One important difference between Vary and Key is how they are
applied. Vary is specified to be specific to the response it occurs in
within, whereas Key is allowed specific to be reused the resource (as identified by the
request URL) it is associated with. The most recent key you receive
for requests a given resource is applicable to all responses from that contain the token "gzip" (in any case)
resource.

This difference allows more efficient implementation (and reflects
practices that many caches use in the
Accept-Encoding header field and an Accept-Language implementing Vary already).

This specification defines a selection of Key parameters to address
common use cases such as selection upon individual Cookie header field
value that starts
fields, User-Agent substrings and numerical ranges. Future
parameters may define further capabilities.

2.1. Relationship with "fr" (in any case). Vary

Origin servers SHOULD still send Vary when using Key, to ensure
backwards compatibility.

For example,

Vary: User-Agent
Key: User-Agent;substr="mozilla"

Note that both the field-name that, in some cases, it may be better to explicitly use "Vary:
*" if clients and modifier names themselves are case
insensitive.

2.1. Header Matching caches don't have any practical way to use the Vary
header field's value. For example,

Vary: *
Key: Cookie;param="ID"

Except when Vary: * is used, the set of headers used in Key SHOULD
reflect the same request header fields as Vary does, even if they
don't have parameters. For example,

Vary: Accept-Encoding, User-Agent
Key: Accept-Encoding, User-Agent;substr="mozilla"

Here, Accept-Encoding is included in Key without parameters; caches
MAY treat these as they do values in the Vary header, relying upon
knowledge of their generic semantics to select an appropriate
response.

2.2. Calculating a Secondary Cache Key

When used by a cache to determine whether a stored response can be
used to satisfy a presented request, each field-name in Key
identifies a potential request header, just as with the Vary response
header field.

However, each of these can have zero to many "key modifiers" key parameters that
change how the response selection process (as defined in
[I-D.ietf-httpbis-p6-cache], [RFC7234],
Section 4.3)) works.

In particular, when a cache that fully implements the Key header field MUST NOT
use this specification, it
creates a stored response unless all of the selecting header fields
nominated secondary cache key for every request by following the
instructions in the Key header field match in both field, ignoring the original Vary header for
this purpose.

Then, when a new request
(i.e., is presented, the secondary cache key
generated for that associated with request can be compared to the stored response) and one to find
the presented
request.

Modifiers operate on a list of zero appropriate response, to many field-values. This list determine if it can be selected.

To generate a secondary cache key for a given request (including that
which is constructed by:

1. Starting stored with a response) using Key, the field-values of all following steps are
taken:

1. If the Key header fields that have field is not present on the
given field-name. most recent
cacheable (as per [RFC7234], Section 3)) response seen for the
resource, abort this algorithm (i.e., fall back to using Vary to
determine the secondary cache key).

2. Splitting each field-value Let "key_value" be the most recently seen Key header field value
for the resource, as the result of Creating a Header Field Value
(Section 2.2.1).

3. Let "secondary_key" be an empty string.

4. Create "key_list" by splitting "key_value" on commas, excluding "," characters.

5. For "key_item" in "key_list":

1. Remove any that occur
inside of leading and trailing WSP from "key_item".

2. If "key_item" does not contain a quoted-string production. ";" character, fail
parameter processing (Section 2.2.2) and skip to the next
"key_item".

3. Flattening Let "field_name" be the list string before the first ";" character
in "key_item".

4. Let "field_value" be the result of lists into Creating a single list that represents Header Field
Value (Section 2.2.1) with "field_name" as the individual
"target_field_name" and the request header field-values.
4. Case-normalising each value in both lists to lowercase. list as
"header_list".

5. Trimming any OWS from Let "parameters" be the start and end of string after the field-values. first ";" character
in "key_item".

6. Create "param_list" by splitting "parameters" on ";"
characters, excepting ";" characters within quoted strings,
as per [RFC7230] Section 3.2.6.

7. For example, given "parameter" in "param_list":

1. If "parameter" does not contain a "=", fail parameter
processing (Section 2.2.2) and skip to the set of headers:

Foo: 1
Bar: z
Foo: 2, a="b,c"

A modifier for "Foo" would operate on next
"key_item".

2. Let "param_name" be the list of presented values
'1', '2', 'a="b,c"'.

Note that step 2 of this string before the first "="
character in "parameter", case-normalized to lowercase.

3. If "param_name" does not identify a Key parameter
processing algorithm optimistically assumes that
double-quotes is implemented, fail parameter
processing (Section 2.2.2) and skip to the next
"key_item".

4. Let "param_value" be the string after the first "="
character in a header field value denote "parameter".

5. If the use first and last characters of "param_value" are
both DQUOTE:

1. Remove the quoted-
string first and last characters of
"param_value".

2. Replace quoted-pairs within "param_value" with the
octet following the backslash, as per [RFC7230]
Section 3.2.6.

6. If "param_value" does not conform to the syntax defined
for it by [I-D.ietf-httpbis-p1-messaging]; the cache parameter definition, fail parameter
processing Section 2.2.2 and skip to the next "key_item".

7. Run the identified processing algorithm on "field_value"
with the "param_value", and append the result to
"secondary_key". If parameter processing fails
Section 2.2.2, skip to the next "key_item".

8. Append a separator character (e.g., NULL) to
"secondary_key".

6. Return "secondary_key".

Note that this specification does not need require that exact algorithm to
be implemented. However, implementations' observable behavior MUST
be identical to "understand" running it. This includes parameter processing
algorithms; implementations MAY use different internal artefacts for
secondary cache keys, as long as the specific header field.

Once results are the appropriate header fields from both same.

Likewise, while the original request secondary cache key associated with both stored
and presented requests is required to use the stored request are processed most recently seen Key
header field for the resource in question, this manner, the result is two
(possibly empty) lists can be achieved using
a variety of values implementation strategies, including (but not limited
to):

o Generating a new secondary cache key for every stored response
associated with the resource upon each specified header field.

The request.

o Caching the secondary cache key modifiers (as specified in with the stored request/response
pair and re-generating it when the Key header field) are then
applied field is observed to
change.

o Caching the lists in secondary cache key with the stored response and
invalidating the stored response(s) when the order they appear in Key (left header field is
observed to right). change.

2.2.1. Creating a Header Field Value

Given a header field name "target_field_name" and "header_list", a
list of ("field_name", "field_value") tuples:

1. Let "target_field_values" be an empty list.

2. For each ("field_name", "field_value") tuple in "header_list":

1. If any modifier "field_name" does not return a match (as per its definition), "target_field_name", skip to
the
headers are said not next tuple.

2. Strip leading and trailing WSP from "field_value" and append
it to match. "target_field_values".

3. If all of the modifiers "target_field_values" is empty, return a
match, an empty string.

4. Return the headers are said to match.

Note that some types concatenation of modifiers are said "target_field_values", separating
each with "," characters.

2.2.2. Failing Parameter Processing

In some cases, a key parameter cannot determine a secondary cache key
corresponding to always match; they can
be used its nominated header field value. When this
happens, Key processing needs to alter fail safely, so that the input lists, correct
behavior is observed.

When this happens, implementations MUST either behave as if the Key
header was not present, or to alter assure that the semantics of
subsequent matches.

Unrecognised modifiers MUST result nominated header fields
being compared match, as per [RFC7234], Section 4.1.

2.3. Key Parameters

A Key parameter associates a name with a specific processing
algorithm that takes two inputs; a HTTP header value "header_value"
(as described in Section 2.2.1), and "parameter_value", a failure to match.

2.2. Key Modifiers string that
indicates how the identified header should be processed.

The set of key parameters (and their associated processing
algorithms) is extensible; see Section 3. This document defines the
following key modifiers:

2.2.1. "w": Word Match Modifier parameters:

2.3.1. div

The "w" modifier matches if the "div" parameter value (after unquoting)
matches (character-for-character) at least one whole member in both
lists.

2.2.2. "s": Substring Match Modifier

The "s" modifier matches if the parameter value (after unquoting) is
contained as normalizes positive integer header values into
groups by dividing them by a sequence of characters in at least one member of both
lists.

2.2.3. "b": Beginning Substring Match Modifier

The "b" modifier matches if both lists contain at least one member
that begins with the same sequence configured value.

Its value's syntax is:

div = 1*DIGIT

To process a set of characters as the header fields against a div parameter, follow
these steps (or their equivalent):

1. If "parameter_value" is "0", fail parameter
value (after unquoting).

2.2.4. "p": Parameter Prefix Match Modifier

The "p" modifier matches if both lists contain at least one member
whose sequence of processing
Section 2.2.2.

2. If "header_value" is the empty string, return "none".

3. If "header_value" contains a ",", remove it and all subsequent
characters.

4. Remove all WSP characters up to (but from "header_value".

5. If "header_value" does not including) the first
semi-colon (";") matches match the div ABNF rule, fail
parameter value, case insensitively,
after whitespace is removed. processing (Section 2.2.2).

6. Return the quotient of "header_value" / "parameter_value"
(omitting the modulus).

For example, given the key: Key: Accept;p="text/html"

then each

Key: Bar;div=5

indicates that the "Bar" header's field value should be partitioned
into groups of 5. Thus, the following header fields is a match:

Accept: text/html
Accept: text/HTML; q=0.5
Accept: text/html;q=0.1
Accept: text/html; foo="bar"

but does not match:

Accept: text/plain
Accept: text/plain; type="text/html"

2.2.5. "pr": Parameter Range Modifier

The "pr" modifier matches if both lists contain at least one member
with the indicated attribute, and its value falls within a specified
numeric range.

This modifier assumes that list members have a "attribute=value"
format (following field values would be
considered the parameter rule same (because, divided by 5, they all result in
[I-D.ietf-httpbis-p2-semantics]).

In the modifier, the indicated attribute is conveyed using the
characters before the colon character 1):

Bar: 1
Bar: 3 , 42
Bar: 4, 1

whereas these would be considered to be in the a different group
(because, divided by 5, they all result in 2);

Bar: 12
Bar: 10
Bar: 14, 1

2.3.2. partition

The "partition" parameter value; the
range is that afterwards.

Formally, the normalizes positive numeric header values
into pre-defined segments.

Its value's syntax is:

parameter_range

partition = attribute ":" "[" [ range_num segment ] *( ":" [ range_num segment ] "]"
range_num )
segment = [ "-" 0*DIGIT "." ] 1*DIGIT

To process a set of header fields against a partition parameter,
follow these steps (or their equivalent):

1. If "header_value" is the empty string, return "none".

2. If "header_value" contains a ",", remove it and all subsequent
characters.

3. Remove all WSP characters from "header_value".

4. If "header_value" does not match the segment ABNF rule, fail
parameter processing (Section 2.2.2).

5. Let "segment_id" be 0.

6. Create a list "segment_list" by splitting "parameter_value" on
":" characters.

7. For each "segment_value" in "segment_list":

1. If "header_value" is less than "segment_value" when they are
numerically compared, skip to step 7.

2. Increment "segment_id" by 1.

8. Return "segment_id".

For example, given the key: Key: Foo;pr=bar[20:30]

the indicated attribute is 'bar', and

Key: Foo;partition=20:30:40

indicates that the range is from "Foo" header's field value should be divided into
four segments:

o less than 20

o 20 to less than 30
(inclusive).

o 30 to less than 40

o forty or greater

Thus, each of the following headers would match: all be normalized to the first
segment:

Foo: bar=20 1
Foo: BAr=25 0
Foo: bar=30, baz=100 4, 54
Foo: baz=10, bar=50, bar=10

whilst 19.9

whereas the following would not:

Foo: bar=19
Foo: bar=
Foo: bar=-30 fall into the second segment:

Foo: bar= 25 20
Foo: thing=100 29.999
Foo: bar

Note that the indicated attribute is always case-insensitive. 24 , 10

2.3.3. match

The range can be incomplete "match" parameter is used to determine if an exact value occurs
in a list of header values. It is case-sensitive.

Its value's syntax is:

match = ( token / quoted-string )

To process a set of header fields against a match parameter, follow
these steps (or their equivalent):

1. If "header_value" is the empty string, return "none".

2. Create "header_list" by splitting "header_value" on either side; for example, given:

Key: Foo;pr=bar[:30] ","
characters.

3. For each "header_item" in "header_list":

1. Remove leading and trailing WSP characters in "header_item".

2. If the value of "header_item" is character-for-character
identical to "parameter_value", return "1".

4. Return "0".

For example, the Key:

Key: Baz;match="charlie"

Would return "1" for the following headers would match:

Foo: bar=20
Foo: bar=1, baz=wibble
Foo: bar=0
Foo: bar=-500

2.2.6. "c": Case Sensitivity Flag header field values:

Baz: charlie
Baz: foo, charlie
Baz: bar, charlie , abc

and "0" for these:

Baz: theodore
Baz: joe, sam
Baz: "charlie"
Baz: Charlie
Baz: cha rlie
Baz: charlie2

2.3.4. substr

The "c" modifier always matches, "substr" parameter is used to determine if a value occurs as a
substring of an item in a list of header values. It is case-
sensitive.

Its value's syntax is:

substr = ( token / quoted-string )
To process a set of header fields against a substr parameter, follow
these steps (or their equivalent):

1. If "header_value" is the empty string, return "none".

2. Create "header_list" by splitting "header_value" on ","
characters.

3. For each "header_item" in "header_list":

1. Remove leading and has trailing WSP characters in "header_item".

2. If the side effect value of reverting
the case normalisation "parameter_value" is character-for-character
present as a substring of "header_value", return "1".

4. Return "0".

For example, the Key:

Key: Abc;substr=bennet

Would return "1" for the following header lists (see #4 in field values:

Abc: bennet
Abc: foo, bennet
Abc: abennet00
Abc: bar, 99bennet , abc
Abc: "bennet"

and "0" for these:

Abc: theodore
Abc: joe, sam
Abc: Bennet
Abc: Ben net

2.3.5. param

The "param" parameter considers the request header field as a list
above), so that subsequent matches become case sensitive.

2.2.7. "n": Not Flag

The "n" modifier always matches, of
key=value parameters, and has uses the side effect of modifying nominated key's value as the semantics
secondary cache key.

Its value's syntax is:

param = ( token / quoted-string )

To process a list of subsequent modifiers (i.e., the match modifiers to
its right, lexically) so that they will header fields against a param parameter, follow
these steps (or their equivalent):

1. Let "header_list" be considered to match if
they do not, an empty list.

2. Create "header_list_tmp1" by splitting header_value on ","
characters.

3. For each "header_item_tmp1" in "header_list_tmp1":

1. Create "header_list_tmp2" by splitting "header_item_tmp1" on
";" characters.

2. For each "header_item_tmp2" in "header_list_tmp2":

1. Remove leading and likewise they will be considered not trailing WSP from "header_item_tmp2".

2. Append "header_item_tmp2" to match if
they do. header_list.

4. For example, given a response with:

Key: Foo;w="a";n;w="b"

then each "header_item" in "header_list":

1. If the presented header:

Foo: a, c

would match, while

Foo: a, b

would "=" character does not occur within "header_item",
skip to the next "header_item".

2. Let "item_name" be the string occurring before the first "="
character in "header_item".

3. If "item_name" does not (because case-insensitively match
"parameter_value", skip to the next "header_item".

4. Return the string occurring after the first "=" character in
"header_item".

5. Return the empty string.

Note that steps 2 and 3 accommodate semicolon-separated values, so
that it contains "b").

2.3. Examples can be used with the Cookie request header field.

For example, this response header field: the Key:

Key: cookie;w="_sess=fhd378";c;w="ID=\"Roy\"",
Accept-Encoding;w="gzip" Def;param=liam

The following headers would allow the cache to reuse return the response it occurs string (surrounded in if single
quotes) indicated:

Def: liam=123 // '123'
Def: mno=456 // ''
Def: // ''
Def: abc=123; liam=890 // '890'
Def: liam="678" // '"678"'

3. IANA Considerations

This specification defines the
presented request contains: HTTP Key Parameter Registry,
maintained at http://www.iana.org/assignments/http-parameters/http-
parameters.xhtml#key .

3.1. Procedure

Key Parameter registrations MUST include the following fields:

o A Cookie header containing both ID="Roy" (in that case) and
_sess=fhd378 (evaluated case insensitively), and Parameter Name: [name]

o An Accept-Encoding header containing Reference: [Pointer to specification text]

Values to be added to this namespace require IETF Review (see
Section 4.1 of [RFC5226]) and MUST conform to the token "gzip" (evaluated
case insensitively).

Less convoluted examples include matching any request with a User-
Agent field value containing "MSIE" purpose of content
coding defined in this section.

3.2. Registrations

This specification makes the following entries in the HTTP Key
Parameter Registry:

4. Security Considerations

Because Key is an alternative to Vary, it is possible for caches to
behave differently based upon whether they implement Key. Likewise,
because support for any combination one Key parameter is not required, it is
possible for different implementations of case:

Key: user-agent;s="MSIE"

And Key to behave differently.
In both cases, an Accept-Language field value for French:

Key: accept-language;b="fr"

2.4. Relationship attacker might be able to exploit these
differences.

This risk is mitigated by the requirement to fall back to Vary

Origin when
unsupported parameters are encountered, coupled with the requirement
that servers SHOULD still send that use Key also include a relevant Vary as normal header.

An attacker with the ability to inject response headers might be able
to perform a cache poisoning attack that tailors a response to a
specific user (e.g., by Keying to a Cookie that's specific to them).
While the attack is still possible without Key, the ability to
accommodate tailor
is new.

When implemented, Key might result in a larger number of stored
responses for a given resource in caches; this, in turn, might be
used to create an attack upon the cache itself. Good cache
replacement algorithms and denial of service monitoring in cache
implementations that do not (yet) understand it. For
example,

Vary: Accept-Encoding
Key: Accept-Encoding;w="gzip"

3. IANA Considerations

TBD

4. Security Considerations

TBD are reasonable mitigations against this risk.

5. References

5.1. Normative References

[I-D.ietf-httpbis-p1-messaging]

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.

[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/
RFC5234, January 2008,
<http://www.rfc-editor.org/info/rfc5234>.

[RFC7230] Fielding, R. R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing",
draft-ietf-httpbis-p1-messaging-21 (work in progress),
October 2012.

[I-D.ietf-httpbis-p2-semantics] RFC
7230, DOI 10.17487/RFC7230, June 2014,
<http://www.rfc-editor.org/info/rfc7230>.

[RFC7231] Fielding, R. R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content",
draft-ietf-httpbis-p2-semantics-21 (work in progress),
October 2012.

[I-D.ietf-httpbis-p6-cache] RFC 7231, DOI
10.17487/RFC7231, June 2014,
<http://www.rfc-editor.org/info/rfc7231>.

[RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
draft-ietf-httpbis-p6-cache-21 (work in progress),
October 2012.

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14,
RFC 2119, March 1997.

[RFC5234] Crocker, D. 7234, DOI 10.17487/RFC7234, June 2014,
<http://www.rfc-editor.org/info/rfc7234>.

5.2. Informative References

[RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
DOI 10.17487/RFC6265, April 2011,
<http://www.rfc-editor.org/info/rfc6265>.

Appendix A. Acknowledgements

Thanks to Ilya Grigorik, Amos Jeffries and P. Overell, "Augmented BNF Yoav Weiss for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. their
feedback.

Authors' Addresses

Roy T. Fielding
Adobe Systems Incorporated

Email: fielding@gbiv.com
URI: http://roy.gbiv.com/

Mark Nottingham

Email: mnot@mnot.net
URI: http://www.mnot.net/