feat(link): dissect the IEEE 802.11 MAC header behind radiotap

docs/source/contributing/conventions/const-vendor-pairing.rst

@@ -40,6 +40,12 @@ module docstring and comments, alongside the ``DATA`` literal it documents; the
 generated ``const`` module carries only the plain, templated docstring every
 other generated module does.
 
+Where the primary source is paywalled, a pinned secondary revision is an acceptable
+``DATA`` source once its values are cross-checked against independent implementations,
+ruled in review of :pr:`2607` (:issue:`2575`). :mod:`pcapkit.vendor.ipx` is the earlier
+example, and the :mod:`pcapkit.vendor.ieee802_11` crawlers check theirs against the
+Linux kernel's header and Wireshark.
+
 ``LINK``-and-Scrape Pairing: TLS Content Types and HandshakeType
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/source/contributing/conventions/mint-criterion.rst

@@ -67,11 +67,15 @@ Measured against the tree, by class:
   ``cls._value2member_map_.setdefault(value, pseudo_member)``.
 * **Raise for any unknown value**: :class:`~pcapkit.const.reg.apptype.apptype.AppType`,
   :class:`~pcapkit.const.ipv6.extension_header.ExtensionHeader`,
-  :class:`~pcapkit.const.pcapng.tls_key_label.TLSKeyLabel` and
-  :class:`~pcapkit.const.hip.transport.Transport`.
-  :class:`~pcapkit.const.hip.transport.Transport` raises from its own range check: its
-  declared range ``0..3`` is exactly its member set, so no unassigned value is left for
-  ``super()._missing_`` (the line after the check is unreachable).
+  :class:`~pcapkit.const.pcapng.tls_key_label.TLSKeyLabel`,
+  :class:`~pcapkit.const.hip.transport.Transport`,
+  :class:`~pcapkit.const.ieee802_11.type.Type` and
+  :class:`~pcapkit.const.ieee802_11.management_subtype.ManagementSubtype`.
+  :class:`~pcapkit.const.hip.transport.Transport`,
+  :class:`~pcapkit.const.ieee802_11.type.Type` and
+  :class:`~pcapkit.const.ieee802_11.management_subtype.ManagementSubtype` raise from their
+  own range checks: each declared range is exactly its member set, so no unassigned value
+  is left for ``super()._missing_`` (the line after the check is unreachable).
 
 Note that these are |aenum|_ classes: ``issubclass(Flags, enum.IntFlag)`` is ``False``
 against the standard library and ``True`` against ``aenum.IntFlag``, so a probe against
@@ -209,8 +213,11 @@ only ``ast.Name`` nodes finds every mint and no unmint at all:
 
    The walk reads each file's own ``_missing_``, so it reports
    :class:`~pcapkit.const.reg.apptype.apptype.AppType` as an unmint although it raises,
-   prints nothing for the flag registries and
-   :class:`~pcapkit.const.hip.transport.Transport` (they call neither function) nor for
+   prints nothing for the flag registries,
+   :class:`~pcapkit.const.hip.transport.Transport`,
+   :class:`~pcapkit.const.ieee802_11.type.Type` and
+   :class:`~pcapkit.const.ieee802_11.management_subtype.ManagementSubtype` (they call
+   neither function) nor for
    :class:`~pcapkit.const.ipv6.extension_header.ExtensionHeader` and
    :class:`~pcapkit.const.pcapng.tls_key_label.TLSKeyLabel` (they define no
    ``_missing_``), and does not see the transport subclasses, which inherit theirs.

docs/source/contributing/conventions/registry-protocol.rst

@@ -802,6 +802,10 @@ from it:
   :class:`~pcapkit.const.reg.linktype.LinkType` members, but
   :func:`~pcapkit.foundation.registry.protocols.register_linktype` holds that name
   for writing both their maps at once, so each takes its capture format's name.
+* :func:`~pcapkit.foundation.registry.protocols.register_radiotap` takes only
+  :class:`~pcapkit.const.reg.linktype.LinkType` members too, keyed by the link type
+  of the frame behind a radiotap header, and takes its owning protocol's name for the
+  same reason.
 * :func:`~pcapkit.foundation.registry.protocols.register_apptype` takes bare
   :class:`int` keys, but writes :class:`~pcapkit.protocols.transport.tcp.TCP`'s map,
   :class:`~pcapkit.protocols.transport.udp.UDP`'s or both, by transport, so no one

