Conditional HTTP Requests Using Digests
Mozilla
mt@lowentropy.net
ART
HTTPBIS
Internet-Draft
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/.
Source for this draft and an issue tracker can be found at
https://github.com/martinthomson/if-digest.
Introduction
Conditional HTTP requests 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
. These preconditions create a
concise and strong binding to the content of a representation as they use a
cryptographic hash function.
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
when, and only when, they appear in all capitals, as shown here.
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
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 or certain Content Security Policy 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
dictionary with keys being the hash
algorithm identifier (from ). Values are byte sequences that contain
the value of the digest. For example (with line wrapping):
Multiple digests MAY be included with If-Digest; the precondition succeeds if
the digest of the selected representation matches any of the included values.
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.
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
dictionary with keys being the hash
algorithm identifier (from ). Values are byte sequences that contain
the value of the digest. For example (with line wrapping):
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.
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.
IANA Considerations
TODO: Register some header fields!
References
Normative References
HTTP Semantics
The Hypertext Transfer Protocol (HTTP) is a stateless application- level protocol for distributed, collaborative, hypertext information systems. This document defines the semantics of HTTP: its architecture, terminology, the "http" and "https" Uniform Resource Identifier (URI) schemes, core request methods, request header fields, response status codes, response header fields, and content negotiation. This document obsoletes RFC 2818, RFC 7231, RFC 7232, RFC 7233, RFC 7235, RFC 7538, RFC 7615, and portions of RFC 7230.
Digest Headers
This document defines the Digest and Want-Digest header fields for HTTP, thus allowing client and server to negotiate an integrity checksum of the exchanged resource representation data. This document obsoletes RFC 3230. It replaces the term "instance" with "representation", which makes it consistent with the HTTP Semantic and Context defined in RFC 7231.
Key words for use in RFCs to Indicate Requirement Levels
In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.
Structured Headers for HTTP
This document describes a set of data types and associated algorithms that are intended to make it easier and safer to define and handle HTTP header fields. It is intended for use by specifications of new HTTP header fields that wish to use a common syntax that is more restrictive than traditional HTTP field values.
Informative References
Content Security Policy Level 3
Google
Subresource Integrity
Dropbox
Mozilla
Mozilla
Google
PATCH Method for HTTP
Several applications extending the Hypertext Transfer Protocol (HTTP) require a feature to do partial resource modification. The existing HTTP PUT method only allows a complete replacement of a document. This proposal adds a new HTTP method, PATCH, to modify an existing HTTP resource. [STANDARDS-TRACK]
Acknowledgments
TODO acknowledge someone.