draft-mcquistin-augmented-ascii-diagrams-09.txt		draft-mcquistin-augmented-ascii-diagrams-10.txt
	Network Working Group S. McQuistin		Network Working Group S. McQuistin
	Internet-Draft V. Band		Internet-Draft V. Band
	Intended status: Experimental D. Jacob		Intended status: Experimental D. Jacob
	Expires: 28 April 2022 C. S. Perkins		Expires: 7 September 2022 C. S. Perkins
	University of Glasgow		University of Glasgow
	25 October 2021		6 March 2022
	Describing Protocol Data Units with Augmented Packet Header Diagrams		Describing Protocol Data Units with Augmented Packet Header Diagrams
	draft-mcquistin-augmented-ascii-diagrams-09		draft-mcquistin-augmented-ascii-diagrams-10
	Abstract		Abstract
	This document describes a machine-readable format for specifying the		This document describes a machine-readable format for specifying the
	syntax of protocol data units within a protocol specification. This		syntax of protocol data units within a protocol specification. This
	format is comprised of a consistently formatted packet header		format is comprised of a consistently formatted packet header
	diagram, followed by structured explanatory text. It is designed to		diagram, followed by structured explanatory text. It is designed to
	maintain human readability while enabling support for automated		maintain human readability while enabling support for automated
	parser generation from the specification document. This document is		parser generation from the specification document. This document is
	itself an example of how the format can be used.		itself an example of how the format can be used.
	skipping to change at page 1, line 38 ¶		skipping to change at page 1, line 38 ¶
	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 28 April 2022.		This Internet-Draft will expire on 7 September 2022.
	Copyright Notice		Copyright Notice
	Copyright (c) 2021 IETF Trust and the persons identified as the		Copyright (c) 2022 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
	2. Background . . . . . . . . . . . . . . . . . . . . . . . . . 4		2. Background . . . . . . . . . . . . . . . . . . . . . . . . . 4
	2.1. Limitations of Current Packet Format Diagrams . . . . . . 4		2.1. Limitations of Current Packet Format Diagrams . . . . . . 4
	2.2. Formal languages in standards documents . . . . . . . . . 7		2.2. Formal languages in standards documents . . . . . . . . . 7
	3. Design Principles . . . . . . . . . . . . . . . . . . . . . . 7		3. Design Principles . . . . . . . . . . . . . . . . . . . . . . 7
	4. Augmented Packet Header Diagrams . . . . . . . . . . . . . . 10		4. Augmented Packet Header Diagrams . . . . . . . . . . . . . . 10
	4.1. PDUs with Fixed and Variable-Width Fields . . . . . . . . 10		4.1. PDUs with Fixed and Variable-Width Fields . . . . . . . . 10
	4.2. PDUs That Cross-Reference Previously Defined Fields . . . 13		4.2. PDUs That Cross-Reference Previously Defined Fields . . . 13
	4.3. PDUs with Non-Contiguous Fields . . . . . . . . . . . . . 16		4.3. PDUs with Non-Contiguous Fields . . . . . . . . . . . . . 16
	4.4. PDUs with Constraints on Field Values . . . . . . . . . . 16		4.4. PDUs with Constraints on Field Values . . . . . . . . . . 17
	4.5. PDUs with Constraints on Field Sizes . . . . . . . . . . 18		4.5. PDUs with Constraints on Field Sizes . . . . . . . . . . 18
	4.6. PDUs That Extend Sub-Structures . . . . . . . . . . . . . 20		4.6. PDUs That Extend Sub-Structures . . . . . . . . . . . . . 20
	4.7. Storing Data for Parsing . . . . . . . . . . . . . . . . 21		4.7. Storing Data for Parsing . . . . . . . . . . . . . . . . 22
	4.8. Connecting Structures with Functions . . . . . . . . . . 22		4.8. Connecting Structures with Functions . . . . . . . . . . 22
	4.9. Specifying Enumerated Types . . . . . . . . . . . . . . . 23		4.9. Specifying Enumerated Types . . . . . . . . . . . . . . . 23
	4.10. Specifying Protocol Data Units . . . . . . . . . . . . . 24		4.10. Specifying Protocol Data Units . . . . . . . . . . . . . 25
	4.11. Importing PDU Definitions from Other Documents . . . . . 25		4.11. Importing PDU Definitions from Other Documents . . . . . 25
	5. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 25		5. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 25
	6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26		6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26
	7. Security Considerations . . . . . . . . . . . . . . . . . . . 26		7. Security Considerations . . . . . . . . . . . . . . . . . . . 26
	8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 26		8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 26
	9. Informative References . . . . . . . . . . . . . . . . . . . 26		9. Informative References . . . . . . . . . . . . . . . . . . . 26
	Appendix A. ABNF specification . . . . . . . . . . . . . . . . . 28		Appendix A. ABNF specification . . . . . . . . . . . . . . . . . 29
	A.1. Constraint Expressions . . . . . . . . . . . . . . . . . 28		A.1. Constraint Expressions . . . . . . . . . . . . . . . . . 29
	A.2. Augmented packet diagrams . . . . . . . . . . . . . . . . 29		A.2. Augmented packet diagrams . . . . . . . . . . . . . . . . 29
	Appendix B. Tooling & source code . . . . . . . . . . . . . . . 29		Appendix B. Tooling & source code . . . . . . . . . . . . . . . 29
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 29		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30
	1. Introduction		1. Introduction
	Packet header diagrams have become a widely used format for		Packet header diagrams have become a widely used format for
	describing the syntax of binary protocols. In otherwise largely		describing the syntax of binary protocols. In otherwise largely
	textual documents, they allow for the visualisation of packet		textual documents, they allow for the visualisation of packet
	formats, reducing human error, and aiding in the implementation of		formats, reducing human error, and aiding in the implementation of
	parsers for the protocols that they specify.		parsers for the protocols that they specify.
	Figure 1 gives an example of how packet header diagrams are used to		Figure 1 gives an example of how packet header diagrams are used to
	skipping to change at page 10, line 49 ¶		skipping to change at page 10, line 49 ¶
	a field is either derived from the value of some previous field, or		a field is either derived from the value of some previous field, or
	is unspecified and inferred from the total size of the packet and the		is unspecified and inferred from the total size of the packet and the
	size of the other fields.		size of the other fields.
	To ensure that there is no ambiguity, a PDU description can contain		To ensure that there is no ambiguity, a PDU description can contain
	only one field whose length is unspecified. The length of a single		only one field whose length is unspecified. The length of a single
	field, where all other fields are of known (but perhaps variable)		field, where all other fields are of known (but perhaps variable)
	length, can be inferred from the total size of the containing PDU.		length, can be inferred from the total size of the containing PDU.
	A PDU description is introduced by the exact phrase "A/An _______ is		A PDU description is introduced by the exact phrase "A/An _______ is
	formatted as follows" within a paragraph. This is followed by the		formatted as follows" within a paragraph. Optionally, this phrase
	PDU description itself, as a packet diagram within an <artwork>		can include a note or comment, delimited by commas, immediately
	element (itself optionally within a <figure> element) in the XML		following the PDU name. That is, "A/An _______, with an optional
			comment, is formatted as follows" can be used to introduce a PDU
			description. The introductory phrase is followed by the PDU
			description itself, as a packet diagram within an <artwork> element
			(itself optionally within a <figure> element) in the XML
	representation, starting with a header line to show the bit width of		representation, starting with a header line to show the bit width of
	the diagram. The description of the fields follows the diagram, as		the diagram. The description of the fields follows the diagram, as
	an XML list (either <dl> or hanging <list>), after a paragraph that		an XML list (either <dl> or hanging <list>), after a paragraph that
	begins with the text "where:".		begins with the text "where:".
	PDU names must be unique, both within a document, and across all		PDU names must be unique, both within a document, and across all
	documents that are linked together (i.e., using the structured		documents that are linked together (i.e., using the structured
	language defined in Section 4.11).		language defined in Section 4.11).
	Each field is defined by a structured text definition and a prose		Each field is defined by a structured text definition and a prose
	description. The structured text definition comprises the field name		description. The structured text definition comprises the field name
	and an optional short name in parenthesis. These are followed by a		and an optional short name in parenthesis. These are followed by a
	colon, the field length, an optional presence expression (described		colon, the field length, an optional presence expression (described
	in Section 4.2), and a terminating period. Field names cannot be the		in Section 4.2), and a terminating period. Text following the
	same as a previously defined PDU name, and must be unique within a		terminating period is not parsed, and this space can be used for
	given structure definition. The structured text definition is given		optional notes or comments. Field names cannot be the same as a
	either in a <dt> tag (if using a <dl>) or as the "hangText" (if using		previously defined PDU name, and must be unique within a given
	a hanging <list>) of a <t> element. The field's prose description is		structure definition. The structured text definition is given either
			in a <dt> tag (if using a <dl>) or as the "hangText" (if using a
			hanging <list>) of a <t> element. The field's prose description is
	given in the following <dd> element or within the same <t> element.		given in the following <dd> element or within the same <t> element.
	Prose descriptions may include structured text (e.g., as defined in		Prose descriptions may include structured text (e.g., as defined in
	Section 4.7).		Section 4.7).
	For example, this can be illustrated using the IPv4 Header Format		For example, this can be illustrated using the IPv4 Header Format
	[RFC791]. An IPv4 Header is formatted as follows:		[RFC791]. An IPv4 Header is formatted as follows:
	0 1 2 3		0 1 2 3
	0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1		0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
	+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+		+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
	skipping to change at page 15, line 45 ¶		skipping to change at page 16, line 10 ¶
	would be a cross-referenced structure. This is not shown here for		would be a cross-referenced structure. This is not shown here for
	brevity.]		brevity.]
	Payload. The length of the Payload is not specified, and hence needs		Payload. The length of the Payload is not specified, and hence needs
	to be inferred from the total length of the packet and the lengths		to be inferred from the total length of the packet and the lengths
	of the known fields. There can only be one field of unspecified		of the known fields. There can only be one field of unspecified
	size in a PDU. Fields where the length is not specified may also		size in a PDU. Fields where the length is not specified may also
	denote this with the phrase "variable length" in place of the		denote this with the phrase "variable length" in place of the
	length definition.		length definition.
	Padding: PC bytes; present only when (P == 1) && (PC > 0). This is a		Padding: PC bytes; present only when (P == 1) && (PC > 0). Note
	variable size field, with size dependent on a later field in the		that PC is defined below. This is a variable size field, with size
	packet. Fields can only depend on the value of a later field if		dependent on a later field in the packet. Fields can only depend
	they follow a field with unspecified size.		on the value of a later field if they follow a field with
			unspecified size.
			The comment (i.e., "Note that PC is defined below") following the
			expression is not parsed.
	Padding Count (PC): 1 byte; present only when P == 1. This is a		Padding Count (PC): 1 byte; present only when P == 1. This is a
	fixed-width field, as previously discussed.		fixed-width field, as previously discussed.
	4.3. PDUs with Non-Contiguous Fields		4.3. PDUs with Non-Contiguous Fields
	In some binary formats, fields are striped across multiple non-		In some binary formats, fields are striped across multiple non-
	contiguous bits. This is often to allow for backwards compatibility		contiguous bits. This is often to allow for backwards compatibility
	with previous definitions of the same fields in earlier documents:		with previous definitions of the same fields in earlier documents:
	striping in this way allows for careful use of the possible range of		striping in this way allows for careful use of the possible range of
	skipping to change at page 23, line 41 ¶		skipping to change at page 23, line 51 ¶
	In addition to the use of the sub-structures, it is desirable to be		In addition to the use of the sub-structures, it is desirable to be
	able to define a type that may take the value of one of a set of		able to define a type that may take the value of one of a set of
	alternative structures.		alternative structures.
	The alternative structures that comprise an enumerated type are		The alternative structures that comprise an enumerated type are
	identified using the exact phrase "The <enumerated type name> is one		identified using the exact phrase "The <enumerated type name> is one
	of: <list of structure names>" where the list of structure names is a		of: <list of structure names>" where the list of structure names is a
	comma separated list (with the last element, if there is more than		comma separated list (with the last element, if there is more than
	one element, preceded by 'or'), each optionally preceded by "a" or		one element, preceded by 'or'), each optionally preceded by "a" or
	"an". The structure names must be defined within the document or a		"an". The structure names must be defined within the document or a
	linked document.		linked document. Optionally, this phrase can include a note or
			comment, delimited by commas, immediately following the enumerated
			type name. That is, "The <enumerated type name>, with an optional
			comment, is one of: <list of structure names>" can be used to define
			an enumerated type.
	Where an enumerated type has only two variants, an alternative phrase		Where an enumerated type has only two variants, an alternative phrase
	can be used: "The <enumerated type name> is either a <variant 1 name>		can be used: "The <enumerated type name> is either a <variant 1 name>
	or <variant 2 name>". The names of the variants must be defined		or <variant 2 name>". The names of the variants must be defined
	within the document or a linked document.		within the document or a linked document. An optional note or
			comment can be included with this alternative phrasing: "The
			<enumerated type name>, with an optional comment, is either a
			<variant 1 name> or <variant 2 name>" can be used.
	An EOL Option is formatted as follows:		An EOL Option is formatted as follows:
	0		0
	0 1 2 3 4 5 6 7		0 1 2 3 4 5 6 7
	+-+-+-+-+-+-+-+-+		+-+-+-+-+-+-+-+-+
	| 0 |		| 0 |
	+-+-+-+-+-+-+-+-+		+-+-+-+-+-+-+-+-+
	where:		where:
	skipping to change at page 24, line 32 ¶		skipping to change at page 24, line 45 ¶
	+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+		+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
	where:		where:
	Option Kind (Kind): 1 byte; Kind == 3. This is a fixed-width field,		Option Kind (Kind): 1 byte; Kind == 3. This is a fixed-width field,
	with a value constraint, as previously described.		with a value constraint, as previously described.
	Option Length (Length): 1 byte; Length == 3. This is a fixed-width		Option Length (Length): 1 byte; Length == 3. This is a fixed-width
	field, with a value constraint, as previously described.		field, with a value constraint, as previously described.
	Window Scale: 1 byte. This is a fixed-width field, as previously		Window Scale Factor: 1 byte. This is a fixed-width field, as
	described.		previously described.
	A TCP Option is either an EOL Option or a Window Scale Factor Option.		A TCP Option is either an EOL Option or a Window Scale Factor Option.
	4.10. Specifying Protocol Data Units		4.10. Specifying Protocol Data Units
	A document will set out different structures that are not, on their		A document will set out different structures that are not, on their
	own, protocol data units. To capture the parsing or serialisation of		own, protocol data units. To capture the parsing or serialisation of
	a protocol, it is necessary to be able to identify or construct those		a protocol, it is necessary to be able to identify or construct those
	packets that are valid PDUs. As a result, it is necessary for the		packets that are valid PDUs. As a result, it is necessary for the
	document to identify those structures that are PDUs.		document to identify those structures that are PDUs.
	skipping to change at page 28, line 35 ¶		skipping to change at page 28, line 45 ¶
	"Describing TCP with Augmented Packet Header Diagrams",		"Describing TCP with Augmented Packet Header Diagrams",
	Work in Progress, Internet-Draft, draft-mcquistin-		Work in Progress, Internet-Draft, draft-mcquistin-
	augmented-tcp-example-02, 25 October 2021,		augmented-tcp-example-02, 25 October 2021,
	<http://www.ietf.org/internet-drafts/draft-mcquistin-		<http://www.ietf.org/internet-drafts/draft-mcquistin-
	augmented-tcp-example-02.txt>.		augmented-tcp-example-02.txt>.
	[draft-mcquistin-quic-augmented-diagrams]		[draft-mcquistin-quic-augmented-diagrams]
	McQuistin, S., Band, V., Jacob, D., and C. S. Perkins,		McQuistin, S., Band, V., Jacob, D., and C. S. Perkins,
	"Describing QUIC's Protocol Data Units with Augmented		"Describing QUIC's Protocol Data Units with Augmented
	Packet Header Diagrams", Work in Progress, Internet-Draft,		Packet Header Diagrams", Work in Progress, Internet-Draft,
	draft-mcquistin-quic-augmented-diagrams-05, 25 October		draft-mcquistin-quic-augmented-diagrams-04, 25 October
	2021, <http://www.ietf.org/internet-drafts/draft-		2021, <http://www.ietf.org/internet-drafts/draft-
	mcquistin-quic-augmented-diagrams-05.txt>.		mcquistin-quic-augmented-diagrams-05.txt>.
	[draft-ietf-tcpm-rfc793bis]		[draft-ietf-tcpm-rfc793bis]
	Eddy, W., "Transmission Control Protocol (TCP)		Eddy, W., "Transmission Control Protocol (TCP)
	Specification", Work in Progress, Internet-Draft, draft-		Specification", Work in Progress, Internet-Draft, draft-
	ietf-tcpm-rfc793bis-25, 7 September 2021,		ietf-tcpm-rfc793bis-27, 22 February 2022,
	<http://www.ietf.org/internet-drafts/draft-ietf-tcpm-		<http://www.ietf.org/internet-drafts/draft-ietf-tcpm-
	rfc793bis-25.txt>.		rfc793bis-27.txt>.
	Appendix A. ABNF specification		Appendix A. ABNF specification
	A.1. Constraint Expressions		A.1. Constraint Expressions
	constant = %x31-39 *(%x30-39) ; natural numbers without leading 0s		constant = %x31-39 *(%x30-39) ; natural numbers without leading 0s
	short-name = ALPHA *(ALPHA / DIGIT / "-" / "_")		short-name = ALPHA *(ALPHA / DIGIT / "-" / "_")
	name = short-name *(" " short-name)		name = short-name *(" " short-name)
	sp = [" "] ; optional space in expression		sp = [" "] ; optional space in expression
	bool-expr = "(" sp bool-expr sp ")" /		bool-expr = "(" sp bool-expr sp ")" /
	"!" sp bool-expr /		"!" sp bool-expr /
	bool-expr sp bool-op sp bool-expr /		bool-expr sp bool-op sp bool-expr /
	bool-expr sp "?" sp expr sp ":" sp expr /		bool-expr sp "?" sp expr sp ":" sp expr /
	expr sp cmp-op sp expr		expr sp cmp-op sp expr
	bool-op = "&&" / "||"		bool-op = "&&" / "||"
End of changes. 21 change blocks.
	33 lines changed or deleted		51 lines changed or added
This html diff was produced by rfcdiff 1.46. The latest version is available from http://tools.ietf.org/tools/rfcdiff/