< draft-mcquistin-augmented-ascii-diagrams-00.txt   draft-mcquistin-augmented-ascii-diagrams-01.txt >
Network Working Group S. McQuistin Network Working Group S. McQuistin
Internet-Draft V. Band Internet-Draft V. Band
Intended status: Informational C. Perkins Intended status: Experimental C. S. Perkins
Expires: 9 January 2020 University of Glasgow Expires: 6 May 2020 University of Glasgow
8 July 2019 3 November 2019
Fully Specifying Protocol Parsing with Augmented ASCII Diagrams Describing Protocol Data Units with Augmented Packet Header Diagrams
draft-mcquistin-augmented-ascii-diagrams-00 draft-mcquistin-augmented-ascii-diagrams-01
Abstract Abstract
This document describes a machine-readable format for fully This document describes a machine-readable format for specifying the
specifying the process by which a protocol can be parsed. This syntax of protocol data units within a protocol specification. This
format combines a consistent ASCII packet diagram format with the use format is comprised of a consistently formatted packet header
of structured text, maintaining human readability while enabling diagram, followed by structured explanatory text. It is designed to
support for machine parsing. This document is itself an example of maintain human readability while enabling support for automated
how this format can be used. parser generation from the specification document. This document is
itself an example of how the format can be used.
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 9 January 2020. This Internet-Draft will expire on 6 May 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 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 Simplified BSD License text
as described in Section 4.e of the Trust Legal Provisions and are as 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 Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Background . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Background . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Limitations of current ASCII packet diagrams usage . . . 3 2.1. Limitations of Current Packet Format Diagrams . . . . . . 4
2.2. Formal languages in standards documents . . . . . . . . . 6 2.2. Formal languages in standards documents . . . . . . . . . 6
3. Design Principles . . . . . . . . . . . . . . . . . . . . . . 6 3. Design Principles . . . . . . . . . . . . . . . . . . . . . . 7
4. Augmented ASCII Packet Header Diagrams . . . . . . . . . . . 8 4. Augmented Packet Header Diagrams . . . . . . . . . . . . . . 8
4.1. Fixed-width Field Format . . . . . . . . . . . . . . . . 8 4.1. PDUs with Fixed and Variable-Width Fields . . . . . . . . 9
4.2. Variable-width Field Format . . . . . . . . . . . . . . . 10 4.2. PDUs That Cross-Reference Previously Defined
4.3. Cross-referencing and Sequences Format . . . . . . . . . 11 Fields . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.4. Optional Field Format . . . . . . . . . . . . . . . . . . 12 4.3. PDUs with Non-Contiguous Fields . . . . . . . . . . . . . 14
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 6. Security Considerations . . . . . . . . . . . . . . . . . . . 14
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14
8. Informative References . . . . . . . . . . . . . . . . . . . 13 8. Informative References . . . . . . . . . . . . . . . . . . . 15
Appendix A. ABNF specification . . . . . . . . . . . . . . . . . 14 Appendix A. ABNF specification . . . . . . . . . . . . . . . . . 16
A.1. Constraint Expressions . . . . . . . . . . . . . . . . . 14 A.1. Constraint Expressions . . . . . . . . . . . . . . . . . 16
A.2. Augmented ASCII diagrams . . . . . . . . . . . . . . . . 14 A.2. Augmented packet diagrams . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 Appendix B. Source code repository . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction 1. Introduction
ASCII packet header diagrams have become the de-facto 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. Given their widespread parsers for the protocols that they specify.
use, and relatively structured form, ASCII packet header diagrams
provide a good base from which to develop a format that supports the
automatic generation of parser code from protocol standards
documents.
There are two broad issues with the existing ASCII packet header Figure 1 gives an example of how packet header diagrams are used to
diagrams that need to be addressed to enable machine-readability. define binary protocol formats. The format has an obvious structure:
First, their use, while sufficiently consistent for human the diagram clearly delineates each field, showing its width and its
readability, contains enough variation to make machine parsing position within the header. This type of diagram is designed for
difficult: different documents tend to use subtly different formats human readers, but is consistent enough that it should be possible to
and conventions. Second, ASCII packet header diagrams alone do not develop a tool that generates a parser for the packet format from the
fully capture the parsing process for protocols, requiring diagram.
supplementary text. To support machine parsing, this supplementary
text must be consistently structured.
This document describes a consistent ASCII packet header format and : 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
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Source Port | Destination Port |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Sequence Number |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Acknowledgment Number |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Data | |U|A|P|R|S|F| |
: | Offset| Reserved |R|C|S|S|Y|I| Window |
: | | |G|K|H|T|N|N| |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Checksum | Urgent Pointer |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Options | Padding |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | data |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 1: TCP's header format (from [RFC793])
Unfortunately, the format of such packet diagrams varies both within
and between documents. This variation makes it difficult to build
tools to generate parsers from the specifications. Better tooling
could be developed if protocol specifications adopted a consistent
format for their packet descriptions. Indeed, this underpins the
format described by this draft: we want to retain the benefits that
packet header diagrams provide, while identifying the benefits of
adopting a consistent format.
This document describes a consistent packet header diagram format and
accompanying structured text constructs that allow for the parsing accompanying structured text constructs that allow for the parsing
process of protocol headers to be fully specified. This provides process of protocol headers to be fully specified. This provides
support for the automatic generation of parser code. Broad design support for the automatic generation of parser code. Broad design
principles, that seek to maintain the primacy of human readability principles, that seek to maintain the primacy of human readability
and flexibility in authorship, are described, before the format and flexibility in authorship, are described, before the format
itself is given. itself is given.
This document is itself an example of the approach that it describes, This document is itself an example of the approach that it describes,
with the ASCII packet diagrams and structured text format described with the packet header diagrams and structured text format described
by example. by example.
This draft describes early work. As consensus builds around the This draft describes early work. As consensus builds around the
particular syntax of the format described, both a formal ABNF particular syntax of the format described, both a formal ABNF
specification and code that parses it (and, as described above, this specification and code that parses it (and, as described above, this
document) will be provided. document) will be provided.
: The RESET_STREAM frame is as follows:
:
: 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
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Stream ID (i) ...
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Application Error Code (16) |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Final Size (i) ...
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
:
: RESET_STREAM frames contain the following fields:
:
: Stream ID: A variable-length integer encoding of the Stream ID
: of the stream being terminated.
:
: Application Protocol Error Code: A 16-bit application protocol
: error code (see Section 20.1) which indicates why the stream
: is being closed.
:
: Final Size: A variable-length integer indicating the final size
: of the stream by the RESET_STREAM sender, in unit of bytes.
Figure 2: QUIC's RESET_STREAM frame format (from [QUIC-TRANSPORT])
2. Background 2. Background
This section begins by considering how ASCII packet header diagrams This section begins by considering how packet header diagrams are
are used in existing documents. This exposes the limitations that used in existing documents. This exposes the limitations that the
the current usage has in terms of machine-readability, guiding the current usage has in terms of machine-readability, guiding the design
design of the format that this document proposes. of the format that this document proposes.
While this document focuses on the machine-readability of packet While this document focuses on the machine-readability of packet
header diagrams, this section also discusses the use of other format diagrams, this section also discusses the use of other
structured or formal languages within IETF documents. Considering structured or formal languages within IETF documents. Considering
how and why these languages are used provides an instructive contrast how and why these languages are used provides an instructive contrast
to the relatively incremental approach proposed here. to the relatively incremental approach proposed here.
2.1. Limitations of current ASCII packet diagrams usage 2.1. Limitations of Current Packet Format Diagrams
ASCII packet header diagrams are commonplace in the IETF standards
documents for binary protocols. While there is no standard for how
these diagrams should be formatted, they have a broadly similar
structure, where the layout of a protocol data unit (PDU) or
structure is given in an ASCII diagram, and a description list of the
fields that it contains are given immediately below. An example of
this format is given in Figure 1.
The RESET_STREAM frame is as follows:
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Stream ID (i) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Application Error Code (16) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Final Size (i) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
RESET_STREAM frames contain the following fields:
Stream ID: A variable-length integer encoding of the Stream ID of
the stream being terminated.
Application Protocol Error Code: A 16-bit application protocol
error code (see Section 20.1) which indicates why the stream is
being closed.
Final Size: A variable-length integer indicating the final size
of the stream by the RESET_STREAM sender, in unit of bytes.
Figure 1: QUIC's RESET_STREAM frame format (from [QUIC-TRANSPORT]) Packet header diagrams are frequently used in IETF standards to
describe the format of binary protocols. While there is no standard
for how these diagrams should be formatted, they have a broadly
similar structure, where the layout of a protocol data unit (PDU) or
structure is shown in diagrammatic form, followed by a description
list of the fields that it contains. An example of this format,
taken from the QUIC specification, is given in Figure 2.
However, these diagrams, and their accompanying descriptions, are These packet header diagrams, and the accompanying descriptions, are
formatted for human readers rather than for machine parsing. As a formatted for human readers rather than for automated processing. As
result, while there is broad consistency in how ASCII packet diagrams a result, while there is rough consistency in how packet header
are formatted, there are a number of limitations that are prohibitive diagrams are formatted, there are a number of limitations that make
to machine parsing: them difficult to work with programmatically:
Inconsistent syntax: There are two classes of consistency that are Inconsistent syntax: There are two classes of consistency that are
required for parsability: internal consistency, within a document needed to support automated processing of specifications: internal
or diagram, and external consistency, across all documents. Given consistency within a diagram or document, and external consistency
that ASCII packet diagrams are formatted for human readers, rather across all documents.
than for machine parsing, there is sufficient variability in how
they are formatted that parsing is difficult.
The format of the "Relay Source Port Option" is shown below:
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| OPTION_RELAY_PORT | Option-Len |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Downstream Source Port |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Where:
Option-Code: OPTION_RELAY_PORT. 16-bit value, 135.
Option-Len: 16-bit value to be set to 2.
Downstream Source Port: 16-bit value. To be set by the IPv6
relay either to the downstream relay agent's UDP source port
used for the UDP packet, or to zero if only the local relay
agent uses the non-DHCP UDP port (not 547).
Figure 2: DHCPv6's Relay Source Port Option (from [RFC8357])
Figure 1 gives an example of internal inconsistency. Here, the Figure 2 gives an example of internal inconsistency. Here, the
ASCII diagram shows a field labelled "Application Error Code", packet diagram shows a field labelled "Application Error Code",
while the accompanying description lists the field as "Application while the accompanying description lists the field as "Application
Protocol Error Code". The use of an abbreviated name is suitable Protocol Error Code". The use of an abbreviated name is suitable
for human readers, but makes parsing the structure difficult for for human readers, but makes parsing the structure difficult for
machines. Figure 2 gives a further example, where the description machines. Figure 3 gives a further example, where the description
lists a field "Option-Code" that does not appear in the ASCII includes an "Option-Code" field that does not appear in the packet
diagram. In addition, the description list describes each field diagram; and where the description states that each field is 16
as being 16 bits in length, while the diagram shows the bits in length, but the diagram shows the OPTION_RELAY_PORT as 13
OPTION_RELAY_PORT as 13 bits, and Option-Len as 19 bits. Another bits, and Option-Len as 19 bits. Another example is [RFC6958],
example of this -- where the diagram and accompanying text where the packet format diagram showing the structure of the
disagree -- is in [RFC6958], where the packet header diagram Burst/Gap Loss Metrics Report Block shows the Number of Bursts
showing the structure of the Burst/Gap Loss Metrics Report Block field as being 12 bits wide but the corresponding text describes
shows the Number of Bursts field as being 12 bits wide but the it as 16 bits.
corresponding text describes it as 16 bits.
Comparing Figure 1 with Figure 2 exposes external inconsistency Comparing Figure 2 with Figure 3 exposes external inconsistency
across documents. While the ASCII diagrams themselves are broadly across documents. While the packet format diagrams are broadly
similar, the text surrounding the diagrams is formatted similar, the surrounding text is formatted differently. If
differently. If machine parsing is to be made possible, then this machine parsing is to be made possible, then this text must be
text must be structured consistently. structured consistently.
Ambiguous constraints: The constraints that are enforced on a Ambiguous constraints: The constraints that are enforced on a
particular field are often described ambiguously, or in a way that particular field are often described ambiguously, or in a way that
cannot be parsed easily. In Figure 2, each of the three fields in cannot be parsed easily. In Figure 3, each of the three fields in
the structure is constrained. The first two fields ("Option-Code" the structure is constrained. The first two fields ("Option-Code"
and "Option-Len") are to be set to constant values (note the and "Option-Len") are to be set to constant values (note the
inconsistency in how these constraints are expressed in the inconsistency in how these constraints are expressed in the
description). However, the third field ("Downstream Source Port") description). However, the third field ("Downstream Source Port")
can take a value from a constrained set. This constraint is can take a value from a constrained set. This constraint is
expressed in prose that can easily be parsed by humans, but not by expressed in prose that cannot readily by understood by machine.
machines.
Poor linking between sub-structures: Protocol data units and other Poor linking between sub-structures: Protocol data units and other
structures are often comprised of sub-structures that are defined structures are often comprised of sub-structures that are defined
elsewhere, either in the same document, or within another elsewhere, either in the same document, or within another
document. Chaining these structures together is essential for document. Chaining these structures together is essential for
machine parsing: the parsing process for a protocol data unit is machine parsing: the parsing process for a protocol data unit is
only fully expressed if all elements can be parsed. only fully expressed if all elements can be parsed.
Figure 1 highlights the difficulty that machine parsers have in Figure 2 highlights the difficulty that machine parsers have in
chaining structures together. Two fields ("Stream ID" and "Final chaining structures together. Two fields ("Stream ID" and "Final
Size") are described as being encoded as variable-length integers; Size") are described as being encoded as variable-length integers;
this is a structure described elsewhere in the same document. this is a structure described elsewhere in the same document.
Structured text is required both alongside the definition of the Structured text is required both alongside the definition of the
containing structure and with the definition of the sub-structure, containing structure and with the definition of the sub-structure,
to allow a parser to link the two together. to allow a parser to link the two together.
: The format of the "Relay Source Port Option" is shown below:
:
: 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
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | OPTION_RELAY_PORT | Option-Len |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Downstream Source Port |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
:
: Where:
:
: Option-Code: OPTION_RELAY_PORT. 16-bit value, 135.
:
: Option-Len: 16-bit value to be set to 2.
:
: Downstream Source Port: 16-bit value. To be set by the IPv6
: relay either to the downstream relay agent's UDP source port
: used for the UDP packet, or to zero if only the local relay
: agent uses the non-DHCP UDP port (not 547).
Figure 3: DHCPv6's Relay Source Port Option (from [RFC8357])
2.2. Formal languages in standards documents 2.2. Formal languages in standards documents
A small proportion of IETF standards documents contain structured and A small proportion of IETF standards documents contain structured and
formal languages, including ABNF [RFC5234], ASN.1 [ASN1], C, CBOR formal languages, including ABNF [RFC5234], ASN.1 [ASN1], C, CBOR
[RFC7049], JSON, the TLS presentation language [RFC8446], YANG models [RFC7049], JSON, the TLS presentation language [RFC8446], YANG models
[RFC7950], and XML. While this broad range of languages may be [RFC7950], and XML. While this broad range of languages may be
problematic for the development of tooling to parse specifications, problematic for the development of tooling to parse specifications,
these, and other, languages serve a range of different use cases. these, and other, languages serve a range of different use cases.
ABNF, for example, is typically used to specify text protocols, while ABNF, for example, is typically used to specify text protocols, while
ASN.1 is used to specify data structure serialisation. This document ASN.1 is used to specify data structure serialisation. This document
skipping to change at page 7, line 38 skipping to change at page 8, line 12
The immediate impact of requiring specific tooling is that The immediate impact of requiring specific tooling is that
adoption is likely to be limited. A long-term impact might be adoption is likely to be limited. A long-term impact might be
that authors whose workflows are incompatible might be alienated that authors whose workflows are incompatible might be alienated
from the process. from the process.
Canonical specifications: As far as possible, machine-readable Canonical specifications: As far as possible, machine-readable
structures should not replicate the human readable specification structures should not replicate the human readable specification
of the protocol within the same document. Such structures should of the protocol within the same document. Such structures should
form part of a canonical specification of the protocol. Adding form part of a canonical specification of the protocol. Adding
supplementary machine-readable structures, in parallel to the supplementary machine-readable structures, in parallel to the
existing human readable text, is undesirable because it could existing human readable text, is undesirable because it creates
create the potential for inconsistency. the potential for inconsistency.
As an example, program code that describes how a protocol data As an example, program code that describes how a protocol data
unit can be parsed might be provided as an appendix within a unit can be parsed might be provided as an appendix within a
standards document. This code would provide a specification of standards document. This code would provide a specification of
the protocol that is separate to the prose description in the main the protocol that is separate to the prose description in the main
body of the document. This has the undesirable effect of body of the document. This has the undesirable effect of
introducing the potential for the program code to specify introducing the potential for the program code to specify
behaviour that the prose-based specification does not, and vice- behaviour that the prose-based specification does not, and vice-
versa. versa.
skipping to change at page 8, line 15 skipping to change at page 8, line 37
then adoption is likely to be limited. At the limits of what can then adoption is likely to be limited. At the limits of what can
be expressed by the language, authors are likely to revert to be expressed by the language, authors are likely to revert to
defining the protocol in prose: this undermines the broad goal of defining the protocol in prose: this undermines the broad goal of
using structured and formal languages. Equally, though, using structured and formal languages. Equally, though,
understandable specifications and ease of use are critical for understandable specifications and ease of use are critical for
adoption. A tool that is simple to use and addresses the most adoption. A tool that is simple to use and addresses the most
common use cases might be preferred to a complex tool that common use cases might be preferred to a complex tool that
addresses all use cases. addresses all use cases.
Minimise required change: Any approach should require as few changes Minimise required change: Any approach should require as few changes
as possible to the way documents are formatted, authored, and as possible to the way that documents are formatted, authored, and
published. Forcing adoption of a particular structured or formal published. Forcing adoption of a particular structured or formal
language is incompatible with the IETF's standardisation process: language is incompatible with the IETF's standardisation process:
there are very few components of standards documents that are non- there are very few components of standards documents that are non-
optional. optional.
4. Augmented ASCII Packet Header Diagrams 4. Augmented Packet Header Diagrams
The design principles described in Section 3 can largely be met by The design principles described in Section 3 can largely be met by
the existing uses of ASCII packet header diagrams. These diagrams the existing uses of packet header diagrams. These diagrams aid
aid human readability, do not require new or specialised authorship human readability, do not require new or specialised authorship
tools, do not split the specification into multiple parts, can tools, do not split the specification into multiple parts, can
express most binary protocol features, and require no changes to the express most binary protocol features, and require no changes to
existing publication processes. existing publication processes.
However, as discussed in Section 2.1 there are limitations to how However, as discussed in Section 2.1 there are limitations to how
ASCII diagrams are used that must be addressed if they are to be packet header diagrams are used that must be addressed if they are to
parsed by machine. In this section, an augmented ASCII packet header be parsed by machine. In this section, an augmented packet header
diagram format is described. diagram format is described.
The concept is first illustrated by example. This is appropriate, The concept is first illustrated by example. This is appropriate,
given the visual nature of the language. In future drafts, these given the visual nature of the language. In future drafts, these
examples will be parsable using provided tools, and a formal examples will be parsable using provided tools, and a formal
specification of the augmented ASCII packet diagrams will be given in specification of the augmented packet diagrams will be given in
Appendix A. Appendix A.
In the augmented ASCII packet diagrams, each protocol data unit is 4.1. PDUs with Fixed and Variable-Width Fields
described in its own section of the document. This enables cross-
referencing between data units using section numbering. In this
specification-by-example, each element of the format will be
described as part of a separate PDU.
4.1. Fixed-width Field Format
The simplest PDU is one that contains only a set of fixed-width The simplest PDU is one that contains only a set of fixed-width
fields in a known order, with no optional fields or variation in the fields in a known order, with no optional fields or variation in the
packet format. packet format.
A Fixed-width Field Format packet is formatted as follows: Some packet formats include variable-width fields, where the size of
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
size of the other fields. A packet can contain only one unspecified
length field, to ensure there is no ambiguity.
0 1 2 3 A PDU description is introduced by the exact phrase "A/An _______ is
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 formatted as follows:" at the end of a paragraph. This is followed
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ by the PDU description itself, as a packet diagram within an
|F2 | Field30 | <artwork> element in the XML representation, starting with a header
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ line to show the bit width of the diagram. The description of the
| | fields follows the diagram, as an XML <dl> list, after a paragraph
+ Field64 + containing the text "where:".
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Each field of the description starts with a <dt> tag comprising the
| | field name and an optional short name in parenthesis. These are
+ Field48 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ followed by a colon, the field length, and a terminating period. The
| | following <dd> tag contains a prose description of the field.
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Field8 | For example, this can be illustrated using the IPv4 Header Format
+-+-+-+-+-+-+-+-+ [RFC791]. An IPv4 Header is formatted as follows:
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Version| IHL | DSCP |ECN| Total Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Identification |Flags| Fragment Offset |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Time to Live | Protocol | Header Checksum |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Destination Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| :
: Payload :
: |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
where: where:
Field2 (F2): 2 bits This is a short field, and the diagram cannot Version (V): 4 bits. This is a fixed-width field, whose full label
show its full label. A short label (F2) is used is shown in the diagram. The field's width -- 4 bits -- is given
in the diagram, and this short label is in the label of the description list, separated from the field's
provided, in brackets, after the full label in label by a colon.
the description list. The field's width -- 2
bits -- is given in the label of the description
list, separated from the field's label by a
colon.
Field30: 30 bits This is a longer field whose full label can be Internet Header Length (IHL): 4 bits. This is a shorter field, whose
shown in the diagram. full label is too large to be shown in the diagram. A short label
(IHL) is used in the diagram, and this short label is provided, in
brackets, after the full label in the description list.
Field64: 8 bytes This is a field that spans multiple rows. Where Differentiated Services Code Point (DSCP): 6 bits. This is a fixed-
fields are an integral number of bytes in size, width field, as previously defined.
and start and end on a byte boundary, the field
length can be given in bytes rather than in
bits.
Field48: 48 bits This is another multi-row field. As Explicit Congestion Notification (ECN): 2 bits. This is a fixed-
illustrated, fields are not required to end of a width field, as previously defined.
32-bit boundary.
Field8: 1 byte This field has been drawn on the next line, Total Length (TL): 2 bytes. This is a fixed-width field, as
where it would have fit on the previous line. previously defined. Where fields are an integral number of bytes
Where possible, the formatting of the diagram in size, the field length can be given in bytes rather than in
should be flexible to meet the needs of human bits.
readers.
4.2. Variable-width Field Format Identification: 2 bytes. This is a fixed-width field, as previously
defined.
Some packet formats include variable-width fields, where the size of Flags: 3 bits. This is a fixed-width field, as previously defined.
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
size of the other fields. A packet can contain only one unspecified
length field, to ensure there is no ambiguity.
A Variable-width Field Format packet is formatted as follows: Fragment Offset: 13 bits. This is a fixed-width field, as previously
defined.
0 1 2 3 Time To Live (TTL): 1 byte. This is a fixed-width field, as
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 previously defined.
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Field8 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| FieldVar - single row ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| :
: FieldVar - multi-row :
: |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| :
: FieldVar - multi-row, unspecified length :
: |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
where: Protocol: 1 byte. This is a fixed-width field, as previously
defined.
Field8 (F): 8 bits This is a fixed-width field, as described Header Checksum: 2 bytes. This is a fixed-width field, as previously
previously. As shown, while this field has a short label (F), defined.
this does not need to be used in the diagram.
FieldVar - single row: 2^F bits This is a variable-length field, Source Address: 32 bits. This is a fixed-width field, as previously
whose length is defined by the value of the field with short label defined.
F (Field8). Constraint expressions can be used in place of
constant values: the grammar for the expression language is
defined in Section a.1. Where fields labels are used in a
constraint, the field being referred to must have been defined
before its label is used. Short variable-length fields are
indicated by "..." instead of a pipe at the end of the row.
FieldVar - multi-row: 2^F bits This is a multi-row variable-length Destination Address: 32 bits. This is a fixed-width field, as
field, again constrained by the value of field F. Instead of the previously defined.
"..." notation, ":" is used to indicate that the field is
variable-length. The use of ":" instead of "..." indicates the
field is likely to be a longer, multi-row field. However,
semantically, there is no difference: these different notations
are for the benefit of human readers.
FieldVar - multi-row, unspecified length This is a variable-width Options: (IHL-5)*32 bits. This is a variable-length field, whose
field whose length is implied by the lengths of the other fields. length is defined by the value of the field with short label IHL
At parsing time, the length of the PDU is known, and this can be (Internet Header Length). Constraint expressions can be used in
used to determine the length of fields whose length is undefined. place of constant values: the grammar for the expression language
Each PDU can only leave a single field's length undefined: all is defined in Appendix A.1. Constraints can include a previously
other fields must be fixed-length, or have their widths defined field's short or full label, where one has been defined.
constrained. Short variable-length fields are indicated by "..." instead of a
pipe at the end of the row.
4.3. Cross-referencing and Sequences Format Payload: TL - ((IHL*32)/8) bytes. This is a multi-row variable-
length field, constrained by the values of fields TL and IHL.
Instead of the "..." notation, ":" is used to indicate that the
field is variable-length. The use of ":" instead of "..."
indicates the field is likely to be a longer, multi-row field.
However, semantically, there is no difference: these different
notations are for the benefit of human readers.
A Cross-referencing and Sequences Format packet is formatted as 4.2. PDUs That Cross-Reference Previously Defined Fields
follows:
0 1 2 3 Binary formats often reference sub-structures that have been defined
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 earlier in the specification. For example, in RTP [RFC3550], the
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Contributing Source Identifiers in an RTP Data Packet are defined as
| Field8 | comprising a list of Source Identifier elements. A Source Identifier
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ is formatted as follows:
| |
+ + 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
+ FieldFixedXRef + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| | | Source Identifier |
+ + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
+ +-+-+-+-+-+-+-+-+
| | :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ :
: :
: FieldVarXref :
: |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
+ +
| |
+ [SeqFieldFixedXRef] +
| |
+ +
| |
+ +-+-+-+-+-+-+-+-+
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
where: where:
Field8 (F): 8 bits This is a fixed-width field, as described Source Identifier: 32 bits. This is a fixed-width field, as
described previously.
The following example shows how a Source Identifier can be referenced
in the description of an RTP Data Packet. It also shows how the
presence of some fields in a format may be dependent on the values of
an earlier field.
An RTP Data Packet is formatted as follows:
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| V |P|X| CC |M| PT | Sequence Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Timestamp |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Synchronization Source identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| [Contributing Source identifiers] |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Header Extension |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Payload :
: :
: |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Padding | Padding Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
where:
Version (V): 2 bits. This is a fixed-width field, as described
previously. previously.
FieldFixedXRef: 1 Fixed-width Field Format This is a field whose Padding (P): 1 bit. This is a fixed-width field, as described
structure is a previously defined PDU format. To indicate this, previously.
the width of the field is given in units of the cross-referenced
structure (here, Fixed-width Field Format).
FieldVarXref: 1 Variable-width Field Format This field references a Extension (X): 1 bit. This is a fixed-width field, as described
variable-width structure. It can be drawn to any width as previously.
appropriate, but must use a variable-width notation. Where
multiple variable-width field format structures are referenced,
the requirement that only one field's length can be unspecified
applies to the enclosing structure.
SeqFieldFixedXRef: 2 Fixed-width Field Format Where a field is CSRC count (CC): 4 bits. This is a fixed-width field, as described
comprised of a sequence of previously defined structures, square previously.
brackets can be used to indicate this in the diagram. The length
of the sequence can be defined using the constraint expression
grammar as described earlier.
4.4. Optional Field Format Marker (M): 1 bit. This is a fixed-width field, as described
previously.
An Optional Field Format packet is formatted as follows: Payload Type (PT): 7 bits. This is a fixed-width field, as described
previously.
0 1 2 3 Sequence Number (PT): 16 bits. This is a fixed-width field, as
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 described previously.
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Field8 | Timestamp (PT): 32 bits. This is a fixed-width field, as described
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ previously.
| OptionalField |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Synchronization Source identifier: 1 * Source Identifier. This is a
field whose structure is a previously defined PDU format. To
indicate this, the width of the field is expressed in terms of
cross-referenced structure (here, Source Identifier). When used
in constraint expressions, PDU names refer to the length of that
PDU structure.
Contributing Source identifiers: CC * Source Identifier. Where a
field is comprised of a sequence of previously defined structures,
square brackets can be used to indicate this in the diagram. The
length of the sequence can be defined using the constraint
expression grammar as described earlier.
Header Extension: 32 bits; present only when X == 1. This is a field
whose presence is predicated on an expression given using the
constraint expression grammar described earlier. Optional fields
can be of any previously defined format (e.g., fixed- or variable-
width). Optional fields are indicated by the presence of a
"Present only when [expr]." as the first line in their
description.
[Note that this example deviates from the format as described in
[RFC3550]. As specified in that document, the Header Extension
would be a cross-referenced structure. This is not shown here for
brevity.]
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
of the known fields. There can only be one field of unspecified
size in a PDU.
Padding: Padding Count bytes; present only when (P == 1) and
(Padding Count > 0).
This is a variable size field, with size dependent on a later
field in the packet. Fields can only depend on the value of a
later field if they follow a field with unspecified size.
Padding Count: 1 byte; present only when P == 1. This is a fixed-
width field, as previously defined.
4.3. PDUs with Non-Contiguous Fields
In some binary formats, fields are striped across multiple non-
contiguous bits. This is often to allow for backwards compatibility
with previous definitions of the same fields in earlier documents:
striping in this way allows for careful use of the possible range of
values.
This format is illustrated using the STUN Message Type
[draft-ietf-tram-stunbis-21]. A STUN Message Type is formatted as
follows:
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|M|M|M|M|M|C|M|M|M|C|M|M|M|M|
|B|A|9|8|7|1|6|5|4|0|3|2|1|0|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
where: where:
Field8 (F): 8 bits This is a fixed-width field, as described Method (M): 12 bits. This field is comprised of multiple sub-fields
previously. (M0 through MB) as shown in the diagram. That these sub-fields
should be concatenated, after parsing, into a single field is
indicated by their being labelled using the 'M' short field name
followed by a single hexadecimal digit, with the least significant
bit labelled with 0, and subsequent bits labelled in sequence.
OptionalField: 4 bytes Present only when F > 3. This is a field Class (C): 2 bits. This field follows the same format as M described
whose presence is predicated on an expression above.
given in the constraint expression grammar
described earlier. Optional fields can be of
any previously defined format (e.g., fixed-
or variable-width). Optional fields are
indicated by the presence of a "Present only
when [expr]." as the first line in their
description
5. IANA Considerations 5. IANA Considerations
This document contains no actions for IANA. This document contains no actions for IANA.
6. Security Considerations 6. Security Considerations
Poorly implemented parsers are a frequent source of security Poorly implemented parsers are a frequent source of security
vulnerabilities in protocol implementations. Structuring the vulnerabilities in protocol implementations. Structuring the
description of a protocol data unit so that a parser can be description of a protocol data unit so that a parser can be
automatically derived from the specification can reduce the automatically derived from the specification can reduce the
likelihood of vulnerable implementations. likelihood of vulnerable implementations.
7. Acknowledgements 7. Acknowledgements
The authors would like to thank David Southgate for preparing a The authors would like to thank David Southgate for preparing a
prototype implementation of some of the ideas described here. prototype implementation of some of the ideas described here.
The authors would like to thank Marc Petit-Huguenin for feedback on
the draft.
This work has received funding from the UK Engineering and Physical This work has received funding from the UK Engineering and Physical
Sciences Research Council under grant EP/R04144X/1. Sciences Research Council under grant EP/R04144X/1.
8. Informative References 8. Informative References
[ASN1] ITU-T, "ITU-T Recommendation X.680, X.681, X.682, and [RFC8357] Deering, S. and R. Hinden, "Generalized UDP Source Port
X.683", ITU-T Recommendation X.680, X.681, X.682, and for DHCP Relay", RFC 8357, March 2018,
X.683. <https://www.rfc-editor.org/info/rfc8357>.
[QUIC-TRANSPORT] [QUIC-TRANSPORT]
Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed
and Secure Transport", draft-ietf-quic-transport-20 (work and Secure Transport", Work in Progress, Internet-Draft,
in progress), 23 April 2019, draft-ietf-quic-transport-20, 23 April 2019,
<http://www.ietf.org/internet-drafts/draft-ietf-quic- <http://www.ietf.org/internet-drafts/draft-ietf-quic-
transport-20.txt>. transport-20.txt>.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>.
[RFC6958] Clark, A., Zhang, S., Zhao, J., and Q. Wu, "RTP Control [RFC6958] Clark, A., Zhang, S., Zhao, J., and Q. Wu, "RTP Control
Protocol (RTCP) Extended Report (XR) Block for Burst/Gap Protocol (RTCP) Extended Report (XR) Block for Burst/Gap
Loss Metric Reporting", RFC 6958, May 2013, Loss Metric Reporting", RFC 6958, May 2013,
<https://www.rfc-editor.org/info/rfc6958>. <https://www.rfc-editor.org/info/rfc6958>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, October 2013,
<https://www.rfc-editor.org/info/rfc7049>.
[RFC7950] Bjorklund, M., "The YANG 1.1 Data Modeling Language", [RFC7950] Bjorklund, M., "The YANG 1.1 Data Modeling Language",
RFC 7950, August 2016, RFC 7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>. <https://www.rfc-editor.org/info/rfc7950>.
[RFC8357] Deering, S. and R. Hinden, "Generalized UDP Source Port
for DHCP Relay", RFC 8357, March 2018,
<https://www.rfc-editor.org/info/rfc8357>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, August 2018, Version 1.3", RFC 8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>. <https://www.rfc-editor.org/info/rfc8446>.
Appendix A. ABNF specification [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>.
A.1. Constraint Expressions [ASN1] ITU-T, "ITU-T Recommendation X.680, X.681, X.682, and
X.683", ITU-T Recommendation X.680, X.681, X.682, and
X.683.
cond-expr = eq-expr "?" cond-expr ":" eq-expr [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
eq-expr = bool-expr eq-op bool-expr Representation (CBOR)", RFC 7049, October 2013,
bool-expr = ord-expr bool-op ord-expr <https://www.rfc-editor.org/info/rfc7049>.
ord-expr = add-expr ord-op add-expr
add-expr = mul-expr add-op mul-expr [RFC3550] Schulzrinne, H., Casner, S., Frederick, R., and V.
mul-expr = expr mul-op expr Jacobson, "RTP: A Transport Protocol for Real-Time
expr = *DIGIT / field-name Applications", RFC 3550, July 2003,
<https://www.rfc-editor.org/info/rfc3550>.
field-name = *ALPHA [draft-ietf-tram-stunbis-21]
Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing,
D., Mahy, R., and P. Matthews, "Session Traversal
Utilities for NAT (STUN)", Work in Progress, Internet-
Draft, draft-ietf-tram-stunbis-21, 21 March 2019,
<http://www.ietf.org/internet-drafts/draft-ietf-tram-
stunbis-21.txt>.
mul-op = "*" / "/" / "%" [RFC791] Postel, J., "Internet Protocol", RFC 791, September 1981,
add-op = "+" / "-" <https://www.rfc-editor.org/info/rfc791>.
ord-op = "<=" / "<" / ">=" / ">"
bool-op = "&&" / "||" / "!"
eq-op = "==" / "!="
A.2. Augmented ASCII diagrams [RFC793] Postel, J., "Transmission Control Protocol", RFC 793,
September 1981, <https://www.rfc-editor.org/info/rfc793>.
Appendix A. ABNF specification
A.1. Constraint Expressions
cond-expr = eq-expr "?" cond-expr ":" eq-expr eq-expr = bool-expr eq-op bool-expr bool-expr = ord-expr bool-op ord-expr ord-expr = add-expr ord-op add-expr add-expr = mul-expr add-op mul-expr mul-expr = expr mul-op expr expr = *DIGIT / field-name / field-name-ws / "(" expr ")" field-name = *ALPHA field-name-ws = *(field-name " ") mul-op = "*" / "/" / "%" add-op = "+" / "-" ord-op = "<=" / "<" / ">=" / ">" bool-op = "&&" / "||" / "!" eq-op = "==" / "!="
A.2. Augmented packet diagrams
Future revisions of this draft will include an ABNF specification for Future revisions of this draft will include an ABNF specification for
the augmented ASCII diagram format described in Section 4. Such a the augmented packet diagram format described in Section 4. Such a
specification is omitted from this draft given that the format is specification is omitted from this draft given that the format is
likely to change as its syntax is developed. Given the visual nature likely to change as its syntax is developed. Given the visual nature
of the format, it is more appropriate for discussion to focus on the of the format, it is more appropriate for discussion to focus on the
examples given in Section 4. examples given in Section 4.
Appendix B. Source code repository
The source code for tooling that can be used to parse this document
is available from https://github.com/lumisota/improving-protocol-
standards.
Authors' Addresses Authors' Addresses
Stephen McQuistin Stephen McQuistin
University of Glasgow University of Glasgow
School of Computing Science School of Computing Science
Glasgow Glasgow
G12 8QQ G12 8QQ
United Kingdom United Kingdom
Email: sm@smcquistin.uk Email: sm@smcquistin.uk
 End of changes. 76 change blocks. 
343 lines changed or deleted 432 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/