< draft-mcquistin-augmented-ascii-diagrams-04.txt   draft-mcquistin-augmented-ascii-diagrams-05.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: 26 October 2020 C. S. Perkins Expires: 19 December 2020 C. S. Perkins
University of Glasgow University of Glasgow
24 April 2020 17 June 2020
Describing Protocol Data Units with Augmented Packet Header Diagrams Describing Protocol Data Units with Augmented Packet Header Diagrams
draft-mcquistin-augmented-ascii-diagrams-04 draft-mcquistin-augmented-ascii-diagrams-05
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 26 October 2020. This Internet-Draft will expire on 19 December 2020.
Copyright Notice Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the Copyright (c) 2020 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 25 skipping to change at page 2, line 25
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 . . . . . . . . . . . . . 15 4.3. PDUs with Non-Contiguous Fields . . . . . . . . . . . . . 15
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 . . . . . . . . . . . . . 17 4.5. PDUs That Extend Sub-Structures . . . . . . . . . . . . . 17
4.6. Storing Data for Parsing . . . . . . . . . . . . . . . . 18 4.6. Storing Data for Parsing . . . . . . . . . . . . . . . . 18
4.7. Connecting Structures with Functions . . . . . . . . . . 19 4.7. Connecting Structures with Functions . . . . . . . . . . 19
4.8. Specifying Enumerated Types . . . . . . . . . . . . . . . 20 4.8. Specifying Enumerated Types . . . . . . . . . . . . . . . 20
4.9. Specifying Protocol Data Units . . . . . . . . . . . . . 21 4.9. Specifying Protocol Data Units . . . . . . . . . . . . . 21
4.10. Importing PDU Definitions from Other Documents . . . . . 21 4.10. Importing PDU Definitions from Other Documents . . . . . 22
5. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 22 5. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 22
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22
7. Security Considerations . . . . . . . . . . . . . . . . . . . 22 7. Security Considerations . . . . . . . . . . . . . . . . . . . 22
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 23 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 23
9. Informative References . . . . . . . . . . . . . . . . . . . 23 9. Informative References . . . . . . . . . . . . . . . . . . . 23
Appendix A. ABNF specification . . . . . . . . . . . . . . . . . 24 Appendix A. ABNF specification . . . . . . . . . . . . . . . . . 24
A.1. Constraint Expressions . . . . . . . . . . . . . . . . . 24 A.1. Constraint Expressions . . . . . . . . . . . . . . . . . 24
A.2. Augmented packet diagrams . . . . . . . . . . . . . . . . 25 A.2. Augmented packet diagrams . . . . . . . . . . . . . . . . 25
Appendix B. Source code repository . . . . . . . . . . . . . . . 25 Appendix B. Source code repository . . . . . . . . . . . . . . . 25
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25
skipping to change at page 14, line 29 skipping to change at page 14, line 27
Payload Type (PT): 7 bits. This is a fixed-width field, as described Payload Type (PT): 7 bits. This is a fixed-width field, as described
previously. previously.
Sequence Number (PT): 16 bits. This is a fixed-width field, as Sequence Number (PT): 16 bits. This is a fixed-width field, as
described previously. described previously.
Timestamp (PT): 32 bits. This is a fixed-width field, as described Timestamp (PT): 32 bits. This is a fixed-width field, as described
previously. previously.
Synchronization Source identifier: 1 * Source Identifier. This is a Synchronization Source identifier: 1 Source Identifier. This is a
field whose structure is a previously defined PDU format (Source field whose structure is a previously defined PDU format (Source
Identifier). To indicate this, the width of the field is Identifier). To indicate this, the width of the field is
expressed in terms of cross-referenced structure. When used in expressed in terms of cross-referenced structure. When used in
constraint expressions, PDU names refer to the length of that PDU constraint expressions, PDU names refer to the length of that PDU
structure. structure.
Contributing Source identifiers: CC * Source Identifier. Where a Contributing Source identifiers: CC Source Identifier. Where a field
field is comprised of a sequence of previously defined structures, is comprised of a sequence of previously defined structures,
square brackets can be used to indicate this in the diagram. The square brackets can be used to indicate this in the diagram. The
length of the sequence can be defined using the constraint length of the sequence can be defined using the constraint
expression grammar as described earlier. expression grammar as described earlier. Where the length is
unknown, the type of each element of the sequence must be given in
square brackets.
In this example, both a PDU name (Source Identifier) and a field In this example, both a PDU name (Source Identifier) and a field
name (CC) are used in the constraint expression. The PDU name name (CC) are used in the constraint expression. The PDU name
refers to the length of the PDU, while the field name refers to refers to the length of the PDU, while the field name refers to
the value of the field. This is possible because field names the value of the field. This is possible because field names
cannot be the same as previously defined PDU names. cannot be the same as previously defined PDU names.
Header Extension: 32 bits; present only when X == 1. This is a field Header Extension: 32 bits; present only when X == 1. This is a field
whose presence is predicated on an expression given using the whose presence is predicated on an expression given using the
constraint expression grammar described earlier. Optional fields constraint expression grammar described earlier. Optional fields
skipping to change at page 15, line 17 skipping to change at page 15, line 18
[Note that this example deviates from the format as described in [Note that this example deviates from the format as described in
[RFC3550]. As specified in that document, the Header Extension [RFC3550]. As specified in that document, the Header Extension
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. size in a PDU.
Padding: Padding Count bytes; present only when (P == 1) and Padding: PC bytes; present only when (P == 1) && (PC > 0). This is a
(Padding Count > 0). variable size field, with size dependent on a later field in the
This is a variable size field, with size dependent on a later packet. Fields can only depend on the value of a later field if
field in the packet. Fields can only depend on the value of a they follow a field with unspecified size.
later field if they follow a field with unspecified size.
Padding Count: 1 byte; present only when P == 1. This is a fixed- Padding Count (PC): 1 byte; present only when P == 1. This is a
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
values. values.
This format is illustrated using the STUN Message Type This format is illustrated using the STUN Message Type
skipping to change at page 16, line 52 skipping to change at page 16, line 50
where: where:
Header Form (HF): 1 bit; HF == 1. This is a fixed-width field, Header Form (HF): 1 bit; HF == 1. This is a fixed-width field,
constrained to be a of an known, exact value. At most one field constrained to be a of an known, exact value. At most one field
value constraint may be given, and if provided, it must be given value constraint may be given, and if provided, it must be given
as a boolean expression, separated by a semi-colon in the field as a boolean expression, separated by a semi-colon in the field
definition name (i.e., the text contained within the <dt> tag). definition name (i.e., the text contained within the <dt> tag).
If present, a value constraint must follow the name, short name, If present, a value constraint must follow the name, short name,
and length of the field, but appear before any presence and length of the field, but appear before any presence
constraint, if applicable. constraint, if applicable. The order of the field must be the
same in both the diagram and description list.
The order of the field must be the same in both the diagram and
description list.
Fixed Bit (FB): 1 bit; FB == 1. This is a fixed-width field, with a Fixed Bit (FB): 1 bit; FB == 1. This is a fixed-width field, with a
value constraint, as previously described. value constraint, as previously described.
Long Packet Type (T): 2 bits. This is a fixed-width field as Long Packet Type (T): 2 bits. This is a fixed-width field as
previously described. previously described.
Reserved Bits (R): 2 bits. This is a fixed-width field as previously Reserved Bits (R): 2 bits. This is a fixed-width field as previously
described. described.
skipping to change at page 20, line 15 skipping to change at page 20, line 15
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
In this example, 'Unprotected Packet' and 'Protected Packet' are In this example, 'Unprotected Packet' and 'Protected Packet' are
existing types. existing types.
To indicate that a structure is created from another by way of a To indicate that a PDU is created from another by way of a function,
function: "A/An <structure type A> is constructed from a <structure the sentence "A/An <PDU name A> is parsed from a <PDU name B> using
type B> using the <function name>(<parameters>) function.". This the <function name> function" is used. This indicates that a PDU A
indicates that a structure of type A is generated using the named is generated by passing PDU B into the named function. The function
function. The parameters in the function call are named fields from must take a single parameter, of the same type as PDU B, and return a
structure type B. They must match the function signature, both in PDU B.
number and type.
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
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.
The function must take a single parameter, of the same type as PDU A,
and return a PDU B.
4.8. Specifying Enumerated Types 4.8. 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
skipping to change at page 21, line 5 skipping to change at page 21, line 13
A PING Frame is formatted as follows: A PING Frame 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 | | 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
where: where:
Frame Type (FT): 1 * Variable-Length Integer Encoding; FT == 1. Frame Type (FT): 1 Variable-Length Integer Encoding; FT == 1. Frame
Frame type, set to 1 for PING frames. type, set to 1 for PING frames.
A HANDSHAKE_DONE Frame is formatted as follows: A HANDSHAKE_DONE Frame 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 | | 30 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
where: where:
Frame Type (FT): 1 * Variable-Length Integer Encoding; FT == 30. Frame Type (FT): 1 Variable-Length Integer Encoding; FT == 30. Frame
Frame type, set to 30 for HANDSHAKE_DONE frames. type, set to 30 for HANDSHAKE_DONE frames.
A Frame is either a PING Frame or a HANDSHAKE_DONE Frame. A Frame is either a PING Frame or a HANDSHAKE_DONE Frame.
4.9. Specifying Protocol Data Units 4.9. 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 21, line 41 skipping to change at page 21, line 49
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.
The Example protocol uses Long Headers, STUN Message Types, IPv4 This document describes the Example protocol. The Example protocol
Headers, and RTP Data Packets. uses Long Headers, STUN Message Types, IPv4 Headers, and RTP Data
Packets.
4.10. Importing PDU Definitions from Other Documents 4.10. 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.
skipping to change at page 25, line 10 skipping to change at page 25, line 10
Appendix A. ABNF specification Appendix A. ABNF specification
A.1. Constraint Expressions A.1. Constraint Expressions
cond-expr = eq-expr "?" cond-expr ":" eq-expr cond-expr = eq-expr "?" cond-expr ":" eq-expr
eq-expr = bool-expr eq-op bool-expr eq-expr = bool-expr eq-op bool-expr
bool-expr = ord-expr bool-op ord-expr bool-expr = ord-expr bool-op ord-expr
ord-expr = add-expr ord-op add-expr ord-expr = add-expr ord-op add-expr
add-expr = mul-expr add-op mul-expr add-expr = mul-expr add-op mul-expr
mul-expr = expr mul-op expr mul-expr = pow-expr mul-op pow-expr
pow-expr = expr pow-op expr
expr = *DIGIT / field-name / expr = *DIGIT / field-name /
field-name-ws / "(" expr ")" field-name-ws / "(" expr ")"
field-name = *ALPHA field-name = ALPHA *(ALPHA / DIGIT)
field-name-ws = *(field-name " ") field-name-ws = *(field-name " ")
pow-op = "^"
mul-op = "*" / "/" / "%" mul-op = "*" / "/" / "%"
add-op = "+" / "-" add-op = "+" / "-"
ord-op = "<=" / "<" / ">=" / ">" ord-op = "<=" / "<" / ">=" / ">"
bool-op = "&&" / "||" / "!" bool-op = "&&" / "||" / "!"
eq-op = "==" / "!=" eq-op = "==" / "!="
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
 End of changes. 18 change blocks. 
35 lines changed or deleted 43 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/