[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]

Versions: 00

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]


Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/