draft-mcquistin-augmented-ascii-diagrams-08.txt   draft-mcquistin-augmented-ascii-diagrams-09.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: 6 November 2021 C. S. Perkins Expires: 28 April 2022 C. S. Perkins
University of Glasgow University of Glasgow
5 May 2021 25 October 2021
Describing Protocol Data Units with Augmented Packet Header Diagrams Describing Protocol Data Units with Augmented Packet Header Diagrams
draft-mcquistin-augmented-ascii-diagrams-08 draft-mcquistin-augmented-ascii-diagrams-09
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 6 November 2021. This Internet-Draft will expire on 28 April 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2021 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
skipping to change at page 2, line 20 skipping to change at page 2, line 20
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 . . . . . . . . . . 16
4.5. PDUs That Extend Sub-Structures . . . . . . . . . . . . . 18 4.5. PDUs with Constraints on Field Sizes . . . . . . . . . . 18
4.6. Storing Data for Parsing . . . . . . . . . . . . . . . . 19 4.6. PDUs That Extend Sub-Structures . . . . . . . . . . . . . 20
4.7. Connecting Structures with Functions . . . . . . . . . . 20 4.7. Storing Data for Parsing . . . . . . . . . . . . . . . . 21
4.8. Specifying Enumerated Types . . . . . . . . . . . . . . . 21 4.8. Connecting Structures with Functions . . . . . . . . . . 22
4.9. Specifying Protocol Data Units . . . . . . . . . . . . . 22 4.9. Specifying Enumerated Types . . . . . . . . . . . . . . . 23
4.10. Importing PDU Definitions from Other Documents . . . . . 22 4.10. Specifying Protocol Data Units . . . . . . . . . . . . . 24
5. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 22 4.11. Importing PDU Definitions from Other Documents . . . . . 25
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 5. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 25
7. Security Considerations . . . . . . . . . . . . . . . . . . . 23 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 23 7. Security Considerations . . . . . . . . . . . . . . . . . . . 26
9. Informative References . . . . . . . . . . . . . . . . . . . 24 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 26
Appendix A. ABNF specification . . . . . . . . . . . . . . . . . 26 9. Informative References . . . . . . . . . . . . . . . . . . . 26
A.1. Constraint Expressions . . . . . . . . . . . . . . . . . 26 Appendix A. ABNF specification . . . . . . . . . . . . . . . . . 28
A.2. Augmented packet diagrams . . . . . . . . . . . . . . . . 26 A.1. Constraint Expressions . . . . . . . . . . . . . . . . . 28
Appendix B. Tooling & source code . . . . . . . . . . . . . . . 26 A.2. Augmented packet diagrams . . . . . . . . . . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 Appendix B. Tooling & source code . . . . . . . . . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 29
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 11, line 10 skipping to change at page 11, line 10
formatted as follows" within a paragraph. This is followed by the formatted as follows" within a paragraph. This is followed by the
PDU description itself, as a packet diagram within an <artwork> PDU description itself, as a packet diagram within an <artwork>
element (itself optionally within a <figure> element) in the XML 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.10). 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. Field names cannot be the
same as a previously defined PDU name, and must be unique within a same as a previously defined PDU name, and must be unique within a
given structure definition. The structured text definition is given given structure definition. The structured text definition is given
either in a <dt> tag (if using a <dl>) or as the "hangText" (if using 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 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.6). 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Version| IHL | DSCP |ECN| Total Length | |Version| IHL | DSCP |ECN| Total Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Identification |Flags| Fragment Offset | | Identification |Flags| Fragment Offset |
skipping to change at page 18, line 14 skipping to change at page 18, line 14
Destination Connection ID: DLen bytes. This is a variable-width Destination Connection ID: DLen bytes. This is a variable-width
field as previously described. field as previously described.
SCID Len (SLen): 1 byte; SLen <= 20. This is a fixed-width field, SCID Len (SLen): 1 byte; SLen <= 20. This is a fixed-width field,
with a value constraint, as previously described. with a value constraint, as previously described.
Source Connection ID: SLen bytes. This is a variable-width field as Source Connection ID: SLen bytes. This is a variable-width field as
previously described. previously described.
4.5. PDUs That Extend Sub-Structures 4.5. PDUs with Constraints on Field Sizes
A PDU may contain fields that have a size that is specified in terms
of the value of another field. So far, our constraint syntax can be
used to specify the length of fields in known units (of bits, bytes,
or other structures). If the units are of variable-width, then it
may not be possible to specify the length of the sequence. However,
it is still necessary to be able to constraint the overall width of
the field. To support this, our constraint syntax includes a "size"
function that evaluates to the width, in bits, of the given named
field.
This syntax is illustrated using the TCP Header format
[draft-ietf-tcpm-rfc793bis]. A TCP 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source Port | Destination Port |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Sequence Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Acknowledgment Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data | |C|E|U|A|P|R|S|F| |
| Offset| Rsrvd |W|C|R|C|S|S|Y|I| Window Size |
| | |R|E|G|K|H|T|N|N| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Checksum | Urgent Pointer |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| [Options] |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| :
: Payload :
: |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
where:
Source Port: 16 bits. This is a fixed-width field as previously
described.
Destination Port: 16 bits. This is a fixed-width field as previously
described.
Sequence Number: 32 bits. This is a fixed-width field as previously
described.
Acknowledgment Number: 32 bits. This is a fixed-width field as
previously described.
Data Offset (DOffset): 4 bits; DOffset >= 5. This is a fixed-width
field, with a value constraint, as previously described.
Reserved (Rsrvd): 4 bits; Rsrvd == 0. This is a fixed-width field,
with a value constraint, as previously described.
CWR: 1 bit. This is a fixed-width field as previously described.
ECE: 1 bit. This is a fixed-width field as previously described.
URG: 1 bit. This is a fixed-width field as previously described.
ACK: 1 bit. This is a fixed-width field as previously described.
PSH: 1 bit. This is a fixed-width field as previously described.
RST: 1 bit. This is a fixed-width field as previously described.
SYN: 1 bit. This is a fixed-width field, with a value constraint, as
previously described.
FIN: 1 bit; (FIN == 0) || (SYN == 0). This is a fixed-width field,
with a value constraint, as previously described.
Window Size: 16 bits. This is a fixed-width field as previously
described.
Checksum: 16 bits. This is a fixed-width field as previously
described.
Urgent Pointer: 16 bits. This is a fixed-width field as previously
described.
Options: [TCP Option]; size(Options) == (DOffset-5)*32; present
only when DOffset > 5. This is a variable-width field that is
comprised of a sequence of TCP Option sub-structures. TCP Option
is an enumerated type, to be defined in Section 4.9. As defined,
the TCP Option type can be either 2 or 3 bytes, depending on the
option type. As a result, it is not possible to specify the
number of TCP Option structures that the Option field will
contain. However, the overall size of the field can be
constrained. The "size(Options) == (DOffset-5)*32" makes use of
the "size" function. This evaluates to the size, in bits, of the
named field. The argument passed to the "size" field must be the
name of the field being defined, or of a previously defined field.
The "DOffset" field contains the number of 32-bit words that are
present in the TCP Header. By default, with no TCP options, this
is 5. As a result, the size of the Options field is constrained
to the value of DOffset, less 5, and multiplied to get the value
in bits.
Payload. This is a variable-width field as previously described.
4.6. PDUs That Extend Sub-Structures
A PDU may not only use or reference existing sub-structures, but they A PDU may not only use or reference existing sub-structures, but they
may extend them, adding new fields, or enforcing different or may extend them, adding new fields, or enforcing different or
additional constraints. additional constraints.
Where a sub-structure is extended, the diagram may show the sub- Where a sub-structure is extended, the diagram may show the sub-
structure as a block, labelled with the sub-structure name. It may structure as a block, labelled with the sub-structure name. It may
also be desirable to show the sub-structure diagram in full; in this also be desirable to show the sub-structure diagram in full; in this
case, the fields must be given in the same order and be of the same case, the fields must be given in the same order and be of the same
length. New field constraints can be shown. Similarly, in the length. New field constraints can be shown. Similarly, in the
skipping to change at page 19, line 19 skipping to change at page 21, line 39
Retry Token. This is a variable-length field as previously defined. Retry Token. This is a variable-length field as previously defined.
Retry Integrity Tag: 128 bits. This is a fixed-width field as Retry Integrity Tag: 128 bits. This is a fixed-width field as
previously defined. previously defined.
As shown, the Long Header packet sub-structure is included. The As shown, the Long Header packet sub-structure is included. The
Retry Packet enforces a new value constraint on the Long Packet Type Retry Packet enforces a new value constraint on the Long Packet Type
(T) field. (T) field.
4.6. Storing Data for Parsing 4.7. Storing Data for Parsing
The parsing process may require data from previously parsed The parsing process may require data from previously parsed
structures. This means that data needs to be stored persistently structures. This means that data needs to be stored persistently
throughout the process. This data needs to be identified. throughout the process. This data needs to be identified.
That the value of a particular field be stored upon parsing is That the value of a particular field be stored upon parsing is
indicated by the exact phrase "On receipt, the value of <field name> indicated by the exact phrase "On receipt, the value of <field name>
is stored as <stored name>." being present at the end of the is stored as <stored name>." being present at the end of the
description of a field (i.e., at the end of the <dd> or <t> element.) description of a field (i.e., at the end of the <dd> or <t> element.)
skipping to change at page 20, line 5 skipping to change at page 22, line 22
where: where:
Long Header (LH): 1 Long Header; LH.T == 0. This is field is a sub- Long Header (LH): 1 Long Header; LH.T == 0. This is field is a sub-
structure, with a constraint, as previously defined. On receipt, structure, with a constraint, as previously defined. On receipt,
the value of LH.DCID is stored as Initial DCID. the value of LH.DCID is stored as Initial DCID.
In this example, the value of the DCID field of the Long Header sub- In this example, the value of the DCID field of the Long Header sub-
structure is stored as Initial DCID. structure is stored as Initial DCID.
4.7. Connecting Structures with Functions 4.8. Connecting Structures with Functions
The parsing or serialisation of some binary formats cannot be fully The parsing or serialisation of some binary formats cannot be fully
described without the use of functions. These functions take described without the use of functions. These functions take
arguments (values from another structure), perform some computation, arguments (values from another structure), perform some computation,
and generate a new structure. and generate a new structure.
Given the goal of fully capturing the parsing or serialisation of Given the goal of fully capturing the parsing or serialisation of
binary protocols, it is necessary to include the signature of these binary protocols, it is necessary to include the signature of these
helper functions. helper functions.
skipping to change at page 20, line 28 skipping to change at page 22, line 45
the function. This is immediately followed by a set of brackets the function. This is immediately followed by a set of brackets
containing a comma separated list of the function's parameters, containing a comma separated list of the function's parameters,
formatted as "<parameter name>: <parameter type>". This is followed formatted as "<parameter name>: <parameter type>". This is followed
by "->" and the return type of the function, followed by a colon. by "->" and the return type of the function, followed by a colon.
The body of the function is not captured, owing to the complexity of The body of the function is not captured, owing to the complexity of
both capturing and translating arbitrary code. As a result, it can both capturing and translating arbitrary code. As a result, it can
be described in whichever format is most suitable for the document be described in whichever format is most suitable for the document
and its readership. and its readership.
Those values that are stored persistently, as defined in Section 4.6, Those values that are stored persistently, as defined in Section 4.7,
are accessible by functions. are accessible by functions.
As an example, the "apply_protection" function is defined as: As an example, the "apply_protection" function is defined as:
func apply_protection(to: Unprotected Packet) func apply_protection(to: Unprotected Packet)
-> Protected Packet: -> Protected Packet:
apply packet protection to payload apply packet protection to payload
apply header protection to first_byte and packet_number apply header protection to first_byte and packet_number
construct appropriate Protected Packet based on first_byte construct appropriate Protected Packet based on first_byte
return Protected Packet return Protected Packet
skipping to change at page 21, line 8 skipping to change at page 23, line 29
must take a single parameter, of the same type as PDU B, and return a must take a single parameter, of the same type as PDU B, and return a
PDU B. PDU B.
To indicate that a PDU can be serialised to another by way of a To indicate that a PDU can be serialised to another by way of a
function, the sentence "A/An <PDU name A> is serialised to a <PDU function, the sentence "A/An <PDU name A> is serialised to a <PDU
name B> using the <function name> function" is used. This indicates name B> using the <function name> function" is used. This indicates
that a PDU B is generated by passing PDU A into the named function. that a PDU B is generated by passing PDU A into the named function.
The function must take a single parameter, of the same type as PDU A, The function must take a single parameter, of the same type as PDU A,
and return a PDU B. and return a PDU B.
4.8. Specifying Enumerated Types 4.9. Specifying Enumerated Types
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.
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.
A PING Frame is formatted as follows: An EOL Option is formatted as follows:
0 1 2 3 0
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
| 1 | | 0 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
where: where:
Frame Type (FT): 1 Variable Length Integer Encoding; FT.T == 1. Fram Option Kind (Kind): 1 byte; Kind == 0. This is a fixed-width field,
e type, set to 1 for PING frames. with a value constraint, as previously described.
A HANDSHAKE_DONE Frame is formatted as follows: A Window Scale Factor Option 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 30 | | 3 | Length | Window Scale |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
where: where:
Frame Type (FT): 1 Variable Length Integer Encoding; FT.T == 30. Fra Option Kind (Kind): 1 byte; Kind == 3. This is a fixed-width field,
me type, set to 30 for HANDSHAKE_DONE frames. with a value constraint, as previously described.
A Frame is either a PING Frame or a HANDSHAKE_DONE Frame. Option Length (Length): 1 byte; Length == 3. This is a fixed-width
field, with a value constraint, as previously described.
4.9. Specifying Protocol Data Units Window Scale: 1 byte. This is a fixed-width field, as previously
described.
A TCP Option is either an EOL Option or a Window Scale Factor Option.
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.
The PDUs that comprise a protocol are identified using the exact The PDUs that comprise a protocol are identified using the exact
phrase "This document describes the <protocol name> protocol. The phrase "This document describes the <protocol name> protocol. The
<protocol name> protocol uses <list of PDU names>" where the list of <protocol name> protocol uses <list of PDU names>" where the list of
PDU names is a comma separated list (with the last element, if there PDU names is a comma separated list (with the last element, if there
is more than one element, preceded by 'and'), each optionally is more than one element, preceded by 'and'), each optionally
preceded by "a" or "an". The PDU names must be structure names preceded by "a" or "an". The PDU names must be structure names
defined in the document or a linked document. The PDU names are defined in the document or a linked document. The PDU names are
pluralised in the list. A document must contain exactly one instance pluralised in the list. A document must contain exactly one instance
of this phrase. of this phrase.
This document describes the Example protocol. The Example protocol This document describes the Example protocol. The Example protocol
uses Long Headers, STUN Message Types, IPv4 Headers, and RTP Data uses Long Headers, STUN Message Types, IPv4 Headers, RTP Data
Packets. Packets, and TCP Headers.
4.10. Importing PDU Definitions from Other Documents 4.11. Importing PDU Definitions from Other Documents
Protocols are often specified across multiple documents, either Protocols are often specified across multiple documents, either
because the specification of a protocol's data units has changed over because the specification of a protocol's data units has changed over
time, or because of explicit extension points contained in the time, or because of explicit extension points contained in the
protocol's original specification. To allow a document to make use protocol's original specification. To allow a document to make use
of a previous PDU definition, it is possible to import PDU of a previous PDU definition, it is possible to import PDU
definitions (written in the format described in this document) from definitions (written in the format described in this document) from
other documents. other documents.
A PDU definition is imported using the exact phrase "A/An ________ is A PDU definition is imported using the exact phrase "A/An ________ is
skipping to change at page 25, line 33 skipping to change at page 28, line 19
Shubina, "The Halting Problems of Network Stack Shubina, "The Halting Problems of Network Stack
Insecurity", ;login: -- December 2011, Volume 36, Number Insecurity", ;login: -- December 2011, Volume 36, Number
6, <https://www.usenix.org/publications/login/december- 6, <https://www.usenix.org/publications/login/december-
2011-volume-36-number-6/halting-problems-network-stack- 2011-volume-36-number-6/halting-problems-network-stack-
insecurity>. insecurity>.
[draft-mcquistin-augmented-udp-example] [draft-mcquistin-augmented-udp-example]
McQuistin, S., Band, V., Jacob, D., and C. S. Perkins, McQuistin, S., Band, V., Jacob, D., and C. S. Perkins,
"Describing UDP with Augmented Packet Header Diagrams", "Describing UDP with Augmented Packet Header Diagrams",
Work in Progress, Internet-Draft, draft-mcquistin- Work in Progress, Internet-Draft, draft-mcquistin-
augmented-udp-example-01, 5 May 2021, augmented-udp-example-02, 25 October 2021,
<http://www.ietf.org/internet-drafts/draft-mcquistin- <http://www.ietf.org/internet-drafts/draft-mcquistin-
augmented-udp-01.txt>. augmented-udp-02.txt>.
[draft-mcquistin-augmented-tcp-example] [draft-mcquistin-augmented-tcp-example]
McQuistin, S., Band, V., Jacob, D., and C. S. Perkins, McQuistin, S., Band, V., Jacob, D., and C. S. Perkins,
"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-01, 5 May 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-01.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-04, 5 May 2021, draft-mcquistin-quic-augmented-diagrams-05, 25 October
<http://www.ietf.org/internet-drafts/draft-mcquistin-quic- 2021, <http://www.ietf.org/internet-drafts/draft-
augmented-diagrams-04.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-21, 3 May 2021, <http://www.ietf.org/ ietf-tcpm-rfc793bis-25, 7 September 2021,
internet-drafts/draft-ietf-tcpm-rfc793bis-21.txt>. <http://www.ietf.org/internet-drafts/draft-ietf-tcpm-
rfc793bis-25.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 = "&&" / "||"
skipping to change at page 26, line 30 skipping to change at page 29, line 19
"!" 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 = "&&" / "||"
cmp-op = "==" / "!=" / "<" / "<=" / ">" / ">=" cmp-op = "==" / "!=" / "<" / "<=" / ">" / ">="
expr = "(" sp expr sp ")" / expr = "(" sp expr sp ")" /
expr sp op sp expr / expr sp op sp expr /
bool-expr "?" expr ":" expr / bool-expr "?" expr ":" expr /
name / short-name "." short-name / name / short-name "." short-name /
"size(" short-name ")" /
constant constant
op = "+" / "-" / "*" / "/" / "%" / "^" op = "+" / "-" / "*" / "/" / "%" / "^"
length = expr sp unit / "[" sp name sp "]" / "variable length" length = expr sp unit / "[" sp name sp "]" / "variable length"
unit = %s"bit" / %s"bits" / %s"byte" / %s"bytes" / name unit = %s"bit" / %s"bits" / %s"byte" / %s"bytes" / name
A.2. Augmented packet diagrams 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 packet 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
 End of changes. 30 change blocks. 
54 lines changed or deleted 167 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/