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.46. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ |