-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathdraft-mcquistin-augmented-ascii-diagrams-12.xml
1679 lines (1584 loc) · 84.4 KB
/
draft-mcquistin-augmented-ascii-diagrams-12.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version='1.0' encoding='US-ASCII'?>
<rfc version='3' ipr='trust200902' submissionType='IETF' docName='draft-mcquistin-augmented-ascii-diagrams-12' category='exp'>
<front>
<title abbrev='Augmented Packet Diagrams'>
Describing Protocol Data Units with Augmented Packet Header Diagrams
</title>
<seriesInfo name='Internet-Draft' value='draft-mcquistin-augmented-ascii-diagrams-12' status="experimental" />
<author fullname='Stephen McQuistin' initials='S.' surname='McQuistin'>
<organization>University of Glasgow</organization>
<address>
<postal>
<street>School of Computing Science</street>
<city>Glasgow</city>
<code>G12 8QQ</code>
<country>UK</country>
</postal>
<email>[email protected]</email>
</address>
</author>
<author fullname='Vivian Band' initials='V.' surname='Band'>
<organization>University of Glasgow</organization>
<address>
<postal>
<street>School of Computing Science</street>
<city>Glasgow</city>
<code>G12 8QQ</code>
<country>UK</country>
</postal>
<email>[email protected]</email>
</address>
</author>
<author fullname='Dejice Jacob' initials='D.' surname='Jacob'>
<organization>University of Glasgow</organization>
<address>
<postal>
<street>School of Computing Science</street>
<city>Glasgow</city>
<code>G12 8QQ</code>
<country>UK</country>
</postal>
<email>[email protected]</email>
</address>
</author>
<author fullname='Colin Perkins' initials='C. S.' surname='Perkins'>
<organization>University of Glasgow</organization>
<address>
<postal>
<street>School of Computing Science</street>
<city>Glasgow</city>
<code>G12 8QQ</code>
<country>UK</country>
</postal>
<email>[email protected]</email>
</address>
</author>
<?date year='2022' month='September' day='5'/?>
<abstract>
<t>
This document describes a machine-readable format for specifying
the syntax of protocol data units within a protocol specification.
This format is comprised of a consistently formatted packet header
diagram, followed by structured explanatory text. It is
designed to maintain human readability while enabling support for
automated parser generation from the specification document. This
document is itself an example of how the format can be used.
</t>
</abstract>
</front>
<middle>
<section anchor='intro'>
<name>Introduction</name>
<t>
Packet header diagrams have become a widely used format for
describing the syntax of binary protocols. In otherwise largely textual
documents, they allow for the visualisation of packet formats, reducing
human error, and aiding in the implementation of parsers for the protocols
that they specify.
</t>
<t>
<xref target="tcp-header-format"/> gives an example of how packet
header diagrams are used to define binary protocol formats. The format
has an obvious structure: the diagram clearly delineates each field,
showing its width and its position within the header. This type of diagram is
designed for human readers, but is consistent enough that it should
be possible to develop a tool that generates a parser for the packet
format from the diagram.
</t>
<figure anchor="tcp-header-format">
<name>TCP's header format (from <xref target="RFC793"/>)</name>
<artwork>
: 0 1 2 3
: 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Source Port | Destination Port |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Sequence Number |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Acknowledgment Number |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Data | |U|A|P|R|S|F| |
: | Offset| Reserved |R|C|S|S|Y|I| Window |
: | | |G|K|H|T|N|N| |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Checksum | Urgent Pointer |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Options | Padding |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | data |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</artwork>
</figure>
<t>
Unfortunately, the format of such packet diagrams varies both within
and between documents. This variation makes it difficult to build
tools to generate parsers from the specifications. Better tooling
could be developed if protocol specifications adopted a consistent
format for their packet descriptions. Indeed,
this underpins the format described by this draft: we want to
retain the benefits that packet header diagrams provide, while identifying
the benefits of adopting a consistent format.
</t>
<t>
This document describes a consistent packet header diagram format and
accompanying structured text constructs that allow for the parsing process
of protocol headers to be fully specified. This provides support for the
automatic generation of parser code. Broad design principles, that seek
to maintain the primacy of human readability and flexibility in
writing, are described, before the format itself is given.
</t>
<t>
This document is itself an example of the approach that it describes, with
the packet header diagrams and structured text format described by example.
Examples that do not form part of the protocol description language are
marked by a colon at the beginning of each line; this prevents them from
being parsed by the accompanying tooling.
</t>
<t>
This draft describes early work. As consensus builds around the
particular syntax of the format described, a formal ABNF
specification (<xref target="ABNF"/>) will be provided.
</t>
<t>
Code that parses
documents written using this format, and that automatically generates parser code for the described
protocols, is described in <xref target="source"/>.
</t>
</section>
<section anchor='background'>
<name>Background</name>
<t>
This section begins by considering how packet header diagrams are
used in existing documents. This exposes the limitations that the current
usage has in terms of machine-readability, guiding the design of the
format that this document proposes.
</t>
<t>
While this document focuses on the machine-readability of packet format
diagrams, this section also discusses the use of other structured or formal
languages within IETF documents. Considering how and why these languages
are used provides an instructive contrast to the relatively incremental
approach proposed here.
</t>
<section anchor='background-ascii'>
<name>Limitations of Current Packet Format Diagrams</name>
<figure anchor="quic-reset-stream">
<name>QUIC's RESET_STREAM frame format (from <xref target="QUIC-TRANSPORT"/>)</name>
<artwork>
: The RESET_STREAM frame is as follows:
:
: 0 1 2 3
: 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Stream ID (i) ...
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Application Error Code (16) |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Final Size (i) ...
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
:
: RESET_STREAM frames contain the following fields:
:
: Stream ID: A variable-length integer encoding of the Stream ID
: of the stream being terminated.
:
: Application Protocol Error Code: A 16-bit application protocol
: error code (see Section 20.1) which indicates why the stream
: is being closed.
:
: Final Size: A variable-length integer indicating the final size
: of the stream by the RESET_STREAM sender, in unit of bytes.
</artwork>
</figure>
<t>
Packet header diagrams are frequently used in IETF standards to describe the
format of binary protocols. While there is no standard for how
these diagrams should be formatted, they have a broadly similar structure,
where the layout of a protocol data unit (PDU) or structure is shown in
diagrammatic form, followed by a description list of the fields that it
contains. An example of this format, taken from the QUIC specification,
is given in <xref target="quic-reset-stream"/>.
</t>
<t>
These packet header diagrams, and the accompanying descriptions, are
formatted for human readers rather than for automated processing. As
a result, while there is rough consistency in how packet header diagrams are
formatted, there are a number of limitations that make them difficult
to work with programmatically:
</t>
<dl>
<dt>
Inconsistent syntax:
</dt>
<dd>
<t>
There are two classes of consistency that are needed to support
automated processing of specifications: internal consistency
within a diagram or document, and external consistency across
all documents.
</t>
<t>
<xref target="quic-reset-stream"/> gives an example of internal
inconsistency. Here, the packet diagram shows a field labelled
"Application Error Code", while the accompanying description lists
the field as "Application Protocol Error Code". The use of an
abbreviated name is suitable for human readers, but makes parsing
the structure difficult for machines.
<xref target="dhcpv6-relaysrcopt"/> gives a further example, where
the description includes an "Option-Code" field that does not appear
in the packet diagram; and where the description states that
each field is 16 bits in length, but the diagram shows
the OPTION_RELAY_PORT as 13 bits, and Option-Len as 19 bits.
Another example is <xref target="RFC6958"/>, where the packet
format diagram showing the structure of the Burst/Gap Loss Metrics
Report Block shows the Number of Bursts field as being 12 bits wide
but the corresponding text describes it as 16 bits.
</t>
<t>
Comparing <xref target="quic-reset-stream"/> with
<xref target="dhcpv6-relaysrcopt"/> exposes external
inconsistency across documents. While the packet format
diagrams are broadly similar, the surrounding text is
formatted differently. If machine parsing is to be made
possible, then this text must be structured consistently.
</t>
</dd>
<dt>
Ambiguous constraints:
</dt>
<dd>
The constraints that are enforced on a particular field are often
described ambiguously, or in a way that cannot be parsed easily.
In <xref target="dhcpv6-relaysrcopt"/>, each of the three fields
in the structure is constrained. The first two fields
("Option-Code" and "Option-Len") are to be set to constant values
(note the inconsistency in how these constraints are expressed in
the description). However, the third field ("Downstream Source
Port") can take a value from a constrained set. This constraint
is expressed in prose that cannot readily by understood by machine.
</dd>
<dt>
Poor linking between sub-structures:
</dt>
<dd>
<t>
Protocol data units and other structures are often comprised of
sub-structures that are defined elsewhere, either in the same
document, or within another document. Chaining these structures
together is essential for machine parsing: the parsing process for
a protocol data unit is only fully expressed if all elements can
be parsed.
</t>
<t>
<xref target="quic-reset-stream"/> highlights the difficulty that
machine parsers have in chaining structures together. Two fields
("Stream ID" and "Final Size") are described as being encoded as
variable-length integers; this is a structure described elsewhere
in the same document. Structured text is required both alongside
the definition of the containing structure and with the definition
of the sub-structure, to allow a parser to link the two together.
</t>
</dd>
<dt>
Lack of extension and evolution syntax:
</dt>
<dd>
<t>
Protocols are often specified across multiple documents, either
because the protocol explicitly includes extension points (e.g.,
profiles and payload format specifications in RTP
<xref target="RFC3550"/>) or because definition of a protocol
data unit has changed and evolved over time. As a result, it is
essential that syntax be provided to allow for a complete
definition of a protocol's parsing process to be constructed
across multiple documents.
</t>
</dd>
</dl>
<figure anchor="dhcpv6-relaysrcopt">
<name>DHCPv6's Relay Source Port Option (from <xref target="RFC8357"/>)</name>
<artwork>
: The format of the "Relay Source Port Option" is shown below:
:
: 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
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | OPTION_RELAY_PORT | Option-Len |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: | Downstream Source Port |
: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
:
: Where:
:
: Option-Code: OPTION_RELAY_PORT. 16-bit value, 135.
:
: Option-Len: 16-bit value to be set to 2.
:
: Downstream Source Port: 16-bit value. To be set by the IPv6
: relay either to the downstream relay agent's UDP source port
: used for the UDP packet, or to zero if only the local relay
: agent uses the non-DHCP UDP port (not 547).
</artwork>
</figure>
</section>
<section anchor='background-others'>
<name>Formal languages in standards documents</name>
<t>
A small proportion of IETF standards documents contain
structured and formal languages, including ABNF <xref target="RFC5234"/>,
ASN.1 <xref target="ASN1"/>, C, CBOR <xref target="RFC7049"/>, JSON,
the TLS presentation language <xref target="RFC8446"/>, YANG models
<xref target="RFC7950"/>, and XML. While this broad
range of languages may be problematic for the development of tooling
to parse specifications, these, and other, languages serve a range of
different use cases. ABNF, for example, is typically used to specify
text protocols, while ASN.1 is used to specify data structure
serialisation. This document specifies a structured language for specifying
the parsing of binary protocol data units.
</t>
</section>
</section>
<section anchor='augmentedascii'>
<name>Augmented Packet Header Diagrams</name>
<t>
As discussed in <xref target="background-ascii"/> there are
limitations to how packet header diagrams are used that must be addressed if they
are to be parsed by machine. In this section, an augmented packet
header diagram format is described. The principles that underpin the design of
this format are discussed in <xref target="designprinciples"/>.
</t>
<t>
The concept is illustrated by example, with accompanying explanatory descriptions.
This is appropriate, given the visual nature of the language. In future drafts a formal specification of the format will be given in <xref target="ABNF"/>.
</t>
<t>
Our examples are drawn from the specifications of TCP <xref target="RFC9293"/>,
STUN <xref target="RFC8489"/>, and QUIC <xref target="QUIC-TRANSPORT"/>. These examples
are illustrative only of the Augmented Packet Header Diagram format that we define in
this document, and they do not necessarily reflect the current state of the specifications
they are taken from. For example, the published QUIC specification <xref target="RFC9000"/>
does not use packet header diagrams to describe the syntax of the protocol.
</t>
<section anchor='ascii-simple'>
<name>Defining Protocol Data Units</name>
<t>
A PDU description is introduced by the exact phrase "A/An
_______ is formatted as follows" within a paragraph. Optionally, this
phrase can include a note or comment, delimited by commas, immediately
following the PDU name. That is, "A/An _______, with an optional
comment, is formatted as follows" can be used to introduce a PDU
description.
The introductory phrase is followed by the PDU description itself, as a packet
diagram within an <artwork> element (itself optionally
within a <figure> element) in the XML representation,
starting with a header line to show the bit width of the diagram.
The description of the fields follows the diagram, as an XML
list (either <dl> or hanging <list>), after a paragraph
that begins with the text "where:".
</t>
<t>
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 <xref target="ascii-import" />).
</t>
<t>
Each field is defined by a structured text definition and a
prose description. The structured text definition comprises
the field name and an optional short name in parenthesis.
These are followed by a colon, the field length, an optional expression
constraining the value of the field, an optional presence constraint,
and, optionally, a terminating period. Text following the terminating period is not
parsed, and this space can be used for optional notes or comments.
Field names cannot be the same as a
previously defined PDU name, and must be unique within a given
structure definition. The structured text definition is given
either in a <dt> tag (if using a <dl>) or as the "hangText"
(if using a hanging <list>) of a <t> element. The field's
prose description is given in the following <dd> element or
within the same <t> element. Prose descriptions may include
structured text (e.g., as defined in <xref target="ascii-store" />).
</t>
<t>
A PDU may be defined not only by the layout and type of
its fields, but also by the value of those fields. For
example, field values may be constrained to be of a
known exact value or to be within a range. The "Data Offset" and
"Reserved" fields in the example below make use of value constraints.
More generally,
our format enables a boolean expression to be attached to
a field, which must be true for the PDU to be parsed
successfully.
</t>
<t>
In addition, a PDU may contain fields that have a size that is specified in terms
of the value of another field. Our constraint syntax can be
used to specify the length of fields in known units (of bits, bytes,
or other structures). In the example below, the "Options" field is defined in units of
"TCP Option" structures, and this is indicated by square brackets in the
diagram and description list.
</t>
<t>
If the units are of variable-width, then it may
not be possible to specify the length of the sequence. However, it is
still necessary to be able to constrain the overall width of the
field. To support this, our constraint syntax includes a "size"
function that evaluates to the width, in bits, of the given named
field. The "Options" field in the example below makes use of this
syntax to constrain the size of the field.
</t>
<t>
Finally, the presence of a field in a PDU may depend on the value of
other fields in that PDU. As shown by the "Options" field in the example
below, a constraint expression can be attached to each field, where that
field is only present in the PDU when the expression is true.
</t>
<t>
We define an ABNF grammar for constraint expressions in <xref target="ABNF-constraints"/>.
This grammar is used across value, size, and presence constraint expressions.
</t>
<t>
These elements can be illustrated using the TCP Header format
<xref target="RFC9293"/>. A TCP Header is formatted as follows:
</t>
<artwork>
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source Port | Destination Port |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Sequence Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Acknowledgment Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data | |C|E|U|A|P|R|S|F| |
| Offset| Rsrvd |W|C|R|C|S|S|Y|I| Window Size |
| | |R|E|G|K|H|T|N|N| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Checksum | Urgent Pointer |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| [Options] |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| :
: Payload :
: |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</artwork>
<t>
where:
</t>
<dl>
<dt>
Source Port: 16 bits.
</dt>
<dd>
<t>
This is a fixed-width field, whose full label is shown in the diagram.
The field's width -- 16 bits -- is given in the label of the description list,
separated from the field's label by a colon.
</t>
</dd>
<dt>
Destination Port: 2 bytes.
</dt>
<dd>
<t>
This is a fixed-width field as previously described. Where fields
are an integral number of bytes in size, the field length can be
given in bytes rather than in bits.
</t>
</dd>
<dt>
Sequence Number: 32 bits.
</dt>
<dd>
<t>
This is a fixed-width field as previously described.
</t>
</dd>
<dt>
Acknowledgment Number: 32 bits.
</dt>
<dd>
<t>
This is a fixed-width field as previously described.
</t>
</dd>
<dt>
Data Offset (DOffset): 4 bits; DOffset >= 5.
</dt>
<dd>
<t>
This is a fixed-width field, with a constraint on its value. At
most one field value constraint may be given per field, and if
provided, it must be given as a boolean expression, separated by a
semi-colon in the field definition name (i.e., the text contained
within the <dt> tag or "hangText" attribute). If present, a
value constraint must follow the name, short name, and length of
the field, but appear before any presence constraint, if
applicable. The order of the field must be the same in both the
diagram and description list.
</t>
</dd>
<dt>
Reserved (Rsrvd): 4 bits; Rsrvd == 0.
</dt>
<dd>
<t>
This is a fixed-width field, with a value constraint, as previously
described. This is a shorter field, whose full label is too large
to be shown in the diagram. A short label (Rsrvd) is used in the
diagram, and this short label is provided, in brackets, after the
full label in the description list.
</t>
</dd>
<dt>
Control bits:
</dt>
<dd>
<t>Optionally, field description lists can be nested. If the XML element (either a
<dd> or a <t>) containing the description of a field contains an XML list (either <dl> or
hanging <list>) as its last element, then this nested list will be parsed for fields, and the
outer description will be ignored. In this example, "Control bits" describes the group of 8 single
bit fields that are described in the list that follows; it is these single bit fields that
will form part of the structure.</t>
<dl>
<dt>
CWR: 1 bit.
</dt>
<dd>
<t>
This is a fixed-width field as previously described.
</t>
</dd>
<dt>
ECE: 1 bit.
</dt>
<dd>
<t>
This is a fixed-width field as previously described.
</t>
</dd>
<dt>
URG: 1 bit.
</dt>
<dd>
<t>
This is a fixed-width field as previously described.
</t>
</dd>
<dt>
ACK: 1 bit.
</dt>
<dd>
<t>
This is a fixed-width field as previously described.
</t>
</dd>
<dt>
PSH: 1 bit.
</dt>
<dd>
<t>
This is a fixed-width field as previously described.
</t>
</dd>
<dt>
RST: 1 bit.
</dt>
<dd>
<t>
This is a fixed-width field as previously described.
</t>
</dd>
<dt>
SYN: 1 bit.
</dt>
<dd>
<t>
This is a fixed-width field, with a value constraint, as previously described.
</t>
</dd>
<dt>
FIN: 1 bit; (FIN == 0) || (SYN == 0).
</dt>
<dd>
<t>
This is a fixed-width field, with a value constraint, as previously described.
</t>
</dd>
</dl>
</dd>
<dt>
Window Size: 16 bits.
</dt>
<dd>
<t>
This is a fixed-width field as previously described.
</t>
</dd>
<dt>
Checksum: 16 bits.
</dt>
<dd>
<t>
This is a fixed-width field as previously described.
</t>
</dd>
<dt>
Urgent Pointer: 16 bits.
</dt>
<dd>
<t>
This is a fixed-width field as previously described.
</t>
</dd>
<dt>
Options: [TCP Option]; size(Options) == (DOffset-5)*32; present only when DOffset > 5.
</dt>
<dd>
<t>
This is a variable-width field that is comprised of a sequence
of TCP Option sub-structures. TCP Option is an enumerated type,
to be defined in <xref target="ascii-enums"/>. As defined, the
TCP Option type can be either 2 or 3 bytes, depending on the
option type. As a result, it is not possible to specify the
number of TCP Option structures that the Option field will
contain. However, the overall size of the field can be
constrained. The "size(Options) == (DOffset-5)*32" makes use
of the "size" function. This evaluates to the size, in bits, of
the named field. The argument passed to the "size" field must
be the name of the field being defined, or of a previously
defined field.
</t>
<t>
The "DOffset" field contains the number of 32-bit words that
are present in the TCP Header. By default, with no TCP options,
this is 5. As a result, the size of the Options field is
constrained to the value of DOffset, less 5, and multiplied to
get the value in bits.
</t>
<t>
The presence of the "Options" field is predicated on an expression.
Optional fields are indicated by the presence of "; present only when [expr]."
at the end of the definition term (i.e., the text contained
within the <dt> tag or "hangText" attribute).
</t>
</dd>
<dt>
Payload.
</dt>
<dd>
This is a multi-row variable-length field, denoted in the diagram by the ":" notation in the
field's border. The length of the Payload is not specified, and hence needs 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 size in a PDU
Fields where the length is not specified may also denote this with the
phrase "variable length" in place of the length definition.
</dd>
</dl>
<t>
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 packet format.
</t>
<t>
Some packet formats include variable-width fields (e.g., the "Options" field
in the example above), where
the size of 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 size of the other
fields.
</t>
<t>
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. For example, the "Payload" field
in the example above is unspecified; its length can be determined by
subtracting the length of the other fields from the total size of the
PDU.
</t>
</section>
<section anchor="ascii-xref">
<name>Cross-Referencing Previously Defined Fields</name>
<t>
Binary formats often reference sub-structures that have been
defined earlier in the specification. For example, in TCP
<xref target="RFC9293"/>, the SACK Range Option (a TCP option type, as will be
discussed in <xref target="ascii-enums" />) is defined in terms of
of SACK blocks. A SACK Block is formatted as follows:
</t>
<artwork>
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Left Edge |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Right Edge |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</artwork>
<t>
where:
</t>
<dl>
<dt>
Left Edge: 4 bytes.
</dt>
<dd>
This is a fixed-width field, as described previously.
</dd>
<dt>
Right Edge: 4 bytes.
</dt>
<dd>
This is a fixed-width field, as described previously.
</dd>
</dl>
<t>
The SACK Block sub-structure is then used in the definition of the
SACK Range Option.
</t>
<t>
A SACK Range Option is formatted as follows:
</t>
<artwork>
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 5 | Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| [Blocks] |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</artwork>
<t>
where:
</t>
<dl>
<dt>
Option Kind (Kind): 1 byte; Kind == 5.
</dt>
<dd>
This is a fixed-width field, as described previously.
</dd>
<dt>
Option Length (Length): 1 byte.
</dt>
<dd>
This is a fixed-width field, as described previously.
</dd>
<dt>
Blocks: (Length-2)/8 SACK Blocks.
</dt>
<dd>
<t>
Where a field is comprised of a sequence of previously defined structures,
square brackets can be used to indicate this in the diagram. The length
of the sequence can be defined using the constraint expression
grammar as described earlier. Where the length is unknown, the type of each
element of the sequence must be given in square brackets.
</t>
<t>
In this example, both a PDU name (SACK Block) and a field name (Length) are
used in the constraint expression. This is possible
because field names cannot be the same as previously defined PDU names.
</t>
</dd>
</dl>
</section>
<section anchor='ascii-enums'>
<name>Specifying Enumerated Types</name>
<t>
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 alternative structures.
</t>
<t>
The alternative structures that comprise an enumerated type are identified using the exact phrase "The <enumerated type name>
is one of: <list of structure names>" where the list of structure names is a comma
separated list (with the last element, if there is more than one element, preceded by 'or'),
each optionally preceded by "a" or "an". The structure names must be defined within the document or a linked document.
Optionally, this phrase can include a note or comment, delimited by commas, immediately
following the enumerated type name. That is, "The <enumerated type name>, with an
optional comment, is one of: <list of structure names>" can be used to define an enumerated type. In both
cases, the colon is optional; for example, "The <enumerated type name> is one of <list of structure
names>" is valid.
</t>
<t>
Where an enumerated type has only two variants, an alternative phrase 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 within the document or a linked document.
An optional note or comment can be included with this alternative phrasing: "The <enumerated type name>, with an optional comment, is either a <variant 1 name> or <variant 2 name>" can be used.
</t>
<t>
An EOL Option is formatted as follows:
</t>
<artwork>
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
| 0 |
+-+-+-+-+-+-+-+-+
</artwork>
<t>
where:
</t>
<dl>
<dt>
Option Kind (Kind): 1 byte; Kind == 0.
</dt>
<dd>
<t>
This is a fixed-width field, with a value constraint, as previously described.
</t>
</dd>
</dl>
<t>
A TCP Option is either an EOL Option or a SACK Range Option.
</t>
</section>
<section anchor='ascii-split'>
<name>Splitting Fields</name>
<t>
In some binary formats, fields are striped across multiple
non-contiguous bits. This is often to allow for backwards
compatibility with previous definitions of the same fields
in earlier documents: striping in this way allows for
careful use of the possible range of values.
</t>
<t>
This format is illustrated using the STUN Message Type
<xref target="RFC8489"/>.
A STUN Message Type is formatted as follows:
</t>
<artwork>
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|M|M|M|M|M|C|M|M|M|C|M|M|M|M|
|B|A|9|8|7|1|6|5|4|0|3|2|1|0|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</artwork>
<t>
where:
</t>
<dl>
<dt>
Method (M): 12 bits (split field).
</dt>
<dd>
This field is comprised of multiple sub-fields (M0 through
MB) as shown in the diagram. That these sub-fields should be
concatenated, after parsing, into a single field is indicated
by their being labelled using the 'M' short field name
followed by a single hexadecimal digit, with the least significant
bit labelled with 0, and subsequent bits labelled in sequence.
</dd>
<dt>
Class (C): 2 bits (split field).
</dt>
<dd>
This field follows the same format as M described above.
</dd>
</dl>
</section>
<section anchor='ascii-extendstructures'>
<name>Extending Sub-Structures</name>
<t>
A PDU may not only use or reference existing sub-structures, but they
may extend them, adding new fields, or enforcing different or additional constraints.
</t>
<t>
Where a sub-structure is extended, the diagram may show the sub-structure as
a block, labelled with the sub-structure name. It may also be desirable to
show the sub-structure diagram in full; in this case, the fields must be
given in the same order and be of the same length. New field constraints
can be shown. Similarly, in the description list, those fields inherited
without change (i.e., with no change to their constraints) do not need to
be repeated. Those with different or additional constraints must be described,
and the order of the fields in the description list must match that of the
sub-structure and the containing structure.
</t>
<t>
This can be illustrated using QUIC <xref target="QUIC-TRANSPORT"/>.
A Long Header is formatted as follows:</t>
<artwork>
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
+-+-+-+-+-+-+-+-+
|1|1| T | R | P |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| DCID Len |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Destination Connection ID (DCID) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| SCID Len |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source Connection ID (SCID) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</artwork>
<t>
where:
</t>
<dl>
<dt>
Header Form (HF): 1 bit; HF == 1.
</dt>
<dd>
This is a fixed-width field, with a value constraint, as previously described.
</dd>
<dt>
Fixed Bit (FB): 1 bit; FB == 1.
</dt>
<dd>
This is a fixed-width field, with a value constraint, as previously described.
</dd>
<dt>
Long Packet Type (T): 2 bits.
</dt>
<dd>
This is a fixed-width field as previously described.
</dd>
<dt>
Reserved Bits (R): 2 bits.
</dt>
<dd>
This is a fixed-width field as previously described.
</dd>
<dt>
Packet Number Length (P): 2 bits.
</dt>
<dd>
This is a fixed-width field as previously described.
</dd>
<dt>
Version ID (VID): 32 bits.
</dt>
<dd>
This is a fixed-width field as previously described.
</dd>
<dt>
DCID Len (DLen): 1 byte; DLen <= 20.
</dt>
<dd>