draft-ietf-httpbis-cache-header-07.txt   draft-ietf-httpbis-cache-header-08.txt 
HTTP M. Nottingham HTTP M. Nottingham
Internet-Draft Fastly Internet-Draft Fastly
Intended status: Standards Track 26 January 2021 Intended status: Standards Track 20 April 2021
Expires: 30 July 2021 Expires: 22 October 2021
The Cache-Status HTTP Response Header Field The Cache-Status HTTP Response Header Field
draft-ietf-httpbis-cache-header-07 draft-ietf-httpbis-cache-header-08
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 30 July 2021. This Internet-Draft will expire on 22 October 2021.
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 27 skipping to change at page 2, line 27
provided without warranty as described in the Simplified BSD License. provided without warranty as described in the Simplified BSD License.
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 . . . . . . . . . . . . . . . . . . . . 6 2.4. The ttl parameter . . . . . . . . . . . . . . . . . . . . 5
2.5. The stored parameter . . . . . . . . . . . . . . . . . . 6 2.5. The stored parameter . . . . . . . . . . . . . . . . . . 5
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 . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4. Defining New Proxy-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 . . . . . . . . . . . . . . . . . . . . . . . . . 9 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8
7.1. Normative References . . . . . . . . . . . . . . . . . . 9 7.1. Normative References . . . . . . . . . . . . . . . . . . 8
7.2. Informative References . . . . . . . . . . . . . . . . . 9 7.2. Informative References . . . . . . . . . . . . . . . . . 9
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9
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.
skipping to change at page 3, line 13 skipping to change at page 3, line 13
Status" for this purpose. Status" for this purpose.
1.1. Notational Conventions 1.1. 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", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
This document uses ABNF as defined in [RFC5234], along with the "%s" This document uses ABNF as defined in [RFC5234].
extension for case sensitivity defined in [RFC7405].
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 [I-D.ietf-httpbis-header-structure], 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
skipping to change at page 7, line 35 skipping to change at page 7, line 19
Cache-Status: ExampleCache; fwd=stale; fwd-status=304 Cache-Status: ExampleCache; fwd=stale; fwd-status=304
A miss that was collapsed with another request: A miss that was collapsed with another request:
Cache-Status: ExampleCache; fwd=uri-miss; collapsed Cache-Status: ExampleCache; fwd=uri-miss; collapsed
A miss that the cache attempted to collapse, but couldn't: A miss that the cache attempted to collapse, but couldn't:
Cache-Status: ExampleCache; fwd=uri-miss; collapsed=?0 Cache-Status: ExampleCache; fwd=uri-miss; collapsed=?0
Going through two layers of caching, both of which were hits, and the Going through two separate layers of caching, where the cache closest
second collapsed with other requests: to the origin responded to an earlier request with a stored response,
and a second cache stored that response and later reused it to
satisfy the current request:
Cache-Status: OriginCache; hit; ttl=1100; collapsed, Cache-Status: OriginCache; hit; ttl=1100,
"CDN Company Here"; hit; ttl=545 "CDN Company Here"; hit; ttl=545
4. Defining New Proxy-Status Parameters 4. Defining New Cache-Status Parameters
New Cache-Status Parameters can be defined by registering them in the New Cache-Status Parameters can be defined by registering them in the
HTTP Cache-Status Parameters registry. HTTP Cache-Status Parameters registry.
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:
skipping to change at page 9, line 17 skipping to change at page 8, line 51
only send sensitive information (e.g., the key parameter) when the only send sensitive information (e.g., the key parameter) when the
client is authorized. client is authorized.
7. References 7. References
7.1. Normative References 7.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, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/rfc/rfc2119>.
[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/info/rfc8126>. <https://www.rfc-editor.org/rfc/rfc8126>.
[I-D.ietf-httpbis-header-structure] [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for
Nottingham, M. and P. Kamp, "Structured Field Values for HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,
HTTP", Work in Progress, Internet-Draft, draft-ietf- <https://www.rfc-editor.org/rfc/rfc8941>.
httpbis-header-structure-19, 3 June 2020,
<http://www.ietf.org/internet-drafts/draft-ietf-httpbis-
header-structure-19.txt>.
[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/info/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/info/rfc5234>. <https://www.rfc-editor.org/rfc/rfc5234>.
[RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF",
RFC 7405, DOI 10.17487/RFC7405, December 2014,
<https://www.rfc-editor.org/info/rfc7405>.
7.2. Informative References 7.2. Informative References
[ENTANGLE] Kettle, J., "Web Cache Entanglement: Novel Pathways to [ENTANGLE] Kettle, J., "Web Cache Entanglement: Novel Pathways to
Poisoning", n.d., <https://i.blackhat.com/USA- Poisoning", 2020, <https://i.blackhat.com/USA-
20/Wednesday/us-20-Kettle-Web-Cache-Entanglement-Novel- 20/Wednesday/us-20-Kettle-Web-Cache-Entanglement-Novel-
Pathways-To-Poisoning-wp.pdf>. Pathways-To-Poisoning-wp.pdf>.
Author's Address Author's Address
Mark Nottingham Mark Nottingham
Fastly Fastly
Prahran VIC Prahran VIC
Australia Australia
Email: mnot@mnot.net Email: mnot@mnot.net
URI: https://www.mnot.net/ URI: https://www.mnot.net/
 End of changes. 18 change blocks. 
32 lines changed or deleted 27 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/