Diff: draft-ietf-httpbis-digest-headers-01.txt - draft-ietf-httpbis-digest-headers-02.txt

	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" [ "." 01DIGIT ] ) / ( "1" [ "." 01( "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

	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.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/