docs/source/pcapkit/const/ieee802_11.rst

@@ -0,0 +1,88 @@
+==============================================================================
+:class:`~pcapkit.protocols.link.ieee802_11.IEEE802_11` Constant Enumerations
+==============================================================================
+
+.. module:: pcapkit.const.ieee802_11
+
+This module contains all constant enumerations of
+:class:`~pcapkit.protocols.link.ieee802_11.IEEE802_11` implementations, each
+from IEEE Std 802.11-2020, Table 9-1, *Valid type and subtype combinations*.
+Available enumerations include:
+
+.. list-table::
+
+   * - :class:`IEEE802_11_Type <pcapkit.const.ieee802_11.type.Type>`
+     - Frame Types
+   * - :class:`IEEE802_11_ManagementSubtype <pcapkit.const.ieee802_11.management_subtype.ManagementSubtype>`
+     - Management Frame Subtypes
+   * - :class:`IEEE802_11_ControlSubtype <pcapkit.const.ieee802_11.control_subtype.ControlSubtype>`
+     - Control Frame Subtypes
+   * - :class:`IEEE802_11_DataSubtype <pcapkit.const.ieee802_11.data_subtype.DataSubtype>`
+     - Data Frame Subtypes
+   * - :class:`IEEE802_11_ExtensionSubtype <pcapkit.const.ieee802_11.extension_subtype.ExtensionSubtype>`
+     - Extension Frame Subtypes
+
+Frame Types
+===========
+
+.. module:: pcapkit.const.ieee802_11.type
+
+This module contains the constant enumeration for **IEEE 802.11 Frame Types**,
+which is automatically generated from :class:`pcapkit.vendor.ieee802_11.type.Type`.
+
+.. autoclass:: pcapkit.const.ieee802_11.type.Type
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Management Frame Subtypes
+=========================
+
+.. module:: pcapkit.const.ieee802_11.management_subtype
+
+This module contains the constant enumeration for **IEEE 802.11 Management Frame Subtypes**,
+which is automatically generated from :class:`pcapkit.vendor.ieee802_11.management_subtype.ManagementSubtype`.
+
+.. autoclass:: pcapkit.const.ieee802_11.management_subtype.ManagementSubtype
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Control Frame Subtypes
+======================
+
+.. module:: pcapkit.const.ieee802_11.control_subtype
+
+This module contains the constant enumeration for **IEEE 802.11 Control Frame Subtypes**,
+which is automatically generated from :class:`pcapkit.vendor.ieee802_11.control_subtype.ControlSubtype`.
+
+.. autoclass:: pcapkit.const.ieee802_11.control_subtype.ControlSubtype
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Data Frame Subtypes
+===================
+
+.. module:: pcapkit.const.ieee802_11.data_subtype
+
+This module contains the constant enumeration for **IEEE 802.11 Data Frame Subtypes**,
+which is automatically generated from :class:`pcapkit.vendor.ieee802_11.data_subtype.DataSubtype`.
+
+.. autoclass:: pcapkit.const.ieee802_11.data_subtype.DataSubtype
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Extension Frame Subtypes
+========================
+
+.. module:: pcapkit.const.ieee802_11.extension_subtype
+
+This module contains the constant enumeration for **IEEE 802.11 Extension Frame Subtypes**,
+which is automatically generated from :class:`pcapkit.vendor.ieee802_11.extension_subtype.ExtensionSubtype`.
+
+.. autoclass:: pcapkit.const.ieee802_11.extension_subtype.ExtensionSubtype
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/pcapkit/const/index.rst

@@ -31,6 +31,8 @@ Some behave otherwise, and :ref:`mint-criterion` gives the full split:
   table only: a second lookup returns the same object, while ``__members__``
   and iteration are unchanged.
 * :class:`~pcapkit.const.hip.transport.Transport`,
+  :class:`~pcapkit.const.ieee802_11.type.Type`,
+  :class:`~pcapkit.const.ieee802_11.management_subtype.ManagementSubtype`,
   :class:`~pcapkit.const.ipv6.extension_header.ExtensionHeader`,
   :class:`~pcapkit.const.pcapng.tls_key_label.TLSKeyLabel` and the memberless
   :class:`~pcapkit.const.reg.apptype.apptype.AppType` base raise
