< draft-mcquistin-augmented-ascii-diagrams-05.txt   draft-mcquistin-augmented-ascii-diagrams-06.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: 19 December 2020 C. S. Perkins Expires: 14 January 2021 C. S. Perkins
University of Glasgow University of Glasgow
17 June 2020 13 July 2020
Describing Protocol Data Units with Augmented Packet Header Diagrams Describing Protocol Data Units with Augmented Packet Header Diagrams
draft-mcquistin-augmented-ascii-diagrams-05 draft-mcquistin-augmented-ascii-diagrams-06
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 19 December 2020. This Internet-Draft will expire on 14 January 2021.
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 31 skipping to change at page 2, line 31
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 . . . . . 22 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 . . . . . . . . . . . . . . . . . 25
A.1. Constraint Expressions . . . . . . . . . . . . . . . . . 24 A.1. Constraint Expressions . . . . . . . . . . . . . . . . . 25
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 . . . . . . . . . . . . . . . . . . . . . . . 26
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 18, line 30 skipping to change at page 18, line 30
| | | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
where: where:
Long Header (LH): 1 Long Header; LH.T == 3. This field is a Long Header (LH): 1 Long Header; LH.T == 3. This field is a
previously defined sub-structure. Its constraints can access previously defined sub-structure. Its constraints can access
fields in that sub-structure. In this example, the T field of the fields in that sub-structure. In this example, the T field of the
Long Header must be equal to 3. Long Header must be equal to 3.
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.6. Storing Data for Parsing
skipping to change at page 20, line 48 skipping to change at page 20, line 48
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 Frame is either a PING Frame or a HANDSHAKE_DONE Frame.
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 Frame Type (FT): 1 byte; FT == 1. Frame type, set to 1 for PING
type, set to 1 for PING frames. 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 Frame Type (FT): 1 byte; FT == 30. Frame type, set to 30 for
type, set to 30 for HANDSHAKE_DONE frames. HANDSHAKE_DONE frames.
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.
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, and RTP Data
skipping to change at page 23, line 16 skipping to change at page 23, line 16
description language has implications for the safety, security, and description language has implications for the safety, security, and
computability properties of the parser for the protocol description computability properties of the parser for the protocol description
language itself, and on the generated parser code for the protocols language itself, and on the generated parser code for the protocols
described using it. The language-theoretic security ([LANGSEC]) described using it. The language-theoretic security ([LANGSEC])
community explores the security implications of programming language community explores the security implications of programming language
design; the principles developed in that community should guide the design; the principles developed in that community should guide the
development of protocol description languages. development of protocol description languages.
8. Acknowledgements 8. Acknowledgements
The authors would like to thank Marc Petit-Huguenin for extensive
feedback on the draft, including work on formalising the constraint
syntax as given in Appendix A.1.
The authors would like to thank David Southgate for preparing a The authors would like to thank David Southgate for preparing a
prototype implementation of some of the ideas described here. prototype implementation of some of the ideas described here.
The authors would like to thank Marc Petit-Huguenin for feedback on
the draft.
This work has received funding from the UK Engineering and Physical This work has received funding from the UK Engineering and Physical
Sciences Research Council under grant EP/R04144X/1. Sciences Research Council under grant EP/R04144X/1.
9. Informative References 9. Informative References
[RFC8357] Deering, S. and R. Hinden, "Generalized UDP Source Port [RFC8357] Deering, S. and R. Hinden, "Generalized UDP Source Port
for DHCP Relay", RFC 8357, March 2018, for DHCP Relay", RFC 8357, March 2018,
<https://www.rfc-editor.org/info/rfc8357>. <https://www.rfc-editor.org/info/rfc8357>.
[QUIC-TRANSPORT] [QUIC-TRANSPORT]
skipping to change at page 24, line 9 skipping to change at page 24, line 9
<https://www.rfc-editor.org/info/rfc7950>. <https://www.rfc-editor.org/info/rfc7950>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, August 2018, Version 1.3", RFC 8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>. <https://www.rfc-editor.org/info/rfc8446>.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 5234, January 2008, Specifications: ABNF", RFC 5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>. <https://www.rfc-editor.org/info/rfc5234>.
[RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF",
RFC 7405, December 2014,
<https://www.rfc-editor.org/info/rfc7405>.
[ASN1] ITU-T, "ITU-T Recommendation X.680, X.681, X.682, and [ASN1] ITU-T, "ITU-T Recommendation X.680, X.681, X.682, and
X.683", ITU-T Recommendation X.680, X.681, X.682, and X.683", ITU-T Recommendation X.680, X.681, X.682, and
X.683. X.683.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, October 2013, Representation (CBOR)", RFC 7049, October 2013,
<https://www.rfc-editor.org/info/rfc7049>. <https://www.rfc-editor.org/info/rfc7049>.
[RFC3550] Schulzrinne, H., Casner, S., Frederick, R., and V. [RFC3550] Schulzrinne, H., Casner, S., Frederick, R., and V.
Jacobson, "RTP: A Transport Protocol for Real-Time Jacobson, "RTP: A Transport Protocol for Real-Time
skipping to change at page 25, line 4 skipping to change at page 25, line 8
[SASSAMAN] Sassaman, L., Patterson, M. L., Bratus, S., and A. [SASSAMAN] Sassaman, L., Patterson, M. L., Bratus, S., and A.
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>.
Appendix A. ABNF specification Appendix A. ABNF specification
A.1. Constraint Expressions A.1. Constraint Expressions
cond-expr = eq-expr "?" cond-expr ":" eq-expr
eq-expr = bool-expr eq-op bool-expr
bool-expr = ord-expr bool-op ord-expr
ord-expr = add-expr ord-op add-expr
add-expr = mul-expr add-op mul-expr field-def = name ["(" short-name ")"]
mul-expr = pow-expr mul-op pow-expr [":" sp ((length [";" sp (bool-expr /
pow-expr = expr pow-op expr (bool-expr ";" sp presence-constraint))]) /
expr = *DIGIT / field-name / (bool-expr [(";" sp presence-constraint)]) /
field-name-ws / "(" expr ")" presence-constraint)] "."
presence-constraint = "present only when " bool-expr
field-name = ALPHA *(ALPHA / DIGIT) constant = %x31-39 *(%x30-39) ; natural numbers without leading 0s
field-name-ws = *(field-name " ") short-name = ALPHA *(ALPHA / DIGIT / "-" / "_")
name = short-name *(" " short-name)
pow-op = "^" sp = [" "] ; optional space in expression
mul-op = "*" / "/" / "%" bool-expr = "(" sp bool-expr sp ")" /
add-op = "+" / "-" "!" sp bool-expr /
ord-op = "<=" / "<" / ">=" / ">" bool-expr sp bool-op sp bool-expr /
bool-op = "&&" / "||" / "!" bool-expr sp "?" sp expr sp ":" sp expr /
eq-op = "==" / "!=" expr sp cmp-op sp expr
bool-op = "&&" / "||"
cmp-op = "==" / "!=" / "<" / "<=" / ">" / ">="
expr = "(" sp expr sp ")" /
expr sp "^" sp expr /
expr sp muldiv-op sp expr /
expr sp addsub-op sp expr /
bool-expr "?" expr ":" expr /
name / short-name "." short-name /
short-name "#" "Size" /
constant
muldiv-op = "*" / "/" / "%"
addsub-op = "+" / "-"
length = expr " " unit / "[" sp name sp "]"
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
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.
 End of changes. 16 change blocks. 
37 lines changed or deleted 52 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/