draft-ietf-httpbis-key-00.txt   draft-ietf-httpbis-key-01.txt 
httpbis Working Group R. Fielding HTTP Working Group R. Fielding
Internet-Draft Adobe Systems Incorporated Internet-Draft Adobe Systems Incorporated
Intended status: Standards Track M. Nottingham Intended status: Standards Track M. Nottingham
Expires: April 21, 2016 October 19, 2015 Expires: September 3, 2016 March 2, 2016
The Key HTTP Response Header Field The Key HTTP Response Header Field
draft-ietf-httpbis-key-00 draft-ietf-httpbis-key-01
Abstract Abstract
The 'Key' header field for HTTP responses allows an origin server to The 'Key' header field for HTTP responses allows an origin server to
describe the secondary cache key ([RFC7234], section 4.1) for a describe the secondary cache key (RFC 7234, Section 4.1) for a
resource, by conveying what is effectively a short algorithm that can resource, by conveying what is effectively a short algorithm that can
be used upon later requests to determine if a stored response is be used upon later requests to determine if a stored response is
reusable for a given request. reusable for a given request.
Key has the advantage of avoiding an additional round trip for Key has the advantage of avoiding an additional round trip for
validation whenever a new request differs slightly, but not validation whenever a new request differs slightly, but not
significantly, from prior requests. significantly, from prior requests.
Key also informs user agents of the request characteristics that Key also informs user agents of the request characteristics that
might result in different content, which can be useful if the user might result in different content, which can be useful if the user
agent is not sending request header fields in order to reduce the agent is not sending request header fields in order to reduce the
risk of fingerprinting. risk of fingerprinting.
Note to Readers Note to Readers
The issues list for this draft can be found at Discussion of this draft takes place on the HTTP working group
mailing list (ietf-http-wg@w3.org), which is archived at
https://lists.w3.org/Archives/Public/ietf-http-wg/ .
Working Group information can be found at http://httpwg.github.io/ ;
source code and issues list for this draft can be found at
https://github.com/httpwg/http-extensions/labels/key . https://github.com/httpwg/http-extensions/labels/key .
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 21, 2016. This Internet-Draft will expire on September 3, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Notational Conventions . . . . . . . . . . . . . . . . . 4 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 4
2. The "Key" Response Header Field . . . . . . . . . . . . . . . 4 2. The "Key" Response Header Field . . . . . . . . . . . . . . . 4
2.1. Relationship with Vary . . . . . . . . . . . . . . . . . 5 2.1. Relationship with Vary . . . . . . . . . . . . . . . . . 5
2.2. Calculating a Secondary Cache Key . . . . . . . . . . . . 6 2.2. Calculating a Secondary Cache Key . . . . . . . . . . . . 6
2.2.1. Creating a Header Field Value . . . . . . . . . . . . 8 2.2.1. Creating a Header Field Value . . . . . . . . . . . . 8
2.2.2. Failing Parameter Processing . . . . . . . . . . . . 8 2.2.2. Failing Parameter Processing . . . . . . . . . . . . 8
2.3. Key Parameters . . . . . . . . . . . . . . . . . . . . . 8 2.3. Key Parameters . . . . . . . . . . . . . . . . . . . . . 9
2.3.1. div . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.3.1. div . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.2. partition . . . . . . . . . . . . . . . . . . . . . . 10 2.3.2. partition . . . . . . . . . . . . . . . . . . . . . . 10
2.3.3. match . . . . . . . . . . . . . . . . . . . . . . . . 11 2.3.3. match . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3.4. substr . . . . . . . . . . . . . . . . . . . . . . . 12 2.3.4. substr . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.5. param . . . . . . . . . . . . . . . . . . . . . . . . 13 2.3.5. param . . . . . . . . . . . . . . . . . . . . . . . . 13
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
3.1. Procedure . . . . . . . . . . . . . . . . . . . . . . . . 14 3.1. Procedure . . . . . . . . . . . . . . . . . . . . . . . . 14
3.2. Registrations . . . . . . . . . . . . . . . . . . . . . . 14 3.2. Registrations . . . . . . . . . . . . . . . . . . . . . . 14
4. Security Considerations . . . . . . . . . . . . . . . . . . . 15 4. Security Considerations . . . . . . . . . . . . . . . . . . . 15
5. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.1. Normative References . . . . . . . . . . . . . . . . . . 15 5.1. Normative References . . . . . . . . . . . . . . . . . . 15
5.2. Informative References . . . . . . . . . . . . . . . . . 16 5.2. Informative References . . . . . . . . . . . . . . . . . 16
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 16 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 16
Appendix B. Changes . . . . . . . . . . . . . . . . . . . . . . 16
B.1. Since -00 . . . . . . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction 1. Introduction
In HTTP caching [RFC7234], the Vary response header field effectively In HTTP caching [RFC7234], the Vary response header field effectively
modifies the key used to store and access a response to include modifies the key used to store and access a response to include
information from the request's headers. This "secondary cache key" information from the request's headers. This "secondary cache key"
allows proactive content negotiation [RFC7231] to work with caches. allows proactive content negotiation [RFC7231] to work with caches.
Vary's operation is generic; it works well when caches understand the Vary's operation is generic; it works well when caches understand the
skipping to change at page 4, line 14 skipping to change at page 4, line 20
1.2. Notational Conventions 1.2. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
This document uses the Augmented Backus-Naur Form (ABNF) notation of This document uses the Augmented Backus-Naur Form (ABNF) notation of
[RFC5234] (including the DQUOTE rule), and the list rule extension [RFC5234] (including the DQUOTE rule), and the list rule extension
defined in [RFC7230], Section 7. It includes by reference the field- defined in [RFC7230], Section 7. It includes by reference the field-
name, quoted-string and quoted-pair rules from that document, and the name, quoted-string and quoted-pair rules from that document, the OWS
parameter rule from [RFC7231]. rule from [RFC7230] and the parameter rule from [RFC7231].
2. The "Key" Response Header Field 2. The "Key" Response Header Field
The "Key" response header field describes the portions of the request The "Key" response header field describes the portions of the request
that the resource currently uses to select representations. that the resource currently uses to select representations.
As such, its semantics are similar to the "Vary" response header As such, its semantics are similar to the "Vary" response header
field, but it allows more fine-grained description, using "key field, but it allows more fine-grained description, using "key
parameters". parameters".
skipping to change at page 4, line 38 skipping to change at page 4, line 44
knows and fully understands the Key header field for a given knows and fully understands the Key header field for a given
resource, it MAY ignore the Vary response header field in any stored resource, it MAY ignore the Vary response header field in any stored
responses for it. responses for it.
Additionally, user agents can use Key to discover if additional Additionally, user agents can use Key to discover if additional
request header fields might influence the resource's selection of request header fields might influence the resource's selection of
responses. responses.
The Key field-value is a comma-delimited list of selecting header The Key field-value is a comma-delimited list of selecting header
fields (similar to Vary), with zero to many parameters each, fields (similar to Vary), with zero to many parameters each,
delimited by semicolons. Whitespace is not allowed in the field- delimited by semicolons.
value between each field-name and its parameter set.
Key = 1#field-name *( ";" parameter ) Key = 1#key-value
key-value = field-name *( OWS ";" OWS parameter )
Note that, as per [RFC7231], parameter names are case-insensitive, Note that, as per [RFC7231], parameter names are case-insensitive,
and parameter values can be double-quoted strings (potentially with and parameter values can be double-quoted strings (potentially with
""-escaped characters inside). "\"-escaped characters inside).
The following header fields have the same effect: The following header fields have the same effect:
Vary: Accept-Encoding, Cookie Vary: Accept-Encoding, Cookie
Key: Accept-Encoding, Cookie Key: Accept-Encoding, Cookie
However, Key's use of parameters allows: However, Key's use of parameters allows:
Key: Accept-Encoding, Cookie;param=foo Key: Accept-Encoding, Cookie; param=foo
to indicate that the secondary cache key depends upon the Accept- to indicate that the secondary cache key depends upon the Accept-
Encoding header field and the "foo" Cookie. Encoding header field and the "foo" Cookie.
One important difference between Vary and Key is how they are One important difference between Vary and Key is how they are
applied. Vary is specified to be specific to the response it occurs applied. Vary is specified to be specific to the response it occurs
within, whereas Key is specific to the resource (as identified by the within, whereas Key is specific to the resource (as identified by the
request URL) it is associated with. The most recent key you receive request URL) it is associated with. The most recent key you receive
for a given resource is applicable to all responses from that for a given resource is applicable to all responses from that
resource. resource.
skipping to change at page 6, line 40 skipping to change at page 6, line 45
the appropriate response, to determine if it can be selected. the appropriate response, to determine if it can be selected.
To generate a secondary cache key for a given request (including that To generate a secondary cache key for a given request (including that
which is stored with a response) using Key, the following steps are which is stored with a response) using Key, the following steps are
taken: taken:
1) If the Key header field is not present on the most recent 1) If the Key header field is not present on the most recent
cacheable (as per [RFC7234], Section 3)) response seen for the cacheable (as per [RFC7234], Section 3)) response seen for the
resource, abort this algorithm (i.e., fall back to using Vary to resource, abort this algorithm (i.e., fall back to using Vary to
determine the secondary cache key). determine the secondary cache key).
2) Let "key_value" be the most recently seen Key header field value 2) Let "key_value" be the result of Creating a Header Field Value
for the resource, as the result of Creating a Header Field Value (Section 2.2.1) with "key" as the "target_field_name" and the
(Section 2.2.1). most recently seen response header list for the resource as
"header_list".
3) Let "secondary_key" be an empty string. 3) Let "secondary_key" be an empty string.
4) Create "key_list" by splitting "key_value" on "," characters.
4) Create "key_list" by splitting "key_value" on "," characters,
excepting "," characters within quoted strings, as per [RFC7230]
Section 3.2.6..
5) For "key_item" in "key_list": 5) For "key_item" in "key_list":
1) Remove any leading and trailing WSP from "key_item". 1) Remove any leading and trailing WSP from "key_item".
2) If "key_item" does not contain a ";" character, fail 2) If "key_item" does not contain a ";" character, fail
parameter processing (Section 2.2.2) and skip to the next parameter processing (Section 2.2.2) and skip to the next
"key_item". "key_item".
3) Let "field_name" be the string before the first ";" character 3) Let "field_name" be the string before the first ";" character
in "key_item". in "key_item", removing any WSP between them.
4) Let "field_value" be the result of Creating a Header Field 4) Let "field_value" be the result of Creating a Header Field
Value (Section 2.2.1) with "field_name" as the Value (Section 2.2.1) with "field_name" as the
"target_field_name" and the request header list as "target_field_name" and the request header list as
"header_list". "header_list".
5) Let "parameters" be the string after the first ";" character 5) Let "parameters" be the string after the first ";" character
in "key_item". in "key_item", removing any WSP between them.
6) Create "param_list" by splitting "parameters" on ";" 6) Create "param_list" by splitting "parameters" on ";"
characters, excepting ";" characters within quoted strings, characters, excepting ";" characters within quoted strings,
as per [RFC7230] Section 3.2.6. as per [RFC7230] Section 3.2.6.
7) For "parameter" in "param_list": 7) For "parameter" in "param_list":
1) If "parameter" does not contain a "=", fail parameter 1) If "parameter" does not contain a "=", fail parameter
processing (Section 2.2.2) and skip to the next processing (Section 2.2.2) and skip to the next
"key_item". "key_item".
2) Let "param_name" be the string before the first "=" 2) Remove any WSP at the beginning and/or end of
"parameter".
3) Let "param_name" be the string before the first "="
character in "parameter", case-normalized to lowercase. character in "parameter", case-normalized to lowercase.
3) If "param_name" does not identify a Key parameter 4) If "param_name" does not identify a Key parameter
processing algorithm that is implemented, fail parameter processing algorithm that is implemented, fail parameter
processing (Section 2.2.2) and skip to the next processing (Section 2.2.2) and skip to the next
"key_item". "key_item".
4) Let "param_value" be the string after the first "=" 5) Let "param_value" be the string after the first "="
character in "parameter". character in "parameter".
5) If the first and last characters of "param_value" are 6) If the first and last characters of "param_value" are
both DQUOTE: both DQUOTE:
1) Remove the first and last characters of 1) Remove the first and last characters of
"param_value". "param_value".
2) Replace quoted-pairs within "param_value" with the 2) Replace quoted-pairs within "param_value" with the
octet following the backslash, as per [RFC7230] octet following the backslash, as per [RFC7230]
Section 3.2.6. Section 3.2.6.
6) If "param_value" does not conform to the syntax defined 7) If "param_value" does not conform to the syntax defined
for it by the parameter definition, fail parameter for it by the parameter definition, fail parameter
processing Section 2.2.2 and skip to the next "key_item". processing Section 2.2.2 and skip to the next "key_item".
7) Run the identified processing algorithm on "field_value" 8) Run the identified processing algorithm on "field_value"
with the "param_value", and append the result to with the "param_value", and append the result to
"secondary_key". If parameter processing fails "secondary_key". If parameter processing fails
Section 2.2.2, skip to the next "key_item". Section 2.2.2, skip to the next "key_item".
8) Append a separator character (e.g., NULL) to 9) Append a separator character (e.g., NULL) to
"secondary_key". "secondary_key".
6) Return "secondary_key". 6) Return "secondary_key".
Note that this specification does not require that exact algorithm to Note that this specification does not require that exact algorithm to
be implemented. However, implementations' observable behavior MUST be implemented. However, implementations' observable behavior MUST
be identical to running it. This includes parameter processing be identical to running it. This includes parameter processing
algorithms; implementations MAY use different internal artefacts for algorithms; implementations MAY use different internal artefacts for
secondary cache keys, as long as the results are the same. secondary cache keys, as long as the results are the same.
Likewise, while the secondary cache key associated with both stored Likewise, while the secondary cache key associated with both stored
skipping to change at page 9, line 35 skipping to change at page 10, line 4
characters. characters.
4) Remove all WSP characters from "header_value". 4) Remove all WSP characters from "header_value".
5) If "header_value" does not match the div ABNF rule, fail 5) If "header_value" does not match the div ABNF rule, fail
parameter processing (Section 2.2.2). parameter processing (Section 2.2.2).
6) Return the quotient of "header_value" / "parameter_value" 6) Return the quotient of "header_value" / "parameter_value"
(omitting the modulus). (omitting the modulus).
For example, the Key: For example, the Key:
Key: Bar;div=5 Key: Bar;div=5
indicates that the "Bar" header's field value should be partitioned indicates that the "Bar" header's field value should be partitioned
into groups of 5. Thus, the following field values would be into groups of 5. Thus, the following field values would be
considered the same (because, divided by 5, they all result in 1): considered the same (because, divided by 5, they all result in 0):
Bar: 1 Bar: 1
Bar: 3 , 42 Bar: 3 , 42
Bar: 4, 1 Bar: 4, 1
whereas these would be considered to be in a different group whereas these would be considered to be in a different group
(because, divided by 5, they all result in 2); (because, divided by 5, they all result in 2);
Bar: 12 Bar: 12
Bar: 10 Bar: 10
Bar: 14, 1 Bar: 14, 1
2.3.2. partition 2.3.2. partition
The "partition" parameter normalizes positive numeric header values The "partition" parameter normalizes positive numeric header values
into pre-defined segments. into pre-defined segments.
Its value's syntax is: Its value's syntax is:
skipping to change at page 15, line 45 skipping to change at page 15, line 45
responses for a given resource in caches; this, in turn, might be responses for a given resource in caches; this, in turn, might be
used to create an attack upon the cache itself. Good cache used to create an attack upon the cache itself. Good cache
replacement algorithms and denial of service monitoring in cache replacement algorithms and denial of service monitoring in cache
implementations are reasonable mitigations against this risk. implementations are reasonable mitigations against this risk.
5. References 5. References
5.1. Normative References 5.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ Requirement Levels", BCP 14, RFC 2119,
RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ Specifications: ABNF", STD 68, RFC 5234,
RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<http://www.rfc-editor.org/info/rfc5234>. <http://www.rfc-editor.org/info/rfc5234>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing", RFC Protocol (HTTP/1.1): Message Syntax and Routing",
7230, DOI 10.17487/RFC7230, June 2014, RFC 7230, DOI 10.17487/RFC7230, June 2014,
<http://www.rfc-editor.org/info/rfc7230>. <http://www.rfc-editor.org/info/rfc7230>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
10.17487/RFC7231, June 2014, DOI 10.17487/RFC7231, June 2014,
<http://www.rfc-editor.org/info/rfc7231>. <http://www.rfc-editor.org/info/rfc7231>.
[RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
RFC 7234, DOI 10.17487/RFC7234, June 2014, RFC 7234, DOI 10.17487/RFC7234, June 2014,
<http://www.rfc-editor.org/info/rfc7234>. <http://www.rfc-editor.org/info/rfc7234>.
5.2. Informative References 5.2. Informative References
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
DOI 10.17487/RFC5226, May 2008,
<http://www.rfc-editor.org/info/rfc5226>.
[RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
DOI 10.17487/RFC6265, April 2011, DOI 10.17487/RFC6265, April 2011,
<http://www.rfc-editor.org/info/rfc6265>. <http://www.rfc-editor.org/info/rfc6265>.
Appendix A. Acknowledgements Appendix A. Acknowledgements
Thanks to Ilya Grigorik, Amos Jeffries and Yoav Weiss for their Thanks to Ilya Grigorik, Amos Jeffries and Yoav Weiss for their
feedback. feedback.
Authors' Addresses Appendix B. Changes
B.1. Since -00
o Issue 108 (field-name cardinality) closed with no action.
o Issue 104 (Support "Or" operator) closed with no action.
o Issue 107 (Whitespace requirement) addressed by allowing
whitespace around parameters.
o Issue 106 (Policy for Key parameter registry) closed with no
action.
Authors' Addresses
Roy T. Fielding Roy T. Fielding
Adobe Systems Incorporated Adobe Systems Incorporated
Email: fielding@gbiv.com Email: fielding@gbiv.com
URI: http://roy.gbiv.com/ URI: http://roy.gbiv.com/
Mark Nottingham Mark Nottingham
Email: mnot@mnot.net Email: mnot@mnot.net
URI: http://www.mnot.net/ URI: https://www.mnot.net/
 End of changes. 38 change blocks. 
41 lines changed or deleted 68 lines changed or added

This html diff was produced by rfcdiff 1.42. The latest version is available from http://tools.ietf.org/tools/rfcdiff/