Internet DRAFT - draft-thomson-http-if-digest
draft-thomson-http-if-digest
HTTPBIS M. Thomson
Internet-Draft Mozilla
Intended status: Informational 9 March 2020
Expires: 10 September 2020
Conditional HTTP Requests Using Digests
draft-thomson-http-if-digest-00
Abstract
Header fields are defined for making HTTP requests that are
conditional on the content of the selected representation of a
resource.
Note to Readers
Discussion of this document 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/
(https://lists.w3.org/Archives/Public/ietf-http-wg/).
Source for this draft and an issue tracker can be found at
https://github.com/martinthomson/if-digest
(https://github.com/martinthomson/if-digest).
Status of 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 https://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 10 September 2020.
Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved.
Thomson Expires 10 September 2020 [Page 1]
Internet-Draft Digest Conditionals March 2020
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://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
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 2
3. If-Digest Header Field . . . . . . . . . . . . . . . . . . . 3
4. If-None-Digest Header field . . . . . . . . . . . . . . . . . 3
5. Security Considerations . . . . . . . . . . . . . . . . . . . 4
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 4
7.1. Normative References . . . . . . . . . . . . . . . . . . 4
7.2. Informative References . . . . . . . . . . . . . . . . . 5
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 5
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5
1. Introduction
Conditional HTTP requests [HTTP] allow a client to specify
preconditions on processing of a request. Conditional requests can
be used to avoid making requests that could be unnecessary based on
information available to the server, but not the client.
This document defines new If-Digest and If-None-Digest preconditions
that are based on the digest of selected representations, as
described in [DIGEST]. These preconditions create a concise and
strong binding to the content of a representation as they use a
cryptographic hash function.
2. Conventions and Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
Thomson Expires 10 September 2020 [Page 2]
Internet-Draft Digest Conditionals March 2020
3. If-Digest Header Field
Conditional requests can be used to prevent actions that involve
representations that are not expected by a client. For instance, a
PATCH [PATCH] request might include the conditional If-Match header
field to ensure that the requested changes are only applied if the
selected representation is what the client expects, preventing
mutation of a resource that might be in an state that is incompatible
with the desire change.
The If-Digest conditional header field allows a client to indicate
the digest of representations that the request can be applied to.
The precondition fails if the selected representation is not equal to
a value specified in the If-Digest header field.
The If-Digest conditional might also be used when a client requests a
representation using the GET method where the digest of the
representation need to match a known value. For instance, if a
resource is referenced using Subresource Integrity [SRI] or certain
Content Security Policy [CSP] rules, a response containing a
different representation would only be discarded by the client.
The format of the If-Digest header is a structured header [SH]
dictionary with keys being the hash algorithm identifier (from
[DIGEST]). Values are byte sequences that contain the value of the
digest. For example (with line wrapping):
If-Digest:
sha-256=:ypeBEsobvcr6wjGzmiPcTaeG7/gUfE5yuYB3ha/uSLs=:
Multiple digests MAY be included with If-Digest; the precondition
succeeds if the digest of the selected representation matches any of
the included values.
4. If-None-Digest Header field
A conditional GET request can be used to avoid transferring a
representation when that representation is already known to the
client. For instance, the If-None-Match header field can carry an
ETag that corresponds to content known to a client.
The If-None-Digest conditional header field indicates the digest of
representations that the server is requested to not apply the method
to. The precondition fails if the digest of the selected
representation is equal to any of the digests indicated in the If-
None-Digest header field.
Thomson Expires 10 September 2020 [Page 3]
Internet-Draft Digest Conditionals March 2020
The If-None-Digest condition might be used similarly to If-None-Match
in fetching content using a GET request. A client includes the
digest of a representation that is already available to it - perhaps
in a cache - the server can respond with a 304 (Not Modified) status
code if the digest of the selected representation is identical to a
provided value.
The format of the If-None-Digest header is a structured header [SH]
dictionary with keys being the hash algorithm identifier (from
[DIGEST]). Values are byte sequences that contain the value of the
digest. For example (with line wrapping):
If-None-Digest:
id-sha-256=:v106/7c+/S7Gw2rTES3ZM+/tY8Thy//PqI4nWcFE8tg=:
Multiple digests MAY be included with If-None-Digest; the
precondition succeeds if the digest of the selected representation
matches none of the included values.
5. Security Considerations
The strength of the digest algorithm determines how reliable these
conditions are. The use of digests for conditional requests depends
on the digest algorithm providing strong collision and second pre-
image resistance. These are not properties guaranteed by the MD5,
CRC32C, SHA, and ADLER32 digest algorithms. If-Digest and If-None-
Digest MUST NOT be used with MD5, CRC32C, SHA, or ADLER32 as there
can be no reasonable expectation that matching the value of a digest
would correspond to matching the content of a representation.
Other digest algorithms could be found to be similarly weak over
time. This specification allows for multiple digests to be indicated
using different digest algorithms. A client that is uncertain of
server support for newer digest algorithms can include digests that
use both old and new functions. A server that is aware of weaknesses
in a given digest algorithm can ignore values based on that algorithm
when the client provides values that use digest algorithms that are
known to be strong. A server MAY reject a request with a 4xx status
code if only digest algorithms that are known to be weak are used in
preconditions.
6. IANA Considerations
TODO: Register some header fields!
7. References
7.1. Normative References
Thomson Expires 10 September 2020 [Page 4]
Internet-Draft Digest Conditionals March 2020
[DIGEST] Polli, R. and L. Pardue, "Digest Headers", Work in
Progress, Internet-Draft, draft-ietf-httpbis-digest-
headers-01, 3 November 2019, <http://www.ietf.org/
internet-drafts/draft-ietf-httpbis-digest-headers-01.txt>.
[HTTP] Fielding, R., Nottingham, M., and J. Reschke, "HTTP
Semantics", Work in Progress, Internet-Draft, draft-ietf-
httpbis-semantics-07, 7 March 2020, <http://www.ietf.org/
internet-drafts/draft-ietf-httpbis-semantics-07.txt>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[SH] Nottingham, M. and P. Kamp, "Structured Headers for HTTP",
Work in Progress, Internet-Draft, draft-ietf-httpbis-
header-structure-14, 28 January 2020,
<http://www.ietf.org/internet-drafts/draft-ietf-httpbis-
header-structure-14.txt>.
7.2. Informative References
[CSP] West, M., "Content Security Policy Level 3", W3C ED, 28
February 2019, <https://w3c.github.io/webappsec-csp/>.
[PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, DOI 10.17487/RFC5789, March 2010,
<https://www.rfc-editor.org/info/rfc5789>.
[SRI] Akhawe, D., Braun, F., Marier, F., and J. Weinberger,
"Subresource Integrity", W3C ED, 4 January 2020,
<https://w3c.github.io/webappsec-subresource-integrity/>.
Acknowledgments
TODO acknowledge someone.
Author's Address
Martin Thomson
Mozilla
Email: mt@lowentropy.net
Thomson Expires 10 September 2020 [Page 5]