@@ -69,6 +71,7 @@ Link Layer
    :maxdepth: 2
 
    arp
+   ieee802_11
    l2tp
    linux
    vlan

docs/source/pcapkit/foundation/registry.rst

@@ -91,6 +91,8 @@ Link Layer Registries
 
 .. autofunction:: pcapkit.foundation.registry.protocols.register_netlink
 
+.. autofunction:: pcapkit.foundation.registry.protocols.register_radiotap
+
 Internet Layer Registries
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

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

@@ -0,0 +1,130 @@
+IEEE 802.11 - Wireless LAN MAC Header
+=====================================
+
+.. module:: pcapkit.protocols.link.ieee802_11
+
+:mod:`pcapkit.protocols.link.ieee802_11` contains
+:class:`~pcapkit.protocols.link.ieee802_11.IEEE802_11` only, which implements
+the extractor for the IEEE 802.11 MAC header [*]_ of a protocol version 0
+frame, as :class:`~pcapkit.protocols.link.radiotap.Radiotap` hands it on. Its
+fields, in the order they appear, numeric ones little-endian:
+
+.. table::
+
+   ======================= ======= ============================================
+   Name                    Octets  Present
+   ======================= ======= ============================================
+   ``frame_control``       2       always (§9.2.4.1)
+   ``duration_id``         2       always (§9.2.4.2)
+   ``addr1``               6       always (§9.2.4.3)
+   ``addr2``               6       Management, Data, and Control frames that
+                                   carry a TA (§9.2.4.3, §9.3.1)
+   ``addr3``               6       Management and Data frames (§9.2.4.3)
+   ``seq_ctrl``            2       Management and Data frames (§9.2.4.4)
+   ``addr4``               6       Data frames with To DS and From DS set
+                                   (§9.2.4.3)
+   ``qos_control``         2       QoS Data subtypes (§9.2.4.5)
+   ``ht_control``          4       QoS Data subtypes and Management frames
+                                   with +HTC/Order set (§9.2.4.6)
+   ======================= ======= ============================================
+
+:func:`~pcapkit.protocols.schema.link.ieee802_11.layout` gives the rule per
+frame type. A Control frame of a subtype whose layout this class does not
+model, and an Extension frame, are read as the minimal frame format of
+§9.2.3: the first three fields only. A Control Frame Extension frame and an
+S1G Beacon lay out B8-B15 of Frame Control differently; see
+:class:`~pcapkit.protocols.data.link.ieee802_11.FrameControl`.
+
+Scope
+-----
+
+* **The frame body** (§9.2.4.7) is kept as
+  :class:`~pcapkit.protocols.misc.raw.Raw`, protected or not.
+* **The FCS** (§9.2.4.8), where one was captured, stays at the end of the
+  body: whether a capture carries it is a radiotap Flags bit, which
+  :class:`~pcapkit.protocols.link.radiotap.Radiotap` does not decode.
+* **Pad octets** that radiotap's data-pad flag says follow the header stay
+  at the start of the body, for the same reason.
+* **A protocol version other than 0** is refused: version 1 is the PV1
+  frame format of §9.8, whose Frame Control field is laid out differently,
+  and versions 2 and 3 are reserved.
+
+.. autoclass:: pcapkit.protocols.link.ieee802_11.IEEE802_11
+   :no-members:
+   :show-inheritance:
+
+   .. autoproperty:: name
+   .. autoproperty:: alias
+   .. autoproperty:: length
+
+   .. automethod:: id
+
+   .. automethod:: read
+   .. automethod:: make
+
+   .. automethod:: __length_hint__
+   .. automethod:: __index__
+
+   .. automethod:: _make_data
+   .. automethod:: _read_frame_control
+   .. automethod:: _make_frame_control
+   .. automethod:: _read_mac_addr
+   .. automethod:: _make_mac_addr
+   .. automethod:: _read_seq_ctrl
+   .. automethod:: _make_seq_ctrl
+   .. automethod:: _read_qos_control
+   .. automethod:: _make_qos_control
+   .. automethod:: _read_ht_control
+   .. automethod:: _make_ht_control
+
+.. autodata:: pcapkit.protocols.link.ieee802_11.SUBTYPE
+   :no-value:
+
+Header Schemas
+--------------
+
+.. module:: pcapkit.protocols.schema.link.ieee802_11
+
+.. autoclass:: pcapkit.protocols.schema.link.ieee802_11.IEEE802_11
+   :members:
+   :show-inheritance:
+
+.. autofunction:: pcapkit.protocols.schema.link.ieee802_11.layout
+
+.. autoclass:: pcapkit.protocols.schema.link.ieee802_11.Layout
+   :members:
+   :show-inheritance:
+
+.. autodata:: pcapkit.protocols.schema.link.ieee802_11.CONTROL_WITH_ADDR2
+   :no-value:
+
+Data Models
+-----------
+
+.. module:: pcapkit.protocols.data.link.ieee802_11
+
+.. autoclass:: pcapkit.protocols.data.link.ieee802_11.IEEE802_11
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pcapkit.protocols.data.link.ieee802_11.FrameControl
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pcapkit.protocols.data.link.ieee802_11.SequenceControl
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pcapkit.protocols.data.link.ieee802_11.QoSControl
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pcapkit.protocols.data.link.ieee802_11.HTControl
+   :members:
+   :show-inheritance:
+
+.. rubric:: Footnotes
+
+.. [*] IEEE Std 802.11-2020, clause 9, *Frame formats*. The clause numbers
+   above are its own, checked against Wireshark's ``packet-ieee80211.c`` where
+   it cites one: §9.2.4.1.10, §9.2.4.6, §9.2.4.7 and §9.8.

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

