draft-ietf-httpbis-digest-headers-07.txt   draft-ietf-httpbis-digest-headers-latest.txt 
HTTP Working Group R. Polli HTTP Working Group R. Polli
Internet-Draft Team Digitale, Italian Government Internet-Draft Team Digitale, Italian Government
Obsoletes: 3230 (if approved) L. Pardue Obsoletes: 3230 (if approved) L. Pardue
Intended status: Standards Track Cloudflare Intended status: Standards Track Cloudflare
Expires: May 20, 2022 November 16, 2021 Expires: July 6, 2022 January 02, 2022
Digest Fields Digest Fields
draft-ietf-httpbis-digest-headers-07 draft-ietf-httpbis-digest-headers-latest
Abstract Abstract
This document defines HTTP fields that support integrity checksums. This document defines HTTP fields that support integrity checksums.
The Digest field can be used for the integrity of HTTP The Digest field can be used for the integrity of HTTP
representations. The Content-Digest field can be used for the representations. The Content-Digest field can be used for the
integrity of HTTP message content. Want-Digest and Want-Content- integrity of HTTP message content. Want-Digest and Want-Content-
Digest can be used to indicate a sender's desire to receive integrity Digest can be used to indicate a sender's desire to receive integrity
fields respectively. fields respectively.
This document obsoletes RFC 3230. This document obsoletes RFC 3230.
Note to Readers About This Document
_RFC EDITOR: please remove this section before publication_ This note is to be removed before publishing as an RFC.
Discussion of this draft takes place on the HTTP working group Status information for this document may be found at
mailing list (ietf-http-wg@w3.org), which is archived at <https://datatracker.ietf.org/doc/draft-ietf-httpbis-digest-
https://lists.w3.org/Archives/Public/ietf-http-wg/ [1]. headers/>.
The source code and issues list for this draft can be found at Discussion of this document takes place on the HTTP Working Group
https://github.com/httpwg/http-extensions [2]. mailing list (<mailto:ietf-http-wg@w3.org>), which is archived at
<https://lists.w3.org/Archives/Public/ietf-http-wg/>. Working Group
information can be found at <https://httpwg.org/>.
Source for this draft and an issue tracker can be found at
<https://github.com/httpwg/http-extensions/labels/digest-headers>.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 20, 2022. This Internet-Draft will expire on July 6, 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2022 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Document Structure . . . . . . . . . . . . . . . . . . . 4
1.2. Concept Overview . . . . . . . . . . . . . . . . . . . . 4
1.3. Replacing RFC 3230 . . . . . . . . . . . . . . . . . . . 5
1.4. Notational Conventions . . . . . . . . . . . . . . . . . 6
2. Representation Digest . . . . . . . . . . . . . . . . . . . . 6
3. The Digest Field . . . . . . . . . . . . . . . . . . . . . . 7
4. The Content-Digest Field . . . . . . . . . . . . . . . . . . 8
5. Want-Digest and Want-Content-Digest Fields . . . . . . . . . 9
6. Digest Algorithm Values . . . . . . . . . . . . . . . . . . . 9
7. Using Digest in State-Changing Requests . . . . . . . . . . . 13
7.1. Digest and Content-Location in Responses . . . . . . . . 14
8. Security Considerations . . . . . . . . . . . . . . . . . . . 14
8.1. Digest Does Not Protect the Full HTTP Message . . . . . . 14
8.2. Digest for End-to-End Integrity . . . . . . . . . . . . . 14
8.3. Usage in Signatures . . . . . . . . . . . . . . . . . . . 14
8.4. Usage in Trailer Fields . . . . . . . . . . . . . . . . . 15
8.5. Usage with Encryption . . . . . . . . . . . . . . . . . . 15
8.6. Algorithm Agility . . . . . . . . . . . . . . . . . . . . 15
8.7. Duplicate digest-algorithm in field value . . . . . . . . 16
8.8. Resource exhaustion . . . . . . . . . . . . . . . . . . . 16
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
9.1. Establish the HTTP Digest Algorithm Values Registry . . . 16
9.2. Obsolete "contentMD5" token in Digest Algorithm . . . . . 17
9.3. Changes Compared to RFC3230 . . . . . . . . . . . . . . . 17
9.4. Changes Compared to RFC5843 . . . . . . . . . . . . . . . 17
9.5. Want-Digest Field Registration . . . . . . . . . . . . . 17
9.6. Digest Field Registration . . . . . . . . . . . . . . . . 18
9.7. Want-Content-Digest Field Registration . . . . . . . . . 18
9.8. Content-Digest Field Registration . . . . . . . . . . . . 18
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 18
10.1. Normative References . . . . . . . . . . . . . . . . . . 18
10.2. Informative References . . . . . . . . . . . . . . . . . 20
10.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Appendix A. Resource Representation and Representation-Data . . 22
Appendix B. Examples of Unsolicited Digest . . . . . . . . . . . 24
B.1. Server Returns Full Representation Data . . . . . . . . . 24
B.2. Server Returns No Representation Data . . . . . . . . . . 25
B.3. Server Returns Partial Representation Data . . . . . . . 25
B.4. Client and Server Provide Full Representation Data . . . 26
B.5. Client Provides Full Representation Data, Server Provides
No Representation Data . . . . . . . . . . . . . . . . . 26
B.6. Client and Server Provide Full Representation Data . . . 27
B.7. POST Response does not Reference the Request URI . . . . 28
B.8. POST Response Describes the Request Status . . . . . . . 28
B.9. Digest with PATCH . . . . . . . . . . . . . . . . . . . . 29
B.10. Error responses . . . . . . . . . . . . . . . . . . . . . 30
B.11. Use with Trailer Fields and Transfer Coding . . . . . . . 31
Appendix C. Examples of Want-Digest Solicited Digest . . . . . . 31
C.1. Server Selects Client's Least Preferred Algorithm . . . . 32
C.2. Server Selects Algorithm Unsupported by Client . . . . . 32
C.3. Server Does Not Support Client Algorithm and Returns an
Error . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 33
FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
G.1. Since draft-ietf-httpbis-digest-headers-06 . . . . . . . 37
G.2. Since draft-ietf-httpbis-digest-headers-05 . . . . . . . 37
G.3. Since draft-ietf-httpbis-digest-headers-04 . . . . . . . 37
G.4. Since draft-ietf-httpbis-digest-headers-03 . . . . . . . 37
G.5. Since draft-ietf-httpbis-digest-headers-02 . . . . . . . 37
G.6. Since draft-ietf-httpbis-digest-headers-01 . . . . . . . 38
G.7. Since draft-ietf-httpbis-digest-headers-00 . . . . . . . 38
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38
1. Introduction 1. Introduction
HTTP does not define a means to protect the integrity of HTTP does not define a means to protect the integrity of
representations. When HTTP messages are transferred between representations. When HTTP messages are transferred between
endpoints, the protocol might choose to make use of features of the endpoints, the protocol might choose to make use of features of the
lower layer in order to provide some integrity protection; for lower layer in order to provide some integrity protection; for
instance, TCP checksums or TLS records [RFC2818]. instance, TCP checksums or TLS records [RFC2818].
This document defines two digest integrity mechanisms for HTTP. This document defines two digest integrity mechanisms for HTTP.
First, representation data integrity, which acts on representation First, representation data integrity, which acts on representation
data (Section 3.2 of [SEMANTICS]). Second, content digest integrity, data (Section 3.2 of [SEMANTICS]). Second, content integrity, which
which acts on conveyed content (Section 6.4 of [SEMANTICS]). Both acts on conveyed content (Section 6.4 of [SEMANTICS]). Both
mechanisms operate independent of transport integrity, offering the mechanisms operate independent of transport integrity, offering the
potential to detect programming errors and corruption of data in potential to detect programming errors and corruption of data in
flight or at rest. They can be used across multiple hops in order to flight or at rest. They can be used across multiple hops in order to
provide end-to-end integrity guarantees, which can aid fault provide end-to-end integrity guarantees, which can aid fault
diagnosis when resources are transferred across hops and system diagnosis when resources are transferred across hops and system
boundaries. Finally, they can be used to validate integrity when boundaries. Finally, they can be used to validate integrity when
reconstructing a resource fetched using different HTTP connections. reconstructing a resource fetched using different HTTP connections.
This document obsoletes [RFC3230]. This document obsoletes [RFC3230].
1.1. Document Structure 1.1. Document Structure
This document is structured as follows: This document is structured as follows:
o Section 2 describes concepts related to representation digests, o Section 2 describes concepts related to representation digests.
It also defines the Digest request and response header and trailer
o Section 3 defines the Digest request and response header and field,
trailer field,
o Section 4 defines the Content-Digest request and response header o Section 3 defines the Content-Digest request and response header
and trailer field, and trailer field,
o Section 5 defines the Want-Digest and Want-Content-Digest request o Section 4 defines the Want-Digest and Want-Content-Digest request
and response header and trailer field, and response header and trailer field,
o Section 6 describes algorithms and their relation to Digest, o Section 5 describes algorithms and their relation to Digest,
o Section 7 details computing representation digests, o Section 6 details computing representation digests,
o Appendix B and Appendix C provide examples of using Digest and o Appendix B and Appendix C provide examples of using Digest and
Want-Digest. Want-Digest.
1.2. Concept Overview 1.2. Concept Overview
This document defines the "Digest" request and response header and This document defines the "Digest" request and response header and
trailer field; see Section 3. At a high level, the value contains a trailer field; see Section 2. At a high level, the value contains a
checksum, computed over "selected representation data" (Section 3.2 checksum, computed over "selected representation data" (Section 3.2
of [SEMANTICS]), that the recipient can use to validate integrity. of [SEMANTICS]), that the recipient can use to validate integrity.
Basing "Digest" on the selected representation makes it Basing "Digest" on the selected representation makes it
straightforward to apply it to use-cases where the transferred data straightforward to apply it to use-cases where the transferred data
requires some sort of manipulation to be considered a representation requires some sort of manipulation to be considered a representation
or conveys a partial representation of a resource, such as Range or conveys a partial representation of a resource, such as Range
Requests (see Section 14.2 of [SEMANTICS]). Requests (see Section 14.2 of [SEMANTICS]).
To support use-cases where a simple checksum of the content bytes is To support use-cases where a simple checksum of the content bytes is
required, this document introduces the "Content-Digest" request and required, this document introduces the "Content-Digest" request and
response header and trailer field; see Section 4. response header and trailer field; see Section 3.
"Digest" and "Content-Digest" support algorithm agility. The "Want- "Digest" and "Content-Digest" contain checksums that are calculated
Digest" and "Want-Content-Digest" fields allows endpoints to express using one of the digest-algorithms listed in the HTTP Digest
interest in "Digest" and "Content-Digest" respectively, and Algorithm Values Registry (see Section 5), which are encoded in the
preference of algorithms in either. format associated with each encoding. Algorithm agility is
supported. The "Want-Digest" and "Want-Content-Digest" fields allows
endpoints to express interest in "Digest" and "Content-Digest"
respectively, and preference of algorithms in either.
Digest field calculations are tied to the "Content-Encoding" and Digest field calculations are tied to the "Content-Encoding" and
"Content-Type" header fields. Therefore, a given resource may have "Content-Type" header fields. Therefore, a given resource may have
multiple different checksum values when transferred with HTTP. multiple different checksum values when transferred with HTTP.
Digest fields do not provide integrity for HTTP messages or fields. Digest fields do not provide integrity for HTTP messages or fields.
However, they can be combined with other mechanisms that protect However, they can be combined with other mechanisms that protect
metadata, such as digital signatures, in order to protect the phases metadata, such as digital signatures, in order to protect the phases
of an HTTP exchange in whole or in part. of an HTTP exchange in whole or in part.
skipping to change at page 5, line 34 skipping to change at page 4, line 25
Historically, the "Content-MD5" header field provided an HTTP Historically, the "Content-MD5" header field provided an HTTP
integrity mechanism but HTTP/1.1 ([RFC7231], Appendix B) obsoleted it integrity mechanism but HTTP/1.1 ([RFC7231], Appendix B) obsoleted it
due to inconsistent handling of partial responses. [RFC3230] defined due to inconsistent handling of partial responses. [RFC3230] defined
the concept of "instance" digests and a more flexible integrity the concept of "instance" digests and a more flexible integrity
scheme to help address issues with "Content-MD5". It first scheme to help address issues with "Content-MD5". It first
introduced the "Digest" and "Want-Digest" fields. HTTP terminology introduced the "Digest" and "Want-Digest" fields. HTTP terminology
has evolved since [RFC3230] was published. The concept of "instance" has evolved since [RFC3230] was published. The concept of "instance"
has been superseded by "selected representation". has been superseded by "selected representation".
This document replaces [RFC3230]. The changes described in the This document replaces [RFC3230]. The changes described in the
following paragraphs are intended to be semantically compatible with following paragraphs are intended to be syntactically and
existing implementations where possible. semantically compatible with existing implementations where possible.
The "Digest" and "Want-Digest" field definitions are updated to align The "Digest" and "Want-Digest" field definitions are updated to align
with the terms and notational conventions in [SEMANTICS]. with the terms and notational conventions in [SEMANTICS].
Negotiation of "Content-MD5" is deprecated and has been replaced by Negotiation of "Content-MD5" is deprecated and has been replaced by
"Content-Digest" negotiation via "Want-Content-Digest". "Content-Digest" negotiation via "Want-Content-Digest".
Sections 4.1.1 and 4.2 of [RFC3230] defined field parameters. This Sections 4.1.1 and 4.2 of [RFC3230] defined field parameters. This
document obsoletes the usage of parameters with "Digest" because this document obsoletes the usage of parameters with "Digest" because this
feature has not been widely deployed and complicates field-value feature has not been widely deployed and complicates field-value
processing. [RFC3230] intended field parameters to provide a common processing. [RFC3230] intended field parameters to provide a common
way to attach additional information to a representation-data-digest. way to attach additional information to a representation-data-digest.
However, if parameters are used as an input to validate the checksum, However, if parameters are used as an input to validate the checksum,
an attacker could alter them to steer the validation behavior. A an attacker could alter them to steer the validation behavior. A
digest-algorithm can still be parameterized by defining its own way digest-algorithm can still be parameterized by defining its own way
to encode parameters into the representation-data-digest, in such a to encode parameters into the representation-data-digest, in such a
way as to mitigate security risks related to its computation. way as to mitigate security risks related to its computation.
The algorithm table has been updated to reflect the current state of The algorithm table has been updated to reflect the current state of
the art, (see Section 6). the art, (see Section 5).
1.4. Notational Conventions 1.4. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
This document uses the Augmented BNF defined in [RFC5234] and updated This document uses the Augmented BNF defined in [RFC5234] and updated
skipping to change at page 6, line 29 skipping to change at page 5, line 20
Section 12.4.2 of [SEMANTICS]. Section 12.4.2 of [SEMANTICS].
The definitions "representation", "selected representation", The definitions "representation", "selected representation",
"representation data", "representation metadata", and "content" in "representation data", "representation metadata", and "content" in
this document are to be interpreted as described in [SEMANTICS]. this document are to be interpreted as described in [SEMANTICS].
Algorithm names respect the casing used in their definition document Algorithm names respect the casing used in their definition document
(e.g. SHA-1, CRC32c) whereas digest-algorithm tokens are quoted (e.g. SHA-1, CRC32c) whereas digest-algorithm tokens are quoted
(e.g. "sha", "crc32c"). (e.g. "sha", "crc32c").
2. Representation Digest The term "checksum" describes the output of the application of an
algorithm to a sequence of bytes, whereas digest is only used in
The representation digest is an integrity mechanism for HTTP relation to the value of the fields.
resources which uses a checksum that is calculated independently of
the content (see Section 6.4 of [SEMANTICS]). It uses the
representation data (see Section 8.1 of [SEMANTICS]), that can be
fully or partially contained in the content, or not contained at all.
This takes into account the effect of the HTTP semantics on the
messages; for example, the content can be affected by Range Requests
or methods such as HEAD, while the way the content is transferred "on
the wire" is dependent on other transformations (e.g. transfer
codings for HTTP/1.1 - see Section 6.1 of [HTTP11]). To help
illustrate how such things affect "Digest", several examples are
provided in Appendix A.
A representation digest consists of the value of a checksum computed
on the entire selected "representation data" (see Section 8.1 of
[SEMANTICS]) of a resource identified according to Section 6.4.2 of
[SEMANTICS] together with an indication of the algorithm used:
representation-data-digest = digest-algorithm "="
<encoded digest output>
When a message has no representation data it is still possible to
assert that no representation data was sent computing the
representation digest on an empty string (see Section 8.3).
The checksum is computed using one of the digest-algorithms listed in
the HTTP Digest Algorithm Values Registry (see Section 6) and then
encoded in the associated format.
3. The Digest Field 2. The Digest Field
The "Digest" field contains a comma-separated list of one or more The "Digest" field contains a comma-separated list of one or more
representation digest values as defined in Section 2. It can be used representation digest values. It can be used in both requests and
in both requests and responses. responses.
A representation digest is an integrity mechanism for HTTP resources
that uses a checksum calculated independently of the content (see
Section 6.4 of [SEMANTICS]). A representation digest consists of the
value of a checksum computed on the entire selected "representation
data" (see Section 8.1 of [SEMANTICS]) of a resource identified
according to Section 6.4.2 of [SEMANTICS], together with an
indication of the algorithm used. Note that representation data can
be fully or partially contained in the content, or not contained at
all. When a message has no representation data it is possible to
assert that no representation data was sent by using the
representation digest on an empty string (see Section 7.3).
Digest = 1#representation-data-digest Digest = 1#representation-data-digest
representation-data-digest = digest-algorithm "="
<encoded checksum output>
For example: For example:
Digest: sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm Digest: sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm
AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==
Basing "Digest" on representation data takes into account the effect
of HTTP semantics on messages; for example, the content can be
affected by Range Requests or methods such as HEAD, while the way the
content is transferred "on the wire" is dependent on other
transformations (e.g. transfer codings for HTTP/1.1 - see Section 6.1
of [HTTP11]). To help illustrate how such things affect "Digest",
several examples are provided in Appendix A.
A "Digest" field MAY contain multiple representation-data-digest A "Digest" field MAY contain multiple representation-data-digest
values. For example, a server may provide representation-data-digest values. For example, a server may provide representation-data-digest
values using different algorithms, allowing it to support a values using different algorithms, allowing it to support a
population of clients with different evolving capabilities; this is population of clients with different evolving capabilities; this is
particularly useful in support of transitioning away from weaker particularly useful in support of transitioning away from weaker
algorithms should the need arise (see Section 8.6). algorithms should the need arise (see Section 7.6).
Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=,
sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm
AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==
A recipient MAY ignore any or all of the representation-data-digests A recipient MAY ignore any or all of the representation-data-digests
in a Digest field. This allows the recipient to choose which digest- in a Digest field. This allows the recipient to choose which digest-
algorithm(s) to use for validation instead of verifying every algorithm(s) to use for validation instead of verifying every
received representation-data-digest. received representation-data-digest.
A sender MAY send a representation-data-digest using a digest- A sender MAY send a representation-data-digest using a digest-
algorithm without knowing whether the recipient supports the digest- algorithm without knowing whether the recipient supports the digest-
algorithm, or even knowing that the recipient will ignore it. algorithm, or even knowing that the recipient will ignore it.
"Digest" can be sent in a trailer section. In this case, "Digest" "Digest" can be sent in a trailer section. In this case, "Digest"
MAY be merged into the header section; see Section 6.5.1 of MAY be merged into the header section; see Section 6.5.1 of
[SEMANTICS]. [SEMANTICS].
When an incremental digest-algorithm is used, the sender and the
receiver can dynamically compute the digest value while streaming the
content.
A non-comprehensive set of examples showing the impacts of A non-comprehensive set of examples showing the impacts of
representation metadata, payload transformations and HTTP methods on representation metadata, payload transformations and HTTP methods on
"Digest" is provided in Appendix B and Appendix C. "Digest" is provided in Appendix B and Appendix C.
4. The Content-Digest Field 3. The Content-Digest Field
The "Content-Digest" field contains a comma-separated list of one or The "Content-Digest" field contains a comma-separated list of one or
more content digest values. A content digest value is computed by more content digest values. A content digest value is computed by
applying a digest-algorithm to the actual message content (see applying a digest-algorithm to the actual message content (see
Section 6.4 of [SEMANTICS]). It can be used in both requests and Section 6.4 of [SEMANTICS]). It can be used in both requests and
responses. responses.
Content-Digest = 1#content-digest Content-Digest = 1#content-digest
content-digest = digest-algorithm "=" content-digest = digest-algorithm "="
<encoded digest output> <encoded checksum output>
For example: For example:
Content-Digest: sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm Content-Digest: sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm
AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==
A "Content-Digest" field MAY contain multiple content-digest values, A "Content-Digest" field MAY contain multiple content-digest values,
similarly to "Digest" (see Section 3) similarly to "Digest" (see Section 2)
Content-Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, Content-Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=,
sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm
AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==
A recipient MAY ignore any or all of the content-digests in a A recipient MAY ignore any or all of the content-digests in a
Content-Digest field. This allows the recipient to choose which Content-Digest field. This allows the recipient to choose which
digest-algorithm(s) to use for validation instead of verifying every digest-algorithm(s) to use for validation instead of verifying every
received content-digest. received content-digest.
A sender MAY send a content-digest using a digest-algorithm without A sender MAY send a content-digest using a digest-algorithm without
knowing whether the recipient supports the digest-algorithm, or even knowing whether the recipient supports the digest-algorithm, or even
knowing that the recipient will ignore it. knowing that the recipient will ignore it.
"Content-Digest" can be sent in a trailer section. In this case, "Content-Digest" can be sent in a trailer section. In this case,
"Content-Digest" MAY be merged into the header section; see "Content-Digest" MAY be merged into the header section; see
Section 6.5.1 of [SEMANTICS]. Section 6.5.1 of [SEMANTICS].
When an incremental digest-algorithm is used, the sender and the 4. Want-Digest and Want-Content-Digest Fields
receiver can dynamically compute the digest value while streaming the
content.
5. Want-Digest and Want-Content-Digest Fields
Senders can indicate their integrity checksum preferences using the Senders can indicate their integrity checksum preferences using the
"Want-Digest" or "Want-Content-Digest" fields. These can be used in "Want-Digest" or "Want-Content-Digest" fields. These can be used in
both requests and responses. both requests and responses.
"Want-Digest" indicates the sender's desire to receive a "Want-Digest" indicates the sender's desire to receive a
representation digest on messages associated with the request URI and representation digest on messages associated with the request URI and
representation metadata, using the "Digest" field. representation metadata, using the "Digest" field.
"Want-Content-Digest" indicates the sender's desire to receive a "Want-Content-Digest" indicates the sender's desire to receive a
skipping to change at page 9, line 37 skipping to change at page 8, line 15
Senders can provide multiple digest-algorithm items with the same Senders can provide multiple digest-algorithm items with the same
qvalue. qvalue.
Examples: Examples:
Want-Digest: sha-256 Want-Digest: sha-256
Want-Digest: sha-512;q=0.3, sha-256;q=1, unixsum;q=0 Want-Digest: sha-512;q=0.3, sha-256;q=1, unixsum;q=0
Want-Content-Digest: sha-256 Want-Content-Digest: sha-256
Want-Content-Digest: sha-512;q=0.3, sha-256;q=1, unixsum;q=0 Want-Content-Digest: sha-512;q=0.3, sha-256;q=1, unixsum;q=0
6. Digest Algorithm Values 5. Digest Algorithm Values
Digest-algorithm values are used to indicate a specific digest Digest-algorithm values are used to indicate a specific digest
computation. computation.
digest-algorithm = token digest-algorithm = token
All digest-algorithm token values are case-insensitive but lower case All digest-algorithm token values are case-insensitive but lower case
is preferred; digest-algorithm token values MUST be compared in a is preferred; digest-algorithm token values MUST be compared in a
case-insensitive fashion. case-insensitive fashion.
Every digest-algorithm defines its computation procedure and encoding Every digest-algorithm defines its computation procedure and encoding
output. Unless specified otherwise, comparison of encoded output is output. Unless specified otherwise, comparison of encoded output is
case-sensitive. case-sensitive.
The "HTTP Digest Algorithm Values Registry", maintained by IANA at The "HTTP Digest Algorithm Values Registry", maintained by IANA at
https://www.iana.org/assignments/http-dig-alg/ [3] registers digest- https://www.iana.org/assignments/http-dig-alg/ [1] registers digest-
algorithm values. Registrations MUST include the following fields: algorithm values. Registrations MUST include the following fields:
o Digest algorithm: the token value. The registry can be used to o Digest algorithm: the token value. The registry can be used to
reserve token values reserve token values
o Status: the status of the algorithm. Use "standard" for o Status: the status of the algorithm. Use "standard" for
standardized algorithms without known problems; "experimental" or standardized algorithms without known problems; "experimental" or
some other appropriate value some other appropriate value
* e.g. according to the type and status of the primary document * e.g. according to the type and status of the primary document
in which the algorithm is defined; "insecure" when the in which the algorithm is defined; "insecure" when the
algorithm is insecure; "reserved" when Digest algorithm algorithm is insecure; "reserved" when the algorithm references
references a reserved token value a reserved token value
o Description: the description of the digest-algorithm and its o Description: the description of the digest-algorithm and its
encoding encoding
o Reference: a set of pointers to the primary documents defining the o Reference: a set of pointers to the primary documents defining the
digest-algorithm digest-algorithm
The associated encoding for new digest-algorithms MUST either be The associated encoding for new digest-algorithms MUST either be
represented as a quoted string or MUST NOT include ";" or "," in the represented as a quoted string or MUST NOT include ";" or "," in the
character sets used for the encoding. character sets used for the encoding.
Insecure digest algorithms MAY be used to preserve integrity against Insecure digest algorithms MAY be used to preserve integrity against
accidental change, but MUST NOT be used in a potentially adversarial corruption, but MUST NOT be used in a potentially adversarial
setting; for example, when signing the digest of content for setting; for example, when signing digest fields' values for
authenticity. authenticity.
The registry is initialized with the tokens listed below. The registry is initialized with the tokens listed below.
sha-512 sha-512
* Digest Algorithm: sha-512 * Digest Algorithm: sha-512
* Description: The SHA-512 algorithm [RFC6234]. The output of * Description: The SHA-512 algorithm [RFC6234]. The output of
this algorithm is encoded using the base64 encoding [RFC4648]. this algorithm is encoded using base64 [RFC4648].
* Reference: [RFC6234], [RFC4648], this document. * Reference: [RFC6234], [RFC4648], this document.
* Status: standard * Status: standard
sha-256 sha-256
* Digest Algorithm: sha-256 * Digest Algorithm: sha-256
* Description: The SHA-256 algorithm [RFC6234]. The output of * Description: The SHA-256 algorithm [RFC6234]. The output of
this algorithm is encoded using the base64 encoding [RFC4648]. this algorithm is encoded using base64 [RFC4648].
* Reference: [RFC6234], [RFC4648], this document. * Reference: [RFC6234], [RFC4648], this document.
* Status: standard * Status: standard
md5 md5
* Digest Algorithm: md5 * Digest Algorithm: md5
* Description: The MD5 algorithm, as specified in [RFC1321]. The * Description: The MD5 algorithm [RFC1321]. The output of this
output of this algorithm is encoded using the base64 encoding algorithm is encoded using base64 [RFC4648]. This digest-
[RFC4648]. This digest-algorithm is now vulnerable to algorithm is now vulnerable to collision attacks. See [NO-MD5]
collision attacks. See [NO-MD5] and [CMU-836068]. and [CMU-836068].
* Reference: [RFC1321], [RFC4648], this document. * Reference: [RFC1321], [RFC4648], this document.
* Status: insecure * Status: insecure
sha sha
* Digest Algorithm: sha * Digest Algorithm: sha
* Description: The SHA-1 algorithm [RFC3174]. The output of this * Description: The SHA-1 algorithm [RFC3174]. The output of this
algorithm is encoded using the base64 encoding [RFC4648]. This algorithm is encoded using base64 [RFC4648]. This digest-
digest-algorithm is now vulnerable to collision attacks. See algorithm is now vulnerable to collision attacks. See
[NO-SHA1] and [IACR-2020-014]. [NO-SHA1] and [IACR-2020-014].
* Reference: [RFC3174], [RFC6234], [RFC4648], this document. * Reference: [RFC3174], [RFC6234], [RFC4648], this document.
* Status: insecure * Status: insecure
unixsum unixsum
* Digest Algorithm: unixsum * Digest Algorithm: unixsum
* Description: The algorithm computed by the UNIX "sum" command, * Description: The algorithm used by the UNIX "sum" command
as defined by the Single UNIX Specification, Version 2 [UNIX]. [UNIX]. The output of this algorithm is an ASCII decimal-digit
The output of this algorithm is an ASCII decimal-digit string string representing the 16-bit checksum, which is the first
representing the 16-bit checksum, which is the first word of word of the output of the UNIX "sum" command.
the output of the UNIX "sum" command.
* Reference: [UNIX], this document. * Reference: [UNIX], this document.
* Status: insecure * Status: insecure
unixcksum unixcksum
* Digest Algorithm: unixcksum * Digest Algorithm: unixcksum
* Description: The algorithm computed by the UNIX "cksum" * Description: The algorithm used by the UNIX "cksum" command
command, as defined by the Single UNIX Specification, Version 2
[UNIX]. The output of this algorithm is an ASCII digit string [UNIX]. The output of this algorithm is an ASCII digit string
representing the 32-bit CRC, which is the first word of the representing the 32-bit CRC, which is the first word of the
output of the UNIX "cksum" command. output of the UNIX "cksum" command.
* Reference: [UNIX], this document. * Reference: [UNIX], this document.
* Status: insecure * Status: insecure
adler32 adler32
* Digest Algorithm: adler32 * Digest Algorithm: adler32
* Description: The ADLER32 algorithm is a checksum specified in * Description: The ADLER32 algorithm [RFC1950]. The 32-bit
[RFC1950] "ZLIB Compressed Data Format". The 32-bit output is output is encoded in hexadecimal (using between 1 and 8 ASCII
encoded in hexadecimal (using between 1 and 8 ASCII characters characters from 0-9, A-F, and a-f; leading 0's are allowed).
from 0-9, A-F, and a-f; leading 0's are allowed). For example, For example, adler32=03da0195 and adler32=3DA0195 are both
adler32=03da0195 and adler32=3DA0195 are both valid checksums valid checksums for the 4-byte message "Wiki". This algorithm
for the 4-byte message "Wiki". This algorithm is obsoleted and is obsoleted and SHOULD NOT be used.
SHOULD NOT be used.
* Reference: [RFC1950], this document. * Reference: [RFC1950], this document.
* Status: insecure * Status: insecure
crc32c crc32c
* Digest Algorithm: crc32c * Digest Algorithm: crc32c
* Description: The CRC32c algorithm is a 32-bit cyclic redundancy
check. It achieves a better hamming distance (for better * Description: The CRC32c algorithm [RFC4960]. The 32-bit output
error-detection performance) than many other 32-bit CRC is encoded in hexadecimal (using between 1 and 8 ASCII
functions. Other places it is used include iSCSI and SCTP. characters from 0-9, A-F, and a-f; leading 0's are allowed).
The 32-bit output is encoded in hexadecimal (using between 1 For example, crc32c=0a72a4df and crc32c=A72A4DF are both valid
and 8 ASCII characters from 0-9, A-F, and a-f; leading 0's are checksums for the 3-byte message "dog".
allowed). For example, crc32c=0a72a4df and crc32c=A72A4DF are
both valid checksums for the 3-byte message "dog".
* Reference: [RFC4960] appendix B, this document. * Reference: [RFC4960] appendix B, this document.
* Status: insecure * Status: insecure
7. Using Digest in State-Changing Requests 6. Using Digest in State-Changing Requests
When the representation enclosed in a state-changing request does not When the representation enclosed in a state-changing request does not
describe the target resource, the representation digest MUST be describe the target resource, the representation digest MUST be
computed on the representation-data. This is the only possible computed on the representation-data. This is the only possible
choice because representation digest requires complete representation choice because representation digest requires complete representation
metadata (see Section 2). metadata (see Section 2).
In responses, In responses,
o if the representation describes the status of the request, o if the representation describes the status of the request,
skipping to change at page 14, line 5 skipping to change at page 12, line 23
field does not affect "Digest" because it is not representation field does not affect "Digest" because it is not representation
metadata. metadata.
For example, in PATCH requests, the representation digest will be For example, in PATCH requests, the representation digest will be
computed on the patch document because the representation metadata computed on the patch document because the representation metadata
refers to the patch document and not to the target resource (see refers to the patch document and not to the target resource (see
Section 2 of [PATCH]). In responses, instead, the representation Section 2 of [PATCH]). In responses, instead, the representation
digest will be computed on the selected representation of the patched digest will be computed on the selected representation of the patched
resource. resource.
7.1. Digest and Content-Location in Responses 6.1. Digest and Content-Location in Responses
When a state-changing method returns the "Content-Location" header When a state-changing method returns the "Content-Location" header
field, the enclosed representation refers to the resource identified field, the enclosed representation refers to the resource identified
by its value and "Digest" is computed accordingly. An example is by its value and "Digest" is computed accordingly. An example is
given in Appendix B.7. given in Appendix B.7.
8. Security Considerations 7. Security Considerations
8.1. Digest Does Not Protect the Full HTTP Message 7.1. Digest Does Not Protect the Full HTTP Message
This document specifies a data integrity mechanism that protects HTTP This document specifies a data integrity mechanism that protects HTTP
"representation data" or content, but not HTTP header and trailer "representation data" or content, but not HTTP header and trailer
fields, from certain kinds of accidental corruption. fields, from certain kinds of corruption.
Digest fields are not intended to be a general protection against Digest fields are not intended to be a general protection against
malicious tampering with HTTP messages. This can be achieved by malicious tampering with HTTP messages. This can be achieved by
combining it with other approaches such as transport-layer security combining it with other approaches such as transport-layer security
or digital signatures. or digital signatures.
8.2. Digest for End-to-End Integrity 7.2. Digest for End-to-End Integrity
Digest fields can help detect "representation data" or content Digest fields can help detect "representation data" or content
modification due to implementation errors, undesired "transforming modification due to implementation errors, undesired "transforming
proxies" (see Section 7.7 of [SEMANTICS]) or other actions as the proxies" (see Section 7.7 of [SEMANTICS]) or other actions as the
data passes across multiple hops or system boundaries. Even a simple data passes across multiple hops or system boundaries. Even a simple
mechanism for end-to-end "representation data" integrity is valuable mechanism for end-to-end "representation data" integrity is valuable
because user-agent can validate that resource retrieval succeeded because user-agent can validate that resource retrieval succeeded
before handing off to a HTML parser, video player etc. for parsing. before handing off to a HTML parser, video player etc. for parsing.
Note that using digest fields alone does not provide end-to-end Note that using digest fields alone does not provide end-to-end
integrity of HTTP messages over multiple hops, since metadata could integrity of HTTP messages over multiple hops, since metadata could
be manipulated at any stage. Methods to protect metadata are be manipulated at any stage. Methods to protect metadata are
discussed in Section 8.3. discussed in Section 7.3.
8.3. Usage in Signatures 7.3. Usage in Signatures
Digital signatures are widely used together with checksums to provide Digital signatures are widely used together with checksums to provide
the certain identification of the origin of a message [NIST800-32]. the certain identification of the origin of a message [NIST800-32].
Such signatures can protect one or more HTTP fields and there are Such signatures can protect one or more HTTP fields and there are
additional considerations when "Digest" is included in this set. additional considerations when digest fields are included in this
set.
Since digest fields are hashes of resource representations, they Since digest fields are checksums of resource representations, they
explicitly depend on the "representation metadata" (e.g. the values explicitly depend on the "representation metadata" (e.g. the values
of "Content-Type", "Content-Encoding" etc). A signature that of "Content-Type", "Content-Encoding" etc). A signature that
protects "Digest" but not other "representation metadata" can expose protects "Digest" but not other "representation metadata" can expose
the communication to tampering. For example, an actor could the communication to tampering. For example, an actor could
manipulate the "Content-Type" field-value and cause a digest manipulate the "Content-Type" field-value and cause a digest
validation failure at the recipient, preventing the application from validation failure at the recipient, preventing the application from
accessing the representation. Such an attack consumes the resources accessing the representation. Such an attack consumes the resources
of both endpoints. See also Section 7.1. of both endpoints. See also Section 6.1.
Digest fields SHOULD always be used over a connection that provides
integrity at the transport layer that protects HTTP fields.
A "Digest" field using NOT RECOMMENDED digest-algorithms SHOULD NOT Since signatures are meant to protect against adversarial use cases,
be used in signatures. insecure and collision-prone algorithms do not provide adequate
guarantees (see Section 5).
Using signatures to protect the checksum of an empty representation Using signatures to protect the checksum of an empty representation
allows receiving endpoints to detect if an eventual payload has been allows receiving endpoints to detect if an eventual payload has been
stripped or added. stripped or added.
Any mangling of digest fields, including de-duplication of Any mangling of digest fields, including de-duplication of
representation-data-digest values or combining different field values representation-data-digest values or combining different field values
(see Section 5.2 of [SEMANTICS]) might affect signature validation. (see Section 5.2 of [SEMANTICS]) might affect signature validation.
8.4. Usage in Trailer Fields 7.4. Usage in Trailer Fields
Before sending digest fields in a trailer section, the sender should Before sending digest fields in a trailer section, the sender should
consider that intermediaries are explicitly allowed to drop any consider that intermediaries are explicitly allowed to drop any
trailer (see Section 6.5.2 of [SEMANTICS]). trailer (see Section 6.5.2 of [SEMANTICS]).
When digest fields are used in a trailer section, the field-values When digest fields are used in a trailer section, the field-values
are received after the content. Eager processing of content before are received after the content. Eager processing of content before
the trailer section prevents digest validation, possibly leading to the trailer section prevents digest validation, possibly leading to
processing of invalid data. processing of invalid data.
Not every digest-algorithm is suitable for use in the trailer Not every digest-algorithm is suitable for use in the trailer
section, some may require to pre-process the whole payload before section, some may require to pre-process the whole payload before
sending a message (e.g. see [I-D.thomson-http-mice]). sending a message (e.g. see [I-D.thomson-http-mice]).
8.5. Usage with Encryption 7.5. Usage with Encryption
Digest fields may expose details of encrypted payload when the
checksum is computed on the unencrypted data.
The checksum of an encrypted payload can change between different The checksum of an encrypted payload can change between different
messages depending on the encryption algorithm used; in those cases messages depending on the encryption algorithm used; in those cases
its value could not be used to provide a proof of integrity "at rest" its value could not be used to provide a proof of integrity "at rest"
unless the whole (e.g. encoded) content is persisted. unless the whole (e.g. encoded) content is persisted.
8.6. Algorithm Agility 7.6. Algorithm Agility
The security properties of digest-algorithms are not fixed. The security properties of digest-algorithms are not fixed.
Algorithm Agility (see [RFC7696]) is achieved by providing Algorithm Agility (see [RFC7696]) is achieved by providing
implementations with flexibility choose digest-algorithms from the implementations with flexibility choose digest-algorithms from the
IANA Digest Algorithm Values registry in Section 9.1. IANA Digest Algorithm Values registry in Section 8.1.
To help endpoints distinguish weaker algorithms from stronger ones, To help endpoints distinguish weaker algorithms from stronger ones,
this document adds to the IANA Digest Algorithm Values registry a new this document adds to the IANA Digest Algorithm Values registry a new
"Status" field containing the most recent appraisal of the digest- "Status" field containing the most recent appraisal of the digest-
algorithm. algorithm.
An endpoint might have a preference for algorithms, such as An endpoint might have a preference for algorithms, such as
preferring "standard" algorithms over "insecure" ones. Transition preferring "standard" algorithms over "insecure" ones. Transition
from weak algorithms is supported by negotiation of digest-algorithm from weak algorithms is supported by negotiation of digest-algorithm
using "Want-Digest" or "Want-Content-Digest" (see Section 5) or by using "Want-Digest" or "Want-Content-Digest" (see Section 4) or by
sending multiple representation-data-digest values from which the sending multiple representation-data-digest values from which the
receiver chooses. Endpoints are advised that sending multiple values receiver chooses. Endpoints are advised that sending multiple values
consumes resources, which may be wasted if the receiver ignores them consumes resources, which may be wasted if the receiver ignores them
(see Section 3). (see Section 2).
8.7. Duplicate digest-algorithm in field value While algorithm agility allows the migration to stronger algorithms
it does not prevent the use of weaker algorithms. Digest fields do
not provide any mitigiations for downgrade or substitution attacks
(see Section 1 of [RFC6211]) of the digest-algorithm. To protect
against such attacks, endpoints could restrict their set of supported
algorithms to stronger ones and protect the fields value by using TLS
and/or digital signatures.
7.7. Duplicate digest-algorithm in field value
An endpoint might receive multiple representation-data-digest values An endpoint might receive multiple representation-data-digest values
(see Section 3) that use the same digest-algorithm with different or (see Section 2) that use the same digest-algorithm with different or
identical digest-values. For example: identical digest-values. For example:
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=, Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=,
sha-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= sha-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
A receiver is permitted to ignore any representation-data-digest A receiver is permitted to ignore any representation-data-digest
value, so validation of duplicates is left as an implementation value, so validation of duplicates is left as an implementation
decision. Endpoints might select all, some, or none of the values decision. Endpoints might select all, some, or none of the values
for checksum comparison and, based on the intersection of those for checksum comparison and, based on the intersection of those
results, conditionally pass or fail digest validation. results, conditionally pass or fail digest validation.
8.8. Resource exhaustion 7.8. Resource exhaustion
Digest fields validation consumes computational resources. In order Digest fields validation consumes computational resources. In order
to avoid resource exhaustion, implementations can restrict validation to avoid resource exhaustion, implementations can restrict validation
of the algorithm types, number of validations, or the size of of the algorithm types, number of validations, or the size of
content. content.
9. IANA Considerations 8. IANA Considerations
9.1. Establish the HTTP Digest Algorithm Values Registry 8.1. Establish the HTTP Digest Algorithm Values Registry
This memo sets this specification to be the establishing document for This memo sets this specification to be the establishing document for
the HTTP Digest Algorithm Values [4] registry. the HTTP Digest Algorithm Values [2] registry.
IANA is asked to update the "Reference" for this registry to refer IANA is asked to update the "Reference" for this registry to refer
this document and to inizialize the registry with the tokens defined this document and to inizialize the registry with the tokens defined
in Section 6. in Section 5.
This registry uses the Specification Required policy (Section 4.6 of This registry uses the Specification Required policy (Section 4.6 of
[RFC8126]). [RFC8126]).
9.2. Obsolete "contentMD5" token in Digest Algorithm 8.2. Obsolete "contentMD5" token in Digest Algorithm
This memo adds the "contentMD5" token in the HTTP Digest Algorithm This memo adds the "contentMD5" token in the HTTP Digest Algorithm
Values [5] registry: Values [3] registry:
o Digest Algorithm: contentMD5 o Digest Algorithm: contentMD5
o Description: Section 5 of [RFC3230] defined the "contentMD5" token o Description: Section 5 of [RFC3230] defined the "contentMD5" token
to be used only in Want-Digest. This token is obsoleted and MUST to be used only in Want-Digest. This token is obsoleted by this
NOT be used. document.
o Reference: Section 9.2 of this document, Section 5 of [RFC3230]. o Reference: Section 8.2 of this document, Section 5 of [RFC3230].
o Status: obsoleted o Status: obsoleted
9.3. Changes Compared to RFC3230 8.3. Changes Compared to RFC3230
The "contentMD5" digest-algorithm token defined in Section 5 of The "contentMD5" digest-algorithm token defined in Section 5 of
[RFC3230] has been added to the HTTP Digest Algorithm Values Registry [RFC3230] has been added to the HTTP Digest Algorithm Values Registry
with the "obsoleted" status. with the "obsoleted" status.
All digest-algorithms defined in [RFC3230] are now "insecure". All digest-algorithms defined in [RFC3230] are now "insecure".
9.4. Changes Compared to RFC5843 8.4. Changes Compared to RFC5843
The digest-algorithm tokens for "MD5", "SHA", "SHA-256", "SHA-512" The digest-algorithm tokens for "MD5", "SHA", "SHA-256", "SHA-512"
have been updated to lowercase. have been updated to lowercase.
The status of "MD5" and "SHA" has been updated to "insecure", and The status of "MD5" and "SHA" has been updated to "insecure", and
their description has been modified accordingly. their description has been modified accordingly.
9.5. Want-Digest Field Registration 8.5. Want-Digest Field Registration
This section registers the "Want-Digest" field in the "Hypertext This section registers the "Want-Digest" field in the "Hypertext
Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS]. Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS].
Field name: "Want-Digest" Field name: "Want-Digest"
Status: permanent Status: permanent
Specification document(s): Section 5 of this document Specification document(s): Section 4 of this document
9.6. Digest Field Registration 8.6. Digest Field Registration
This section registers the "Digest" field in the "Hypertext Transfer This section registers the "Digest" field in the "Hypertext Transfer
Protocol (HTTP) Field Name Registry" [SEMANTICS]. Protocol (HTTP) Field Name Registry" [SEMANTICS].
Field name: "Digest" Field name: "Digest"
Status: permanent Status: permanent
Specification document(s): Section 3 of this document Specification document(s): Section 2 of this document
9.7. Want-Content-Digest Field Registration 8.7. Want-Content-Digest Field Registration
This section registers the "Want-Content-Digest" field in the This section registers the "Want-Content-Digest" field in the
"Hypertext Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS]. "Hypertext Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS].
Field name: "Want-Content-Digest" Field name: "Want-Content-Digest"
Status: permanent Status: permanent
Specification document(s): Section 5 of this document Specification document(s): Section 4 of this document
9.8. Content-Digest Field Registration 8.8. Content-Digest Field Registration
This section registers the "Content-Digest" field in the "Hypertext This section registers the "Content-Digest" field in the "Hypertext
Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS]. Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS].
Field name: "Content-Digest" Field name: "Content-Digest"
Status: permanent Status: permanent
Specification document(s): Section 4 of this document Specification document(s): Section 3 of this document
10. References 9. References
10.1. Normative References 9.1. Normative References
[CMU-836068] [CMU-836068]
Carnagie Mellon University, Software Engineering Carnagie Mellon University, Software Engineering
Institute, "MD5 Vulnerable to collision attacks", December Institute, "MD5 Vulnerable to collision attacks", December
2008, <https://www.kb.cert.org/vuls/id/836068/>. 2008, <https://www.kb.cert.org/vuls/id/836068/>.
[IACR-2020-014] [IACR-2020-014]
Leurent, G. and T. Peyrin, "SHA-1 is a Shambles", January Leurent, G. and T. Peyrin, "SHA-1 is a Shambles", January
2020, <https://eprint.iacr.org/2020/014.pdf>. 2020, <https://eprint.iacr.org/2020/014.pdf>.
skipping to change at page 20, line 31 skipping to change at page 18, line 48
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[SEMANTICS] [SEMANTICS]
Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP
Semantics", draft-ietf-httpbis-semantics-19 (work in Semantics", draft-ietf-httpbis-semantics-19 (work in
progress), September 2021. progress), September 2021.
[UNIX] The Open Group, "The Single UNIX Specification, Version 2 [UNIX] The Open Group, "The Single UNIX Specification, Version 2
- 6 Vol Set for UNIX 98", February 1997. - 6 Vol Set for UNIX 98", February 1997.
10.2. Informative References 9.2. Informative References
[HTTP11] Fielding, R. T., Nottingham, M., and J. Reschke, [HTTP11] Fielding, R. T., Nottingham, M., and J. Reschke,
"HTTP/1.1", draft-ietf-httpbis-messaging-19 (work in "HTTP/1.1", draft-ietf-httpbis-messaging-19 (work in
progress), September 2021. progress), September 2021.
[I-D.ietf-httpbis-header-structure]
Nottingham, M. and P. Kamp, "Structured Field Values for
HTTP", draft-ietf-httpbis-header-structure-19 (work in
progress), June 2020.
[I-D.thomson-http-mice] [I-D.thomson-http-mice]
Thomson, M. and J. Yasskin, "Merkle Integrity Content Thomson, M. and J. Yasskin, "Merkle Integrity Content
Encoding", draft-thomson-http-mice-03 (work in progress), Encoding", draft-thomson-http-mice-03 (work in progress),
August 2018. August 2018.
[NO-MD5] Turner, S. and L. Chen, "Updated Security Considerations [NO-MD5] Turner, S. and L. Chen, "Updated Security Considerations
for the MD5 Message-Digest and the HMAC-MD5 Algorithms", for the MD5 Message-Digest and the HMAC-MD5 Algorithms",
RFC 6151, DOI 10.17487/RFC6151, March 2011, RFC 6151, DOI 10.17487/RFC6151, March 2011,
<https://www.rfc-editor.org/info/rfc6151>. <https://www.rfc-editor.org/info/rfc6151>.
skipping to change at page 21, line 18 skipping to change at page 19, line 28
<https://www.rfc-editor.org/info/rfc6194>. <https://www.rfc-editor.org/info/rfc6194>.
[PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP", [PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, DOI 10.17487/RFC5789, March 2010, RFC 5789, DOI 10.17487/RFC5789, March 2010,
<https://www.rfc-editor.org/info/rfc5789>. <https://www.rfc-editor.org/info/rfc5789>.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
DOI 10.17487/RFC2818, May 2000, DOI 10.17487/RFC2818, May 2000,
<https://www.rfc-editor.org/info/rfc2818>. <https://www.rfc-editor.org/info/rfc2818>.
[RFC6211] Schaad, J., "Cryptographic Message Syntax (CMS) Algorithm
Identifier Protection Attribute", RFC 6211,
DOI 10.17487/RFC6211, April 2011,
<https://www.rfc-editor.org/info/rfc6211>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231, Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014, DOI 10.17487/RFC7231, June 2014,
<https://www.rfc-editor.org/info/rfc7231>. <https://www.rfc-editor.org/info/rfc7231>.
[RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396,
DOI 10.17487/RFC7396, October 2014, DOI 10.17487/RFC7396, October 2014,
<https://www.rfc-editor.org/info/rfc7396>. <https://www.rfc-editor.org/info/rfc7396>.
[RFC7696] Housley, R., "Guidelines for Cryptographic Algorithm [RFC7696] Housley, R., "Guidelines for Cryptographic Algorithm
Agility and Selecting Mandatory-to-Implement Algorithms", Agility and Selecting Mandatory-to-Implement Algorithms",
BCP 201, RFC 7696, DOI 10.17487/RFC7696, November 2015, BCP 201, RFC 7696, DOI 10.17487/RFC7696, November 2015,
<https://www.rfc-editor.org/info/rfc7696>. <https://www.rfc-editor.org/info/rfc7696>.
[RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP
APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
<https://www.rfc-editor.org/info/rfc7807>. <https://www.rfc-editor.org/info/rfc7807>.
10.3. URIs [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for
HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,
[1] https://lists.w3.org/Archives/Public/ietf-http-wg/ <https://www.rfc-editor.org/info/rfc8941>.
[2] https://github.com/httpwg/http-extensions 9.3. URIs
[3] https://www.iana.org/assignments/http-dig-alg/ [1] https://www.iana.org/assignments/http-dig-alg/
[4] https://www.iana.org/assignments/http-dig-alg/ [2] https://www.iana.org/assignments/http-dig-alg/
[5] https://www.iana.org/assignments/http-dig-alg/ [3] https://www.iana.org/assignments/http-dig-alg/
[6] https://github.com/httpwg/http-core/ [4] https://github.com/httpwg/http-core/
issues/313#issuecomment-584389706 issues/313#issuecomment-584389706
Appendix A. Resource Representation and Representation-Data Appendix A. Resource Representation and Representation-Data
The following examples show how representation metadata, payload The following examples show how representation metadata, payload
transformations and method impacts on the message and content. When transformations and method impacts on the message and content. When
the content contains non-printable characters (e.g. when it is the content contains non-printable characters (e.g. when it is
compressed) it is shown as a Base64-encoded string. compressed) it is shown as a Base64-encoded string.
PUT /entries/1234 HTTP/1.1 PUT /entries/1234 HTTP/1.1
skipping to change at page 28, line 8 skipping to change at page 26, line 30
sha-512=pxo7aYzcGI88pnDnoSmAnaOEVys0MABhgvHY9+VI+ElE6 sha-512=pxo7aYzcGI88pnDnoSmAnaOEVys0MABhgvHY9+VI+ElE6
0jBCwnMPyA/s3NF3ZO5oIWA7lf8ukk+\n5KJzm3p5og== 0jBCwnMPyA/s3NF3ZO5oIWA7lf8ukk+\n5KJzm3p5og==
iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw==
Response with Digest of Encoded Content Response with Digest of Encoded Content
B.7. POST Response does not Reference the Request URI B.7. POST Response does not Reference the Request URI
The request "Digest" field-value is computed on the enclosed The request "Digest" field-value is computed on the enclosed
representation (see Section 7). representation (see Section 6).
The representation enclosed in the response refers to the resource The representation enclosed in the response refers to the resource
identified by "Content-Location" (see Section 6.4.2 of [SEMANTICS]). identified by "Content-Location" (see Section 6.4.2 of [SEMANTICS]).
"Digest" is thus computed on the enclosed representation. "Digest" is thus computed on the enclosed representation.
POST /books HTTP/1.1 POST /books HTTP/1.1
Host: foo.example Host: foo.example
Content-Type: application/json Content-Type: application/json
Accept: application/json Accept: application/json
Accept-Encoding: identity Accept-Encoding: identity
skipping to change at page 28, line 45 skipping to change at page 27, line 25
Response with Digest of Resource Response with Digest of Resource
Note that a "204 No Content" response without content but with the Note that a "204 No Content" response without content but with the
same "Digest" field-value would have been legitimate too. In that same "Digest" field-value would have been legitimate too. In that
case, "Content-Digest" would have been computed on an empty content. case, "Content-Digest" would have been computed on an empty content.
B.8. POST Response Describes the Request Status B.8. POST Response Describes the Request Status
The request "Digest" field-value is computed on the enclosed The request "Digest" field-value is computed on the enclosed
representation (see Section 7). representation (see Section 6).
The representation enclosed in the response describes the status of The representation enclosed in the response describes the status of
the request, so "Digest" is computed on that enclosed representation. the request, so "Digest" is computed on that enclosed representation.
Response "Digest" has no explicit relation with the resource Response "Digest" has no explicit relation with the resource
referenced by "Location". referenced by "Location".
POST /books HTTP/1.1 POST /books HTTP/1.1
Host: foo.example Host: foo.example
Content-Type: application/json Content-Type: application/json
skipping to change at page 32, line 37 skipping to change at page 31, line 21
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
{"hello": "world"} {"hello": "world"}
Response with Different Algorithm Response with Different Algorithm
C.2. Server Selects Algorithm Unsupported by Client C.2. Server Selects Algorithm Unsupported by Client
The client requests a only "sha" digest because that is the only The client requests a "sha" digest because that is the only algorithm
algorithm it supports. The server is not obliged to produce a it supports. The server is not obliged to produce a response
response containing a "sha" digest, it instead uses a different containing a "sha" digest, it instead uses a different algorithm.
algorithm.
GET /items/123 HTTP/1.1 GET /items/123 HTTP/1.1
Host: foo.example Host: foo.example
Want-Digest: sha;q=1 Want-Digest: sha;q=1
GET Request with Want-Digest GET Request with Want-Digest
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Digest: sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm Digest: sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm
skipping to change at page 34, line 22 skipping to change at page 33, line 4
FAQ FAQ
_RFC Editor: Please remove this section before publication._ _RFC Editor: Please remove this section before publication._
1. Why remove all references to content-md5? 1. Why remove all references to content-md5?
Those were unnecessary to understanding and using this Those were unnecessary to understanding and using this
specification. specification.
2. Why remove references to instance manipulation? 2. Why remove references to instance manipulation?
Those were unnecessary for correctly using and applying the Those were unnecessary for correctly using and applying the
specification. An example with Range Request is more than specification. An example with Range Request is more than
enough. This document uses the term "partial representation" enough. This document uses the term "partial representation"
which should group all those cases. which should group all those cases.
3. How to use "Digest" with "PATCH" method? 3. How to use "Digest" with "PATCH" method?
See Section 7. See Section 6.
4. Why remove references to delta-encoding? 4. Why remove references to delta-encoding?
Unnecessary for a correct implementation of this specification. Unnecessary for a correct implementation of this specification.
The revised specification can be nicely adapted to "delta The revised specification can be nicely adapted to "delta
encoding", but all the references here to delta encoding don't encoding", but all the references here to delta encoding don't
add anything to this RFC. Another job would be to refresh delta add anything to this RFC. Another job would be to refresh delta
encoding. encoding.
5. Why remove references to Digest Authentication? 5. Why remove references to Digest Authentication?
This specification seems to me completely unrelated to Digest This specification seems to me completely unrelated to Digest
Authentication but for the word "Digest". Authentication but for the word "Digest".
6. What changes in "Want-Digest"? 6. What changes in "Want-Digest"?
The contentMD5 token defined in Section 5 of [RFC3230] is The contentMD5 token defined in Section 5 of [RFC3230] is
deprecated by this document. deprecated by this document.
To clarify that "Digest" and "Want-Digest" can be used in both
requests and responses - [RFC3230] carefully uses "sender" and
"receiver" in their definition - we added examples on using
"Want-Digest" in responses to advertise the supported digest-
algorithms and the inability to accept requests with unsupported
digest-algorithms.
7. Does this specification change supported algorithms? 7. Does this specification change supported algorithms?
Yes. This RFC updates [RFC5843] which is still delegated for all Yes. This RFC updates [RFC5843] which is still delegated for all
algorithms updates. To simplify a future transition to algorithms updates. To simplify a future transition to
Structured Fields [I-D.ietf-httpbis-header-structure] we suggest Structured Fields [RFC8941] we suggest to use lowercase for
to use lowercase for digest-algorithms. digest-algorithms.
8. What about mid-stream trailer fields? 8. What about mid-stream trailer fields?
While mid-stream trailer fields [6] are interesting, since this While mid-stream trailer fields [4] are interesting, since this
specification is a rewrite of [RFC3230] we do not think we should specification is a rewrite of [RFC3230] we do not think we should
face that. As a first thought, nothing in this document face that. As a first thought, nothing in this document
precludes future work that would find a use for mid-stream precludes future work that would find a use for mid-stream
trailers, for example an incremental digest-algorithm. A trailers with specific algorithms. A document defining such a
document defining such a digest-algorithm is best positioned to digest-algorithm is best positioned to describe how it is used.
describe how it is used.
Code Samples Code Samples
_RFC Editor: Please remove this section before publication._ _RFC Editor: Please remove this section before publication._
How can I generate and validate the "Digest" values shown in the How can I generate and validate the "Digest" values shown in the
examples throughout this document? examples throughout this document?
The following python3 code can be used to generate digests for JSON The following python3 code can be used to generate digests for JSON
objects using SHA algorithms for a range of encodings. Note that objects using SHA algorithms for a range of encodings. Note that
these are formatted as base64. This function could be adapted to these are formatted as base64. This function could be adapted to
other algorithms and should take into account their specific other algorithms and should take into account their specific
formatting rules. formatting rules.
import base64, json, hashlib, brotli, logging import base64, json, hashlib, brotli, logging
 End of changes. 104 change blocks. 
266 lines changed or deleted 180 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/