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/