@@ -27,6 +27,7 @@ link layer, with detailed implementation and methods.
    inarp
    frad
    gre
+   ieee802_11
    l2tp
    l2tpv2
    linux_sll

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

@@ -32,11 +32,8 @@ bounds the whole of it; the 802.11 MAC frame starts at that offset.
 Scope
 -----
 
-Decoding every optional field radiotap.org defines, and the 802.11 MAC
-frame behind them, is future work tracked on :issue:`2460` and
-:issue:`2502` -- this is already the widest of that issue's five
-follow-ups, and the 802.11 MAC frame is a protocol family of its own. This
-first cut instead:
+Decoding every optional field radiotap.org defines is tracked on
+:issue:`2576`. This class:
 
 * **Decodes** the fixed 8-octet start -- ``it_version``, ``it_pad``,
   ``it_len`` -- and walks the present-flags chain far enough to know how
@@ -47,11 +44,15 @@ first cut instead:
   select -- the octets between the present-flags chain and ``it_len`` are
   kept whole and undissected, as
   :attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.fields`.
-* **Leaves opaque** everything from ``it_len`` on: the 802.11 MAC frame
-  itself, which has no dissector anywhere in this package yet. It is kept
-  as :class:`~pcapkit.protocols.misc.raw.Raw` (or
-  :class:`~pcapkit.protocols.misc.null.NoPayload` when nothing follows),
-  unconditionally.
+* **Hands** everything from ``it_len`` on, the 802.11 MAC frame, to
+  :class:`~pcapkit.protocols.link.ieee802_11.IEEE802_11`
+  (:class:`~pcapkit.protocols.misc.null.NoPayload` when nothing follows).
+  The header names no next protocol, since an 802.11 frame always follows it,
+  so the frame is looked up in
+  :attr:`Radiotap.__proto__ <pcapkit.protocols.link.radiotap.Radiotap.__proto__>`
+  under :attr:`LinkType.IEEE802_11 <pcapkit.const.reg.linktype.LinkType.IEEE802_11>`;
+  :func:`~pcapkit.foundation.registry.protocols.register_radiotap` replaces
+  the entry.
 
 .. autoclass:: pcapkit.protocols.link.radiotap.Radiotap
    :no-members:
@@ -65,15 +66,18 @@ first cut instead:
 
    .. automethod:: read
    .. automethod:: make
+   .. automethod:: register
 
    .. automethod:: __length_hint__
    .. automethod:: __index__
 
    .. automethod:: _make_data
-   .. automethod:: _import_next_layer
+   .. automethod:: _get_payload
 
    .. autoattribute:: __proto__
       :no-value:
+   .. autoattribute:: __proto_key__
+      :no-value:
 
 Header Schemas
 --------------