feat(link): implement LINUX_SLL and LINUX_SLL2 dissectors

docs/source/contributing/pep.rst

@@ -40,7 +40,7 @@ step-by-step guide for adding a protocol, and is worth reading before starting
 one. Grouped by each TCP/IP layer and ordered by protocol name alphabetically,
 the ones outstanding are,
 
-* Link Layer: DSL, EAPOL, FDDI, ISDN, LINUX_SLL, LINUX_SLL2, NDP, PPP
+* Link Layer: DSL, EAPOL, FDDI, ISDN, NDP, PPP
 * Internet Layer: ECN, ICMP, ICMPv6, IGMP, Shim6
 * Transport Layer: DCCP, RSVP
 * Application Layer: BGP, DHCP, DHCPv6, DNS, IMAP, LDAP, MQTT, NNTP,
@@ -49,10 +49,10 @@ the ones outstanding are,
 
 Several of these come in pairs that want a shared abstract base rather than two
 independent implementations, in the way
-:class:`~pcapkit.protocols.internet.ip.IP` already covers its family: ICMP with
-ICMPv6, and ``LINUX_SLL`` with ``LINUX_SLL2``. **Done** for TLS/SSL with
-DTLS: :class:`~pcapkit.protocols.application.ssl.SSL` is the shared
-record-layer base of :class:`~pcapkit.protocols.application.tls.TLS` and
+:class:`~pcapkit.protocols.internet.ip.IP` already covers its family: ICMP
+with ICMPv6, and TLS/SSL with DTLS. **Done** for TLS/SSL with DTLS:
+:class:`~pcapkit.protocols.application.ssl.SSL` is the shared record-layer base
+of :class:`~pcapkit.protocols.application.tls.TLS` and
 :class:`~pcapkit.protocols.application.dtls.DTLS` -- see the `DTLS`_ section
 below.
 :class:`~pcapkit.protocols.link.vlan.VLAN` is the closer precedent for a pair
@@ -66,8 +66,7 @@ whose *layout* is identical -- it holds the whole of the tag, and
    ``NotImplemented`` folder. **Those files are not a roadmap.** They are
    scratch reminders, so a stub's presence does not mean a protocol is planned or
    claimed, and its absence does not mean the protocol is unwanted:
-   ``LINUX_SLL``, ``LINUX_SLL2`` and ``QUIC`` have no stub and are on the
-   list above,
+   ``QUIC`` has no stub and is on the list above,
    while **NGAP** has none either and is implemented. Take this page as the
    record and ignore the folder.
 
@@ -363,9 +362,7 @@ Follow-ups to the bindings above:
   instead of guessing, since a guess path is wrong on non-HTTP input.
 
 Beyond those, the gaps most likely to be met in a real capture are ICMP (1),
-ICMPv6 (58) and IGMP (2) on the internet layer, each of which has a stub;
-and ``LINUX_SLL`` and ``LINUX_SLL2`` at the link layer, which every
-``tcpdump -i any`` capture uses and which have no stub.
+ICMPv6 (58) and IGMP (2) on the internet layer, each of which has a stub.
 
 PCAPNG Support
 --------------
