From 53e71b47abaabaa8f6cbfdf530a4f435726b0bd8 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Sun, 1 Nov 2026 23:51:13 -0500 Subject: [PATCH] feat(link): decode radiotap's optional fields (#2576) - Decode the field-data region into Radiotap.decoded, one entry per presence bit, bits 16 and 17 included: alignment from the header start, namespaces, raw vendor data, extended words and TLVs; the rest ends as an Unknown. - Read and make each type through Radiotap.__field__, keyed by FieldType, with register_field and the register_radiotap_field wrapper for new types. - Give each type a RadiotapField schema whose fields, size and __align__ are its radiotap.org layout; bitmaps are EnumFields of their flag registries. - Add pcapkit.const.radiotap, FieldType and fourteen flag registries named after Linux's macros, each with a crawler scraping its radiotap.org page. - Tests: spec, radiotap-library and tcpdump vectors, both round trips, a registered type, a radiotap-field option family, the registrar tables. The protocols/link, const, vendor, project, foundation and corekit legs pass. --- .../conventions/mint-criterion.rst | 9 +- .../conventions/registry-protocol.rst | 15 + docs/source/contributing/pep.rst | 4 +- docs/source/pcapkit/const/index.rst | 5 +- docs/source/pcapkit/const/radiotap.rst | 244 +++ docs/source/pcapkit/foundation/registry.rst | 2 + .../pcapkit/protocols/link/ieee802_11.rst | 3 +- .../pcapkit/protocols/link/radiotap.rst | 432 +++- docs/source/pcapkit/vendor/index.rst | 1 + docs/source/pcapkit/vendor/radiotap.rst | 250 +++ .../generators/option_families/radiotap.py | 106 + pcapkit/all.py | 1 + pcapkit/const/__init__.py | 6 + pcapkit/const/radiotap/__init__.py | 69 + pcapkit/const/radiotap/ampdu_flags.py | 85 + pcapkit/const/radiotap/channel_flags.py | 94 + pcapkit/const/radiotap/eht_known.py | 124 ++ pcapkit/const/radiotap/field_type.py | 165 ++ pcapkit/const/radiotap/flags.py | 85 + .../const/radiotap/he_mu_other_user_known.py | 85 + pcapkit/const/radiotap/lsig_data1.py | 67 + pcapkit/const/radiotap/mcs_known.py | 85 + pcapkit/const/radiotap/rx_flags.py | 64 + pcapkit/const/radiotap/s1g_known.py | 85 + pcapkit/const/radiotap/timestamp_flags.py | 67 + pcapkit/const/radiotap/tx_flags.py | 82 + pcapkit/const/radiotap/vht_coding.py | 73 + pcapkit/const/radiotap/vht_flags.py | 84 + pcapkit/const/radiotap/vht_known.py | 90 + pcapkit/foundation/__init__.py | 1 + pcapkit/foundation/registry/__init__.py | 1 + .../foundation/registry/protocols/__init__.py | 1 + pcapkit/foundation/registry/protocols/link.py | 52 +- pcapkit/protocols/data/__init__.py | 12 +- pcapkit/protocols/data/link/__init__.py | 49 +- pcapkit/protocols/data/link/radiotap.py | 586 +++++- pcapkit/protocols/link/ieee802_11.py | 6 +- pcapkit/protocols/link/radiotap.py | 1798 ++++++++++++++++- pcapkit/protocols/schema/__init__.py | 9 + pcapkit/protocols/schema/link/__init__.py | 44 + pcapkit/protocols/schema/link/radiotap.py | 585 +++++- pcapkit/vendor/__init__.py | 6 + pcapkit/vendor/radiotap/__init__.py | 69 + pcapkit/vendor/radiotap/ampdu_flags.py | 46 + pcapkit/vendor/radiotap/channel_flags.py | 51 + pcapkit/vendor/radiotap/eht_known.py | 59 + pcapkit/vendor/radiotap/field_type.py | 151 ++ pcapkit/vendor/radiotap/flags.py | 303 +++ .../vendor/radiotap/he_mu_other_user_known.py | 38 + pcapkit/vendor/radiotap/lsig_data1.py | 40 + pcapkit/vendor/radiotap/mcs_known.py | 48 + pcapkit/vendor/radiotap/rx_flags.py | 39 + pcapkit/vendor/radiotap/s1g_known.py | 46 + pcapkit/vendor/radiotap/timestamp_flags.py | 40 + pcapkit/vendor/radiotap/tx_flags.py | 44 + pcapkit/vendor/radiotap/vht_coding.py | 42 + pcapkit/vendor/radiotap/vht_flags.py | 44 + pcapkit/vendor/radiotap/vht_known.py | 47 + tests/const/census/radiotap.py | 21 + tests/const/test_const_registry_protocol.py | 56 +- .../test_nameless_enum_rendering_unit.py | 49 +- tests/foundation/registry/test_protocols.py | 5 + .../test_registrar_code_check_unit.py | 3 + .../registry/test_registry_symmetry_unit.py | 3 + .../link/test_radiotap_fields_2576_unit.py | 711 +++++++ .../vendor/test_radiotap_crawler_2576_unit.py | 575 ++++++ tests/vendor/test_vendor_missing_body_unit.py | 1 + 67 files changed, 8058 insertions(+), 105 deletions(-) create mode 100644 docs/source/pcapkit/const/radiotap.rst create mode 100644 docs/source/pcapkit/vendor/radiotap.rst create mode 100644 examples/generators/option_families/radiotap.py create mode 100644 pcapkit/const/radiotap/__init__.py create mode 100644 pcapkit/const/radiotap/ampdu_flags.py create mode 100644 pcapkit/const/radiotap/channel_flags.py create mode 100644 pcapkit/const/radiotap/eht_known.py create mode 100644 pcapkit/const/radiotap/field_type.py create mode 100644 pcapkit/const/radiotap/flags.py create mode 100644 pcapkit/const/radiotap/he_mu_other_user_known.py create mode 100644 pcapkit/const/radiotap/lsig_data1.py create mode 100644 pcapkit/const/radiotap/mcs_known.py create mode 100644 pcapkit/const/radiotap/rx_flags.py create mode 100644 pcapkit/const/radiotap/s1g_known.py create mode 100644 pcapkit/const/radiotap/timestamp_flags.py create mode 100644 pcapkit/const/radiotap/tx_flags.py create mode 100644 pcapkit/const/radiotap/vht_coding.py create mode 100644 pcapkit/const/radiotap/vht_flags.py create mode 100644 pcapkit/const/radiotap/vht_known.py create mode 100644 pcapkit/vendor/radiotap/__init__.py create mode 100644 pcapkit/vendor/radiotap/ampdu_flags.py create mode 100644 pcapkit/vendor/radiotap/channel_flags.py create mode 100644 pcapkit/vendor/radiotap/eht_known.py create mode 100644 pcapkit/vendor/radiotap/field_type.py create mode 100644 pcapkit/vendor/radiotap/flags.py create mode 100644 pcapkit/vendor/radiotap/he_mu_other_user_known.py create mode 100644 pcapkit/vendor/radiotap/lsig_data1.py create mode 100644 pcapkit/vendor/radiotap/mcs_known.py create mode 100644 pcapkit/vendor/radiotap/rx_flags.py create mode 100644 pcapkit/vendor/radiotap/s1g_known.py create mode 100644 pcapkit/vendor/radiotap/timestamp_flags.py create mode 100644 pcapkit/vendor/radiotap/tx_flags.py create mode 100644 pcapkit/vendor/radiotap/vht_coding.py create mode 100644 pcapkit/vendor/radiotap/vht_flags.py create mode 100644 pcapkit/vendor/radiotap/vht_known.py create mode 100644 tests/const/census/radiotap.py create mode 100644 tests/protocols/link/test_radiotap_fields_2576_unit.py create mode 100644 tests/vendor/test_radiotap_crawler_2576_unit.py diff --git a/docs/source/contributing/conventions/mint-criterion.rst b/docs/source/contributing/conventions/mint-criterion.rst index d98b46144d..0f0546314c 100644 --- a/docs/source/contributing/conventions/mint-criterion.rst +++ b/docs/source/contributing/conventions/mint-criterion.rst @@ -60,8 +60,9 @@ Measured against the tree, by class: :mod:`mh.dhcp_support_mode ` and :mod:`vlan.priority_level `. * **Cache in the value table only**: :class:`~pcapkit.const.tcp.flags.Flags`, - :class:`~pcapkit.const.ftp.command.CommandType` and the Mobility Header flag - registries, such as :class:`~pcapkit.const.mh.binding_ack_flag.BindingACKFlag`. They + :class:`~pcapkit.const.ftp.command.CommandType`, the Mobility Header flag + registries, such as :class:`~pcapkit.const.mh.binding_ack_flag.BindingACKFlag`, and + the radiotap flag registries, such as :class:`~pcapkit.const.radiotap.flags.Flags`. They range-check and hand back to ``super()._missing_``, which for an ``aenum.IntFlag`` reaches ``_create_pseudo_member_`` and ends in ``cls._value2member_map_.setdefault(value, pseudo_member)``. @@ -232,8 +233,8 @@ only ``ast.Name`` nodes finds every mint and no unmint at all: lookup then finds. :class:`~pcapkit.const.mh.cga_type.CGAType` grows ``__members__``, ``_member_map_`` and ``_value2member_map_``; :class:`~pcapkit.const.tcp.flags.Flags`, - :class:`~pcapkit.const.ftp.command.CommandType` and the Mobility Header flag - registries grow ``_value2member_map_`` only. Snapshot + :class:`~pcapkit.const.ftp.command.CommandType` and the Mobility Header and + radiotap flag registries grow ``_value2member_map_`` only. Snapshot ``{member.value for member in Cls}`` before any lookup regardless -- that snapshot cannot see the flag registries' cache, so compare ``len(Cls._value2member_map_)`` too -- and use a throwaway process per registry when comparing behaviour across diff --git a/docs/source/contributing/conventions/registry-protocol.rst b/docs/source/contributing/conventions/registry-protocol.rst index 20b049ad62..664a10bdba 100644 --- a/docs/source/contributing/conventions/registry-protocol.rst +++ b/docs/source/contributing/conventions/registry-protocol.rst @@ -863,6 +863,21 @@ unless its ``EXCUSED`` table gives the reason. It fails as well on a map whose o defines no ``register*`` classmethod of its own, unless its ``INHERITED`` table names the one typed for that map's keys. +**A protocol's table from a code to the layout read under it is such a map as well, and +each layout is a concrete schema.** Ruled in review of :pr:`2657` (:issue:`2576`): the +table is a class-level map on the protocol, with its ``register_`` classmethod and +its wrapper, and never a dictionary at module level; each layout is a +:class:`~pcapkit.protocols.schema.schema.Schema` subclass with typed fields, defined with +the protocol's other schemas, and never built inside the map. Radiotap's field types are +the example: +:attr:`Radiotap.__field__ ` is +written by :meth:`Radiotap.register_field ` +and :func:`~pcapkit.foundation.registry.protocols.link.register_radiotap_field`, in the +shape of :func:`~pcapkit.foundation.registry.protocols.transport.register_sctp_chunk` +above, and each type's layout is a +:class:`~pcapkit.protocols.schema.link.radiotap.RadiotapField` subclass, whose fields +are the type's subfields and whose ``__align__`` is its alignment. + .. _registry-protocol-index: The Registry Index diff --git a/docs/source/contributing/pep.rst b/docs/source/contributing/pep.rst index c81099e71b..f03eba26d0 100644 --- a/docs/source/contributing/pep.rst +++ b/docs/source/contributing/pep.rst @@ -1220,8 +1220,8 @@ neither header treats as carrying an EtherType each have a dissector of their ow ``NETLINK`` to :class:`~pcapkit.protocols.link.netlink.Netlink`, ``IPGRE`` and ``IP6GRE`` to :class:`~pcapkit.protocols.link.gre.GRE`, ``FRAD`` to :class:`~pcapkit.protocols.link.frad.FRAD`, and ``IEEE80211_RADIOTAP`` to -:class:`~pcapkit.protocols.link.radiotap.Radiotap` (:issue:`2502`), which keeps its -optional fields undissected (:issue:`2576`) and hands the 802.11 frame to +:class:`~pcapkit.protocols.link.radiotap.Radiotap` (:issue:`2502`), which decodes its +optional fields (:issue:`2576`) and hands the 802.11 frame to :class:`~pcapkit.protocols.link.ieee802_11.IEEE802_11`, which dissects the MAC header and keeps the frame body :class:`~pcapkit.protocols.misc.raw.Raw` (:issue:`2575`). diff --git a/docs/source/pcapkit/const/index.rst b/docs/source/pcapkit/const/index.rst index 35115c306b..d4999c3057 100644 --- a/docs/source/pcapkit/const/index.rst +++ b/docs/source/pcapkit/const/index.rst @@ -24,8 +24,8 @@ Some behave otherwise, and :ref:`mint-criterion` gives the full split: * :class:`~pcapkit.const.mh.cga_type.CGAType` installs a permanent member, so ``__members__`` and iteration grow. -* :class:`~pcapkit.const.tcp.flags.Flags` and the Mobility Header flag - registries, such as +* :class:`~pcapkit.const.tcp.flags.Flags` and the Mobility Header and radiotap + flag registries, such as :class:`~pcapkit.const.mh.binding_ack_flag.BindingACKFlag`, hand back to |aenum|_'s flag base, which caches the composed object in the value lookup table only: a second lookup returns the same object, while ``__members__`` @@ -74,6 +74,7 @@ Link Layer ieee802_11 l2tp linux + radiotap vlan Internet Layer diff --git a/docs/source/pcapkit/const/radiotap.rst b/docs/source/pcapkit/const/radiotap.rst new file mode 100644 index 0000000000..81020318f4 --- /dev/null +++ b/docs/source/pcapkit/const/radiotap.rst @@ -0,0 +1,244 @@ +========================================================================== +:class:`~pcapkit.protocols.link.radiotap.Radiotap` Constant Enumerations +========================================================================== + +.. module:: pcapkit.const.radiotap + +This module contains all constant enumerations of +:class:`~pcapkit.protocols.link.radiotap.Radiotap` implementations, each scraped +from radiotap.org [*]_. Available enumerations include: + +.. list-table:: + + * - :class:`Radiotap_FieldType ` + - Field Types + * - :class:`Radiotap_Flags ` + - Flags + * - :class:`Radiotap_ChannelFlags ` + - Channel Flags + * - :class:`Radiotap_RXFlags ` + - RX Flags + * - :class:`Radiotap_TXFlags ` + - TX Flags + * - :class:`Radiotap_MCSKnown ` + - MCS Known Flags + * - :class:`Radiotap_AMPDUFlags ` + - A-MPDU Status Flags + * - :class:`Radiotap_VHTKnown ` + - VHT Known Flags + * - :class:`Radiotap_VHTFlags ` + - VHT Flags + * - :class:`Radiotap_VHTCoding ` + - VHT Coding Flags + * - :class:`Radiotap_TimestampFlags ` + - Timestamp Flags + * - :class:`Radiotap_HEMUOtherUserKnown ` + - HE-MU-other-user Known Flags + * - :class:`Radiotap_LSIGData1 ` + - L-SIG Data1 Flags + * - :class:`Radiotap_S1GKnown ` + - S1G Known Flags + * - :class:`Radiotap_EHTKnown ` + - EHT Known Flags + +.. versionadded:: 1.6.0 + +Field Types +=========== + +.. module:: pcapkit.const.radiotap.field_type + +This module contains the constant enumeration for **Radiotap Field Types**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.field_type.FieldType`. + +.. autoclass:: pcapkit.const.radiotap.field_type.FieldType + :members: + :undoc-members: + :show-inheritance: + +Flags +===== + +.. module:: pcapkit.const.radiotap.flags + +This module contains the constant enumeration for **Radiotap Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.flags.Flags`. + +.. autoclass:: pcapkit.const.radiotap.flags.Flags + :members: + :undoc-members: + :show-inheritance: + +Channel Flags +============= + +.. module:: pcapkit.const.radiotap.channel_flags + +This module contains the constant enumeration for **Radiotap Channel Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.channel_flags.ChannelFlags`. + +.. autoclass:: pcapkit.const.radiotap.channel_flags.ChannelFlags + :members: + :undoc-members: + :show-inheritance: + +RX Flags +======== + +.. module:: pcapkit.const.radiotap.rx_flags + +This module contains the constant enumeration for **Radiotap RX Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.rx_flags.RXFlags`. + +.. autoclass:: pcapkit.const.radiotap.rx_flags.RXFlags + :members: + :undoc-members: + :show-inheritance: + +TX Flags +======== + +.. module:: pcapkit.const.radiotap.tx_flags + +This module contains the constant enumeration for **Radiotap TX Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.tx_flags.TXFlags`. + +.. autoclass:: pcapkit.const.radiotap.tx_flags.TXFlags + :members: + :undoc-members: + :show-inheritance: + +MCS Known Flags +=============== + +.. module:: pcapkit.const.radiotap.mcs_known + +This module contains the constant enumeration for **Radiotap MCS Known Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.mcs_known.MCSKnown`. + +.. autoclass:: pcapkit.const.radiotap.mcs_known.MCSKnown + :members: + :undoc-members: + :show-inheritance: + +A-MPDU Status Flags +=================== + +.. module:: pcapkit.const.radiotap.ampdu_flags + +This module contains the constant enumeration for **Radiotap A-MPDU Status Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.ampdu_flags.AMPDUFlags`. + +.. autoclass:: pcapkit.const.radiotap.ampdu_flags.AMPDUFlags + :members: + :undoc-members: + :show-inheritance: + +VHT Known Flags +=============== + +.. module:: pcapkit.const.radiotap.vht_known + +This module contains the constant enumeration for **Radiotap VHT Known Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.vht_known.VHTKnown`. + +.. autoclass:: pcapkit.const.radiotap.vht_known.VHTKnown + :members: + :undoc-members: + :show-inheritance: + +VHT Flags +========= + +.. module:: pcapkit.const.radiotap.vht_flags + +This module contains the constant enumeration for **Radiotap VHT Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.vht_flags.VHTFlags`. + +.. autoclass:: pcapkit.const.radiotap.vht_flags.VHTFlags + :members: + :undoc-members: + :show-inheritance: + +VHT Coding Flags +================ + +.. module:: pcapkit.const.radiotap.vht_coding + +This module contains the constant enumeration for **Radiotap VHT Coding Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.vht_coding.VHTCoding`. + +.. autoclass:: pcapkit.const.radiotap.vht_coding.VHTCoding + :members: + :undoc-members: + :show-inheritance: + +Timestamp Flags +=============== + +.. module:: pcapkit.const.radiotap.timestamp_flags + +This module contains the constant enumeration for **Radiotap Timestamp Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.timestamp_flags.TimestampFlags`. + +.. autoclass:: pcapkit.const.radiotap.timestamp_flags.TimestampFlags + :members: + :undoc-members: + :show-inheritance: + +HE-MU-other-user Known Flags +============================ + +.. module:: pcapkit.const.radiotap.he_mu_other_user_known + +This module contains the constant enumeration for **Radiotap HE-MU-other-user Known Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.he_mu_other_user_known.HEMUOtherUserKnown`. + +.. autoclass:: pcapkit.const.radiotap.he_mu_other_user_known.HEMUOtherUserKnown + :members: + :undoc-members: + :show-inheritance: + +L-SIG Data1 Flags +================= + +.. module:: pcapkit.const.radiotap.lsig_data1 + +This module contains the constant enumeration for **Radiotap L-SIG Data1 Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.lsig_data1.LSIGData1`. + +.. autoclass:: pcapkit.const.radiotap.lsig_data1.LSIGData1 + :members: + :undoc-members: + :show-inheritance: + +S1G Known Flags +=============== + +.. module:: pcapkit.const.radiotap.s1g_known + +This module contains the constant enumeration for **Radiotap S1G Known Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.s1g_known.S1GKnown`. + +.. autoclass:: pcapkit.const.radiotap.s1g_known.S1GKnown + :members: + :undoc-members: + :show-inheritance: + +EHT Known Flags +=============== + +.. module:: pcapkit.const.radiotap.eht_known + +This module contains the constant enumeration for **Radiotap EHT Known Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.eht_known.EHTKnown`. + +.. autoclass:: pcapkit.const.radiotap.eht_known.EHTKnown + :members: + :undoc-members: + :show-inheritance: + +.. rubric:: Footnotes + +.. [*] https://www.radiotap.org/fields/defined, its unofficial-fields + page and each field's own page. diff --git a/docs/source/pcapkit/foundation/registry.rst b/docs/source/pcapkit/foundation/registry.rst index 2c7df9bf6c..c5a2f9e506 100644 --- a/docs/source/pcapkit/foundation/registry.rst +++ b/docs/source/pcapkit/foundation/registry.rst @@ -115,6 +115,8 @@ Link Layer Registries .. autofunction:: pcapkit.foundation.registry.protocols.link.register_radiotap +.. autofunction:: pcapkit.foundation.registry.protocols.link.register_radiotap_field + Internet Layer Registries ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/pcapkit/protocols/link/ieee802_11.rst b/docs/source/pcapkit/protocols/link/ieee802_11.rst index 5ac7d83ff4..eee2ef9820 100644 --- a/docs/source/pcapkit/protocols/link/ieee802_11.rst +++ b/docs/source/pcapkit/protocols/link/ieee802_11.rst @@ -44,7 +44,8 @@ Scope * **The FCS** (§9.2.4.8), where one was captured, stays at the end of the body: this class does not decide whether a capture carries one, which behind radiotap is a Flags bit - :class:`~pcapkit.protocols.link.radiotap.Radiotap` does not decode. + :class:`~pcapkit.protocols.link.radiotap.Radiotap` decodes but does not + pass on. * **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 diff --git a/docs/source/pcapkit/protocols/link/radiotap.rst b/docs/source/pcapkit/protocols/link/radiotap.rst index 368e49d322..bfeac758e3 100644 --- a/docs/source/pcapkit/protocols/link/radiotap.rst +++ b/docs/source/pcapkit/protocols/link/radiotap.rst @@ -33,18 +33,16 @@ bounds the whole of it; the 802.11 MAC frame starts at that offset. Scope ----- -Decoding every optional field radiotap.org defines is tracked on -:issue:`2576`. This class: +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 - many words it has - (:attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.present`), without - decoding what any bit selects. -* **Skips, rather than decodes,** the optional-field region those bits - 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`. + ``it_len`` -- and walks the present-flags chain, recording every word as + :attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.present`. +* **Keeps** the optional-field region those bits select whole, as + :attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.fields`, which is + what a rebuild from the data model writes, and **decodes** it as + :attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.decoded`, by the + rules below. * **Hands** everything from ``it_len`` on, the 802.11 MAC frame, to :class:`~pcapkit.protocols.link.ieee802_11.IEEE802_11` (:class:`~pcapkit.protocols.misc.no_payload.NoPayload` when nothing follows). @@ -55,6 +53,54 @@ Decoding every optional field radiotap.org defines is tracked on :func:`~pcapkit.foundation.registry.protocols.link.register_radiotap` replaces the entry. +Field Decoding +-------------- + +The bits are walked in order, word by word, and the fields they select follow +one another in the same order, each aligned to its own boundary counted from +the start of the header. A field type is read and made by the methods +:attr:`Radiotap.__field__ ` +names for it, through the schema the +:class:`~pcapkit.protocols.schema.link.radiotap.RadiotapField` registry holds +for it: the schema's fields are the subfields of the type's page on +radiotap.org, their total is its size, and its ``__align__`` its alignment, +which match the tables of the Linux kernel, Wireshark and radiotap.org's own +``radiotap-library`` wherever they size it. A page that names no alignment +takes that of its subfields, single octets, but for FHSS, which those three +align to 2. The fields are radiotap.org's defined ones, and RTS retries and data +retries, bits 16 and 17, from its unofficially used ones, which those three +size alike; OpenBSD writes a 2-octet RSSI field at bit 16 instead, which is not +read. A bitmap radiotap.org defines bit by bit is a member of its flag registry +under :mod:`pcapkit.const.radiotap`, which keeps the bits it does not name. A +field type registered through +:func:`~pcapkit.foundation.registry.protocols.link.register_radiotap_field` is +decoded the same way. + +* **Namespaces.** Bits 29 and 30 mean the same in every word. Bit 29, the + Radiotap Namespace field, carries nothing, and the next word restarts the + radiotap namespace at bit 0. Bit 30, the Vendor Namespace field, carries an + OUI, a sub-namespace and a ``skip_length``; the words up to the next + namespace field select vendor fields, whose data is the ``skip_length`` + octets after it, kept whole. Without either, the next word continues the + namespace, each bit numbered 32 past the same bit of the word before. +* **TLVs.** Bit 28 makes the rest of the region a list of type-length-value + items. An item's data is decoded where its type has a schema whose size it + matches, and kept raw otherwise; a vendor item is split into its header and + raw data. +* **What is not decoded.** A radiotap-namespace bit no field is defined for -- + 18, FreeBSD's XChannel, which radiotap.org lists as unofficial, and every one + numbered 32 or more, the TLV-only types included -- or a field that runs + past the region, ends the walk, since nothing after it can be located: an + :class:`~pcapkit.protocols.data.link.radiotap.Unknown` entry keeps every + octet from there on, and its ``reason`` says which of the two it was. + +Each bit with data in the radiotap namespace, and each namespace field, has +one entry in :attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.decoded`, +keyed by its :class:`~pcapkit.const.radiotap.field_type.FieldType`; the +subfields keep radiotap.org's names. +:meth:`~pcapkit.protocols.link.radiotap.Radiotap.make` takes the same entries +as ``fields`` and encodes them with zero padding. + .. autoclass:: pcapkit.protocols.link.radiotap.Radiotap :no-members: :show-inheritance: @@ -68,17 +114,87 @@ Decoding every optional field radiotap.org defines is tracked on .. automethod:: read .. automethod:: make .. automethod:: register + .. automethod:: register_field .. automethod:: __length_hint__ .. automethod:: __index__ .. automethod:: _make_data + .. automethod:: _read_radiotap_fields + .. automethod:: _make_radiotap_fields + + .. automethod:: _read_field_unknown + .. automethod:: _read_field_tsft + .. automethod:: _read_field_flags + .. automethod:: _read_field_rate + .. automethod:: _read_field_channel + .. automethod:: _read_field_fhss + .. automethod:: _read_field_antenna_signal + .. automethod:: _read_field_antenna_noise + .. automethod:: _read_field_lock_quality + .. automethod:: _read_field_tx_attenuation + .. automethod:: _read_field_db_tx_attenuation + .. automethod:: _read_field_dbm_tx_power + .. automethod:: _read_field_antenna + .. automethod:: _read_field_db_antenna_signal + .. automethod:: _read_field_db_antenna_noise + .. automethod:: _read_field_rx_flags + .. automethod:: _read_field_tx_flags + .. automethod:: _read_field_rts_retries + .. automethod:: _read_field_data_retries + .. automethod:: _read_field_mcs + .. automethod:: _read_field_ampdu_status + .. automethod:: _read_field_vht + .. automethod:: _read_field_timestamp + .. automethod:: _read_field_he + .. automethod:: _read_field_he_mu + .. automethod:: _read_field_he_mu_other_user + .. automethod:: _read_field_zero_length_psdu + .. automethod:: _read_field_lsig + .. automethod:: _read_field_s1g + .. automethod:: _read_field_usig + .. automethod:: _read_field_eht + + .. automethod:: _make_field_unknown + .. automethod:: _make_field_tsft + .. automethod:: _make_field_flags + .. automethod:: _make_field_rate + .. automethod:: _make_field_channel + .. automethod:: _make_field_fhss + .. automethod:: _make_field_antenna_signal + .. automethod:: _make_field_antenna_noise + .. automethod:: _make_field_lock_quality + .. automethod:: _make_field_tx_attenuation + .. automethod:: _make_field_db_tx_attenuation + .. automethod:: _make_field_dbm_tx_power + .. automethod:: _make_field_antenna + .. automethod:: _make_field_db_antenna_signal + .. automethod:: _make_field_db_antenna_noise + .. automethod:: _make_field_rx_flags + .. automethod:: _make_field_tx_flags + .. automethod:: _make_field_rts_retries + .. automethod:: _make_field_data_retries + .. automethod:: _make_field_mcs + .. automethod:: _make_field_ampdu_status + .. automethod:: _make_field_vht + .. automethod:: _make_field_timestamp + .. automethod:: _make_field_he + .. automethod:: _make_field_he_mu + .. automethod:: _make_field_he_mu_other_user + .. automethod:: _make_field_zero_length_psdu + .. automethod:: _make_field_lsig + .. automethod:: _make_field_s1g + .. automethod:: _make_field_usig + .. automethod:: _make_field_eht + .. automethod:: _get_payload .. autoattribute:: __proto__ :no-value: .. autoattribute:: __proto_key__ :no-value: + .. autoattribute:: __field__ + :no-value: Header Schemas -------------- @@ -89,6 +205,148 @@ Header Schemas :members: :show-inheritance: +.. autoclass:: pcapkit.protocols.schema.link.radiotap.RadiotapField + :members: + :show-inheritance: + + .. autoattribute:: __align__ + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.Unknown + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.TSFT + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.Flags + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.Rate + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.Channel + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.FHSS + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.AntennaSignal + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.AntennaNoise + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.LockQuality + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.TXAttenuation + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.DBTXAttenuation + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.DBmTXPower + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.Antenna + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.DBAntennaSignal + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.DBAntennaNoise + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.RXFlags + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.TXFlags + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.RTSRetries + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.DataRetries + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.MCS + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.AMPDUStatus + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.VHT + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.Timestamp + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.HE + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.HEMU + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.HEMUOtherUser + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.ZeroLengthPSDU + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.LSIG + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.VendorNamespace + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.S1G + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.USIG + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.EHT + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.TLV + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.schema.link.radiotap.VendorTLV + :members: + :show-inheritance: + Data Models ----------- @@ -98,8 +356,158 @@ Data Models :members: :show-inheritance: +.. autoclass:: pcapkit.protocols.data.link.radiotap.RadiotapField + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.Unknown + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.TSFT + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.Flags + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.Rate + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.Channel + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.FHSS + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.AntennaSignal + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.AntennaNoise + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.LockQuality + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.TXAttenuation + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.DBTXAttenuation + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.DBmTXPower + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.Antenna + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.DBAntennaSignal + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.DBAntennaNoise + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.RXFlags + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.TXFlags + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.RTSRetries + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.DataRetries + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.MCS + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.AMPDUStatus + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.VHT + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.Timestamp + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.HE + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.HEMU + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.HEMUOtherUser + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.ZeroLengthPSDU + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.LSIG + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.TLVFields + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.RadiotapNamespace + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.VendorNamespace + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.S1G + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.USIG + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.EHT + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.TLV + :members: + :show-inheritance: + +.. autoclass:: pcapkit.protocols.data.link.radiotap.VendorTLV + :members: + :show-inheritance: + .. rubric:: Footnotes -.. [*] ; the Linux kernel's +.. [*] , its field pages and its + ``radiotap-library``; the Linux kernel's ``include/net/ieee80211_radiotap.h`` and ``net/wireless/radiotap.c``; and - Wireshark's ``packet-ieee80211-radiotap.c``. + Wireshark's ``packet-ieee80211-radiotap.c`` and + ``packet-ieee80211-radiotap-iter.c``. diff --git a/docs/source/pcapkit/vendor/index.rst b/docs/source/pcapkit/vendor/index.rst index 2e2e576d1d..05ca07ba3f 100644 --- a/docs/source/pcapkit/vendor/index.rst +++ b/docs/source/pcapkit/vendor/index.rst @@ -47,6 +47,7 @@ Link Layer ieee802_11 l2tp linux + radiotap vlan Internet Layer diff --git a/docs/source/pcapkit/vendor/radiotap.rst b/docs/source/pcapkit/vendor/radiotap.rst new file mode 100644 index 0000000000..688c0420e3 --- /dev/null +++ b/docs/source/pcapkit/vendor/radiotap.rst @@ -0,0 +1,250 @@ +====================================================================== +:class:`~pcapkit.protocols.link.radiotap.Radiotap` Vendor Crawlers +====================================================================== + +.. module:: pcapkit.vendor.radiotap + +This module contains all vendor crawlers of +:class:`~pcapkit.protocols.link.radiotap.Radiotap` implementations, each scraping +radiotap.org [*]_. Available vendor crawlers include: + +.. list-table:: + + * - :class:`Radiotap_FieldType ` + - Field Types + * - :class:`Radiotap_Flags ` + - Flags + * - :class:`Radiotap_ChannelFlags ` + - Channel Flags + * - :class:`Radiotap_RXFlags ` + - RX Flags + * - :class:`Radiotap_TXFlags ` + - TX Flags + * - :class:`Radiotap_MCSKnown ` + - MCS Known Flags + * - :class:`Radiotap_AMPDUFlags ` + - A-MPDU Status Flags + * - :class:`Radiotap_VHTKnown ` + - VHT Known Flags + * - :class:`Radiotap_VHTFlags ` + - VHT Flags + * - :class:`Radiotap_VHTCoding ` + - VHT Coding Flags + * - :class:`Radiotap_TimestampFlags ` + - Timestamp Flags + * - :class:`Radiotap_HEMUOtherUserKnown ` + - HE-MU-other-user Known Flags + * - :class:`Radiotap_LSIGData1 ` + - L-SIG Data1 Flags + * - :class:`Radiotap_S1GKnown ` + - S1G Known Flags + * - :class:`Radiotap_EHTKnown ` + - EHT Known Flags + +.. versionadded:: 1.6.0 + +Field Types +=========== + +.. module:: pcapkit.vendor.radiotap.field_type + +This module contains the vendor crawler for **Radiotap Field Types**, +which is automatically generating :class:`pcapkit.const.radiotap.field_type.FieldType`. + +The registry is radiotap.org's *Defined Fields* table, scraped from +:attr:`~pcapkit.vendor.radiotap.field_type.FieldType.LINK`, and RTS retries and data +retries from its *Unofficially Used Fields* table, scraped from +:data:`~pcapkit.vendor.radiotap.field_type.UNOFFICIAL_LINK`. A bit number is also a +TLV type, so the TLV-only fields from 32 on are in it too. The tables name no +reserved value: ``_missing_`` resolves bits 29, 30 and 31 of every extended +presence word to ``Reserved``, as radiotap.org's introduction reserves them, and +every other value to ``Unassigned``. + +.. autoclass:: pcapkit.vendor.radiotap.field_type.FieldType + :members: FLAG, LINK + :show-inheritance: + +.. autodata:: pcapkit.vendor.radiotap.field_type.UNOFFICIAL_LINK + +.. autodata:: pcapkit.vendor.radiotap.field_type.UNOFFICIAL + +Flags +===== + +.. module:: pcapkit.vendor.radiotap.flags + +This module contains the vendor crawler for **Radiotap Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.flags.Flags`. + +Each flag crawler scrapes the table on its field's page, and subclasses this one. +A row whose mask sets one bit is a member; a row that sets more bits, or that +radiotap.org marks reserved or unused, is not, and its bits stay undefined. A +member's name is the macro the crawler's ``NAMES`` gives its bit, less the +``IEEE80211_RADIOTAP_`` or ``IEEE80211_`` prefix: the Linux kernel's, from +``include/net/ieee80211_radiotap.h``, or Wireshark's where Linux names none. +Neither names the HE-MU-other-user bits, which take radiotap.org's wording. + +.. autoclass:: pcapkit.vendor.radiotap.flags.Flags + :members: FLAG, LINK, SUBFIELD, NAMES + :show-inheritance: + +Channel Flags +============= + +.. module:: pcapkit.vendor.radiotap.channel_flags + +This module contains the vendor crawler for **Radiotap Channel Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.channel_flags.ChannelFlags`. + +.. autoclass:: pcapkit.vendor.radiotap.channel_flags.ChannelFlags + :members: FLAG, LINK, SUBFIELD, NAMES + :show-inheritance: + +RX Flags +======== + +.. module:: pcapkit.vendor.radiotap.rx_flags + +This module contains the vendor crawler for **Radiotap RX Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.rx_flags.RXFlags`. + +.. autoclass:: pcapkit.vendor.radiotap.rx_flags.RXFlags + :members: FLAG, LINK, SUBFIELD, NAMES + :show-inheritance: + +TX Flags +======== + +.. module:: pcapkit.vendor.radiotap.tx_flags + +This module contains the vendor crawler for **Radiotap TX Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.tx_flags.TXFlags`. + +.. autoclass:: pcapkit.vendor.radiotap.tx_flags.TXFlags + :members: FLAG, LINK, SUBFIELD, NAMES + :show-inheritance: + +MCS Known Flags +=============== + +.. module:: pcapkit.vendor.radiotap.mcs_known + +This module contains the vendor crawler for **Radiotap MCS Known Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.mcs_known.MCSKnown`. + +.. autoclass:: pcapkit.vendor.radiotap.mcs_known.MCSKnown + :members: FLAG, LINK, SUBFIELD, NAMES + :show-inheritance: + +A-MPDU Status Flags +=================== + +.. module:: pcapkit.vendor.radiotap.ampdu_flags + +This module contains the vendor crawler for **Radiotap A-MPDU Status Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.ampdu_flags.AMPDUFlags`. + +.. autoclass:: pcapkit.vendor.radiotap.ampdu_flags.AMPDUFlags + :members: FLAG, LINK, SUBFIELD, NAMES + :show-inheritance: + +VHT Known Flags +=============== + +.. module:: pcapkit.vendor.radiotap.vht_known + +This module contains the vendor crawler for **Radiotap VHT Known Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.vht_known.VHTKnown`. + +.. autoclass:: pcapkit.vendor.radiotap.vht_known.VHTKnown + :members: FLAG, LINK, SUBFIELD, NAMES + :show-inheritance: + +VHT Flags +========= + +.. module:: pcapkit.vendor.radiotap.vht_flags + +This module contains the vendor crawler for **Radiotap VHT Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.vht_flags.VHTFlags`. + +.. autoclass:: pcapkit.vendor.radiotap.vht_flags.VHTFlags + :members: FLAG, LINK, SUBFIELD, NAMES + :show-inheritance: + +VHT Coding Flags +================ + +.. module:: pcapkit.vendor.radiotap.vht_coding + +This module contains the vendor crawler for **Radiotap VHT Coding Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.vht_coding.VHTCoding`. + +.. autoclass:: pcapkit.vendor.radiotap.vht_coding.VHTCoding + :members: FLAG, LINK, SUBFIELD, NAMES + :show-inheritance: + +Timestamp Flags +=============== + +.. module:: pcapkit.vendor.radiotap.timestamp_flags + +This module contains the vendor crawler for **Radiotap Timestamp Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.timestamp_flags.TimestampFlags`. + +.. autoclass:: pcapkit.vendor.radiotap.timestamp_flags.TimestampFlags + :members: FLAG, LINK, SUBFIELD, NAMES + :show-inheritance: + +HE-MU-other-user Known Flags +============================ + +.. module:: pcapkit.vendor.radiotap.he_mu_other_user_known + +This module contains the vendor crawler for **Radiotap HE-MU-other-user Known Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.he_mu_other_user_known.HEMUOtherUserKnown`. + +.. autoclass:: pcapkit.vendor.radiotap.he_mu_other_user_known.HEMUOtherUserKnown + :members: FLAG, LINK, SUBFIELD, NAMES + :show-inheritance: + +L-SIG Data1 Flags +================= + +.. module:: pcapkit.vendor.radiotap.lsig_data1 + +This module contains the vendor crawler for **Radiotap L-SIG Data1 Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.lsig_data1.LSIGData1`. + +.. autoclass:: pcapkit.vendor.radiotap.lsig_data1.LSIGData1 + :members: FLAG, LINK, SUBFIELD, NAMES + :show-inheritance: + +S1G Known Flags +=============== + +.. module:: pcapkit.vendor.radiotap.s1g_known + +This module contains the vendor crawler for **Radiotap S1G Known Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.s1g_known.S1GKnown`. + +.. autoclass:: pcapkit.vendor.radiotap.s1g_known.S1GKnown + :members: FLAG, LINK, SUBFIELD, NAMES + :show-inheritance: + +EHT Known Flags +=============== + +.. module:: pcapkit.vendor.radiotap.eht_known + +This module contains the vendor crawler for **Radiotap EHT Known Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.eht_known.EHTKnown`. + +.. autoclass:: pcapkit.vendor.radiotap.eht_known.EHTKnown + :members: FLAG, LINK, SUBFIELD, NAMES + :show-inheritance: + +.. rubric:: Footnotes + +.. [*] https://www.radiotap.org/fields/defined, its unofficial-fields + page and each field's own page. diff --git a/examples/generators/option_families/radiotap.py b/examples/generators/option_families/radiotap.py new file mode 100644 index 0000000000..a5187f3753 --- /dev/null +++ b/examples/generators/option_families/radiotap.py @@ -0,0 +1,106 @@ +# -*- coding: utf-8 -*- +"""The ``radiotap-field`` family: the fields of a radiotap header. + +Each case is one field, built from keyword arguments by the field's +``_make_field_*``: a presence bit selects a field of the radiotap namespace, +and a TLV item carries a type from 32 on, which only a TLV carries. The +rebuild is from what the parse decoded. No capture is written, as no +envelope here carries a radiotap header. + +A family module of :file:`examples/generators/options.py`, which loads it by +path and binds ``generator`` to itself before this body runs (#2615). + +""" +# Deferring these is the design, as in options.py -- see its module docstring. +# pylint: disable=import-outside-toplevel + +from __future__ import annotations + +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from typing import Any + +#: :file:`examples/generators/options.py`, which its loader binds here +#: before this body runs. +generator = globals()['generator'] # type: Any + + +def _radiotap_field_registry() -> 'Any': + from pcapkit.protocols.link.radiotap import Radiotap + return Radiotap.__field__ + + +def _radiotap_field_overrides() -> 'dict[Any, dict[str, Any]]': + from pcapkit.const.radiotap.field_type import FieldType as Enum_FieldType + + # Every subfield is given, as no field defaults one. + return { + Enum_FieldType.TSFT: {'mactime': 0x0102030405060708}, + Enum_FieldType.Flags: {'flags': 0x10}, + Enum_FieldType.Rate: {'rate': 2}, + Enum_FieldType.Channel: {'frequency': 2412, 'flags': 0x00A0}, + Enum_FieldType.FHSS: {'hop_set': 1, 'hop_pattern': 2}, + Enum_FieldType.Antenna_signal: {'signal': -40}, + Enum_FieldType.Antenna_noise: {'noise': -90}, + Enum_FieldType.Lock_quality: {'quality': 3}, + Enum_FieldType.TX_attenuation: {'attenuation': 4}, + Enum_FieldType.dB_TX_attenuation: {'attenuation': 5}, + Enum_FieldType.dBm_TX_power: {'power': -6}, + Enum_FieldType.Antenna: {'antenna': 1}, + Enum_FieldType.dB_antenna_signal: {'signal': 50}, + Enum_FieldType.dB_antenna_noise: {'noise': 20}, + Enum_FieldType.RX_flags: {'flags': 0x0002}, + Enum_FieldType.TX_flags: {'flags': 0x0008}, + Enum_FieldType.RTS_retries: {'retries': 3}, + Enum_FieldType.data_retries: {'retries': 1}, + Enum_FieldType.MCS: {'known': 0x27, 'flags': 0x25, 'mcs': 7}, + Enum_FieldType.A_MPDU_status: {'reference': 7, 'flags': 0x0105, 'delimiter_crc': 0xAB, 'reserved': 0}, + Enum_FieldType.VHT: {'known': 0x0244, 'flags': 0x05, 'bandwidth': 4, 'mcs_nss': (0x91, 0, 0, 0), + 'coding': 0x01, 'group_id': 2, 'partial_aid': 0x1234}, + Enum_FieldType.timestamp: {'timestamp': 1, 'accuracy': 2, 'unit_position': 0x11, 'flags': 0x02}, + Enum_FieldType.HE: {'data1': 1, 'data2': 2, 'data3': 3, 'data4': 4, 'data5': 5, 'data6': 6}, + Enum_FieldType.HE_MU: {'flags1': 1, 'flags2': 2, 'ru_channel1': (1, 2, 3, 4), 'ru_channel2': (5, 6, 7, 8)}, + Enum_FieldType.HE_MU_other_user: {'per_user_1': 1, 'per_user_2': 2, 'per_user_position': 3, + 'per_user_known': 0x23}, + Enum_FieldType.FieldType_0_length_PSDU: {'psdu_type': 1}, + Enum_FieldType.L_SIG: {'data1': 0x0007, 'data2': 0x1234}, + Enum_FieldType.S1G: {'known': 0x0103, 'data1': 2, 'data2': 3}, + Enum_FieldType.U_SIG: {'common': 0x11, 'value': 0x22, 'mask': 0x33}, + Enum_FieldType.EHT: {'known': 3, 'data': tuple(range(9)), 'user_info': (0xA1, 0xA2)}, + } + + +def _radiotap_field_build(code: 'Any', kwargs: 'dict[str, Any]') -> 'Any': + from pcapkit.const.radiotap.field_type import FieldType as Enum_FieldType + from pcapkit.protocols.link.radiotap import Radiotap + + if code < Enum_FieldType.TLV_fields_in_radiotap: + return Radiotap(present=(1 << code,), fields=[(code, dict(kwargs))]) + tlv = Enum_FieldType.TLV_fields_in_radiotap + return Radiotap(present=(1 << tlv,), fields=[(tlv, {'tlvs': [{'type': code, 'data': dict(kwargs)}]})]) + + +def _radiotap_parse(octets: 'bytes') -> 'Any': + from pcapkit.protocols.link.radiotap import Radiotap + return Radiotap(octets, len(octets)) + + +def _radiotap_field_extract(parsed: 'Any') -> 'Any': + return parsed.info.present, parsed.info.decoded + + +def _radiotap_field_rebuild(collection: 'Any') -> 'Any': + from pcapkit.protocols.link.radiotap import Radiotap + + present, decoded = collection + return Radiotap(present=present, fields=decoded) + + +#: The families this module adds. +FAMILIES = ( + # No capture -- see the module docstring. + generator.Family('radiotap-field', _radiotap_field_registry, _radiotap_field_overrides, + _radiotap_field_build, _radiotap_parse, _radiotap_field_extract, + _radiotap_field_rebuild, capture=None, envelope=None), +) diff --git a/pcapkit/all.py b/pcapkit/all.py index 50866422cb..653d48c8c8 100644 --- a/pcapkit/all.py +++ b/pcapkit/all.py @@ -97,6 +97,7 @@ 'register_ethertype', 'register_loopback', 'register_arphrd', 'register_frad', 'register_netlink', 'register_radiotap', + 'register_radiotap_field', 'register_transtype', 'register_ipx', 'register_icmp_type', diff --git a/pcapkit/const/__init__.py b/pcapkit/const/__init__.py index 78ff490ec6..2ef92b6b5c 100644 --- a/pcapkit/const/__init__.py +++ b/pcapkit/const/__init__.py @@ -33,6 +33,7 @@ from pcapkit.const.mh import * from pcapkit.const.ngap import * from pcapkit.const.ospf import * +from pcapkit.const.radiotap import * from pcapkit.const.sctp import * from pcapkit.const.sslv2 import * from pcapkit.const.tcp import * @@ -100,6 +101,11 @@ 'NGAP_ProcedureCode', 'NGAP_ProtocolIE', # OSPF 'OSPF_Authentication', 'OSPF_Packet', + # Radiotap + 'Radiotap_FieldType', 'Radiotap_Flags', 'Radiotap_ChannelFlags', 'Radiotap_RXFlags', + 'Radiotap_TXFlags', 'Radiotap_MCSKnown', 'Radiotap_AMPDUFlags', 'Radiotap_VHTKnown', + 'Radiotap_VHTFlags', 'Radiotap_VHTCoding', 'Radiotap_TimestampFlags', + 'Radiotap_HEMUOtherUserKnown', 'Radiotap_LSIGData1', 'Radiotap_S1GKnown', 'Radiotap_EHTKnown', # SCTP 'SCTP_Chunk', 'SCTP_Parameter', 'SCTP_CauseCode', 'SCTP_PayloadProtocolIdentifier', # SSLv2 diff --git a/pcapkit/const/radiotap/__init__.py b/pcapkit/const/radiotap/__init__.py new file mode 100644 index 0000000000..62bd506eb7 --- /dev/null +++ b/pcapkit/const/radiotap/__init__.py @@ -0,0 +1,69 @@ +# -*- coding: utf-8 -*- +# pylint: disable=unused-import +""":class:`~pcapkit.protocols.link.radiotap.Radiotap` Constant Enumerations +============================================================================== + +.. module:: pcapkit.const.radiotap + +This module contains all constant enumerations of +:class:`~pcapkit.protocols.link.radiotap.Radiotap` implementations. Available +enumerations include: + +.. list-table:: + + * - :class:`Radiotap_FieldType ` + - Field Types + * - :class:`Radiotap_Flags ` + - Flags + * - :class:`Radiotap_ChannelFlags ` + - Channel Flags + * - :class:`Radiotap_RXFlags ` + - RX Flags + * - :class:`Radiotap_TXFlags ` + - TX Flags + * - :class:`Radiotap_MCSKnown ` + - MCS Known Flags + * - :class:`Radiotap_AMPDUFlags ` + - A-MPDU Status Flags + * - :class:`Radiotap_VHTKnown ` + - VHT Known Flags + * - :class:`Radiotap_VHTFlags ` + - VHT Flags + * - :class:`Radiotap_VHTCoding ` + - VHT Coding Flags + * - :class:`Radiotap_TimestampFlags ` + - Timestamp Flags + * - :class:`Radiotap_HEMUOtherUserKnown ` + - HE-MU-other-user Known Flags + * - :class:`Radiotap_LSIGData1 ` + - L-SIG Data1 Flags + * - :class:`Radiotap_S1GKnown ` + - S1G Known Flags + * - :class:`Radiotap_EHTKnown ` + - EHT Known Flags + +""" + +from pcapkit.const.radiotap.ampdu_flags import AMPDUFlags as Radiotap_AMPDUFlags +from pcapkit.const.radiotap.channel_flags import ChannelFlags as Radiotap_ChannelFlags +from pcapkit.const.radiotap.eht_known import EHTKnown as Radiotap_EHTKnown +from pcapkit.const.radiotap.field_type import FieldType as Radiotap_FieldType +from pcapkit.const.radiotap.flags import Flags as Radiotap_Flags +from pcapkit.const.radiotap.he_mu_other_user_known import \ + HEMUOtherUserKnown as Radiotap_HEMUOtherUserKnown +from pcapkit.const.radiotap.lsig_data1 import LSIGData1 as Radiotap_LSIGData1 +from pcapkit.const.radiotap.mcs_known import MCSKnown as Radiotap_MCSKnown +from pcapkit.const.radiotap.rx_flags import RXFlags as Radiotap_RXFlags +from pcapkit.const.radiotap.s1g_known import S1GKnown as Radiotap_S1GKnown +from pcapkit.const.radiotap.timestamp_flags import TimestampFlags as Radiotap_TimestampFlags +from pcapkit.const.radiotap.tx_flags import TXFlags as Radiotap_TXFlags +from pcapkit.const.radiotap.vht_coding import VHTCoding as Radiotap_VHTCoding +from pcapkit.const.radiotap.vht_flags import VHTFlags as Radiotap_VHTFlags +from pcapkit.const.radiotap.vht_known import VHTKnown as Radiotap_VHTKnown + +__all__ = [ + 'Radiotap_FieldType', 'Radiotap_Flags', 'Radiotap_ChannelFlags', 'Radiotap_RXFlags', + 'Radiotap_TXFlags', 'Radiotap_MCSKnown', 'Radiotap_AMPDUFlags', 'Radiotap_VHTKnown', + 'Radiotap_VHTFlags', 'Radiotap_VHTCoding', 'Radiotap_TimestampFlags', + 'Radiotap_HEMUOtherUserKnown', 'Radiotap_LSIGData1', 'Radiotap_S1GKnown', 'Radiotap_EHTKnown', +] diff --git a/pcapkit/const/radiotap/ampdu_flags.py b/pcapkit/const/radiotap/ampdu_flags.py new file mode 100644 index 0000000000..27116b4123 --- /dev/null +++ b/pcapkit/const/radiotap/ampdu_flags.py @@ -0,0 +1,85 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap A-MPDU Status Flags +================================== + +.. module:: pcapkit.const.radiotap.ampdu_flags + +This module contains the constant enumeration for **Radiotap A-MPDU Status Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.ampdu_flags.AMPDUFlags`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['AMPDUFlags'] + + +class AMPDUFlags(EnumRegistry, IntFlag): + """[AMPDUFlags] Radiotap A-MPDU Status Flags""" + + #: driver reports 0-length subframes + AMPDU_REPORT_ZEROLEN = 1 << 0 + + #: frame is 0-length subframe (valid only if 0x0001 is set) + AMPDU_IS_ZEROLEN = 1 << 1 + + #: last subframe is known (should be set for all subframes in an A-MPDU) + AMPDU_LAST_KNOWN = 1 << 2 + + #: this frame is the last subframe + AMPDU_IS_LAST = 1 << 3 + + #: delimiter CRC error + AMPDU_DELIM_CRC_ERR = 1 << 4 + + #: delimiter CRC value known: the delimiter CRC value field is valid + AMPDU_DELIM_CRC_KNOWN = 1 << 5 + + #: EOF value + AMPDU_EOF = 1 << 6 + + #: EOF value known + AMPDU_EOF_KNOWN = 1 << 7 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'AMPDUFlags': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) diff --git a/pcapkit/const/radiotap/channel_flags.py b/pcapkit/const/radiotap/channel_flags.py new file mode 100644 index 0000000000..7064dbe055 --- /dev/null +++ b/pcapkit/const/radiotap/channel_flags.py @@ -0,0 +1,94 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap Channel Flags +============================ + +.. module:: pcapkit.const.radiotap.channel_flags + +This module contains the constant enumeration for **Radiotap Channel Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.channel_flags.ChannelFlags`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['ChannelFlags'] + + +class ChannelFlags(EnumRegistry, IntFlag): + """[ChannelFlags] Radiotap Channel Flags""" + + #: S1G 700MHz spectrum channel + CHAN_700MHZ = 1 << 0 + + #: S1G 800MHz spectrum channel + CHAN_800MHZ = 1 << 1 + + #: S1G 900MHz spectrum channel + CHAN_900MHZ = 1 << 2 + + #: Turbo Channel + CHAN_TURBO = 1 << 4 + + #: CCK channel + CHAN_CCK = 1 << 5 + + #: OFDM channel + CHAN_OFDM = 1 << 6 + + #: 2 GHz spectrum channel + CHAN_2GHZ = 1 << 7 + + #: 5 GHz spectrum channel + CHAN_5GHZ = 1 << 8 + + #: Only passive scan allowed + CHAN_PASSIVE = 1 << 9 + + #: Dynamic CCK-OFDM channel + CHAN_DYN = 1 << 10 + + #: GFSK channel (FHSS PHY) + CHAN_GFSK = 1 << 11 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'ChannelFlags': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) diff --git a/pcapkit/const/radiotap/eht_known.py b/pcapkit/const/radiotap/eht_known.py new file mode 100644 index 0000000000..a9de2edc41 --- /dev/null +++ b/pcapkit/const/radiotap/eht_known.py @@ -0,0 +1,124 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap EHT Known Flags +============================== + +.. module:: pcapkit.const.radiotap.eht_known + +This module contains the constant enumeration for **Radiotap EHT Known Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.eht_known.EHTKnown`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['EHTKnown'] + + +class EHTKnown(EnumRegistry, IntFlag): + """[EHTKnown] Radiotap EHT Known Flags""" + + #: Spatial Reuse Known + EHT_KNOWN_SPATIAL_REUSE = 1 << 1 + + #: GI (Guard Interval) Known + EHT_KNOWN_GI = 1 << 2 + + #: number of LTF symbols Known + EHT_KNOWN_EHT_LTF = 1 << 4 + + #: OFDMA (including TB), MU-MIMO: LDPC Extra Symbol Segment Known + EHT_KNOWN_LDPC_EXTRA_SYM_OM = 1 << 5 + + #: OFDMA (including TB), MU-MIMO: Pre-FEC Padding Factor Known + EHT_KNOWN_PRE_PADD_FACOR_OM = 1 << 6 + + #: OFDMA (including TB), MU-MIMO: PE Disambiguity Known + EHT_KNOWN_PE_DISAMBIGUITY_OM = 1 << 7 + + #: OFDMA (including TB), MU-MIMO: Disregard Known + EHT_KNOWN_DISREGARD_O = 1 << 8 + + #: EHT sounding: Disregard Known + EHT_KNOWN_DISREGARD_S = 1 << 9 + + #: CRC1 Known + EHT_KNOWN_CRC1 = 1 << 13 + + #: Tail1 Known + EHT_KNOWN_TAIL1 = 1 << 14 + + #: OFDMA (including TB): CRC2 Known + EHT_KNOWN_CRC2_O = 1 << 15 + + #: OFDMA (including TB): Tail2 Known + EHT_KNOWN_TAIL2_O = 1 << 16 + + #: EHT sounding: NSS Known + EHT_KNOWN_NSS_S = 1 << 17 + + #: EHT sounding: Beamformed Known + EHT_KNOWN_BEAMFORMED_S = 1 << 18 + + #: MU-MIMO: Number Of Non-OFDMA Users Known + EHT_KNOWN_NR_NON_OFDMA_USERS_M = 1 << 19 + + #: MU-MIMO: User Encoding Block CRC Known + EHT_KNOWN_ENCODING_BLOCK_CRC_M = 1 << 20 + + #: MU-MIMO: User Encoding Block Tail Known + EHT_KNOWN_ENCODING_BLOCK_TAIL_M = 1 << 21 + + #: OFDMA (including TB), MU-MIMO: RU/MRU Size Known + EHT_KNOWN_RU_MRU_SIZE_OM = 1 << 22 + + #: OFDMA (including TB), MU-MIMO: RU/MRU Index Known + EHT_KNOWN_RU_MRU_INDEX_OM = 1 << 23 + + #: OFDMA (including TB), MU-MIMO: RU Allocation (TB format) Known + EHT_KNOWN_RU_ALLOC_TB_FMT = 1 << 24 + + #: Primary 80 MHz Channel Position known + EHT_KNOWN_PRIMARY_80 = 1 << 25 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFFFFFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'EHTKnown': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFFFFFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) diff --git a/pcapkit/const/radiotap/field_type.py b/pcapkit/const/radiotap/field_type.py new file mode 100644 index 0000000000..db4ed17aff --- /dev/null +++ b/pcapkit/const/radiotap/field_type.py @@ -0,0 +1,165 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap Field Types +========================== + +.. module:: pcapkit.const.radiotap.field_type + +This module contains the constant enumeration for **Radiotap Field Types**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.field_type.FieldType`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntEnum + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['FieldType'] + + +class FieldType(EnumRegistry, IntEnum): + """[FieldType] Radiotap Field Types""" + + #: TSFT + TSFT = 0 + + #: Flags + Flags = 1 + + #: Rate + Rate = 2 + + #: Channel + Channel = 3 + + #: FHSS + FHSS = 4 + + #: Antenna signal + Antenna_signal = 5 + + #: Antenna noise + Antenna_noise = 6 + + #: Lock quality + Lock_quality = 7 + + #: TX attenuation + TX_attenuation = 8 + + #: dB TX attenuation + dB_TX_attenuation = 9 + + #: dBm TX power + dBm_TX_power = 10 + + #: Antenna + Antenna = 11 + + #: dB antenna signal + dB_antenna_signal = 12 + + #: dB antenna noise + dB_antenna_noise = 13 + + #: RX flags + RX_flags = 14 + + #: TX flags + TX_flags = 15 + + #: RTS retries [unofficial, generated by Linux (only libertas driver), NetBSD + #: (?)] + RTS_retries = 16 + + #: data retries [unofficial, generated by Linux (mac80211), parsed by + #: wireshark] + data_retries = 17 + + #: MCS + MCS = 19 + + #: A-MPDU status + A_MPDU_status = 20 + + #: VHT + VHT = 21 + + #: timestamp + timestamp = 22 + + #: HE + HE = 23 + + #: HE-MU + HE_MU = 24 + + #: HE-MU-other-user + HE_MU_other_user = 25 + + #: 0-length-PSDU + FieldType_0_length_PSDU = 26 + + #: L-SIG + L_SIG = 27 + + #: TLV fields in radiotap + TLV_fields_in_radiotap = 28 + + #: Radiotap Namespace + Radiotap_Namespace = 29 + + #: Vendor Namespace + Vendor_Namespace = 30 + + #: S1G + S1G = 32 + + #: U-SIG + U_SIG = 33 + + #: EHT + EHT = 34 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'FieldType': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + if value % 32 in (29, 30, 31): + #: Reserved in every presence word + return cls._unregistered_member(value, 'Reserved') + return cls._unregistered_member(value, 'Unassigned') diff --git a/pcapkit/const/radiotap/flags.py b/pcapkit/const/radiotap/flags.py new file mode 100644 index 0000000000..31b573615e --- /dev/null +++ b/pcapkit/const/radiotap/flags.py @@ -0,0 +1,85 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap Flags +==================== + +.. module:: pcapkit.const.radiotap.flags + +This module contains the constant enumeration for **Radiotap Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.flags.Flags`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['Flags'] + + +class Flags(EnumRegistry, IntFlag): + """[Flags] Radiotap Flags""" + + #: sent/received during CFP + F_CFP = 1 << 0 + + #: sent/received with short preamble + F_SHORTPRE = 1 << 1 + + #: sent/received with WEP encryption + F_WEP = 1 << 2 + + #: sent/received with fragmentation + F_FRAG = 1 << 3 + + #: frame includes FCS + F_FCS = 1 << 4 + + #: frame has padding between 802.11 header and payload (to 32-bit boundary) + F_DATAPAD = 1 << 5 + + #: frame failed FCS check + F_BADFCS = 1 << 6 + + #: frame used short guard interval (HT) [Currently unspecified but used] + F_SHORTGI = 1 << 7 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'Flags': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) diff --git a/pcapkit/const/radiotap/he_mu_other_user_known.py b/pcapkit/const/radiotap/he_mu_other_user_known.py new file mode 100644 index 0000000000..ceb873a8db --- /dev/null +++ b/pcapkit/const/radiotap/he_mu_other_user_known.py @@ -0,0 +1,85 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap HE-MU-other-user Known Flags +=========================================== + +.. module:: pcapkit.const.radiotap.he_mu_other_user_known + +This module contains the constant enumeration for **Radiotap HE-MU-other-user Known Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.he_mu_other_user_known.HEMUOtherUserKnown`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['HEMUOtherUserKnown'] + + +class HEMUOtherUserKnown(EnumRegistry, IntFlag): + """[HEMUOtherUserKnown] Radiotap HE-MU-other-user Known Flags""" + + #: user field position known + user_field_position_known = 1 << 0 + + #: STA-ID known (B0-10) + STA_ID_known = 1 << 1 + + #: NSTS known (B11-13, only for non-MU-MIMO) + NSTS_known = 1 << 2 + + #: Tx Beamforming known (B14, only for non-MU-MIMO) + Tx_Beamforming_known = 1 << 3 + + #: Spatial Configuration known (B11-B14, only for MU-MIMO) + Spatial_Configuration_known = 1 << 4 + + #: MCS known (B15-18) + MCS_known = 1 << 5 + + #: DCM known (B19) + DCM_known = 1 << 6 + + #: Coding known (B20) + Coding_known = 1 << 7 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'HEMUOtherUserKnown': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) diff --git a/pcapkit/const/radiotap/lsig_data1.py b/pcapkit/const/radiotap/lsig_data1.py new file mode 100644 index 0000000000..2ba39b8b2d --- /dev/null +++ b/pcapkit/const/radiotap/lsig_data1.py @@ -0,0 +1,67 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap L-SIG Data1 Flags +================================ + +.. module:: pcapkit.const.radiotap.lsig_data1 + +This module contains the constant enumeration for **Radiotap L-SIG Data1 Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.lsig_data1.LSIGData1`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['LSIGData1'] + + +class LSIGData1(EnumRegistry, IntFlag): + """[LSIGData1] Radiotap L-SIG Data1 Flags""" + + #: rate known + LSIG_DATA1_RATE_KNOWN = 1 << 0 + + #: length known + LSIG_DATA1_LENGTH_KNOWN = 1 << 1 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'LSIGData1': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) diff --git a/pcapkit/const/radiotap/mcs_known.py b/pcapkit/const/radiotap/mcs_known.py new file mode 100644 index 0000000000..a9e2858f82 --- /dev/null +++ b/pcapkit/const/radiotap/mcs_known.py @@ -0,0 +1,85 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap MCS Known Flags +============================== + +.. module:: pcapkit.const.radiotap.mcs_known + +This module contains the constant enumeration for **Radiotap MCS Known Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.mcs_known.MCSKnown`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['MCSKnown'] + + +class MCSKnown(EnumRegistry, IntFlag): + """[MCSKnown] Radiotap MCS Known Flags""" + + #: bandwidth + MCS_HAVE_BW = 1 << 0 + + #: MCS index known (in mcs part of the field) + MCS_HAVE_MCS = 1 << 1 + + #: guard interval + MCS_HAVE_GI = 1 << 2 + + #: HT format + MCS_HAVE_FMT = 1 << 3 + + #: FEC type + MCS_HAVE_FEC = 1 << 4 + + #: STBC known + MCS_HAVE_STBC = 1 << 5 + + #: Ness known (Number of extension spatial streams) + MCS_HAVE_NESS = 1 << 6 + + #: Ness data - bit 1 (MSB) of Number of extension spatial streams + MCS_NESS_BIT1 = 1 << 7 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'MCSKnown': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) diff --git a/pcapkit/const/radiotap/rx_flags.py b/pcapkit/const/radiotap/rx_flags.py new file mode 100644 index 0000000000..63eb71c77a --- /dev/null +++ b/pcapkit/const/radiotap/rx_flags.py @@ -0,0 +1,64 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap RX Flags +======================= + +.. module:: pcapkit.const.radiotap.rx_flags + +This module contains the constant enumeration for **Radiotap RX Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.rx_flags.RXFlags`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['RXFlags'] + + +class RXFlags(EnumRegistry, IntFlag): + """[RXFlags] Radiotap RX Flags""" + + #: PLCP CRC check failed + F_RX_BADPLCP = 1 << 1 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'RXFlags': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) diff --git a/pcapkit/const/radiotap/s1g_known.py b/pcapkit/const/radiotap/s1g_known.py new file mode 100644 index 0000000000..2bebdf3888 --- /dev/null +++ b/pcapkit/const/radiotap/s1g_known.py @@ -0,0 +1,85 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap S1G Known Flags +============================== + +.. module:: pcapkit.const.radiotap.s1g_known + +This module contains the constant enumeration for **Radiotap S1G Known Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.s1g_known.S1GKnown`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['S1GKnown'] + + +class S1GKnown(EnumRegistry, IntFlag): + """[S1GKnown] Radiotap S1G Known Flags""" + + #: S1G PPDU Format known + S1G_KNOWN_PPDU_FORMAT = 1 << 0 + + #: Response indication known + S1G_KNOWN_RESPONSE_IND = 1 << 1 + + #: Guard interval known + S1G_KNOWN_GI = 1 << 2 + + #: NSS known + S1G_KNOWN_NSS = 1 << 3 + + #: Bandwidth known + S1G_KNOWN_BW = 1 << 4 + + #: MCS known + S1G_KNOWN_MCS = 1 << 5 + + #: Color known + S1G_KNOWN_COLOR = 1 << 6 + + #: uplink indication known + S1G_KNOWN_UPLINK_IND = 1 << 7 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'S1GKnown': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) diff --git a/pcapkit/const/radiotap/timestamp_flags.py b/pcapkit/const/radiotap/timestamp_flags.py new file mode 100644 index 0000000000..f7e3a36ab9 --- /dev/null +++ b/pcapkit/const/radiotap/timestamp_flags.py @@ -0,0 +1,67 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap Timestamp Flags +============================== + +.. module:: pcapkit.const.radiotap.timestamp_flags + +This module contains the constant enumeration for **Radiotap Timestamp Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.timestamp_flags.TimestampFlags`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['TimestampFlags'] + + +class TimestampFlags(EnumRegistry, IntFlag): + """[TimestampFlags] Radiotap Timestamp Flags""" + + #: 32-bit counter (high 32 bits are unused) + TIMESTAMP_FLAG_32BIT = 1 << 0 + + #: accuracy known + TIMESTAMP_FLAG_ACCURACY = 1 << 1 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'TimestampFlags': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) diff --git a/pcapkit/const/radiotap/tx_flags.py b/pcapkit/const/radiotap/tx_flags.py new file mode 100644 index 0000000000..7e49c92bde --- /dev/null +++ b/pcapkit/const/radiotap/tx_flags.py @@ -0,0 +1,82 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap TX Flags +======================= + +.. module:: pcapkit.const.radiotap.tx_flags + +This module contains the constant enumeration for **Radiotap TX Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.tx_flags.TXFlags`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['TXFlags'] + + +class TXFlags(EnumRegistry, IntFlag): + """[TXFlags] Radiotap TX Flags""" + + #: Transmission failed due to excessive retries + F_TX_FAIL = 1 << 0 + + #: Transmission used CTS-to-self protection + F_TX_CTS = 1 << 1 + + #: Transmission used RTS/CTS handshake + F_TX_RTS = 1 << 2 + + #: Transmission shall not expect an ACK frame and not retry when no ACK is + #: received + F_TX_NOACK = 1 << 3 + + #: Transmission includes a pre-configured sequence number that should not be + #: changed by the driver’s TX handlers + F_TX_NOSEQNO = 1 << 4 + + #: Transmission should not be reordered relative to other frames that have this + #: flag set + F_TX_ORDER = 1 << 5 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'TXFlags': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) diff --git a/pcapkit/const/radiotap/vht_coding.py b/pcapkit/const/radiotap/vht_coding.py new file mode 100644 index 0000000000..ac8c04a03d --- /dev/null +++ b/pcapkit/const/radiotap/vht_coding.py @@ -0,0 +1,73 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap VHT Coding Flags +=============================== + +.. module:: pcapkit.const.radiotap.vht_coding + +This module contains the constant enumeration for **Radiotap VHT Coding Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.vht_coding.VHTCoding`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['VHTCoding'] + + +class VHTCoding(EnumRegistry, IntFlag): + """[VHTCoding] Radiotap VHT Coding Flags""" + + #: Coding for user 0 -- Set to 0 for BCC. Set to 1 for LDPC. + CODING_LDPC_USER0 = 1 << 0 + + #: Coding for user 1 -- Set to 0 for BCC. Set to 1 for LDPC. + CODING_LDPC_USER1 = 1 << 1 + + #: Coding for user 2 -- Set to 0 for BCC. Set to 1 for LDPC. + CODING_LDPC_USER2 = 1 << 2 + + #: Coding for user 3 -- Set to 0 for BCC. Set to 1 for LDPC. + CODING_LDPC_USER3 = 1 << 3 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'VHTCoding': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) diff --git a/pcapkit/const/radiotap/vht_flags.py b/pcapkit/const/radiotap/vht_flags.py new file mode 100644 index 0000000000..be9d7588b3 --- /dev/null +++ b/pcapkit/const/radiotap/vht_flags.py @@ -0,0 +1,84 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap VHT Flags +======================== + +.. module:: pcapkit.const.radiotap.vht_flags + +This module contains the constant enumeration for **Radiotap VHT Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.vht_flags.VHTFlags`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['VHTFlags'] + + +class VHTFlags(EnumRegistry, IntFlag): + """[VHTFlags] Radiotap VHT Flags""" + + #: STBC -- Space-time block coding. Set to 0 if no spatial streams of any user + #: has STBC. Set to 1 if all spatial streams of all users have STBC. + VHT_FLAG_STBC = 1 << 0 + + #: TXOP_PS_NOT_ALLOWED -- Valid only for AP transmitters. Set to 0 if STAs may + #: doze during TXOP. Set to 1 if STAs may not doze during TXOP or transmitter + #: is non-AP. + VHT_FLAG_TXOP_PS_NA = 1 << 1 + + #: Guard interval. -- Set to 0 for long GI. Set to 1 for short GI. + VHT_FLAG_SGI = 1 << 2 + + #: Short GI NSYM disambiguation -- Valid only if short GI is used. Set to 0 if + #: NSYM mod 10 != 9 or short GI not used. Set to 1 if NSYM mod 10 = 9. + VHT_FLAG_SGI_NSYM_M10_9 = 1 << 3 + + #: LDPC Extra OFDM symbol -- Set to 1 if one or more users are using LDPC and + #: the encoding process resulted in extra OFDM symbol(s). Set to 0 otherwise. + VHT_FLAG_LDPC_EXTRA_OFDM_SYM = 1 << 4 + + #: Beamformed -- Valid for SU PPDUs only. + VHT_FLAG_BEAMFORMED = 1 << 5 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'VHTFlags': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) diff --git a/pcapkit/const/radiotap/vht_known.py b/pcapkit/const/radiotap/vht_known.py new file mode 100644 index 0000000000..7d30e517c8 --- /dev/null +++ b/pcapkit/const/radiotap/vht_known.py @@ -0,0 +1,90 @@ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""Radiotap VHT Known Flags +============================== + +.. module:: pcapkit.const.radiotap.vht_known + +This module contains the constant enumeration for **Radiotap VHT Known Flags**, +which is automatically generated from :class:`pcapkit.vendor.radiotap.vht_known.VHTKnown`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['VHTKnown'] + + +class VHTKnown(EnumRegistry, IntFlag): + """[VHTKnown] Radiotap VHT Known Flags""" + + #: STBC known -- In flags part of the field. + VHT_KNOWN_STBC = 1 << 0 + + #: TXOP_PS_NOT_ALLOWED known -- In flags part of the field. + VHT_KNOWN_TXOP_PS_NA = 1 << 1 + + #: Guard interval -- In flags part of the field. + VHT_KNOWN_GI = 1 << 2 + + #: Short GI NSYM disambiguation known -- In flags part of the field. + VHT_KNOWN_SGI_NSYM_DIS = 1 << 3 + + #: LDPC extra OFDM symbol known -- In flags part of the field. + VHT_KNOWN_LDPC_EXTRA_OFDM_SYM = 1 << 4 + + #: Beamformed known/applicable -- In flags part of the field. This flag should + #: be set to zero for MU PPDUs. + VHT_KNOWN_BEAMFORMED = 1 << 5 + + #: Bandwidth known -- In bandwidth part of the field. + VHT_KNOWN_BANDWIDTH = 1 << 6 + + #: Group ID known -- In group_id part of the field. + VHT_KNOWN_GROUP_ID = 1 << 7 + + #: Partial AID known/applicable -- In partial_aid part of the field. This flag + #: should be set to zero for MU PPDUs. + VHT_KNOWN_PARTIAL_AID = 1 << 8 + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> 'VHTKnown': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not (isinstance(value, int) and 0 <= value <= 0xFFFF): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) diff --git a/pcapkit/foundation/__init__.py b/pcapkit/foundation/__init__.py index b18ce5c648..a203b26623 100644 --- a/pcapkit/foundation/__init__.py +++ b/pcapkit/foundation/__init__.py @@ -37,6 +37,7 @@ 'register_ethertype', 'register_loopback', 'register_arphrd', 'register_frad', 'register_netlink', 'register_radiotap', + 'register_radiotap_field', 'register_transtype', 'register_ipx', 'register_icmp_type', diff --git a/pcapkit/foundation/registry/__init__.py b/pcapkit/foundation/registry/__init__.py index a86b32a887..664721e5db 100644 --- a/pcapkit/foundation/registry/__init__.py +++ b/pcapkit/foundation/registry/__init__.py @@ -33,6 +33,7 @@ 'register_ethertype', 'register_loopback', 'register_arphrd', 'register_frad', 'register_netlink', 'register_radiotap', + 'register_radiotap_field', 'register_transtype', 'register_ipx', diff --git a/pcapkit/foundation/registry/protocols/__init__.py b/pcapkit/foundation/registry/protocols/__init__.py index be3eabe7e9..dc56460eee 100644 --- a/pcapkit/foundation/registry/protocols/__init__.py +++ b/pcapkit/foundation/registry/protocols/__init__.py @@ -44,6 +44,7 @@ 'register_ethertype', 'register_loopback', 'register_arphrd', 'register_frad', 'register_netlink', 'register_radiotap', + 'register_radiotap_field', 'register_transtype', 'register_ipx', diff --git a/pcapkit/foundation/registry/protocols/link.py b/pcapkit/foundation/registry/protocols/link.py index 43874a0da8..ff89e446de 100644 --- a/pcapkit/foundation/registry/protocols/link.py +++ b/pcapkit/foundation/registry/protocols/link.py @@ -17,6 +17,7 @@ from typing import TYPE_CHECKING, cast, overload from pcapkit.const.linux.arphrd import ARPHRD as Enum_ARPHRD +from pcapkit.const.radiotap.field_type import FieldType as Radiotap_FieldType from pcapkit.const.reg.ethertype import EtherType as Enum_EtherType from pcapkit.const.reg.linktype import LinkType as Enum_LinkType from pcapkit.corekit.module import ModuleDescriptor @@ -28,19 +29,24 @@ from pcapkit.protocols.link.loopback import Loopback from pcapkit.protocols.link.netlink import Netlink from pcapkit.protocols.link.radiotap import Radiotap +from pcapkit.protocols.schema.link.radiotap import RadiotapField as Schema_Radiotap_Field +from pcapkit.utilities.exceptions import RegistryError from pcapkit.utilities.logging import get_logger if TYPE_CHECKING: - from typing import Type + from typing import Optional, Type from pcapkit.const.reg.ethertype import EtherType from pcapkit.corekit.sentinels import NullType + from pcapkit.protocols.link.radiotap import FieldConstructor as Radiotap_FieldConstructor + from pcapkit.protocols.link.radiotap import FieldParser as Radiotap_FieldParser from pcapkit.protocols.protocol import ProtocolBase __all__ = [ 'register_ethertype', 'register_loopback', 'register_arphrd', 'register_frad', 'register_netlink', 'register_radiotap', + 'register_radiotap_field', ] #: logging.Logger: Module-level logger, a child of the package-wide @@ -325,3 +331,47 @@ def register_radiotap(code: 'Enum_LinkType', module: 'str | ModuleDescriptor[Pro if isinstance(module, ModuleDescriptor): module = module.klass _register_name(module, (Radiotap, code)) + + +# NOTE: pcapkit.protocols.link.radiotap.Radiotap.__field__ +def register_radiotap_field(code: 'Radiotap_FieldType', + meth: 'str | tuple[Radiotap_FieldParser, Radiotap_FieldConstructor]', *, + schema: 'Optional[Type[Schema_Radiotap_Field]]' = None) -> 'None': + """Register a radiotap field parser. + + The function will register the given field parser to the + :data:`pcapkit.protocols.link.radiotap.Radiotap.__field__` registry. A + field type is decoded once both it and the schema registry hold an entry + for it. A presence bit 28 to 30 follows rules of its own, as does a vendor + namespace TLV item, so an entry for one is stored and not reached there; a + type from 32 on is reached only as a TLV item. + + Args: + code: :class:`~pcapkit.protocols.link.radiotap.Radiotap` field type as + in :class:`~pcapkit.const.radiotap.field_type.FieldType`. + meth: Method name, or a ``(parser, constructor)`` pair of callables, to + parse and construct the field. A name names the + ``_read_field_*`` and ``_make_field_*`` methods, and has to name + an existing ``_read_field_*`` one. + schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the + field, whose fields are its subfields and whose ``__align__`` is its + alignment. It should be a subclass of + :class:`pcapkit.protocols.schema.link.radiotap.RadiotapField`. + + Raises: + RegistryError: If ``code`` is not a + :class:`~pcapkit.const.radiotap.field_type.FieldType` member, e.g. + a member of another enum, or ``meth`` is a name with no matching + ``_read_field_*`` method. + + .. versionadded:: 1.6.0 + + """ + _check_code(code, Radiotap_FieldType, Radiotap) + if isinstance(meth, str) and not hasattr(Radiotap, f'_read_field_{meth}'): + raise RegistryError('method must be a radiotap field parser function') + + Radiotap.register_field(code, meth) + if schema is not None: + Schema_Radiotap_Field.register(code, schema) + logger.debug('registered radiotap field parser: %s', code.name) diff --git a/pcapkit/protocols/data/__init__.py b/pcapkit/protocols/data/__init__.py index 38650a76df..953c99f545 100644 --- a/pcapkit/protocols/data/__init__.py +++ b/pcapkit/protocols/data/__init__.py @@ -85,7 +85,17 @@ 'Netlink', # IEEE 802.11 Radiotap Header - 'Radiotap', + 'Radiotap', 'Radiotap_Field', 'Radiotap_Unknown', 'Radiotap_TSFT', 'Radiotap_Flags', + 'Radiotap_Rate', 'Radiotap_Channel', 'Radiotap_FHSS', 'Radiotap_AntennaSignal', + 'Radiotap_AntennaNoise', 'Radiotap_LockQuality', 'Radiotap_TXAttenuation', + 'Radiotap_DBTXAttenuation', 'Radiotap_DBmTXPower', 'Radiotap_Antenna', + 'Radiotap_DBAntennaSignal', 'Radiotap_DBAntennaNoise', 'Radiotap_RXFlags', + 'Radiotap_TXFlags', 'Radiotap_RTSRetries', 'Radiotap_DataRetries', 'Radiotap_MCS', + 'Radiotap_AMPDUStatus', 'Radiotap_VHT', + 'Radiotap_Timestamp', 'Radiotap_HE', 'Radiotap_HEMU', 'Radiotap_HEMUOtherUser', + 'Radiotap_ZeroLengthPSDU', 'Radiotap_LSIG', 'Radiotap_TLVFields', + 'Radiotap_RadiotapNamespace', 'Radiotap_VendorNamespace', 'Radiotap_S1G', 'Radiotap_USIG', + 'Radiotap_EHT', 'Radiotap_TLV', 'Radiotap_VendorTLV', # 802.1Q/802.1ad VLAN Tag Types 'VLAN', 'VLAN_TCI', diff --git a/pcapkit/protocols/data/link/__init__.py b/pcapkit/protocols/data/link/__init__.py index bb85863975..f525193ddb 100644 --- a/pcapkit/protocols/data/link/__init__.py +++ b/pcapkit/protocols/data/link/__init__.py @@ -37,7 +37,44 @@ from pcapkit.protocols.data.link.netlink import Netlink # IEEE 802.11 Radiotap Header +from pcapkit.protocols.data.link.radiotap import EHT as Radiotap_EHT +from pcapkit.protocols.data.link.radiotap import FHSS as Radiotap_FHSS +from pcapkit.protocols.data.link.radiotap import HE as Radiotap_HE +from pcapkit.protocols.data.link.radiotap import HEMU as Radiotap_HEMU +from pcapkit.protocols.data.link.radiotap import LSIG as Radiotap_LSIG +from pcapkit.protocols.data.link.radiotap import MCS as Radiotap_MCS +from pcapkit.protocols.data.link.radiotap import S1G as Radiotap_S1G +from pcapkit.protocols.data.link.radiotap import TLV as Radiotap_TLV +from pcapkit.protocols.data.link.radiotap import TSFT as Radiotap_TSFT +from pcapkit.protocols.data.link.radiotap import USIG as Radiotap_USIG +from pcapkit.protocols.data.link.radiotap import VHT as Radiotap_VHT +from pcapkit.protocols.data.link.radiotap import AMPDUStatus as Radiotap_AMPDUStatus +from pcapkit.protocols.data.link.radiotap import Antenna as Radiotap_Antenna +from pcapkit.protocols.data.link.radiotap import AntennaNoise as Radiotap_AntennaNoise +from pcapkit.protocols.data.link.radiotap import AntennaSignal as Radiotap_AntennaSignal +from pcapkit.protocols.data.link.radiotap import Channel as Radiotap_Channel +from pcapkit.protocols.data.link.radiotap import DataRetries as Radiotap_DataRetries +from pcapkit.protocols.data.link.radiotap import DBAntennaNoise as Radiotap_DBAntennaNoise +from pcapkit.protocols.data.link.radiotap import DBAntennaSignal as Radiotap_DBAntennaSignal +from pcapkit.protocols.data.link.radiotap import DBmTXPower as Radiotap_DBmTXPower +from pcapkit.protocols.data.link.radiotap import DBTXAttenuation as Radiotap_DBTXAttenuation +from pcapkit.protocols.data.link.radiotap import Flags as Radiotap_Flags +from pcapkit.protocols.data.link.radiotap import HEMUOtherUser as Radiotap_HEMUOtherUser +from pcapkit.protocols.data.link.radiotap import LockQuality as Radiotap_LockQuality from pcapkit.protocols.data.link.radiotap import Radiotap +from pcapkit.protocols.data.link.radiotap import RadiotapField as Radiotap_Field +from pcapkit.protocols.data.link.radiotap import RadiotapNamespace as Radiotap_RadiotapNamespace +from pcapkit.protocols.data.link.radiotap import Rate as Radiotap_Rate +from pcapkit.protocols.data.link.radiotap import RTSRetries as Radiotap_RTSRetries +from pcapkit.protocols.data.link.radiotap import RXFlags as Radiotap_RXFlags +from pcapkit.protocols.data.link.radiotap import Timestamp as Radiotap_Timestamp +from pcapkit.protocols.data.link.radiotap import TLVFields as Radiotap_TLVFields +from pcapkit.protocols.data.link.radiotap import TXAttenuation as Radiotap_TXAttenuation +from pcapkit.protocols.data.link.radiotap import TXFlags as Radiotap_TXFlags +from pcapkit.protocols.data.link.radiotap import Unknown as Radiotap_Unknown +from pcapkit.protocols.data.link.radiotap import VendorNamespace as Radiotap_VendorNamespace +from pcapkit.protocols.data.link.radiotap import VendorTLV as Radiotap_VendorTLV +from pcapkit.protocols.data.link.radiotap import ZeroLengthPSDU as Radiotap_ZeroLengthPSDU # 802.1Q/802.1ad VLAN Tag Types from pcapkit.protocols.data.link.vlan import TCI as VLAN_TCI @@ -73,7 +110,17 @@ 'Netlink', # IEEE 802.11 Radiotap Header - 'Radiotap', + 'Radiotap', 'Radiotap_Field', 'Radiotap_Unknown', 'Radiotap_TSFT', 'Radiotap_Flags', + 'Radiotap_Rate', 'Radiotap_Channel', 'Radiotap_FHSS', 'Radiotap_AntennaSignal', + 'Radiotap_AntennaNoise', 'Radiotap_LockQuality', 'Radiotap_TXAttenuation', + 'Radiotap_DBTXAttenuation', 'Radiotap_DBmTXPower', 'Radiotap_Antenna', + 'Radiotap_DBAntennaSignal', 'Radiotap_DBAntennaNoise', 'Radiotap_RXFlags', + 'Radiotap_TXFlags', 'Radiotap_RTSRetries', 'Radiotap_DataRetries', 'Radiotap_MCS', + 'Radiotap_AMPDUStatus', 'Radiotap_VHT', + 'Radiotap_Timestamp', 'Radiotap_HE', 'Radiotap_HEMU', 'Radiotap_HEMUOtherUser', + 'Radiotap_ZeroLengthPSDU', 'Radiotap_LSIG', 'Radiotap_TLVFields', + 'Radiotap_RadiotapNamespace', 'Radiotap_VendorNamespace', 'Radiotap_S1G', 'Radiotap_USIG', + 'Radiotap_EHT', 'Radiotap_TLV', 'Radiotap_VendorTLV', # 802.1Q/802.1ad VLAN Tag Types 'VLAN', 'VLAN_TCI', diff --git a/pcapkit/protocols/data/link/radiotap.py b/pcapkit/protocols/data/link/radiotap.py index d358ee9c9f..6221e071bd 100644 --- a/pcapkit/protocols/data/link/radiotap.py +++ b/pcapkit/protocols/data/link/radiotap.py @@ -4,21 +4,586 @@ from typing import TYPE_CHECKING from pcapkit.corekit.infoclass import info_final +from pcapkit.protocols.data.data import Data from pcapkit.protocols.data.protocol import Protocol if TYPE_CHECKING: - pass + from pcapkit.const.radiotap.ampdu_flags import AMPDUFlags + from pcapkit.const.radiotap.channel_flags import ChannelFlags + from pcapkit.const.radiotap.eht_known import EHTKnown + from pcapkit.const.radiotap.field_type import FieldType + from pcapkit.const.radiotap.flags import Flags as Radiotap_Flags + from pcapkit.const.radiotap.he_mu_other_user_known import HEMUOtherUserKnown + from pcapkit.const.radiotap.lsig_data1 import LSIGData1 + from pcapkit.const.radiotap.mcs_known import MCSKnown + from pcapkit.const.radiotap.rx_flags import RXFlags as Radiotap_RXFlags + from pcapkit.const.radiotap.s1g_known import S1GKnown + from pcapkit.const.radiotap.timestamp_flags import TimestampFlags + from pcapkit.const.radiotap.tx_flags import TXFlags as Radiotap_TXFlags + from pcapkit.const.radiotap.vht_coding import VHTCoding + from pcapkit.const.radiotap.vht_flags import VHTFlags + from pcapkit.const.radiotap.vht_known import VHTKnown + from pcapkit.corekit.infoclass import OrderedMultiInfo + from pcapkit.corekit.multidict import OrderedMultiDict -__all__ = ['Radiotap'] +__all__ = [ + 'Radiotap', + + 'RadiotapField', 'Unknown', + 'TSFT', 'Flags', 'Rate', 'Channel', 'FHSS', 'AntennaSignal', 'AntennaNoise', + 'LockQuality', 'TXAttenuation', 'DBTXAttenuation', 'DBmTXPower', 'Antenna', + 'DBAntennaSignal', 'DBAntennaNoise', 'RXFlags', 'TXFlags', 'RTSRetries', 'DataRetries', + 'MCS', 'AMPDUStatus', + 'VHT', 'Timestamp', 'HE', 'HEMU', 'HEMUOtherUser', 'ZeroLengthPSDU', 'LSIG', + 'TLVFields', 'RadiotapNamespace', 'VendorNamespace', 'S1G', 'USIG', 'EHT', + 'TLV', 'VendorTLV', +] + + +class RadiotapField(Data): + """Data model for a radiotap field. + + Each field's subfields are named as its own page on radiotap.org names + them, and each is the little-endian integer read off the wire. A bitmap + radiotap.org defines bit by bit is a member of its flag registry under + :mod:`pcapkit.const.radiotap`, which keeps the bits it does not name; any + other bitmap stays the integer. + + """ + + #: The presence bit that selects the field, or its TLV type. + type: 'FieldType' + + +@info_final +class Unknown(RadiotapField): + """Data model for an octet run a field type does not decode. + + It is the field of a presence bit no field is defined for, or of a field + that does not fit in what the header holds, and it holds every octet + from the end of the field before it to the end of the field-data region, + since what follows cannot be located without knowing its size. + + """ + + #: The octets, kept whole. + data: 'bytes' + #: The reason the walk stopped here, that the field type has no layout or + #: that the field runs past the field-data region. :meth:`Radiotap.make + #: ` does not read it. + reason: 'str' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', data: 'bytes', reason: 'str') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class TSFT(RadiotapField): + """Data model for the TSFT field, bit 0.""" + + #: The MAC's 64-bit Time Synchronization Function timer, in microseconds, + #: when the first bit of the MPDU arrived. + mactime: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', mactime: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class Flags(RadiotapField): + """Data model for the Flags field, bit 1.""" + + #: Properties of the frame. + flags: 'Radiotap_Flags' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', flags: 'Radiotap_Flags') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class Rate(RadiotapField): + """Data model for the Rate field, bit 2.""" + + #: TX/RX data rate, in units of 500 kbps. + rate: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', rate: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class Channel(RadiotapField): + """Data model for the Channel field, bit 3.""" + + #: TX/RX frequency, in MHz. + frequency: 'int' + #: Channel flags. + flags: 'ChannelFlags' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', frequency: 'int', flags: 'ChannelFlags') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class FHSS(RadiotapField): + """Data model for the FHSS field, bit 4.""" + + #: Hop set of a frequency-hopping radio. + hop_set: 'int' + #: Hop pattern of a frequency-hopping radio. + hop_pattern: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', hop_set: 'int', hop_pattern: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class AntennaSignal(RadiotapField): + """Data model for the Antenna signal field, bit 5.""" + + #: RF signal power at the antenna, in dBm. + signal: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', signal: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class AntennaNoise(RadiotapField): + """Data model for the Antenna noise field, bit 6.""" + + #: RF noise power at the antenna, in dBm. + noise: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', noise: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class LockQuality(RadiotapField): + """Data model for the Lock quality field, bit 7.""" + + #: Quality of Barker code lock, unitless. + quality: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', quality: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class TXAttenuation(RadiotapField): + """Data model for the TX attenuation field, bit 8.""" + + #: Distance from the maximum transmit power, unitless; ``0`` is maximum power. + attenuation: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', attenuation: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class DBTXAttenuation(RadiotapField): + """Data model for the dB TX attenuation field, bit 9.""" + + #: Distance from the maximum transmit power, in dB; ``0`` is maximum power. + attenuation: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', attenuation: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class DBmTXPower(RadiotapField): + """Data model for the dBm TX power field, bit 10.""" + + #: Transmit power at the antenna port, in dBm. + power: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', power: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class Antenna(RadiotapField): + """Data model for the Antenna field, bit 11.""" + + #: Index of the RX/TX antenna, from ``0``. + antenna: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', antenna: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class DBAntennaSignal(RadiotapField): + """Data model for the dB antenna signal field, bit 12.""" + + #: RF signal power at the antenna, in dB from an arbitrary reference. + signal: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', signal: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class DBAntennaNoise(RadiotapField): + """Data model for the dB antenna noise field, bit 13.""" + + #: RF noise power at the antenna, in dB from an arbitrary reference. + noise: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', noise: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class RXFlags(RadiotapField): + """Data model for the RX flags field, bit 14.""" + + #: Properties of the received frame. + flags: 'Radiotap_RXFlags' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', flags: 'Radiotap_RXFlags') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class TXFlags(RadiotapField): + """Data model for the TX flags field, bit 15.""" + + #: Properties of the transmitted frame. + flags: 'Radiotap_TXFlags' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', flags: 'Radiotap_TXFlags') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class RTSRetries(RadiotapField): + """Data model for the RTS retries field, bit 16, which radiotap.org lists as unofficial.""" + + #: RTS retries the transmitted frame used. + retries: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', retries: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class DataRetries(RadiotapField): + """Data model for the data retries field, bit 17, which radiotap.org lists as unofficial.""" + + #: Data retries the transmitted frame used. + retries: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', retries: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class MCS(RadiotapField): + """Data model for the MCS field, bit 19.""" + + #: Which of :attr:`flags` and :attr:`mcs` are known. + known: 'MCSKnown' + #: Bandwidth, guard interval, HT format, FEC type, STBC and Ness, a bitmap. + flags: 'int' + #: MCS rate index, as in IEEE Std 802.11n-2009. + mcs: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', known: 'MCSKnown', flags: 'int', mcs: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class AMPDUStatus(RadiotapField): + """Data model for the A-MPDU status field, bit 20.""" + + #: Reference number, the same for every subframe of an A-MPDU. + reference: 'int' + #: A-MPDU flags. + flags: 'AMPDUFlags' + #: Delimiter CRC value. + delimiter_crc: 'int' + #: Reserved. + reserved: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', reference: 'int', flags: 'AMPDUFlags', # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + delimiter_crc: 'int', reserved: 'int') -> 'None': ... # pylint: disable=unused-argument + + +@info_final +class VHT(RadiotapField): + """Data model for the VHT field, bit 21.""" + + #: Which of the subfields below are known. + known: 'VHTKnown' + #: STBC, TXOP_PS_NOT_ALLOWED, guard interval, LDPC extra OFDM symbol and + #: beamformed. + flags: 'VHTFlags' + #: Bandwidth. + bandwidth: 'int' + #: MCS and NSS of each of the four users. + mcs_nss: 'tuple[int, int, int, int]' + #: Coding of each user. + coding: 'VHTCoding' + #: Group ID. + group_id: 'int' + #: Partial AID. + partial_aid: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', known: 'VHTKnown', flags: 'VHTFlags', bandwidth: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + mcs_nss: 'tuple[int, int, int, int]', coding: 'VHTCoding', group_id: 'int', # pylint: disable=unused-argument + partial_aid: 'int') -> 'None': ... # pylint: disable=unused-argument + + +@info_final +class Timestamp(RadiotapField): + """Data model for the timestamp field, bit 22.""" + + #: The timestamp, in the unit :attr:`unit_position` names. + timestamp: 'int' + #: Expected accuracy of :attr:`timestamp`, in the same unit. + accuracy: 'int' + #: Unit (bits 0-3) and sampling position (bits 4-7). + unit_position: 'int' + #: Timestamp flags. + flags: 'TimestampFlags' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', timestamp: 'int', accuracy: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + unit_position: 'int', flags: 'TimestampFlags') -> 'None': ... # pylint: disable=unused-argument + + +@info_final +class HE(RadiotapField): + """Data model for the HE field, bit 23, mostly the common part of HE-SIG-A.""" + + #: PPDU format and which of the subfields are known. + data1: 'int' + #: Which of the subfields are known, and the primary 80 MHz channel. + data2: 'int' + #: BSS color, beam change, UL/DL, MCS, DCM, coding, LDPC and STBC. + data3: 'int' + #: Spatial reuse, or STA-ID in an HE MU PPDU. + data4: 'int' + #: Bandwidth, guard interval, LTF symbol size, TxBF and PE disambiguity. + data5: 'int' + #: NSTS, Doppler and TXOP. + data6: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', data1: 'int', data2: 'int', data3: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + data4: 'int', data5: 'int', data6: 'int') -> 'None': ... # pylint: disable=unused-argument + + +@info_final +class HEMU(RadiotapField): + """Data model for the HE-MU field, bit 24, from HE-SIG-A and HE-SIG-B.""" + + #: SIG-B MCS, DCM, compression and which of the subfields are known. + flags1: 'int' + #: Bandwidth, SIG-B symbols or MU-MIMO users, and punctured preamble. + flags2: 'int' + #: RU_channel1, one octet per RU. + ru_channel1: 'tuple[int, int, int, int]' + #: RU_channel2, one octet per RU. + ru_channel2: 'tuple[int, int, int, int]' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', flags1: 'int', flags2: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + ru_channel1: 'tuple[int, int, int, int]', # pylint: disable=unused-argument + ru_channel2: 'tuple[int, int, int, int]') -> 'None': ... # pylint: disable=unused-argument + + +@info_final +class HEMUOtherUser(RadiotapField): + """Data model for the HE-MU-other-user field, bit 25, a SIG-B user field.""" + + #: B0-B14 of the HE-SIG-B user field. + per_user_1: 'int' + #: B15-B20 of the HE-SIG-B user field. + per_user_2: 'int' + #: Position of the user field, from ``0``. + per_user_position: 'int' + #: Which of the subfields are known. + per_user_known: 'HEMUOtherUserKnown' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', per_user_1: 'int', per_user_2: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + per_user_position: 'int', per_user_known: 'HEMUOtherUserKnown') -> 'None': ... # pylint: disable=unused-argument + + +@info_final +class ZeroLengthPSDU(RadiotapField): + """Data model for the 0-length-PSDU field, bit 26.""" + + #: Type of the PPDU, the field radiotap.org names ``type``. + psdu_type: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', psdu_type: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class LSIG(RadiotapField): + """Data model for the L-SIG field, bit 27.""" + + #: Which of the subfields in :attr:`data2` are known. + data1: 'LSIGData1' + #: Rate (bits 0-3) and length (bits 4-15). + data2: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', data1: 'LSIGData1', data2: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class TLV(Data): + """Data model for one item of the TLV fields in radiotap.""" + + #: Type, from the same allocation as the presence bits. + type: 'FieldType' + #: Length of :attr:`data`, in octets, less the padding after it. + length: 'int' + #: The data, decoded where the type defines a layout and :attr:`length` + #: matches it; the raw octets otherwise. + data: 'RadiotapField | VendorTLV | bytes' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', length: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + data: 'RadiotapField | VendorTLV | bytes') -> 'None': ... # pylint: disable=unused-argument + + +@info_final +class TLVFields(RadiotapField): + """Data model for the TLV fields in radiotap, bit 28. + + The items fill the rest of the field-data region, each padded to a + multiple of 4 octets. + + """ + + #: The items, in order. + tlvs: 'tuple[TLV, ...]' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', tlvs: 'tuple[TLV, ...]') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class RadiotapNamespace(RadiotapField): + """Data model for the Radiotap Namespace field, bit 29 of a presence word. + + It has no contents. The presence word after the one carrying it starts + the radiotap namespace afresh, from bit 0. + + """ + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class VendorNamespace(RadiotapField): + """Data model for the Vendor Namespace field, bit 30 of a presence word. + + The presence words after the one carrying it, up to the next namespace + field, select fields of the vendor namespace, and the data of every one of + them is in :attr:`data`, kept whole. + + """ + + #: The vendor's IEEE 802 Organizationally Unique Identifier, 3 octets. + oui: 'bytes' + #: Vendor-specific namespace selector. + sub_namespace: 'int' + #: Octets of :attr:`data`, as the header gives it. + skip_length: 'int' + #: The vendor namespace's data, kept whole. + data: 'bytes' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', oui: 'bytes', sub_namespace: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + skip_length: 'int', data: 'bytes') -> 'None': ... # pylint: disable=unused-argument + + +@info_final +class S1G(RadiotapField): + """Data model for the S1G field, TLV type 32.""" + + #: Which of the subfields are known. + known: 'S1GKnown' + #: PPDU format, response indication, guard interval, NSS, bandwidth and MCS. + data1: 'int' + #: Color, uplink indication and RSSI. + data2: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', known: 'S1GKnown', data1: 'int', data2: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class USIG(RadiotapField): + """Data model for the U-SIG field, TLV type 33.""" + + #: Which of the common subfields are known, and their values. + common: 'int' + #: Version-dependent subfields. + value: 'int' + #: Which bits of :attr:`value` are known. + mask: 'int' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', common: 'int', value: 'int', mask: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@info_final +class EHT(RadiotapField): + """Data model for the EHT field, TLV type 34.""" + + #: Which of the subfields are known. + known: 'EHTKnown' + #: The nine data words. + data: 'tuple[int, ...]' + #: One word per user, as many as the TLV holds. + user_info: 'tuple[int, ...]' + + if TYPE_CHECKING: + def __init__(self, type: 'FieldType', known: 'EHTKnown', data: 'tuple[int, ...]', # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + user_info: 'tuple[int, ...]') -> 'None': ... # pylint: disable=unused-argument + + +@info_final +class VendorTLV(Data): + """Data model for the data of a vendor namespace TLV, type 30.""" + + #: The vendor's IEEE 802 Organizationally Unique Identifier, 3 octets. + oui: 'bytes' + #: Vendor-specific subtype. + subtype: 'int' + #: Index of the presence bit the vendor data stands for. + presence_type: 'int' + #: Reserved, padding the vendor data to a 4-octet boundary. + reserved: 'int' + #: The vendor data, kept whole. + data: 'bytes' + + if TYPE_CHECKING: + def __init__(self, oui: 'bytes', subtype: 'int', presence_type: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements + reserved: 'int', data: 'bytes') -> 'None': ... # pylint: disable=unused-argument @info_final class Radiotap(Protocol): """Data model for an IEEE 802.11 radiotap header. - Only the fixed 8-octet start is decoded field by field; the rest is kept - whole, see :attr:`present` and :attr:`fields` and the module docstring's - *Scope* section on :mod:`pcapkit.protocols.link.radiotap`. + The fixed 8-octet start and the present-flags chain are decoded field by + field; the optional-field region is kept whole as :attr:`fields`, which + is what a rebuild writes, and decoded as :attr:`decoded`. See the module + docstring's *Scope* section on :mod:`pcapkit.protocols.link.radiotap`. """ @@ -39,10 +604,15 @@ class Radiotap(Protocol): #: follows; it is clear on the last word read, unless the capture ran #: out before a word it claimed would follow. present: 'tuple[int, ...]' - #: The optional-field region :attr:`present` selects, kept whole and - #: undissected. + #: The optional-field region :attr:`present` selects, kept whole. fields: 'bytes' + #: The fields of :attr:`fields`, decoded in wire order, keyed by type: + #: one per bit of :attr:`present` that selects data in the radiotap + #: namespace or switches namespace. See :meth:`Radiotap.read + #: `. + decoded: 'OrderedMultiInfo[FieldType, RadiotapField]' if TYPE_CHECKING: def __init__(self, it_version: 'int', it_pad: 'int', it_len: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements - present: 'tuple[int, ...]', fields: 'bytes') -> 'None': ... # pylint: disable=unused-argument + present: 'tuple[int, ...]', fields: 'bytes', # pylint: disable=unused-argument + decoded: 'OrderedMultiDict[FieldType, RadiotapField]') -> 'None': ... # pylint: disable=unused-argument diff --git a/pcapkit/protocols/link/ieee802_11.py b/pcapkit/protocols/link/ieee802_11.py index d2e297d97f..952724f8b8 100644 --- a/pcapkit/protocols/link/ieee802_11.py +++ b/pcapkit/protocols/link/ieee802_11.py @@ -41,9 +41,9 @@ :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: this class does not decide whether a capture carries one, which behind radiotap is a -Flags bit :class:`~pcapkit.protocols.link.radiotap.Radiotap` does not decode. -For the same reason, the pad octets that radiotap's data-pad flag says follow -the header stay at the start of the body. +Flags bit :class:`~pcapkit.protocols.link.radiotap.Radiotap` decodes but does +not pass on. For the same reason, the pad octets that radiotap's data-pad flag +says follow the header stay at the start of the body. A frame of any protocol version but 0 is refused: version 1 is the PV1 frame format of §9.8, whose Frame Control field is laid out differently, and diff --git a/pcapkit/protocols/link/radiotap.py b/pcapkit/protocols/link/radiotap.py index 9c3f67be89..e36f022930 100644 --- a/pcapkit/protocols/link/radiotap.py +++ b/pcapkit/protocols/link/radiotap.py @@ -7,11 +7,16 @@ :mod:`pcapkit.protocols.link.radiotap` contains :class:`~pcapkit.protocols.link.radiotap.Radiotap` only, which implements the extractor for the radiotap header [*]_ capture tools prepend to an 802.11 -frame, as seen on a ``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` capture -whose ``arphrd_type`` is ``ARPHRD_IEEE80211_RADIOTAP`` -- -:class:`~pcapkit.protocols.link.linux_sll.LinuxSLL` dispatches here instead -of falling back to :class:`~pcapkit.protocols.misc.raw.Raw` for that one -case; see :attr:`LinuxSLL.__proto__ `. +frame, as seen on a ``LINKTYPE_IEEE802_11_RADIOTAP`` capture, or on a +``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` capture whose ``arphrd_type`` +is ``ARPHRD_IEEE80211_RADIOTAP``. +:class:`~pcapkit.protocols.misc.pcap.frame.Frame` and +:class:`~pcapkit.protocols.misc.pcapng.PCAPNG` bind +:attr:`LinkType.IEEE802_11_RADIOTAP ` +here, and :class:`~pcapkit.protocols.link.linux_sll.LinuxSLL` dispatches here +for that one ``arphrd_type`` instead of falling back to +:class:`~pcapkit.protocols.misc.raw.Raw`; see +:attr:`LinuxSLL.__proto__ `. Radiotap is not part of the 802.11 standard itself: it is a prefix *in front of* the raw 802.11 MAC frame, written by the capturing tool rather than by the radio. Its structure is a fixed 8-octet start, all little-endian: @@ -35,17 +40,16 @@ Scope ----- -Decoding every optional field radiotap.org defines is tracked on -:issue:`2576`. This class: +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 many - words it has (:attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.present`), - without decoding what any bit selects. -* **Skips, rather than decodes,** the optional-field region those bits - 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`. + ``it_len`` -- and walks the present-flags chain, recording every word as + :attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.present`. +* **Keeps** the optional-field region those bits select whole, as + :attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.fields`, which is + what a rebuild from the data model writes, and **decodes** it as + :attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.decoded`, by the + rules below. * **Hands** everything from ``it_len`` on, the 802.11 MAC frame, to :class:`~pcapkit.protocols.link.ieee802_11.IEEE802_11` (:class:`~pcapkit.protocols.misc.no_payload.NoPayload` when nothing follows). @@ -54,33 +58,164 @@ :attr:`Radiotap.__proto__ ` under :attr:`LinkType.IEEE802_11 `. -.. [*] ; the Linux kernel's +Field Decoding +-------------- + +The bits are walked in order, word by word, and the fields they select follow +one another in the same order, each aligned to its own boundary counted from +the start of the header. A field type is read and made by the methods +:attr:`Radiotap.__field__ ` +names for it, through the schema the +:class:`~pcapkit.protocols.schema.link.radiotap.RadiotapField` registry holds +for it: the schema's fields are the subfields of the type's page on +radiotap.org, their total is its size, and its ``__align__`` its alignment, +which match the tables of the Linux kernel, Wireshark and radiotap.org's own +``radiotap-library`` wherever they size it. A page that names no alignment +takes that of its subfields, single octets, but for FHSS, which those three +align to 2. The fields are radiotap.org's defined ones, and RTS retries and data +retries, bits 16 and 17, from its unofficially used ones, which those three +size alike; OpenBSD writes a 2-octet RSSI field at bit 16 instead, which is not +read. A bitmap radiotap.org defines bit by bit is a member of its flag registry +under :mod:`pcapkit.const.radiotap`, which keeps the bits it does not name. A +field type registered through +:func:`~pcapkit.foundation.registry.protocols.link.register_radiotap_field` is +decoded the same way. + +* **Namespaces.** Bits 29 and 30 mean the same in every word. Bit 29, the + Radiotap Namespace field, carries nothing, and the next word restarts the + radiotap namespace at bit 0. Bit 30, the Vendor Namespace field, carries an + OUI, a sub-namespace and a ``skip_length``; the words up to the next + namespace field select vendor fields, whose data is the ``skip_length`` + octets after it, kept whole. Without either, the next word continues the + namespace, each bit numbered 32 past the same bit of the word before. +* **TLVs.** Bit 28 makes the rest of the region a list of type-length-value + items. An item's data is decoded where its type has a schema whose size it + matches, and kept raw otherwise; a vendor item is split into its header and + raw data. +* **What is not decoded.** A radiotap-namespace bit no field is defined for -- + 18, FreeBSD's XChannel, which radiotap.org lists as unofficial, and every one + numbered 32 or more, the TLV-only types included -- or a field that runs + past the region, ends the walk, since nothing after it can be located: an + :class:`~pcapkit.protocols.data.link.radiotap.Unknown` entry keeps every + octet from there on, and its ``reason`` says which of the two it was. + +.. [*] , its field pages and its + ``radiotap-library``; the Linux kernel's ``include/net/ieee80211_radiotap.h`` and ``net/wireless/radiotap.c``; and - Wireshark's ``packet-ieee80211-radiotap.c``, all of which agree on the - fixed start and the present-flags chaining described above. + Wireshark's ``packet-ieee80211-radiotap.c`` and + ``packet-ieee80211-radiotap-iter.c``, all of which agree on the fixed start + and the present-flags chaining described above, and on each field layout + they give. .. versionadded:: 1.6.0 """ import collections -from typing import TYPE_CHECKING +import collections.abc +from typing import TYPE_CHECKING, cast +from pcapkit.const.radiotap.field_type import FieldType as Enum_FieldType from pcapkit.const.reg.linktype import LinkType as Enum_LinkType +from pcapkit.corekit.fields.collections import ListField +from pcapkit.corekit.fields.strings import pad_length from pcapkit.corekit.module import ModuleDescriptor +from pcapkit.corekit.multidict import OrderedMultiDict +from pcapkit.protocols.data.link.radiotap import EHT as Data_EHT +from pcapkit.protocols.data.link.radiotap import FHSS as Data_FHSS +from pcapkit.protocols.data.link.radiotap import HE as Data_HE +from pcapkit.protocols.data.link.radiotap import HEMU as Data_HEMU +from pcapkit.protocols.data.link.radiotap import LSIG as Data_LSIG +from pcapkit.protocols.data.link.radiotap import MCS as Data_MCS +from pcapkit.protocols.data.link.radiotap import S1G as Data_S1G +from pcapkit.protocols.data.link.radiotap import TLV as Data_TLV +from pcapkit.protocols.data.link.radiotap import TSFT as Data_TSFT +from pcapkit.protocols.data.link.radiotap import USIG as Data_USIG +from pcapkit.protocols.data.link.radiotap import VHT as Data_VHT +from pcapkit.protocols.data.link.radiotap import AMPDUStatus as Data_AMPDUStatus +from pcapkit.protocols.data.link.radiotap import Antenna as Data_Antenna +from pcapkit.protocols.data.link.radiotap import AntennaNoise as Data_AntennaNoise +from pcapkit.protocols.data.link.radiotap import AntennaSignal as Data_AntennaSignal +from pcapkit.protocols.data.link.radiotap import Channel as Data_Channel +from pcapkit.protocols.data.link.radiotap import DataRetries as Data_DataRetries +from pcapkit.protocols.data.link.radiotap import DBAntennaNoise as Data_DBAntennaNoise +from pcapkit.protocols.data.link.radiotap import DBAntennaSignal as Data_DBAntennaSignal +from pcapkit.protocols.data.link.radiotap import DBmTXPower as Data_DBmTXPower +from pcapkit.protocols.data.link.radiotap import DBTXAttenuation as Data_DBTXAttenuation +from pcapkit.protocols.data.link.radiotap import Flags as Data_Flags +from pcapkit.protocols.data.link.radiotap import HEMUOtherUser as Data_HEMUOtherUser +from pcapkit.protocols.data.link.radiotap import LockQuality as Data_LockQuality from pcapkit.protocols.data.link.radiotap import Radiotap as Data_Radiotap +from pcapkit.protocols.data.link.radiotap import RadiotapNamespace as Data_RadiotapNamespace +from pcapkit.protocols.data.link.radiotap import Rate as Data_Rate +from pcapkit.protocols.data.link.radiotap import RTSRetries as Data_RTSRetries +from pcapkit.protocols.data.link.radiotap import RXFlags as Data_RXFlags +from pcapkit.protocols.data.link.radiotap import Timestamp as Data_Timestamp +from pcapkit.protocols.data.link.radiotap import TLVFields as Data_TLVFields +from pcapkit.protocols.data.link.radiotap import TXAttenuation as Data_TXAttenuation +from pcapkit.protocols.data.link.radiotap import TXFlags as Data_TXFlags +from pcapkit.protocols.data.link.radiotap import Unknown as Data_Unknown +from pcapkit.protocols.data.link.radiotap import VendorNamespace as Data_VendorNamespace +from pcapkit.protocols.data.link.radiotap import VendorTLV as Data_VendorTLV +from pcapkit.protocols.data.link.radiotap import ZeroLengthPSDU as Data_ZeroLengthPSDU from pcapkit.protocols.link.link import Link from pcapkit.protocols.protocol import ProtocolBase +from pcapkit.protocols.schema.link.radiotap import EHT as Schema_EHT +from pcapkit.protocols.schema.link.radiotap import FHSS as Schema_FHSS +from pcapkit.protocols.schema.link.radiotap import HE as Schema_HE +from pcapkit.protocols.schema.link.radiotap import HEMU as Schema_HEMU +from pcapkit.protocols.schema.link.radiotap import LSIG as Schema_LSIG +from pcapkit.protocols.schema.link.radiotap import MCS as Schema_MCS +from pcapkit.protocols.schema.link.radiotap import S1G as Schema_S1G +from pcapkit.protocols.schema.link.radiotap import TLV as Schema_TLV +from pcapkit.protocols.schema.link.radiotap import TSFT as Schema_TSFT +from pcapkit.protocols.schema.link.radiotap import USIG as Schema_USIG +from pcapkit.protocols.schema.link.radiotap import VHT as Schema_VHT +from pcapkit.protocols.schema.link.radiotap import AMPDUStatus as Schema_AMPDUStatus +from pcapkit.protocols.schema.link.radiotap import Antenna as Schema_Antenna +from pcapkit.protocols.schema.link.radiotap import AntennaNoise as Schema_AntennaNoise +from pcapkit.protocols.schema.link.radiotap import AntennaSignal as Schema_AntennaSignal +from pcapkit.protocols.schema.link.radiotap import Channel as Schema_Channel +from pcapkit.protocols.schema.link.radiotap import DataRetries as Schema_DataRetries +from pcapkit.protocols.schema.link.radiotap import DBAntennaNoise as Schema_DBAntennaNoise +from pcapkit.protocols.schema.link.radiotap import DBAntennaSignal as Schema_DBAntennaSignal +from pcapkit.protocols.schema.link.radiotap import DBmTXPower as Schema_DBmTXPower +from pcapkit.protocols.schema.link.radiotap import DBTXAttenuation as Schema_DBTXAttenuation +from pcapkit.protocols.schema.link.radiotap import Flags as Schema_Flags +from pcapkit.protocols.schema.link.radiotap import HEMUOtherUser as Schema_HEMUOtherUser +from pcapkit.protocols.schema.link.radiotap import LockQuality as Schema_LockQuality from pcapkit.protocols.schema.link.radiotap import Radiotap as Schema_Radiotap +from pcapkit.protocols.schema.link.radiotap import RadiotapField as Schema_Field +from pcapkit.protocols.schema.link.radiotap import Rate as Schema_Rate +from pcapkit.protocols.schema.link.radiotap import RTSRetries as Schema_RTSRetries +from pcapkit.protocols.schema.link.radiotap import RXFlags as Schema_RXFlags +from pcapkit.protocols.schema.link.radiotap import Timestamp as Schema_Timestamp +from pcapkit.protocols.schema.link.radiotap import TXAttenuation as Schema_TXAttenuation +from pcapkit.protocols.schema.link.radiotap import TXFlags as Schema_TXFlags +from pcapkit.protocols.schema.link.radiotap import Unknown as Schema_Unknown +from pcapkit.protocols.schema.link.radiotap import VendorNamespace as Schema_VendorNamespace +from pcapkit.protocols.schema.link.radiotap import VendorTLV as Schema_VendorTLV +from pcapkit.protocols.schema.link.radiotap import ZeroLengthPSDU as Schema_ZeroLengthPSDU from pcapkit.protocols.schema.schema import Schema -from pcapkit.utilities.exceptions import ProtocolError +from pcapkit.utilities.exceptions import CaughtByCaller, FieldValueError, ProtocolError from pcapkit.utilities.warnings import RegistryWarning, warn if TYPE_CHECKING: - from typing import Any, ClassVar, DefaultDict, Optional, Sequence, Type + from typing import (Any, Callable, ClassVar, DefaultDict, Iterator, Mapping, Optional, Sequence, + Tuple, Type, Union) from typing_extensions import Literal from pcapkit.corekit.enum import EnumRegistry + from pcapkit.protocols.data.link.radiotap import RadiotapField as Data_Field + + #: A field given to :meth:`Radiotap.make`: a data model, or a ``(type, mapping)`` pair. + FieldEntry = Union[Data_Field, Tuple[Union[Enum_FieldType, int], Mapping[str, Any]]] + #: Parser of a field type registered as a callable: the type and the + #: parsed schema, to the data model. + FieldParser = Callable[[Enum_FieldType, Schema_Field], Data_Field] + #: Constructor of a field type registered as a callable: the type and a + #: data model or a mapping of its subfields, to the schema. + FieldConstructor = Callable[[Enum_FieldType, Union[Data_Field, Mapping[str, Any]]], Schema_Field] __all__ = ['Radiotap'] @@ -95,9 +230,21 @@ #: Octets of one present-flags word, extended or not. _PRESENT_WORD_LEN = 4 +#: Bits of one present-flags word. +_PRESENT_WORD_BITS = 8 * _PRESENT_WORD_LEN + +#: The largest field type, the bound of a TLV's ``type``; a presence bit past +#: it ends the walk, see :meth:`Radiotap._walk_present`. +_FIELD_TYPE_MAX = (1 << 8 * Schema_TLV.__fields__['type'].length) - 1 + +#: Why an :class:`~pcapkit.protocols.data.link.radiotap.Unknown` entry ended +#: the walk, as its ``reason`` says. +_REASON_NO_LAYOUT = 'no layout is defined for the field type' +_REASON_PAST_REGION = 'the field runs past the field-data region' + class Radiotap(Link[Data_Radiotap, Schema_Radiotap], - schema=Schema_Radiotap, data=Data_Radiotap): + schema=Schema_Radiotap, data=Data_Radiotap): """This class implements the IEEE 802.11 radiotap header. The 802.11 MAC frame this header precedes is dispatched through the @@ -111,8 +258,10 @@ class Radiotap(Link[Data_Radiotap, Schema_Radiotap], * - :attr:`~pcapkit.const.reg.linktype.LinkType.IEEE802_11` - :class:`pcapkit.protocols.link.ieee802_11.IEEE802_11` - See the module docstring's *Scope* section for what is, and is not, - decoded. + and each field of the field-data region through :attr:`__field__`, keyed + by its :class:`~pcapkit.const.radiotap.field_type.FieldType`. See the + module docstring's *Scope* and *Field Decoding* sections for what is, and + is not, decoded. """ @@ -134,6 +283,50 @@ class Radiotap(Link[Data_Radiotap, Schema_Radiotap], #: :attr:`Link.__proto_key__ ` is. __proto_key__: 'ClassVar[tuple[Type[EnumRegistry], bool]]' = (Enum_LinkType, False) + #: Field type to method mapping, see :meth:`_read_radiotap_fields` and + #: :meth:`_make_radiotap_fields`. A :obj:`str` value names the methods + #: ``_read_field_${name}`` and ``_make_field_${name}``, any other value is a + #: ``(parser, constructor)`` pair; either works on the type's schema in the + #: :class:`~pcapkit.protocols.schema.link.radiotap.RadiotapField` registry. A + #: type missing from either has no layout and is kept raw. Presence bits 28 to + #: 30 and vendor namespace TLV items follow rules of their own, see the module + #: docstring; a type from 32 on is reached as a TLV item only. + __field__ = collections.defaultdict( + lambda: 'unknown', + { + Enum_FieldType.TSFT: 'tsft', + Enum_FieldType.Flags: 'flags', + Enum_FieldType.Rate: 'rate', + Enum_FieldType.Channel: 'channel', + Enum_FieldType.FHSS: 'fhss', + Enum_FieldType.Antenna_signal: 'antenna_signal', + Enum_FieldType.Antenna_noise: 'antenna_noise', + Enum_FieldType.Lock_quality: 'lock_quality', + Enum_FieldType.TX_attenuation: 'tx_attenuation', + Enum_FieldType.dB_TX_attenuation: 'db_tx_attenuation', + Enum_FieldType.dBm_TX_power: 'dbm_tx_power', + Enum_FieldType.Antenna: 'antenna', + Enum_FieldType.dB_antenna_signal: 'db_antenna_signal', + Enum_FieldType.dB_antenna_noise: 'db_antenna_noise', + Enum_FieldType.RX_flags: 'rx_flags', + Enum_FieldType.TX_flags: 'tx_flags', + Enum_FieldType.RTS_retries: 'rts_retries', + Enum_FieldType.data_retries: 'data_retries', + Enum_FieldType.MCS: 'mcs', + Enum_FieldType.A_MPDU_status: 'ampdu_status', + Enum_FieldType.VHT: 'vht', + Enum_FieldType.timestamp: 'timestamp', + Enum_FieldType.HE: 'he', + Enum_FieldType.HE_MU: 'he_mu', + Enum_FieldType.HE_MU_other_user: 'he_mu_other_user', + Enum_FieldType.FieldType_0_length_PSDU: 'zero_length_psdu', + Enum_FieldType.L_SIG: 'lsig', + Enum_FieldType.S1G: 's1g', + Enum_FieldType.U_SIG: 'usig', + Enum_FieldType.EHT: 'eht', + }, + ) # type: DefaultDict[Enum_FieldType | int, str | tuple[FieldParser, FieldConstructor]] + ########################################################################## # Properties. ########################################################################## @@ -187,8 +380,19 @@ def read(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_Radiota followed, while the previous word's bit 31 is set, by a further ``it_present`` word, then by the field-data region those bits - select (kept whole, see the module docstring's *Scope* section), - then by the 802.11 MAC frame at offset ``it_len``. + select, then by the 802.11 MAC frame at offset ``it_len``. + + The region is decoded into + :attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.decoded` as the + module docstring's *Field Decoding* section describes: one entry per + bit that selects radiotap-namespace data or switches namespace, keyed + by its :class:`~pcapkit.const.radiotap.field_type.FieldType`. A bit in + a vendor namespace has no entry of its own, since its data is in the + :class:`~pcapkit.protocols.data.link.radiotap.VendorNamespace` entry, + and nothing after the TLV fields or an + :class:`~pcapkit.protocols.data.link.radiotap.Unknown` entry has one. + Octets after the last field stay in + :attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.fields` alone. Args: length: Length of packet data. @@ -242,6 +446,7 @@ def read(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_Radiota it_len=it_len, present=tuple(present), fields=fields, + decoded=self._read_radiotap_fields(present, fields), ) header_len = _FIXED_HEADER_LEN + tail_offset return self._decode_next_layer(radiotap, Enum_LinkType.IEEE802_11, max(0, length - header_len)) @@ -250,7 +455,7 @@ def make(self, it_version: 'int' = 0, it_pad: 'int' = 0, present: 'Sequence[int]' = (0,), - fields: 'bytes' = b'', + fields: 'bytes | Mapping[Enum_FieldType | int, Data_Field | Mapping[str, Any]] | Sequence[FieldEntry]' = b'', # pylint: disable=line-too-long it_len: 'Optional[int]' = None, payload: 'bytes | ProtocolBase | Schema' = b'', **kwargs: 'Any') -> 'Schema_Radiotap': @@ -262,12 +467,22 @@ def make(self, present: Every present-flags word, in order; the first is the mandatory one radiotap.org calls ``it_present``, and each but the last conventionally has bit 31 set (not enforced - here, so a capture that read short of its own chain - replays exactly: see the ``Note`` on + for raw ``fields``, so a capture that read short of its own + chain replays exactly: see the ``Note`` on :meth:`FRAD.make ` for the same tolerance). - fields: The optional-field region ``present`` selects, kept - whole; see the module docstring's *Scope* section. + fields: The optional-field region ``present`` selects: the raw + octets, written as they are, or its fields, which are + encoded with zero padding. Fields are given as + :attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.decoded` + holds them, or as a sequence of data models or + ``(type, mapping)`` pairs, a type being a + :class:`~pcapkit.const.radiotap.field_type.FieldType` or an + :class:`int`. There is one per bit :meth:`read` gives an entry + for, in the same order, and an + :class:`~pcapkit.protocols.data.link.radiotap.Unknown` one, or + one of a type no field is defined for, is written raw and + ends the region. it_len: Total header length, header included; computed from ``present`` and ``fields`` when omitted. payload: Payload data (the 802.11 MAC frame). @@ -279,8 +494,11 @@ def make(self, Raises: ProtocolError: If ``it_version`` or ``it_pad`` does not fit in 8 bits; if ``present`` is empty or any of its words does not - fit in 32 bits; if ``fields`` is not :class:`bytes`; or if - ``it_len`` is given and does not fit in 16 bits. + fit in 32 bits; if ``fields`` is neither :class:`bytes` nor + fields; if the fields do not match the bits of ``present``, + a word but the last of which ends the chain, or a value does + not fit its subfield; or if ``it_len`` is given and does not + fit in 16 bits. """ for name, value in (('it_version', it_version), ('it_pad', it_pad)): @@ -295,9 +513,12 @@ def make(self, or not 0 <= word <= 0xFFFF_FFFF): raise ProtocolError(f'{self.alias}: invalid present word: {word!r}') - if not isinstance(fields, (bytes, bytearray)): - raise ProtocolError(f'{self.alias}: invalid fields: {fields!r}, must be bytes') - fields = bytes(fields) + if isinstance(fields, (bytes, bytearray)): + fields_bytes = bytes(fields) + elif not isinstance(fields, (collections.abc.Mapping, list, tuple)): + raise ProtocolError(f'{self.alias}: invalid fields: {fields!r}, must be bytes or fields') + else: + fields_bytes = self._make_radiotap_fields(present, fields) if isinstance(payload, ProtocolBase): payload_bytes = bytes(payload) @@ -309,7 +530,7 @@ def make(self, chain_bytes = b''.join(word.to_bytes(_PRESENT_WORD_LEN, 'little') for word in present[1:]) if it_len is None: - it_len = _FIXED_HEADER_LEN + len(chain_bytes) + len(fields) + it_len = _FIXED_HEADER_LEN + len(chain_bytes) + len(fields_bytes) elif (not isinstance(it_len, int) or isinstance(it_len, bool) or not 0 <= it_len <= 0xFFFF): raise ProtocolError(f'{self.alias}: invalid it_len: {it_len!r}') @@ -319,7 +540,7 @@ def make(self, it_pad=it_pad, it_len=it_len, it_present=present[0], - payload=chain_bytes + fields + payload_bytes, + payload=chain_bytes + fields_bytes + payload_bytes, ) @classmethod @@ -367,6 +588,31 @@ def register(cls, code: 'Enum_LinkType', # type: ignore[override] f'{incumbent!r} with {entry!r}', RegistryWarning) cls.__proto__[code] = entry + @classmethod + def register_field(cls, code: 'Enum_FieldType', meth: 'str | tuple[FieldParser, FieldConstructor]') -> 'None': + """Register a field parser. + + Args: + code: Radiotap field type. + meth: Method name, or a ``(parser, constructor)`` pair of + callables, to parse and construct the field; see + :attr:`__field__`. + + Warns: + RegistryWarning: If a different entry is already registered for + ``code``; it is overwritten. Handing back the entry already + stored, or one equal to it, is a silent no-op. Re-registering + the entry ``code`` shipped with is accepted like any other, + so an override can be undone (:issue:`1362`, :issue:`1363`). + + """ + incumbent = cls.__field__.get(code) + if incumbent is not None and incumbent == meth: + return + if incumbent is not None: + warn(f'field type {code} already registered, overwriting', RegistryWarning) + cls.__field__[code] = meth + ########################################################################## # Data models. ########################################################################## @@ -408,6 +654,13 @@ def __index__(cls) -> 'Enum_LinkType': # pylint: disable=invalid-index-returned def _make_data(cls, data: 'Data_Radiotap') -> 'dict[str, Any]': # type: ignore[override] """Create key-value pairs from ``data`` for protocol construction. + The field-data region is rebuilt from + :attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.fields`, the + octets as captured, so padding, trailing octets and fields that were + not decoded come back exactly; an edit to + :attr:`~pcapkit.protocols.data.link.radiotap.Radiotap.decoded` takes + a :meth:`make` call that passes it as ``fields``. + Args: data: protocol data @@ -424,20 +677,1467 @@ def _make_data(cls, data: 'Data_Radiotap') -> 'dict[str, Any]': # type: ignore[ 'payload': cls._make_payload(data), } - def _get_payload(self) -> 'bytes': - """Get the 802.11 MAC frame this header precedes. + def _read_radiotap_fields(self, present: 'Sequence[int]', + fields: 'bytes') -> 'OrderedMultiDict[Enum_FieldType, Data_Field]': + """Decode the field-data region. - The header schema's payload starts right after the fixed 8-octet - start, so it also holds the present-flags chain and the field-data - region it selects; those belong to this header, and the frame starts - ``self._mac_offset`` octets in, as :meth:`read` records it. Both - :meth:`Protocol._import_next_layer ` - and the :class:`~pcapkit.protocols.misc.raw.Raw` that - :func:`~pcapkit.corekit.decorators.beholder` falls back to on a - refused frame read from here. + Args: + present: Every present-flags word read. + fields: The field-data region. Returns: - The 802.11 MAC frame, as :obj:`bytes`. + The decoded fields, as :meth:`read` describes them. """ - return self.__header__.get_payload()[self._mac_offset:] + decoded = OrderedMultiDict() # type: OrderedMultiDict[Enum_FieldType, Data_Field] + start = _FIXED_HEADER_LEN + _PRESENT_WORD_LEN * (len(present) - 1) + pos = 0 + for index in self._walk_present(present): + field_type = Enum_FieldType.get(index) + if index == Enum_FieldType.Radiotap_Namespace: + decoded.add(field_type, Data_RadiotapNamespace(type=field_type)) + continue + + found = None # type: Optional[tuple[Data_Field, int]] + if index == Enum_FieldType.Vendor_Namespace: + found = self._read_vendor_namespace(field_type, fields, pos, start) + elif index == Enum_FieldType.TLV_fields_in_radiotap: + found = self._read_tlv_fields(field_type, fields, pos, start) + else: + found = self._read_present_field(field_type, fields, pos, start) + + if found is None: + found = self._read_field_unknown(field_type, Schema_Unknown(data=fields[pos:]), + reason=_REASON_PAST_REGION), len(fields) + entry, pos = found + decoded.add(field_type, entry) + if isinstance(entry, Data_Unknown) or index == Enum_FieldType.TLV_fields_in_radiotap: + break + return decoded + + def _make_radiotap_fields(self, present: 'Sequence[int]', + fields: 'Mapping[Enum_FieldType | int, Data_Field | Mapping[str, Any]] | Sequence[FieldEntry]') -> 'bytes': # pylint: disable=line-too-long + """Encode the field-data region, the inverse of :meth:`_read_radiotap_fields`. + + Args: + present: Every present-flags word. + fields: The fields, as :meth:`make` takes them. + + Returns: + The field-data region. + + Raises: + ProtocolError: If the fields do not match the bits of ``present``, + a word but the last of which ends the chain, or a value does + not fit its subfield. + + """ + for number, word in enumerate(present[:-1]): + if not word & _IT_PRESENT_EXTENDED: + raise ProtocolError(f'{self.alias}: invalid present: word {number} ends the chain, ' + 'but more follow') + + entries = [] # type: list[tuple[Enum_FieldType, Mapping[str, Any]]] + if isinstance(fields, collections.abc.Mapping): + items = fields.items(multi=True) if isinstance(fields, OrderedMultiDict) else fields.items() + entries.extend((Enum_FieldType.get(key), value) for key, value in items) + else: + for item in fields: + if isinstance(item, tuple): + entries.append((Enum_FieldType.get(item[0]), item[1])) + else: + entries.append((Enum_FieldType.get(item['type']), item)) + + out = bytearray() + start = _FIXED_HEADER_LEN + _PRESENT_WORD_LEN * (len(present) - 1) + given = iter(entries) + for index in self._walk_present(present): + expected = Enum_FieldType.get(index) + pair = next(given, None) + if pair is None: + raise ProtocolError(f'{self.alias}: invalid fields: none given for {expected!r}') + field_type, entry = pair + if field_type != expected: + raise ProtocolError(f'{self.alias}: invalid fields: {field_type!r} given where ' + f'present selects {expected!r}') + + layout = None if index >= Enum_FieldType.TLV_fields_in_radiotap else self._lookup_field(expected) + if index in (Enum_FieldType.TLV_fields_in_radiotap, Enum_FieldType.Radiotap_Namespace, + Enum_FieldType.Vendor_Namespace): + decodable = True + else: + decodable = layout is not None and not self._field_size(layout[2])[1] + if isinstance(entry, Data_Unknown) or not decodable: + out += self._make_field_unknown(expected, entry).pack() + break + if index == Enum_FieldType.Radiotap_Namespace: + continue + + pos = start + len(out) + if index == Enum_FieldType.Vendor_Namespace: + out += self._make_vendor_namespace(entry, pos) + elif index == Enum_FieldType.TLV_fields_in_radiotap: + out += self._make_tlv_fields(entry, pos) + break + else: + _, constructor, schema = layout # type: ignore[misc] + out += bytes(pad_length(pos, schema.__align__)) + out += constructor(expected, entry).pack() + + left = sum(1 for _ in given) + if left: + raise ProtocolError(f'{self.alias}: invalid fields: {left} given past what present selects') + return bytes(out) + + def _read_field_unknown(self, field_type: 'Enum_FieldType', schema: 'Schema_Unknown', *, + reason: 'str' = _REASON_NO_LAYOUT) -> 'Data_Unknown': + """Read the octets of a field type with no layout, or of a field that + runs past the field-data region. + + Args: + field_type: type of the field + schema: parsed field schema, every octet to the end of the region + reason: why the field is not decoded + + Returns: + Parsed field data. + + """ + return Data_Unknown(type=field_type, data=schema.data, reason=reason) + + def _read_field_tsft(self, field_type: 'Enum_FieldType', schema: 'Schema_TSFT') -> 'Data_TSFT': + """Read a TSFT field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_TSFT(type=field_type, mactime=schema.mactime) + + def _read_field_flags(self, field_type: 'Enum_FieldType', schema: 'Schema_Flags') -> 'Data_Flags': + """Read a Flags field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_Flags(type=field_type, flags=schema.flags) + + def _read_field_rate(self, field_type: 'Enum_FieldType', schema: 'Schema_Rate') -> 'Data_Rate': + """Read a Rate field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_Rate(type=field_type, rate=schema.rate) + + def _read_field_channel(self, field_type: 'Enum_FieldType', schema: 'Schema_Channel') -> 'Data_Channel': + """Read a Channel field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_Channel(type=field_type, frequency=schema.frequency, flags=schema.flags) + + def _read_field_fhss(self, field_type: 'Enum_FieldType', schema: 'Schema_FHSS') -> 'Data_FHSS': + """Read an FHSS field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_FHSS(type=field_type, hop_set=schema.hop_set, hop_pattern=schema.hop_pattern) + + def _read_field_antenna_signal(self, field_type: 'Enum_FieldType', + schema: 'Schema_AntennaSignal') -> 'Data_AntennaSignal': + """Read an Antenna signal field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_AntennaSignal(type=field_type, signal=schema.signal) + + def _read_field_antenna_noise(self, field_type: 'Enum_FieldType', + schema: 'Schema_AntennaNoise') -> 'Data_AntennaNoise': + """Read an Antenna noise field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_AntennaNoise(type=field_type, noise=schema.noise) + + def _read_field_lock_quality(self, field_type: 'Enum_FieldType', + schema: 'Schema_LockQuality') -> 'Data_LockQuality': + """Read a Lock quality field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_LockQuality(type=field_type, quality=schema.quality) + + def _read_field_tx_attenuation(self, field_type: 'Enum_FieldType', + schema: 'Schema_TXAttenuation') -> 'Data_TXAttenuation': + """Read a TX attenuation field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_TXAttenuation(type=field_type, attenuation=schema.attenuation) + + def _read_field_db_tx_attenuation(self, field_type: 'Enum_FieldType', + schema: 'Schema_DBTXAttenuation') -> 'Data_DBTXAttenuation': + """Read a dB TX attenuation field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_DBTXAttenuation(type=field_type, attenuation=schema.attenuation) + + def _read_field_dbm_tx_power(self, field_type: 'Enum_FieldType', + schema: 'Schema_DBmTXPower') -> 'Data_DBmTXPower': + """Read a dBm TX power field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_DBmTXPower(type=field_type, power=schema.power) + + def _read_field_antenna(self, field_type: 'Enum_FieldType', schema: 'Schema_Antenna') -> 'Data_Antenna': + """Read an Antenna field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_Antenna(type=field_type, antenna=schema.antenna) + + def _read_field_db_antenna_signal(self, field_type: 'Enum_FieldType', + schema: 'Schema_DBAntennaSignal') -> 'Data_DBAntennaSignal': + """Read a dB antenna signal field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_DBAntennaSignal(type=field_type, signal=schema.signal) + + def _read_field_db_antenna_noise(self, field_type: 'Enum_FieldType', + schema: 'Schema_DBAntennaNoise') -> 'Data_DBAntennaNoise': + """Read a dB antenna noise field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_DBAntennaNoise(type=field_type, noise=schema.noise) + + def _read_field_rx_flags(self, field_type: 'Enum_FieldType', schema: 'Schema_RXFlags') -> 'Data_RXFlags': + """Read an RX flags field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_RXFlags(type=field_type, flags=schema.flags) + + def _read_field_tx_flags(self, field_type: 'Enum_FieldType', schema: 'Schema_TXFlags') -> 'Data_TXFlags': + """Read a TX flags field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_TXFlags(type=field_type, flags=schema.flags) + + def _read_field_rts_retries(self, field_type: 'Enum_FieldType', + schema: 'Schema_RTSRetries') -> 'Data_RTSRetries': + """Read an RTS retries field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_RTSRetries(type=field_type, retries=schema.retries) + + def _read_field_data_retries(self, field_type: 'Enum_FieldType', + schema: 'Schema_DataRetries') -> 'Data_DataRetries': + """Read a data retries field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_DataRetries(type=field_type, retries=schema.retries) + + def _read_field_mcs(self, field_type: 'Enum_FieldType', schema: 'Schema_MCS') -> 'Data_MCS': + """Read an MCS field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_MCS(type=field_type, known=schema.known, flags=schema.flags, mcs=schema.mcs) + + def _read_field_ampdu_status(self, field_type: 'Enum_FieldType', + schema: 'Schema_AMPDUStatus') -> 'Data_AMPDUStatus': + """Read an A-MPDU status field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_AMPDUStatus(type=field_type, reference=schema.reference, flags=schema.flags, + delimiter_crc=schema.delimiter_crc, reserved=schema.reserved) + + def _read_field_vht(self, field_type: 'Enum_FieldType', schema: 'Schema_VHT') -> 'Data_VHT': + """Read a VHT field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_VHT(type=field_type, known=schema.known, flags=schema.flags, bandwidth=schema.bandwidth, + mcs_nss=cast('tuple[int, int, int, int]', tuple(schema.mcs_nss)), + coding=schema.coding, group_id=schema.group_id, + partial_aid=schema.partial_aid) + + def _read_field_timestamp(self, field_type: 'Enum_FieldType', schema: 'Schema_Timestamp') -> 'Data_Timestamp': + """Read a timestamp field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_Timestamp(type=field_type, timestamp=schema.timestamp, accuracy=schema.accuracy, + unit_position=schema.unit_position, flags=schema.flags) + + def _read_field_he(self, field_type: 'Enum_FieldType', schema: 'Schema_HE') -> 'Data_HE': + """Read an HE field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_HE(type=field_type, data1=schema.data1, data2=schema.data2, data3=schema.data3, + data4=schema.data4, data5=schema.data5, data6=schema.data6) + + def _read_field_he_mu(self, field_type: 'Enum_FieldType', schema: 'Schema_HEMU') -> 'Data_HEMU': + """Read an HE-MU field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_HEMU(type=field_type, flags1=schema.flags1, flags2=schema.flags2, + ru_channel1=cast('tuple[int, int, int, int]', tuple(schema.ru_channel1)), + ru_channel2=cast('tuple[int, int, int, int]', tuple(schema.ru_channel2))) + + def _read_field_he_mu_other_user(self, field_type: 'Enum_FieldType', + schema: 'Schema_HEMUOtherUser') -> 'Data_HEMUOtherUser': + """Read an HE-MU-other-user field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_HEMUOtherUser(type=field_type, per_user_1=schema.per_user_1, per_user_2=schema.per_user_2, + per_user_position=schema.per_user_position, + per_user_known=schema.per_user_known) + + def _read_field_zero_length_psdu(self, field_type: 'Enum_FieldType', + schema: 'Schema_ZeroLengthPSDU') -> 'Data_ZeroLengthPSDU': + """Read a 0-length-PSDU field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_ZeroLengthPSDU(type=field_type, psdu_type=schema.psdu_type) + + def _read_field_lsig(self, field_type: 'Enum_FieldType', schema: 'Schema_LSIG') -> 'Data_LSIG': + """Read an L-SIG field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_LSIG(type=field_type, data1=schema.data1, data2=schema.data2) + + def _read_field_s1g(self, field_type: 'Enum_FieldType', schema: 'Schema_S1G') -> 'Data_S1G': + """Read an S1G field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_S1G(type=field_type, known=schema.known, data1=schema.data1, data2=schema.data2) + + def _read_field_usig(self, field_type: 'Enum_FieldType', schema: 'Schema_USIG') -> 'Data_USIG': + """Read a U-SIG field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_USIG(type=field_type, common=schema.common, value=schema.value, mask=schema.mask) + + def _read_field_eht(self, field_type: 'Enum_FieldType', schema: 'Schema_EHT') -> 'Data_EHT': + """Read an EHT field. + + Args: + field_type: type of the field + schema: parsed field schema + + Returns: + Parsed field data. + + """ + return Data_EHT(type=field_type, known=schema.known, data=tuple(schema.data), + user_info=tuple(schema.user_info)) + + def _make_field_unknown(self, field_type: 'Enum_FieldType', + entry: 'Data_Field | Mapping[str, Any]') -> 'Schema_Unknown': + """Make the octets of a field that is written raw: an unknown one, or + one of a type with no layout. + + Args: + field_type: type of the field + entry: field data, whose ``data`` is the octets + + Returns: + Constructed field schema. + + Raises: + ProtocolError: If ``data`` is not :class:`bytes`. + + """ + data = entry.get('data') + if not isinstance(data, (bytes, bytearray)): + raise ProtocolError(f'{self.alias}: invalid fields: {field_type!r} is written raw, ' + f'so its data must be bytes, not {data!r}') + return Schema_Unknown(data=bytes(data)) + + def _make_field_tsft(self, field_type: 'Enum_FieldType', + entry: 'Data_TSFT | Mapping[str, Any]') -> 'Schema_TSFT': + """Make a TSFT field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_TSFT(mactime=self._make_subfield(field_type, Schema_TSFT, entry, 'mactime')) + + def _make_field_flags(self, field_type: 'Enum_FieldType', + entry: 'Data_Flags | Mapping[str, Any]') -> 'Schema_Flags': + """Make a Flags field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_Flags(flags=self._make_subfield(field_type, Schema_Flags, entry, 'flags')) + + def _make_field_rate(self, field_type: 'Enum_FieldType', + entry: 'Data_Rate | Mapping[str, Any]') -> 'Schema_Rate': + """Make a Rate field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_Rate(rate=self._make_subfield(field_type, Schema_Rate, entry, 'rate')) + + def _make_field_channel(self, field_type: 'Enum_FieldType', + entry: 'Data_Channel | Mapping[str, Any]') -> 'Schema_Channel': + """Make a Channel field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_Channel( + frequency=self._make_subfield(field_type, Schema_Channel, entry, 'frequency'), + flags=self._make_subfield(field_type, Schema_Channel, entry, 'flags'), + ) + + def _make_field_fhss(self, field_type: 'Enum_FieldType', + entry: 'Data_FHSS | Mapping[str, Any]') -> 'Schema_FHSS': + """Make an FHSS field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_FHSS( + hop_set=self._make_subfield(field_type, Schema_FHSS, entry, 'hop_set'), + hop_pattern=self._make_subfield(field_type, Schema_FHSS, entry, 'hop_pattern'), + ) + + def _make_field_antenna_signal(self, field_type: 'Enum_FieldType', + entry: 'Data_AntennaSignal | Mapping[str, Any]') -> 'Schema_AntennaSignal': + """Make an Antenna signal field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_AntennaSignal(signal=self._make_subfield(field_type, Schema_AntennaSignal, entry, 'signal')) + + def _make_field_antenna_noise(self, field_type: 'Enum_FieldType', + entry: 'Data_AntennaNoise | Mapping[str, Any]') -> 'Schema_AntennaNoise': + """Make an Antenna noise field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_AntennaNoise(noise=self._make_subfield(field_type, Schema_AntennaNoise, entry, 'noise')) + + def _make_field_lock_quality(self, field_type: 'Enum_FieldType', + entry: 'Data_LockQuality | Mapping[str, Any]') -> 'Schema_LockQuality': + """Make a Lock quality field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_LockQuality(quality=self._make_subfield(field_type, Schema_LockQuality, entry, 'quality')) + + def _make_field_tx_attenuation(self, field_type: 'Enum_FieldType', + entry: 'Data_TXAttenuation | Mapping[str, Any]') -> 'Schema_TXAttenuation': + """Make a TX attenuation field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_TXAttenuation( + attenuation=self._make_subfield(field_type, Schema_TXAttenuation, entry, 'attenuation'), + ) + + def _make_field_db_tx_attenuation(self, field_type: 'Enum_FieldType', + entry: 'Data_DBTXAttenuation | Mapping[str, Any]') -> 'Schema_DBTXAttenuation': + """Make a dB TX attenuation field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_DBTXAttenuation( + attenuation=self._make_subfield(field_type, Schema_DBTXAttenuation, entry, 'attenuation'), + ) + + def _make_field_dbm_tx_power(self, field_type: 'Enum_FieldType', + entry: 'Data_DBmTXPower | Mapping[str, Any]') -> 'Schema_DBmTXPower': + """Make a dBm TX power field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_DBmTXPower(power=self._make_subfield(field_type, Schema_DBmTXPower, entry, 'power')) + + def _make_field_antenna(self, field_type: 'Enum_FieldType', + entry: 'Data_Antenna | Mapping[str, Any]') -> 'Schema_Antenna': + """Make an Antenna field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_Antenna(antenna=self._make_subfield(field_type, Schema_Antenna, entry, 'antenna')) + + def _make_field_db_antenna_signal(self, field_type: 'Enum_FieldType', + entry: 'Data_DBAntennaSignal | Mapping[str, Any]') -> 'Schema_DBAntennaSignal': + """Make a dB antenna signal field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_DBAntennaSignal(signal=self._make_subfield(field_type, Schema_DBAntennaSignal, entry, 'signal')) + + def _make_field_db_antenna_noise(self, field_type: 'Enum_FieldType', + entry: 'Data_DBAntennaNoise | Mapping[str, Any]') -> 'Schema_DBAntennaNoise': + """Make a dB antenna noise field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_DBAntennaNoise(noise=self._make_subfield(field_type, Schema_DBAntennaNoise, entry, 'noise')) + + def _make_field_rx_flags(self, field_type: 'Enum_FieldType', + entry: 'Data_RXFlags | Mapping[str, Any]') -> 'Schema_RXFlags': + """Make an RX flags field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_RXFlags(flags=self._make_subfield(field_type, Schema_RXFlags, entry, 'flags')) + + def _make_field_tx_flags(self, field_type: 'Enum_FieldType', + entry: 'Data_TXFlags | Mapping[str, Any]') -> 'Schema_TXFlags': + """Make a TX flags field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_TXFlags(flags=self._make_subfield(field_type, Schema_TXFlags, entry, 'flags')) + + def _make_field_rts_retries(self, field_type: 'Enum_FieldType', + entry: 'Data_RTSRetries | Mapping[str, Any]') -> 'Schema_RTSRetries': + """Make an RTS retries field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_RTSRetries(retries=self._make_subfield(field_type, Schema_RTSRetries, entry, 'retries')) + + def _make_field_data_retries(self, field_type: 'Enum_FieldType', + entry: 'Data_DataRetries | Mapping[str, Any]') -> 'Schema_DataRetries': + """Make a data retries field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_DataRetries(retries=self._make_subfield(field_type, Schema_DataRetries, entry, 'retries')) + + def _make_field_mcs(self, field_type: 'Enum_FieldType', entry: 'Data_MCS | Mapping[str, Any]') -> 'Schema_MCS': + """Make an MCS field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_MCS( + known=self._make_subfield(field_type, Schema_MCS, entry, 'known'), + flags=self._make_subfield(field_type, Schema_MCS, entry, 'flags'), + mcs=self._make_subfield(field_type, Schema_MCS, entry, 'mcs'), + ) + + def _make_field_ampdu_status(self, field_type: 'Enum_FieldType', + entry: 'Data_AMPDUStatus | Mapping[str, Any]') -> 'Schema_AMPDUStatus': + """Make an A-MPDU status field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_AMPDUStatus( + reference=self._make_subfield(field_type, Schema_AMPDUStatus, entry, 'reference'), + flags=self._make_subfield(field_type, Schema_AMPDUStatus, entry, 'flags'), + delimiter_crc=self._make_subfield(field_type, Schema_AMPDUStatus, entry, 'delimiter_crc'), + reserved=self._make_subfield(field_type, Schema_AMPDUStatus, entry, 'reserved'), + ) + + def _make_field_vht(self, field_type: 'Enum_FieldType', entry: 'Data_VHT | Mapping[str, Any]') -> 'Schema_VHT': + """Make a VHT field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_VHT( + known=self._make_subfield(field_type, Schema_VHT, entry, 'known'), + flags=self._make_subfield(field_type, Schema_VHT, entry, 'flags'), + bandwidth=self._make_subfield(field_type, Schema_VHT, entry, 'bandwidth'), + mcs_nss=self._make_subfield_list(field_type, Schema_VHT, entry, 'mcs_nss'), + coding=self._make_subfield(field_type, Schema_VHT, entry, 'coding'), + group_id=self._make_subfield(field_type, Schema_VHT, entry, 'group_id'), + partial_aid=self._make_subfield(field_type, Schema_VHT, entry, 'partial_aid'), + ) + + def _make_field_timestamp(self, field_type: 'Enum_FieldType', + entry: 'Data_Timestamp | Mapping[str, Any]') -> 'Schema_Timestamp': + """Make a timestamp field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_Timestamp( + timestamp=self._make_subfield(field_type, Schema_Timestamp, entry, 'timestamp'), + accuracy=self._make_subfield(field_type, Schema_Timestamp, entry, 'accuracy'), + unit_position=self._make_subfield(field_type, Schema_Timestamp, entry, 'unit_position'), + flags=self._make_subfield(field_type, Schema_Timestamp, entry, 'flags'), + ) + + def _make_field_he(self, field_type: 'Enum_FieldType', entry: 'Data_HE | Mapping[str, Any]') -> 'Schema_HE': + """Make an HE field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_HE( + data1=self._make_subfield(field_type, Schema_HE, entry, 'data1'), + data2=self._make_subfield(field_type, Schema_HE, entry, 'data2'), + data3=self._make_subfield(field_type, Schema_HE, entry, 'data3'), + data4=self._make_subfield(field_type, Schema_HE, entry, 'data4'), + data5=self._make_subfield(field_type, Schema_HE, entry, 'data5'), + data6=self._make_subfield(field_type, Schema_HE, entry, 'data6'), + ) + + def _make_field_he_mu(self, field_type: 'Enum_FieldType', + entry: 'Data_HEMU | Mapping[str, Any]') -> 'Schema_HEMU': + """Make an HE-MU field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_HEMU( + flags1=self._make_subfield(field_type, Schema_HEMU, entry, 'flags1'), + flags2=self._make_subfield(field_type, Schema_HEMU, entry, 'flags2'), + ru_channel1=self._make_subfield_list(field_type, Schema_HEMU, entry, 'ru_channel1'), + ru_channel2=self._make_subfield_list(field_type, Schema_HEMU, entry, 'ru_channel2'), + ) + + def _make_field_he_mu_other_user(self, field_type: 'Enum_FieldType', + entry: 'Data_HEMUOtherUser | Mapping[str, Any]') -> 'Schema_HEMUOtherUser': + """Make an HE-MU-other-user field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_HEMUOtherUser( + per_user_1=self._make_subfield(field_type, Schema_HEMUOtherUser, entry, 'per_user_1'), + per_user_2=self._make_subfield(field_type, Schema_HEMUOtherUser, entry, 'per_user_2'), + per_user_position=self._make_subfield(field_type, Schema_HEMUOtherUser, entry, 'per_user_position'), + per_user_known=self._make_subfield(field_type, Schema_HEMUOtherUser, entry, 'per_user_known'), + ) + + def _make_field_zero_length_psdu(self, field_type: 'Enum_FieldType', + entry: 'Data_ZeroLengthPSDU | Mapping[str, Any]') -> 'Schema_ZeroLengthPSDU': + """Make a 0-length-PSDU field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_ZeroLengthPSDU( + psdu_type=self._make_subfield(field_type, Schema_ZeroLengthPSDU, entry, 'psdu_type'), + ) + + def _make_field_lsig(self, field_type: 'Enum_FieldType', entry: 'Data_LSIG | Mapping[str, Any]') -> 'Schema_LSIG': + """Make an L-SIG field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_LSIG( + data1=self._make_subfield(field_type, Schema_LSIG, entry, 'data1'), + data2=self._make_subfield(field_type, Schema_LSIG, entry, 'data2'), + ) + + def _make_field_s1g(self, field_type: 'Enum_FieldType', entry: 'Data_S1G | Mapping[str, Any]') -> 'Schema_S1G': + """Make an S1G field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_S1G( + known=self._make_subfield(field_type, Schema_S1G, entry, 'known'), + data1=self._make_subfield(field_type, Schema_S1G, entry, 'data1'), + data2=self._make_subfield(field_type, Schema_S1G, entry, 'data2'), + ) + + def _make_field_usig(self, field_type: 'Enum_FieldType', entry: 'Data_USIG | Mapping[str, Any]') -> 'Schema_USIG': + """Make a U-SIG field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_USIG( + common=self._make_subfield(field_type, Schema_USIG, entry, 'common'), + value=self._make_subfield(field_type, Schema_USIG, entry, 'value'), + mask=self._make_subfield(field_type, Schema_USIG, entry, 'mask'), + ) + + def _make_field_eht(self, field_type: 'Enum_FieldType', entry: 'Data_EHT | Mapping[str, Any]') -> 'Schema_EHT': + """Make an EHT field. + + Args: + field_type: type of the field + entry: field data, a data model or a mapping of its subfields + + Returns: + Constructed field schema. + + """ + return Schema_EHT( + known=self._make_subfield(field_type, Schema_EHT, entry, 'known'), + data=self._make_subfield_list(field_type, Schema_EHT, entry, 'data'), + user_info=self._make_subfield_list(field_type, Schema_EHT, entry, 'user_info'), + ) + + def _get_payload(self) -> 'bytes': + """Get the 802.11 MAC frame this header precedes. + + The header schema's payload starts right after the fixed 8-octet + start, so it also holds the present-flags chain and the field-data + region it selects; those belong to this header, and the frame starts + ``self._mac_offset`` octets in, as :meth:`read` records it. Both + :meth:`Protocol._import_next_layer ` + and the :class:`~pcapkit.protocols.misc.raw.Raw` that + :func:`~pcapkit.corekit.decorators.beholder` falls back to on a + refused frame read from here. + + Returns: + The 802.11 MAC frame, as :obj:`bytes`. + + """ + return self.__header__.get_payload()[self._mac_offset:] + + @staticmethod + def _walk_present(present: 'Sequence[int]') -> 'Iterator[int]': + """Walk the present-flags words, in wire order. + + Bit 31 of each word is skipped, since it only chains the next word. A + radiotap-namespace bit whose index passes the largest field type ends + the walk, which takes a chain of more than 2048 words. + + Args: + present: Every present-flags word. + + Yields: + ``29`` or ``30`` for a namespace field, in any word; and, for a + bit of a radiotap-namespace word, its index in the namespace, which + is its field type. A bit of a vendor-namespace word yields nothing. + + """ + base = 0 + vendor = False + for word in present: + switch = None + for bit in range(_PRESENT_WORD_BITS - 1): + if not word >> bit & 1: + continue + if bit in (Enum_FieldType.Radiotap_Namespace, Enum_FieldType.Vendor_Namespace): + switch = bit + yield bit + elif not vendor: + if base + bit > _FIELD_TYPE_MAX: + return + yield base + bit + if switch is None: + base += _PRESENT_WORD_BITS + else: + base = 0 + vendor = switch == Enum_FieldType.Vendor_Namespace + + def _lookup_field(self, field_type: 'Enum_FieldType') -> 'Optional[tuple[FieldParser, FieldConstructor, Type[Schema_Field]]]': # pylint: disable=line-too-long + """Look up the parser, constructor and schema of a field type. + + Args: + field_type: type of the field + + Returns: + What :attr:`__field__` and the + :class:`~pcapkit.protocols.schema.link.radiotap.RadiotapField` + registry hold for ``field_type``; :obj:`None` if either has no + entry for it, or if :attr:`__field__` names a method the class does + not have, since the type then has no layout. + + """ + name = self._lookup_registry(self.__field__, field_type) + schema = Schema_Field.registry[field_type] # pylint: disable=unsubscriptable-object + if name == 'unknown' or schema is Schema_Unknown: + return None + if not isinstance(name, str): + return name[0], name[1], schema + parser = getattr(self, f'_read_field_{name}', None) + constructor = getattr(self, f'_make_field_{name}', None) + if parser is None or constructor is None: + return None + return parser, constructor, schema + + @staticmethod + def _field_size(schema: 'Type[Schema]') -> 'tuple[int, bool]': + """Size the fields of ``schema``, a radiotap field or a part of one. + + Args: + schema: the schema + + Returns: + The octets of its fields up to the first whose length is not + fixed, a list taking the rest of what holds the field, and whether + there is one. + + """ + size = 0 + for field in schema.__fields__.values(): + if field.length < 0: + return size, True + size += field.length + return size, False + + def _read_present_field(self, field_type: 'Enum_FieldType', fields: 'bytes', pos: 'int', + start: 'int') -> 'Optional[tuple[Data_Field, int]]': + """Decode a field of the radiotap namespace a presence bit selects. + + Args: + field_type: type of the field + fields: The field-data region. + pos: Offset in ``fields`` where the field may start, before + alignment. + start: Offset of ``fields`` from the start of the header. + + Returns: + The field, and the offset in ``fields`` just past it; an + :class:`~pcapkit.protocols.data.link.radiotap.Unknown` entry of the + rest of ``fields`` for a type with no layout, or one that only a + TLV carries; :obj:`None` if the field runs past ``fields``. + + """ + layout = None if field_type >= Enum_FieldType.TLV_fields_in_radiotap else self._lookup_field(field_type) + if layout is None or self._field_size(layout[2])[1]: + return self._read_field_unknown(field_type, Schema_Unknown(data=fields[pos:])), len(fields) + + parser, _, schema = layout + size, _ = self._field_size(schema) + offset = pos + pad_length(start + pos, schema.__align__) + data = fields[offset:offset + size] + if len(data) != size: + return None + return parser(field_type, schema.unpack(data, size, None)), offset + size # type: ignore[call-arg,misc] + + def _make_subfield(self, field_type: 'Enum_FieldType', schema: 'Type[Schema]', + entry: 'Mapping[str, Any]', name: 'str') -> 'int': + """Check an integer subfield of ``entry`` against the field of ``schema`` that holds it. + + Args: + field_type: type of the field, for the error message + schema: field schema + entry: a data model or a mapping holding the subfield + name: name of the subfield + + Returns: + The subfield's value, as a plain :class:`int`. + + Raises: + ProtocolError: If the subfield is missing, or does not fit in its + field, signed as the field is. + + """ + what = f'{field_type.name}.{name}' + if name not in entry: + raise ProtocolError(f'{self.alias}: invalid fields: {what} missing') + field = schema.__fields__[name] + if getattr(field, '__signed__', None): + return self._make_sint(entry[name], bits=8 * field.length, name=what) + return self._make_uint(entry[name], bits=8 * field.length, name=what) + + def _make_subfield_list(self, field_type: 'Enum_FieldType', schema: 'Type[Schema]', + entry: 'Mapping[str, Any]', name: 'str') -> 'tuple[int, ...]': + """Check a list subfield of ``entry`` against the field of ``schema`` that holds it. + + Args: + field_type: type of the field, for the error message + schema: field schema + entry: a data model or a mapping holding the subfield + name: name of the subfield + + Returns: + The subfield's values. + + Raises: + ProtocolError: If the subfield is missing, is not a list or tuple + of as many values as its field holds, or a value does not fit. + + """ + what = f'{field_type.name}.{name}' + if name not in entry: + raise ProtocolError(f'{self.alias}: invalid fields: {what} missing') + value = entry[name] + field = schema.__fields__[name] + # NOTE: ``ListField`` keeps its item field private; its width is what + # a value has to fit in, and the list's length is the count of values. + item = field._item_type if isinstance(field, ListField) else None # pylint: disable=protected-access + if not isinstance(value, (list, tuple)) or item is None: + raise ProtocolError(f'{self.alias}: invalid {what}: {value!r}, must be a list of values') + if field.length >= 0 and len(value) * item.length != field.length: + raise ProtocolError(f'{self.alias}: invalid {what}: {value!r}, ' + f'must have {field.length // item.length} values') + return tuple(self._make_uint(number, bits=8 * item.length, name=what) for number in value) + + def _read_vendor_namespace(self, field_type: 'Enum_FieldType', fields: 'bytes', pos: 'int', + start: 'int') -> 'Optional[tuple[Data_VendorNamespace, int]]': + """Decode a Vendor Namespace field and its vendor data. + + Args: + field_type: type of the field + fields: The field-data region. + pos: Offset in ``fields`` where the field may start, before + alignment. + start: Offset of ``fields`` from the start of the header. + + Returns: + The field, and the offset in ``fields`` just past its data; + :obj:`None` if either runs past ``fields``. + + """ + size, _ = self._field_size(Schema_VendorNamespace) + offset = pos + pad_length(start + pos, Schema_VendorNamespace.__align__) + header = fields[offset:offset + size] + if len(header) != size: + return None + schema = cast('Schema_VendorNamespace', + Schema_VendorNamespace.unpack(header, size, None)) # type: ignore[call-arg,misc] + end = offset + size + schema.skip_length + if end > len(fields): + return None + return Data_VendorNamespace( + type=field_type, + oui=schema.oui, + sub_namespace=schema.sub_namespace, + skip_length=schema.skip_length, + data=fields[offset + size:end], + ), end + + def _make_vendor_namespace(self, entry: 'Data_VendorNamespace | Mapping[str, Any]', pos: 'int') -> 'bytes': + """Encode a Vendor Namespace field, the inverse of :meth:`_read_vendor_namespace`. + + Args: + entry: The field, a data model or a mapping of its subfields; its + ``skip_length`` may be left out. + pos: Offset from the start of the header where the field may + start, before alignment. + + Returns: + The alignment padding, the field and its vendor data. + + Raises: + ProtocolError: If ``oui`` is not 3 octets, ``data`` is not + :class:`bytes`, ``skip_length`` is not its length, or a + subfield does not fit. + + """ + field_type = cast('Enum_FieldType', Enum_FieldType.Vendor_Namespace) + oui, data = self._make_vendor_data(field_type, Schema_VendorNamespace, entry) + values = {**entry, 'skip_length': entry.get('skip_length', len(data))} + if values['skip_length'] != len(data): + raise ProtocolError(f'{self.alias}: invalid Vendor_Namespace.skip_length: {values["skip_length"]!r}, ' + f'data has {len(data)} octets') + schema = Schema_VendorNamespace( + oui=oui, + sub_namespace=self._make_subfield(field_type, Schema_VendorNamespace, values, 'sub_namespace'), + skip_length=self._make_subfield(field_type, Schema_VendorNamespace, values, 'skip_length'), + ) + return bytes(pad_length(pos, Schema_VendorNamespace.__align__)) + schema.pack() + data + + def _read_tlv_fields(self, field_type: 'Enum_FieldType', fields: 'bytes', pos: 'int', + start: 'int') -> 'Optional[tuple[Data_TLVFields, int]]': + """Decode the TLV fields, which fill the rest of the field-data region. + + Args: + field_type: type of the field + fields: The field-data region. + pos: Offset in ``fields`` where the TLV fields may start, before + alignment. + start: Offset of ``fields`` from the start of the header. + + Returns: + The TLV fields, and the length of ``fields``; :obj:`None` if an + item runs past ``fields``. Padding the end of ``fields`` cuts + short is not required. + + """ + size, _ = self._field_size(Schema_TLV) + offset = pos + pad_length(start + pos, Schema_TLV.__align__) + if offset > len(fields): + return None + tlvs = [] # type: list[Data_TLV] + while offset < len(fields): + header = fields[offset:offset + size] + if len(header) != size: + return None + schema = cast('Schema_TLV', Schema_TLV.unpack(header, size, None)) # type: ignore[call-arg,misc] + data = fields[offset + size:offset + size + schema.length] + if len(data) != schema.length: + return None + tlvs.append(Data_TLV(type=schema.type, length=schema.length, + data=self._read_tlv_data(schema.type, data))) + offset += size + len(data) + pad_length(len(data), Schema_TLV.__align__) + return Data_TLVFields(type=field_type, tlvs=tuple(tlvs)), len(fields) + + def _make_tlv_fields(self, entry: 'Data_TLVFields | Mapping[str, Any]', pos: 'int') -> 'bytes': + """Encode the TLV fields, the inverse of :meth:`_read_tlv_fields`. + + Args: + entry: The TLV fields, a data model or a mapping whose ``tlvs`` + are data models or mappings of ``type``, ``data`` and, + optionally, ``length``. + pos: Offset from the start of the header where the TLV fields + may start, before alignment. + + Returns: + The alignment padding and the items, each padded. + + Raises: + ProtocolError: If an item's ``length`` is not that of its data, + or a subfield or its data does not encode. + + """ + out = bytearray(pad_length(pos, Schema_TLV.__align__)) + for item in entry.get('tlvs', ()): + tlv_type = Enum_FieldType.get(item['type']) + data = self._make_tlv_data(tlv_type, item['data']) + if item.get('length', len(data)) != len(data): + raise ProtocolError(f'{self.alias}: invalid TLV.length: {item["length"]!r}, ' + f'data has {len(data)} octets') + values = {'type': tlv_type, 'length': len(data)} + field_type = cast('Enum_FieldType', Enum_FieldType.TLV_fields_in_radiotap) + out += Schema_TLV( + type=self._make_subfield(field_type, Schema_TLV, values, 'type'), + length=self._make_subfield(field_type, Schema_TLV, values, 'length'), + ).pack() + out += data + bytes(pad_length(len(data), Schema_TLV.__align__)) + return bytes(out) + + def _read_tlv_data(self, tlv_type: 'Enum_FieldType', data: 'bytes') -> 'Data_Field | Data_VendorTLV | bytes': + """Decode a TLV item's data. + + Args: + tlv_type: Type of the item. + data: The item's data. + + Returns: + A vendor TLV for the Vendor Namespace type, the field for a type + whose schema ``data`` fills exactly, and the raw octets otherwise. + + """ + if tlv_type == Enum_FieldType.Vendor_Namespace: + size, _ = self._field_size(Schema_VendorTLV) + if len(data) < size: + return data + vendor = cast('Schema_VendorTLV', + Schema_VendorTLV.unpack(data[:size], size, None)) # type: ignore[call-arg,misc] + return Data_VendorTLV(oui=vendor.oui, subtype=vendor.subtype, presence_type=vendor.presence_type, + reserved=vendor.reserved, data=data[size:]) + + layout = self._lookup_field(tlv_type) + if layout is None: + return data + parser, _, field_schema = layout + size, rest = self._field_size(field_schema) + if len(data) < size or (not rest and len(data) != size): + return data + # NOTE: a list taking the rest refuses octets that are not whole items + # of it; the refusal is handled here, so it is quiet. + with CaughtByCaller(FieldValueError): + try: + schema = cast('Schema_Field', field_schema.unpack(data, len(data), None)) # type: ignore[call-arg,misc] + except FieldValueError: + return data + return parser(tlv_type, schema) + + def _make_tlv_data(self, tlv_type: 'Enum_FieldType', + data: 'Data_Field | Data_VendorTLV | Mapping[str, Any] | bytes') -> 'bytes': + """Encode a TLV item's data, the inverse of :meth:`_read_tlv_data`. + + Args: + tlv_type: Type of the item. + data: The item's data: raw octets, written as they are, or decoded. + + Returns: + The item's data. + + Raises: + ProtocolError: If decoded data is given for a type with no layout, + or does not encode. + + """ + if isinstance(data, (bytes, bytearray)): + return bytes(data) + if tlv_type == Enum_FieldType.Vendor_Namespace: + oui, vendor_data = self._make_vendor_data(tlv_type, Schema_VendorTLV, data) + values = {'reserved': 0, **data} + return Schema_VendorTLV( + oui=oui, + subtype=self._make_subfield(tlv_type, Schema_VendorTLV, values, 'subtype'), + presence_type=self._make_subfield(tlv_type, Schema_VendorTLV, values, 'presence_type'), + reserved=self._make_subfield(tlv_type, Schema_VendorTLV, values, 'reserved'), + ).pack() + vendor_data + layout = self._lookup_field(tlv_type) + if layout is None: + raise ProtocolError(f'{self.alias}: invalid TLV.data: {tlv_type!r} defines no layout, ' + 'so its data must be bytes') + return layout[1](tlv_type, data).pack() + + def _make_vendor_data(self, field_type: 'Enum_FieldType', schema: 'Type[Schema]', + entry: 'Mapping[str, Any]') -> 'tuple[bytes, bytes]': + """Check the OUI and the vendor data of a vendor namespace or a vendor TLV. + + Args: + field_type: type of the field, for the error message + schema: schema of the vendor header, whose ``oui`` the OUI fills + entry: A data model or a mapping holding ``oui`` and ``data``, + which may be left out for none. + + Returns: + The OUI and the vendor data. + + Raises: + ProtocolError: If ``oui`` is not as many octets as its field, or + ``data`` is not :class:`bytes`. + + """ + what = 'VendorTLV' if schema is Schema_VendorTLV else field_type.name + oui = entry.get('oui') + size = schema.__fields__['oui'].length + if not isinstance(oui, (bytes, bytearray)) or len(oui) != size: + raise ProtocolError(f'{self.alias}: invalid {what}.oui: {oui!r}, must be {size} octets') + data = entry.get('data', b'') + if not isinstance(data, (bytes, bytearray)): + raise ProtocolError(f'{self.alias}: invalid {what}.data: {data!r}, must be bytes') + return bytes(oui), bytes(data) diff --git a/pcapkit/protocols/schema/__init__.py b/pcapkit/protocols/schema/__init__.py index 5e75df69f6..b7a1ad579f 100644 --- a/pcapkit/protocols/schema/__init__.py +++ b/pcapkit/protocols/schema/__init__.py @@ -35,6 +35,15 @@ 'Loopback', 'Netlink', 'Radiotap', + 'Radiotap_Field', 'Radiotap_Unknown', 'Radiotap_TSFT', 'Radiotap_Flags', 'Radiotap_Rate', + 'Radiotap_Channel', 'Radiotap_FHSS', 'Radiotap_AntennaSignal', 'Radiotap_AntennaNoise', + 'Radiotap_LockQuality', 'Radiotap_TXAttenuation', 'Radiotap_DBTXAttenuation', + 'Radiotap_DBmTXPower', 'Radiotap_Antenna', 'Radiotap_DBAntennaSignal', + 'Radiotap_DBAntennaNoise', 'Radiotap_RXFlags', 'Radiotap_TXFlags', 'Radiotap_RTSRetries', + 'Radiotap_DataRetries', 'Radiotap_MCS', 'Radiotap_AMPDUStatus', 'Radiotap_VHT', + 'Radiotap_Timestamp', 'Radiotap_HE', 'Radiotap_HEMU', 'Radiotap_HEMUOtherUser', + 'Radiotap_ZeroLengthPSDU', 'Radiotap_LSIG', 'Radiotap_VendorNamespace', 'Radiotap_S1G', + 'Radiotap_USIG', 'Radiotap_EHT', 'Radiotap_TLV', 'Radiotap_VendorTLV', 'VLAN', 'VLAN_TCI', # Internet Layer Protocols diff --git a/pcapkit/protocols/schema/link/__init__.py b/pcapkit/protocols/schema/link/__init__.py index 8e8e04b905..1e058d0800 100644 --- a/pcapkit/protocols/schema/link/__init__.py +++ b/pcapkit/protocols/schema/link/__init__.py @@ -11,7 +11,42 @@ from pcapkit.protocols.schema.link.linux_sll2 import LinuxSLL2 from pcapkit.protocols.schema.link.loopback import Loopback from pcapkit.protocols.schema.link.netlink import Netlink +from pcapkit.protocols.schema.link.radiotap import EHT as Radiotap_EHT +from pcapkit.protocols.schema.link.radiotap import FHSS as Radiotap_FHSS +from pcapkit.protocols.schema.link.radiotap import HE as Radiotap_HE +from pcapkit.protocols.schema.link.radiotap import HEMU as Radiotap_HEMU +from pcapkit.protocols.schema.link.radiotap import LSIG as Radiotap_LSIG +from pcapkit.protocols.schema.link.radiotap import MCS as Radiotap_MCS +from pcapkit.protocols.schema.link.radiotap import S1G as Radiotap_S1G +from pcapkit.protocols.schema.link.radiotap import TLV as Radiotap_TLV +from pcapkit.protocols.schema.link.radiotap import TSFT as Radiotap_TSFT +from pcapkit.protocols.schema.link.radiotap import USIG as Radiotap_USIG +from pcapkit.protocols.schema.link.radiotap import VHT as Radiotap_VHT +from pcapkit.protocols.schema.link.radiotap import AMPDUStatus as Radiotap_AMPDUStatus +from pcapkit.protocols.schema.link.radiotap import Antenna as Radiotap_Antenna +from pcapkit.protocols.schema.link.radiotap import AntennaNoise as Radiotap_AntennaNoise +from pcapkit.protocols.schema.link.radiotap import AntennaSignal as Radiotap_AntennaSignal +from pcapkit.protocols.schema.link.radiotap import Channel as Radiotap_Channel +from pcapkit.protocols.schema.link.radiotap import DataRetries as Radiotap_DataRetries +from pcapkit.protocols.schema.link.radiotap import DBAntennaNoise as Radiotap_DBAntennaNoise +from pcapkit.protocols.schema.link.radiotap import DBAntennaSignal as Radiotap_DBAntennaSignal +from pcapkit.protocols.schema.link.radiotap import DBmTXPower as Radiotap_DBmTXPower +from pcapkit.protocols.schema.link.radiotap import DBTXAttenuation as Radiotap_DBTXAttenuation +from pcapkit.protocols.schema.link.radiotap import Flags as Radiotap_Flags +from pcapkit.protocols.schema.link.radiotap import HEMUOtherUser as Radiotap_HEMUOtherUser +from pcapkit.protocols.schema.link.radiotap import LockQuality as Radiotap_LockQuality from pcapkit.protocols.schema.link.radiotap import Radiotap +from pcapkit.protocols.schema.link.radiotap import RadiotapField as Radiotap_Field +from pcapkit.protocols.schema.link.radiotap import Rate as Radiotap_Rate +from pcapkit.protocols.schema.link.radiotap import RTSRetries as Radiotap_RTSRetries +from pcapkit.protocols.schema.link.radiotap import RXFlags as Radiotap_RXFlags +from pcapkit.protocols.schema.link.radiotap import Timestamp as Radiotap_Timestamp +from pcapkit.protocols.schema.link.radiotap import TXAttenuation as Radiotap_TXAttenuation +from pcapkit.protocols.schema.link.radiotap import TXFlags as Radiotap_TXFlags +from pcapkit.protocols.schema.link.radiotap import Unknown as Radiotap_Unknown +from pcapkit.protocols.schema.link.radiotap import VendorNamespace as Radiotap_VendorNamespace +from pcapkit.protocols.schema.link.radiotap import VendorTLV as Radiotap_VendorTLV +from pcapkit.protocols.schema.link.radiotap import ZeroLengthPSDU as Radiotap_ZeroLengthPSDU from pcapkit.protocols.schema.link.vlan import TCI as VLAN_TCI from pcapkit.protocols.schema.link.vlan import VLAN @@ -26,5 +61,14 @@ 'Loopback', 'Netlink', 'Radiotap', + 'Radiotap_Field', 'Radiotap_Unknown', 'Radiotap_TSFT', 'Radiotap_Flags', 'Radiotap_Rate', + 'Radiotap_Channel', 'Radiotap_FHSS', 'Radiotap_AntennaSignal', 'Radiotap_AntennaNoise', + 'Radiotap_LockQuality', 'Radiotap_TXAttenuation', 'Radiotap_DBTXAttenuation', + 'Radiotap_DBmTXPower', 'Radiotap_Antenna', 'Radiotap_DBAntennaSignal', + 'Radiotap_DBAntennaNoise', 'Radiotap_RXFlags', 'Radiotap_TXFlags', 'Radiotap_RTSRetries', + 'Radiotap_DataRetries', 'Radiotap_MCS', 'Radiotap_AMPDUStatus', 'Radiotap_VHT', + 'Radiotap_Timestamp', 'Radiotap_HE', 'Radiotap_HEMU', 'Radiotap_HEMUOtherUser', + 'Radiotap_ZeroLengthPSDU', 'Radiotap_LSIG', 'Radiotap_VendorNamespace', 'Radiotap_S1G', + 'Radiotap_USIG', 'Radiotap_EHT', 'Radiotap_TLV', 'Radiotap_VendorTLV', 'VLAN', 'VLAN_TCI', ] diff --git a/pcapkit/protocols/schema/link/radiotap.py b/pcapkit/protocols/schema/link/radiotap.py index 3d41bd9cf6..3f268ddb3c 100644 --- a/pcapkit/protocols/schema/link/radiotap.py +++ b/pcapkit/protocols/schema/link/radiotap.py @@ -4,13 +4,45 @@ from typing import TYPE_CHECKING +from pcapkit.const.radiotap.ampdu_flags import AMPDUFlags as Enum_AMPDUFlags +from pcapkit.const.radiotap.channel_flags import ChannelFlags as Enum_ChannelFlags +from pcapkit.const.radiotap.eht_known import EHTKnown as Enum_EHTKnown +from pcapkit.const.radiotap.field_type import FieldType as Enum_FieldType +from pcapkit.const.radiotap.flags import Flags as Enum_Flags +from pcapkit.const.radiotap.he_mu_other_user_known import \ + HEMUOtherUserKnown as Enum_HEMUOtherUserKnown +from pcapkit.const.radiotap.lsig_data1 import LSIGData1 as Enum_LSIGData1 +from pcapkit.const.radiotap.mcs_known import MCSKnown as Enum_MCSKnown +from pcapkit.const.radiotap.rx_flags import RXFlags as Enum_RXFlags +from pcapkit.const.radiotap.s1g_known import S1GKnown as Enum_S1GKnown +from pcapkit.const.radiotap.timestamp_flags import TimestampFlags as Enum_TimestampFlags +from pcapkit.const.radiotap.tx_flags import TXFlags as Enum_TXFlags +from pcapkit.const.radiotap.vht_coding import VHTCoding as Enum_VHTCoding +from pcapkit.const.radiotap.vht_flags import VHTFlags as Enum_VHTFlags +from pcapkit.const.radiotap.vht_known import VHTKnown as Enum_VHTKnown +from pcapkit.corekit.fields.collections import ListField from pcapkit.corekit.fields.misc import PayloadField -from pcapkit.corekit.fields.numbers import UInt8Field, UInt16Field, UInt32Field -from pcapkit.protocols.schema.schema import Schema, schema_final +from pcapkit.corekit.fields.numbers import (EnumField, Int8Field, UInt8Field, UInt16Field, + UInt32Field, UInt64Field) +from pcapkit.corekit.fields.strings import BytesField +from pcapkit.protocols.schema.schema import EnumSchema, Schema, schema_final -__all__ = ['Radiotap'] +__all__ = [ + 'Radiotap', + + 'RadiotapField', 'Unknown', + 'TSFT', 'Flags', 'Rate', 'Channel', 'FHSS', 'AntennaSignal', 'AntennaNoise', + 'LockQuality', 'TXAttenuation', 'DBTXAttenuation', 'DBmTXPower', 'Antenna', + 'DBAntennaSignal', 'DBAntennaNoise', 'RXFlags', 'TXFlags', 'RTSRetries', 'DataRetries', + 'MCS', 'AMPDUStatus', + 'VHT', 'Timestamp', 'HE', 'HEMU', 'HEMUOtherUser', 'ZeroLengthPSDU', 'LSIG', + 'VendorNamespace', 'S1G', 'USIG', 'EHT', + 'TLV', 'VendorTLV', +] if TYPE_CHECKING: + from typing import ClassVar + from pcapkit.protocols.protocol import ProtocolBase @@ -25,7 +57,8 @@ class Radiotap(Schema): 802.11 MAC frame behind it -- is captured together as :attr:`payload`, since where one ends and the next begins is only known once the present-flags chain itself has been walked; see :meth:`Radiotap.read - `. + `. Each field in the + region is a :class:`RadiotapField` of its own. """ @@ -44,3 +77,547 @@ class Radiotap(Schema): def __init__(self, it_version: 'int', it_pad: 'int', it_len: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements it_present: 'int', # pylint: disable=unused-argument payload: 'bytes | ProtocolBase | Schema') -> 'None': ... # pylint: disable=unused-argument + + +class RadiotapField(EnumSchema[Enum_FieldType]): + """Header schema for a radiotap field, little-endian on the wire. + + A subclass registered with a field type is the layout of that type's field, + as its page on radiotap.org gives it: its subfields are the schema's fields, + its size their total, and its alignment :attr:`__align__`. A field a + presence bit selects has a fixed size. + + """ + + __default__ = lambda: Unknown + __additional__ = ['__align__'] + __excluded__ = ['__align__'] + + #: Alignment of the field, in octets counted from the start of the header. + __align__: 'ClassVar[int]' = 1 + + +@schema_final +class Unknown(RadiotapField): + """Header schema for an octet run a field type does not decode, kept whole.""" + + #: The octets, to the end of the field-data region. + data: 'bytes' = BytesField(length=lambda pkt: pkt['__length__']) + + if TYPE_CHECKING: + def __init__(self, data: 'bytes') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class TSFT(RadiotapField, code=Enum_FieldType.TSFT): + """Header schema for the TSFT field, bit 0.""" + + __align__ = 8 + + #: Time Synchronization Function timer, in microseconds. + mactime: 'int' = UInt64Field(byteorder='little') + + if TYPE_CHECKING: + def __init__(self, mactime: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class Flags(RadiotapField, code=Enum_FieldType.Flags): + """Header schema for the Flags field, bit 1.""" + + #: Properties of the frame. + flags: 'Enum_Flags' = EnumField(length=1, namespace=Enum_Flags) + + if TYPE_CHECKING: + def __init__(self, flags: 'Enum_Flags | int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class Rate(RadiotapField, code=Enum_FieldType.Rate): + """Header schema for the Rate field, bit 2.""" + + #: TX/RX data rate, in 500 kbps. + rate: 'int' = UInt8Field() + + if TYPE_CHECKING: + def __init__(self, rate: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class Channel(RadiotapField, code=Enum_FieldType.Channel): + """Header schema for the Channel field, bit 3.""" + + __align__ = 2 + + #: TX/RX frequency, in MHz. + frequency: 'int' = UInt16Field(byteorder='little') + #: Channel flags. + flags: 'Enum_ChannelFlags' = EnumField(length=2, byteorder='little', namespace=Enum_ChannelFlags) + + if TYPE_CHECKING: + def __init__(self, frequency: 'int', flags: 'Enum_ChannelFlags | int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class FHSS(RadiotapField, code=Enum_FieldType.FHSS): + """Header schema for the FHSS field, bit 4. + + Its page names no alignment; the Linux kernel, Wireshark and + radiotap-library align it to 2. + + """ + + __align__ = 2 + + #: Hop set. + hop_set: 'int' = UInt8Field() + #: Hop pattern. + hop_pattern: 'int' = UInt8Field() + + if TYPE_CHECKING: + def __init__(self, hop_set: 'int', hop_pattern: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class AntennaSignal(RadiotapField, code=Enum_FieldType.Antenna_signal): + """Header schema for the Antenna signal field, bit 5.""" + + #: RF signal power at the antenna, in dBm. + signal: 'int' = Int8Field() + + if TYPE_CHECKING: + def __init__(self, signal: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class AntennaNoise(RadiotapField, code=Enum_FieldType.Antenna_noise): + """Header schema for the Antenna noise field, bit 6.""" + + #: RF noise power at the antenna, in dBm. + noise: 'int' = Int8Field() + + if TYPE_CHECKING: + def __init__(self, noise: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class LockQuality(RadiotapField, code=Enum_FieldType.Lock_quality): + """Header schema for the Lock quality field, bit 7.""" + + __align__ = 2 + + #: Quality of Barker code lock. + quality: 'int' = UInt16Field(byteorder='little') + + if TYPE_CHECKING: + def __init__(self, quality: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class TXAttenuation(RadiotapField, code=Enum_FieldType.TX_attenuation): + """Header schema for the TX attenuation field, bit 8.""" + + __align__ = 2 + + #: Transmit power below the maximum, unitless. + attenuation: 'int' = UInt16Field(byteorder='little') + + if TYPE_CHECKING: + def __init__(self, attenuation: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class DBTXAttenuation(RadiotapField, code=Enum_FieldType.dB_TX_attenuation): + """Header schema for the dB TX attenuation field, bit 9.""" + + __align__ = 2 + + #: Transmit power below the maximum, in dB. + attenuation: 'int' = UInt16Field(byteorder='little') + + if TYPE_CHECKING: + def __init__(self, attenuation: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class DBmTXPower(RadiotapField, code=Enum_FieldType.dBm_TX_power): + """Header schema for the dBm TX power field, bit 10.""" + + #: Transmit power, in dBm. + power: 'int' = Int8Field() + + if TYPE_CHECKING: + def __init__(self, power: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class Antenna(RadiotapField, code=Enum_FieldType.Antenna): + """Header schema for the Antenna field, bit 11.""" + + #: Antenna index. + antenna: 'int' = UInt8Field() + + if TYPE_CHECKING: + def __init__(self, antenna: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class DBAntennaSignal(RadiotapField, code=Enum_FieldType.dB_antenna_signal): + """Header schema for the dB antenna signal field, bit 12.""" + + #: RF signal power at the antenna, in dB from an arbitrary reference. + signal: 'int' = UInt8Field() + + if TYPE_CHECKING: + def __init__(self, signal: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class DBAntennaNoise(RadiotapField, code=Enum_FieldType.dB_antenna_noise): + """Header schema for the dB antenna noise field, bit 13.""" + + #: RF noise power at the antenna, in dB from an arbitrary reference. + noise: 'int' = UInt8Field() + + if TYPE_CHECKING: + def __init__(self, noise: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class RXFlags(RadiotapField, code=Enum_FieldType.RX_flags): + """Header schema for the RX flags field, bit 14.""" + + __align__ = 2 + + #: Properties of the received frame. + flags: 'Enum_RXFlags' = EnumField(length=2, byteorder='little', namespace=Enum_RXFlags) + + if TYPE_CHECKING: + def __init__(self, flags: 'Enum_RXFlags | int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class TXFlags(RadiotapField, code=Enum_FieldType.TX_flags): + """Header schema for the TX flags field, bit 15.""" + + __align__ = 2 + + #: Properties of the transmitted frame. + flags: 'Enum_TXFlags' = EnumField(length=2, byteorder='little', namespace=Enum_TXFlags) + + if TYPE_CHECKING: + def __init__(self, flags: 'Enum_TXFlags | int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class RTSRetries(RadiotapField, code=Enum_FieldType.RTS_retries): + """Header schema for the RTS retries field, bit 16, from radiotap.org's unofficial fields.""" + + #: RTS retries. + retries: 'int' = UInt8Field() + + if TYPE_CHECKING: + def __init__(self, retries: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class DataRetries(RadiotapField, code=Enum_FieldType.data_retries): + """Header schema for the data retries field, bit 17, from radiotap.org's unofficial fields.""" + + #: Data retries. + retries: 'int' = UInt8Field() + + if TYPE_CHECKING: + def __init__(self, retries: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class MCS(RadiotapField, code=Enum_FieldType.MCS): + """Header schema for the MCS field, bit 19.""" + + #: Which of :attr:`flags` and :attr:`mcs` are known. + known: 'Enum_MCSKnown' = EnumField(length=1, namespace=Enum_MCSKnown) + #: Flags, which hold value subfields. + flags: 'int' = UInt8Field() + #: MCS rate index. + mcs: 'int' = UInt8Field() + + if TYPE_CHECKING: + def __init__(self, known: 'Enum_MCSKnown | int', flags: 'int', mcs: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class AMPDUStatus(RadiotapField, code=Enum_FieldType.A_MPDU_status): + """Header schema for the A-MPDU status field, bit 20.""" + + __align__ = 4 + + #: Reference number of the A-MPDU. + reference: 'int' = UInt32Field(byteorder='little') + #: Flags. + flags: 'Enum_AMPDUFlags' = EnumField(length=2, byteorder='little', namespace=Enum_AMPDUFlags) + #: A-MPDU subframe delimiter CRC. + delimiter_crc: 'int' = UInt8Field() + #: Reserved. + reserved: 'int' = UInt8Field() + + if TYPE_CHECKING: + def __init__(self, reference: 'int', flags: 'Enum_AMPDUFlags | int', delimiter_crc: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements + reserved: 'int') -> 'None': ... # pylint: disable=unused-argument + + +@schema_final +class VHT(RadiotapField, code=Enum_FieldType.VHT): + """Header schema for the VHT field, bit 21.""" + + __align__ = 2 + + #: Which of the subfields are known. + known: 'Enum_VHTKnown' = EnumField(length=2, byteorder='little', namespace=Enum_VHTKnown) + #: Flags. + flags: 'Enum_VHTFlags' = EnumField(length=1, namespace=Enum_VHTFlags) + #: Bandwidth. + bandwidth: 'int' = UInt8Field() + #: MCS and NSS of each of the four users. + mcs_nss: 'list[int]' = ListField(length=4, item_type=UInt8Field()) + #: FEC coding of each user. + coding: 'Enum_VHTCoding' = EnumField(length=1, namespace=Enum_VHTCoding) + #: Group ID. + group_id: 'int' = UInt8Field() + #: Partial AID. + partial_aid: 'int' = UInt16Field(byteorder='little') + + if TYPE_CHECKING: + def __init__(self, known: 'Enum_VHTKnown | int', flags: 'Enum_VHTFlags | int', bandwidth: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements + mcs_nss: 'list[int] | tuple[int, ...]', coding: 'Enum_VHTCoding | int', # pylint: disable=unused-argument + group_id: 'int', partial_aid: 'int') -> 'None': ... # pylint: disable=unused-argument + + +@schema_final +class Timestamp(RadiotapField, code=Enum_FieldType.timestamp): + """Header schema for the timestamp field, bit 22.""" + + __align__ = 8 + + #: Timestamp. + timestamp: 'int' = UInt64Field(byteorder='little') + #: Accuracy, in nanoseconds. + accuracy: 'int' = UInt16Field(byteorder='little') + #: Unit and sampling position. + unit_position: 'int' = UInt8Field() + #: Flags. + flags: 'Enum_TimestampFlags' = EnumField(length=1, namespace=Enum_TimestampFlags) + + if TYPE_CHECKING: + def __init__(self, timestamp: 'int', accuracy: 'int', unit_position: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements + flags: 'Enum_TimestampFlags | int') -> 'None': ... # pylint: disable=unused-argument + + +@schema_final +class HE(RadiotapField, code=Enum_FieldType.HE): + """Header schema for the HE field, bit 23.""" + + __align__ = 2 + + #: Format and which other subfields are known. + data1: 'int' = UInt16Field(byteorder='little') + #: Second data word. + data2: 'int' = UInt16Field(byteorder='little') + #: Third data word. + data3: 'int' = UInt16Field(byteorder='little') + #: Fourth data word. + data4: 'int' = UInt16Field(byteorder='little') + #: Fifth data word. + data5: 'int' = UInt16Field(byteorder='little') + #: Sixth data word. + data6: 'int' = UInt16Field(byteorder='little') + + if TYPE_CHECKING: + def __init__(self, data1: 'int', data2: 'int', data3: 'int', data4: 'int', data5: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements + data6: 'int') -> 'None': ... # pylint: disable=unused-argument + + +@schema_final +class HEMU(RadiotapField, code=Enum_FieldType.HE_MU): + """Header schema for the HE-MU field, bit 24.""" + + __align__ = 2 + + #: First flags word. + flags1: 'int' = UInt16Field(byteorder='little') + #: Second flags word. + flags2: 'int' = UInt16Field(byteorder='little') + #: RU allocation of channel 1. + ru_channel1: 'list[int]' = ListField(length=4, item_type=UInt8Field()) + #: RU allocation of channel 2. + ru_channel2: 'list[int]' = ListField(length=4, item_type=UInt8Field()) + + if TYPE_CHECKING: + def __init__(self, flags1: 'int', flags2: 'int', ru_channel1: 'list[int] | tuple[int, ...]', # pylint: disable=unused-argument,super-init-not-called,multiple-statements + ru_channel2: 'list[int] | tuple[int, ...]') -> 'None': ... # pylint: disable=unused-argument + + +@schema_final +class HEMUOtherUser(RadiotapField, code=Enum_FieldType.HE_MU_other_user): + """Header schema for the HE-MU-other-user field, bit 25.""" + + __align__ = 2 + + #: First per-user word. + per_user_1: 'int' = UInt16Field(byteorder='little') + #: Second per-user word. + per_user_2: 'int' = UInt16Field(byteorder='little') + #: Position of the user. + per_user_position: 'int' = UInt8Field() + #: Which of the per-user subfields are known. + per_user_known: 'Enum_HEMUOtherUserKnown' = EnumField(length=1, namespace=Enum_HEMUOtherUserKnown) + + if TYPE_CHECKING: + def __init__(self, per_user_1: 'int', per_user_2: 'int', per_user_position: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements + per_user_known: 'Enum_HEMUOtherUserKnown | int') -> 'None': ... # pylint: disable=unused-argument + + +@schema_final +class ZeroLengthPSDU(RadiotapField, code=Enum_FieldType.FieldType_0_length_PSDU): + """Header schema for the 0-length-PSDU field, bit 26.""" + + #: Why no PSDU was captured. + psdu_type: 'int' = UInt8Field() + + if TYPE_CHECKING: + def __init__(self, psdu_type: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class LSIG(RadiotapField, code=Enum_FieldType.L_SIG): + """Header schema for the L-SIG field, bit 27.""" + + __align__ = 2 + + #: Which of the subfields of :attr:`data2` are known. + data1: 'Enum_LSIGData1' = EnumField(length=2, byteorder='little', namespace=Enum_LSIGData1) + #: Rate and length. + data2: 'int' = UInt16Field(byteorder='little') + + if TYPE_CHECKING: + def __init__(self, data1: 'Enum_LSIGData1 | int', data2: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class VendorNamespace(RadiotapField): + """Header schema for the Vendor Namespace field, bit 30. + + The vendor data it gives the length of follows it, and is not a subfield of + its own; nor is the schema registered, since a vendor namespace TLV is a + :class:`VendorTLV` instead. + + """ + + __align__ = 2 + + #: OUI of the vendor. + oui: 'bytes' = BytesField(length=3) + #: Sub-namespace of the vendor's. + sub_namespace: 'int' = UInt8Field() + #: Octets of vendor data that follow. + skip_length: 'int' = UInt16Field(byteorder='little') + + if TYPE_CHECKING: + def __init__(self, oui: 'bytes', sub_namespace: 'int', skip_length: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class S1G(RadiotapField, code=Enum_FieldType.S1G): + """Header schema for the S1G field, type 32, which only a TLV carries.""" + + __align__ = 2 + + #: Which of the subfields are known. + known: 'Enum_S1GKnown' = EnumField(length=2, byteorder='little', namespace=Enum_S1GKnown) + #: First data word. + data1: 'int' = UInt16Field(byteorder='little') + #: Second data word. + data2: 'int' = UInt16Field(byteorder='little') + + if TYPE_CHECKING: + def __init__(self, known: 'Enum_S1GKnown | int', data1: 'int', data2: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class USIG(RadiotapField, code=Enum_FieldType.U_SIG): + """Header schema for the U-SIG field, type 33, which only a TLV carries.""" + + __align__ = 4 + + #: Common subfields, which hold value subfields. + common: 'int' = UInt32Field(byteorder='little') + #: Value of the U-SIG bits. + value: 'int' = UInt32Field(byteorder='little') + #: Which of :attr:`value`'s bits are known. + mask: 'int' = UInt32Field(byteorder='little') + + if TYPE_CHECKING: + def __init__(self, common: 'int', value: 'int', mask: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements + + +@schema_final +class EHT(RadiotapField, code=Enum_FieldType.EHT): + """Header schema for the EHT field, type 34, which only a TLV carries.""" + + __align__ = 4 + + #: Which of the subfields are known. + known: 'Enum_EHTKnown' = EnumField(length=4, byteorder='little', namespace=Enum_EHTKnown) + #: The data words, nine of them. + data: 'list[int]' = ListField(length=36, item_type=UInt32Field(byteorder='little')) + #: One word per user, to the end of the field. + user_info: 'list[int]' = ListField(length=lambda pkt: pkt['__length__'], + item_type=UInt32Field(byteorder='little')) + + if TYPE_CHECKING: + def __init__(self, known: 'Enum_EHTKnown | int', data: 'list[int] | tuple[int, ...]', # pylint: disable=unused-argument,super-init-not-called,multiple-statements + user_info: 'list[int] | tuple[int, ...]') -> 'None': ... # pylint: disable=unused-argument + + +@schema_final +class TLV(RadiotapField): + """Header schema for the type and length opening a TLV item, bit 28. + + The item's data follows, then padding to its + :attr:`~RadiotapField.__align__`, which the TLV list is aligned to as well. + The schema is not registered, since a TLV item is no field of a type of its + own. + + """ + + __align__ = 4 + + #: Type of the item, a field type. + type: 'Enum_FieldType' = EnumField(length=2, byteorder='little', namespace=Enum_FieldType) + #: Octets of the item's data. + length: 'int' = UInt16Field(byteorder='little') + + if TYPE_CHECKING: + def __init__(self, type: 'Enum_FieldType | int', length: 'int') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin + + +@schema_final +class VendorTLV(Schema): + """Header schema for the vendor header opening the data of a vendor namespace TLV item. + + The vendor data follows, to the end of the item. + + """ + + #: OUI of the vendor. + oui: 'bytes' = BytesField(length=3) + #: Sub-namespace of the vendor's. + subtype: 'int' = UInt8Field() + #: Vendor type of the data. + presence_type: 'int' = UInt16Field(byteorder='little') + #: Reserved. + reserved: 'int' = UInt16Field(byteorder='little') + + if TYPE_CHECKING: + def __init__(self, oui: 'bytes', subtype: 'int', presence_type: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements + reserved: 'int') -> 'None': ... # pylint: disable=unused-argument diff --git a/pcapkit/vendor/__init__.py b/pcapkit/vendor/__init__.py index 30c0a08055..58756d5247 100644 --- a/pcapkit/vendor/__init__.py +++ b/pcapkit/vendor/__init__.py @@ -123,6 +123,7 @@ def __getattr__(name: 'str') -> 'typing.NoReturn': from pcapkit.vendor.mh import * from pcapkit.vendor.ngap import * from pcapkit.vendor.ospf import * + from pcapkit.vendor.radiotap import * from pcapkit.vendor.sctp import * from pcapkit.vendor.sslv2 import * from pcapkit.vendor.tcp import * @@ -195,6 +196,11 @@ def __getattr__(name: 'str') -> 'typing.NoReturn': 'NGAP_ProcedureCode', 'NGAP_ProtocolIE', # OSPF 'OSPF_Authentication', 'OSPF_Packet', + # Radiotap + 'Radiotap_FieldType', 'Radiotap_Flags', 'Radiotap_ChannelFlags', 'Radiotap_RXFlags', + 'Radiotap_TXFlags', 'Radiotap_MCSKnown', 'Radiotap_AMPDUFlags', 'Radiotap_VHTKnown', + 'Radiotap_VHTFlags', 'Radiotap_VHTCoding', 'Radiotap_TimestampFlags', + 'Radiotap_HEMUOtherUserKnown', 'Radiotap_LSIGData1', 'Radiotap_S1GKnown', 'Radiotap_EHTKnown', # SCTP 'SCTP_Chunk', 'SCTP_Parameter', 'SCTP_CauseCode', 'SCTP_PayloadProtocolIdentifier', diff --git a/pcapkit/vendor/radiotap/__init__.py b/pcapkit/vendor/radiotap/__init__.py new file mode 100644 index 0000000000..427db46ffc --- /dev/null +++ b/pcapkit/vendor/radiotap/__init__.py @@ -0,0 +1,69 @@ +# -*- coding: utf-8 -*- +# pylint: disable=unused-import +""":class:`~pcapkit.protocols.link.radiotap.Radiotap` Vendor Crawlers +======================================================================== + +.. module:: pcapkit.vendor.radiotap + +This module contains all vendor crawlers of +:class:`~pcapkit.protocols.link.radiotap.Radiotap` implementations. +Available vendor crawlers include: + +.. list-table:: + + * - :class:`Radiotap_FieldType ` + - Field Types + * - :class:`Radiotap_Flags ` + - Flags + * - :class:`Radiotap_ChannelFlags ` + - Channel Flags + * - :class:`Radiotap_RXFlags ` + - RX Flags + * - :class:`Radiotap_TXFlags ` + - TX Flags + * - :class:`Radiotap_MCSKnown ` + - MCS Known Flags + * - :class:`Radiotap_AMPDUFlags ` + - A-MPDU Status Flags + * - :class:`Radiotap_VHTKnown ` + - VHT Known Flags + * - :class:`Radiotap_VHTFlags ` + - VHT Flags + * - :class:`Radiotap_VHTCoding ` + - VHT Coding Flags + * - :class:`Radiotap_TimestampFlags ` + - Timestamp Flags + * - :class:`Radiotap_HEMUOtherUserKnown ` + - HE-MU-other-user Known Flags + * - :class:`Radiotap_LSIGData1 ` + - L-SIG Data1 Flags + * - :class:`Radiotap_S1GKnown ` + - S1G Known Flags + * - :class:`Radiotap_EHTKnown ` + - EHT Known Flags + +""" + +from pcapkit.vendor.radiotap.ampdu_flags import AMPDUFlags as Radiotap_AMPDUFlags +from pcapkit.vendor.radiotap.channel_flags import ChannelFlags as Radiotap_ChannelFlags +from pcapkit.vendor.radiotap.eht_known import EHTKnown as Radiotap_EHTKnown +from pcapkit.vendor.radiotap.field_type import FieldType as Radiotap_FieldType +from pcapkit.vendor.radiotap.flags import Flags as Radiotap_Flags +from pcapkit.vendor.radiotap.he_mu_other_user_known import \ + HEMUOtherUserKnown as Radiotap_HEMUOtherUserKnown +from pcapkit.vendor.radiotap.lsig_data1 import LSIGData1 as Radiotap_LSIGData1 +from pcapkit.vendor.radiotap.mcs_known import MCSKnown as Radiotap_MCSKnown +from pcapkit.vendor.radiotap.rx_flags import RXFlags as Radiotap_RXFlags +from pcapkit.vendor.radiotap.s1g_known import S1GKnown as Radiotap_S1GKnown +from pcapkit.vendor.radiotap.timestamp_flags import TimestampFlags as Radiotap_TimestampFlags +from pcapkit.vendor.radiotap.tx_flags import TXFlags as Radiotap_TXFlags +from pcapkit.vendor.radiotap.vht_coding import VHTCoding as Radiotap_VHTCoding +from pcapkit.vendor.radiotap.vht_flags import VHTFlags as Radiotap_VHTFlags +from pcapkit.vendor.radiotap.vht_known import VHTKnown as Radiotap_VHTKnown + +__all__ = [ + 'Radiotap_FieldType', 'Radiotap_Flags', 'Radiotap_ChannelFlags', 'Radiotap_RXFlags', + 'Radiotap_TXFlags', 'Radiotap_MCSKnown', 'Radiotap_AMPDUFlags', 'Radiotap_VHTKnown', + 'Radiotap_VHTFlags', 'Radiotap_VHTCoding', 'Radiotap_TimestampFlags', + 'Radiotap_HEMUOtherUserKnown', 'Radiotap_LSIGData1', 'Radiotap_S1GKnown', 'Radiotap_EHTKnown', +] diff --git a/pcapkit/vendor/radiotap/ampdu_flags.py b/pcapkit/vendor/radiotap/ampdu_flags.py new file mode 100644 index 0000000000..7de75e87ed --- /dev/null +++ b/pcapkit/vendor/radiotap/ampdu_flags.py @@ -0,0 +1,46 @@ +# -*- coding: utf-8 -*- +"""Radiotap A-MPDU Status Flags +================================== + +.. module:: pcapkit.vendor.radiotap.ampdu_flags + +This module contains the vendor crawler for **Radiotap A-MPDU Status Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.ampdu_flags.AMPDUFlags`. + +The registry is the bits of the A-MPDU status field's ``flags``, as radiotap.org tables them; see +:mod:`pcapkit.vendor.radiotap.flags` for how a row becomes a member, and where +its name comes from. + +""" + +import sys + +from pcapkit.vendor.radiotap.flags import Flags + +__all__ = ['AMPDUFlags'] + + +class AMPDUFlags(Flags): + """Radiotap A-MPDU Status Flags""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFFFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/A-MPDU%20status.html' + #: Subfield whose table is scraped. + SUBFIELD = None + #: The source macro of each bit, keyed by mask, which is Linux's. + NAMES = { + 0x0001: 'IEEE80211_RADIOTAP_AMPDU_REPORT_ZEROLEN', + 0x0002: 'IEEE80211_RADIOTAP_AMPDU_IS_ZEROLEN', + 0x0004: 'IEEE80211_RADIOTAP_AMPDU_LAST_KNOWN', + 0x0008: 'IEEE80211_RADIOTAP_AMPDU_IS_LAST', + 0x0010: 'IEEE80211_RADIOTAP_AMPDU_DELIM_CRC_ERR', + 0x0020: 'IEEE80211_RADIOTAP_AMPDU_DELIM_CRC_KNOWN', + 0x0040: 'IEEE80211_RADIOTAP_AMPDU_EOF', + 0x0080: 'IEEE80211_RADIOTAP_AMPDU_EOF_KNOWN', + } # type: dict[int, str] + + +if __name__ == '__main__': + sys.exit(AMPDUFlags()) # type: ignore[arg-type] diff --git a/pcapkit/vendor/radiotap/channel_flags.py b/pcapkit/vendor/radiotap/channel_flags.py new file mode 100644 index 0000000000..ea765b8a09 --- /dev/null +++ b/pcapkit/vendor/radiotap/channel_flags.py @@ -0,0 +1,51 @@ +# -*- coding: utf-8 -*- +"""Radiotap Channel Flags +============================ + +.. module:: pcapkit.vendor.radiotap.channel_flags + +This module contains the vendor crawler for **Radiotap Channel Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.channel_flags.ChannelFlags`. + +The registry is the bits of the Channel field's ``flags``, as radiotap.org tables them; see +:mod:`pcapkit.vendor.radiotap.flags` for how a row becomes a member, and where +its name comes from. + +""" + +import sys + +from pcapkit.vendor.radiotap.flags import Flags + +__all__ = ['ChannelFlags'] + + +class ChannelFlags(Flags): + """Radiotap Channel Flags""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFFFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/Channel.html' + #: Subfield whose table is scraped. + SUBFIELD = None + #: The source macro of each bit, keyed by mask, which is Linux's, and + #: Wireshark's ``packet-ieee80211-radiotap-defs.h`` for ``0x0010``, + #: ``0x0200`` and ``0x0800``, which Linux leaves unnamed. + NAMES = { + 0x0001: 'IEEE80211_CHAN_700MHZ', + 0x0002: 'IEEE80211_CHAN_800MHZ', + 0x0004: 'IEEE80211_CHAN_900MHZ', + 0x0010: 'IEEE80211_CHAN_TURBO', + 0x0020: 'IEEE80211_CHAN_CCK', + 0x0040: 'IEEE80211_CHAN_OFDM', + 0x0080: 'IEEE80211_CHAN_2GHZ', + 0x0100: 'IEEE80211_CHAN_5GHZ', + 0x0200: 'IEEE80211_CHAN_PASSIVE', + 0x0400: 'IEEE80211_CHAN_DYN', + 0x0800: 'IEEE80211_CHAN_GFSK', + } # type: dict[int, str] + + +if __name__ == '__main__': + sys.exit(ChannelFlags()) # type: ignore[arg-type] diff --git a/pcapkit/vendor/radiotap/eht_known.py b/pcapkit/vendor/radiotap/eht_known.py new file mode 100644 index 0000000000..13acd76d90 --- /dev/null +++ b/pcapkit/vendor/radiotap/eht_known.py @@ -0,0 +1,59 @@ +# -*- coding: utf-8 -*- +"""Radiotap EHT Known Flags +============================== + +.. module:: pcapkit.vendor.radiotap.eht_known + +This module contains the vendor crawler for **Radiotap EHT Known Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.eht_known.EHTKnown`. + +The registry is the bits of the EHT field's ``known``, as radiotap.org tables them; see +:mod:`pcapkit.vendor.radiotap.flags` for how a row becomes a member, and where +its name comes from. + +""" + +import sys + +from pcapkit.vendor.radiotap.flags import Flags + +__all__ = ['EHTKnown'] + + +class EHTKnown(Flags): + """Radiotap EHT Known Flags""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFFFFFFFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/EHT.html' + #: Subfield whose table is scraped. + SUBFIELD = 'known' + #: The source macro of each bit, keyed by mask, which is Linux's. + NAMES = { + 0x00000002: 'IEEE80211_RADIOTAP_EHT_KNOWN_SPATIAL_REUSE', + 0x00000004: 'IEEE80211_RADIOTAP_EHT_KNOWN_GI', + 0x00000010: 'IEEE80211_RADIOTAP_EHT_KNOWN_EHT_LTF', + 0x00000020: 'IEEE80211_RADIOTAP_EHT_KNOWN_LDPC_EXTRA_SYM_OM', + 0x00000040: 'IEEE80211_RADIOTAP_EHT_KNOWN_PRE_PADD_FACOR_OM', + 0x00000080: 'IEEE80211_RADIOTAP_EHT_KNOWN_PE_DISAMBIGUITY_OM', + 0x00000100: 'IEEE80211_RADIOTAP_EHT_KNOWN_DISREGARD_O', + 0x00000200: 'IEEE80211_RADIOTAP_EHT_KNOWN_DISREGARD_S', + 0x00002000: 'IEEE80211_RADIOTAP_EHT_KNOWN_CRC1', + 0x00004000: 'IEEE80211_RADIOTAP_EHT_KNOWN_TAIL1', + 0x00008000: 'IEEE80211_RADIOTAP_EHT_KNOWN_CRC2_O', + 0x00010000: 'IEEE80211_RADIOTAP_EHT_KNOWN_TAIL2_O', + 0x00020000: 'IEEE80211_RADIOTAP_EHT_KNOWN_NSS_S', + 0x00040000: 'IEEE80211_RADIOTAP_EHT_KNOWN_BEAMFORMED_S', + 0x00080000: 'IEEE80211_RADIOTAP_EHT_KNOWN_NR_NON_OFDMA_USERS_M', + 0x00100000: 'IEEE80211_RADIOTAP_EHT_KNOWN_ENCODING_BLOCK_CRC_M', + 0x00200000: 'IEEE80211_RADIOTAP_EHT_KNOWN_ENCODING_BLOCK_TAIL_M', + 0x00400000: 'IEEE80211_RADIOTAP_EHT_KNOWN_RU_MRU_SIZE_OM', + 0x00800000: 'IEEE80211_RADIOTAP_EHT_KNOWN_RU_MRU_INDEX_OM', + 0x01000000: 'IEEE80211_RADIOTAP_EHT_KNOWN_RU_ALLOC_TB_FMT', + 0x02000000: 'IEEE80211_RADIOTAP_EHT_KNOWN_PRIMARY_80', + } # type: dict[int, str] + + +if __name__ == '__main__': + sys.exit(EHTKnown()) # type: ignore[arg-type] diff --git a/pcapkit/vendor/radiotap/field_type.py b/pcapkit/vendor/radiotap/field_type.py new file mode 100644 index 0000000000..34337aa6d9 --- /dev/null +++ b/pcapkit/vendor/radiotap/field_type.py @@ -0,0 +1,151 @@ +# -*- coding: utf-8 -*- +"""Radiotap Field Types +========================== + +.. module:: pcapkit.vendor.radiotap.field_type + +This module contains the vendor crawler for **Radiotap Field Types**, +which is automatically generating :class:`pcapkit.const.radiotap.field_type.FieldType`. + +The registry is radiotap.org's *Defined Fields* table, two columns -- the bit +number and the field name, linked to the field's own page -- scraped from +:attr:`FieldType.LINK`. A bit number is also the field's type in a TLV +(radiotap.org's *TLV fields in radiotap* page), so the registry covers both, +and the TLV-only fields from 32 on are in the same table. + +To those it adds the fields of :data:`UNOFFICIAL` from radiotap.org's +*Unofficially Used Fields* table, scraped from :data:`UNOFFICIAL_LINK`, each +commented with the systems that table says generate and parse it. Bit 16 is +RTS retries there, as Linux, Wireshark and radiotap-library read it; OpenBSD +writes its RSSI field at the same bit, a 2-octet layout of its own, and the +table's other rows -- OpenBSD's FCS in header at bit 14 and FreeBSD's +XChannel at bit 18 -- are left out, since the first clashes with RX flags and +neither Linux nor Wireshark's iterator sizes the second. + +The tables name no reserved value. radiotap.org's introduction reserves bits +29, 30 and 31 of every presence word, ``n * 32 - 3`` to ``n * 32 - 1``: the +first two are the namespace fields the table names, and the third chains +another presence word, so ``_missing_`` resolves the rest of those to +``Reserved`` and every other value to ``Unassigned``. The bound is the 16-bit +TLV type field; a bit number past it takes a chain of more than 2048 +presence words. + +""" + +import collections +import sys +from typing import TYPE_CHECKING, cast + +import bs4 + +from pcapkit.vendor.default import Vendor + +if TYPE_CHECKING: + from collections import Counter + + from bs4.element import Tag + +__all__ = ['FieldType'] + +#: Link to radiotap.org's *Unofficially Used Fields* table: the bit number, +#: the field, the systems that generate it and those that parse it. +UNOFFICIAL_LINK = 'https://www.radiotap.org/fields/unofficial' + +#: The fields of that table the registry takes, by name. +UNOFFICIAL = ('RTS retries', 'data retries') + + +class FieldType(Vendor): + """Radiotap Field Types""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFFFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/defined' + + def request(self, text: 'str') -> 'list[Tag]': # type: ignore[override] # pylint: disable=signature-differs + """Fetch registry table. + + Args: + text: Context from :attr:`~FieldType.LINK` or :data:`UNOFFICIAL_LINK`. + + Returns: + Rows (``tr``) of the registry table, less its header row. + + """ + soup = bs4.BeautifulSoup(text, 'html5lib') + return soup.select('table tr')[1:] + + def count(self, data: 'list[Tag]') -> 'Counter[str]': # type: ignore[override] + """Count field records. + + Args: + data: Registry data. + + Returns: + Field recordings. + + """ + return collections.Counter(self.safe_name(name) for _, name, _ in self._fields(data)) + + def process(self, data: 'list[Tag]') -> 'tuple[list[str], list[str]]': # type: ignore[override] + """Process registry data. + + Args: + data: Registry data. + + Returns: + Enumeration fields and missing fields. + + """ + enum = [] # type: list[str] + miss = [ + 'if value % 32 in (29, 30, 31):', + ' #: Reserved in every presence word', + " return cls._unregistered_member(value, 'Reserved')", + "return cls._unregistered_member(value, 'Unassigned')", + ] + for code, name, desc in self._fields(data): + renm = self.rename(name, str(code)) + enum.append(f'#: {self.wrap_comment(desc)}\n {renm} = {code}') + return enum, miss + + def _request(self) -> 'list[Tag]': # type: ignore[override] + """Fetch both tables, :attr:`~FieldType.LINK` then :data:`UNOFFICIAL_LINK`. + + Returns: + Rows (``tr``) of both tables, less their header rows. + + """ + rows = cast('list[Tag]', super()._request()) + self.LINK = UNOFFICIAL_LINK + try: + rows += cast('list[Tag]', super()._request()) + finally: + del self.LINK + return rows + + def _fields(self, data: 'list[Tag]') -> 'list[tuple[int, str, str]]': + """Pick the fields out of the rows. + + Args: + data: Rows of both tables; a row of the unofficial one has four cells. + + Returns: + Each field's bit number, name and description, in bit order. + + """ + fields = [] # type: list[tuple[int, str, str]] + for row in data: + cells = [' '.join(cell.get_text().split()) for cell in row.select('td')] + if len(cells) == 2: + fields.append((int(cells[0]), cells[1], cells[1])) + elif cells[1] in UNOFFICIAL: + code, name, generators, parsers = cells + used = f'generated by {generators}' + (f', parsed by {parsers}' if parsers else '') + fields.append((int(code), name, f'{name} [unofficial, {used}]')) + return sorted(fields, key=lambda field: field[0]) + + +if __name__ == '__main__': + sys.exit(FieldType()) # type: ignore[arg-type] diff --git a/pcapkit/vendor/radiotap/flags.py b/pcapkit/vendor/radiotap/flags.py new file mode 100644 index 0000000000..41e6812b26 --- /dev/null +++ b/pcapkit/vendor/radiotap/flags.py @@ -0,0 +1,303 @@ +# -*- coding: utf-8 -*- +"""Radiotap Flags +==================== + +.. module:: pcapkit.vendor.radiotap.flags + +This module contains the vendor crawler for **Radiotap Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.flags.Flags`. + +Each radiotap bitmap radiotap.org defines bit by bit has a flag registry, and +each registry's crawler scrapes the table on its field's page. +:class:`Flags` holds the scraping every one of them shares, and the crawlers of +the other bitmaps subclass it, naming their page and, where it holds more than +one bitmap, the subfield. + +A table row whose mask sets one bit is a member. A row that sets more bits, or +that radiotap.org marks reserved or unused, is not: its bits stay undefined, +which an ``aenum.IntFlag`` keeps in a value rather than dropping, so they +round-trip. The Flags page lists its last bit in a table of its own, which the +member's comment names. + +A member's value and comment come from radiotap.org, and its name from the +crawler's :attr:`~Flags.NAMES`: the macro the Linux kernel's +``include/net/ieee80211_radiotap.h`` [#]_ defines for the bit, less its +``IEEE80211_RADIOTAP_`` or ``IEEE80211_`` prefix. Where Linux defines none, the +macro is Wireshark's, from ``packet-ieee80211-radiotap-defs.h`` [#]_ or +``packet-ieee80211-radiotap.c`` [#]_; where neither does, the member takes +radiotap.org's wording of the bit, as :meth:`~Vendor.safe_name` renders it. + +.. [#] Linux at commit ``e5fefa3da5bf``, + https://github.com/torvalds/linux/blob/e5fefa3da5bf7c45bef90a3cca6a49e6c2d80877/include/net/ieee80211_radiotap.h +.. [#] Wireshark at commit ``090e75fa5daa``, + https://gitlab.com/wireshark/wireshark/-/blob/090e75fa5daa8ec6ffc35df00c3a93c281458ece/epan/dissectors/packet-ieee80211-radiotap-defs.h +.. [#] Wireshark at commit ``aae6da75c524``, + https://gitlab.com/wireshark/wireshark/-/blob/aae6da75c524dc8525373ae1a2bd634592e0e278/epan/dissectors/packet-ieee80211-radiotap.c + +""" + +import collections +import re +import sys +from typing import TYPE_CHECKING + +import bs4 + +from pcapkit.vendor.default import Vendor + +if TYPE_CHECKING: + from collections import Counter + from typing import Callable, List, Optional, Tuple + + from bs4.element import Tag + + #: Text before a table, its column names and its rows, as + #: :meth:`Flags.request` returns each table. + Table = Tuple[str, List[str], List[List[str]]] + +__all__ = ['Flags'] + +LINE = lambda NAME, DOCS, FLAG, ENUM, MODL: f'''\ +# -*- coding: utf-8 -*- +# pylint: disable=line-too-long,consider-using-f-string +"""{(name := DOCS.split(' [', maxsplit=1)[0])} +{'=' * (len(name) + 6)} + +.. module:: {MODL.replace('vendor', 'const')} + +This module contains the constant enumeration for **{name}**, +which is automatically generated from :class:`{MODL}.{NAME}`. + +""" + +from typing import TYPE_CHECKING + +from aenum import IntFlag + +from pcapkit.corekit.enum import EnumRegistry +from pcapkit.utilities.exceptions import EnumValueError + +if TYPE_CHECKING: + from typing import Any + +__all__ = ['{NAME}'] + + +class {NAME}(EnumRegistry, IntFlag): + """[{NAME}] {DOCS}""" + + {ENUM} + + @classmethod + def _validate_value(cls, value: 'Any') -> 'None': + """Reject ``value`` unless it passes the range check :meth:`_missing_` makes. + + Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value` + with that check and the message it raises, so + :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the + values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the + same words (:issue:`1816`). + + Args: + value: Value about to be looked up or minted. + + Raises: + EnumValueError: If ``value`` fails that check. A + :exc:`ValueError`, so an ``except ValueError`` caller is + unaffected. + + """ + if not ({FLAG}): + raise EnumValueError('%r is not a valid %s' % (value, cls.__name__)) + + @classmethod + def _missing_(cls, value: 'int') -> '{NAME}': + """Lookup function used when value is not found. + + Args: + value: Value to get enum item. + + """ + if not ({FLAG}): + raise ValueError('%r is not a valid %s' % (value, cls.__name__)) + return super()._missing_(value) +''' # type: Callable[[str, str, str, str, str], str] + +#: Meanings radiotap.org gives a bit it leaves undefined, lower-cased. +RESERVED = re.compile(r'\(?(reserved|unused)\b') + +#: Meaning radiotap.org gives a bit that means what the first column says. +SAME = '(same)' + +#: A mask, as radiotap.org writes one in a table's first column. +MASK = re.compile(r'0x[0-9a-fA-F]+') + +#: Prefixes of the source macros, dropped from a member's name, longest first. +PREFIXES = ('IEEE80211_RADIOTAP_', 'IEEE80211_') + + +class Flags(Vendor): + """Radiotap Flags""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/Flags.html' + #: Subfield whose table is scraped, as the page names it before the table; + #: :obj:`None` for every table on the page. + SUBFIELD = None # type: Optional[str] + #: The source macro of each bit, keyed by mask, which is Linux's for ``0x01`` + #: to ``0x40``, and Wireshark's ``packet-ieee80211-radiotap.c`` for ``0x80``, + #: which Linux leaves unnamed. + NAMES = { + 0x01: 'IEEE80211_RADIOTAP_F_CFP', + 0x02: 'IEEE80211_RADIOTAP_F_SHORTPRE', + 0x04: 'IEEE80211_RADIOTAP_F_WEP', + 0x08: 'IEEE80211_RADIOTAP_F_FRAG', + 0x10: 'IEEE80211_RADIOTAP_F_FCS', + 0x20: 'IEEE80211_RADIOTAP_F_DATAPAD', + 0x40: 'IEEE80211_RADIOTAP_F_BADFCS', + 0x80: 'IEEE80211_RADIOTAP_F_SHORTGI', + } # type: dict[int, str] + + def request(self, text: 'str') -> 'list[Table]': # type: ignore[override] # pylint: disable=signature-differs + """Fetch registry tables. + + Args: + text: Context from :attr:`~Flags.LINK`. + + Returns: + Each table of :attr:`SUBFIELD`, as the text before it, its column + names and its rows of cell texts. A table with no header row gets + the column names ``mask`` and ``meaning``. + + """ + soup = bs4.BeautifulSoup(text, 'html5lib') + tables = [] # type: list[Table] + for table in soup.select('table'): + caption, subfield = self._caption(table) + if self.SUBFIELD is not None and subfield != self.SUBFIELD: + continue + rows = [[' '.join(' '.join(cell.stripped_strings).replace('«BR»', ' ').split()) + for cell in row.select('td, th')] for row in table.select('tr')] + if rows and MASK.fullmatch(rows[0][0]): + tables.append((caption, ['mask', 'meaning'], rows)) + else: + tables.append((caption, rows[0], rows[1:])) + return tables + + def count(self, data: 'list[Table]') -> 'Counter[str]': # type: ignore[override] + """Count field records. + + Args: + data: Registry data. + + Returns: + Field recordings. + + """ + return collections.Counter(self.safe_name(name) for _, name, _ in self._members(data)) + + def process(self, data: 'list[Table]') -> 'list[str]': # type: ignore[override] + """Process registry data. + + Args: + data: Registry data. + + Returns: + Enumeration fields. + + """ + enum = [] # type: list[str] + for mask, name, desc in self._members(data): + macro = self.NAMES.get(mask) + if macro is None: + renm = self.rename(name, f'0x{mask:x}') + else: + renm = next(macro[len(prefix):] for prefix in PREFIXES if macro.startswith(prefix)) + enum.append(f'#: {self.wrap_comment(desc)}\n {renm} = 1 << {mask.bit_length() - 1}') + return enum + + def context(self, data: 'list[Table]') -> 'str': # type: ignore[override] + """Generate constant context. + + Args: + data: Registry data. + + Returns: + Constant context. + + """ + ENUM = '\n\n '.join(map(lambda s: s.rstrip(), self.process(data))) + return LINE(self.NAME, self.DOCS, self.FLAG, ENUM, self.__module__) + + def _caption(self, table: 'Tag') -> 'tuple[str, Optional[str]]': + """Name the subfield a table describes. + + Args: + table: The table. + + Returns: + The text of the paragraph before the table, and the subfield it + names: the ```` word of a paragraph ``The x + field ...``, or the text of the heading above the table. + + """ + caption = '' + for elem in table.find_all_previous(['p', 'h2']): + text = ' '.join(elem.get_text().split()) + caption = caption or text + if elem.name == 'h2': + return caption, text + code = elem.find('code') + if code is not None and text.startswith(f'The {code.get_text()} '): + return caption, code.get_text() + return caption, None + + def _members(self, data: 'list[Table]') -> 'list[tuple[int, str, str]]': + """Pick the members out of the tables. + + Args: + data: Registry data. + + Returns: + Each member's mask, name and description, in mask order. + + """ + members = {} # type: dict[int, tuple[str, str]] + for number, (caption, header, rows) in enumerate(data): + for row in rows: + if not MASK.fullmatch(row[0]): + continue + mask = int(row[0], 16) + if mask & (mask - 1): + continue + meanings = [(column, text) for column, text in zip(header[1:], row[1:]) + if column.lower() != 'notes'] + notes = [text for column, text in zip(header[1:], row[1:]) if column.lower() == 'notes' and text] + first = meanings[0][1] + defined = [(column, first if text == SAME else text) for column, text in meanings + if not RESERVED.match((first if text == SAME else text).lower())] + if not defined: + continue + + name = defined[0][1] + if len(defined) == len(meanings) and len({text for _, text in defined}) == 1: + desc = name + else: + # NOTE: a page with a column per PPDU kind defines some bits + # for some kinds only, so the comment names the kinds. + kinds = collections.defaultdict(list) # type: dict[str, list[str]] + for column, text in defined: + kinds[text].append(column) + desc = '; '.join(f'{", ".join(columns)}: {text}' for text, columns in kinds.items()) + if notes: + desc = f'{desc} -- {" ".join(notes)}' + if number: + desc = f'{desc} [{caption.rstrip(":")}]' + members[mask] = (name, desc) + return [(mask, name, desc) for mask, (name, desc) in sorted(members.items())] + + +if __name__ == '__main__': + sys.exit(Flags()) # type: ignore[arg-type] diff --git a/pcapkit/vendor/radiotap/he_mu_other_user_known.py b/pcapkit/vendor/radiotap/he_mu_other_user_known.py new file mode 100644 index 0000000000..c070977ebc --- /dev/null +++ b/pcapkit/vendor/radiotap/he_mu_other_user_known.py @@ -0,0 +1,38 @@ +# -*- coding: utf-8 -*- +"""Radiotap HE-MU-other-user Known Flags +=========================================== + +.. module:: pcapkit.vendor.radiotap.he_mu_other_user_known + +This module contains the vendor crawler for **Radiotap HE-MU-other-user Known Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.he_mu_other_user_known.HEMUOtherUserKnown`. + +The registry is the bits of the HE-MU-other-user field's ``per_user_known``, as radiotap.org tables them; see +:mod:`pcapkit.vendor.radiotap.flags` for how a row becomes a member, and where +its name comes from. + +""" + +import sys + +from pcapkit.vendor.radiotap.flags import Flags + +__all__ = ['HEMUOtherUserKnown'] + + +class HEMUOtherUserKnown(Flags): + """Radiotap HE-MU-other-user Known Flags""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/HE-MU-other-user.html' + #: Subfield whose table is scraped. + SUBFIELD = 'per_user_known' + #: No bit has a source macro, since neither Linux nor Wireshark names these + #: bits, so each member takes radiotap.org's wording. + NAMES = {} # type: dict[int, str] + + +if __name__ == '__main__': + sys.exit(HEMUOtherUserKnown()) # type: ignore[arg-type] diff --git a/pcapkit/vendor/radiotap/lsig_data1.py b/pcapkit/vendor/radiotap/lsig_data1.py new file mode 100644 index 0000000000..65050ad72e --- /dev/null +++ b/pcapkit/vendor/radiotap/lsig_data1.py @@ -0,0 +1,40 @@ +# -*- coding: utf-8 -*- +"""Radiotap L-SIG Data1 Flags +================================ + +.. module:: pcapkit.vendor.radiotap.lsig_data1 + +This module contains the vendor crawler for **Radiotap L-SIG Data1 Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.lsig_data1.LSIGData1`. + +The registry is the bits of the L-SIG field's ``data1``, as radiotap.org tables them; see +:mod:`pcapkit.vendor.radiotap.flags` for how a row becomes a member, and where +its name comes from. + +""" + +import sys + +from pcapkit.vendor.radiotap.flags import Flags + +__all__ = ['LSIGData1'] + + +class LSIGData1(Flags): + """Radiotap L-SIG Data1 Flags""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFFFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/L-SIG.html' + #: Subfield whose table is scraped. + SUBFIELD = 'data1' + #: The source macro of each bit, keyed by mask, which is Linux's. + NAMES = { + 0x0001: 'IEEE80211_RADIOTAP_LSIG_DATA1_RATE_KNOWN', + 0x0002: 'IEEE80211_RADIOTAP_LSIG_DATA1_LENGTH_KNOWN', + } # type: dict[int, str] + + +if __name__ == '__main__': + sys.exit(LSIGData1()) # type: ignore[arg-type] diff --git a/pcapkit/vendor/radiotap/mcs_known.py b/pcapkit/vendor/radiotap/mcs_known.py new file mode 100644 index 0000000000..f30a9daf39 --- /dev/null +++ b/pcapkit/vendor/radiotap/mcs_known.py @@ -0,0 +1,48 @@ +# -*- coding: utf-8 -*- +"""Radiotap MCS Known Flags +============================== + +.. module:: pcapkit.vendor.radiotap.mcs_known + +This module contains the vendor crawler for **Radiotap MCS Known Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.mcs_known.MCSKnown`. + +The registry is the bits of the MCS field's ``known``, as radiotap.org tables them; see +:mod:`pcapkit.vendor.radiotap.flags` for how a row becomes a member, and where +its name comes from. + +""" + +import sys + +from pcapkit.vendor.radiotap.flags import Flags + +__all__ = ['MCSKnown'] + + +class MCSKnown(Flags): + """Radiotap MCS Known Flags""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/MCS.html' + #: Subfield whose table is scraped. + SUBFIELD = 'known' + #: The source macro of each bit, keyed by mask, which is Linux's, and + #: Wireshark's ``packet-ieee80211-radiotap-defs.h`` for ``0x40`` and + #: ``0x80``, which Linux leaves unnamed. + NAMES = { + 0x01: 'IEEE80211_RADIOTAP_MCS_HAVE_BW', + 0x02: 'IEEE80211_RADIOTAP_MCS_HAVE_MCS', + 0x04: 'IEEE80211_RADIOTAP_MCS_HAVE_GI', + 0x08: 'IEEE80211_RADIOTAP_MCS_HAVE_FMT', + 0x10: 'IEEE80211_RADIOTAP_MCS_HAVE_FEC', + 0x20: 'IEEE80211_RADIOTAP_MCS_HAVE_STBC', + 0x40: 'IEEE80211_RADIOTAP_MCS_HAVE_NESS', + 0x80: 'IEEE80211_RADIOTAP_MCS_NESS_BIT1', + } # type: dict[int, str] + + +if __name__ == '__main__': + sys.exit(MCSKnown()) # type: ignore[arg-type] diff --git a/pcapkit/vendor/radiotap/rx_flags.py b/pcapkit/vendor/radiotap/rx_flags.py new file mode 100644 index 0000000000..167be5d719 --- /dev/null +++ b/pcapkit/vendor/radiotap/rx_flags.py @@ -0,0 +1,39 @@ +# -*- coding: utf-8 -*- +"""Radiotap RX Flags +======================= + +.. module:: pcapkit.vendor.radiotap.rx_flags + +This module contains the vendor crawler for **Radiotap RX Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.rx_flags.RXFlags`. + +The registry is the bits of the RX flags field, as radiotap.org tables them; see +:mod:`pcapkit.vendor.radiotap.flags` for how a row becomes a member, and where +its name comes from. + +""" + +import sys + +from pcapkit.vendor.radiotap.flags import Flags + +__all__ = ['RXFlags'] + + +class RXFlags(Flags): + """Radiotap RX Flags""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFFFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/RX%20flags.html' + #: Subfield whose table is scraped. + SUBFIELD = None + #: The source macro of each bit, keyed by mask, which is Linux's. + NAMES = { + 0x0002: 'IEEE80211_RADIOTAP_F_RX_BADPLCP', + } # type: dict[int, str] + + +if __name__ == '__main__': + sys.exit(RXFlags()) # type: ignore[arg-type] diff --git a/pcapkit/vendor/radiotap/s1g_known.py b/pcapkit/vendor/radiotap/s1g_known.py new file mode 100644 index 0000000000..9edb412cca --- /dev/null +++ b/pcapkit/vendor/radiotap/s1g_known.py @@ -0,0 +1,46 @@ +# -*- coding: utf-8 -*- +"""Radiotap S1G Known Flags +============================== + +.. module:: pcapkit.vendor.radiotap.s1g_known + +This module contains the vendor crawler for **Radiotap S1G Known Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.s1g_known.S1GKnown`. + +The registry is the bits of the S1G field's ``known``, as radiotap.org tables them; see +:mod:`pcapkit.vendor.radiotap.flags` for how a row becomes a member, and where +its name comes from. + +""" + +import sys + +from pcapkit.vendor.radiotap.flags import Flags + +__all__ = ['S1GKnown'] + + +class S1GKnown(Flags): + """Radiotap S1G Known Flags""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFFFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/S1G.html' + #: Subfield whose table is scraped. + SUBFIELD = 'known' + #: The source macro of each bit, keyed by mask, which is Linux's. + NAMES = { + 0x0001: 'IEEE80211_RADIOTAP_S1G_KNOWN_PPDU_FORMAT', + 0x0002: 'IEEE80211_RADIOTAP_S1G_KNOWN_RESPONSE_IND', + 0x0004: 'IEEE80211_RADIOTAP_S1G_KNOWN_GI', + 0x0008: 'IEEE80211_RADIOTAP_S1G_KNOWN_NSS', + 0x0010: 'IEEE80211_RADIOTAP_S1G_KNOWN_BW', + 0x0020: 'IEEE80211_RADIOTAP_S1G_KNOWN_MCS', + 0x0040: 'IEEE80211_RADIOTAP_S1G_KNOWN_COLOR', + 0x0080: 'IEEE80211_RADIOTAP_S1G_KNOWN_UPLINK_IND', + } # type: dict[int, str] + + +if __name__ == '__main__': + sys.exit(S1GKnown()) # type: ignore[arg-type] diff --git a/pcapkit/vendor/radiotap/timestamp_flags.py b/pcapkit/vendor/radiotap/timestamp_flags.py new file mode 100644 index 0000000000..eea539e79d --- /dev/null +++ b/pcapkit/vendor/radiotap/timestamp_flags.py @@ -0,0 +1,40 @@ +# -*- coding: utf-8 -*- +"""Radiotap Timestamp Flags +============================== + +.. module:: pcapkit.vendor.radiotap.timestamp_flags + +This module contains the vendor crawler for **Radiotap Timestamp Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.timestamp_flags.TimestampFlags`. + +The registry is the bits of the timestamp field's ``flags``, as radiotap.org tables them; see +:mod:`pcapkit.vendor.radiotap.flags` for how a row becomes a member, and where +its name comes from. + +""" + +import sys + +from pcapkit.vendor.radiotap.flags import Flags + +__all__ = ['TimestampFlags'] + + +class TimestampFlags(Flags): + """Radiotap Timestamp Flags""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/timestamp.html' + #: Subfield whose table is scraped. + SUBFIELD = 'flags' + #: The source macro of each bit, keyed by mask, which is Linux's. + NAMES = { + 0x01: 'IEEE80211_RADIOTAP_TIMESTAMP_FLAG_32BIT', + 0x02: 'IEEE80211_RADIOTAP_TIMESTAMP_FLAG_ACCURACY', + } # type: dict[int, str] + + +if __name__ == '__main__': + sys.exit(TimestampFlags()) # type: ignore[arg-type] diff --git a/pcapkit/vendor/radiotap/tx_flags.py b/pcapkit/vendor/radiotap/tx_flags.py new file mode 100644 index 0000000000..cc859011a9 --- /dev/null +++ b/pcapkit/vendor/radiotap/tx_flags.py @@ -0,0 +1,44 @@ +# -*- coding: utf-8 -*- +"""Radiotap TX Flags +======================= + +.. module:: pcapkit.vendor.radiotap.tx_flags + +This module contains the vendor crawler for **Radiotap TX Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.tx_flags.TXFlags`. + +The registry is the bits of the TX flags field, as radiotap.org tables them; see +:mod:`pcapkit.vendor.radiotap.flags` for how a row becomes a member, and where +its name comes from. + +""" + +import sys + +from pcapkit.vendor.radiotap.flags import Flags + +__all__ = ['TXFlags'] + + +class TXFlags(Flags): + """Radiotap TX Flags""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFFFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/TX%20flags.html' + #: Subfield whose table is scraped. + SUBFIELD = None + #: The source macro of each bit, keyed by mask, which is Linux's. + NAMES = { + 0x0001: 'IEEE80211_RADIOTAP_F_TX_FAIL', + 0x0002: 'IEEE80211_RADIOTAP_F_TX_CTS', + 0x0004: 'IEEE80211_RADIOTAP_F_TX_RTS', + 0x0008: 'IEEE80211_RADIOTAP_F_TX_NOACK', + 0x0010: 'IEEE80211_RADIOTAP_F_TX_NOSEQNO', + 0x0020: 'IEEE80211_RADIOTAP_F_TX_ORDER', + } # type: dict[int, str] + + +if __name__ == '__main__': + sys.exit(TXFlags()) # type: ignore[arg-type] diff --git a/pcapkit/vendor/radiotap/vht_coding.py b/pcapkit/vendor/radiotap/vht_coding.py new file mode 100644 index 0000000000..bfbfc5bccb --- /dev/null +++ b/pcapkit/vendor/radiotap/vht_coding.py @@ -0,0 +1,42 @@ +# -*- coding: utf-8 -*- +"""Radiotap VHT Coding Flags +=============================== + +.. module:: pcapkit.vendor.radiotap.vht_coding + +This module contains the vendor crawler for **Radiotap VHT Coding Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.vht_coding.VHTCoding`. + +The registry is the bits of the VHT field's ``coding``, as radiotap.org tables them; see +:mod:`pcapkit.vendor.radiotap.flags` for how a row becomes a member, and where +its name comes from. + +""" + +import sys + +from pcapkit.vendor.radiotap.flags import Flags + +__all__ = ['VHTCoding'] + + +class VHTCoding(Flags): + """Radiotap VHT Coding Flags""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/VHT.html' + #: Subfield whose table is scraped. + SUBFIELD = 'coding' + #: The source macro of each bit, keyed by mask, which is Linux's. + NAMES = { + 0x01: 'IEEE80211_RADIOTAP_CODING_LDPC_USER0', + 0x02: 'IEEE80211_RADIOTAP_CODING_LDPC_USER1', + 0x04: 'IEEE80211_RADIOTAP_CODING_LDPC_USER2', + 0x08: 'IEEE80211_RADIOTAP_CODING_LDPC_USER3', + } # type: dict[int, str] + + +if __name__ == '__main__': + sys.exit(VHTCoding()) # type: ignore[arg-type] diff --git a/pcapkit/vendor/radiotap/vht_flags.py b/pcapkit/vendor/radiotap/vht_flags.py new file mode 100644 index 0000000000..301cd87240 --- /dev/null +++ b/pcapkit/vendor/radiotap/vht_flags.py @@ -0,0 +1,44 @@ +# -*- coding: utf-8 -*- +"""Radiotap VHT Flags +======================== + +.. module:: pcapkit.vendor.radiotap.vht_flags + +This module contains the vendor crawler for **Radiotap VHT Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.vht_flags.VHTFlags`. + +The registry is the bits of the VHT field's ``flags``, as radiotap.org tables them; see +:mod:`pcapkit.vendor.radiotap.flags` for how a row becomes a member, and where +its name comes from. + +""" + +import sys + +from pcapkit.vendor.radiotap.flags import Flags + +__all__ = ['VHTFlags'] + + +class VHTFlags(Flags): + """Radiotap VHT Flags""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/VHT.html' + #: Subfield whose table is scraped. + SUBFIELD = 'flags' + #: The source macro of each bit, keyed by mask, which is Linux's. + NAMES = { + 0x01: 'IEEE80211_RADIOTAP_VHT_FLAG_STBC', + 0x02: 'IEEE80211_RADIOTAP_VHT_FLAG_TXOP_PS_NA', + 0x04: 'IEEE80211_RADIOTAP_VHT_FLAG_SGI', + 0x08: 'IEEE80211_RADIOTAP_VHT_FLAG_SGI_NSYM_M10_9', + 0x10: 'IEEE80211_RADIOTAP_VHT_FLAG_LDPC_EXTRA_OFDM_SYM', + 0x20: 'IEEE80211_RADIOTAP_VHT_FLAG_BEAMFORMED', + } # type: dict[int, str] + + +if __name__ == '__main__': + sys.exit(VHTFlags()) # type: ignore[arg-type] diff --git a/pcapkit/vendor/radiotap/vht_known.py b/pcapkit/vendor/radiotap/vht_known.py new file mode 100644 index 0000000000..8ab0fd2e88 --- /dev/null +++ b/pcapkit/vendor/radiotap/vht_known.py @@ -0,0 +1,47 @@ +# -*- coding: utf-8 -*- +"""Radiotap VHT Known Flags +============================== + +.. module:: pcapkit.vendor.radiotap.vht_known + +This module contains the vendor crawler for **Radiotap VHT Known Flags**, +which is automatically generating :class:`pcapkit.const.radiotap.vht_known.VHTKnown`. + +The registry is the bits of the VHT field's ``known``, as radiotap.org tables them; see +:mod:`pcapkit.vendor.radiotap.flags` for how a row becomes a member, and where +its name comes from. + +""" + +import sys + +from pcapkit.vendor.radiotap.flags import Flags + +__all__ = ['VHTKnown'] + + +class VHTKnown(Flags): + """Radiotap VHT Known Flags""" + + #: Value limit checker. + FLAG = 'isinstance(value, int) and 0 <= value <= 0xFFFF' + #: Link to registry. + LINK = 'https://www.radiotap.org/fields/VHT.html' + #: Subfield whose table is scraped. + SUBFIELD = 'known' + #: The source macro of each bit, keyed by mask, which is Linux's. + NAMES = { + 0x0001: 'IEEE80211_RADIOTAP_VHT_KNOWN_STBC', + 0x0002: 'IEEE80211_RADIOTAP_VHT_KNOWN_TXOP_PS_NA', + 0x0004: 'IEEE80211_RADIOTAP_VHT_KNOWN_GI', + 0x0008: 'IEEE80211_RADIOTAP_VHT_KNOWN_SGI_NSYM_DIS', + 0x0010: 'IEEE80211_RADIOTAP_VHT_KNOWN_LDPC_EXTRA_OFDM_SYM', + 0x0020: 'IEEE80211_RADIOTAP_VHT_KNOWN_BEAMFORMED', + 0x0040: 'IEEE80211_RADIOTAP_VHT_KNOWN_BANDWIDTH', + 0x0080: 'IEEE80211_RADIOTAP_VHT_KNOWN_GROUP_ID', + 0x0100: 'IEEE80211_RADIOTAP_VHT_KNOWN_PARTIAL_AID', + } # type: dict[int, str] + + +if __name__ == '__main__': + sys.exit(VHTKnown()) # type: ignore[arg-type] diff --git a/tests/const/census/radiotap.py b/tests/const/census/radiotap.py new file mode 100644 index 0000000000..1aeb484d84 --- /dev/null +++ b/tests/const/census/radiotap.py @@ -0,0 +1,21 @@ +# -*- coding: utf-8 -*- +"""The registries of :mod:`pcapkit.const.radiotap`, for :mod:`tests.const.census`.""" + +#: Each registry, as ``module:QualName``, and its kind. +REGISTRIES = { + 'pcapkit.const.radiotap.ampdu_flags:AMPDUFlags': 'flag', + 'pcapkit.const.radiotap.channel_flags:ChannelFlags': 'flag', + 'pcapkit.const.radiotap.eht_known:EHTKnown': 'flag', + 'pcapkit.const.radiotap.field_type:FieldType': 'int', + 'pcapkit.const.radiotap.flags:Flags': 'flag', + 'pcapkit.const.radiotap.he_mu_other_user_known:HEMUOtherUserKnown': 'flag', + 'pcapkit.const.radiotap.lsig_data1:LSIGData1': 'flag', + 'pcapkit.const.radiotap.mcs_known:MCSKnown': 'flag', + 'pcapkit.const.radiotap.rx_flags:RXFlags': 'flag', + 'pcapkit.const.radiotap.s1g_known:S1GKnown': 'flag', + 'pcapkit.const.radiotap.timestamp_flags:TimestampFlags': 'flag', + 'pcapkit.const.radiotap.tx_flags:TXFlags': 'flag', + 'pcapkit.const.radiotap.vht_coding:VHTCoding': 'flag', + 'pcapkit.const.radiotap.vht_flags:VHTFlags': 'flag', + 'pcapkit.const.radiotap.vht_known:VHTKnown': 'flag', +} diff --git a/tests/const/test_const_registry_protocol.py b/tests/const/test_const_registry_protocol.py index d9b86c772a..29ad3c9af4 100644 --- a/tests/const/test_const_registry_protocol.py +++ b/tests/const/test_const_registry_protocol.py @@ -64,6 +64,20 @@ ('pcapkit.const.mh.handover_initiate_flag', 'HandoverInitiateFlag', 'pcapkit/const/mh/handover_initiate_flag.py'), ('pcapkit.const.ipv6.extension_header', 'ExtensionHeader', 'pcapkit/const/ipv6/extension_header.py'), ('pcapkit.const.tcp.flags', 'Flags', 'pcapkit/const/tcp/flags.py'), + ('pcapkit.const.radiotap.flags', 'Flags', 'pcapkit/const/radiotap/flags.py'), + ('pcapkit.const.radiotap.channel_flags', 'ChannelFlags', 'pcapkit/const/radiotap/channel_flags.py'), + ('pcapkit.const.radiotap.rx_flags', 'RXFlags', 'pcapkit/const/radiotap/rx_flags.py'), + ('pcapkit.const.radiotap.tx_flags', 'TXFlags', 'pcapkit/const/radiotap/tx_flags.py'), + ('pcapkit.const.radiotap.mcs_known', 'MCSKnown', 'pcapkit/const/radiotap/mcs_known.py'), + ('pcapkit.const.radiotap.ampdu_flags', 'AMPDUFlags', 'pcapkit/const/radiotap/ampdu_flags.py'), + ('pcapkit.const.radiotap.vht_coding', 'VHTCoding', 'pcapkit/const/radiotap/vht_coding.py'), + ('pcapkit.const.radiotap.timestamp_flags', 'TimestampFlags', 'pcapkit/const/radiotap/timestamp_flags.py'), + ('pcapkit.const.radiotap.he_mu_other_user_known', 'HEMUOtherUserKnown', 'pcapkit/const/radiotap/he_mu_other_user_known.py'), + ('pcapkit.const.radiotap.lsig_data1', 'LSIGData1', 'pcapkit/const/radiotap/lsig_data1.py'), + ('pcapkit.const.radiotap.s1g_known', 'S1GKnown', 'pcapkit/const/radiotap/s1g_known.py'), + ('pcapkit.const.radiotap.vht_known', 'VHTKnown', 'pcapkit/const/radiotap/vht_known.py'), + ('pcapkit.const.radiotap.vht_flags', 'VHTFlags', 'pcapkit/const/radiotap/vht_flags.py'), + ('pcapkit.const.radiotap.eht_known', 'EHTKnown', 'pcapkit/const/radiotap/eht_known.py'), ) #: The crawlers whose bespoke templates are converted, and which must therefore @@ -75,6 +89,7 @@ 'pcapkit/vendor/mh/handover_initiate_flag.py', 'pcapkit/vendor/ipv6/extension_header.py', 'pcapkit/vendor/tcp/flags.py', + 'pcapkit/vendor/radiotap/flags.py', ) #: Every method of the protocol the ruling says must always exist. @@ -96,6 +111,26 @@ def _is_generated_shape(source: 'str') -> 'bool': and not any(f'def {method}(' in source for method in PROTOCOL)) +def _template_crawler(crawler: 'str') -> 'str': + """The crawler whose ``LINE`` renders the registry ``crawler`` generates. + + ``crawler`` itself, unless its class subclasses another crawler module's, as + each :mod:`pcapkit.vendor.radiotap` flag crawler does + :mod:`pcapkit.vendor.radiotap.flags`'s (#2576); then that module. A + subclass of :class:`pcapkit.vendor.default.Vendor` stays ``crawler``. + + """ + tree = ast.parse((REPO_ROOT / crawler).read_text()) + bases = {base.id for node in tree.body if isinstance(node, ast.ClassDef) + for base in node.bases if isinstance(base, ast.Name)} + for node in tree.body: + if (isinstance(node, ast.ImportFrom) and node.module is not None + and node.module.startswith('pcapkit.vendor.') and node.module.count('.') == 3 + and any(alias.name in bases for alias in node.names)): + return node.module.replace('.', '/') + '.py' + return crawler + + def _unused_value(cls: 'Any') -> 'int': """First non-negative integer no member of ``cls`` carries. @@ -159,19 +194,20 @@ def test_converted_crawlers_do_not_spell_their_own_get(self) -> None: def test_each_converted_entry_is_what_converted_means(self) -> None: """Each :data:`CONVERTED` entry is a bespoke template whose members carry nothing extra. - Its crawler, the one :data:`CONVERTED_VENDORS` pairs it with, spells a - module-level ``LINE`` template of its own rather than rendering the - default one, and neither that crawler nor the const module defines a - ``__new__``. So a default-template registry cannot be filed here in place - of the generated side of + The crawler rendering it, which :func:`_template_crawler` finds and + :data:`CONVERTED_VENDORS` lists, spells a module-level ``LINE`` template + of its own rather than rendering the default one, and neither the + crawlers nor the const module define a ``__new__``. So a + default-template registry cannot be filed here in place of the + generated side of :meth:`GeneratedTemplateSourceInheritsTests.test_every_generated_const_module_is_accounted_for` (#2615). """ - crawlers = [relpath.replace('pcapkit/const/', 'pcapkit/vendor/', 1) - for _, _, relpath in CONVERTED] - self.assertEqual(sorted(crawlers), sorted(CONVERTED_VENDORS)) - for (_, name, relpath), crawler in zip(CONVERTED, crawlers): + owners = [relpath.replace('pcapkit/const/', 'pcapkit/vendor/', 1) for _, _, relpath in CONVERTED] + crawlers = [_template_crawler(owner) for owner in owners] + self.assertEqual(sorted(set(crawlers)), sorted(CONVERTED_VENDORS)) + for (_, name, relpath), owner, crawler in zip(CONVERTED, owners, crawlers): with self.subTest(registry=name): tree = ast.parse((REPO_ROOT / crawler).read_text()) self.assertTrue(any(isinstance(node, ast.Assign) @@ -179,7 +215,7 @@ def test_each_converted_entry_is_what_converted_means(self) -> None: for target in node.targets) for node in tree.body), f'{crawler} renders the default template, so {name} is not converted') - for path in (relpath, crawler): + for path in (relpath, owner, crawler): self.assertNotIn('def __new__(', (REPO_ROOT / path).read_text(), f'{path} attaches attributes in __new__, so {name} is not converted') diff --git a/tests/dumpkit/test_nameless_enum_rendering_unit.py b/tests/dumpkit/test_nameless_enum_rendering_unit.py index f2199422b7..da031ecf00 100644 --- a/tests/dumpkit/test_nameless_enum_rendering_unit.py +++ b/tests/dumpkit/test_nameless_enum_rendering_unit.py @@ -20,6 +20,24 @@ RUNTIME_DEPS = ('tbtrim', 'aenum', 'chardet', 'dictdumper') HAS_RUNTIME = all(importlib.util.find_spec(name) is not None for name in RUNTIME_DEPS) +#: Flag registries whose field is wider than the bits they declare, to the +#: schema field holding each: a radiotap bitmap keeps the bits radiotap.org does +#: not name, so its bound is its subfield's width rather than its declared +#: bits' (#2576). Checked both ways by ``test_each_wider_field_is_wider``. +WIDER_FIELDS = { + 'pcapkit.const.radiotap.ampdu_flags.AMPDUFlags': ('AMPDUStatus', 'flags'), + 'pcapkit.const.radiotap.channel_flags.ChannelFlags': ('Channel', 'flags'), + 'pcapkit.const.radiotap.eht_known.EHTKnown': ('EHT', 'known'), + 'pcapkit.const.radiotap.lsig_data1.LSIGData1': ('LSIG', 'data1'), + 'pcapkit.const.radiotap.rx_flags.RXFlags': ('RXFlags', 'flags'), + 'pcapkit.const.radiotap.s1g_known.S1GKnown': ('S1G', 'known'), + 'pcapkit.const.radiotap.timestamp_flags.TimestampFlags': ('Timestamp', 'flags'), + 'pcapkit.const.radiotap.tx_flags.TXFlags': ('TXFlags', 'flags'), + 'pcapkit.const.radiotap.vht_coding.VHTCoding': ('VHT', 'coding'), + 'pcapkit.const.radiotap.vht_flags.VHTFlags': ('VHT', 'flags'), + 'pcapkit.const.radiotap.vht_known.VHTKnown': ('VHT', 'known'), +} + class StdFlags(enum.IntFlag): """``ACK`` and ``SYN`` of :class:`pcapkit.const.tcp.flags.Flags`, as a stdlib flag enumeration. @@ -354,6 +372,15 @@ def test_a_value_past_the_field_is_refused_rather_than_rendered(self) -> None: # outside every single one of them. self.assertGreaterEqual(len(widths), 3, widths) + def test_each_wider_field_is_wider(self) -> None: + """Each :data:`WIDER_FIELDS` entry is a flag registry whose field outgrows its declared bits.""" + registries = _flag_registries() + for label in WIDER_FIELDS: + with self.subTest(registry=label): + self.assertIn(label, registries) + self.assertGreater(_field_mask(registries[label]).bit_length(), + _declared_bits(registries[label]).bit_length()) + def _const_path() -> 'list[str]': """The filesystem path of :mod:`pcapkit.const`, for :func:`pkgutil.walk_packages`. @@ -427,19 +454,21 @@ def _field_mask(registry: 'FlagRegistry') -> int: """The width of *registry*'s field, as an all-ones mask. Every flag registry in the library bounds its :meth:`~enum.Enum._missing_` - to the field its declared bits live in, and for every one of them that bound - is exactly the smallest all-ones mask covering every declared bit -- - ``0xFFF`` for ``Flags``' ``1 << 0 .. 1 << 11``, ``0xFF`` for the eight-bit - Mobility Header flags, ``0x07`` for the three-bit - :class:`~pcapkit.const.ftp.command.CommandType`. + to the field its declared bits live in, and for every one of them but those + of :data:`WIDER_FIELDS` that bound is exactly the smallest all-ones mask + covering every declared bit -- ``0xFFF`` for ``Flags``' ``1 << 0 .. 1 << 11``, + ``0xFF`` for the eight-bit Mobility Header flags, ``0x07`` for the three-bit + :class:`~pcapkit.const.ftp.command.CommandType`. Those of :data:`WIDER_FIELDS` + take their schema field's width instead. :class:`~pcapkit.const.reg.apptype.TransportProtocol` is a plain :class:`~aenum.IntEnum` (GitHub issue #808), so it does not match ``issubclass(attribute, (enum.Flag, aenum.Flag))`` and this function never sees it at all. - Derived rather than read off the source, so it cannot drift from the guard - and needs no table to maintain. That it does not drift is itself asserted, by + Derived rather than read off the guard's source, so it cannot drift from the + guard; :data:`WIDER_FIELDS` names fields, not widths. That it does not drift + is itself asserted, by :meth:`NamelessEnumRenderingTests.test_a_value_past_the_field_is_refused_rather_than_rendered`. Args: @@ -449,6 +478,12 @@ def _field_mask(registry: 'FlagRegistry') -> int: An all-ones mask as wide as the registry's field. """ + wider = WIDER_FIELDS.get(f'{registry.__module__}.{registry.__name__}') + if wider is not None: + from pcapkit.protocols.schema.link import radiotap # pylint: disable=import-outside-toplevel + + schema, name = wider + return (1 << 8 * getattr(radiotap, schema).__fields__[name].length) - 1 return (1 << _declared_bits(registry).bit_length()) - 1 diff --git a/tests/foundation/registry/test_protocols.py b/tests/foundation/registry/test_protocols.py index f8b0ce7bed..d71f904893 100644 --- a/tests/foundation/registry/test_protocols.py +++ b/tests/foundation/registry/test_protocols.py @@ -33,6 +33,7 @@ 'register_pcapng_option', 'register_pcapng_record', 'register_pcapng_secrets', + 'register_radiotap_field', 'register_sctp_cause', 'register_sctp_chunk', 'register_sctp_parameter', @@ -914,11 +915,13 @@ def test_option_like_registry_wrappers_validate_methods_and_register_schema(self from pcapkit.const.sctp.cause_code import CauseCode from pcapkit.const.sctp.chunk import Chunk from pcapkit.const.sctp.parameter import Parameter as SCTPParameter + from pcapkit.const.radiotap.field_type import FieldType from pcapkit.const.tcp.mp_tcp_option import MPTCPOption from pcapkit.const.tcp.option import Option as TCPOption from pcapkit.foundation.registry import protocols as registry from pcapkit.foundation.registry.protocols import application as reg_application from pcapkit.foundation.registry.protocols import internet as reg_internet + from pcapkit.foundation.registry.protocols import link as reg_link from pcapkit.foundation.registry.protocols import misc as reg_misc from pcapkit.foundation.registry.protocols import transport as reg_transport from pcapkit.utilities.exceptions import RegistryError @@ -961,6 +964,8 @@ def test_option_like_registry_wrappers_validate_methods_and_register_schema(self RecordType.nrb_record_ipv4), (registry.register_pcapng_secrets, reg_misc.PCAPNG, '_read_secrets_unit', reg_misc.Schema_PCAPNG_DSBSecrets, 'register_secrets', SecretsType.TLS_Key_Log), + (registry.register_radiotap_field, reg_link.Radiotap, '_read_field_unit', + reg_link.Schema_Radiotap_Field, 'register_field', FieldType.TSFT), ] schema = object diff --git a/tests/foundation/registry/test_registrar_code_check_unit.py b/tests/foundation/registry/test_registrar_code_check_unit.py index cd91d8063d..d1fff6283d 100644 --- a/tests/foundation/registry/test_registrar_code_check_unit.py +++ b/tests/foundation/registry/test_registrar_code_check_unit.py @@ -82,6 +82,8 @@ 'pcapkit.protocols.schema.misc.pcapng:NameResolutionRecord'), ('register_pcapng_secrets', 'pcapkit.protocols.misc.pcapng:PCAPNG', 'pcapkit.protocols.schema.misc.pcapng:DSBSecrets'), + ('register_radiotap_field', 'pcapkit.protocols.link.radiotap:Radiotap', + 'pcapkit.protocols.schema.link.radiotap:RadiotapField'), ) #: Registrars keyed on an enum code and given a protocol class, with the classes @@ -122,6 +124,7 @@ 'register_pcapng_option': 'pcapkit.const.pcapng.option_type:OptionType', 'register_pcapng_record': 'pcapkit.const.pcapng.record_type:RecordType', 'register_pcapng_secrets': 'pcapkit.const.pcapng.secrets_type:SecretsType', + 'register_radiotap_field': 'pcapkit.const.radiotap.field_type:FieldType', 'register_linktype': 'pcapkit.const.reg.linktype:LinkType', 'register_pcap': 'pcapkit.const.reg.linktype:LinkType', 'register_pcapng': 'pcapkit.const.reg.linktype:LinkType', diff --git a/tests/foundation/registry/test_registry_symmetry_unit.py b/tests/foundation/registry/test_registry_symmetry_unit.py index ecc9b98131..585accdd7d 100644 --- a/tests/foundation/registry/test_registry_symmetry_unit.py +++ b/tests/foundation/registry/test_registry_symmetry_unit.py @@ -160,6 +160,9 @@ class MethodRegistrar(NamedTuple): MethodRegistrar('register_pcapng_secrets', 'pcapkit.protocols.misc.pcapng:PCAPNG', '__secrets__', 'pcapkit.protocols.schema.misc.pcapng:DSBSecrets', ('pcapkit.const.pcapng.secrets_type:SecretsType.WireGuard_Key_Log',)), + MethodRegistrar('register_radiotap_field', 'pcapkit.protocols.link.radiotap:Radiotap', '__field__', + 'pcapkit.protocols.schema.link.radiotap:RadiotapField', + ('pcapkit.const.radiotap.field_type:FieldType.Channel',)), ) diff --git a/tests/protocols/link/test_radiotap_fields_2576_unit.py b/tests/protocols/link/test_radiotap_fields_2576_unit.py new file mode 100644 index 0000000000..78ead84708 --- /dev/null +++ b/tests/protocols/link/test_radiotap_fields_2576_unit.py @@ -0,0 +1,711 @@ +# -*- coding: utf-8 -*- +"""GitHub issue #2576: radiotap's optional fields, decoded. + +:class:`~pcapkit.protocols.link.radiotap.Radiotap` decodes the field-data +region into ``decoded`` per the radiotap.org field pages: each field's +alignment, size and subfields, the namespace fields, extended presence words +and the TLV list. Unknown and vendor fields stay raw, ``fields`` keeps the +region as captured, and both round trips are byte-exact. + +The vectors come from three places: + +* hand-built from radiotap.org's field pages, with each expected value + worked out by hand; +* the ``check/`` vectors of radiotap.org's own parser library, + https://github.com/radiotap/radiotap-library at + ``c21ba1e6fc6cc7723bd02faf000dd6d3d345abfa``, each pinned to what that + library's ``.out`` file prints for it; +* records of tcpdump's test captures ``ieee802.11_exthdr.pcap``, + ``ieee802.11_rx-stbc.pcap`` and ``ieee802.11_htc.pcap``, + https://github.com/the-tcpdump-group/tcpdump at + ``f34cf40526e1f6326138fedba2a606d1c2f089f3``, each pinned to what tcpdump's + ``.out`` file prints for it. + +Each test imports :mod:`pcapkit` itself, after +:func:`~tests._support.reimport_once_per_class`. + +""" + +import struct +import unittest + +from tests._support import reimport_once_per_class + +#: An 802.11 Ack frame to ``01:01:01:01:01:01``, with a 4-octet FCS. +ACK = bytes.fromhex('d4000000') + b'\x01' * 6 + b'\x11\x22\x33\x44' + +#: radiotap-library's ``check/*.bin`` vectors, by file name. +RTLIB = { + '0': '00001000010000001122334455667788', + '00': '00002000010000a001000000000000001122334455667788aabbccddeeff0011', + '0fcs': '00001400014000001122334455667788aabbccdd', + '0v0': '00003000010000c0010000a0010000001122334455667788000000000400ffeeddcc000000000000' + 'aabbccddeeff0011', + '0v0-2': '00003000010000c0020000a0010000001122334455667788000000000400ffeeddcc000000000000' + 'aabbccddeeff0011', + '0v0-3': '00003000010000c0020000a0010000001122334455667788000000010400ffeeddcc000000000000' + 'aabbccddeeff0011', + '0v0-4': '00003800010000c000000080000010a001000000000000001122334455667788000000000400' + 'ffeeddcc000000000000aabbccddeeff0011', + '1': '000009000200000033', + 'malformed-vendor': '000022002e4800c000000080000000a00400000010029e09a000e3050000ffffffff', + 'unparsed-vendor': '000027002e4800c000000080000000a00400000010029e09a000e3050000ffffffff' + '0200dead04', +} + +#: The radiotap headers of tcpdump's test-capture records, by file and record. +TCPDUMP = { + 'exthdr#1': '000059006f480080f70177100000000068d698000000000010026c09a000eaaa0100000000000200' + '6c09a000031b68d698000000000001000140334080aa009fff019cffaa00000000000000000000' + '00000000000000000000', + 'exthdr#3': '0000530045840280777f761000000000ddd998000000000002aa1b000000000000026c09a00003' + '1bfc060000000000000000000000000043364380aa009fff019cffe1000000000000000000000000' + '00000000', + 'rx-stbc#1': '000025002b480800641c00000000000010009e098004cd0100002725070000000000000000', + 'rx-stbc#2': '000025002b4808003d0f23070000000010009e098004d20100002741070000000000000000', + 'htc#1': '00003c006b08804086b2ae390000000004003c144001d3950000fcc3fe00e5690f008021027f00037f' + '001000cb050204feff000000000000e06e8e27', +} + +#: The ``reason`` of an ``Unknown`` entry, for a type with no layout and for a +#: field past the region. +NO_LAYOUT = 'no layout is defined for the field type' +PAST = 'the field runs past the field-data region' + +#: Wire octets of each field below, from 0x81 up, so that a signed octet is negative. +PATTERN = bytes(range(0x81, 0xA1)) + +#: The pad octets each field takes after a Flags field ends at octet 9 of the +#: header, and what the field decodes to from :data:`PATTERN`, worked out from +#: its radiotap.org page. +EXPECTED = { + 'Rate': (0, {'rate': 0x81}), + 'Channel': (1, {'frequency': 0x8281, 'flags': 0x8483}), + 'FHSS': (1, {'hop_set': 0x81, 'hop_pattern': 0x82}), + 'Antenna_signal': (0, {'signal': -127}), + 'Antenna_noise': (0, {'noise': -127}), + 'Lock_quality': (1, {'quality': 0x8281}), + 'TX_attenuation': (1, {'attenuation': 0x8281}), + 'dB_TX_attenuation': (1, {'attenuation': 0x8281}), + 'dBm_TX_power': (0, {'power': -127}), + 'Antenna': (0, {'antenna': 0x81}), + 'dB_antenna_signal': (0, {'signal': 0x81}), + 'dB_antenna_noise': (0, {'noise': 0x81}), + 'RX_flags': (1, {'flags': 0x8281}), + 'TX_flags': (1, {'flags': 0x8281}), + 'RTS_retries': (0, {'retries': 0x81}), + 'data_retries': (0, {'retries': 0x81}), + 'MCS': (0, {'known': 0x81, 'flags': 0x82, 'mcs': 0x83}), + 'A_MPDU_status': (3, {'reference': 0x84838281, 'flags': 0x8685, 'delimiter_crc': 0x87, + 'reserved': 0x88}), + 'VHT': (1, {'known': 0x8281, 'flags': 0x83, 'bandwidth': 0x84, 'mcs_nss': (0x85, 0x86, 0x87, 0x88), + 'coding': 0x89, 'group_id': 0x8A, 'partial_aid': 0x8C8B}), + 'timestamp': (7, {'timestamp': 0x8887868584838281, 'accuracy': 0x8A89, 'unit_position': 0x8B, + 'flags': 0x8C}), + 'HE': (1, {'data1': 0x8281, 'data2': 0x8483, 'data3': 0x8685, 'data4': 0x8887, 'data5': 0x8A89, + 'data6': 0x8C8B}), + 'HE_MU': (1, {'flags1': 0x8281, 'flags2': 0x8483, 'ru_channel1': (0x85, 0x86, 0x87, 0x88), + 'ru_channel2': (0x89, 0x8A, 0x8B, 0x8C)}), + 'HE_MU_other_user': (1, {'per_user_1': 0x8281, 'per_user_2': 0x8483, 'per_user_position': 0x85, + 'per_user_known': 0x86}), + 'FieldType_0_length_PSDU': (0, {'psdu_type': 0x81}), + 'L_SIG': (1, {'data1': 0x8281, 'data2': 0x8483}), +} + +#: Octets of each field in :data:`EXPECTED`, from its radiotap.org page. +SIZE = { + 'Rate': 1, 'Channel': 4, 'FHSS': 2, 'Antenna_signal': 1, 'Antenna_noise': 1, 'Lock_quality': 2, + 'TX_attenuation': 2, 'dB_TX_attenuation': 2, 'dBm_TX_power': 1, 'Antenna': 1, + 'dB_antenna_signal': 1, 'dB_antenna_noise': 1, 'RX_flags': 2, 'TX_flags': 2, 'RTS_retries': 1, + 'data_retries': 1, 'MCS': 3, + 'A_MPDU_status': 8, 'VHT': 12, 'timestamp': 12, 'HE': 12, 'HE_MU': 12, 'HE_MU_other_user': 6, + 'FieldType_0_length_PSDU': 1, 'L_SIG': 4, +} + +#: ``(alignment, size)`` of each field in the tables of three parsers, where +#: they give one: the Linux kernel's ``net/wireless/radiotap.c``, Wireshark's +#: ``epan/dissectors/packet-ieee80211-radiotap-iter.c`` and radiotap-library's +#: ``radiotap.c``. Bit 18, which radiotap.org lists as unofficial and none of +#: them sizes, is left out; Wireshark gives bit 25 no size. +REFERENCE = { + 'linux': {0: (8, 8), 1: (1, 1), 2: (1, 1), 3: (2, 4), 4: (2, 2), 5: (1, 1), 6: (1, 1), 7: (2, 2), + 8: (2, 2), 9: (2, 2), 10: (1, 1), 11: (1, 1), 12: (1, 1), 13: (1, 1), 14: (2, 2), + 15: (2, 2), 16: (1, 1), 17: (1, 1), 19: (1, 3), 20: (4, 8), 21: (2, 12)}, + 'wireshark': {0: (8, 8), 1: (1, 1), 2: (1, 1), 3: (2, 4), 4: (2, 2), 5: (1, 1), 6: (1, 1), + 7: (2, 2), 8: (2, 2), 9: (2, 2), 10: (1, 1), 11: (1, 1), 12: (1, 1), 13: (1, 1), + 14: (2, 2), 15: (2, 2), 16: (1, 1), 17: (1, 1), 19: (1, 3), 20: (4, 8), 21: (2, 12), + 22: (8, 12), + 23: (2, 12), 24: (2, 12), 26: (1, 1), 27: (2, 4)}, + 'radiotap-library': {0: (8, 8), 1: (1, 1), 2: (1, 1), 3: (2, 4), 4: (2, 2), 5: (1, 1), 6: (1, 1), + 7: (2, 2), 8: (2, 2), 9: (2, 2), 10: (1, 1), 11: (1, 1), 12: (1, 1), + 13: (1, 1), 14: (2, 2), 15: (2, 2), 16: (1, 1), 17: (1, 1), 19: (1, 3), + 20: (4, 8), 21: (2, 12), 22: (8, 12)}, +} + + +def _radiotap(present: 'list[int]', fields: bytes = b'', it_len: 'int | None' = None) -> bytes: + """Pack a radiotap header: fixed start, present-flags chain, fields.""" + if it_len is None: + it_len = 4 + 4 * len(present) + len(fields) + return struct.pack(' None: + reimport_once_per_class(self) + + def _parse(self, raw: bytes): # type: ignore[no-untyped-def] + from pcapkit.protocols.link.radiotap import Radiotap + + parsed = Radiotap(raw, len(raw)) + self.assertEqual(parsed.data, raw) + return parsed + + def _entries(self, parsed) -> 'list[tuple[str, dict]]': # type: ignore[no-untyped-def] + """The decoded fields as ``(type name, subfields)``, the type left out.""" + return [(key.name, {name: value for name, value in entry.items() if name != 'type'}) + for key, entry in parsed.info.decoded.items(multi=True)] + + def _assert_round_trips(self, parsed, raw: bytes, *, reencodes: bool = True) -> None: # type: ignore[no-untyped-def] + """Rebuild ``raw`` from the info, its dict, and, unless ``reencodes`` is + false, from ``present`` and ``decoded`` through ``make()``.""" + from pcapkit.protocols.link.radiotap import Radiotap + + for data in (parsed.info, parsed.info.to_dict()): + with self.subTest(data=type(data).__name__): + self.assertEqual(Radiotap.from_data(data).data.hex(), raw.hex()) + if reencodes: + made = Radiotap(present=parsed.info.present, fields=parsed.info.decoded, + payload=raw[parsed.info.it_len:]) + self.assertEqual(made.data.hex(), raw.hex()) + + def test_each_field_decodes_at_its_alignment(self) -> None: + """Every field radiotap.org lays out, after a 1-octet Flags field, and its padding.""" + from pcapkit.const.radiotap.field_type import FieldType + + for name, (pad, values) in EXPECTED.items(): + with self.subTest(field=name): + field_type = FieldType[name] + data = PATTERN[:SIZE[name]] + raw = _radiotap([1 << 1 | 1 << field_type], b'\x5a' + bytes(pad) + data) + ACK + parsed = self._parse(raw) + self.assertEqual(self._entries(parsed), [('Flags', {'flags': 0x5A}), (name, values)]) + self.assertEqual(parsed.payload.data, ACK) + self._assert_round_trips(parsed, raw) + + def test_tsft_aligns_from_the_header_start(self) -> None: + """The 8-octet TSFT after one word needs no pad; after two words it takes 4.""" + for present, pad in (([1], 0), ([1 << 31 | 1, 0], 4), ([1 << 31 | 1, 1 << 31, 0], 0)): + with self.subTest(words=len(present)): + raw = _radiotap(present, bytes(pad) + PATTERN[:8]) + parsed = self._parse(raw) + self.assertEqual(self._entries(parsed), [('TSFT', {'mactime': 0x8887868584838281})]) + self._assert_round_trips(parsed, raw) + + def test_radiotap_library_vectors(self) -> None: + """What radiotap-library's ``check/*.out`` prints for each, under its default options.""" + tsft_0 = ('TSFT', {'mactime': 9833440827789222417}) + tsft_1 = ('TSFT', {'mactime': 1225260500033256362}) + reset = ('Radiotap_Namespace', {}) + vendor_head = [('Flags', {'flags': 0x10}), ('Rate', {'rate': 2}), + ('Channel', {'frequency': 2462, 'flags': 0x00A0}), + ('Antenna_signal', {'signal': -29}), ('Antenna', {'antenna': 5}), + ('RX_flags', {'flags': 0})] + + def vendor(sub: int) -> 'tuple[str, dict]': + return ('Vendor_Namespace', {'oui': b'\x00\x00\x00', 'sub_namespace': sub, 'skip_length': 4, + 'data': bytes.fromhex('ffeeddcc')}) + + cases = { + '0': [tsft_0], + '00': [tsft_0, reset, tsft_1], + # its --fcshdr option reads bit 14 as OpenBSD's FCS; the default is RX flags + '0fcs': [tsft_0, ('RX_flags', {'flags': 0xBBAA})], + '0v0': [tsft_0, vendor(0), reset, tsft_1], + '0v0-2': [tsft_0, vendor(0), reset, tsft_1], + '0v0-3': [tsft_0, vendor(1), reset, tsft_1], + '0v0-4': [tsft_0, vendor(0), reset, tsft_1], + '1': [('Flags', {'flags': 0x33})], + 'malformed-vendor': vendor_head + [('Vendor_Namespace', {'data': b'\xff' * 4, 'reason': PAST})], + 'unparsed-vendor': vendor_head + [ + ('Vendor_Namespace', {'oui': b'\xff' * 3, 'sub_namespace': 0xFF, 'skip_length': 2, + 'data': b'\xde\xad'}), + reset, ('Rate', {'rate': 4}), + ], + } + for name, expected in cases.items(): + with self.subTest(vector=name): + raw = bytes.fromhex(RTLIB[name]) + parsed = self._parse(raw) + self.assertEqual(self._entries(parsed), expected) + # 0fcs ends in two octets no bit selects, kept in ``fields`` alone + self._assert_round_trips(parsed, raw, reencodes=name != '0fcs') + + malformed = self._parse(bytes.fromhex(RTLIB['malformed-vendor'])).info.decoded + self.assertEqual(type(malformed.getlist(30)[0]).__name__, 'Unknown') + + def test_tcpdump_captures(self) -> None: + """What tcpdump's ``.out`` file prints for each record, where it decodes the field.""" + signal = 'Antenna_signal' + cases = { + # 10016360us tsft 1.0 Mb/s 2412 MHz 11b -22dBm signal -86dBm noise antenna 1 [bit 32] + 'exthdr#1': [('TSFT', {'mactime': 10016360}), ('Flags', {'flags': 0x10}), ('Rate', {'rate': 2}), + ('Channel', {'frequency': 2412, 'flags': 0x00A0}), (signal, {'signal': -22}), + ('Antenna_noise', {'noise': -86}), ('Antenna', {'antenna': 1}), + ('RX_flags', {'flags': 0}), ('S1G', None)], + # 10017245us tsft 1.0 Mb/s -86dBm noise 27dBm tx power [bit 15] + 'exthdr#3': [('TSFT', {'mactime': 10017245}), ('Rate', {'rate': 2}), + ('Antenna_noise', {'noise': -86}), ('dBm_TX_power', {'power': 27}), + ('TX_flags', {'flags': 0}), ('data_retries', {'retries': 0}), ('S1G', None)], + # 7268us tsft 2462 MHz 11n -51dBm signal antenna 1 ... MCS 7 40 MHz short GI RX-STBC1 + 'rx-stbc#1': [('TSFT', {'mactime': 7268}), ('Flags', {'flags': 0x10}), + ('Channel', {'frequency': 2462, 'flags': 0x0480}), (signal, {'signal': -51}), + ('Antenna', {'antenna': 1}), ('RX_flags', {'flags': 0}), + ('MCS', {'known': 0x27, 'flags': 0x25, 'mcs': 7})], + # 119738173us tsft 2462 MHz 11n -46dBm signal antenna 1 ... MCS 7 40 MHz long GI RX-STBC2 + 'rx-stbc#2': [('TSFT', {'mactime': 119738173}), ('Flags', {'flags': 0x10}), + ('Channel', {'frequency': 2462, 'flags': 0x0480}), (signal, {'signal': -46}), + ('Antenna', {'antenna': 1}), ('RX_flags', {'flags': 0}), + ('MCS', {'known': 0x27, 'flags': 0x41, 'mcs': 7})], + # 967750278us tsft wep 5180 MHz 11a -45dBm signal -107dBm noise antenna 0 [bit 23] + 'htc#1': [('TSFT', {'mactime': 967750278}), ('Flags', {'flags': 0x04}), + ('Channel', {'frequency': 5180, 'flags': 0x0140}), (signal, {'signal': -45}), + ('Antenna_noise', {'noise': -107}), ('Antenna', {'antenna': 0}), + ('HE', {'data1': 0xC3FC, 'data2': 0x00FE, 'data3': 0x69E5, 'data4': 0x000F, + 'data5': 0x2180, 'data6': 0x7F02}), + ('Vendor_Namespace', {'oui': b'\x00\x03\x7f', 'sub_namespace': 0, 'skip_length': 16, + 'data': bytes.fromhex('cb050204feff000000000000e06e8e27')})], + } + for name, expected in cases.items(): + with self.subTest(record=name): + raw = bytes.fromhex(TCPDUMP[name]) + ACK + parsed = self._parse(raw) + entries = self._entries(parsed) + self.assertEqual([key for key, _ in entries], [key for key, _ in expected]) + for (key, values), (_, want) in zip(entries, expected): + if want is None: # a bit no field is defined for: the rest, raw + self.assertEqual(sorted(values), ['data', 'reason']) + self.assertEqual(values['reason'], NO_LAYOUT) + else: + self.assertEqual(values, want, key) + self.assertEqual(parsed.payload.data, ACK) + # rx-stbc's headers end in 8 zero octets no bit selects + self._assert_round_trips(parsed, raw, reencodes=not name.startswith('rx-stbc')) + + def test_namespaces_restart_and_repeat(self) -> None: + """A per-chain signal in each of three radiotap namespaces, as Linux writes them.""" + from pcapkit.const.radiotap.field_type import FieldType + + reset = 1 << 29 | 1 << 31 + present = [1 << 5 | reset, 1 << 5 | 1 << 11 | reset, 1 << 5 | 1 << 11] + raw = _radiotap(present, bytes([0xD8, 0xD6, 0x00, 0xDA, 0x01])) + ACK + parsed = self._parse(raw) + self.assertEqual([key for key, _ in self._entries(parsed)], + ['Antenna_signal', 'Radiotap_Namespace', 'Antenna_signal', 'Antenna', + 'Radiotap_Namespace', 'Antenna_signal', 'Antenna']) + decoded = parsed.info.decoded + self.assertEqual([entry.signal for entry in decoded.getlist(FieldType.Antenna_signal)], [-40, -42, -38]) + self.assertEqual([entry.antenna for entry in decoded.getlist(FieldType.Antenna)], [0, 1]) + self._assert_round_trips(parsed, raw) + + def test_a_namespace_without_a_reset_continues_at_bit_32(self) -> None: + """Bit 0 of a second word is field type 32 there, which no presence bit defines.""" + raw = _radiotap([1 << 1 | 1 << 31, 1], b'\x10\xaa\xbb') + parsed = self._parse(raw) + self.assertEqual(self._entries(parsed), + [('Flags', {'flags': 0x10}), ('S1G', {'data': b'\xaa\xbb', 'reason': NO_LAYOUT})]) + self.assertEqual(type(parsed.info.decoded.getlist(32)[0]).__name__, 'Unknown') + self._assert_round_trips(parsed, raw) + + def test_a_bit_no_field_is_defined_for_ends_the_walk(self) -> None: + """Bit 18, FreeBSD's XChannel, has no layout; the MCS field after it stays raw.""" + raw = _radiotap([1 << 1 | 1 << 18 | 1 << 19], b'\x10\x07\x27\x25\x07') + parsed = self._parse(raw) + self.assertEqual(self._entries(parsed), + [('Flags', {'flags': 0x10}), + ('Unassigned', {'data': b'\x07\x27\x25\x07', 'reason': NO_LAYOUT})]) + self.assertEqual(int(list(parsed.info.decoded)[1]), 18) + self._assert_round_trips(parsed, raw) + + def test_the_unofficial_retries_fields(self) -> None: + """Bits 16 and 17, as Linux writes them on a TX status frame, before an MCS field.""" + raw = _radiotap([1 << 15 | 1 << 16 | 1 << 17 | 1 << 19], b'\x02\x00\x03\x01\x27\x25\x07') + parsed = self._parse(raw) + self.assertEqual(self._entries(parsed), [ + ('TX_flags', {'flags': 0x0002}), ('RTS_retries', {'retries': 3}), ('data_retries', {'retries': 1}), + ('MCS', {'known': 0x27, 'flags': 0x25, 'mcs': 7}), + ]) + self._assert_round_trips(parsed, raw) + + def test_a_field_past_the_region_is_unknown(self) -> None: + """A TSFT with half its octets inside ``it_len``, and a capture cut inside a field.""" + raw = _radiotap([1 << 1 | 1], PATTERN[:4]) + ACK + parsed = self._parse(raw) + self.assertEqual(self._entries(parsed), [('TSFT', {'data': PATTERN[:4], 'reason': PAST})]) + self._assert_round_trips(parsed, raw) + + whole = _radiotap([1 << 3], PATTERN[:4]) + for keep in range(8, len(whole)): + with self.subTest(keep=keep): + parsed = self._parse(whole[:keep]) + self.assertEqual(self._entries(parsed), [('Channel', {'data': whole[8:keep], 'reason': PAST})]) + + def test_tlv_fields(self) -> None: + """Each kind of TLV item, after a Flags field and 3 pad octets.""" + def item(tlv_type: int, data: bytes) -> bytes: + return struct.pack(' None: + """An item whose length runs past ``it_len`` leaves the whole list raw, its pad included.""" + tlvs = struct.pack(' None: # type: ignore[no-untyped-def] + """``value`` is a member of ``registry`` worth ``number``, with the bits of ``named`` set.""" + with self.subTest(registry=registry.__name__): + self.assertIsInstance(value, registry) + self.assertEqual(int(value), number) + self.assertEqual(value & named, named) + + def test_bitmaps_decode_into_their_flag_registries(self) -> None: + """A bitmap radiotap.org defines bit by bit is a registry member, its undefined bits kept.""" + from pcapkit.const.radiotap.ampdu_flags import AMPDUFlags + from pcapkit.const.radiotap.channel_flags import ChannelFlags + from pcapkit.const.radiotap.eht_known import EHTKnown + from pcapkit.const.radiotap.flags import Flags + from pcapkit.const.radiotap.he_mu_other_user_known import HEMUOtherUserKnown + from pcapkit.const.radiotap.lsig_data1 import LSIGData1 + from pcapkit.const.radiotap.mcs_known import MCSKnown + from pcapkit.const.radiotap.rx_flags import RXFlags + from pcapkit.const.radiotap.s1g_known import S1GKnown + from pcapkit.const.radiotap.timestamp_flags import TimestampFlags + from pcapkit.const.radiotap.vht_coding import VHTCoding + from pcapkit.const.radiotap.vht_flags import VHTFlags + from pcapkit.const.radiotap.vht_known import VHTKnown + + # Flags, Channel, RX flags, MCS and VHT; the Channel flags carry the + # undefined bits 0x0008 and 0x8000, the VHT known the unused 0x0200, + # and the VHT coding the unused 0x10 + fields = (b'\x90' + b'\x00' + struct.pack(' None: + """The enum-or-int rule: a member, a composite or an ``int`` writes the same octets.""" + from pcapkit.const.radiotap.flags import Flags + from pcapkit.protocols.link.radiotap import Radiotap + from pcapkit.utilities.exceptions import ProtocolError + + expected = _radiotap([1 << 1], b'\x50') + for value in (Flags.F_FCS | Flags.F_BADFCS, Flags.get(0x50), 0x50): + with self.subTest(value=value): + self.assertEqual(Radiotap(present=(1 << 1,), fields=[(1, {'flags': value})]).data, expected) + for value in ('FCS', 0x100, True): + with self.subTest(value=value), self.assertRaises(ProtocolError): + Radiotap(present=(1 << 1,), fields=[(1, {'flags': value})]) + + def test_make_from_type_and_mapping_pairs(self) -> None: + """``make()`` takes a type as a member or an ``int``, and writes the padding.""" + from pcapkit.const.radiotap.field_type import FieldType + from pcapkit.protocols.link.radiotap import Radiotap + + # a vendor namespace in the second word, then the radiotap one again + present = (1 << 1 | 1 << 3 | 1 << 5 | 1 << 30 | 1 << 31, 1 << 29 | 1 << 31, 1) + fields = [ + (FieldType.Flags, {'flags': 0x10}), + (3, {'frequency': 2412, 'flags': 0x00A0}), + (5, {'signal': -40}), + (FieldType.Vendor_Namespace, {'oui': b'\x00\x13\x74', 'sub_namespace': 2, 'data': b'\x01\x02'}), + (29, {}), + (0, {'mactime': 1}), + ] + made = Radiotap(present=present, fields=fields, payload=ACK) + # Flags at octet 16, a pad, Channel, the signal, a pad, the vendor field + # and its data, then TSFT on the 8-octet boundary at octet 32 + expected = _radiotap(list(present), + b'\x10' + b'\x00' + struct.pack(' None: + """Raw octets are written as given, whatever ``present`` says.""" + from pcapkit.protocols.link.radiotap import Radiotap + + made = Radiotap(present=(1 << 31, 7), fields=b'\x01\x02\x03') + self.assertEqual(made.data, _radiotap([1 << 31, 7], b'\x01\x02\x03')) + + def test_make_rejects_fields_that_do_not_fit(self) -> None: + from pcapkit.const.radiotap.field_type import FieldType + from pcapkit.protocols.link.radiotap import Radiotap + from pcapkit.utilities.exceptions import ProtocolError + + flags = (FieldType.Flags, {'flags': 0}) + cases = { + 'a string': ((2,), 'flags'), + 'not iterable': ((2,), 2), + 'none for a bit': ((2 | 4,), [flags]), + 'one past the bits': ((2,), [flags, flags]), + 'the wrong type': ((2,), [(FieldType.Rate, {'rate': 0})]), + 'a missing subfield': ((2,), [(FieldType.Flags, {})]), + 'an unsigned overflow': ((2,), [(FieldType.Flags, {'flags': 0x100})]), + 'a bool': ((4,), [(FieldType.Rate, {'rate': True})]), + 'a signed overflow': ((1 << 5,), [(FieldType.Antenna_signal, {'signal': 128})]), + 'a short tuple': ((1 << 21,), [(FieldType.VHT, {'known': 0, 'flags': 0, 'bandwidth': 0, + 'mcs_nss': (0,), 'coding': 0, 'group_id': 0, + 'partial_aid': 0})]), + 'a short oui': ((1 << 30,), [(30, {'oui': b'\x00', 'sub_namespace': 0, 'data': b''})]), + 'a wrong skip_length': ((1 << 30,), [(30, {'oui': bytes(3), 'sub_namespace': 0, + 'skip_length': 4, 'data': b''})]), + 'a chain cut short': ((2, 0), [flags]), + 'raw data not bytes': ((1 << 18,), [(18, {'data': 'x'})]), + 'a wrong tlv length': ((1 << 28,), [(28, {'tlvs': [{'type': 32, 'length': 1, 'data': b''}]})]), + 'decoded tlv data of no layout': ((1 << 28,), [(28, {'tlvs': [{'type': 18, 'data': {'x': 1}}]})]), + } + for name, (present, fields) in cases.items(): + with self.subTest(case=name), self.assertRaises(ProtocolError): + Radiotap(present=present, fields=fields) + + def test_unknown_entries_are_written_raw(self) -> None: + """An ``Unknown`` entry, or one for a bit no field is defined for, ends the region.""" + from pcapkit.const.radiotap.field_type import FieldType + from pcapkit.protocols.data.link.radiotap import Unknown + from pcapkit.protocols.link.radiotap import Radiotap + + unknown = Unknown(type=FieldType.TSFT, data=b'\x01\x02', reason='any') + self.assertEqual(Radiotap(present=(1,), fields=[unknown]).data, _radiotap([1], b'\x01\x02')) + self.assertEqual(Radiotap(present=(1 << 18,), fields=[(18, {'data': b'\x03'})]).data, + _radiotap([1 << 18], b'\x03')) + + def test_the_layouts_match_three_parsers(self) -> None: + """Alignment and size of each field's schema, as the Linux kernel, Wireshark and radiotap-library give them.""" + from pcapkit.protocols.schema.link.radiotap import RadiotapField + + for parser, table in REFERENCE.items(): + for bit, (align, size) in table.items(): + with self.subTest(parser=parser, bit=bit): + schema = RadiotapField.registry[bit] + self.assertEqual((schema.__align__, sum(field.length for field in schema.__fields__.values())), + (align, size)) + + def test_each_field_type_pairs_a_schema_with_its_methods(self) -> None: + """``__field__`` and the schema registry name the same types, and each name has its two methods.""" + from pcapkit.protocols.link.radiotap import Radiotap + from pcapkit.protocols.schema.link.radiotap import RadiotapField + + self.assertEqual(sorted(map(int, Radiotap.__field__)), sorted(map(int, RadiotapField.registry))) + for code, name in Radiotap.__field__.items(): + with self.subTest(field=code.name): + self.assertTrue(callable(getattr(Radiotap, f'_read_field_{name}', None))) + self.assertTrue(callable(getattr(Radiotap, f'_make_field_{name}', None))) + + def test_a_ragged_eht_tlv_stays_raw_and_quiet(self) -> None: + """An EHT item whose user words do not end on a word stays raw, and nothing is logged.""" + import logging + + records = [] # type: list[logging.LogRecord] + handler = logging.Handler() + handler.emit = records.append # type: ignore[method-assign] + logger = logging.getLogger('pcapkit') + logger.addHandler(handler) + try: + data = struct.pack('<10I', 0, *range(9)) + b'\xa1\xa2' + raw = _radiotap([1 << 28], struct.pack(' None: + """``register_field`` warns when it displaces an entry, and only then.""" + from unittest import mock + + from pcapkit.const.radiotap.field_type import FieldType + from pcapkit.protocols.link.radiotap import Radiotap + from pcapkit.utilities.warnings import RegistryWarning + + registry = Radiotap.__dict__['__field__'] + try: + with mock.patch('pcapkit.protocols.link.radiotap.warn') as warn: + Radiotap.register_field(FieldType.Channel, 'fhss') + warn.assert_called_once() + self.assertIs(warn.call_args.args[1], RegistryWarning) + self.assertEqual(registry[FieldType.Channel], 'fhss') + finally: + registry[FieldType.Channel] = 'channel' + + # An unregistered type carries no entry, so registering one is not an + # overwrite, and handing back the entry stored, or one equal to it, is a + # silent no-op (#1362). + custom = FieldType.get(18) + self.assertNotIn(custom, registry) + pair = (lambda *_: None, lambda *_: None) + try: + with mock.patch('pcapkit.protocols.link.radiotap.warn') as warn: + Radiotap.register_field(custom, pair) + Radiotap.register_field(custom, pair) + Radiotap.register_field(custom, (pair[0], pair[1])) + warn.assert_not_called() + self.assertIs(registry[custom], pair) + + with mock.patch('pcapkit.protocols.link.radiotap.warn') as warn: + Radiotap.register_field(custom, 'tsft') + warn.assert_called_once() + self.assertEqual(registry[custom], 'tsft') + finally: + registry.pop(custom, None) + + def test_a_field_type_registered_through_the_api_decodes(self) -> None: + """Bit 18, FreeBSD's XChannel, registered with a schema, a parser and a constructor of its own.""" + from unittest import mock + + from pcapkit.const.radiotap.field_type import FieldType + from pcapkit.corekit.fields.numbers import UInt8Field, UInt16Field, UInt32Field + from pcapkit.corekit.infoclass import info_final + from pcapkit.foundation.registry import register_radiotap_field + from pcapkit.protocols.data.link.radiotap import RadiotapField as DataField + from pcapkit.protocols.link.radiotap import Radiotap + from pcapkit.protocols.schema.link.radiotap import RadiotapField + from pcapkit.protocols.schema.schema import schema_final + + @schema_final + class XChannelSchema(RadiotapField): + __align__ = 4 + + flags = UInt32Field(byteorder='little') + frequency = UInt16Field(byteorder='little') + channel = UInt8Field() + maxpower = UInt8Field() + + @info_final + class XChannel(DataField): + flags: int + frequency: int + channel: int + maxpower: int + + def parser(field_type, schema): # type: ignore[no-untyped-def] + return XChannel(type=field_type, flags=schema.flags, frequency=schema.frequency, + channel=schema.channel, maxpower=schema.maxpower) + + def constructor(field_type, entry): # type: ignore[no-untyped-def] + return XChannelSchema(flags=entry['flags'], frequency=entry['frequency'], + channel=entry['channel'], maxpower=entry['maxpower']) + + raw = _radiotap([1 << 1 | 1 << 18 | 1 << 19], + b'\x10' + bytes(3) + struct.pack(' None: + """The capture path of #2502: ``LINUX_SLL`` with ``ARPHRD_IEEE80211_RADIOTAP``.""" + from pcapkit.const.linux.arphrd import ARPHRD + from pcapkit.protocols.link.linux_sll1 import LinuxSLL1 + + radiotap = bytes.fromhex(TCPDUMP['rx-stbc#1']) + raw = (struct.pack('>HHH', 0, ARPHRD.IEEE80211_RADIOTAP, 0) + bytes(8) + struct.pack('>H', 0) + + radiotap + ACK) + parsed = LinuxSLL1(raw, len(raw)) + self.assertEqual(parsed.protochain.chain, 'LINUX_SLL1:Radiotap:802.11:Raw') + self.assertEqual(parsed.payload.info.decoded[19].mcs, 7) + self.assertEqual(parsed.data, raw) + self.assertEqual(type(parsed).from_data(parsed.info).data, raw) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/vendor/test_radiotap_crawler_2576_unit.py b/tests/vendor/test_radiotap_crawler_2576_unit.py new file mode 100644 index 0000000000..74d3bb3b9a --- /dev/null +++ b/tests/vendor/test_radiotap_crawler_2576_unit.py @@ -0,0 +1,575 @@ +# -*- coding: utf-8 -*- +"""GitHub issue #2576: the radiotap crawlers. + +:mod:`pcapkit.vendor.radiotap.field_type` scrapes radiotap.org's *Defined +Fields* table and two rows of its *Unofficially Used Fields* one, and each flag +crawler the table on its field's page. Regenerating each constant module from +the fixtures below, the tables as radiotap.org served them on 2026-11-01, is a +no-op against the committed file, so a crawler edit that was never regenerated +fails here. + +**The fixtures are built inline and parsed with the same** ``html5lib`` **the +crawlers use**, rather than fetched, as in ``test_ftp_return_code_unit.py``: +the unit tier makes no network call. + +The suite is unit-tier (see :mod:`tests._tiers`): it reads no capture and makes +no network call. + +""" +from __future__ import annotations + +import html +import importlib +import importlib.util +import pathlib +import unittest +from typing import TYPE_CHECKING + +from tests._support import reimport_once_per_class + +if TYPE_CHECKING: + from typing import Any + +#: Test tier (#1958): renders the constant modules from recorded data and compares them +#: with the committed files, which the vendor scripts regenerate on one interpreter. +__tier__ = 'LATEST' + +#: Repository root, i.e. the grandparent of the directory holding this file. +ROOT = pathlib.Path(__file__).resolve().parents[2] + +#: The distributions importing :mod:`pcapkit.vendor` with its crawlers needs, as +#: ``test_ipx_packet_unit.py`` names them. +VENDOR_DEPS = ('requests', 'bs4', 'html5lib') + +#: Whether the crawlers are importable at all; see ``test_ipx_packet_unit.py``. +HAS_VENDOR_DEPS = all(importlib.util.find_spec(name) is not None for name in VENDOR_DEPS) + +#: Each row of the *Defined Fields* table, as ``(bit number, field, page)``. +ROWS = ( + (0, 'TSFT', 'TSFT'), (1, 'Flags', 'Flags'), (2, 'Rate', 'Rate'), (3, 'Channel', 'Channel'), + (4, 'FHSS', 'FHSS'), (5, 'Antenna signal', 'Antenna%20signal'), + (6, 'Antenna noise', 'Antenna%20noise'), (7, 'Lock quality', 'Lock%20quality'), + (8, 'TX attenuation', 'TX%20attenuation'), (9, 'dB TX attenuation', 'dB%20TX%20attenuation'), + (10, 'dBm TX power', 'dBm%20TX%20power'), (11, 'Antenna', 'Antenna'), + (12, 'dB antenna signal', 'dB%20antenna%20signal'), (13, 'dB antenna noise', 'dB%20antenna%20noise'), + (14, 'RX flags', 'RX%20flags'), (15, 'TX flags', 'TX%20flags'), (19, 'MCS', 'MCS'), + (20, 'A-MPDU status', 'A-MPDU%20status'), (21, 'VHT', 'VHT'), (22, 'timestamp', 'timestamp'), + (23, 'HE', 'HE'), (24, 'HE-MU', 'HE-MU'), (25, 'HE-MU-other-user', 'HE-MU-other-user'), + (26, '0-length-PSDU', '0-length-PSDU'), (27, 'L-SIG', 'L-SIG'), + (28, 'TLV fields in radiotap', 'TLV'), (29, 'Radiotap Namespace', 'Radiotap%20Namespace'), + (30, 'Vendor Namespace', 'Vendor%20Namespace'), (32, 'S1G', 'S1G'), (33, 'U-SIG', 'U-SIG'), + (34, 'EHT', 'EHT'), +) + +#: Each row of the *Unofficially Used Fields* table, as ``(bit number, field, +#: page, generators, parsers)``. +UNOFFICIAL_ROWS = ( + (14, 'FCS in header', 'FCS%20in%20header', 'OpenBSD', 'wireshark'), + (16, 'RSSI', 'RSSI', 'OpenBSD', ''), + (16, 'RTS retries', 'RTS%20retries', 'Linux (only libertas driver), NetBSD (?)', ''), + (17, 'data retries', 'data%20retries', 'Linux (mac80211)', 'wireshark'), + (18, 'XChannel', 'XChannel', 'FreeBSD, OS X', 'wireshark (partial)'), +) + +#: The *Defined Fields* page, in the shape the live one has: a header row of bold +#: cells, then one row per field, the name linked to its page. +FIXTURE = ''.join(( + 'Radiotap - Defined Fields', + '

Defined Fields

The following fields are defined:

', + '', + *(f'' for bit, name, page in ROWS), + '
bit numberfield
{bit}{name}

', +)) + +#: The *Unofficially Used Fields* page, in the same shape. +UNOFFICIAL = ''.join(( + 'Radiotap - Unofficially Used Fields', + '

Unofficially Used Fields

', + '', + '', + *(f'' + f'' for bit, name, page, generators, parsers in UNOFFICIAL_ROWS), + '
bit numberfieldgenerators/OS(es)parser(s)
{bit}{name}{generators}{parsers}
', +)) + +#: Each flag crawler's page, as ``(module, class, page)``. +FLAG_CRAWLERS = ( + ('flags', 'Flags', 'Flags'), ('channel_flags', 'ChannelFlags', 'Channel'), + ('rx_flags', 'RXFlags', 'RX flags'), ('tx_flags', 'TXFlags', 'TX flags'), + ('mcs_known', 'MCSKnown', 'MCS'), ('ampdu_flags', 'AMPDUFlags', 'A-MPDU status'), + ('vht_known', 'VHTKnown', 'VHT'), ('vht_flags', 'VHTFlags', 'VHT'), ('vht_coding', 'VHTCoding', 'VHT'), + ('timestamp_flags', 'TimestampFlags', 'timestamp'), + ('he_mu_other_user_known', 'HEMUOtherUserKnown', 'HE-MU-other-user'), + ('lsig_data1', 'LSIGData1', 'L-SIG'), ('s1g_known', 'S1GKnown', 'S1G'), ('eht_known', 'EHTKnown', 'EHT'), +) + +#: Prefixes the name maps' macros carry, which the member names drop. +PREFIXES = ('IEEE80211_RADIOTAP_', 'IEEE80211_') + +#: The tables of each field page, and the one after them where a page holds +#: more, which no crawler takes: ``(heading, paragraph, subfield, rows)``, the +#: heading and subfield :obj:`None` where the page has none. Cell texts are kept +#: as served, ``«BR»`` included. +PAGES = {'A-MPDU status': ((None, + 'The following flags are defined:', + None, + (('0x0001', 'driver reports 0-length subframes'), + ('0x0002', 'frame is 0-length subframe (valid only if 0x0001 is set)'), + ('0x0004', 'last subframe is known (should be set for all subframes in an A-MPDU)'), + ('0x0008', 'this frame is the last subframe'), + ('0x0010', 'delimiter CRC error'), + ('0x0020', 'delimiter CRC value known: the delimiter CRC value field is valid'), + ('0x0040', 'EOF value'), + ('0x0080', 'EOF value known'), + ('0xff00', 'reserved'))),), + 'Channel': ((None, + 'Currently, the following flags are defined:', + None, + (('Mask', 'Meaning'), + ('0x0001', 'S1G 700MHz spectrum channel'), + ('0x0002', 'S1G 800MHz spectrum channel'), + ('0x0004', 'S1G 900MHz spectrum channel'), + ('0x0010', 'Turbo Channel'), + ('0x0020', 'CCK channel'), + ('0x0040', 'OFDM channel'), + ('0x0080', '2 GHz spectrum channel'), + ('0x0100', '5 GHz spectrum channel'), + ('0x0200', 'Only passive scan allowed'), + ('0x0400', 'Dynamic CCK-OFDM channel'), + ('0x0800', 'GFSK channel (FHSS PHY)'))),), + 'EHT': (('known', + 'Note that for trigger-based (TB) PPDUs, the EHT-SIG isn’t present over the air as all the ' + 'information for each station is provided in the trigger frame. Sniffer should - where possible - ' + 'provide a subset of the OFDMA related fields to simplify understanding of the resulting capture ' + '(i.e. to be able to read it without having to go back to the prior trigger frame.)', + 'known', + (('bits', 'OFDMA (including TB)', 'MU-MIMO', 'EHT sounding'), + ('0x00000001', '(reserved)', '(reserved)', '(reserved)'), + ('0x00000002', 'Spatial Reuse Known', '(same)', '(same)'), + ('0x00000004', 'GI (Guard Interval) Known', '(same)', '(same)'), + ('0x00000008', '(reserved)', '(reserved)', '(reserved)'), + ('0x00000010', 'number of LTF symbols Known', '(same)', '(same)'), + ('0x00000020', 'LDPC Extra Symbol Segment Known', '(same)', '(reserved)'), + ('0x00000040', 'Pre-FEC Padding Factor Known', '(same)', '(reserved)'), + ('0x00000080', 'PE Disambiguity Known', '(same)', '(reserved)'), + ('0x00000100', 'Disregard Known', '(same)', '(reserved)'), + ('0x00000200', '(reserved)', '(reserved)', 'Disregard Known'), + ('0x00001c00', '(reserved)', '(reserved)', '(reserved)'), + ('0x00002000', 'CRC1 Known', '(same)', '(same)'), + ('0x00004000', 'Tail1 Known', '(same)', '(same)'), + ('0x00008000', 'CRC2 Known', '(reserved)', '(reserved)'), + ('0x00010000', 'Tail2 Known', '(reserved)', '(reserved)'), + ('0x00020000', '(reserved)', '(reserved)', 'NSS Known'), + ('0x00040000', '(reserved)', '(reserved)', 'Beamformed Known'), + ('0x00080000', '(reserved)', 'Number Of Non-OFDMA Users Known', '(reserved)'), + ('0x00100000', '(reserved)', 'User Encoding Block CRC Known', '(reserved)'), + ('0x00200000', '(reserved)', 'User Encoding Block Tail Known', '(reserved)'), + ('0x00400000', 'RU/MRU Size Known', '(same)', '(reserved)'), + ('0x00800000', 'RU/MRU Index Known', '(same)', '(reserved)'), + ('0x01000000', 'RU Allocation (TB format) Known', '(same)', '(reserved)'), + ('0x02000000', 'Primary 80 MHz Channel Position known', '(same)', '(same)'), + ('0xfc000000', '(reserved)', '(reserved)', '(reserved)'))), + ('data[0]', + 'data[0]', + 'data[0]', + (('bits', 'meaning'), + ('0x00000007', '(reserved)'), + ('0x00000078', 'Spatial Reuse'), + ('0x00000180', 'GI (0=0.8us, 1=1.6us, 2=3.2us, 3=reserved)'), + ('0x00000600', 'LTF symbol size (0=unknown, 1=1x, 2=2x, 3=4x)'), + ('0x00003800', 'number of LTF symbols (0=1x, 1=2x, 2=4x, 3=6x, 4=8x, 5-7=reserved)'), + ('0x00004000', 'LDPC extra symbol segment'), + ('0x00018000', 'Pre-FEC padding factor'), + ('0x00020000', 'PE Disambiguity'), + ('0x000c0000', 'Disregard (EHT sounding)'), + ('0x00300000', '(reserved) (EHT sounding)'), + ('0x003c0000', 'Disregard (non EHT sounding)'), + ('0x03c00000', 'CRC1 (OFDMA: B0-16+9N, EHT sounding: B0-15, non-OFDMA: B0-41)'), + ('0xfc000000', 'Tail1')))), + 'Flags': ((None, + 'Currently, the following flags are defined:', + None, + (('Mask', 'Meaning'), + ('0x01', 'sent/received during CFP'), + ('0x02', 'sent/received with short preamble'), + ('0x04', 'sent/received with WEP encryption'), + ('0x08', 'sent/received with fragmentation'), + ('0x10', 'frame includes FCS'), + ('0x20', 'frame has padding between 802.11 header and payload (to 32-bit boundary)'), + ('0x40', 'frame failed FCS check'))), + (None, + 'Currently unspecified but used:', + None, + (('Mask', 'Meaning'), ('0x80', 'frame used short guard interval (HT)')))), + 'HE-MU-other-user': (('per_user_1', + 'per_user_1', + 'per_user_1', + (('0x7fff', 'B0-B14 of the HE-SIG-B user field as in spec'), + ('0x8000', '(reserved)'))), + ('per_user_2', + 'per_user_2', + 'per_user_2', + (('0x003f', 'B15-B20 of the HE-SIG-B user field as in spec'), + ('0xffc0', '(reserved)'))), + ('per_user_known', + 'per_user_known', + 'per_user_known', + (('0x01', 'user field position known'), + ('0x02', 'STA-ID known (B0-10)'), + ('0x04', 'NSTS known (B11-13, only for non-MU-MIMO)'), + ('0x08', 'Tx Beamforming known (B14, only for non-MU-MIMO)'), + ('0x10', 'Spatial Configuration known (B11-B14, only for MU-MIMO)'), + ('0x20', 'MCS known (B15-18)'), + ('0x40', 'DCM known (B19)'), + ('0x80', 'Coding known (B20)')))), + 'L-SIG': (('data1', + 'data1', + 'data1', + (('0x0001', 'rate known'), ('0x0002', 'length known'), ('0xfffc', '(reserved)'))), + ('data2', 'data2', 'data2', (('0x000f', 'rate'), ('0xfff0', 'length')))), + 'MCS': ((None, + 'The known field indicates which information is known:', + 'known', + (('flag', 'definition'), + ('0x01', 'bandwidth'), + ('0x02', 'MCS index known (in mcs part of the field)'), + ('0x04', 'guard interval'), + ('0x08', 'HT format'), + ('0x10', 'FEC type'), + ('0x20', 'STBC known'), + ('0x40', 'Ness known (Number of extension spatial streams)'), + ('0x80', 'Ness data - bit 1 (MSB) of Number of extension spatial streams'))), + (None, + 'The flags field is any combination of the following:', + 'flags', + (('flag', 'definition'), + ('0x03', 'bandwidth - 0: 20, 1: 40, 2: 20L, 3: 20U'), + ('0x04', 'guard interval - 0: long GI, 1: short GI'), + ('0x08', 'HT format - 0: mixed, 1: greenfield'), + ('0x10', 'FEC type - 0: BCC, 1: LDPC'), + ('0x60', 'Number of STBC streams'), + ('0x80', 'Ness - bit 0 (LSB) of Number of extension spatial streams')))), + 'RX flags': ((None, + 'The following flags are currently defined:', + None, + (('mask', 'meaning'), + ('0x0001', 'reserved (was FCS failed but this is a regular flag)'), + ('0x0002', 'PLCP CRC check failed'), + ('0xfffc', 'reserved for future expansion'))),), + 'S1G': (('known', + 'known', + 'known', + (('0x0001', 'S1G PPDU Format known'), + ('0x0002', 'Response indication known'), + ('0x0004', 'Guard interval known'), + ('0x0008', 'NSS known'), + ('0x0010', 'Bandwidth known'), + ('0x0020', 'MCS known'), + ('0x0040', 'Color known'), + ('0x0080', 'uplink indication known'), + ('0xFF00', 'Reserved'))), + ('data1', + 'data1', + 'data1', + (('0x0003', 'S1G PPDU Format: 0=S1G_1M, 1=S1G_SHORT, 2=S1G_LONG'), + ('0x000C', + 'Response indication: 0=NO_RESPONSE, 1=NDP_RESPONSE, 2=NORMAL_RESPONSE, 3=LONG_RESPONSE'), + ('0x0010', 'Reserved'), + ('0x0020', 'Guard interval: 0=Long GI, 1=Short GI'), + ('0x00C0', 'Number spatial streams: 0=1 Spatial stream, 1=2, .. 3=4 Spatial streams'), + ('0x0F00', 'Bandwidth: 0=1MHz, 1=2MHz, 2=4MHz, 3=8MHz, 4=16MHz, 5-15 reserved'), + ('0xF000', 'MCS (MCS rate index, 0-10, 11-15 reserved)')))), + 'TX flags': ((None, + 'Properties of transmitted frames.', + None, + (('mask', 'meaning'), + ('0x0001', 'Transmission failed due to excessive retries'), + ('0x0002', 'Transmission used CTS-to-self protection'), + ('0x0004', 'Transmission used RTS/CTS handshake'), + ('0x0008', + 'Transmission shall not expect an ACK frame and not retry when no ACK is received'), + ('0x0010', + 'Transmission includes a pre-configured sequence number that should not be changed by the ' + 'driver’s TX handlers'), + ('0x0020', + 'Transmission should not be reordered relative to other frames that have this flag set'))),), + 'VHT': ((None, + 'The known field indicates which information is known:', + 'known', + (('flag', 'definition', 'notes'), + ('0x0001', 'STBC known', 'In flags part of the field.'), + ('0x0002', 'TXOP_PS_NOT_ALLOWED known', 'In flags part of the field.'), + ('0x0004', 'Guard interval', 'In flags part of the field.'), + ('0x0008', 'Short GI NSYM disambiguation known', 'In flags part of the field.'), + ('0x0010', 'LDPC extra OFDM symbol known', 'In flags part of the field.'), + ('0x0020', + 'Beamformed known/applicable', + 'In flags part of the field. This flag should be set to zero for MU PPDUs.'), + ('0x0040', 'Bandwidth known', 'In bandwidth part of the field.'), + ('0x0080', 'Group ID known', 'In group_id part of the field.'), + ('0x0100', + 'Partial AID known/applicable', + 'In partial_aid part of the field. This flag should be set to zero for MU PPDUs.'), + ('0xfe00', '(unused)', ''))), + (None, + 'The flags field is any combination of the following:', + 'flags', + (('flag', 'definition', 'notes'), + ('0x01', + 'STBC', + 'Space-time block coding.«BR»Set to 0 if no spatial streams of any user has STBC.«BR»Set to 1 if ' + 'all spatial streams of all users have STBC.'), + ('0x02', + 'TXOP_PS_NOT_ALLOWED', + 'Valid only for AP transmitters.«BR»Set to 0 if STAs may doze during TXOP.«BR»Set to 1 if STAs ' + 'may not doze during TXOP or transmitter is non-AP.'), + ('0x04', 'Guard interval.', 'Set to 0 for long GI.«BR»Set to 1 for short GI.'), + ('0x08', + 'Short GI NSYM disambiguation', + 'Valid only if short GI is used.«BR»Set to 0 if NSYM mod 10 != 9 or short GI not used.«BR»Set to ' + '1 if NSYM mod 10 = 9.'), + ('0x10', + 'LDPC Extra OFDM symbol', + 'Set to 1 if one or more users are using LDPC and the encoding process resulted in extra OFDM ' + 'symbol(s).«BR»Set to 0 otherwise.'), + ('0x20', 'Beamformed', 'Valid for SU PPDUs only.'), + ('0xc0', '(unused)', ''))), + (None, + 'The bandwidth field encodes the bandwidth:', + 'bandwidth', + (('bitmask', 'definition', 'notes'), ('0x1f', 'Bandwidth', ''), ('0xe0', '(unused)', ''))), + (None, + 'Bandwidth values are:', + 'bandwidth', + (('value', 'total bandwidth (MHz)', 'sideband', 'sideband index'), + ('0', '20', '', ''), + ('1', '40', '', ''), + ('2', '40', '20L', '0'), + ('3', '40', '20U', '1'), + ('4', '80', '', ''), + ('5', '80', '40L', '0'), + ('6', '80', '40U', '1'), + ('7', '80', '20LL', '0'), + ('8', '80', '20LU', '1'), + ('9', '80', '20UL', '2'), + ('10', '80', '20UU', '3'), + ('11', '160', '', ''), + ('12', '160', '80L', '0'), + ('13', '160', '80U', '1'), + ('14', '160', '40LL', '0'), + ('15', '160', '40LU', '1'), + ('16', '160', '40UL', '2'), + ('17', '160', '40UU', '3'), + ('18', '160', '20LLL', '0'), + ('19', '160', '20LLU', '1'), + ('20', '160', '20LUL', '2'), + ('21', '160', '20LUU', '3'), + ('22', '160', '20ULL', '4'), + ('23', '160', '20ULU', '5'), + ('24', '160', '20UUL', '6'), + ('25', '160', '20UUU', '7'))), + (None, + 'The four mcs_nss fields encode MCS and NSS for up to four users:', + 'bandwidth', + (('bitmask', 'definition', 'notes'), + ('0x0f', 'NSS', 'Number of spatial streams, range 1-8.'), + ('0xf0', 'MCS', 'MCS rate index, range 0-9.'))), + (None, + 'The coding field encodes the FEC for up to four users:', + 'coding', + (('bitmask', 'definition', 'notes'), + ('0x01', 'Coding for user 0', 'Set to 0 for BCC.«BR»Set to 1 for LDPC.'), + ('0x02', 'Coding for user 1', 'Set to 0 for BCC.«BR»Set to 1 for LDPC.'), + ('0x04', 'Coding for user 2', 'Set to 0 for BCC.«BR»Set to 1 for LDPC.'), + ('0x08', 'Coding for user 3', 'Set to 0 for BCC.«BR»Set to 1 for LDPC.'), + ('0xf0', '(unused)', '')))), + 'timestamp': (('unit/position', + 'unit/position', + 'unit/position', + (('flag', 'meaning'), + ('0x000F', 'unit - see below'), + ('0x00F0', 'sampling position - see below'))), + ('unit/position', + 'unit/position', + 'unit/position', + (('value', 'unit'), + ('0', 'milliseconds'), + ('1', 'microseconds'), + ('2', 'nanoseconds'), + ('3-15', 'reserved'))), + ('unit/position', + 'unit/position', + 'unit/position', + (('value', 'sampling position'), + ('0', 'first bit (or symbol containing it) of MPDU - matches TSFT field'), + ('1', 'signal acquisition at start of PLCP'), + ('2', 'end of PPDU'), + ('3', 'end of MPDU (after FCS)'), + ('4-14', 'reserved'), + ('15', 'unknown or vendor/OOB defined'))), + ('flags', + 'flags', + 'flags', + (('0x01', '32-bit counter (high 32 bits are unused)'), + ('0x02', 'accuracy known'), + ('0xFC', 'reserved'))))} + + +def _page(name: 'str') -> 'str': + """Render the fixture of a field page, in the shape the live one has.""" + parts = [f'Radiotap - {name}

{name}

'] + for heading, paragraph, subfield, rows in PAGES[name]: + if heading is not None: + parts.append(f'

{heading}

') + if subfield is not None and heading is None: + rest = paragraph[len(f'The {subfield}'):] + parts.append(f'

The {subfield}{html.escape(rest)}

') + else: + parts.append(f'

{html.escape(paragraph)}

') + parts.append('') + parts.extend('' + ''.join(f'' for cell in row) + '' for row in rows) + parts.append('
{html.escape(cell)}
') + parts.append('') + return ''.join(parts) + + +def _normalize(context: 'str') -> 'str': + """Apply the whitespace normalisation the generator writes files through, + as ``test_ipx_packet_unit.py`` does.""" + lines = [] # type: list[str] + for line in context.splitlines(): + if line: + if line.strip(): + lines.append(line.rstrip()) + else: + lines.append(line) + return '\n'.join(lines) + '\n' + + +@unittest.skipUnless(HAS_VENDOR_DEPS, f'vendor extra not installed ({", ".join(VENDOR_DEPS)})') +class RadiotapCrawlerTests(unittest.TestCase): + """The scraped radiotap.org tables, and the registries they generate.""" + + def setUp(self) -> None: + reimport_once_per_class(self) + + def _crawler(self, module: 'str', name: 'str') -> 'Any': + """The crawler class, skipping when it was imported from another tree.""" + vendor_module = importlib.import_module(f'pcapkit.vendor.radiotap.{module}') + const_module = importlib.import_module(f'pcapkit.const.radiotap.{module}') + for found in (vendor_module, const_module): + resolved = pathlib.Path(found.__file__).resolve() + if ROOT not in resolved.parents: + self.skipTest(f'{found.__name__} was imported from {resolved}, which is outside ' + f'{ROOT}; install this checkout with `pip install -e .`') + return getattr(vendor_module, name) + + def _assert_regenerates(self, module: 'str', name: 'str', *pages: 'str') -> None: + """Rendering ``pages`` through the crawler reproduces the committed module.""" + klass = self._crawler(module, name) + vendor = klass.__new__(klass) + vendor.NAME = klass.__name__ + vendor.DOCS = klass.__doc__ + data = [item for page in pages for item in vendor.request(page)] + vendor.record = vendor.count(data) + generated = _normalize(vendor.context(data)) + path = ROOT / 'pcapkit' / 'const' / 'radiotap' / f'{module}.py' + self.assertEqual(generated, path.read_text(encoding='utf-8'), + f'regenerating {path.relative_to(ROOT)} would change it; run ' + '`pcapkit-vendor radiotap` and commit the result') + + def test_field_types_regenerate(self) -> None: + self._assert_regenerates('field_type', 'FieldType', FIXTURE, UNOFFICIAL) + + def test_flag_registries_regenerate(self) -> None: + for module, name, page in FLAG_CRAWLERS: + with self.subTest(crawler=name): + self._assert_regenerates(module, name, _page(page)) + + def test_the_crawlers_scrape_radiotap_org(self) -> None: + klass = self._crawler('field_type', 'FieldType') + self.assertEqual(klass.LINK, 'https://www.radiotap.org/fields/defined') + self.assertEqual(importlib.import_module(klass.__module__).UNOFFICIAL_LINK, + 'https://www.radiotap.org/fields/unofficial') + rows = klass.__new__(klass).request(FIXTURE) + self.assertEqual([int(row.select('td')[0].text) for row in rows], [bit for bit, _, _ in ROWS]) + for module, name, page in FLAG_CRAWLERS: + with self.subTest(crawler=name): + klass = self._crawler(module, name) + self.assertEqual(klass.LINK, f'https://www.radiotap.org/fields/{page.replace(" ", "%20")}.html') + + def test_a_crawler_takes_its_subfield_alone(self) -> None: + """A page tabulating several subfields gives each crawler its own table.""" + for module, name, page, count in (('mcs_known', 'MCSKnown', 'MCS', 1), ('vht_known', 'VHTKnown', 'VHT', 1), + ('vht_flags', 'VHTFlags', 'VHT', 1), ('vht_coding', 'VHTCoding', 'VHT', 1), + ('timestamp_flags', 'TimestampFlags', 'timestamp', 1), + ('lsig_data1', 'LSIGData1', 'L-SIG', 1), ('s1g_known', 'S1GKnown', 'S1G', 1), + ('he_mu_other_user_known', 'HEMUOtherUserKnown', 'HE-MU-other-user', 1), + ('flags', 'Flags', 'Flags', 2)): + with self.subTest(crawler=name): + klass = self._crawler(module, name) + tables = klass.__new__(klass).request(_page(page)) + self.assertEqual(len(tables), count) + + def test_members_take_the_name_maps(self) -> None: + """Every member is named after its map's macro, less the prefix, and no map name is unused.""" + for module, name, _ in FLAG_CRAWLERS: + with self.subTest(crawler=name): + klass = self._crawler(module, name) + registry = getattr(importlib.import_module(f'pcapkit.const.radiotap.{module}'), name) + members = {int(member): member.name for member in registry} + self.assertTrue(set(klass.NAMES) <= set(members), 'a map names a bit the page does not') + for mask, macro in klass.NAMES.items(): + prefix = next(prefix for prefix in PREFIXES if macro.startswith(prefix)) + self.assertEqual(members[mask], macro[len(prefix):]) + if module == 'he_mu_other_user_known': + # neither Linux nor Wireshark names these bits + self.assertEqual((klass.NAMES, members[0x01]), ({}, 'user_field_position_known')) + else: + self.assertEqual(set(klass.NAMES), set(members), 'a member falls back to radiotap.org wording') + + def test_every_row_is_a_member(self) -> None: + """Every defined field, and RTS retries and data retries from the unofficial table.""" + from pcapkit.const.radiotap.field_type import FieldType + + self.assertEqual([member.value for member in FieldType], sorted([bit for bit, _, _ in ROWS] + [16, 17])) + self.assertEqual(FieldType(26).name, 'FieldType_0_length_PSDU') + self.assertEqual((FieldType(16).name, FieldType(17).name), ('RTS_retries', 'data_retries')) + # the unofficial rows the registry leaves out + self.assertEqual((FieldType(14).name, FieldType(18).name), ('RX_flags', 'Unassigned')) + + def test_values_the_table_leaves_out(self) -> None: + """Bits 29 to 31 of every word are reserved; the rest are unassigned, up to the TLV type's width.""" + from pcapkit.const.radiotap.field_type import FieldType + + for value, name in ((31, 'Reserved'), (61, 'Reserved'), (62, 'Reserved'), (63, 'Reserved'), + (18, 'Unassigned'), (35, 'Unassigned'), (0xFFFF, 'Reserved')): + with self.subTest(value=value): + self.assertEqual(FieldType(value).name, name) + self.assertEqual(FieldType.get(value), value) + for value in (-1, 0x10000): + with self.subTest(value=value), self.assertRaises(ValueError): + FieldType(value) + + def test_flag_registries_keep_the_bits_they_do_not_name(self) -> None: + """An undefined bit stays in the value; a value past the field's width is refused.""" + from pcapkit.const.radiotap.channel_flags import ChannelFlags + from pcapkit.const.radiotap.eht_known import EHTKnown + from pcapkit.const.radiotap.rx_flags import RXFlags + + cck_2ghz = ChannelFlags.get(0x00A0) + self.assertEqual(cck_2ghz, ChannelFlags.CHAN_CCK | ChannelFlags.CHAN_2GHZ) + for registry, value in ((ChannelFlags, 0x0008), (ChannelFlags, 0x80A8), (RXFlags, 0x0003), + (EHTKnown, 0x00000001), (EHTKnown, 0xFC000002)): + with self.subTest(registry=registry.__name__, value=hex(value)): + member = registry.get(value) + self.assertIsInstance(member, registry) + self.assertEqual(int(member), value) + self.assertIn(RXFlags.F_RX_BADPLCP, RXFlags.get(0x0003)) + for registry, value in ((ChannelFlags, 0x10000), (RXFlags, -1), (EHTKnown, 1 << 32)): + with self.subTest(registry=registry.__name__, value=value), self.assertRaises(ValueError): + registry(value) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/vendor/test_vendor_missing_body_unit.py b/tests/vendor/test_vendor_missing_body_unit.py index 2f12cfe930..e5ecbeca5e 100644 --- a/tests/vendor/test_vendor_missing_body_unit.py +++ b/tests/vendor/test_vendor_missing_body_unit.py @@ -118,6 +118,7 @@ 'pcapkit/vendor/pcapng/record_type.py', 'pcapkit/vendor/pcapng/secrets_type.py', 'pcapkit/vendor/pcapng/verdict_type.py', + 'pcapkit/vendor/radiotap/field_type.py', 'pcapkit/vendor/reg/linktype.py', 'pcapkit/vendor/sslv2/handshake_type.py', 'pcapkit/vendor/sslv2/version.py',