draft-ietf-httpbis-digest-headers-01.txt   draft-ietf-httpbis-digest-headers-02.txt 
HTTP R. Polli HTTP R. Polli
Internet-Draft Team Digitale, Italian Government Internet-Draft Team Digitale, Italian Government
Intended status: Standards Track L. Pardue Intended status: Standards Track L. Pardue
Expires: May 6, 2020 Cloudflare Expires: September 10, 2020 Cloudflare
November 03, 2019 March 09, 2020
Digest Headers Digest Headers
draft-ietf-httpbis-digest-headers-01 draft-ietf-httpbis-digest-headers-02
Abstract Abstract
This document defines the Digest and Want-Digest header fields for This document defines the Digest and Want-Digest header fields for
HTTP, thus allowing client and server to negotiate an integrity HTTP, thus allowing client and server to negotiate an integrity
checksum of the exchanged resource representation data. checksum of the exchanged resource representation data.
This document obsoletes RFC 3230. It replaces the term "instance" This document obsoletes RFC 3230. It replaces the term "instance"
with "representation", which makes it consistent with the HTTP with "representation", which makes it consistent with the HTTP
Semantic and Context defined in RFC 7231. Semantic and Context defined in RFC 7231.
skipping to change at page 1, line 48 skipping to change at page 1, line 48
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 6, 2020. This Internet-Draft will expire on September 10, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2020 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 Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. A Brief History of Integrity Header Fields . . . . . . . 4 1.1. A Brief History of Integrity Header Fields . . . . . . . 4
1.2. This Proposal . . . . . . . . . . . . . . . . . . . . . . 4 1.2. This Proposal . . . . . . . . . . . . . . . . . . . . . . 4
1.3. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4. Notational Conventions . . . . . . . . . . . . . . . . . 5 1.4. Notational Conventions . . . . . . . . . . . . . . . . . 5
2. Resource Representation and Representation-Data . . . . . . . 6 2. Representation Digest . . . . . . . . . . . . . . . . . . . . 6
3. Digest Algorithm Values . . . . . . . . . . . . . . . . . . . 7 3. The Digest Header Field . . . . . . . . . . . . . . . . . . . 6
3.1. Representation Digest . . . . . . . . . . . . . . . . . . 9 4. The Want-Digest Header Field . . . . . . . . . . . . . . . . 7
3.1.1. digest-algorithm Encoding Examples . . . . . . . . . 10 5. Digest Algorithm Values . . . . . . . . . . . . . . . . . . . 8
4. Header Field Specifications . . . . . . . . . . . . . . . . . 10 6. Use of Digest when acting on resources . . . . . . . . . . . 10
4.1. Want-Digest . . . . . . . . . . . . . . . . . . . . . . . 10 6.1. Digest and PATCH . . . . . . . . . . . . . . . . . . . . 11
4.2. Digest . . . . . . . . . . . . . . . . . . . . . . . . . 10 7. Deprecate Negotiation of Content-MD5 . . . . . . . . . . . . 11
5. Use of Digest when acting on resources . . . . . . . . . . . 11 8. Relationship to Subresource Integrity (SRI) . . . . . . . . . 11
5.1. Digest and PATCH . . . . . . . . . . . . . . . . . . . . 12 8.1. Supporting Both SRI and Representation Digest . . . . . . 12
6. Deprecate Negotiation of Content-MD5 . . . . . . . . . . . . 12 9. Examples of Unsolicited Digest . . . . . . . . . . . . . . . 13
7. Broken Cryptographic Algorithms . . . . . . . . . . . . . . . 12 9.1. Server Returns Full Representation Data . . . . . . . . . 13
8. Relationship to Subresource Integrity (SRI) . . . . . . . . . 13 9.2. Server Returns No Representation Data . . . . . . . . . . 13
8.1. Supporting Both SRI and Representation Digest . . . . . . 14 9.3. Server Returns Partial Representation Data . . . . . . . 13
9. Examples of Unsolicited Digest . . . . . . . . . . . . . . . 14 9.4. Client and Server Provide Full Representation Data . . . 14
9.1. Server Returns Full Representation Data . . . . . . . . . 14
9.2. Server Returns No Representation Data . . . . . . . . . . 15
9.3. Server Returns Partial Representation Data . . . . . . . 15
9.4. Client and Server Provide Full Representation Data . . . 15
9.5. Client Provides Full Representation Data, Server Provides 9.5. Client Provides Full Representation Data, Server Provides
No Representation Data . . . . . . . . . . . . . . . . . 16 No Representation Data . . . . . . . . . . . . . . . . . 15
9.6. Client and Server Provide Full Representation Data, 9.6. Client and Server Provide Full Representation Data,
Client Uses id-sha-256. . . . . . . . . . . . . . . . . . 17 Client Uses id-sha-256. . . . . . . . . . . . . . . . . . 15
9.7. POST Response does not Reference the Request URI . . . . 17 9.7. POST Response does not Reference the Request URI . . . . 16
9.8. POST Response Describes the Request Status . . . . . . . 18 9.8. POST Response Describes the Request Status . . . . . . . 17
9.9. Digest with PATCH . . . . . . . . . . . . . . . . . . . . 19 9.9. Digest with PATCH . . . . . . . . . . . . . . . . . . . . 17
9.10. Error responses . . . . . . . . . . . . . . . . . . . . . 18
10. Examples of Want-Digest Solicited Digest . . . . . . . . . . 19 10. Examples of Want-Digest Solicited Digest . . . . . . . . . . 19
10.1. Server Selects Client's Least Preferred Algorithm . . . 20 10.1. Server Selects Client's Least Preferred Algorithm . . . 19
10.2. Server Selects Algorithm Unsupported by Client . . . . . 20 10.2. Server Selects Algorithm Unsupported by Client . . . . . 20
10.3. Server Does Not Support Client Algorithm and Returns an 10.3. Server Does Not Support Client Algorithm and Returns an
Error . . . . . . . . . . . . . . . . . . . . . . . . . 20 Error . . . . . . . . . . . . . . . . . . . . . . . . . 20
11. Security Considerations . . . . . . . . . . . . . . . . . . . 21 11. Security Considerations . . . . . . . . . . . . . . . . . . . 20
11.1. Digest Does Not Protect the Full HTTP Message . . . . . 21 11.1. Digest Does Not Protect the Full HTTP Message . . . . . 20
11.2. Broken Cryptographic Algorithms . . . . . . . . . . . . 21 11.2. Broken Cryptographic Algorithms . . . . . . . . . . . . 21
11.3. Other Deprecated Algorithms . . . . . . . . . . . . . . 21 11.3. Other Deprecated Algorithms . . . . . . . . . . . . . . 21
11.4. Digest for End-to-End Integrity . . . . . . . . . . . . 21 11.4. Digest for End-to-End Integrity . . . . . . . . . . . . 21
11.5. Usage in Signatures . . . . . . . . . . . . . . . . . . 22 11.5. Digest and Content-Location in responses . . . . . . . . 21
11.6. Message Truncation . . . . . . . . . . . . . . . . . . . 22 11.6. Usage in signatures . . . . . . . . . . . . . . . . . . 21
11.7. Algorithm Agility . . . . . . . . . . . . . . . . . . . 22 11.7. Message Truncation . . . . . . . . . . . . . . . . . . . 22
11.8. Algorithm Agility . . . . . . . . . . . . . . . . . . . 22
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22
12.1. Establish the HTTP Digest Algorithm Values . . . . . . . 22 12.1. Establish the HTTP Digest Algorithm Values . . . . . . . 22
12.2. The "status" Field in the HTTP Digest Algorithm Values . 23 12.2. The "status" Field in the HTTP Digest Algorithm Values . 22
12.3. Deprecate "MD5" Digest Algorithm . . . . . . . . . . . . 23 12.3. Deprecate "MD5" Digest Algorithm . . . . . . . . . . . . 23
12.4. Update "CRC32C" Digest Algorithm . . . . . . . . . . . . 23 12.4. Update "CRC32C" Digest Algorithm . . . . . . . . . . . . 23
12.5. Obsolete "SHA" Digest Algorithm . . . . . . . . . . . . 23 12.5. Obsolete "SHA" Digest Algorithm . . . . . . . . . . . . 23
12.6. Obsolete "ADLER32" Digest Algorithm . . . . . . . . . . 24 12.6. Obsolete "ADLER32" Digest Algorithm . . . . . . . . . . 23
12.7. The "ID-SHA-256" Digest Algorithm . . . . . . . . . . . 24 12.7. The "ID-SHA-256" Digest Algorithm . . . . . . . . . . . 24
12.8. The "ID-SHA-512" Digest Algorithm . . . . . . . . . . . 24 12.8. The "ID-SHA-512" Digest Algorithm . . . . . . . . . . . 24
12.9. Changes compared to RFC5843 . . . . . . . . . . . . . . 24 12.9. Changes compared to RFC5843 . . . . . . . . . . . . . . 24
12.10. Want-Digest Header Field Registration . . . . . . . . . 25 12.10. Want-Digest Header Field Registration . . . . . . . . . 25
12.11. Digest Header Field Registration . . . . . . . . . . . . 25 12.11. Digest Header Field Registration . . . . . . . . . . . . 25
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 25
13.1. Normative References . . . . . . . . . . . . . . . . . . 25 13.1. Normative References . . . . . . . . . . . . . . . . . . 25
13.2. Informative References . . . . . . . . . . . . . . . . . 28 13.2. Informative References . . . . . . . . . . . . . . . . . 27
13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 28 13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Appendix A. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 28 Appendix A. Resource Representation and Representation-Data . . 28
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 29 Appendix B. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 30
Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 31
Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 31
D.1. Since draft-ietf-httpbis-digest-headers-00 . . . . . . . 30 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 E.1. Since draft-ietf-httpbis-digest-headers-00 . . . . . . . 32
E.2. Since draft-ietf-httpbis-digest-headers-01 . . . . . . . 33
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33
1. Introduction 1. Introduction
The core specification of HTTP does not define a means to protect the The core specification of HTTP does not define a means to protect the
integrity of resources. When HTTP messages are transferred between integrity of resources. 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].
However, there are cases where relying on this alone is insufficient. However, there are cases where relying on this alone is insufficient.
skipping to change at page 6, line 8 skipping to change at page 6, line 8
[RFC7230]. [RFC7230].
The definitions "representation", "selected representation", The definitions "representation", "selected representation",
"representation data", "representation metadata", and "payload body" "representation data", "representation metadata", and "payload body"
in this document are to be interpreted as described in [RFC7230] and in this document are to be interpreted as described in [RFC7230] and
[RFC7231]. [RFC7231].
The definition "validator" in this document is to be interpreted as The definition "validator" in this document is to be interpreted as
described in Section 7.2 of [RFC7231]. described in Section 7.2 of [RFC7231].
2. Resource Representation and Representation-Data 2. Representation Digest
To avoid inconsistencies, an integrity mechanism for HTTP messages The representation digest is an integrity mechanism for HTTP
should decouple the checksum calculation from: resources which uses a checksum that is calculated independently of
the payload body and message body. It uses the representation data
(see [RFC7231]), that can be fully or partially contained in the
message body, or not contained at all:
o the payload body - which may be altered by mechanism like Range representation-data := Content-Encoding( Content-Type( bits ) )
Requests [RFC7233] or the method (eg. HEAD);
o and the message body - which depends on "Transfer-Encoding" and This takes into account the effect of the HTTP semantics on the
whatever transformations the intermediaries may apply. messages; for example the payload body can be affected by Range
Requests or methods such as HEAD, while the message body is dependent
on transfer codings and other transformations: Appendix A contains
several examples to help illustrate those effects.
The following examples show how representation metadata, payload A representation digest consists of the value of a checksum computed
transformations and method impacts on the message and payload body. on the entire selected "representation data" of a resource together
with an indication of the algorithm used (and any parameters)
Here is a gzip-compressed json object representation-data-digest = digest-algorithm "="
<encoded digest output>
Request: The checksum is computed using one of the "digest-algorithms" listed
in Section 5 and then encoded in the associated format.
PUT /entries/1234 HTTP/1.1 The example below shows the "sha-256" digest-algorithm which uses
Content-Type: application/json base64 encoding.
Content-Encoding: gzip
H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
Now the same payload body conveys a malformed json object. 3. The Digest Header Field
Request: The Digest header field contains a list of one or more representation
digest values as defined in Section 2. It can be used in both
request and response.
PUT /entries/1234 HTTP/1.1 Digest = "Digest" ":" OWS 1#representation-data-digest
Content-Type: application/json
H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= The resource is specified by the effective request URI and any
"validator" contained in the message.
A Range-Request alters the payload body, conveying a partial The relationship between Content-Location (see [RFC7231]
representation. Section 3.1.4.2) and Digest is demonstrated in Section 9.7. A
comprehensive set of examples showing the impacts of representation
metadata, payload transformations and HTTP methods on digest is
provided in Section 9 and Section 10.
Request: A Digest header field MAY contain multiple representation-data-digest
values. This could be useful for responses expected to reside in
caches shared by users with different browsers, for example.
GET /entries/1234 HTTP/1.1 A recipient MAY ignore any or all of the representation-data-digests
Range: bytes=1-7 in a Digest header field. This allows the recipient to choose which
digest-algorithm(s) to use for validation instead of verifying every
received representation-data-digest.
Response: A sender MAY send a representation-data-digest using a digest-
algorithm without knowing whether the recipient supports the digest-
algorithm, or even knowing that the recipient will ignore it.
HTTP/1.1 206 Partial Content Two examples of its use are
Content-Encoding: gzip
Content-Type: application/json
Content-Range: bytes 1-7/18
iwgAla3RXA== Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm
AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==
Now the method too alters the payload body. Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=,
id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
Request: 4. The Want-Digest Header Field
HEAD /entries/1234 HTTP/1.1 The Want-Digest message header field indicates the sender's desire to
Accept: application/json receive a representation digest on messages associated with the
Accept-Encoding: gzip request URI and representation metadata.
Response: Want-Digest = "Want-Digest" ":" OWS 1#want-digest-value
want-digest-value = digest-algorithm [ ";" "q" "=" qvalue]
qvalue = ( "0" [ "." 0*1DIGIT ] ) /
( "1" [ "." 0*1( "0" ) ] )
HTTP/1.1 200 OK If a digest-algorithm is not accompanied by a qvalue, it is treated
Content-Type: application/json as if its associated qvalue were 1.0.
Content-Encoding: gzip
3. Digest Algorithm Values The sender is willing to accept a digest-algorithm if and only if it
is listed in a Want-Digest header field of a message, and its qvalue
is non-zero.
If multiple acceptable digest-algorithm values are given, the
sender's preferred digest-algorithm is the one (or ones) with the
highest qvalue.
Two examples of its use are
Want-Digest: sha-256
Want-Digest: SHA-512;q=0.3, sha-256;q=1, md5;q=0
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. For some algorithms, one or more parameters may be computation. For some algorithms, one or more parameters can be
supplied. supplied.
digest-algorithm = token digest-algorithm = token
The BNF for "parameter" is as is used in [RFC7230]. All digest- The BNF for "parameter" is as is used in [RFC7230]. All digest-
algorithm values are case-insensitive. algorithm values are case-insensitive.
The Internet Assigned Numbers Authority (IANA) acts as a registry for The Internet Assigned Numbers Authority (IANA) acts as a registry for
digest-algorithm values. The registry contains the following tokens. digest-algorithm values. The registry contains the tokens listed
below.
SHA-256: Some algorithms, although registered, have since been found
vulnerable: the MD5 algorithm MUST NOT be used due to collision
attacks [CMU-836068] and the SHA algorithm is NOT RECOMMENDED due to
collision attacks [IACR-2019-459].
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 the base64 encoding [RFC4648].
* Reference: [RFC6234], [RFC4648], this document. * Reference: [RFC6234], [RFC4648], this document.
* Status: standard * Status: standard
SHA-512: 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 the base64 encoding [RFC4648].
* Reference: [RFC6234], [RFC4648], this document. * Reference: [RFC6234], [RFC4648], this document.
* Status: standard * Status: standard
MD5: MD5
* Description: The MD5 algorithm, as specified in [RFC1321]. The * Description: The MD5 algorithm, as specified in [RFC1321]. The
output of this algorithm is encoded using the base64 encoding output of this algorithm is encoded using the base64 encoding
[RFC4648]. The MD5 algorithm MUST NOT be used as it's now [RFC4648]. The MD5 algorithm MUST NOT be used as it's now
vulnerable to collision attacks [CMU-836068]. vulnerable to collision attacks [CMU-836068].
* Reference: [RFC1321], [RFC4648], this document. * Reference: [RFC1321], [RFC4648], this document.
* Status: deprecated * Status: deprecated
SHA: 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]. The algorithm is encoded using the base64 encoding [RFC4648]. The
SHA algorithm is NOT RECOMMENDED as it's now vulnerable to SHA algorithm is NOT RECOMMENDED as it's now vulnerable to
collision attacks [IACR-2019-459]. collision attacks [IACR-2019-459].
* Reference: [RFC3174], [RFC6234], [RFC4648], this document. * Reference: [RFC3174], [RFC6234], [RFC4648], this document.
* Status: obsoleted * Status: obsoleted
UNIXsum: UNIXsum
* Description: The algorithm computed by the UNIX "sum" command, * Description: The algorithm computed by the UNIX "sum" command,
as defined by the Single UNIX Specification, Version 2 [UNIX]. as defined by the Single UNIX Specification, Version 2 [UNIX].
The output of this algorithm is an ASCII decimal-digit string The output of this algorithm is an ASCII decimal-digit string
representing the 16-bit checksum, which is the first word of representing the 16-bit checksum, which is the first 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: standard * Status: standard
UNIXcksum: UNIXcksum
* Description: The algorithm computed by the UNIX "cksum" * Description: The algorithm computed by the UNIX "cksum"
command, as defined by the Single UNIX Specification, Version 2 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: standard * Status: standard
To allow sender and recipient to provide a checksum which is To allow sender and recipient to provide a checksum which is
independent from "Content-Encoding", the following additional independent from "Content-Encoding", the following additional
algorithms are defined: algorithms are defined:
ID-SHA-512: ID-SHA-512
* Description: The sha-512 digest of the representation-data of * Description: The sha-512 digest of the representation-data of
the resource when no content coding is applied (eg. "Content- the resource when no content coding is applied (eg. "Content-
Encoding: identity") Encoding: identity")
* Reference: [RFC6234], [RFC4648], this document. * Reference: [RFC6234], [RFC4648], this document.
* Status: standard * Status: standard
ID-SHA-256: ID-SHA-256
* Description: The sha-256 digest of the representation-data of * Description: The sha-256 digest of the representation-data of
the resource when no content coding is applied (eg. "Content- the resource when no content coding is applied (eg. "Content-
Encoding: identity") Encoding: identity")
* Reference: [RFC6234], [RFC4648], this document. * Reference: [RFC6234], [RFC4648], this document.
* Status: standard * Status: standard
If other digest-algorithm values are defined, the associated encoding If other digest-algorithm values are defined, the associated encoding
MUST either be represented as a quoted string, or MUST NOT include MUST either be represented as a quoted string, or MUST NOT include
";" or "," in the character sets used for the encoding. ";" or "," in the character sets used for the encoding.
3.1. Representation Digest 6. Use of Digest when acting on resources
A representation digest is the value of the output of a digest
algorithm, together with an indication of the algorithm used (and any
parameters).
representation-data-digest = digest-algorithm "="
<encoded digest output>
As explained in Section 2 the digest is computed on the entire
selected "representation data" of the resource defined in [RFC7231]:
representation-data := Content-Encoding( Content-Type( bits ) )
The encoded digest output uses the encoding format defined for the
specific digest-algorithm.
3.1.1. digest-algorithm Encoding Examples
The "sha-256" digest-algorithm uses base64 encoding. Note that
digest-algorithm values are case insensitive.
sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
The "UNIXsum" digest-algorithm uses ASCII string of decimal digits.
UNIXsum=30637
4. Header Field Specifications
The following headers are defined
4.1. Want-Digest
The Want-Digest message header field indicates the sender's desire to
receive a representation digest on messages associated with the
request URI and representation metadata.
Want-Digest = "Want-Digest" ":" OWS 1#want-digest-value
want-digest-value = digest-algorithm [ ";" "q" "=" qvalue]
qvalue = ( "0" [ "." 0*1DIGIT ] ) / ( "1" [ "." 0*1( "0" ) ] )
If a digest-algorithm is not accompanied by a qvalue, it is treated
as if its associated qvalue were 1.0.
The sender is willing to accept a digest-algorithm if and only if it
is listed in a Want-Digest header field of a message, and its qvalue
is non-zero.
If multiple acceptable digest-algorithm values are given, the
sender's preferred digest-algorithm is the one (or ones) with the
highest qvalue.
Two examples of its use are
Want-Digest: sha-256
Want-Digest: SHA-512;q=0.3, sha-256;q=1, md5;q=0
4.2. Digest
The Digest header field provides a digest of the representation data.
Digest = "Digest" ":" OWS 1#representation-data-digest
"Representation data" might be:
o fully contained in the message body,
o partially-contained in the message body,
o or not at all contained in the message body.
The resource is specified by the effective request URI and any
"validator" contained in the message.
For example, in a response to a HEAD request, the digest is
calculated using the representation data that would have been
enclosed in the payload body if the same request had been a GET.
Digest can be used in requests too.
The "Digest" value depends on the representation metadata.
A Digest header field MAY contain multiple representation-data-digest
values. This could be useful for responses expected to reside in
caches shared by users with different browsers, for example.
A recipient MAY ignore any or all of the representation-data-digests
in a Digest header field. This allows the recipient to chose which
digest-algorithm(s) to use for validation instead of verifying every
received representation-data-digest.
A sender MAY send a representation-data-digest using a digest-
algorithm without knowing whether the recipient supports the digest-
algorithm, or even knowing that the recipient will ignore it.
Two examples of its use are
Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==
Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
5. Use of Digest when acting on resources
POST and PATCH requests may appear to convey partial representations POST and PATCH requests can appear to convey partial representations
but are semantically acting on resources. The enclosed but are semantically acting on resources. The enclosed
representation, including its metadata refers to that action. representation, including its metadata refers to that action.
In these requests the representation digest MUST be computed on the In these requests the representation digest MUST be computed on the
representation-data of that action. representation-data of that action. This is the only possible choice
because representation digest requires complete representation
This is the only possible choice because representation digest metadata (see Section 2).
requires complete representation metadata (see Section 3.1).
In responses, In responses,
o if the representation describes the status of the request, o if the representation describes the status of the request,
"Digest" MUST be computed on the enclosed representation (see "Digest" MUST be computed on the enclosed representation (see
Section 9.8 ); Section 9.8 );
o if there is a referenced resource "Digest" MUST be computed on the o if there is a referenced resource "Digest" MUST be computed on the
selected representation of the referenced resource even if that is selected representation of the referenced resource even if that is
different from the target resource. That may or may not result in different from the target resource. That might or might not
computing "Digest" on the enclosed representation. result in computing "Digest" on the enclosed representation.
The latter case might be done accordingly to the HTTP semantics of
the given method, for example using the "Content-Location" header
field.
Differently from "Content-Location", which is representation The latter case might be done according to the HTTP semantics of the
metadata, the "Location" header field does not affect "Digest". given method, for example using the "Content-Location" header field.
In contrast, the "Location" header field does not affect "Digest"
because it is not representation metadata.
5.1. Digest and PATCH 6.1. Digest and PATCH
In PATCH requests the representation digest MUST be computed on the In PATCH requests the representation digest MUST be computed on the
patch document. patch document because the representation metadata refers to the
patch document and not to the target resource (see Section 2 of
This is because the representation metadata refers to the patch [RFC5789]).
document and not to the target resource (see Section 2 of [RFC5789]).
In PATCH responses the representation digest MUST be computed on the In PATCH responses the representation digest MUST be computed on the
selected representation of the patched resource. selected representation of the patched resource.
"Digest" usage with PATCH is thus very similar to the POST one, but "Digest" usage with PATCH is thus very similar to the POST one, but
with the resource's own semantic partly implied by the method and by with the resource's own semantic partly implied by the method and by
the patch document. the patch document.
6. Deprecate Negotiation of Content-MD5 7. Deprecate Negotiation of Content-MD5
This RFC deprecates the negotiation of Content-MD5 as it has been This RFC deprecates the negotiation of Content-MD5 as it has been
obsoleted by [RFC7231] obsoleted by [RFC7231].
7. Broken Cryptographic Algorithms
The MD5 algorithm MUST NOT be used as it has been found vulnerable to
collision attacks [CMU-836068].
The SHA algorithm is NOT RECOMMENDED as it has been found vulnerable
to collision attacks [IACR-2019-459].
8. Relationship to Subresource Integrity (SRI) 8. Relationship to Subresource Integrity (SRI)
Subresource Integrity [SRI] is an integrity mechanism that shares Subresource Integrity [SRI] is an integrity mechanism that shares
some similarities to the present document's mechanism. However, some similarities to the present document's mechanism. However,
there are differences in motivating factors, threat model and there are differences in motivating factors, threat model and
specification of integrity digest generation, signalling and specification of integrity digest generation, signalling and
validation. validation.
SRI allows a first-party authority to declare an integrity assertion SRI allows a first-party authority to declare an integrity assertion
on a resource served by a first or third party authority. This is on a resource served by a first or third party authority. This is
done via the "integrity" attribute that can added to "script" or done via the "integrity" attribute that can be added to "script" or
"link" HTML elements. Therefore, the integrity assertion is always "link" HTML elements. Therefore, the integrity assertion is always
made out-of-band to the resource fetch. In contrast, the "Digest" made out-of-band to the resource fetch. In contrast, the "Digest"
header field is supplied in-band alongside the selected header field is supplied in-band alongside the selected
representation, meaning that an authority can only declare an representation, meaning that an authority can only declare an
integrity assertion for itself. Methods to improve the security integrity assertion for itself. Methods to improve the security
properties of representation digests are presented in Section 11. properties of representation digests are presented in Section 11.
This contrast is interesting because on one hand self-assertion is This contrast is interesting because on one hand self-assertion is
less likely to be affected by coordination problems such as the less likely to be affected by coordination problems such as the
first-party holding stale information about the third party, but on first-party holding stale information about the third party, but on
the other hand the self-assertion is only as trustworthy as the the other hand the self-assertion is only as trustworthy as the
authority that provided it. authority that provided it.
The SRI "integrity" attribute contains a cryptographic hash algorithm The SRI "integrity" attribute contains a cryptographic hash algorithm
and digest value which is similar to "representation-data-digest" and digest value which is similar to "representation-data-digest"
(see Section 3.1). The major differences are in serialization (see Section 2). The major differences are in serialization format.
format.
The SRI digest value is calculated over the identity encoding of the The SRI digest value is calculated over the identity encoding of the
resource, not the selected representation (as specified for resource, not the selected representation (as specified for
"representation-data-digest" in this document). Section 3.4.5 of "representation-data-digest" in this document). Section 3.4.5 of
[SRI] describes the benefit of the identity approach - the SRI [SRI] describes the benefit of the identity approach - the SRI
"integrity" attribute can contain multiple algorithm-value pairs "integrity" attribute can contain multiple algorithm-value pairs
where each applies to a different identity encoded payload. This where each applies to a different identity encoded payload. This
allows for protection of distinct resources sharing a URL. However, allows for protection of distinct resources sharing a URL. However,
this is a contrast to the design of representation digests, where this is a contrast to the design of representation digests, where
multiple "Digest" field-values all protect the same representation. multiple "Digest" field-values all protect the same representation.
skipping to change at page 14, line 11 skipping to change at page 12, line 34
SRI specifies strong requirements on the selection of algorithm for SRI specifies strong requirements on the selection of algorithm for
generation and validation of digests. In contrast, the requirements generation and validation of digests. In contrast, the requirements
in this document are weaker. in this document are weaker.
SRI defines no method for a client to declare an integrity assertion SRI defines no method for a client to declare an integrity assertion
on resources it transfers to a server. In contrast, the "Digest" on resources it transfers to a server. In contrast, the "Digest"
header field can appear on requests. header field can appear on requests.
8.1. Supporting Both SRI and Representation Digest 8.1. Supporting Both SRI and Representation Digest
The SRI and Representation Digest mechanism are different and The SRI and Representation Digest mechanisms are different and
complementary but one is not capable of replacing the other because complementary but one is not capable of replacing the other because
they have have different threat, security and implementation they have different threat, security and implementation properties.
properties.
A user agent that supports both mechanisms is expected to apply the A user agent that supports both mechanisms is expected to apply the
rules specified for each but since the two mechanisms are rules specified for each but since the two mechanisms are
independent, the ordering is not important. However, a user agent independent, the ordering is not important. However, a user agent
supporting both could benefit from performing representation digest supporting both could benefit from performing representation digest
validation first because the it does not require a conversion to into validation first because it does not always require a conversion into
identity encoding. identity encoding.
There is a chance that a user agent supporting both mechanisms may There is a chance that a user agent supporting both mechanisms may
find one validates successfully while the other fails. This document find one validates successfully while the other fails. This document
specifies no requirements or guidance for user agents that experience specifies no requirements or guidance for user agents that experience
such cases. such cases.
9. Examples of Unsolicited Digest 9. Examples of Unsolicited Digest
The following examples demonstrate interactions where a server The following examples demonstrate interactions where a server
skipping to change at page 16, line 5 skipping to change at page 14, line 26
The request contains a "Digest" header calculated on the enclosed The request contains a "Digest" header calculated on the enclosed
representation. representation.
It also includes an "Accept-Encoding: br" header field that It also includes an "Accept-Encoding: br" header field that
advertises the client supports brotli encoding. advertises the client supports brotli encoding.
The response includes a "Content-Encoding: br" that indicates the The response includes a "Content-Encoding: br" that indicates the
selected representation is brotli encoded. The "Digest" field-value selected representation is brotli encoded. The "Digest" field-value
is therefore different compared to the request. is therefore different compared to the request.
The response body is displayed as a base64-encoded string because it
contains non-printable characters.
Request: Request:
PUT /items/123 PUT /items/123
Content-Type: application/json Content-Type: application/json
Content-Encoding: identity Content-Encoding: identity
Accept-Encoding: br Accept-Encoding: br
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
{"hello": "world"} {"hello": "world"}
skipping to change at page 17, line 16 skipping to change at page 15, line 42
id-sha-256. id-sha-256.
The response contains two digest values: The response contains two digest values:
o one with no content coding applied, which in this case o one with no content coding applied, which in this case
accidentally matches the unencoded digest-value sent in the accidentally matches the unencoded digest-value sent in the
request; request;
o one taking into account the "Content-Encoding". o one taking into account the "Content-Encoding".
As the response body contains non-printable characters, it is
displayed as a base64-encoded string.
Request: Request:
PUT /items/123 HTTP/1.1 PUT /items/123 HTTP/1.1
Content-Type: application/json Content-Type: application/json
Content-Encoding: identity Content-Encoding: identity
Accept-Encoding: br Accept-Encoding: br
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
{"hello": "world"} {"hello": "world"}
Response: Response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Content-Encoding: br Content-Encoding: br
Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=,
id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw==
9.7. POST Response does not Reference the Request URI 9.7. POST Response does not Reference the Request URI
Request "Digest" value is computed on the enclosed representation Request "Digest" value is computed on the enclosed representation
(see Section 5). (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 [RFC7231] Section 3.1.4.2 and identified by "Content-Location" (see [RFC7231] Section 3.1.4.2 and
Section 3.1.4.1 point 4). Section 3.1.4.1 point 4).
"Digest" is thus computed on the enclosed representation. "Digest" is thus computed on the enclosed representation.
Request: Request:
POST /books HTTP/1.1 POST /books HTTP/1.1
skipping to change at page 18, line 21 skipping to change at page 17, line 4
{"title": "New Title"} {"title": "New Title"}
Response Response
HTTP/1.1 201 Created HTTP/1.1 201 Created
Content-Type: application/json Content-Type: application/json
Digest: id-sha-256=BZlF2v0IzjuxN01RQ97EUXriaNNLhtI8Chx8Eq+XYSc= Digest: id-sha-256=BZlF2v0IzjuxN01RQ97EUXriaNNLhtI8Chx8Eq+XYSc=
Content-Location: /books/123 Content-Location: /books/123
{"id": "123", "title": "New Title"} {"id": "123", "title": "New Title"}
Note that a "204 No Content" response without a payload body but with Note that a "204 No Content" response without a payload body but with
the same "Digest" field-value would have been legitimate too. the same "Digest" field-value would have been legitimate too.
9.8. POST Response Describes the Request Status 9.8. POST Response Describes the Request Status
Request "Digest" value is computed on the enclosed representation Request "Digest" value is computed on the enclosed representation
(see Section 5). (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".
Request: Request:
POST /books HTTP/1.1 POST /books HTTP/1.1
Content-Type: application/json Content-Type: application/json
Accept: application/json Accept: application/json
Accept-Encoding: identity Accept-Encoding: identity
Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ=
Location: /books/123 Location: /books/123
{"title": "New Title"} {"title": "New Title"}
Response Response
HTTP/1.1 201 Created HTTP/1.1 201 Created
Content-Type: application/json Content-Type: application/json
Digest: id-sha-256=0o/WKwSfnmIoSlop2LV/ISaBDth05IeW27zzNMUh5l8= Digest: id-sha-256=0o/WKwSfnmIoSlop2LV/ISaBDth05IeW27zzNMUh5l8=
Location: /books/123 Location: /books/123
{"status": "created", "id": "123", "ts": 1569327729, "instance": "/books/123"} {
"status": "created",
"id": "123",
"ts": 1569327729,
"instance": "/books/123"
}
9.9. Digest with PATCH 9.9. Digest with PATCH
This case is analogous to a POST request where the target resource This case is analogous to a POST request where the target resource
reflects the effective request URI. reflects the effective request URI.
The PATCH request uses the "application/merge-patch+json" media type The PATCH request uses the "application/merge-patch+json" media type
defined in [RFC7396]. defined in [RFC7396].
"Digest" is calculated on the enclosed payload, which corresponds to "Digest" is calculated on the enclosed payload, which corresponds to
skipping to change at page 19, line 47 skipping to change at page 18, line 32
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Digest: id-sha-256=BZlF2v0IzjuxN01RQ97EUXriaNNLhtI8Chx8Eq+XYSc= Digest: id-sha-256=BZlF2v0IzjuxN01RQ97EUXriaNNLhtI8Chx8Eq+XYSc=
{"id": "123", "title": "New Title"} {"id": "123", "title": "New Title"}
Note that a "204 No Content" response without a payload body but with Note that a "204 No Content" response without a payload body but with
the same "Digest" field-value would have been legitimate too. the same "Digest" field-value would have been legitimate too.
9.10. Error responses
In error responses, the representation-data does not necessarily
refer to the target resource. Instead it refers to the
representation of the error.
In the following example a client attempts to patch the resource
located at /books/123. However, the resource does not exist and the
server generates a 404 response with a body that describes the error
in accordance with [RFC7807].
The digest of the response is computed on this enclosed
representation.
Request:
PATCH /books/123 HTTP/1.1
Content-Type: application/merge-patch+json
Accept: application/json
Accept-Encoding: identity
Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ=
{"title": "New Title"}
Response:
HTTP/1.1 404 Not Found
Content-Type: application/problem+json
Digest: sha-256=UJSojgEzqUe4UoHzmNl5d2xkmrW3BOdmvsvWu1uFeu0=
{
"title": "Not Found",
"detail": "Cannot PATCH a non-existent resource",
"status": 404
}
10. Examples of Want-Digest Solicited Digest 10. Examples of Want-Digest Solicited Digest
The following examples demonstrate interactions where a client The following examples demonstrate interactions where a client
solicits a "Digest" using "Want-Digest". solicits a "Digest" using "Want-Digest".
10.1. Server Selects Client's Least Preferred Algorithm 10.1. Server Selects Client's Least Preferred Algorithm
The client requests a digest, preferring sha. The server is free to The client requests a digest, preferring sha. The server is free to
reply with sha-256 anyway. reply with sha-256 anyway.
skipping to change at page 20, line 36 skipping to change at page 20, line 17
The client requests a sha digest only. The server is currently free The client requests a sha digest only. The server is currently free
to reply with a Digest containing an unsupported algorithm. to reply with a Digest containing an unsupported algorithm.
Request: Request:
GET /items/123 GET /items/123
Want-Digest: sha;q=1 Want-Digest: sha;q=1
Response: Response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Content-Encoding: identity Content-Encoding: identity
Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm
+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==
{"hello": "world"} {"hello": "world"}
10.3. Server Does Not Support Client Algorithm and Returns an Error 10.3. Server Does Not Support Client Algorithm and Returns an Error
The client requests a sha Digest, the server advises for sha-256 and The client requests a sha Digest, the server advises for sha-256 and
sha-512 sha-512
Request: Request:
GET /items/123 GET /items/123
Want-Digest: sha;q=1 Want-Digest: sha;q=1
skipping to change at page 22, line 14 skipping to change at page 21, line 41
Moreover identity digest algorithms (eg. ID-SHA-256 and ID-SHA-512) Moreover identity digest algorithms (eg. ID-SHA-256 and ID-SHA-512)
allow piecing together a resource from different sources (e.g. allow piecing together a resource from different sources (e.g.
different servers that perhaps apply different content codings) different servers that perhaps apply different content codings)
enabling the user-agent to detect that the application-layer tasks enabling the user-agent to detect that the application-layer tasks
completed properly, before handing off to say the HTML parser, video completed properly, before handing off to say the HTML parser, video
player etc. player etc.
Even a simple mechanism for end-to-end validation is thus valuable. Even a simple mechanism for end-to-end validation is thus valuable.
11.5. Usage in Signatures 11.5. Digest and Content-Location in responses
When a state-changing method returns the "Content-Location" header
field, the enclosed representation refers to the resource identified
by its value and "Digest" is computed accordingly.
11.6. 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 header fields and there are Such signatures can protect one or more header fields and there are
additional considerations when "Digest" is included in this set. additional considerations when "Digest" is included in this set.
Since the "Digest" header field is a hash of a resource Since the "Digest" header field is a hash of a resource
representation, it explicitly depends on the "representation representation, it explicitly depends on the "representation
metadata" (eg. the values of "Content-Type", "Content-Encoding" etc). metadata" (eg. the values of "Content-Type", "Content-Encoding" etc).
A signature that protects "Digest" but not other "representation A signature that protects "Digest" but not other "representation
metadata" may expose the communication to tampering. For example, an metadata" can expose the communication to tampering. For example, an
actor could manipulate the "Content-Type" field-value and cause a actor could manipulate the "Content-Type" field-value and cause a
digest validation failure at the recipient, preventing the digest validation failure at the recipient, preventing the
application from accessing the representation. Such an attack application from accessing the representation. Such an attack
consumes the resources of both endpoints. consumes the resources of both endpoints. See also Section 11.5.
"Digest" SHOULD always be used over a connection which provides "Digest" SHOULD always be used over a connection which provides
integrity at transport layer that protects HTTP header fields. integrity at the transport layer that protects HTTP header fields.
A "Digest" header field using NOT RECOMMENDED digest-algorithms A "Digest" header field using NOT RECOMMENDED digest-algorithms
SHOULD NOT be used in signatures. SHOULD NOT be used in signatures.
11.6. Message Truncation 11.7. Message Truncation
... ...
11.7. Algorithm Agility 11.8. Algorithm Agility
... ...
12. IANA Considerations 12. IANA Considerations
12.1. Establish the HTTP Digest Algorithm Values 12.1. Establish the HTTP Digest Algorithm Values
This memo sets this spec to be the establishing document for the HTTP This memo sets this spec to be the establishing document for the HTTP
Digest Algorithm Values [4] Digest Algorithm Values [4]
skipping to change at page 23, line 22 skipping to change at page 23, line 12
or "deprecated" according to the type and status of the primary or "deprecated" according to the type and status of the primary
document in which the algorithm is defined. document in which the algorithm is defined.
12.3. Deprecate "MD5" Digest Algorithm 12.3. Deprecate "MD5" Digest Algorithm
This memo updates the "MD5" digest algorithm in the HTTP Digest This memo updates the "MD5" digest algorithm in the HTTP Digest
Algorithm Values [6] registry: Algorithm Values [6] registry:
o Digest Algorithm: MD5 o Digest Algorithm: MD5
o Description: As specified in Section 3. o Description: As specified in Section 5.
o Status: As specified in Section 3. o Status: As specified in Section 5.
12.4. Update "CRC32C" Digest Algorithm 12.4. Update "CRC32C" Digest Algorithm
This memo updates the "CRC32c" digest algorithm in the HTTP Digest This memo updates the "CRC32c" digest algorithm in the HTTP Digest
Algorithm Values [7] registry: Algorithm Values [7] registry:
o Digest Algorithm: CRC32c o Digest Algorithm: CRC32c
o Description: The CRC32c algorithm is a 32-bit cyclic redundancy o Description: The CRC32c algorithm is a 32-bit cyclic redundancy
check. It achieves a better hamming distance (for better error- check. It achieves a better hamming distance (for better error-
skipping to change at page 24, line 4 skipping to change at page 23, line 42
o Reference: [RFC4960] appendix B, this document. o Reference: [RFC4960] appendix B, this document.
o Status: standard. o Status: standard.
12.5. Obsolete "SHA" Digest Algorithm 12.5. Obsolete "SHA" Digest Algorithm
This memo updates the "SHA" digest algorithm in the HTTP Digest This memo updates the "SHA" digest algorithm in the HTTP Digest
Algorithm Values [8] registry: Algorithm Values [8] registry:
o Digest Algorithm: SHA o Digest Algorithm: SHA
o Description: As specified in Section 3.
o Status: As specified in Section 3. o Description: As specified in Section 5.
o Status: As specified in Section 5.
12.6. Obsolete "ADLER32" Digest Algorithm 12.6. Obsolete "ADLER32" Digest Algorithm
This memo updates the "ADLER32" digest algorithm in the HTTP Digest This memo updates the "ADLER32" digest algorithm in the HTTP Digest
Algorithm Values [9] registry: Algorithm Values [9] registry:
o Digest Algorithm: ADLER32 o Digest Algorithm: ADLER32
o Description: The ADLER32 algorithm is a checksum specified in o Description: The ADLER32 algorithm is a checksum specified in
[RFC1950] "ZLIB Compressed Data Format". The 32-bit output is [RFC1950] "ZLIB Compressed Data Format". The 32-bit output is
encoded in hexadecimal (using between 1 and 8 ASCII characters encoded in hexadecimal (using between 1 and 8 ASCII characters
from 0-9, A-F, and a-f; leading 0's are allowed). For example, from 0-9, A-F, and a-f; leading 0's are allowed). For example,
ADLER32=03da0195 and ADLER32=3DA0195 are both valid checksums for ADLER32=03da0195 and ADLER32=3DA0195 are both valid checksums for
the 4-byte message "Wiki". This algorithm is obsoleted and SHOULD the 4-byte message "Wiki". This algorithm is obsoleted and SHOULD
NOT be used. NOT be used.
o Status: obsoleted o Status: obsoleted
skipping to change at page 24, line 32 skipping to change at page 24, line 21
o Status: obsoleted o Status: obsoleted
12.7. The "ID-SHA-256" Digest Algorithm 12.7. The "ID-SHA-256" Digest Algorithm
This memo registers the "ID-SHA-256" digest algorithm in the HTTP This memo registers the "ID-SHA-256" digest algorithm in the HTTP
Digest Algorithm Values [10] registry: Digest Algorithm Values [10] registry:
o Digest Algorithm: ID-SHA-256 o Digest Algorithm: ID-SHA-256
o Description: As specified in Section 3. o Description: As specified in Section 5.
o Status: As specified in Section 3. o Status: As specified in Section 5.
12.8. The "ID-SHA-512" Digest Algorithm 12.8. The "ID-SHA-512" Digest Algorithm
This memo registers the "ID-SHA-512" digest algorithm in the HTTP This memo registers the "ID-SHA-512" digest algorithm in the HTTP
Digest Algorithm Values [11] registry: Digest Algorithm Values [11] registry:
o Digest Algorithm: ID-SHA-512 o Digest Algorithm: ID-SHA-512
o Description: As specified in Section 3. o Description: As specified in Section 5.
o Status: As specified in Section 3. o Status: As specified in Section 5.
12.9. Changes compared to RFC5843 12.9. Changes compared to RFC5843
The status of "MD5" has been updated to "deprecated", and its The status of "MD5" has been updated to "deprecated", and its
description states that this algorithm MUST NOT be used. description states that this algorithm MUST NOT be used.
The status of "SHA" has been updated to "obsoleted", and its The status of "SHA" has been updated to "obsoleted", and its
description states that this algorithm is NOT RECOMMENDED. description states that this algorithm is NOT RECOMMENDED.
The status for "CRC32C" has been updated to "standard". The status for "CRC32C" has been updated to "standard".
skipping to change at page 25, line 26 skipping to change at page 25, line 18
"Permanent Message Header Field Names" registry ([RFC3864]). "Permanent Message Header Field Names" registry ([RFC3864]).
Header field name: "Want-Digest" Header field name: "Want-Digest"
Applicable protocol: http Applicable protocol: http
Status: standard Status: standard
Author/Change controller: IETF Author/Change controller: IETF
Specification document(s): Section 4.1 of this document Specification document(s): Section 4 of this document
12.11. Digest Header Field Registration 12.11. Digest Header Field Registration
This section registers the "Digest" header field in the "Permanent This section registers the "Digest" header field in the "Permanent
Message Header Field Names" registry ([RFC3864]). Message Header Field Names" registry ([RFC3864]).
Header field name: "Digest" Header field name: "Digest"
Applicable protocol: http Applicable protocol: http
Status: standard Status: standard
Author/Change controller: IETF Author/Change controller: IETF
Specification document(s): Section 4.2 of this document Specification document(s): Section 3 of this document
13. References 13. References
13.1. Normative References 13.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/>.
skipping to change at page 28, line 19 skipping to change at page 28, line 13
<https://www.rfc-editor.org/info/rfc2818>. <https://www.rfc-editor.org/info/rfc2818>.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", [RFC5789] 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>.
[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>.
[RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP
APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
<https://www.rfc-editor.org/info/rfc7807>.
[SRI] Akhawe, D., Braun, F., Marier, F., and J. Weinberger, [SRI] Akhawe, D., Braun, F., Marier, F., and J. Weinberger,
"Subresource Integrity", W3C Recommendation REC-SRI- "Subresource Integrity", W3C Recommendation REC-SRI-
20160623, June 2016, 20160623, June 2016,
<https://www.w3.org/TR/2016/REC-SRI-20160623/>. <https://www.w3.org/TR/2016/REC-SRI-20160623/>.
13.3. URIs 13.3. URIs
[1] https://lists.w3.org/Archives/Public/ietf-http-wg/ [1] https://lists.w3.org/Archives/Public/ietf-http-wg/
[2] https://github.com/httpwg/http-extensions [2] https://github.com/httpwg/http-extensions
skipping to change at page 28, line 48 skipping to change at page 28, line 46
[7] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml [7] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml
[8] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml [8] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml
[9] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml [9] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml
[10] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml [10] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml
[11] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml [11] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml
Appendix A. FAQ Appendix A. Resource Representation and Representation-Data
The following examples show how representation metadata, payload
transformations and method impacts on the message and payload body.
When the payload body contains non-printable characters (eg. when it
is compressed) it is shown as base64-encoded string.
Here is a gzip-compressed json object
Request:
PUT /entries/1234 HTTP/1.1
Content-Type: application/json
Content-Encoding: gzip
H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA=
Now the same payload body conveys a malformed json object.
Request:
PUT /entries/1234 HTTP/1.1
Content-Type: application/json
H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA=
A Range-Request alters the payload body, conveying a partial
representation.
Request:
GET /entries/1234 HTTP/1.1
Range: bytes=1-7
Response:
HTTP/1.1 206 Partial Content
Content-Encoding: gzip
Content-Type: application/json
Content-Range: bytes 1-7/18
iwgAla3RXA==
Now the method too alters the payload body.
Request:
HEAD /entries/1234 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip
Response:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Encoding: gzip
Finally the semantics of an HTTP response might decouple the
effective request URI from the enclosed representation. In the
example response below, the "Content-Location" header field indicates
that the enclosed representation refers to the resource available at
"/authors/123".
Request:
POST /authors/ HTTP/1.1
Accept: application/json
Content-Type: application/json
{"author": "Camilleri"}
Response:
HTTP/1.1 201 Created
Content-Type: application/json
Content-Location: /authors/123
Location: /authors/123
{"id": "123", "author": "Camilleri"}
Appendix B. FAQ
1. Why remove all references to content-md5? 1. Why remove all references to content-md5?
Those were unnecessary to understanding and using this spec. Those were unnecessary to understanding and using this spec.
2. Why remove references to instance manipulation? 2. Why remove references to instance manipulation?
Those were unnecessary for correctly using and applying the spec. Those were unnecessary for correctly using and applying the spec.
An example with Range Request is more than enough. This doc uses An example with Range Request is more than enough. This doc uses
the term "partial representation" which should group all those the term "partial representation" which should group all those
cases. cases.
3. How to use "Digest" with "PATCH" method? 3. How to use "Digest" with "PATCH" method?
See Section 5. See Section 6.
4. Why remove references to delta-encoding? 4. Why remove references to delta-encoding?
Unnecessary for a correct implementation of this spec. The Unnecessary for a correct implementation of this spec. The
revised spec can be nicely adapted to "delta encoding", but all revised spec can be nicely adapted to "delta encoding", but all
the references here to delta encoding don't add anything to this the references here to delta encoding don't add anything to this
RFC. Another job would be to refresh delta encoding. RFC. Another job would be to refresh delta encoding.
5. Why remove references to Digest Authentication? 5. Why remove references to Digest Authentication?
This RFC seems to me completely unrelated to Digest This RFC seems to me completely unrelated to Digest
Authentication but for the word "Digest". Authentication but for the word "Digest".
skipping to change at page 30, line 18 skipping to change at page 32, line 5
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 import base64, json, hashlib, brotli
def digest(item, encoding=lambda x: x, algorithm=hashlib.sha256): def digest(item, encoding=lambda x: x, algorithm=hashlib.sha256):
json_bytes = json.dumps(item).encode() json_bytes = json.dumps(item).encode()
content_encoded = encoding(json_bytes) content_encoded = encoding(json_bytes)
checksum_bytes = algorithm(content_encoded).digest() checksum_bytes = algorithm(content_encoded).digest()
return base64.encodebytes(checksum_bytes).strip() return base64.encodebytes(checksum_bytes).strip()
item = {"hello": "world"} item = {"hello": "world"}
print("Identity encoding, sha256", digest(item)) print("Encoding | digest-algorithm | digest-value")
# Out: Identity encoding, sha256 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= print("Identity | sha256 |", digest(item))
# Encoding | digest-algorithm | digest-value
# Identity | sha256 | 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=
print("Brotli encoding, sha256", digest(item, encoding=brotli.compress)) print("Encoding | digest-algorithm | digest-value")
# Out: Brotli encoding, sha256 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= print("Brotli | sha256 |", digest(item, encoding=brotli.compress))
# Encoding | digest-algorithm | digest-value
# Brotli , sha256 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=
print("Identity encoding, sha512", digest(item, algorithm=hashlib.sha512)) print("Encoding | digest-algorithm | digest-value")
# Out: Identity encoding, sha512 b'WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==\n' print("Identity | sha512 |", digest(item, algorithm=hashlib.sha512))
# Encoding | digest-algorithm | digest-value
# Identity | sha512 | b'WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2s
vX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==\n'
Changes Changes
_RFC Editor: Please remove this section before publication._ _RFC Editor: Please remove this section before publication._
D.1. Since draft-ietf-httpbis-digest-headers-00 E.1. Since draft-ietf-httpbis-digest-headers-00
o Align title with document name o Align title with document name
o Add id-sha-* algorithm examples #880 o Add id-sha-* algorithm examples #880
o Reference [RFC6234] and [RFC3174] instead of FIPS-1 o Reference [RFC6234] and [RFC3174] instead of FIPS-1
o Deprecate MD5 o Deprecate MD5
o Obsolete ADLER-32 but don't forbid it #828 o Obsolete ADLER-32 but don't forbid it #828
o Update CRC32C value in IANA table #828 o Update CRC32C value in IANA table #828
o Use when acting on resources (POST, PATCH) #853 o Use when acting on resources (POST, PATCH) #853
o Added Relationship with SRI, draft Use Cases #868, #971 o Added Relationship with SRI, draft Use Cases #868, #971
o Warn about the implications of "Content-Location"
E.2. Since draft-ietf-httpbis-digest-headers-01
o Digest of error responses is computed on the error representation-
data #1004
o Effect of HTTP semantics on payload and message body moved to
appendix #1122
o Editorial refactoring, moving headers sections up. #1109-#1112,
#1116, #1117, #1122-#1124
Authors' Addresses Authors' Addresses
Roberto Polli Roberto Polli
Team Digitale, Italian Government Team Digitale, Italian Government
Email: robipolli@gmail.com Email: robipolli@gmail.com
Lucas Pardue Lucas Pardue
Cloudflare Cloudflare
 End of changes. 109 change blocks. 
284 lines changed or deleted 366 lines changed or added

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