< draft-polli-id-digest-algorithms-01.txt		draft-polli-id-digest-algorithms-02.txt >
	Network Working Group R. Polli		Network Working Group R. Polli
	Internet-Draft Digital Transformation Department, Italian Government		Internet-Draft Digital Transformation Department, Italian Government
	Intended status: Standards Track 18 December 2020		Intended status: Experimental 2 December 2021
	Expires: 21 June 2021		Expires: 5 June 2022
	The "id-" prefix for Digest Algorithms		The "id-" prefix for Digest Algorithms
	draft-polli-id-digest-algorithms-01		draft-polli-id-digest-algorithms-02
	Abstract		Abstract
	This document defines the "id-" prefix for digest-algorithms used in		This document defines the "id-" prefix for digest-algorithms used in
	the Digest HTTP field. This prefix explicits that the value of the		the Digest Fields. This prefix explicits that the computed checksum
	digest-algorithm is independent from Content-Encoding.		value is independent from Content-Encoding.
	Note to Readers		Note to Readers
	_RFC EDITOR: please remove this section before publication_		_RFC EDITOR: please remove this section before publication_
	Discussion of this draft takes place on the HTTP working group		Discussion of this draft takes place on the HTTP working group
	mailing list (ietf-http-wg@w3.org), which is archived at		mailing list (ietf-http-wg@w3.org), which is archived at
	https://lists.w3.org/Archives/Public/ietf-http-wg/		https://lists.w3.org/Archives/Public/ietf-http-wg/
	(https://lists.w3.org/Archives/Public/ietf-http-wg/).		(https://lists.w3.org/Archives/Public/ietf-http-wg/).
	The source code and issues list for this draft can be found at		The source code and issues list for this draft can be found at
	https://github.com/ioggstream/draft-polli-Retry-Scope		https://github.com/ioggstream/draft-polli-id-digest-algorithms
	(https://github.com/ioggstream/draft-polli-Retry-Scope).		(https://github.com/ioggstream/draft-polli-id-digest-algorithms).
	Status of This Memo		Status of This Memo
	This Internet-Draft is submitted in full conformance with the		This Internet-Draft is submitted in full conformance with the
	provisions of BCP 78 and BCP 79.		provisions of BCP 78 and BCP 79.
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute		Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-		working documents as Internet-Drafts. The list of current Internet-
	Drafts is at https://datatracker.ietf.org/drafts/current/.		Drafts is at https://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	This Internet-Draft will expire on 21 June 2021.		This Internet-Draft will expire on 5 June 2022.
	Copyright Notice		Copyright Notice
	Copyright (c) 2020 IETF Trust and the persons identified as the		Copyright (c) 2021 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 (https://trustee.ietf.org/		Provisions Relating to IETF Documents (https://trustee.ietf.org/
	license-info) in effect on the date of publication of this document.		license-info) in effect on the date of publication of this document.
	Please review these documents carefully, as they describe your rights		Please review these documents carefully, as they describe your rights
	and restrictions with respect to this document. Code Components		and restrictions with respect to this document. Code Components
	extracted from this document must include Simplified BSD License text		extracted from this document must include Revised BSD License text as
	as described in Section 4.e of the Trust Legal Provisions and are		described in Section 4.e of the Trust Legal Provisions and are
	provided without warranty as described in the Simplified BSD License.		provided without warranty as described in the Revised BSD License.
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
	1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3		1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
	2. The "id-" prefix for digest-algorithms . . . . . . . . . . . 3		2. The "id-" prefix for digest-algorithms . . . . . . . . . . . 3
	3. Security Considerations . . . . . . . . . . . . . . . . . . . 4		3. Security Considerations . . . . . . . . . . . . . . . . . . . 3
	3.1. Disclosure of encrypted content . . . . . . . . . . . . . 4		3.1. Disclosure of encrypted content . . . . . . . . . . . . . 4
	4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4		4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4
	4.1. TBD how to reserve "id-" prefix? . . . . . . . . . . . . 4		5. Normative References . . . . . . . . . . . . . . . . . . . . 4
	5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 4		Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 5
	5.1. The id-crc32c digest-algorithm . . . . . . . . . . . . . 4		A.1. The id-sha-256 digest-algorithm . . . . . . . . . . . . . 5
	6. Normative References . . . . . . . . . . . . . . . . . . . . 4
	Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 5
	FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5		FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
	Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 5		Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 5
			Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 6
	Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 6		Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
			Since draft-polli-id-digest-algorithms-01 . . . . . . . . . . . 6
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6		Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6
	1. Introduction		1. Introduction
	The [DIGEST] defines a way to convey a checksum of a representation-		The [DIGEST] defines a way to convey a checksum of a representation-
	data as specified in [SEMANTICS].		data as specified in [SEMANTICS].
	As the representation data depends on the value of "Content-		As the representation data depends on the value of Content-Encoding,
	Encoding", it is useful to convey the checksum value of a		it is useful to convey the checksum value of a representation without
	representation without any content-coding applied.		any content coding applied.
	This proposal introduces the "id-" prefix to specify that the		This proposal introduces the id- prefix to specify that the provided
	provided digest-algorithm value is computed on the representation-		digest-algorithm value is computed on the representation-data without
	data without any content-coding applied.		any content coding applied.
	1.1. Notational Conventions		1.1. Notational Conventions
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and		"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
	"OPTIONAL" in this document are to be interpreted as described in		"OPTIONAL" in this document are to be interpreted as described in
	BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all		BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
	capitals, as shown here. These words may also appear in this		capitals, as shown here. These words may also appear in this
	document in lower case as plain English words, absent their normative		document in lower case as plain English words, absent their normative
	meanings.		meanings.
	This document uses the Augmented BNF defined in [RFC5234] and updated		This document uses the Augmented BNF defined in [RFC5234] and updated
	by [RFC7405].		by [RFC7405].
	The definitions "representation", "selected representation",		The definitions "representation", "selected representation",
	"representation data", "representation metadata", and "payload body"		"representation data", "representation metadata", and "content" in
	in this document are to be interpreted as described in [SEMANTICS].		this document are to be interpreted as described in [SEMANTICS].
	The definitions "digest-algorithm" and "representation-data-digest"		The definitions "digest-algorithm" and "representation-data-digest"
	in this document are to be interpreted as described in [DIGEST].		in this document are to be interpreted as described in [DIGEST].
	2. The "id-" prefix for digest-algorithms		2. The "id-" prefix for digest-algorithms
	A digest-algorithm to be registered within the HTTP Digest Algorithm		A new digest-algorithm to be registered within the HTTP Digest
	Values (https://www.iana.org/assignments/http-dig-alg/http-dig-		Algorithm Values Registry (https://www.iana.org/assignments/http-dig-
	alg.xhtml) MUST NOT start with the string "id-".		alg/) MUST NOT start with the string id-.
	The following two examples show two digest-algorithm names that		The following two examples show two digest-algorithm names that
	cannot be registered		cannot be registered
	id-crc32c		id-sha-256
	id-adler32		id-sha-512
	For every digest-algorithm registered in the HTTP Digest Algorithm		For every digest-algorithm registered in the HTTP Digest Algorithm
	Values (https://www.iana.org/assignments/http-dig-alg/http-dig-		Values (https://www.iana.org/assignments/http-dig-alg/) the associate
	alg.xhtml) the associate "id-" digest-algorithm has the following		id- digest-algorithm has the following properties:
	properties:
	* the checksum is computed on the representation-data of the		* the checksum is computed on the representation-data of the
	resource when no content coding is applied;		resource when no content coding is applied;
	* the checksum is computed according to the original digest-		* the checksum is computed according to the original digest-
	algorithm Description field, and uses the same encoding of the		algorithm "Description" field, and uses the same encoding of the
	original digest-algorithm.		original digest-algorithm.
	This definition is compatible, and thus extends, the definition of
	the "id-sha-256" and "id-sha-512" digest-algorithms contained in
	Section X of [DIGEST].
	3. Security Considerations		3. Security Considerations
	3.1. Disclosure of encrypted content		3.1. Disclosure of encrypted content
	Like the "id-sha-256" digest-algoritm defined in [DIGEST] if the		If the content coding provides encryption features, sending the
	content-coding provides encryption features, sending the checksum of		checksum of unencoded representation can disclose information about
	unencoded representation can disclose information.		the original content.
	4. IANA Considerations		4. IANA Considerations
	4.1. TBD how to reserve "id-" prefix?		Please, add the following text to the "Note" section of the HTTP
			Digest Algorithm Values (https://www.iana.org/assignments/http-dig-
	5. Examples		alg/).
	5.1. The id-crc32c digest-algorithm
	The following request conveys a brotli encoded json object
	{"hello": "world"}
	The "Digest" computed using the "crc32c" digest-algorithm present in
	HTTP Digest Algorithm Values (https://www.iana.org/assignments/http-
	dig-alg/http-dig-alg.xhtml) is content-coding aware, while its
	associated "id-" digest-algorithm is not "id-crc32c"
	POST /data HTTP/1.1		" For each registered Digest Algorithm, an associated id- algorithm
	Content-Type: application/json		is defined.
	Content-Encoding: br
	Digest: id-crc32c=43794720, crc32c=DB329237
	CwGAZG9nAw==		The associated representation-data-digest is computed according to
			Section 2 of this document. "
	6. Normative References		5. Normative References
	[DIGEST] Polli, R. and L. Pardue, "Digest Headers", Work in		[DIGEST] Polli, R. and L. Pardue, "Digest Fields", Work in
	Progress, Internet-Draft, draft-ietf-httpbis-digest-		Progress, Internet-Draft, draft-ietf-httpbis-digest-
	headers-04, 17 October 2020, <http://www.ietf.org/		headers-07, 16 November 2021,
	internet-drafts/draft-ietf-httpbis-digest-headers-04.txt>.		<https://www.ietf.org/archive/id/draft-ietf-httpbis-
			digest-headers-07.txt>.
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119,		Requirement Levels", BCP 14, RFC 2119,
	DOI 10.17487/RFC2119, March 1997,		DOI 10.17487/RFC2119, March 1997,
	<https://www.rfc-editor.org/info/rfc2119>.		<https://www.rfc-editor.org/info/rfc2119>.
	[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax		[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
	Specifications: ABNF", STD 68, RFC 5234,		Specifications: ABNF", STD 68, RFC 5234,
	DOI 10.17487/RFC5234, January 2008,		DOI 10.17487/RFC5234, January 2008,
	<https://www.rfc-editor.org/info/rfc5234>.		<https://www.rfc-editor.org/info/rfc5234>.
	[RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF",		[RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF",
	RFC 7405, DOI 10.17487/RFC7405, December 2014,		RFC 7405, DOI 10.17487/RFC7405, December 2014,
	<https://www.rfc-editor.org/info/rfc7405>.		<https://www.rfc-editor.org/info/rfc7405>.
	[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC		[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
	2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,		2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
	May 2017, <https://www.rfc-editor.org/info/rfc8174>.		May 2017, <https://www.rfc-editor.org/info/rfc8174>.
	[SEMANTICS]		[SEMANTICS]
	Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer		Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP
	Protocol (HTTP/1.1): Semantics and Content", RFC 7231,		Semantics", Work in Progress, Internet-Draft, draft-ietf-
	DOI 10.17487/RFC7231, June 2014,		httpbis-semantics-19, 12 September 2021,
	<https://www.rfc-editor.org/info/rfc7231>.		<https://www.ietf.org/archive/id/draft-ietf-httpbis-
			semantics-19.txt>.
	Appendix A. Acknowledgements		Appendix A. Examples
	This specification was born from a thread created by James Manger and		A.1. The id-sha-256 digest-algorithm
	the subsequent discussion here https://github.com/httpwg/http-
	extensions/issues/885.		The following request conveys a brotli encoded json object
			{"hello": "world"}
			The Digest computed using the "sha-256" digest-algorithm present in
			HTTP Digest Algorithm Values (https://www.iana.org/assignments/http-
			dig-alg/) is content coding aware, while its associated "id-" digest-
			algorithm is not.
			POST /data HTTP/1.1
			Content-Type: application/json
			Content-Encoding: br
			Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=,
			id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
			CwGAZiwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw==
	FAQ		FAQ
	Q: Question 1 Answer 1		_RFC Editor: Please remove this section before publication._
			Q: Why to convey the checksum independent from the content
			codings? This is useful to identify and validate a resource
			downloaded from different sources using different content codings,
			or to compare a resource with its stored or signed counterpart.
			Q: How does it improve the life of checksum providers? If providers
			use reverse proxies to eg. compress responses, this could
			invalidate content coding aware checksums. Providing an id-
			algorithm, allows the digest checksum to be validated.
	Code Samples		Code Samples
	_RFC Editor: Please remove this section before publication._		_RFC Editor: Please remove this section before publication._
	How can I generate and validate the "Digest" values shown in the		How can I generate an identity digest value?
	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 crc32c algorithm. Note that these are formatted as		objects using crc32c algorithm. Note that these are formatted as
	base64. This function could be adapted to other algorithms and		base64. This function could be adapted to other algorithms and
	should take into account their specific formatting rules.		should take into account their specific formatting rules.
	import base64, json, brotli, crc32c		import base64, json, brotli, hashlib
	identity = lambda x: x		identity = lambda x: x
	def digest(item, content_coding=identity, algorithm=crc32c.crc32c):		def digest(item, content_coding=identity, algorithm=hashlib.sha256) -> bytes:
	json_bytes = json.dumps(item).encode()		json_bytes = json.dumps(item).encode()
	content_encoded = content_coding(json_bytes)		content_encoded = content_coding(json_bytes)
	checksum = algorithm(content_encoded)		checksum = algorithm(content_encoded)
	# encode result has uppercase hex		return base64.encodebytes(checksum.digest())
	return hex(checksum)[2:].upper()
	item = {"hello": "world"}		item = {"hello": "world"}
	print("crc32c digest value for a br-coded representation: ",		print("sha-256 digest value for a br-coded representation: ",
	digest(item, content_coding=brotli.compress)		digest(item, content_coding=brotli.compress)
	)		)
	print("id-crc32c digest value for a br-coded representation: ",		print("id-sha-256 digest value for a br-coded representation: ",
	digest(item, content_coding=identity)		digest(item, content_coding=identity)
	)		)
			Acknowledgements
			This specification was born from a thread created by James Manger and
			the subsequent discussion here https://github.com/httpwg/http-
			extensions/issues/885.
	Change Log		Change Log
	RFC EDITOR PLEASE DELETE THIS SECTION.		_RFC Editor: Please remove this section before publication._
			Since draft-polli-id-digest-algorithms-01
			* Include id-sha-256 and id-sha-512.
	Author's Address		Author's Address
	Roberto Polli		Roberto Polli
	Digital Transformation Department, Italian Government		Digital Transformation Department, Italian Government
	Italy		Italy
	Email: robipolli@gmail.com		Email: robipolli@gmail.com
End of changes. 39 change blocks.
	94 lines changed or deleted		110 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/