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] Fielding, R., Nottingham, M., and J. Reschke, "HTTP Semantics", Work in Progress, Internet-Draft, draft-ietf- httpbis-semantics-07, 7 March 2020, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [SH] Nottingham, M. and P. Kamp, "Structured Headers for HTTP", Work in Progress, Internet-Draft, draft-ietf-httpbis- header-structure-14, 28 January 2020, . 7.2. Informative References [CSP] West, M., "Content Security Policy Level 3", W3C ED, 28 February 2019, . [PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, DOI 10.17487/RFC5789, March 2010, . [SRI] Akhawe, D., Braun, F., Marier, F., and J. Weinberger, "Subresource Integrity", W3C ED, 4 January 2020, . Acknowledgments TODO acknowledge someone. Author's Address Martin Thomson Mozilla Email: mt@lowentropy.net Thomson Expires 10 September 2020 [Page 5]