< draft-nottingham-binary-structured-headers-00.txt		draft-nottingham-binary-structured-headers-01.txt >
	Network Working Group M. Nottingham		Network Working Group M. Nottingham
	Internet-Draft Fastly		Internet-Draft Fastly
	Intended status: Standards Track November 1, 2019		Intended status: Standards Track January 10, 2020
	Expires: May 4, 2020		Expires: July 13, 2020
	Binary Structured HTTP Headers		Binary Structured HTTP Headers
	draft-nottingham-binary-structured-headers-00		draft-nottingham-binary-structured-headers-01
	Abstract		Abstract
	This specification defines a binary serialisation of Structured		This specification defines a binary serialisation of Structured
	Headers for HTTP, along with a negotiation mechanism for its use in		Headers for HTTP, along with a negotiation mechanism for its use in
	HTTP/2. It also defines how to use Structured Headers for many		HTTP/2. It also defines how to use Structured Headers for many
	existing headers - thereby "backporting" them - when supported by two		existing headers - thereby "backporting" them - when supported by two
	peers.		peers.
	Note to Readers		Note to Readers
	skipping to change at page 2, line 4 ¶		skipping to change at page 2, line 4 ¶
	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 4, 2020.		This Internet-Draft will expire on July 13, 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
	skipping to change at page 2, line 36 ¶		skipping to change at page 2, line 36 ¶
	2.1. The Binary Literal Representation . . . . . . . . . . . . 4		2.1. The Binary Literal Representation . . . . . . . . . . . . 4
	2.1.1. Lists . . . . . . . . . . . . . . . . . . . . . . . . 4		2.1.1. Lists . . . . . . . . . . . . . . . . . . . . . . . . 4
	2.1.2. Dictionaries . . . . . . . . . . . . . . . . . . . . 4		2.1.2. Dictionaries . . . . . . . . . . . . . . . . . . . . 4
	2.1.3. Items . . . . . . . . . . . . . . . . . . . . . . . . 5		2.1.3. Items . . . . . . . . . . . . . . . . . . . . . . . . 5
	2.1.4. String Literals . . . . . . . . . . . . . . . . . . . 5		2.1.4. String Literals . . . . . . . . . . . . . . . . . . . 5
	2.2. Binary Structured Types . . . . . . . . . . . . . . . . . 5		2.2. Binary Structured Types . . . . . . . . . . . . . . . . . 5
	2.2.1. Inner Lists . . . . . . . . . . . . . . . . . . . . . 6		2.2.1. Inner Lists . . . . . . . . . . . . . . . . . . . . . 6
	2.2.2. Parameters . . . . . . . . . . . . . . . . . . . . . 6		2.2.2. Parameters . . . . . . . . . . . . . . . . . . . . . 6
	2.2.3. Item Payload Types . . . . . . . . . . . . . . . . . 7		2.2.3. Item Payload Types . . . . . . . . . . . . . . . . . 7
	3. Using Binary Structured Headers in HTTP/2 . . . . . . . . . . 10		3. Using Binary Structured Headers in HTTP/2 . . . . . . . . . . 10
	3.1. Binary Structured Headers Setting . . . . . . . . . . . . 11		3.1. Binary Structured Headers Setting . . . . . . . . . . . . 10
	3.2. The BINHEADERS Frame . . . . . . . . . . . . . . . . . . 11		3.2. The BINHEADERS Frame . . . . . . . . . . . . . . . . . . 11
	4. Using Binary Structured Headers with Existing Fields . . . . 12		4. Using Binary Structured Headers with Existing Fields . . . . 12
	4.1. Directly Represented Fields . . . . . . . . . . . . . . . 12		4.1. Directly Represented Fields . . . . . . . . . . . . . . . 12
	4.2. Aliased Fields . . . . . . . . . . . . . . . . . . . . . 14		4.2. Aliased Fields . . . . . . . . . . . . . . . . . . . . . 14
	4.2.1. URLs . . . . . . . . . . . . . . . . . . . . . . . . 15		4.2.1. URLs . . . . . . . . . . . . . . . . . . . . . . . . 15
	4.2.2. Dates . . . . . . . . . . . . . . . . . . . . . . . . 15		4.2.2. Dates . . . . . . . . . . . . . . . . . . . . . . . . 15
	4.2.3. ETags . . . . . . . . . . . . . . . . . . . . . . . . 16		4.2.3. ETags . . . . . . . . . . . . . . . . . . . . . . . . 16
	4.2.4. Links . . . . . . . . . . . . . . . . . . . . . . . . 16		4.2.4. Links . . . . . . . . . . . . . . . . . . . . . . . . 16
	4.2.5. Cookies . . . . . . . . . . . . . . . . . . . . . . . 17		4.2.5. Cookies . . . . . . . . . . . . . . . . . . . . . . . 16
	5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17		5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
	6. Security Considerations . . . . . . . . . . . . . . . . . . . 17		6. Security Considerations . . . . . . . . . . . . . . . . . . . 17
	7. References . . . . . . . . . . . . . . . . . . . . . . . . . 17		7. References . . . . . . . . . . . . . . . . . . . . . . . . . 17
	7.1. Normative References . . . . . . . . . . . . . . . . . . 17		7.1. Normative References . . . . . . . . . . . . . . . . . . 17
	7.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 18		7.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 18
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19		Appendix A. Data Supporting Directly Represented Field Mappings 19
			Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21
	1. Introduction		1. Introduction
	HTTP messages often pass through several systems - clients,		HTTP messages often pass through several systems - clients,
	intermediaries, servers, and subsystems of each - that parse and		intermediaries, servers, and subsystems of each - that parse and
	process their header and trailer fields. This repeated parsing (and		process their header and trailer fields. This repeated parsing (and
	often re-serialisation) adds latency and consumes CPU, energy, and		often re-serialisation) adds latency and consumes CPU, energy, and
	other resources.		other resources.
	Structured Headers for HTTP [I-D.ietf-httpbis-header-structure]		Structured Headers for HTTP [I-D.ietf-httpbis-header-structure]
	skipping to change at page 8, line 11 ¶		skipping to change at page 8, line 11 ¶
	The item's parameters, if present, are serialised in a following		The item's parameters, if present, are serialised in a following
	Parameter type (Section 2.2.2); they do not form part of the payload		Parameter type (Section 2.2.2); they do not form part of the payload
	of the item.		of the item.
	2.2.3.1. Integers		2.2.3.1. Integers
	The Integer data type (type=0x3) has a payload in the format:		The Integer data type (type=0x3) has a payload in the format:
	5 6 7 0 1 2 3 4 5 6 7		5 6 7 0 1 2 3 4 5 6 7
	+---+---+---+---+---+---+---+---+---+---+---		+---+---+---+---+---+---+---+---+---+---+---
	S | X | Length (8+)		S | Integer (2+)
	+---+---+---+---+---+---+---+---+---+---+---		+---+---+---+---+---+---+---+---+---+---+---
	0 1 2 3 4 5 6 7
	+---+---+---+---+---+---+---+---
	| Integer (Length octets)
	+---+---+---+---+---+---+---+---
	Its fields are:		Its fields are:
	o S: sign bit; 0 is negative, 1 is positive		o S: sign bit; 0 is negative, 1 is positive
	o X: 2 bits of padding		o Integer: The integer, encoded as per [RFC7541], Section 5.1, with
			a 2-bit prefix
	o Length: The number of octets used to represent the integer,
	encoded as per [RFC7541], Section 5.1, with a 2-bit prefix
	o Integer: Length octets
	2.2.3.2. Floats		2.2.3.2. Floats
	The Float data type (type=0x4) have a payload in the format:		The Float data type (type=0x4) have a payload in the format:
	5 6 7 0 1 2 3 4 5 6 7		5 6 7 0 1 2 3 4 5 6 7
	+---+---+---+---+---+---+---+---+---+---+---		+---+---+---+---+---+---+---+---+---+---+---
	S | X | ILength (8+)		S | Integer (2+)
	+---+---+---+---+---+---+---+---+---+---+---		+---+---+---+---+---+---+---+---+---+---+---
	0 1 2 3 4 5 6 7		0 1 2 3 4 5 6 7
	+---+---+---+---+---+---+---+---		+---+---+---+---+---+---+---+---
	| Integer (ILength octets)
	+---+---+---+---+---+---+---+---
	0 1 2 3 4 5 6 7
	+---+---+---+---+---+---+---+---
	| FLength (8+)		| FLength (8+)
	+---+---+---+---+---+---+---+---		+---+---+---+---+---+---+---+---
	0 1 2 3 4 5 6 7		0 1 2 3 4 5 6 7
	+---+---+---+---+---+---+---+---		+---+---+---+---+---+---+---+---
	| Fractional (FLength octets)		| Fractional (8+)
	+---+---+---+---+---+---+---+---		+---+---+---+---+---+---+---+---
	Its fields are:		Its fields are:
	o S: sign bit; 0 is negative, 1 is positive		o S: sign bit; 0 is negative, 1 is positive
	o X: 2 bits of padding		o Integer: The integer component, encoded as per [RFC7541],
			Section 5.1, with a 2-bit prefix.
	o ILength: The number of octets used to represent the integer
	component, encoded as per [RFC7541], Section 5.1, with a 2-bit
	prefix.
	o Integer - ILength octets
	o FLength: The number of octets used to represent the fractional
	component, encoded as per [RFC7541], Section 5.1, with a 2-bit
	prefix.
	o Fractional: FLength octets		o Fractional: The fractional component, encoded as per [RFC7541],
			Section 5.1, with a 8-bit prefix.
	2.2.3.3. Strings		2.2.3.3. Strings
	The String data type (type=0x5) has a payload in the format:		The String data type (type=0x5) has a payload in the format:
	5 6 7 0 1 2 3 4 5 6 7		5 6 7 0 1 2 3 4 5 6 7
	+---+---+---+---+---+---+---+---+---+---+---		+---+---+---+---+---+---+---+---+---+---+---
	L(3+) | String (L octets)		L(3+) | String (L octets)
	+---+---+---+---+---+---+---+---+---+---+---		+---+---+---+---+---+---+---+---+---+---+---
	skipping to change at page 13, line 23 ¶		skipping to change at page 13, line 4 ¶
	o Access-Control-Allow-Headers - List		o Access-Control-Allow-Headers - List
	o Access-Control-Allow-Methods - List		o Access-Control-Allow-Methods - List
	o Access-Control-Allow-Origin - Item		o Access-Control-Allow-Origin - Item
	o Access-Control-Max-Age - Item		o Access-Control-Max-Age - Item
	o Access-Control-Request-Headers - List		o Access-Control-Request-Headers - List
	o Access-Control-Request-Method - Item		o Access-Control-Request-Method - Item
	o Age - Item		o Age - Item
	o Allow - List		o Allow - List
	o ALPN - List		o ALPN - List
	o Alt-Svc - List		o Alt-Svc - Dictionary
	o Alt-Used - Item		o Alt-Used - Item
	o Cache-Control - Dictionary		o Cache-Control - Dictionary
			o Connection - List
	o Content-Encoding - Item		o Content-Encoding - Item
	o Content-Language - List		o Content-Language - List
	o Content-Length - Item		o Content-Length - Item
	o Content-Type - Item		o Content-Type - Item
	o Expect - Item		o Expect - Item
	o Forwarded - List		o Expect-CT - Dictionary
			o Forwarded - Dictionary
	o Host - Item		o Host - Item
			o Keep-Alive - Dictionary
	o Origin - Item		o Origin - Item
	o Pragma - Dictionary		o Pragma - Dictionary
	o Prefer - Dictionary		o Prefer - Dictionary
	o Preference-Applied - Dictionary		o Preference-Applied - Dictionary
	o Retry-After - Item (see caveat below)		o Retry-After - Item (see caveat below)
	skipping to change at page 14, line 17 ¶		skipping to change at page 14, line 4 ¶
	o Prefer - Dictionary		o Prefer - Dictionary
	o Preference-Applied - Dictionary		o Preference-Applied - Dictionary
	o Retry-After - Item (see caveat below)		o Retry-After - Item (see caveat below)
	o Surrogate-Control - Dictionary		o Surrogate-Control - Dictionary
	o TE - List		o TE - List
	o Trailer - List		o Trailer - List
	o Transfer-Encoding - List		o Transfer-Encoding - List
	o Vary - List		o Vary - List
	o X-Content-Type-Options - Item		o X-Content-Type-Options - Item
			o X-XSS-Protection - List
	Note that only the delta-seconds form of Retry-After is supported; a		Note that only the delta-seconds form of Retry-After is supported; a
	Retry-After value containing a http-date will need to be either		Retry-After value containing a http-date will need to be either
	converted into delta-seconds or serialised as a String Literal		converted into delta-seconds or serialised as a String Literal
	(Section 2.1.4).		(Section 2.1.4).
	4.2. Aliased Fields		4.2. Aliased Fields
	The following HTTP field names can have their values represented in		The following HTTP field names can have their values represented in
	Structured headers by mapping them into its data types and then		Structured headers by mapping them into its data types and then
	serialising the resulting Structured Header using an alternative		serialising the resulting Structured Header using an alternative
	skipping to change at page 17, line 19 ¶		skipping to change at page 17, line 4 ¶
	and a Dictionary, respectively. The serialisation is almost		and a Dictionary, respectively. The serialisation is almost
	identical, except that the Expires parameter is always a string (as		identical, except that the Expires parameter is always a string (as
	it can contain a comma), multiple cookie-strings can appear in Set-		it can contain a comma), multiple cookie-strings can appear in Set-
	Cookie, and cookie-pairs are delimited in Cookie by a comma, rather		Cookie, and cookie-pairs are delimited in Cookie by a comma, rather
	than a semicolon.		than a semicolon.
	Set-Cookie: SH-Set-Cookie Cookie: SH-Cookie		Set-Cookie: SH-Set-Cookie Cookie: SH-Cookie
	SH-Set-Cookie: lang=en-US, Expires="Wed, 09 Jun 2021 10:18:14 GMT"		SH-Set-Cookie: lang=en-US, Expires="Wed, 09 Jun 2021 10:18:14 GMT"
	SH-Cookie: SID=31d4d96e407aad42, lang=en-US		SH-Cookie: SID=31d4d96e407aad42, lang=en-US
	ISSUE: explicitly convert Expires to an integer?		ISSUE: explicitly convert Expires to an integer?
	https://github.com/mnot/I-D/issues/308 [10]		https://github.com/mnot/I-D/issues/308 [10] ISSUE: dictionary keys
			cannot contain UC alpha. https://github.com/mnot/I-D/issues/312 [11]
			ISSUE: explicitly allow non-string content. https://github.com/mnot/
			I-D/issues/313 [12]
	5. IANA Considerations		5. IANA Considerations
	ISSUE: todo		ISSUE: todo
	6. Security Considerations		6. Security Considerations
	As is so often the case, having alternative representations of data		As is so often the case, having alternative representations of data
	brings the potential for security weaknesses, when attackers exploit		brings the potential for security weaknesses, when attackers exploit
	the differences between those representations and their handling.		the differences between those representations and their handling.
	skipping to change at page 19, line 7 ¶		skipping to change at page 18, line 46 ¶
	[6] https://github.com/mnot/I-D/issues/305		[6] https://github.com/mnot/I-D/issues/305
	[7] https://github.com/mnot/I-D/issues/305		[7] https://github.com/mnot/I-D/issues/305
	[8] https://github.com/mnot/I-D/issues/305		[8] https://github.com/mnot/I-D/issues/305
	[9] https://github.com/mnot/I-D/issues/307		[9] https://github.com/mnot/I-D/issues/307
	[10] https://github.com/mnot/I-D/issues/308		[10] https://github.com/mnot/I-D/issues/308
			[11] https://github.com/mnot/I-D/issues/312
			[12] https://github.com/mnot/I-D/issues/313
			[13] https://httparchive.org
			[14] https://discuss.httparchive.org/t/working-with-csv-dumps/1835
			Appendix A. Data Supporting Directly Represented Field Mappings
			_RFC EDITOR: please remove this section before publication_
			To help guide decisions about Directly Represented Fields, the HTTP
			response headers captured by the HTTP Archive https://httparchive.org
			[13], representing more than 400,000,000 HTTP exchanges, were parsed
			as Structured Headers using the types listed in Section 4.1, with the
			indicated number of successful header instances, failures, and the
			resulting failure rate:
			o accept: 10060 / 8 = 0%
			o accept-encoding: 37322 / 4 = 0%
			o accept-language: 216051 / 199 = 0%
			o accept-patch: 3 / 0 = 0%
			o accept-ranges: 277520850 / 240940 = 0%
			o access-control-allow-credentials: 17305094 / 16503 = 0%
			o access-control-allow-headers: 10829889 / 19028 = 0%
			o access-control-allow-methods: 15706123 / 12994 = 0%
			o access-control-allow-origin: 79694513 / 209447 = 0%
			o access-control-max-age: 5166126 / 9236 = 0%
			o access-control-request-headers: 48937 / 532 = 1%
			o access-control-request-method: 151702 / 12859 = 7%
			o age: 222024968 / 417140 = 0%
			o allow: 398227 / 567 = 0%
			o alt-svc: 26793600 / 1779280 = 6%
			o cache-control: 373807306 / 4119381 = 1%
			o connection: 188382722 / 244317 = 0%
			o content-encoding: 301904345 / 23368 = 0%
			o content-language: 152252635 / 81760 = 0%
			o content-length: 367973320 / 209032 = 0%
			o content-type: 398500045 / 432427 = 0%
			o expect: 0 / 1 = 100%
			o expect-ct: 26129601 / 30226 = 0%
			o forwarded: 23 / 59 = 71%
			o host: 23003 / 781 = 3%
			o keep-alive: 2 / 0 = 0%
			o origin: 27921 / 1677 = 5%
			o pragma: 219160866 / 890328 = 0%
			o preference-applied: 2 / 59 = 96%
			o retry-after: 680494 / 2832 = 0%
			o surrogate-control: 156370 / 736 = 0%
			o trailer: 1 / 0 = 0%
			o transfer-encoding: 127553768 / 458 = 0%
			o vary: 310245980 / 866776 = 0%
			o x-content-type-options: 94309348 / 608045 = 0%
			o x-xss-protection: 72910239 / 348566 = 0%
			This data set focuses on response headers, although some request
			headers are present (because, the Web).
			Some failure rates are slightly raised because of a bug in the input
			data (see https://discuss.httparchive.org/t/working-with-csv-
			dumps/1835 [14]).
			"preference-applied" has a high failure rate because of the occurence
			of '.' in keys (e.g., "odata.include-annotations")
			"forwarded" has a high failure rate because many senders use the
			unquoted form for IP addresses, which makes integer parsing fail;
			e.g., "for=192.168.1.1"
			The top ten header fields in that data set that were not parsed as
			Directly Represented Fields are:
			o date: 405374834
			o server: 367671207
			o expires: 326515189
			o last-modified: 325777639
			o etag: 271541372
			o location: 180398510
			o via: 179060017
			o x-powered-by: 178075863
			o status: 169014311
			o content-location: 126069665
	Author's Address		Author's Address
	Mark Nottingham		Mark Nottingham
	Fastly		Fastly
	Email: mnot@mnot.net		Email: mnot@mnot.net
	URI: https://www.mnot.net/		URI: https://www.mnot.net/
End of changes. 26 change blocks.
	45 lines changed or deleted		160 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/