@@ -1084,30 +1081,35 @@ post-wave-1 consistency sweep described under `Release Plan — 1.5.0 in Two
 Steps`_ above.
 
 **Wave 2 — the protocol pairs that want a shared abstract base**, per `More
-Protocols, More!!!`_ above: **ICMP with ICMPv6**, **TLS/SSL with DTLS**, and
-``LINUX_SLL`` with ``LINUX_SLL2``, plus **IGMP** and **DCCP** on their own. These are
-grouped because the shared-base question is the design work and doing either half of
-a pair alone would answer it twice. ``LINUX_SLL`` matters out of proportion to its
-size: every ``tcpdump -i any`` capture uses it, and neither variant has even a
-stub. **DCCP** is the transport-layer implementation, tracked by :issue:`2489`, and
+Protocols, More!!!`_ above: **ICMP with ICMPv6** and **TLS/SSL with DTLS**,
+plus **IGMP** and **DCCP** on their own. These are grouped because the shared-base
+question is the design work and doing either half of a pair alone would answer it
+twice. **DCCP** is the transport-layer implementation, tracked by :issue:`2489`, and
 blocked on :issue:`2479` for its pseudo-header checksum.
 
 **Done within wave 2 — TLS/SSL with DTLS.** The `DTLS`_ section above lists
 what is decoded (the shared :class:`~pcapkit.protocols.application.ssl.SSL`
 base, TLS, DTLS, and handshake message framing) and what is not (DTLS
 handshake-fragment reassembly, :issue:`2440`).
 
-**Done ahead of wave 2 — handlers for the** ``DLT_NULL`` **and** ``DLT_RAW``
-**link types.** Both are genuine DLTs that a capture can legitimately be rooted
-in — ``DLT_NULL`` (0) is BSD's loopback encapsulation, ``DLT_RAW`` (101) an IP
-packet with no link header at all.
+**Done ahead of wave 2 — handlers for the** ``DLT_NULL``, ``DLT_RAW``,
+``DLT_LINUX_SLL`` **and** ``DLT_LINUX_SLL2`` **link types.** Each is a
+genuine DLT that a capture can legitimately be rooted in — ``DLT_NULL`` (0)
+is BSD's loopback encapsulation, ``DLT_RAW`` (101) an IP packet with no link
+header at all, and ``DLT_LINUX_SLL`` (113) with ``DLT_LINUX_SLL2`` (276) the
+Linux "cooked" capture header every ``tcpdump -i any`` capture uses.
 :class:`~pcapkit.protocols.link.loopback.Loopback` dissects ``DLT_NULL`` and
-``DLT_LOOP`` (:issue:`1574`), and the frame dispatcher reads ``DLT_RAW`` as IPv4
-or IPv6 by its version nibble (:issue:`1502`), so of the link types this
-section names only ``LINUX_SLL`` and ``LINUX_SLL2`` remain enumerated but
-unparsed. Neither ``NULL`` nor ``RAW`` is an honest stand-in for "unknown link
-type", which is why the toolkit raises for an unresolvable link-layer name
-instead of defaulting to :attr:`LinkType.NULL <pcapkit.const.reg.linktype.LinkType.NULL>`.
+``DLT_LOOP`` (:issue:`1574`), the frame dispatcher reads ``DLT_RAW`` as IPv4
+or IPv6 by its version nibble (:issue:`1502`), and
+:class:`~pcapkit.protocols.link.linux_sll1.LinuxSLL1` with
+:class:`~pcapkit.protocols.link.linux_sll2.LinuxSLL2` dissect the Linux
+cooked-capture variants (:issue:`2438`). The ``arphrd_type`` values
+neither header treats as carrying an EtherType (``NETLINK``, ``IPGRE``, ``IP6GRE``,
+``IEEE80211_RADIOTAP``, ``FRAD``) have no dissector of their own, tracked
+as :issue:`2460`. Neither ``NULL`` nor ``RAW`` is an honest stand-in for "unknown
+link type", which is why the toolkit raises for an unresolvable link-layer
+name instead of defaulting to :attr:`LinkType.NULL
+<pcapkit.const.reg.linktype.LinkType.NULL>`.
 
 **Wave 3 — the remaining protocols** from the same list, taken three or four at a
 time. QUIC, DSL, FDDI and ISDN come last: QUIC because it is really HTTP/3 over a

docs/source/ext.rst

@@ -30,6 +30,12 @@ The protocol classes :mod:`pcapkit` ships:
 +                                                                  +                +-----------------------+-------------------------------------------------------------+
 |                                                                  | L2TP Family    | :class:`pcapkit.protocols.link.l2tpv2.L2TPv2`                                       |
 +                                                                  +----------------+-----------------------+-------------------------------------------------------------+
+|                                                                  |                | :class:`pcapkit.protocols.link.linux_sll.LinuxSLL`                                  |
++                                                                  +                +-----------------------+-------------------------------------------------------------+
+|                                                                  | LINUX_SLL      | :class:`pcapkit.protocols.link.linux_sll1.LinuxSLL1`                                |
++                                                                  + Family         +-----------------------+-------------------------------------------------------------+
+|                                                                  |                | :class:`pcapkit.protocols.link.linux_sll2.LinuxSLL2`                                |
++                                                                  +----------------+-----------------------+-------------------------------------------------------------+
 |                                                                  | :class:`pcapkit.protocols.link.loopback.Loopback`                                                    |
 +                                                                  +----------------+-----------------------+-------------------------------------------------------------+
 |                                                                  |                | :class:`pcapkit.protocols.link.vlan.VLAN`                                           |

docs/source/pcapkit/protocols/index.rst

@@ -63,7 +63,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
        end
 
        subgraph link [Link Layer]
-           Link --> Ethernet & L2TP & Loopback & VLAN & ARP
+           Link --> Ethernet & L2TP & LinuxSLL & Loopback & VLAN & ARP
 
            subgraph arp [ARP Family]
                ARP --> InARP
@@ -76,6 +76,10 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
            subgraph l2tp [L2TP Family]
                L2TP --> L2TPv2
            end
+
+           subgraph sll [LinuxSLL Family]
+               LinuxSLL --> LinuxSLL1 & LinuxSLL2
+           end
        end
 
        subgraph internet [Internet Layer]
@@ -117,6 +121,9 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
        click Ethernet "link/ethernet.html#pcapkit.protocols.link.ethernet.Ethernet"
        click L2TP "link/l2tp.html#pcapkit.protocols.link.l2tp.L2TP"
        click L2TPv2 "link/l2tpv2.html#pcapkit.protocols.link.l2tpv2.L2TPv2"
+       click LinuxSLL "link/linux_sll.html#pcapkit.protocols.link.linux_sll.LinuxSLL"
+       click LinuxSLL1 "link/linux_sll1.html#pcapkit.protocols.link.linux_sll1.LinuxSLL1"
+       click LinuxSLL2 "link/linux_sll2.html#pcapkit.protocols.link.linux_sll2.LinuxSLL2"
        click Loopback "link/loopback.html#pcapkit.protocols.link.loopback.Loopback"
        click VLAN "link/vlan.html#pcapkit.protocols.link.vlan.VLAN"
        click C_Tag "link/c_tag.html#pcapkit.protocols.link.c_tag.C_Tag"

docs/source/pcapkit/protocols/link/index.rst

@@ -26,6 +26,9 @@ link layer, with detailed implementation and methods.
    arp
    l2tp
    l2tpv2
+   linux_sll
+   linux_sll1
+   linux_sll2
    loopback
    vlan
    c_tag

docs/source/pcapkit/protocols/link/linux_sll.rst

@@ -0,0 +1,64 @@
+LinuxSLL - Linux "Cooked" Capture Encapsulation Family
+======================================================
+
+.. module:: pcapkit.protocols.link.linux_sll
+
+:mod:`pcapkit.protocols.link.linux_sll` contains
+:class:`~pcapkit.protocols.link.linux_sll.LinuxSLL` only, the base class of the
+Linux "cooked" capture encapsulation family:
+
+.. list-table::
+   :header-rows: 1
+
+   * - ``LinkType``
+     - Class
+   * - ``LINUX_SLL`` (113)
+     - :class:`~pcapkit.protocols.link.linux_sll1.LinuxSLL1`
+   * - ``LINUX_SLL2`` (276)
+     - :class:`~pcapkit.protocols.link.linux_sll2.LinuxSLL2`
+
+The versions differ in field order and width, so each parses its own header.
+The base holds what they share: the next-layer dispatch, and link-layer address
+validation. It has no registry index, so its ``__index__`` raises.
+
+.. autoclass:: pcapkit.protocols.link.linux_sll.LinuxSLL
+   :no-members:
+   :show-inheritance:
+
+   .. automethod:: id
+   .. automethod:: __index__
+   .. automethod:: _import_next_layer
+
+Auxiliary Functions
+-------------------
+
+.. autofunction:: pcapkit.protocols.link.linux_sll._resolve_next_layer_proto
+.. autofunction:: pcapkit.protocols.link.linux_sll._validate_link_addr
+
+Auxiliary Constants
+-------------------
+
+.. autodata:: pcapkit.protocols.link.linux_sll._ARPHRD_NOT_ETHERTYPE
+.. autodata:: pcapkit.protocols.link.linux_sll._ETHERTYPE_FIELD
+   :no-value:
+
+Hardware Types
+--------------
+
+The ``arphrd_type`` values in ``_ARPHRD_NOT_ETHERTYPE`` are named by the enumeration below.
+
+.. autoclass:: pcapkit.const.linux.arphrd.ARPHRD
+   :members:
+   :show-inheritance:
+
+.. _linux-sll-labels:
+
+Selecting a Version
+-------------------
+
+The family name selects either version, and each version's own name selects that
+version only, as :class:`~pcapkit.protocols.internet.ipv4.IPv4` and
+:class:`~pcapkit.protocols.internet.ipv6.IPv6` do under
+:class:`~pcapkit.protocols.internet.ip.IP`. ``'LinuxSLL'`` is in both versions;
+``'LinuxSLL1' in`` a v2 layer is :data:`False`. String ``==`` does not expand a
+key, so ``v1 == 'LinuxSLL'`` is :data:`False` while ``'LinuxSLL' in v1`` is :data:`True`.

docs/source/pcapkit/protocols/link/linux_sll1.rst

@@ -0,0 +1,75 @@
+Linux "Cooked" Capture Encapsulation
+=====================================
+
+.. module:: pcapkit.protocols.link.linux_sll1
+
+:mod:`pcapkit.protocols.link.linux_sll1` contains
+:class:`~pcapkit.protocols.link.linux_sll1.LinuxSLL1`
+only, which implements the extractor for the Linux "cooked" capture
+encapsulation [*]_ of ``LINKTYPE_LINUX_SLL`` -- the header every
+``tcpdump -i any`` capture on Linux uses -- whose structure is described as
+below:
+
+.. table::
+
+   ====== ===== ============================== ================================
+   Octets Bits  Name                           Description
+   ====== ===== ============================== ================================
+   0          0 ``linux_sll.packet_type``      Packet Type
+   ------ ----- ------------------------------ --------------------------------
+   2         16 ``linux_sll.arphrd_type``      ARP Hardware Type
+   ------ ----- ------------------------------ --------------------------------
+   4         32 ``linux_sll.link_addr_length`` Link-Layer Address Length
+   ------ ----- ------------------------------ --------------------------------
+   6         48 ``linux_sll.link_addr``        Link-Layer Address (padded)
+   ------ ----- ------------------------------ --------------------------------
+   14       112 ``linux_sll.protocol_type``    Protocol (Internet Layer)
+   ====== ===== ============================== ================================
+
+Next-layer dispatch is shared with
+:class:`~pcapkit.protocols.link.linux_sll2.LinuxSLL2`; see
+:mod:`~pcapkit.protocols.link.linux_sll`. Its
+:meth:`~pcapkit.protocols.link.linux_sll1.LinuxSLL1.id` is
+``('LinuxSLL1',)``, and its
+:attr:`~pcapkit.protocols.link.linux_sll1.LinuxSLL1.alias` is ``'LINUX_SLL1'``;
+see :ref:`linux-sll-labels`.
+
+.. autoclass:: pcapkit.protocols.link.linux_sll1.LinuxSLL1
+   :no-members:
+   :show-inheritance:
+
+   .. autoproperty:: name
+   .. autoproperty:: alias
+   .. autoproperty:: info_name
+   .. autoproperty:: length
+   .. autoproperty:: protocol
+
+   .. automethod:: id
+   .. automethod:: read
+   .. automethod:: make
+
+   .. automethod:: _make_data
+
+   .. automethod:: __index__
+
+Header Schemas
+--------------
+
+.. module:: pcapkit.protocols.schema.link.linux_sll1
+
+.. autoclass:: pcapkit.protocols.schema.link.linux_sll1.LinuxSLL1
+   :members:
+   :show-inheritance:
+
+Data Models
+-----------
+
+.. module:: pcapkit.protocols.data.link.linux_sll1
+
+.. autoclass:: pcapkit.protocols.data.link.linux_sll1.LinuxSLL1
+   :members:
+   :show-inheritance:
+
+.. rubric:: Footnotes
+
+.. [*] https://www.tcpdump.org/linktypes/LINKTYPE_LINUX_SLL.html

docs/source/pcapkit/protocols/link/linux_sll2.rst

@@ -0,0 +1,79 @@
+Linux "Cooked" Capture Encapsulation v2
+=========================================
+
+.. module:: pcapkit.protocols.link.linux_sll2
+
+:mod:`pcapkit.protocols.link.linux_sll2` contains
+:class:`~pcapkit.protocols.link.linux_sll2.LinuxSLL2`
+only, which implements the extractor for the Linux "cooked" capture
+encapsulation v2 [*]_ of ``LINKTYPE_LINUX_SLL2``, whose structure is described
+as below:
+
+.. table::
+
+   ====== ===== ================================ ================================
+   Octets Bits  Name                             Description
+   ====== ===== ================================ ================================
+   0          0 ``linux_sll2.protocol_type``     Protocol (Internet Layer)
+   ------ ----- -------------------------------- --------------------------------
+   2         16 ``linux_sll2.reserved``          Reserved
+   ------ ----- -------------------------------- --------------------------------
+   4         32 ``linux_sll2.interface_index``   Interface Index
+   ------ ----- -------------------------------- --------------------------------
+   8         64 ``linux_sll2.arphrd_type``       ARP Hardware Type
+   ------ ----- -------------------------------- --------------------------------
+   10        80 ``linux_sll2.packet_type``       Packet Type
+   ------ ----- -------------------------------- --------------------------------
+   11        88 ``linux_sll2.link_addr_length``  Link-Layer Address Length
+   ------ ----- -------------------------------- --------------------------------
+   12        96 ``linux_sll2.link_addr``         Link-Layer Address (padded)
+   ====== ===== ================================ ================================
+
+Unlike v1, ``protocol_type`` comes first, ``interface_index`` is new, and
+``packet_type`` and ``link_addr_length`` are 1 octet rather than 2. See
+:class:`~pcapkit.protocols.link.linux_sll1.LinuxSLL1` for v1; next-layer
+dispatch is shared, see :mod:`~pcapkit.protocols.link.linux_sll`. Its
+:meth:`~pcapkit.protocols.link.linux_sll2.LinuxSLL2.id` is
+``('LinuxSLL2',)``, and its
+:attr:`~pcapkit.protocols.link.linux_sll2.LinuxSLL2.alias` is ``'LINUX_SLL2'``;
+see :ref:`linux-sll-labels`.
+
+.. autoclass:: pcapkit.protocols.link.linux_sll2.LinuxSLL2
+   :no-members:
+   :show-inheritance:
+
+   .. autoproperty:: name
+   .. autoproperty:: alias
+   .. autoproperty:: info_name
+   .. autoproperty:: length
+   .. autoproperty:: protocol
+
+   .. automethod:: id
+   .. automethod:: read
+   .. automethod:: make
+
+   .. automethod:: _make_data
+
+   .. automethod:: __index__
+
+Header Schemas
+--------------
+
+.. module:: pcapkit.protocols.schema.link.linux_sll2
+
+.. autoclass:: pcapkit.protocols.schema.link.linux_sll2.LinuxSLL2
+   :members:
+   :show-inheritance:
+
+Data Models
+-----------
+
+.. module:: pcapkit.protocols.data.link.linux_sll2
+
+.. autoclass:: pcapkit.protocols.data.link.linux_sll2.LinuxSLL2
+   :members:
+   :show-inheritance:
+
+.. rubric:: Footnotes
+
+.. [*] https://www.tcpdump.org/linktypes/LINKTYPE_LINUX_SLL2.html