diff --git a/docs/source/pcapkit/protocols/application/ngap.rst b/docs/source/pcapkit/protocols/application/ngap.rst index b5243eb096..f22faf03e7 100644 --- a/docs/source/pcapkit/protocols/application/ngap.rst +++ b/docs/source/pcapkit/protocols/application/ngap.rst @@ -25,22 +25,24 @@ Decoding therefore needs the optional |pycrate|_ dependency (``pip install pypcapkit[NGAP]``). :mod:`pcapkit` imports and works without it; an NGAP payload simply degrades to the opaque payload path, exactly as an unregistered PPID would, because -:meth:`SCTP._import_next_layer ` -is wrapped in :func:`~pcapkit.utilities.decorators.beholder` and falls back to +:meth:`~pcapkit.protocols.protocol.Protocol._import_next_layer`, which +:class:`~pcapkit.protocols.transport.sctp.SCTP` inherits, is wrapped in +:func:`~pcapkit.utilities.decorators.beholder` and falls back to :class:`~pcapkit.protocols.misc.raw.Raw`. -Why |pycrate|_ rather than a PER codec of our own -------------------------------------------------- +Decoder Dependency +------------------ -Two things make it the cheaper answer. |pycrate|_ **ships NGAP already -compiled**, at ``pycrate_asn1dir/NGAP.py``, so the 3GPP ASN.1 source does not -have to be vendored here and tracked across releases; and it is **pure -Python**, with no compiled extension to build on any platform. Decoding costs -0.15 ms per PDU, the same order as :mod:`pcapkit`'s own per-packet cost, so -the generic strategy below is not paying for the convenience. +|pycrate|_ is used rather than a PER codec of our own, for two reasons. It +**ships NGAP already compiled**, at ``pycrate_asn1dir/NGAP.py``, so the 3GPP +ASN.1 source does not have to be vendored here and tracked across releases; and +it is **pure Python**, with no compiled extension to build on any platform. +Decoding costs 0.15 ms per PDU, the same order as :mod:`pcapkit`'s own +per-packet cost, so the generic strategy below is not paying for the +convenience. -Generic conversion, not 81 hand-written procedures --------------------------------------------------- +Generic Conversion +------------------ The decoded value tree is mapped into :class:`~pcapkit.corekit.infoclass.Info` objects **structurally**, by ASN.1 shape rather than by procedure: @@ -65,7 +67,7 @@ kind, procedure code, criticality, message type name and the IE list -- are surfaced as first-class fields on :class:`~pcapkit.protocols.data.application.ngap.NGAP` regardless. -Known limitations +Known Limitations ----------------- * **PPID 66 payloads are not decoded.** ``NGAP_over_DTLS_over_SCTP`` wraps the @@ -73,14 +75,14 @@ Known limitations bytes reaching :meth:`NGAP.read` are not an APER encoding. The PPID is registered so that it is *named* rather than anonymous; the payload itself degrades to :class:`~pcapkit.protocols.misc.raw.Raw`. -* **The specification version is |pycrate|_'s, not this package's.** The IE and - procedure enumerations were generated from ``NGAP_Constants`` of |pycrate|_ - 0.8.1 (Release-18-era: 81 procedure codes, 438 protocol IE IDs, highest 443). - A |pycrate|_ that carries a newer NGAP will decode IEs that +* **The specification version is that of the installed decoder, not this + package's.** The IE and procedure enumerations were generated from + ``NGAP_Constants`` of |pycrate|_ 0.8.1 (Release-18-era: 81 procedure codes, + 438 protocol IE IDs, highest 443). A |pycrate|_ that carries a newer NGAP will decode IEs that :class:`~pcapkit.protocols.application.ngap.ProcedureCode` and - :class:`~pcapkit.protocols.application.ngap.ProtocolIE` do not name; both - extend themselves at lookup time rather than failing, so such a value is - reported as ``Unassigned_``. + :class:`~pcapkit.protocols.application.ngap.ProtocolIE` do not name. Such a + value resolves to a non-registering member called ``Unassigned`` rather than + failing or adding a member to either enumeration. * **NGAP over a fragmented SCTP association is not reassembled.** A DATA chunk is decoded on its own, so an ``NGAP-PDU`` split across chunks by SCTP fragmentation fails to decode rather than being reassembled first. diff --git a/docs/source/pcapkit/protocols/application/ospf.rst b/docs/source/pcapkit/protocols/application/ospf.rst index 883c7c37de..b5ab314a76 100644 --- a/docs/source/pcapkit/protocols/application/ospf.rst +++ b/docs/source/pcapkit/protocols/application/ospf.rst @@ -16,19 +16,19 @@ as below: ====== ===== ================== =============================== 0 0 ``ospf.version`` Version Number ------ ----- ------------------ ------------------------------- - 0 0 ``ospf.type`` Type + 1 8 ``ospf.type`` Type ------ ----- ------------------ ------------------------------- - 0 1 ``ospf.len`` Packet Length (header included) + 2 16 ``ospf.len`` Packet Length (header included) ------ ----- ------------------ ------------------------------- - 0 2 ``ospf.router_id`` Router ID + 4 32 ``ospf.router_id`` Router ID ------ ----- ------------------ ------------------------------- - 0 4 ``ospf.area_id`` Area ID + 8 64 ``ospf.area_id`` Area ID ------ ----- ------------------ ------------------------------- - 0 6 ``ospf.chksum`` Checksum + 12 96 ``ospf.chksum`` Checksum ------ ----- ------------------ ------------------------------- - 0 7 ``ospf.autype`` Authentication Type + 14 112 ``ospf.autype`` Authentication Type ------ ----- ------------------ ------------------------------- - 1 8 ``ospf.auth`` Authentication + 16 128 ``ospf.auth`` Authentication ====== ===== ================== =============================== .. raw:: html diff --git a/docs/source/pcapkit/protocols/index.rst b/docs/source/pcapkit/protocols/index.rst index 8941a79903..da2c43b031 100644 --- a/docs/source/pcapkit/protocols/index.rst +++ b/docs/source/pcapkit/protocols/index.rst @@ -5,8 +5,7 @@ Protocol Family .. module:: pcapkit.protocols.data .. module:: pcapkit.protocols.schema -:mod:`pcapkit.protocols` is collection of all protocol families, -with detailed implementation and methods. +:mod:`pcapkit.protocols` is the collection of all protocol families. .. toctree:: :maxdepth: 2 @@ -18,10 +17,9 @@ with detailed implementation and methods. application/index misc/index -All protocol classes are implemented as :class:`~pcapkit.protocols.protocol.ProtocolBase` -subclasses, which are responsible for processing extracted binary packet data -and/or construct protocol packet from given information. Below is a brief -diagram of the class hierarchy of :mod:`pcapkit.protocols`: +All protocol classes are :class:`~pcapkit.protocols.protocol.ProtocolBase` +subclasses, which parse extracted binary packet data and/or construct a packet +from given information. The class hierarchy of :mod:`pcapkit.protocols`: .. mermaid:: @@ -106,7 +104,7 @@ diagram of the class hierarchy of :mod:`pcapkit.protocols`: click C "/pcapkit/protocols/protocol.html#pcapkit.protocols.protocol.Protocol" click D "/ext.html#what-s-in-for-protocols" - click Link "/pcapkit/protocols/link/link.html#pcapkit.protocols.link.Link" + click Link "/pcapkit/protocols/link/link.html#pcapkit.protocols.link.link.Link" click Ethernet "/pcapkit/protocols/link/ethernet.html#pcapkit.protocols.link.ethernet.Ethernet" click L2TP "/pcapkit/protocols/link/l2tp.html#pcapkit.protocols.link.l2tp.L2TP" click L2TPv2 "/pcapkit/protocols/link/l2tpv2.html#pcapkit.protocols.link.l2tpv2.L2TPv2" @@ -119,27 +117,27 @@ diagram of the class hierarchy of :mod:`pcapkit.protocols`: click RARP "/pcapkit/protocols/application/rarp.html#pcapkit.protocols.application.rarp.RARP" click DRARP "/pcapkit/protocols/application/rarp.html#pcapkit.protocols.application.rarp.DRARP" - click Internet "/pcapkit/protocols/internet/internet.html#pcapkit.protocols.internet.Internet" + click Internet "/pcapkit/protocols/internet/internet.html#pcapkit.protocols.internet.internet.Internet" click AH "/pcapkit/protocols/internet/ah.html#pcapkit.protocols.internet.ah.AH" click ESP "/pcapkit/protocols/internet/esp.html#pcapkit.protocols.internet.esp.ESP" click HIP "/pcapkit/protocols/internet/hip.html#pcapkit.protocols.internet.hip.HIP" click HOPOPT "/pcapkit/protocols/internet/hopopt.html#pcapkit.protocols.internet.hopopt.HOPOPT" click IP "/pcapkit/protocols/internet/ip.html#pcapkit.protocols.internet.ip.IP" click IPsec "/pcapkit/protocols/internet/ipsec.html#pcapkit.protocols.internet.ipsec.IPsec" - click IPv4 "/pcapkit/protocols/internet/ipv4.html#pcapkit.protocols.internet.ip.ipv4.IPv4" - click IPv6 "/pcapkit/protocols/internet/ipv6.html#pcapkit.protocols.internet.ip.ipv6.IPv6" + click IPv4 "/pcapkit/protocols/internet/ipv4.html#pcapkit.protocols.internet.ipv4.IPv4" + click IPv6 "/pcapkit/protocols/internet/ipv6.html#pcapkit.protocols.internet.ipv6.IPv6" click IPv6-Frag "/pcapkit/protocols/internet/ipv6_frag.html#pcapkit.protocols.internet.ipv6_frag.IPv6_Frag" click IPv6-Opts "/pcapkit/protocols/internet/ipv6_opts.html#pcapkit.protocols.internet.ipv6_opts.IPv6_Opts" click IPv6-Route "/pcapkit/protocols/internet/ipv6_route.html#pcapkit.protocols.internet.ipv6_route.IPv6_Route" click IPX "/pcapkit/protocols/internet/ipx.html#pcapkit.protocols.internet.ipx.IPX" click MH "/pcapkit/protocols/internet/mh.html#pcapkit.protocols.internet.mh.MH" - click Transport "/pcapkit/protocols/transport/transport.html#pcapkit.protocols.transport.Transport" - click TCP "/pcapkit/protocols/transport/tcp.html#pcapkit.protocols.internet.tcp.TCP" - click UDP "/pcapkit/protocols/transport/udp.html#pcapkit.protocols.internet.udp.UDP" + click Transport "/pcapkit/protocols/transport/transport.html#pcapkit.protocols.transport.transport.Transport" + click TCP "/pcapkit/protocols/transport/tcp.html#pcapkit.protocols.transport.tcp.TCP" + click UDP "/pcapkit/protocols/transport/udp.html#pcapkit.protocols.transport.udp.UDP" click SCTP "/pcapkit/protocols/transport/sctp.html#pcapkit.protocols.transport.sctp.SCTP" - click Application "/pcapkit/protocols/application/application.html#pcapkit.protocols.application.Application" + click Application "/pcapkit/protocols/application/application.html#pcapkit.protocols.application.application.Application" click HTTP "/pcapkit/protocols/application/http.html#pcapkit.protocols.application.http.HTTP" click h1 "/pcapkit/protocols/application/httpv1.html#pcapkit.protocols.application.httpv1.HTTP" click h2 "/pcapkit/protocols/application/httpv2.html#pcapkit.protocols.application.httpv2.HTTP" diff --git a/docs/source/pcapkit/protocols/internet/ah.rst b/docs/source/pcapkit/protocols/internet/ah.rst index 273710a787..12be9b7e3a 100644 --- a/docs/source/pcapkit/protocols/internet/ah.rst +++ b/docs/source/pcapkit/protocols/internet/ah.rst @@ -4,7 +4,7 @@ AH - Authentication Header .. module:: pcapkit.protocols.internet.ah :mod:`pcapkit.protocols.internet.ah` contains -:class:`~pcapkit.protocols.internet.AH` only, +:class:`~pcapkit.protocols.internet.ah.AH` only, which implements extractor for Authentication Header (AH) [*]_, whose structure is described as below: @@ -15,9 +15,9 @@ Octets Bits Name Description 0 0 ``ah.next`` Next Header 1 8 ``ah.length`` Payload Length 2 16 Reserved (must be zero) - 4 32 ``sah.spi`` Security Parameters Index (SPI) - 8 64 ``sah.seq`` Sequence Number Field - 12 96 ``sah.icv`` Integrity Check Value (ICV) + 4 32 ``ah.spi`` Security Parameters Index (SPI) + 8 64 ``ah.seq`` Sequence Number Field + 12 96 ``ah.icv`` Integrity Check Value (ICV) ======= ========= ======================= =================================== .. autoclass:: pcapkit.protocols.internet.ah.AH diff --git a/docs/source/pcapkit/protocols/internet/esp.rst b/docs/source/pcapkit/protocols/internet/esp.rst index bf5cc32225..b2c1ae4a29 100644 --- a/docs/source/pcapkit/protocols/internet/esp.rst +++ b/docs/source/pcapkit/protocols/internet/esp.rst @@ -120,12 +120,8 @@ registered**: 3DES, AES-CTR, the AES-CCM and Camellia families, ChaCha20-Poly1305, the implicit IV variants of :rfc:`8750`, the :rfc:`9227` MGM suites, and the transforms long since deprecated. -The enumerations themselves are generated into :mod:`pcapkit.const.esp` and -re-exported here for convenience: -:class:`Cipher ` is -:class:`pcapkit.const.esp.cipher.Cipher` and :class:`Integrity -` is -:class:`pcapkit.const.esp.integrity.Integrity`. +Both enumerations are generated into :mod:`pcapkit.const.esp` and re-exported +from this module. Both enumerations additionally carry each transform's prefix-stripped spelling as an alias, since that is how ESP and :rfc:`8221` name the algorithms, so diff --git a/docs/source/pcapkit/protocols/internet/ipv4.rst b/docs/source/pcapkit/protocols/internet/ipv4.rst index 6eb79859f3..b27245d710 100644 --- a/docs/source/pcapkit/protocols/internet/ipv4.rst +++ b/docs/source/pcapkit/protocols/internet/ipv4.rst @@ -12,25 +12,25 @@ as below: ======= ========= ====================== ============================================= Octets Bits Name Description ======= ========= ====================== ============================================= - 0 0 ``ip.version`` Version (``4``) - 0 4 ``ip.hdr_len`` Internal Header Length (IHL) - 1 8 ``ip.tos.pre`` Precedence - 1 11 ``ip.tos.del`` Delay - 1 12 ``ip.tos.thr`` Throughput - 1 13 ``ip.tos.rel`` Reliability - 1 14 ``ip.tos.ecn`` Explicit Congestion Notification (ECN) - 2 16 ``ip.len`` Total Length - 4 32 ``ip.id`` Identification + 0 0 ``ipv4.version`` Version (``4``) + 0 4 ``ipv4.hdr_len`` Internet Header Length (IHL) + 1 8 ``ipv4.tos.pre`` Precedence + 1 11 ``ipv4.tos.del`` Delay + 1 12 ``ipv4.tos.thr`` Throughput + 1 13 ``ipv4.tos.rel`` Reliability + 1 14 ``ipv4.tos.ecn`` Explicit Congestion Notification (ECN) + 2 16 ``ipv4.len`` Total Length + 4 32 ``ipv4.id`` Identification 6 48 Reserved Bit (must be ``\x00``) - 6 49 ``ip.flags.df`` Don't Fragment (DF) - 6 50 ``ip.flags.mf`` More Fragments (MF) - 6 51 ``ip.offset`` Fragment Offset - 8 64 ``ip.ttl`` Time To Live (TTL) - 9 72 ``ip.protocol`` Protocol (Transport Layer) - 10 80 ``ip.checksum`` Header Checksum - 12 96 ``ip.src`` Source IP Address - 16 128 ``ip.dst`` Destination IP Address - 20 160 ``ip.options`` IP Options (if IHL > ``5``) + 6 49 ``ipv4.flags.df`` Don't Fragment (DF) + 6 50 ``ipv4.flags.mf`` More Fragments (MF) + 6 51 ``ipv4.offset`` Fragment Offset + 8 64 ``ipv4.ttl`` Time To Live (TTL) + 9 72 ``ipv4.protocol`` Protocol (Transport Layer) + 10 80 ``ipv4.checksum`` Header Checksum + 12 96 ``ipv4.src`` Source IP Address + 16 128 ``ipv4.dst`` Destination IP Address + 20 160 ``ipv4.options`` IP Options (if IHL > ``5``) ======= ========= ====================== ============================================= .. autoclass:: pcapkit.protocols.internet.ipv4.IPv4 diff --git a/docs/source/pcapkit/protocols/internet/ipv6.rst b/docs/source/pcapkit/protocols/internet/ipv6.rst index b12e499311..ce7ee42316 100644 --- a/docs/source/pcapkit/protocols/internet/ipv6.rst +++ b/docs/source/pcapkit/protocols/internet/ipv6.rst @@ -12,14 +12,14 @@ as below: ======= ========= ===================== ======================================= Octets Bits Name Description ======= ========= ===================== ======================================= - 0 0 ``ip.version`` Version (``6``) - 0 4 ``ip.class`` Traffic Class - 1 12 ``ip.label`` Flow Label - 4 32 ``ip.payload`` Payload Length (header excludes) - 6 48 ``ip.next`` Next Header - 7 56 ``ip.limit`` Hop Limit - 8 64 ``ip.src`` Source Address - 24 192 ``ip.dst`` Destination Address + 0 0 ``ipv6.version`` Version (``6``) + 0 4 ``ipv6.class`` Traffic Class + 1 12 ``ipv6.label`` Flow Label + 4 32 ``ipv6.payload`` Payload Length (header excludes) + 6 48 ``ipv6.next`` Next Header + 7 56 ``ipv6.limit`` Hop Limit + 8 64 ``ipv6.src`` Source Address + 24 192 ``ipv6.dst`` Destination Address ======= ========= ===================== ======================================= .. autoclass:: pcapkit.protocols.internet.ipv6.IPv6 diff --git a/docs/source/pcapkit/protocols/internet/ipv6_ext.rst b/docs/source/pcapkit/protocols/internet/ipv6_ext.rst index 5da6cc37c3..d722b6f95b 100644 --- a/docs/source/pcapkit/protocols/internet/ipv6_ext.rst +++ b/docs/source/pcapkit/protocols/internet/ipv6_ext.rst @@ -5,18 +5,17 @@ IPv6_Ext - IPv6 Extension Header :mod:`pcapkit.protocols.internet.ipv6_ext` contains :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` -only, which serves two roles at once: it is the -shared **base class** of all eight IPv6 extension headers this package -implements -- supplying them the ``extension``-mode contract, i.e. the -guards that make :attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.payload`, +only, which serves two roles at once. It is the shared **base class** of all +eight IPv6 extension headers this package implements, supplying the +``extension``-mode contract: the guards that make +:attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.payload`, :attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.protocol` and :attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.protochain` -unavailable on a header parsed as part of an IPv6 chain -- and it -implements a **generic** extractor for IPv6 extension -headers [*]_, standing in for one whenever the header's own dedicated -parser is unavailable or has failed. :rfc:`6564#section-4` guarantees, -with an RFC 2119 **MUST**, that any IPv6 extension header defined -since April 2012 carries the same first two octets: +unavailable on a header parsed as part of an IPv6 chain. It also implements a +**generic** extractor for IPv6 extension headers [*]_, standing in whenever a +header's own dedicated parser is unavailable or has failed. :rfc:`6564#section-4` +requires, with an RFC 2119 **MUST**, that any IPv6 extension header defined since +April 2012 carry the same first two octets: ======= ========= ===================== ===================================== Octets Bits Name Description @@ -27,12 +26,12 @@ Octets Bits Name Description 2 16 ``payload`` Header-specific content ======= ========= ===================== ===================================== -so those two octets are parseable without knowing anything else about -the header. See the module docstring below for the closed exception -table (``IPv6-Frag`` and ``AH`` each use their own length rule; ``ESP`` -has a dedicated parser whose own info reports no next header rather than -lacking one, and ``253`` and ``254`` have no dedicated parser at all -- -none of the three ever reaches this class), the two ways this class is +so those two octets are parseable without knowing anything else about the +header. The module docstring in :file:`pcapkit/protocols/internet/ipv6_ext.py` +holds the closed exception table (``IPv6-Frag`` and ``AH`` each use their own +length rule; ``ESP`` has a dedicated parser whose own info reports no next header +rather than lacking one, and ``253`` and ``254`` have no dedicated parser at all, +so none of the three ever reaches this class), the two ways this class is dispatched to, and why an overrun stops the walk instead of clipping it. .. autoclass:: pcapkit.protocols.internet.ipv6_ext.IPv6_Ext diff --git a/docs/source/pcapkit/protocols/internet/ipv6_opts.rst b/docs/source/pcapkit/protocols/internet/ipv6_opts.rst index 6ff3f1dcf2..10351c4df5 100644 --- a/docs/source/pcapkit/protocols/internet/ipv6_opts.rst +++ b/docs/source/pcapkit/protocols/internet/ipv6_opts.rst @@ -12,9 +12,9 @@ as below: ======= ========= =================== ================================= Octets Bits Name Description ======= ========= =================== ================================= - 0 0 ``opt.next`` Next Header - 1 8 ``opt.length`` Header Extensive Length - 2 16 ``opt.options`` Options + 0 0 ``opts.next`` Next Header + 1 8 ``opts.length`` Header Extensive Length + 2 16 ``opts.options`` Options ======= ========= =================== ================================= .. autoclass:: pcapkit.protocols.internet.ipv6_opts.IPv6_Opts diff --git a/docs/source/pcapkit/protocols/link/c_tag.rst b/docs/source/pcapkit/protocols/link/c_tag.rst index 6293c61b70..f3beaa7eab 100644 --- a/docs/source/pcapkit/protocols/link/c_tag.rst +++ b/docs/source/pcapkit/protocols/link/c_tag.rst @@ -5,7 +5,7 @@ C_Tag - 802.1Q Customer VLAN Tag Type :mod:`pcapkit.protocols.link.c_tag` contains :class:`~pcapkit.protocols.link.c_tag.C_Tag` only, which implements extractor for -the 802.1Q Customer VLAN Tag Type (C-Tag, formerly the Q-Tag) [*]_, EtherType +the 802.1Q Customer VLAN Tag Type (C-Tag) [*]_, EtherType ``0x8100``. Its structure, and all of its parsing and construction, come from @@ -14,13 +14,10 @@ identity -- :attr:`~pcapkit.protocols.link.c_tag.C_Tag.name`, :attr:`~pcapkit.protocols.link.c_tag.C_Tag.alias`, :attr:`~pcapkit.protocols.link.c_tag.C_Tag.info_name` -- and its registry index. -It lives in a module of its own rather than beside -:class:`~pcapkit.protocols.link.s_tag.S_Tag` because the two are reached through -*different* registry indices, ``0x8100`` against ``0x88A8``, which is the -project's rule for when protocols share a module. Contrast -:class:`~pcapkit.protocols.link.arp.InARP`, which shares -:mod:`~pcapkit.protocols.link.arp` with :class:`~pcapkit.protocols.link.arp.ARP` -precisely because it inherits its index. +It has a module of its own, apart from +:class:`~pcapkit.protocols.link.s_tag.S_Tag`, because the two are reached through +*different* registry indices, ``0x8100`` against ``0x88A8``; see +:mod:`pcapkit.protocols.link.vlan` for the rule. .. autoclass:: pcapkit.protocols.link.c_tag.C_Tag :no-members: diff --git a/docs/source/pcapkit/protocols/link/ethernet.rst b/docs/source/pcapkit/protocols/link/ethernet.rst index ecb9e51b18..fa67920c3d 100644 --- a/docs/source/pcapkit/protocols/link/ethernet.rst +++ b/docs/source/pcapkit/protocols/link/ethernet.rst @@ -11,15 +11,15 @@ below: .. table:: - ====== ===== ============ ========================= - Octets Bits Name Description - ====== ===== ============ ========================= - 0 0 ``eth.dst`` Destination MAC Address - ------ ----- ------------ ------------------------- - 1 8 ``eth.src`` Source MAC Address - ------ ----- ------------ ------------------------- - 2 16 ``eth.type`` Protocol (Internet Layer) - ====== ===== ============ ========================= + ====== ===== ================= ========================= + Octets Bits Name Description + ====== ===== ================= ========================= + 0 0 ``ethernet.dst`` Destination MAC Address + ------ ----- ----------------- ------------------------- + 6 48 ``ethernet.src`` Source MAC Address + ------ ----- ----------------- ------------------------- + 12 96 ``ethernet.type`` Protocol (Internet Layer) + ====== ===== ================= ========================= .. autoclass:: pcapkit.protocols.link.ethernet.Ethernet :no-members: diff --git a/docs/source/pcapkit/protocols/link/l2tp.rst b/docs/source/pcapkit/protocols/link/l2tp.rst index 554074ec89..05d5ec71ae 100644 --- a/docs/source/pcapkit/protocols/link/l2tp.rst +++ b/docs/source/pcapkit/protocols/link/l2tp.rst @@ -20,47 +20,45 @@ of their own: Only L2TPv2 is implemented. -The base deliberately carries **no header parsing at all**, in the way -:class:`~pcapkit.protocols.internet.ip.IP` carries none for its family. That is -not tidiness: the versions genuinely do not share a header. All that is common -across them is the *first 16-bit word carrying a version nibble at bits 12-15*; -everything after it differs, so a base that parsed further would be assuming one -version's layout for all of them. - -What the family still wants ---------------------------- - -**L2TPv3** [:rfc:`3931`] has a different session header and a different control -message header from v2, and is reachable two ways -- over UDP port 1701 like v2, -and directly over IP as **protocol number 115**. That second route is why +The base deliberately parses no header, as +:class:`~pcapkit.protocols.internet.ip.IP` does for its family, because the +versions do not share one. Only the first 16-bit word, with a version nibble at +bits 12-15, is common to all of them; a base that parsed further would assume one +version's layout for every version. + +Versions Not Implemented +------------------------ + +**L2TPv3** [:rfc:`3931`] has a different session header and control message +header from v2, and is reachable two ways: over UDP port 1701 like v2, and +directly over IP as **protocol number 115**. That second route is why :attr:`Internet.__proto__ ` -leaves 115 unbound today: the binding waits on an ``L2TPv3`` class, not on a -different framing decision. It also means v3 is the first member of this family -to have a real :meth:`~pcapkit.protocols.protocol.Protocol.__index__`, and so -the first that must have a module of its own under the project's one-module-per-index -rule. +leaves 115 unbound: the binding waits on an ``L2TPv3`` class. It would also be +the first member of this family with a real +:meth:`~pcapkit.protocols.protocol.Protocol.__index__`, and so the first that +needs a module of its own under the project's one-module-per-index rule. **L2F** [:rfc:`2341`] is reached when the version nibble reads ``1``. It is *not* an earlier version of L2TP: :rfc:`2661` ยง3.1 requires ``Ver`` to be 2 and reserves the value 1 "to permit detection of L2F packets should they arrive intermixed with -L2TP packets". L2F is a separate protocol with its own header. It is therefore to -be implemented as ``L2F``, the canonical name, carrying ``L2TPv1`` only as an -alias in its :meth:`~pcapkit.protocols.protocol.Protocol.id` -- the same -relationship HTTP/3 has to QUIC. c.f. -:meth:`HTTPv1.id ` for how a -version-flavoured alias is spelled: canonical name first, alias second, since -callers take element zero as canonical. - -Selecting a version -------------------- - -Nothing dispatches on the version nibble yet, because only one version exists. -When a second lands, the mechanism it wants already has a precedent in +L2TP packets". L2F is a separate protocol with its own header, so it is to be +implemented as ``L2F``, the canonical name, with ``L2TPv1`` only as an alias in its +:meth:`~pcapkit.protocols.protocol.Protocol.id` -- the relationship HTTP/3 has to +QUIC. c.f. :meth:`HTTPv1.id ` for +how a version-flavoured alias is spelled: canonical name first, alias second, +since callers take element zero as canonical. + +Version Dispatch +---------------- + +Nothing dispatches on the version nibble, because only one version exists. A +second would follow the precedent of :class:`~pcapkit.protocols.application.http.HTTP`, which reads a version and delegates to a per-version class. L2TP is the easier case: :meth:`HTTP._guess_version ` -has to *trial-parse* each candidate because the wire format carries no version -field, whereas L2TP states its version explicitly in those four bits. So a +has to *infer* the version -- recognising the HTTP/2 preface or an HTTP/1 start +line, else trial-parsing each candidate -- because HTTP's wire format carries no +version field, whereas L2TP states its version explicitly in those four bits. A deterministic switch on ``Ver`` is enough, and no new registry is needed. .. autoclass:: pcapkit.protocols.link.l2tp.L2TP diff --git a/docs/source/pcapkit/protocols/link/l2tpv2.rst b/docs/source/pcapkit/protocols/link/l2tpv2.rst index e0c3e6d15c..94f7d380a3 100644 --- a/docs/source/pcapkit/protocols/link/l2tpv2.rst +++ b/docs/source/pcapkit/protocols/link/l2tpv2.rst @@ -57,10 +57,10 @@ reading ``2``. It is dispatched from whichever version was on the wire. The version is reported by :attr:`~pcapkit.protocols.link.l2tpv2.L2TPv2.alias` instead. - IANA protocol number 115 (``L2TP``) is deliberately left unbound. It - references :rfc:`3931`, i.e. **L2TPv3**, whose session and control message - headers are a different shape -- so the binding waits on an ``L2TPv3`` class - rather than on this one. See :mod:`pcapkit.protocols.link.l2tp`. + IANA protocol number 115 (``L2TP``) is deliberately left unbound: it + references :rfc:`3931`, i.e. **L2TPv3**, whose headers have a different shape, + so the binding waits on an ``L2TPv3`` class rather than this one. See + :mod:`pcapkit.protocols.link.l2tp`. .. autoclass:: pcapkit.protocols.link.l2tpv2.L2TPv2 :no-members: diff --git a/docs/source/pcapkit/protocols/link/s_tag.rst b/docs/source/pcapkit/protocols/link/s_tag.rst index 97b29e5ce6..a3d2df4fa4 100644 --- a/docs/source/pcapkit/protocols/link/s_tag.rst +++ b/docs/source/pcapkit/protocols/link/s_tag.rst @@ -13,16 +13,15 @@ identity -- :attr:`~pcapkit.protocols.link.s_tag.S_Tag.name`, :attr:`~pcapkit.protocols.link.s_tag.S_Tag.alias`, :attr:`~pcapkit.protocols.link.s_tag.S_Tag.info_name` -- and its registry index. -It lives in a module of its own rather than beside -:class:`~pcapkit.protocols.link.c_tag.C_Tag` because the two are reached through -*different* registry indices, ``0x88A8`` against ``0x8100``, which is the -project's rule for when protocols share a module. +It has a module of its own, apart from +:class:`~pcapkit.protocols.link.c_tag.C_Tag`, because the two are reached through +*different* registry indices, ``0x88A8`` against ``0x8100``; see +:mod:`pcapkit.protocols.link.vlan` for the rule. .. note:: - 802.1ad was incorporated into IEEE 802.1Q-2011, so the service tag is - specified by 802.1Q today. The ``802.1ad`` name is kept because it is what the - provider-bridging tag is universally called. + 802.1ad is part of IEEE 802.1Q-2011. The ``802.1ad`` name is kept because it + is what the provider-bridging tag is universally called. .. autoclass:: pcapkit.protocols.link.s_tag.S_Tag :no-members: diff --git a/docs/source/pcapkit/protocols/link/vlan.rst b/docs/source/pcapkit/protocols/link/vlan.rst index 1c2ededdeb..9de25a8555 100644 --- a/docs/source/pcapkit/protocols/link/vlan.rst +++ b/docs/source/pcapkit/protocols/link/vlan.rst @@ -23,24 +23,23 @@ The tag structure is described as below: ======= ========= ====================== ============================= Octets Bits Name Description ======= ========= ====================== ============================= - 1 0 ``vlan.tci`` Tag Control Information - 1 0 ``vlan.tci.pcp`` Priority Code Point - 1 3 ``vlan.tci.dei`` Drop Eligible Indicator - 1 4 ``vlan.tci.vid`` VLAN Identifier - 3 24 ``vlan.type`` Protocol (Internet Layer) + 0 0 ``vlan.tci`` Tag Control Information + 0 0 ``vlan.tci.pcp`` Priority Code Point + 0 3 ``vlan.tci.dei`` Drop Eligible Indicator + 0 4 ``vlan.tci.vid`` VLAN Identifier + 2 16 ``vlan.type`` Protocol (Internet Layer) ======= ========= ====================== ============================= -The two tags carry an identical tag control information layout and are told apart -solely by the tag protocol identifier (TPID) that selected them -- ``0x8100`` for -the customer tag against ``0x88A8`` for the service tag. That TPID is not part of -either tag: it is the EtherType field of whatever encapsulates the tag, so both -classes read the same four octets and share every byte of parsing and -construction code, which is what this base holds. +The two tags carry an identical tag control information layout and differ only +in the tag protocol identifier (TPID) that selected them -- ``0x8100`` for the +customer tag, ``0x88A8`` for the service tag. The TPID is not part of either tag: +it is the EtherType field of whatever encapsulates the tag. Both classes read the +same four octets and share all parsing and construction code, which this base +holds. -They are nonetheless distinct classes rather than one class bound at two -EtherTypes, because 802.1ad *stacks* them. In a Q-in-Q frame the service tag's -own next-EtherType is ``0x8100``, which selects a customer tag in turn, so both -tags appear in one frame: +They are still distinct classes rather than one class bound at two EtherTypes, +because 802.1ad *stacks* them. In a Q-in-Q frame the service tag's own +next-EtherType is ``0x8100``, which selects a customer tag in turn: .. code-block:: text @@ -52,18 +51,17 @@ tags appear in one frame: :attr:`~pcapkit.protocols.protocol.Protocol.info_name` -- ``s_tag`` against ``c_tag`` -- is what keeps the two apart in the parsed -:class:`~pcapkit.corekit.infoclass.Info`. A single class bound at both EtherTypes -would nest one ``c_tag`` inside another, leaving nothing in the output to say -which of the two was the service tag. +:class:`~pcapkit.corekit.infoclass.Info`. One class bound at both EtherTypes +would nest a ``c_tag`` inside a ``c_tag``, leaving nothing to say which was the +service tag. -Two distinct EtherTypes also means two distinct -:meth:`~pcapkit.protocols.protocol.Protocol.__index__` values, which is the -project's rule for when protocols get separate modules: siblings that *share* an +Two EtherTypes also mean two :meth:`~pcapkit.protocols.protocol.Protocol.__index__` +values, which is the project's rule for separate modules: siblings that *share* an index may share a module, as :class:`~pcapkit.protocols.link.arp.InARP` shares :mod:`~pcapkit.protocols.link.arp` and :class:`~pcapkit.protocols.application.rarp.DRARP` shares -:mod:`~pcapkit.protocols.application.rarp`. This base declares no index of its own -- -it is abstract and nothing dispatches to it -- so its ``__index__`` raises. +:mod:`~pcapkit.protocols.application.rarp`. This base is abstract, nothing +dispatches to it, and it declares no index, so its ``__index__`` raises. .. autoclass:: pcapkit.protocols.link.vlan.VLAN :no-members: diff --git a/docs/source/pcapkit/protocols/misc/pcap.rst b/docs/source/pcapkit/protocols/misc/pcap.rst index ace2d5a381..362132d662 100644 --- a/docs/source/pcapkit/protocols/misc/pcap.rst +++ b/docs/source/pcapkit/protocols/misc/pcap.rst @@ -17,7 +17,7 @@ Global Header .. module:: pcapkit.protocols.misc.pcap.header :mod:`pcapkit.protocols.misc.pcap.header` contains -:class:`~pcapkit.protocols.misc.pcap.Header` only, +:class:`~pcapkit.protocols.misc.pcap.header.Header` only, which implements extractor for global headers [*]_ of PCAP, whose structure is described as below: diff --git a/docs/source/pcapkit/protocols/misc/pcapng.rst b/docs/source/pcapkit/protocols/misc/pcapng.rst index 71de1768ff..d147d744f8 100644 --- a/docs/source/pcapkit/protocols/misc/pcapng.rst +++ b/docs/source/pcapkit/protocols/misc/pcapng.rst @@ -197,12 +197,10 @@ Auxiliary Data :undoc-members: :show-inheritance: -:class:`TLSKeyLabel ` lives in -:mod:`pcapkit.const.pcapng.tls_key_label`, generated the same way as its -:mod:`pcapkit.const.pcapng` siblings since :rfc:`9850#section-4.2` makes it an -IANA registry rather than a hand-picked helper enum. This module still -re-exports it under its own name, so -``from pcapkit.protocols.misc.pcapng import TLSKeyLabel`` keeps working. +:class:`TLSKeyLabel ` is defined +in :mod:`pcapkit.const.pcapng.tls_key_label`, generated like its +:mod:`pcapkit.const.pcapng` siblings because :rfc:`9850#section-4.2` makes it an +IANA registry. This module re-exports it as ``TLSKeyLabel``. .. autoclass:: pcapkit.protocols.misc.pcapng.WireGuardKeyLabel :members: diff --git a/docs/source/pcapkit/protocols/protocol.rst b/docs/source/pcapkit/protocols/protocol.rst index 2fcb6d765a..c7cc7a9e3e 100644 --- a/docs/source/pcapkit/protocols/protocol.rst +++ b/docs/source/pcapkit/protocols/protocol.rst @@ -6,9 +6,8 @@ Root Protocol .. currentmodule:: pcapkit.protocols.protocol :mod:`pcapkit.protocols.protocol` contains -:class:`~pcapkit.protocols.protocol.Protocol` only, which is -an abstract base class for all protocol family, with pre-defined -utility arguments and methods of specified protocols. +:class:`~pcapkit.protocols.protocol.Protocol` only, the abstract base class for +all protocol families, with pre-defined utility arguments and methods. .. autoclass:: pcapkit.protocols.protocol.Protocol :no-members: