draft-ietf-httpbis-sfbis-03.txt		draft-ietf-httpbis-sfbis-latest.txt
	HTTP Working Group M. Nottingham		HTTP Working Group M. Nottingham
	Internet-Draft Cloudflare		Internet-Draft Cloudflare
	Obsoletes: 8941 (if approved) P. Kamp		Obsoletes: 8941 (if approved) P. Kamp
	Intended status: Standards Track The Varnish Cache Project		Intended status: Standards Track The Varnish Cache Project
	Expires: February 4, 2024 August 3, 2023		Expires: March 15, 2024 September 12, 2023
	Structured Field Values for HTTP		Structured Field Values for HTTP
	draft-ietf-httpbis-sfbis-03		draft-ietf-httpbis-sfbis-latest
	Abstract		Abstract
	This document describes a set of data types and associated algorithms		This document describes a set of data types and associated algorithms
	that are intended to make it easier and safer to define and handle		that are intended to make it easier and safer to define and handle
	HTTP header and trailer fields, known as "Structured Fields",		HTTP header and trailer fields, known as "Structured Fields",
	"Structured Headers", or "Structured Trailers". It is intended for		"Structured Headers", or "Structured Trailers". It is intended for
	use by specifications of new HTTP fields that wish to use a common		use by specifications of new HTTP fields that wish to use a common
	syntax that is more restrictive than traditional HTTP field values.		syntax that is more restrictive than traditional HTTP field values.
	skipping to change at page 2, line 7 ¶		skipping to change at page 2, line 7 ¶
	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 February 4, 2024.		This Internet-Draft will expire on March 15, 2024.
	Copyright Notice		Copyright Notice
	Copyright (c) 2023 IETF Trust and the persons identified as the		Copyright (c) 2023 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
	skipping to change at page 3, line 33 ¶		skipping to change at page 3, line 33 ¶
	4.2.10. Parsing a Display String . . . . . . . . . . . . . . 35		4.2.10. Parsing a Display String . . . . . . . . . . . . . . 35
	5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36		5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36
	6. Security Considerations . . . . . . . . . . . . . . . . . . . 36		6. Security Considerations . . . . . . . . . . . . . . . . . . . 36
	7. References . . . . . . . . . . . . . . . . . . . . . . . . . 37		7. References . . . . . . . . . . . . . . . . . . . . . . . . . 37
	7.1. Normative References . . . . . . . . . . . . . . . . . . 37		7.1. Normative References . . . . . . . . . . . . . . . . . . 37
	7.2. Informative References . . . . . . . . . . . . . . . . . 37		7.2. Informative References . . . . . . . . . . . . . . . . . 37
	Appendix A. Frequently Asked Questions . . . . . . . . . . . . . 38		Appendix A. Frequently Asked Questions . . . . . . . . . . . . . 38
	A.1. Why Not JSON? . . . . . . . . . . . . . . . . . . . . . . 38		A.1. Why Not JSON? . . . . . . . . . . . . . . . . . . . . . . 38
	Appendix B. Implementation Notes . . . . . . . . . . . . . . . . 39		Appendix B. Implementation Notes . . . . . . . . . . . . . . . . 39
	Appendix C. ABNF . . . . . . . . . . . . . . . . . . . . . . . . 40		Appendix C. ABNF . . . . . . . . . . . . . . . . . . . . . . . . 40
	Appendix D. Changes from RFC 8941 . . . . . . . . . . . . . . . 42		Appendix D. Changes from RFC 8941 . . . . . . . . . . . . . . . 41
	Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 42		Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 42
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42
	1. Introduction		1. Introduction
	Specifying the syntax of new HTTP header (and trailer) fields is an		Specifying the syntax of new HTTP header (and trailer) fields is an
	onerous task; even with the guidance in Section 16.3.2 of [HTTP],		onerous task; even with the guidance in Section 16.3.2 of [HTTP],
	there are many decisions -- and pitfalls -- for a prospective HTTP		there are many decisions -- and pitfalls -- for a prospective HTTP
	field author.		field author.
	skipping to change at page 15, line 52 ¶		skipping to change at page 15, line 52 ¶
	because Unicode has processing considerations (e.g., normalization)		because Unicode has processing considerations (e.g., normalization)
	and security considerations (e.g., homograph attacks) that make it		and security considerations (e.g., homograph attacks) that make it
	more difficult to handle correctly.		more difficult to handle correctly.
	Note that Display Strings do not indicate the language used in the		Note that Display Strings do not indicate the language used in the
	value; that can be done separately if necessary (e.g., with a		value; that can be done separately if necessary (e.g., with a
	parameter).		parameter).
	For example:		For example:
	Example-DisplayString: %"This is intended for display to %C3%BCsers."		Example-DisplayString: %"This is intended for display to %c3%bcsers."
	See Section 6 for additional security considerations when handling		See Section 6 for additional security considerations when handling
	Display Strings.		Display Strings.
	4. Working with Structured Fields in HTTP		4. Working with Structured Fields in HTTP
	This section defines how to serialize and parse Structured Fields in		This section defines how to serialize and parse Structured Fields in
	textual HTTP field values and other encodings compatible with them		textual HTTP field values and other encodings compatible with them
	(e.g., in HTTP/2 [RFC9113] before compression with HPACK [HPACK]).		(e.g., in HTTP/2 [RFC9113] before compression with HPACK [HPACK]).
	4.1. Serializing Structured Fields		4.1. Serializing Structured Fields
	skipping to change at page 23, line 40 ¶		skipping to change at page 23, line 40 ¶
	with input_date (Section 4.1.4).		with input_date (Section 4.1.4).
	3. Return output.		3. Return output.
	4.1.11. Serializing a Display String		4.1.11. Serializing a Display String
	Given a sequence of Unicode codepoints as input_sequence, return an		Given a sequence of Unicode codepoints as input_sequence, return an
	ASCII string suitable for use in an HTTP field value.		ASCII string suitable for use in an HTTP field value.
	1. If input_sequence is not a sequence of Unicode codepoints, fail		1. If input_sequence is not a sequence of Unicode codepoints, fail
	parsing.		serialization.
	2. Let byte_array be the result of applying UTF-8 encoding [UTF8] to		2. Let byte_array be the result of applying UTF-8 encoding [UTF8] to
	input_sequence.		input_sequence.
	3. Let encoded_string be a string containing "%" followed by DQUOTE.		3. Let encoded_string be a string containing "%" followed by DQUOTE.
	4. For each byte in byte_array:		4. For each byte in byte_array:
	1. If byte is %x25 ("%"), %x22 (DQUOTE), or in the ranges		1. If byte is %x25 ("%"), %x22 (DQUOTE), or in the ranges
	%x00-1f or %x7f-ff:		%x00-1f or %x7f-ff:
	1. Append "%" to encoded_string.		1. Append "%" to encoded_string.
	2. Let encoded_byte be the result of applying base16		2. Let encoded_byte be the result of applying base16
	encoding (Section 8 of [RFC4648]) to byte.		encoding (Section 8 of [RFC4648]) to byte, with any
			alphabetic characters converted to lowercase.
	3. Append encoded_byte to encoded_string.		3. Append encoded_byte to encoded_string.
	2. Otherwise, decode byte as an ASCII character and append the		2. Otherwise, decode byte as an ASCII character and append the
	result to encoded_string.		result to encoded_string.
	5. Append DQUOTE to encoded_string.		5. Append DQUOTE to encoded_string.
	6. Return encoded_string.		6. Return encoded_string.
	skipping to change at page 35, line 31 ¶		skipping to change at page 35, line 31 ¶
	2. If char is in the range %x00-1f or %x7f-ff (i.e., it is not		2. If char is in the range %x00-1f or %x7f-ff (i.e., it is not
	in VCHAR or SP), fail parsing.		in VCHAR or SP), fail parsing.
	3. If char is "%":		3. If char is "%":
	1. Let octet_hex be the result of consuming two characters		1. Let octet_hex be the result of consuming two characters
	from input_string. If there are not two characters, fail		from input_string. If there are not two characters, fail
	parsing.		parsing.
	2. Let octet be the result of hex decoding octet_hex		2. If octet_hex contains characters outside the range
	(Section 8 of [RFC4648]), in a case-insensitive fashion.		%x30-39 or %x61-66 (i.e., it is not in 0-9 or lowercase
	If decoding fails, fail parsing.		a-f), fail parsing.
	3. Append octet to byte_array.		3. Let octet be the result of hex decoding octet_hex
			(Section 8 of [RFC4648]).
			4. Append octet to byte_array.
	4. If char is DQUOTE:		4. If char is DQUOTE:
	1. Let unicode_sequence be the result of decoding byte_array		1. Let unicode_sequence be the result of decoding byte_array
	as a UTF-8 string [UTF8]. Fail parsing if decoding		as a UTF-8 string [UTF8]. Fail parsing if decoding
	fails.		fails.
	2. Return unicode_sequence.		2. Return unicode_sequence.
	5. Otherwise, if char is not "%" or DQUOTE:		5. Otherwise, if char is not "%" or DQUOTE:
	skipping to change at page 40, line 9 ¶		skipping to change at page 40, line 11 ¶
	Implementations are allowed to limit the size of different		Implementations are allowed to limit the size of different
	structures, subject to the minimums defined for each type. When a		structures, subject to the minimums defined for each type. When a
	structure exceeds an implementation limit, that structure fails		structure exceeds an implementation limit, that structure fails
	parsing or serialization.		parsing or serialization.
	Appendix C. ABNF		Appendix C. ABNF
	This section uses the Augmented Backus-Naur Form (ABNF) notation		This section uses the Augmented Backus-Naur Form (ABNF) notation
	[RFC5234] to illustrate expected syntax of Structured Fields.		[RFC5234] to illustrate expected syntax of Structured Fields.
			However, it cannot be used to validate their syntax, because it does
			not capture all requirements.
	This section is non-normative. If there is disagreement between the		This section is non-normative. If there is disagreement between the
	parsing algorithms and ABNF, the specified algorithms take		parsing algorithms and ABNF, the specified algorithms take
	precedence.		precedence.
	sf-list = list-member *( OWS "," OWS list-member )		sf-list = list-member *( OWS "," OWS list-member )
	list-member = sf-item / inner-list		list-member = sf-item / inner-list
	inner-list = "(" *SP [ sf-item *( 1*SP sf-item ) *SP ] ")"
	parameters
	parameters = *( ";" *SP parameter )
	parameter = param-key [ "=" param-value ]
	param-key = key
	key = ( lcalpha / "*" )
	*( lcalpha / DIGIT / "_" / "-" / "." / "*" )
	lcalpha = %x61-7A ; a-z
	param-value = bare-item
	sf-dictionary = dict-member *( OWS "," OWS dict-member )
	dict-member = member-key ( parameters / ( "=" member-value ))
	member-key = key
	member-value = sf-item / inner-list
	sf-item = bare-item parameters
	bare-item = sf-integer / sf-decimal / sf-string / sf-token
	/ sf-binary / sf-boolean / sf-date
	sf-integer = ["-"] 1*15DIGIT		inner-list = "(" *SP [ sf-item *( 1*SP sf-item ) *SP ] ")"
			parameters
	sf-decimal = ["-"] 1*12DIGIT "." 1*3DIGIT		parameters = *( ";" *SP parameter )
			parameter = param-key [ "=" param-value ]
			param-key = key
			key = ( lcalpha / "*" )
			*( lcalpha / DIGIT / "_" / "-" / "." / "*" )
			lcalpha = %x61-7A ; a-z
			param-value = bare-item
	sf-string = DQUOTE *chr DQUOTE		sf-dictionary = dict-member *( OWS "," OWS dict-member )
	chr = unescaped / escaped		dict-member = member-key ( parameters / ( "=" member-value ))
	unescaped = %x20-21 / %x23-5B / %x5D-7E		member-key = key
	escaped = "\" ( DQUOTE / "\" )		member-value = sf-item / inner-list
	sf-token = ( ALPHA / "*" ) *( tchar / ":" / "/" )		sf-item = bare-item parameters
			bare-item = sf-integer / sf-decimal / sf-string / sf-token
			/ sf-binary / sf-boolean / sf-date / sf-displaystring
	sf-binary = ":" *(base64) ":"		sf-integer = ["-"] 1*15DIGIT
	base64 = ALPHA / DIGIT / "+" / "/" / "="		sf-decimal = ["-"] 1*12DIGIT "." 1*3DIGIT
			sf-string = DQUOTE *( unescaped / "%" / bs-escaped ) DQUOTE
			sf-token = ( ALPHA / "*" ) *( tchar / ":" / "/" )
			sf-binary = ":" base64 ":"
			sf-boolean = "?" ( "0" / "1" )
			sf-date = "@" sf-integer
			sf-displaystring = "%" DQUOTE *( unescaped / "\" / pct-encoded ) DQUOTE
	sf-boolean = "?" boolean		base64 = *( ALPHA / DIGIT / "+" / "/" ) *"="
	boolean = "0" / "1"
	sf-date = "@" sf-integer		unescaped = %x20-21 / %x23-24 / %x26-5B / %x5D-7E
			bs-escaped = "\" ( DQUOTE / "\" )
	sf-displaystring = "%" DQUOTE *uchr DQUOTE		pct-encoded = "%" lc-hexdig lc-hexdig
	uchr = chr / uescaped		lc-hexdig = DIGIT / %x61-66 ; 0-9, a-f
	uescaped = "%" HEXDIG HEXDIG
	Appendix D. Changes from RFC 8941		Appendix D. Changes from RFC 8941
	This revision of the Structured Field Values for HTTP specification		This revision of the Structured Field Values for HTTP specification
	has made the following changes:		has made the following changes:
	o Added the Date structured type. (Section 3.3.7)		o Added the Date structured type. (Section 3.3.7)
	o Stopped encouraging use of ABNF in definitions of new structured		o Stopped encouraging use of ABNF in definitions of new structured
	fields. (Section 2)		fields. (Section 2)
	o Moved ABNF to an informative appendix. (Appendix C)		o Moved ABNF to an informative appendix. (Appendix C)
	o Added a "Structured Type" column to the HTTP Field Name Registry.		o Added a "Structured Type" column to the HTTP Field Name Registry.
	(Section 5)		(Section 5)
	o Refined parse failure handling. (Section 4.2)		o Refined parse failure handling. (Section 4.2)
End of changes. 20 change blocks.
	49 lines changed or deleted		48 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/