< draft-ietf-httpbis-cache-header-08.txt		draft-ietf-httpbis-cache-header-09.txt >
	HTTP M. Nottingham		HTTP M. Nottingham
	Internet-Draft Fastly		Internet-Draft Fastly
	Intended status: Standards Track 20 April 2021		Intended status: Standards Track 8 July 2021
	Expires: 22 October 2021		Expires: 9 January 2022
	The Cache-Status HTTP Response Header Field		The Cache-Status HTTP Response Header Field
	draft-ietf-httpbis-cache-header-08		draft-ietf-httpbis-cache-header-09
	Abstract		Abstract
	To aid debugging, HTTP caches often append header fields to a		To aid debugging, HTTP caches often append header fields to a
	response explaining how they handled the request. This specification		response explaining how they handled the request. This specification
	codifies that practice and updates it to align with HTTP's current		codifies that practice and updates it to align with HTTP's current
	caching model.		caching model.
	Note to Readers		Note to Readers
	skipping to change at page 1, line 48 ¶		skipping to change at page 1, line 48 ¶
	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 https://datatracker.ietf.org/drafts/current/.		Drafts is at https://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 22 October 2021.		This Internet-Draft will expire on 9 January 2022.
	Copyright Notice		Copyright Notice
	Copyright (c) 2021 IETF Trust and the persons identified as the		Copyright (c) 2021 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 (https://trustee.ietf.org/		Provisions Relating to IETF Documents (https://trustee.ietf.org/
	license-info) in effect on the date of publication of this document.		license-info) in effect on the date of publication of this document.
	Please review these documents carefully, as they describe your rights		Please review these documents carefully, as they describe your rights
	skipping to change at page 2, line 28 ¶		skipping to change at page 2, line 28 ¶
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
	1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3		1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
	2. The Cache-Status HTTP Response Header Field . . . . . . . . . 3		2. The Cache-Status HTTP Response Header Field . . . . . . . . . 3
	2.1. The hit parameter . . . . . . . . . . . . . . . . . . . . 4		2.1. The hit parameter . . . . . . . . . . . . . . . . . . . . 4
	2.2. The fwd parameter . . . . . . . . . . . . . . . . . . . . 4		2.2. The fwd parameter . . . . . . . . . . . . . . . . . . . . 4
	2.3. The fwd-status parameter . . . . . . . . . . . . . . . . 5		2.3. The fwd-status parameter . . . . . . . . . . . . . . . . 5
	2.4. The ttl parameter . . . . . . . . . . . . . . . . . . . . 5		2.4. The ttl parameter . . . . . . . . . . . . . . . . . . . . 5
	2.5. The stored parameter . . . . . . . . . . . . . . . . . . 5		2.5. The stored parameter . . . . . . . . . . . . . . . . . . 6
	2.6. The collapsed parameter . . . . . . . . . . . . . . . . . 6		2.6. The collapsed parameter . . . . . . . . . . . . . . . . . 6
	2.7. The key parameter . . . . . . . . . . . . . . . . . . . . 6		2.7. The key parameter . . . . . . . . . . . . . . . . . . . . 6
	2.8. The detail parameter . . . . . . . . . . . . . . . . . . 6		2.8. The detail parameter . . . . . . . . . . . . . . . . . . 6
	3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6		3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6
	4. Defining New Cache-Status Parameters . . . . . . . . . . . . 7		4. Defining New Cache-Status Parameters . . . . . . . . . . . . 7
	5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8		5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
	6. Security Considerations . . . . . . . . . . . . . . . . . . . 8		6. Security Considerations . . . . . . . . . . . . . . . . . . . 8
	7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8		7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
	7.1. Normative References . . . . . . . . . . . . . . . . . . 8		7.1. Normative References . . . . . . . . . . . . . . . . . . 9
	7.2. Informative References . . . . . . . . . . . . . . . . . 9		7.2. Informative References . . . . . . . . . . . . . . . . . 10
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9		Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10
	1. Introduction		1. Introduction
	To aid debugging, HTTP caches often append header fields to a		To aid debugging, HTTP caches often append header fields to a
	response explaining how they handled the request. Unfortunately, the		response explaining how they handled the request. Unfortunately, the
	semantics of these headers are often unclear, and both the semantics		semantics of these headers are often unclear, and both the semantics
	and syntax used vary between implementations.		and syntax used vary between implementations.
	This specification defines a new HTTP response header field, "Cache-		This specification defines a new HTTP response header field, "Cache-
	Status" for this purpose.		Status" for this purpose.
	skipping to change at page 3, line 21 ¶		skipping to change at page 3, line 21 ¶
	capitals, as shown here.		capitals, as shown here.
	This document uses ABNF as defined in [RFC5234].		This document uses ABNF as defined in [RFC5234].
	2. The Cache-Status HTTP Response Header Field		2. The Cache-Status HTTP Response Header Field
	The Cache-Status HTTP response header field indicates caches'		The Cache-Status HTTP response header field indicates caches'
	handling of the request corresponding to the response it occurs		handling of the request corresponding to the response it occurs
	within.		within.
	Its value is a List [RFC8941], Section 3.1:		Its value is a List ([RFC8941], Section 3.1):
	Cache-Status = sf-list		Cache-Status = sf-list
	Each member of the list represents a cache that has handled the		Each member of the list represents a cache that has handled the
	request. The first member of the list represents the cache closest		request. The first member of the list represents the cache closest
	to the origin server, and the last member of the list represents the		to the origin server, and the last member of the list represents the
	cache closest to the user (possibly including the user agent's cache		cache closest to the user (possibly including the user agent's cache
	itself, if it appends a value).		itself, if it appends a value).
	The Cache-Status header field is only applicable to responses that		The Cache-Status header field is only applicable to responses that
	are generated by an origin server. An intermediary SHOULD NOT append		have been generated by an origin server. An intermediary SHOULD NOT
	a Cache-Status member to responses that it generates, even if that		append a Cache-Status member to responses that it generates, even if
	intermediary contains a cache, except when the generated response is		that intermediary contains a cache, except when the generated
	based upon a stored response (e.g., a 304 Not Modified or 206 Partial		response is based upon a stored response (e.g., a 304 Not Modified or
	Content).		206 Partial Content).
	Caches determine when it is appropriate to add the Cache-Status		Caches determine when it is appropriate to add the Cache-Status
	header field to a response. Some might add it to all responses,		header field to a response. Some might add it to all responses,
	whereas others might only do so when specifically configured to, or		whereas others might only do so when specifically configured to, or
	when the request contains a header field that activates a debugging		when the request contains a header field that activates a debugging
	mode.		mode.
	When adding a value to the Cache-Status header field, caches SHOULD		When adding a value to the Cache-Status header field, caches SHOULD
	preserve the existing field value, to allow debugging of the entire		preserve the existing field value, to allow debugging of the entire
	chain of caches handling the request.		chain of caches handling the request.
	skipping to change at page 5, line 28 ¶		skipping to change at page 5, line 28 ¶
	directives) did not allow its use		directives) did not allow its use
	* stale - The cache was able to select a response for the request,		* stale - The cache was able to select a response for the request,
	but it was stale		but it was stale
	* partial - The cache was able to select a partial response for the		* partial - The cache was able to select a partial response for the
	request, but it did not contain all of the requested ranges (or		request, but it did not contain all of the requested ranges (or
	the request was for the complete response)		the request was for the complete response)
	The most specific reason that the cache is aware of SHOULD be used.		The most specific reason that the cache is aware of SHOULD be used.
			See also [I-D.ietf-httpbis-semantics], Section 4.
	2.3. The fwd-status parameter		2.3. The fwd-status parameter
	"fwd-status" indicates what status code the next hop server returned		"fwd-status" indicates what status code (see
	in response to the request. Only meaningful when "fwd" is present;		[I-D.ietf-httpbis-semantics], Section 15) the next hop server
	if "fwd-status" is not present but "fwd" is, it defaults to the		returned in response to the request. Only meaningful when "fwd" is
	status code sent in the response.		present; if "fwd-status" is not present but "fwd" is, it defaults to
			the status code sent in the response.
	This parameter is useful to distinguish cases when the next hop		This parameter is useful to distinguish cases when the next hop
	server sends a 304 Not Modified response to a conditional request, or		server sends a 304 Not Modified response to a conditional request, or
	a 206 Partial Response because of a range request.		a 206 Partial Response because of a range request.
	2.4. The ttl parameter		2.4. The ttl parameter
	"ttl" indicates the response's remaining freshness lifetime as		"ttl" indicates the response's remaining freshness lifetime (see
	calculated by the cache, as an integer number of seconds, measured		[I-D.ietf-httpbis-cache], Section 4.2.1) as calculated by the cache,
	when the response header section is sent by the cache. This includes		as an integer number of seconds, measured when the response header
	freshness assigned by the cache; e.g., through heuristics, local		section is sent by the cache. This includes freshness assigned by
	configuration, or other factors. May be negative, to indicate		the cache; e.g., through heuristics (see [I-D.ietf-httpbis-cache],
	staleness.		Section 4.2.2), local configuration, or other factors. May be
			negative, to indicate staleness.
	2.5. The stored parameter		2.5. The stored parameter
	"stored" indicates whether the cache stored the response; a true		"stored" indicates whether the cache stored the response (see
	value indicates that it did. Only meaningful when fwd is present.		[I-D.ietf-httpbis-cache], Section 3); a true value indicates that it
			did. Only meaningful when fwd is present.
	2.6. The collapsed parameter		2.6. The collapsed parameter
	"collapsed" indicates whether this request was collapsed together		"collapsed" indicates whether this request was collapsed together
	with one or more other forward requests; if true, the response was		with one or more other forward requests (see
			[I-D.ietf-httpbis-cache], Section 4); if true, the response was
	successfully reused; if not, a new request had to be made. If not		successfully reused; if not, a new request had to be made. If not
	present, the request was not collapsed with others. Only meaningful		present, the request was not collapsed with others. Only meaningful
	when fwd is present.		when fwd is present.
	2.7. The key parameter		2.7. The key parameter
	"key" conveys a representation of the cache key used for the		"key" conveys a representation of the cache key (see
	response. Note that this may be implementation-specific.		[I-D.ietf-httpbis-cache], Section 2) used for the response. Note
			that this may be implementation-specific.
	2.8. The detail parameter		2.8. The detail parameter
	"detail" allows implementations to convey additional information not		"detail" allows implementations to convey additional information not
	captured in other parameters; for example, implementation-specific		captured in other parameters; for example, implementation-specific
	states, or other caching-related metrics.		states, or other caching-related metrics.
	For example:		For example:
	Cache-Status: ExampleCache; hit; detail=MEMORY		Cache-Status: ExampleCache; hit; detail=MEMORY
	skipping to change at page 7, line 42 ¶		skipping to change at page 8, line 4 ¶
	Registration requests are reviewed and approved by a Designated		Registration requests are reviewed and approved by a Designated
	Expert, as per [RFC8126], Section 4.5. A specification document is		Expert, as per [RFC8126], Section 4.5. A specification document is
	appreciated, but not required.		appreciated, but not required.
	The Expert(s) should consider the following factors when evaluating		The Expert(s) should consider the following factors when evaluating
	requests:		requests:
	* Community feedback		* Community feedback
	* If the value is sufficiently well-defined		* If the value is sufficiently well-defined
	* Generic parameters are preferred over vendor-specific,		* Generic parameters are preferred over vendor-specific,
	application-specific, or deployment-specific values. If a generic		application-specific, or deployment-specific values. If a generic
	value cannot be agreed upon in the community, the parameter's name		value cannot be agreed upon in the community, the parameter's name
	should be correspondingly specific (e.g., with a prefix that		should be correspondingly specific (e.g., with a prefix that
	identifies the vendor, application or deployment).		identifies the vendor, application or deployment).
	Registration requests should use the following template:		Registration requests should use the following template:
	* Name: [a name for the Cache-Status Parameter that matches key]		* Name: [a name for the Cache-Status Parameter that matches key]
	* Description: [a description of the parameter semantics and value]		* Description: [a description of the parameter semantics and value]
	* Reference: [to a specification defining this parameter]		* Reference: [to a specification defining this parameter]
	See the registry at https://iana.org/assignments/http-cache-status		See the registry at https://iana.org/assignments/http-cache-status
	(https://iana.org/assignments/http-cache-status) for details on where		(https://iana.org/assignments/http-cache-status) for details on where
	to send registration requests.		to send registration requests.
	5. IANA Considerations		5. IANA Considerations
	Upon publication, please create the HTTP Cache-Status Parameters		Upon publication, please create the HTTP Cache-Status Parameters
	registry at https://iana.org/assignments/http-cache-status		registry at https://iana.org/assignments/http-cache-status
	(https://iana.org/assignments/http-cache-status) and populate it with		(https://iana.org/assignments/http-cache-status) and populate it with
	the types defined in Section 2; see Section 4 for its associated		the types defined in Section 2; see Section 4 for its associated
	procedures.		procedures.
			Also, please create the following entry in the Hypertext Transfer
			Protocol (HTTP) Field Name Registry defined in
			[I-D.ietf-httpbis-semantics], Section 18.4:
			* Field name: Cache-Status
			* Status: permanent
			* Specification document: [this document]
			* Comments:
	6. Security Considerations		6. Security Considerations
	Attackers can use the information in Cache-Status to probe the		Attackers can use the information in Cache-Status to probe the
	behaviour of the cache (and other components), and infer the activity		behaviour of the cache (and other components), and infer the activity
	of those using the cache. The Cache-Status header field may not		of those using the cache. The Cache-Status header field may not
	create these risks on its own, but can assist attackers in exploiting		create these risks on its own, but can assist attackers in exploiting
	them.		them.
	For example, knowing if a cache has stored a response can help an		For example, knowing if a cache has stored a response can help an
	attacker execute a timing attack on sensitive data. Exposing the		attacker execute a timing attack on sensitive data. Exposing the
	skipping to change at page 9, line 14 ¶		skipping to change at page 9, line 39 ¶
	[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for		[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
	Writing an IANA Considerations Section in RFCs", BCP 26,		Writing an IANA Considerations Section in RFCs", BCP 26,
	RFC 8126, DOI 10.17487/RFC8126, June 2017,		RFC 8126, DOI 10.17487/RFC8126, June 2017,
	<https://www.rfc-editor.org/rfc/rfc8126>.		<https://www.rfc-editor.org/rfc/rfc8126>.
	[RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for		[RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for
	HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,		HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,
	<https://www.rfc-editor.org/rfc/rfc8941>.		<https://www.rfc-editor.org/rfc/rfc8941>.
			[I-D.ietf-httpbis-semantics]
			Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP
			Semantics", Work in Progress, Internet-Draft, draft-ietf-
			httpbis-semantics-16, 27 May 2021,
			<https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
			semantics-16>.
			[I-D.ietf-httpbis-cache]
			Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP
			Caching", Work in Progress, Internet-Draft, draft-ietf-
			httpbis-cache-16, 27 May 2021,
			<https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
			cache-16>.
	[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC		[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
	2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,		2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
	May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.		May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
	[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,		Specifications: ABNF", STD 68, RFC 5234,
	DOI 10.17487/RFC5234, January 2008,		DOI 10.17487/RFC5234, January 2008,
	<https://www.rfc-editor.org/rfc/rfc5234>.		<https://www.rfc-editor.org/rfc/rfc5234>.
	7.2. Informative References		7.2. Informative References
End of changes. 17 change blocks.
	31 lines changed or deleted		63 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/