Skip to content

Commit 60beed4

Browse files
authored
docs(protocols): second pass over link and transport (#1103) (#1784)
Reads the link and transport data models and the tcp.rst and sctp.rst autodoc lists left unread by the first pass, and takes the review items. - data l2tp: Flags carries no version; L2TP.flags points at version - data tcp: hdr_len is the Data Offset in octets; TSval/TSecr named; POC-SP is the connection service profile option; MP_CAPABLE H means HMAC-SHA1 in version 0 and HMAC-SHA256 in version 1 (schema, make too) - data udp: "header includes" reworded - vlan: the header table printed vlan.* keys; info uses c_tag/s_tag - tcp: the #616 bullet names connection rather than flags; the _MPTCP Option.registry reference now resolves to EnumSchema.registry ast.dump is identical with docstrings blanked; tests/project and the 57 related test files pass. Refs #1103
1 parent a34f757 commit 60beed4

7 files changed

Lines changed: 31 additions & 25 deletions

File tree

‎docs/source/pcapkit/protocols/link/vlan.rst‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,16 +18,17 @@ modules of their own:
1818
* - ``0x88A8`` (service tag, 802.1ad)
1919
- :class:`~pcapkit.protocols.link.s_tag.S_Tag`
2020

21-
The tag structure is described as below:
21+
The tag structure is described as below, keyed as for a customer tag; a service
22+
tag's keys start ``s_tag`` instead:
2223

2324
======= ========= ====================== =============================
2425
Octets Bits Name Description
2526
======= ========= ====================== =============================
26-
0 0 ``vlan.tci`` Tag Control Information
27-
0 0 ``vlan.tci.pcp`` Priority Code Point
28-
0 3 ``vlan.tci.dei`` Drop Eligible Indicator
29-
0 4 ``vlan.tci.vid`` VLAN Identifier
30-
2 16 ``vlan.type`` Protocol (Internet Layer)
27+
0 0 ``c_tag.tci`` Tag Control Information
28+
0 0 ``c_tag.tci.pcp`` Priority Code Point
29+
0 3 ``c_tag.tci.dei`` Drop Eligible Indicator
30+
0 4 ``c_tag.tci.vid`` VLAN Identifier
31+
2 16 ``c_tag.type`` Protocol (Internet Layer)
3132
======= ========= ====================== =============================
3233

3334
The two tags carry an identical tag control information layout and differ only

‎pcapkit/protocols/data/link/l2tp.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717

1818
@info_final
1919
class Flags(Data):
20-
"""Data model for L2TP flags and version info."""
20+
"""Data model for L2TP flags."""
2121

2222
#: Type.
2323
type: 'Type'
@@ -43,7 +43,7 @@ def __init__(self, type: 'Type', len: 'bool', seq: 'bool', offset: 'bool', prio:
4343
class L2TP(Protocol):
4444
"""Data model for L2TP packet."""
4545

46-
#: Flags and version info.
46+
#: Flags; the version nibble is :attr:`version`.
4747
flags: 'Flags'
4848
#: Version.
4949
version: 'int'

‎pcapkit/protocols/data/transport/tcp.py‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ class TCP(Protocol):
8686
seq: 'int'
8787
#: Acknowledgment number.
8888
ack: 'int'
89-
#: Data offset.
89+
#: Header length, i.e. the Data Offset in octets.
9090
hdr_len: 'int'
9191
#: Flags.
9292
flags: 'Flags'
@@ -225,9 +225,9 @@ def __init__(self, kind: 'OptionNumber', length: 'int', data: 'bytes') -> 'None'
225225
class Timestamps(Option):
226226
"""Data model for TCP timestamp option."""
227227

228-
#: Timestamp .
228+
#: Timestamp value.
229229
timestamp: 'int'
230-
#: Echo data.
230+
#: Timestamp echo reply.
231231
echo: 'int'
232232

233233
if TYPE_CHECKING:
@@ -244,7 +244,7 @@ def __init__(self, kind: 'OptionNumber', length: 'int') -> 'None': ... # pylint
244244

245245
@info_final
246246
class PartialOrderServiceProfile(Option):
247-
"""Data model for TCP partial order connection profile option."""
247+
"""Data model for TCP partial order connection service profile option."""
248248

249249
#: Start flag.
250250
start: 'bool'
@@ -403,15 +403,16 @@ def __init__(self, kind: 'OptionNumber', length: 'int', subtype: 'MPTCPOption',
403403
class MPTCPCapableFlag(Data):
404404
"""Data model for TCP MPTCP capable option flags."""
405405

406-
#: Checksum require flag.
406+
#: Checksum required flag.
407407
req: 'bool'
408408
#: Extensibility flag.
409409
ext: 'bool'
410410
#: Flag for not establishing new subflows to the source address (``C``).
411411
deny_join: 'bool'
412412
#: Reserved flags (``D`` to ``G``).
413413
reserved: 'int'
414-
#: HMAC-SHA1 flag.
414+
#: HMAC algorithm flag (``H``): HMAC-SHA1 under version 0 (:rfc:`6824`),
415+
#: HMAC-SHA256 under version 1 (:rfc:`8684`).
415416
hsa: 'bool'
416417

417418
if TYPE_CHECKING:

‎pcapkit/protocols/data/transport/udp.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ class UDP(Protocol):
2020
srcport: 'AppType'
2121
#: Destination port.
2222
dstport: 'AppType'
23-
#: Length (header includes).
23+
#: Length, header included.
2424
len: 'int'
2525
#: Checksum.
2626
checksum: 'bytes'

‎pcapkit/protocols/link/vlan.py‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,16 +10,17 @@
1010
modules of their own, since they are reached through different registry indices
1111
-- :class:`~pcapkit.protocols.link.c_tag.C_Tag` for the 802.1Q customer tag
1212
(``0x8100``) and :class:`~pcapkit.protocols.link.s_tag.S_Tag` for the 802.1ad
13-
service tag (``0x88A8``). The tag structure is described as below:
13+
service tag (``0x88A8``). The tag structure is described as below, keyed as for
14+
a customer tag; a service tag's keys start ``s_tag`` instead:
1415
1516
======= ========= ====================== =============================
1617
Octets Bits Name Description
1718
======= ========= ====================== =============================
18-
0 0 ``vlan.tci`` Tag Control Information
19-
0 0 ``vlan.tci.pcp`` Priority Code Point
20-
0 3 ``vlan.tci.dei`` Drop Eligible Indicator
21-
0 4 ``vlan.tci.vid`` VLAN Identifier
22-
2 16 ``vlan.type`` Protocol (Internet Layer)
19+
0 0 ``c_tag.tci`` Tag Control Information
20+
0 0 ``c_tag.tci.pcp`` Priority Code Point
21+
0 3 ``c_tag.tci.dei`` Drop Eligible Indicator
22+
0 4 ``c_tag.tci.vid`` VLAN Identifier
23+
2 16 ``c_tag.type`` Protocol (Internet Layer)
2324
======= ========= ====================== =============================
2425
2526
The two tags carry an **identical** tag control information layout -- the same

‎pcapkit/protocols/schema/transport/tcp.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -164,7 +164,7 @@ class MPTCPCapableFlags(TypedDict):
164164
deny_join: int
165165
#: Reserved flags (``D`` to ``G``).
166166
reserved: int
167-
#: Use of HMAC-SHA1.
167+
#: Use of HMAC-SHA1 under version 0, HMAC-SHA256 under version 1.
168168
hsa: int
169169

170170
class MPTCPSubtypeJoin(TypedDict):
@@ -679,7 +679,8 @@ class _MPTCP(Schema):
679679
#: Subtype and flags.
680680
#:
681681
#: The forward match is anchored at the option's first octet, not after the
682-
#: option header: this schema is what :data:`Option.registry` dispatches to
682+
#: option header: this schema is what :attr:`Option.registry
683+
#: <pcapkit.protocols.schema.schema.EnumSchema.registry>` dispatches to
683684
#: for ``kind == Multipath_TCP`` and, unlike the other option schemas, it
684685
#: does not inherit :class:`Option` and so consumes ``kind`` and ``length``
685686
#: itself. :rfc:`8684` section 3 therefore puts ``kind`` in bits 0-7,

‎pcapkit/protocols/transport/tcp.py‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -304,7 +304,8 @@ class TCP(Transport[Data_TCP, Schema_TCP],
304304
305305
.. versionchanged:: 1.5.0
306306
307-
* :meth:`read` reports the flags of a flagless segment as an empty
307+
* :meth:`read` reports the :attr:`connection` flags of a flagless
308+
segment, and ``info.connection``, as an empty
308309
:class:`~pcapkit.const.tcp.flags.Flags` rather than a plain
309310
:obj:`int` (:issue:`616`).
310311
* A constructed MPTCP option sets its ``subtype`` (:issue:`566`), and
@@ -2893,7 +2894,8 @@ def _make_mptcp_capable(self, subtype: 'Enum_MPTCPOption', opt: 'Optional[Data_M
28932894
flag_deny_join: flag for not establishing new subflows to the
28942895
source address
28952896
flag_reserved: reserved flags (``D`` to ``G``)
2896-
flag_hsa: use of HMAC-SHA1 flag
2897+
flag_hsa: use of HMAC-SHA1 (version 0) or HMAC-SHA256
2898+
(version 1) flag
28972899
skey: option sender's key
28982900
rkey: option receiver's key
28992901
dl_len: data-level length

0 commit comments

Comments
 (0)