Conditional HTTP Requests Using Digests

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.¶

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

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.¶

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.¶

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!¶

Acknowledgments

TODO acknowledge someone.¶

Author's Address