< draft-mcquistin-augmented-ascii-diagrams-02.txt   draft-mcquistin-augmented-ascii-diagrams-03.txt >
Network Working Group S. McQuistin Network Working Group S. McQuistin
Internet-Draft V. Band Internet-Draft V. Band
Intended status: Experimental C. S. Perkins Intended status: Experimental D. Jacob
Expires: 7 August 2020 University of Glasgow Expires: 10 September 2020 C. S. Perkins
4 February 2020 University of Glasgow
9 March 2020
Describing Protocol Data Units with Augmented Packet Header Diagrams Describing Protocol Data Units with Augmented Packet Header Diagrams
draft-mcquistin-augmented-ascii-diagrams-02 draft-mcquistin-augmented-ascii-diagrams-03
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 37 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 7 August 2020. This Internet-Draft will expire on 10 September 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 15 skipping to change at page 2, line 16
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 . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . 9 4. Augmented Packet Header Diagrams . . . . . . . . . . . . . . 9
4.1. PDUs with Fixed and Variable-Width Fields . . . . . . . . 9 4.1. PDUs with Fixed and Variable-Width Fields . . . . . . . . 10
4.2. PDUs That Cross-Reference Previously Defined Fields . . . 12 4.2. PDUs That Cross-Reference Previously Defined Fields . . . 12
4.3. PDUs with Non-Contiguous Fields . . . . . . . . . . . . . 15 4.3. PDUs with Non-Contiguous Fields . . . . . . . . . . . . . 15
4.4. Importing PDU Definitions from Other Documents . . . . . 15 4.4. Importing PDU Definitions from Other Documents . . . . . 15
5. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 16 5. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 16
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 16 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 17
9. Informative References . . . . . . . . . . . . . . . . . . . 17 9. Informative References . . . . . . . . . . . . . . . . . . . 17
Appendix A. ABNF specification . . . . . . . . . . . . . . . . . 18 Appendix A. ABNF specification . . . . . . . . . . . . . . . . . 18
A.1. Constraint Expressions . . . . . . . . . . . . . . . . . 18 A.1. Constraint Expressions . . . . . . . . . . . . . . . . . 18
A.2. Augmented packet diagrams . . . . . . . . . . . . . . . . 18 A.2. Augmented packet diagrams . . . . . . . . . . . . . . . . 19
Appendix B. Source code repository . . . . . . . . . . . . . . . 19 Appendix B. Source code repository . . . . . . . . . . . . . . . 19
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19
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.
skipping to change at page 3, line 41 skipping to change at page 3, line 41
format for their packet descriptions. Indeed, this underpins the format for their packet descriptions. Indeed, this underpins the
format described by this draft: we want to retain the benefits that format described by this draft: we want to retain the benefits that
packet header diagrams provide, while identifying the benefits of packet header diagrams provide, while identifying the benefits of
adopting a consistent format. adopting a consistent format.
This document describes a consistent packet header diagram format and 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 writing, are described, before the format itself
itself is given. 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 packet header diagrams and structured text format described with the packet header diagrams and structured text format described
by example. Examples that do not form part of the protocol by example. Examples that do not form part of the protocol
description language are marked by a colon at the beginning of each description language are marked by a colon at the beginning of each
line; this prevents them from being parsed by the accompanying line; this prevents them from being parsed by the accompanying
tooling. tooling.
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
skipping to change at page 8, line 7 skipping to change at page 8, line 7
written for people, who require text and diagrams that they can written for people, who require text and diagrams that they can
understand. Structures that cannot be easily parsed by people understand. Structures that cannot be easily parsed by people
should be avoided, and if included, should be clearly delineated should be avoided, and if included, should be clearly delineated
from human-readable content. from human-readable content.
Any approach that shifts this balance -- that is, that primarily Any approach that shifts this balance -- that is, that primarily
targets machine readers -- is likely to be disruptive to the targets machine readers -- is likely to be disruptive to the
standardisation process, which relies upon discussion centered standardisation process, which relies upon discussion centered
around documents written in prose. around documents written in prose.
Authorship tools are diverse: Authorship is a distributed process Writing tools are diverse: Standards document writing is a
that involves a diverse set of tools and workflows. The distributed process that involves a diverse set of tools and
introduction of machine-readable structures into specifications workflows. The introduction of machine-readable structures into
should not require that specific tools are used to produce specifications should not require that specific tools are used to
standards documents, to ensure that disruption to existing produce standards documents, to ensure that disruption to existing
workflows is minimised. This does not preclude the development of workflows is minimised. This does not preclude the development of
optional, supplementary tools that aid in the authoring machine- optional, supplementary tools that aid in the authoring machine-
readable structures. readable structures.
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
skipping to change at page 9, line 13 skipping to change at page 9, line 13
guarantee intrinsic safety, security, and computability properties guarantee intrinsic safety, security, and computability properties
of both the generated parser code for the protocol, and the parser of both the generated parser code for the protocol, and the parser
of the description language itself. In much the same way as the of the description language itself. In much the same way as the
language-theoretic security ([LANGSEC]) community advocates for language-theoretic security ([LANGSEC]) community advocates for
programming language design to be informed by the desired programming language design to be informed by the desired
properties of the parsers for those languages, protocol designers properties of the parsers for those languages, protocol designers
should be aware of the implications of their design choices. The should be aware of the implications of their design choices. The
expressiveness of the protocol description languages that they use expressiveness of the protocol description languages that they use
to define their protocols can force such awareness. to define their protocols can force such awareness.
Broadly, those languages that are more expressive tend to have Broadly, those languages that have grammars which are more
parsers that are more complex and less safe. As a result, while expressive tend to have parsers that are more complex and less
considering the other goals described in this document, protocol safe. As a result, while considering the other goals described in
description languages should attempt to be minimally expressive, this document, protocol description languages should attempt to be
and restrict protocol designs to those for which safe and secure minimally expressive, and either restrict protocol designs to
parsers can be generated. those for which safe and secure parsers can be generated, or as a
minimum, ensure that protocol designers are aware of the
boundaries their designs cross, in terms of computability and
decidability [SASSAMAN].
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 that 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 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 packet header diagrams. These diagrams aid the existing uses of packet header diagrams. These diagrams aid
human readability, do not require new or specialised authorship human readability, do not require new or specialised tools to write,
tools, do not split the specification into multiple parts, can do not split the specification into multiple parts, can express most
express most binary protocol features, and require no changes to binary protocol features, and require no changes to existing
existing publication processes. 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
packet header diagrams are used that must be addressed if they are to packet header diagrams are used that must be addressed if they are to
be parsed by machine. In this section, an augmented 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 packet diagrams will be given in specification of the augmented packet diagrams will be given in
skipping to change at page 10, line 8 skipping to change at page 10, line 14
4.1. PDUs with Fixed and Variable-Width Fields 4.1. PDUs with Fixed and Variable-Width Fields
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.
Some packet formats include variable-width fields, where the size of Some packet formats include variable-width fields, where the size of
a field is either derived from the value of some previous field, or a field is either derived from the value of some previous field, or
is unspecified and inferred from the total size of the packet and the is unspecified and inferred from the total size of the packet and the
size of the other fields. A packet can contain only one unspecified size of the other fields.
length field, to ensure there is no ambiguity.
To ensure that there is no ambiguity, a PDU description can contain
only one field whose length is unspecified. The length of a single
field, where all other fields are of known (but perhaps variable)
length, can be inferred from the total size of the containing PDU.
A PDU description is introduced by the exact phrase "A/An _______ is A PDU description is introduced by the exact phrase "A/An _______ is
formatted as follows:" at the end of a paragraph. This is followed formatted as follows:" at the end of a paragraph. This is followed
by the PDU description itself, as a packet diagram within an by the PDU description itself, as a packet diagram within an
<artwork> element in the XML representation, starting with a header <artwork> element in the XML representation, starting with a header
line to show the bit width of the diagram. The description of the 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 fields follows the diagram, as an XML <dl> list, after a paragraph
containing the text "where:". containing the text "where:".
PDU names must be unique, both within a document, and across all
documents that are linked together (i.e., using the structured
language defined in Section 4.4).
Each field of the description starts with a <dt> tag comprising the Each field of the description starts with a <dt> tag comprising the
field name and an optional short name in parenthesis. These are field name and an optional short name in parenthesis. These are
followed by a colon, the field length, an optional presence followed by a colon, the field length, an optional presence
expression (described in Section 4.2), and a terminating period. The expression (described in Section 4.2), and a terminating period. The
following <dd> tag contains a prose description of the field. Field following <dd> tag contains a prose description of the field. Field
names cannot be the same as a previously defined PDU name. names cannot be the same as a previously defined PDU name, and must
be unique within a given structure definition.
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 19 skipping to change at page 18, line 27
[RFC791] Postel, J., "Internet Protocol", RFC 791, September 1981, [RFC791] Postel, J., "Internet Protocol", RFC 791, September 1981,
<https://www.rfc-editor.org/info/rfc791>. <https://www.rfc-editor.org/info/rfc791>.
[RFC793] Postel, J., "Transmission Control Protocol", RFC 793, [RFC793] Postel, J., "Transmission Control Protocol", RFC 793,
September 1981, <https://www.rfc-editor.org/info/rfc793>. September 1981, <https://www.rfc-editor.org/info/rfc793>.
[LANGSEC] LANGSEC, "LANGSEC: Language-theoretic Security", [LANGSEC] LANGSEC, "LANGSEC: Language-theoretic Security",
<http://langsec.org>. <http://langsec.org>.
[SASSAMAN] Sassaman, L., Patterson, M. L., Bratus, S., and A.
Shubina, "The Halting Problems of Network Stack
Insecurity", ;login: -- December 2011, Volume 36, Number
6, <https://www.usenix.org/publications/login/december-
2011-volume-36-number-6/halting-problems-network-stack-
insecurity>.
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 = expr mul-op expr
expr = *DIGIT / field-name / expr = *DIGIT / field-name /
field-name-ws / "(" expr ")" field-name-ws / "(" expr ")"
skipping to change at page 19, line 7 skipping to change at page 19, line 34
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
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 Appendix B. Source code repository
The source for this draft is available from https://github.com/
glasgow-ipl/draft-mcquistin-augmented-ascii-diagrams.
The source code for tooling that can be used to parse this document The source code for tooling that can be used to parse this document
is available from https://github.com/lumisota/improving-protocol- is available from https://github.com/glasgow-ipl/ips-protodesc-code.
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
skipping to change at page 19, line 21 skipping to change at page 20, line 4
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
Vivian Band Vivian Band
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: vivianband0@gmail.com Email: vivianband0@gmail.com
Dejice Jacob
University of Glasgow
School of Computing Science
Glasgow
G12 8QQ
United Kingdom
Email: d.jacob.1@research.gla.ac.uk
Colin Perkins Colin Perkins
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: csp@csperkins.org Email: csp@csperkins.org
 End of changes. 19 change blocks. 
32 lines changed or deleted 61 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/