diff --git a/docs/source/contributing/pep.rst b/docs/source/contributing/pep.rst index 4706b98401..c81099e71b 100644 --- a/docs/source/contributing/pep.rst +++ b/docs/source/contributing/pep.rst @@ -298,8 +298,8 @@ small part of each is bound to a dissector; everything else resolves to complaint and yields nothing useful. * :class:`~pcapkit.const.reg.linktype.LinkType` -- - ``NULL``, ``ETHERNET``, ``LOOP``, ``LINUX_SLL``, ``IPV4``, ``IPV6`` and - ``LINUX_SLL2``, declared identically + ``NULL``, ``ETHERNET``, ``IEEE802_11``, ``FRELAY``, ``LOOP``, ``LINUX_SLL``, + ``IEEE802_11_RADIOTAP``, ``IPV4``, ``IPV6`` and ``LINUX_SLL2``, declared identically in :class:`~pcapkit.protocols.misc.pcap.frame.Frame` and :class:`~pcapkit.protocols.misc.pcapng.PCAPNG`, which also read ``RAW`` as ``IPV4`` or ``IPV6`` by its version nibble. @@ -961,9 +961,11 @@ offload heuristic on :issue:`2470`. clear is :attr:`~pcapkit.corekit.checksum.internet.ChecksumStatus.NOT_COMPUTED`, and ``make()`` computes one when ``checksum_present`` asks without giving it. Neither GRE nor the Linux cooked-capture header carries a length, so a GRE frame - the capture cut short is - :attr:`~pcapkit.corekit.checksum.internet.ChecksumStatus.INVALID`. Settled at - implementation (:issue:`2618`). + the capture cut short there is + :attr:`~pcapkit.corekit.checksum.internet.ChecksumStatus.INVALID`, settled at + implementation (:issue:`2618`); behind IPv4 or IPv6, which state the payload + length, it is :attr:`~pcapkit.corekit.checksum.internet.ChecksumStatus.TRUNCATED` + (:issue:`2649`). * **DCCP covers what its Checksum Coverage gives** (:rfc:`4340#section-9.2`), over a pseudo-header that carries the whole packet's length, as TCP's does, so a fragment is diff --git a/docs/source/pcapkit/protocols/link/frad.rst b/docs/source/pcapkit/protocols/link/frad.rst index 5c28183e4e..4900e94398 100644 --- a/docs/source/pcapkit/protocols/link/frad.rst +++ b/docs/source/pcapkit/protocols/link/frad.rst @@ -6,8 +6,9 @@ FRAD - Frame Relay Access Device :mod:`pcapkit.protocols.link.frad` contains :class:`~pcapkit.protocols.link.frad.FRAD` only, which implements the extractor for Frame Relay's multiprotocol -encapsulation [*]_, as seen on a ``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` -capture whose ``arphrd_type`` is ``ARPHRD_FRAD``. Its structure, the Q.922 +encapsulation [*]_, as seen on a ``LINKTYPE_FRELAY`` capture, or on a +``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` capture whose ``arphrd_type`` is +``ARPHRD_FRAD``. Its structure, the Q.922 LAPF address onward with no trailing FCS, is described as below: .. table:: diff --git a/docs/source/pcapkit/protocols/link/gre.rst b/docs/source/pcapkit/protocols/link/gre.rst index 625e9a87da..7e587db8a0 100644 --- a/docs/source/pcapkit/protocols/link/gre.rst +++ b/docs/source/pcapkit/protocols/link/gre.rst @@ -7,11 +7,14 @@ GRE - Generic Routing Encapsulation :class:`~pcapkit.protocols.link.gre.GRE` only, which implements the extractor for the Generic Routing Encapsulation base header [*]_ plus the optional Key and Sequence Number extensions [*]_, as -seen on a ``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` capture whose -``arphrd_type`` is ``ARPHRD_IPGRE`` or ``ARPHRD_IP6GRE`` -- both land on this -one class, the "IP"/"IP6" distinction being only which outer IP version the -tunnel carries. Its structure, with every optional field present, is -described as below: +reached through IP protocol number 47 behind any layer sharing +:attr:`Internet.__proto__ `, +IPv4 and IPv6 among them, or as seen on a +``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` capture whose +``arphrd_type`` is ``ARPHRD_IPGRE`` or ``ARPHRD_IP6GRE`` -- ``ARPHRD_IPGRE`` +and ``ARPHRD_IP6GRE`` both land on this one class, the "IP"/"IP6" distinction +being only which outer IP version the tunnel carries. Its structure, with +every optional field present, is described as below: .. table:: @@ -47,6 +50,11 @@ its own. A nonzero Version Number (RFC 2637's "Enhanced GRE"/PPTP, version 1) is a different, incompatible protocol and is refused rather than misread; see the module docstring's *Scope* section. +Flow tracing and TCP reassembly follow the tunnel's inner flow, keyed by the +IP header nearest the TCP segment as for any tunnel (:issue:`1581`), and IPv4 +reassembly of an outer datagram fragmented in transit yields a parsed GRE +layer. + .. autoclass:: pcapkit.protocols.link.gre.GRE :no-members: :show-inheritance: diff --git a/examples/generators/dispatch_families/internet.py b/examples/generators/dispatch_families/internet.py index d55d7ade8f..6b5686861a 100644 --- a/examples/generators/dispatch_families/internet.py +++ b/examples/generators/dispatch_families/internet.py @@ -27,6 +27,7 @@ 4, # IPv4 6, # TCP 17, # UDP + 47, # GRE 50, # ESP 51, # AH 89, # OSPFIGP @@ -79,6 +80,9 @@ def _payload(code: 'int') -> 'bytes': if code == TransType.IPv6_Frag: from pcapkit.protocols.internet.ipv6_frag import IPv6_Frag return bytes(IPv6_Frag(next=17, id=1, offset=0, mf=False, payload=_udp(9999))) + if code == TransType.GRE: + from pcapkit.protocols.link.gre import GRE + return bytes(GRE(protocol_type=0x0800, payload=_ip4(6, _tcp(9999)))) if code == TransType.ESP: from pcapkit.protocols.internet.esp import ESP return bytes(ESP(spi=0x1234, seq=1, payload=b'\x01\x02\x03\x04')) @@ -164,6 +168,7 @@ def _build(code: 'int') -> 'Any': 'internet/IPv6_ICMP': ('pcapkit.protocols.internet.icmpv6', 'ICMPv6'), 'internet/IPv6_Route': ('pcapkit.protocols.internet.ipv6_route', 'IPv6_Route'), 'internet/IPv6_Frag': ('pcapkit.protocols.internet.ipv6_frag', 'IPv6_Frag'), + 'internet/GRE': ('pcapkit.protocols.link.gre', 'GRE'), 'internet/ESP': ('pcapkit.protocols.internet.esp', 'ESP'), 'internet/AH': ('pcapkit.protocols.internet.ah', 'AH'), 'internet/IGMP': ('pcapkit.protocols.internet.igmp', 'IGMP'), diff --git a/examples/generators/dispatch_families/linktype.py b/examples/generators/dispatch_families/linktype.py index d8e967a35e..6a55899495 100644 --- a/examples/generators/dispatch_families/linktype.py +++ b/examples/generators/dispatch_families/linktype.py @@ -59,6 +59,9 @@ def _payload(code: 'Any') -> 'tuple[bytes, bool]': return _wlan_ack(), False if code == LinkType.IEEE802_11_RADIOTAP: return _radiotap(_wlan_ack()), False + if code == LinkType.FRELAY: # direct NLPID 0xCC, IPv4 + from pcapkit.protocols.link.frad import FRAD + return bytes(FRAD(nlpid=0xCC, payload=_ip4(6, _tcp(9999)))), False raise LookupError(f'linktype: no payload builder for {code!r}') # pragma: no cover @@ -110,6 +113,7 @@ def _pcapng_build(code: 'Any') -> 'Any': 'pcap-frame/LINUX_SLL2': ('pcapkit.protocols.link', 'LinuxSLL2'), 'pcap-frame/IEEE802_11': ('pcapkit.protocols.link', 'IEEE802_11'), 'pcap-frame/IEEE802_11_RADIOTAP': ('pcapkit.protocols.link', 'Radiotap'), + 'pcap-frame/FRELAY': ('pcapkit.protocols.link', 'FRAD'), # -- PCAPNG.__proto__ (LinkType) -------------------------------------------- 'pcapng-frame/NULL': ('pcapkit.protocols.link', 'Loopback'), @@ -121,4 +125,5 @@ def _pcapng_build(code: 'Any') -> 'Any': 'pcapng-frame/LINUX_SLL2': ('pcapkit.protocols.link', 'LinuxSLL2'), 'pcapng-frame/IEEE802_11': ('pcapkit.protocols.link', 'IEEE802_11'), 'pcapng-frame/IEEE802_11_RADIOTAP': ('pcapkit.protocols.link', 'Radiotap'), + 'pcapng-frame/FRELAY': ('pcapkit.protocols.link', 'FRAD'), } diff --git a/pcapkit/protocols/internet/internet.py b/pcapkit/protocols/internet/internet.py index bff2517bff..f5ebc23f66 100644 --- a/pcapkit/protocols/internet/internet.py +++ b/pcapkit/protocols/internet/internet.py @@ -77,6 +77,8 @@ class Internet(ProtocolBase[_PT, _ST], Generic[_PT, _ST]): # pylint: disable=ab - :class:`pcapkit.protocols.internet.ipv6_route.IPv6_Route` * - :attr:`~pcapkit.const.reg.transtype.TransType.IPv6_Frag` - :class:`pcapkit.protocols.internet.ipv6_frag.IPv6_Frag` + * - :attr:`~pcapkit.const.reg.transtype.TransType.GRE` + - :class:`pcapkit.protocols.link.gre.GRE` * - :attr:`~pcapkit.const.reg.transtype.TransType.ESP` - :class:`pcapkit.protocols.internet.esp.ESP` * - :attr:`~pcapkit.const.reg.transtype.TransType.AH` @@ -134,6 +136,9 @@ class Internet(ProtocolBase[_PT, _ST], Generic[_PT, _ST]): # pylint: disable=ab Enum_TransType.IPv6_ICMP: ModuleDescriptor('pcapkit.protocols.internet.icmpv6', 'ICMPv6'), Enum_TransType.IPv6_Route: ModuleDescriptor('pcapkit.protocols.internet.ipv6_route', 'IPv6_Route'), Enum_TransType.IPv6_Frag: ModuleDescriptor('pcapkit.protocols.internet.ipv6_frag', 'IPv6_Frag'), + # NOTE: a tunnel is placed by its payload, so GRE lives under ``protocols.link``; + # see :doc:`/contributing/conventions/protocol-layer-placement`. + Enum_TransType.GRE: ModuleDescriptor('pcapkit.protocols.link.gre', 'GRE'), Enum_TransType.ESP: ModuleDescriptor('pcapkit.protocols.internet.esp', 'ESP'), Enum_TransType.AH: ModuleDescriptor('pcapkit.protocols.internet.ah', 'AH'), Enum_TransType.IGMP: ModuleDescriptor('pcapkit.protocols.internet.igmp', 'IGMP'), diff --git a/pcapkit/protocols/link/frad.py b/pcapkit/protocols/link/frad.py index 681b4d4b2b..5b13d8e30d 100644 --- a/pcapkit/protocols/link/frad.py +++ b/pcapkit/protocols/link/frad.py @@ -7,6 +7,7 @@ :mod:`pcapkit.protocols.link.frad` contains :class:`~pcapkit.protocols.link.frad.FRAD` only, which implements the extractor for Frame Relay's multiprotocol encapsulation [*]_, as seen on a +``LINKTYPE_FRELAY`` capture, or on a ``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` capture whose ``arphrd_type`` is ``ARPHRD_FRAD`` -- :class:`~pcapkit.protocols.link.linux_sll.LinuxSLL` dispatches here instead of falling back to diff --git a/pcapkit/protocols/link/gre.py b/pcapkit/protocols/link/gre.py index dccf27c283..13e236e081 100644 --- a/pcapkit/protocols/link/gre.py +++ b/pcapkit/protocols/link/gre.py @@ -7,9 +7,13 @@ :mod:`pcapkit.protocols.link.gre` contains :class:`~pcapkit.protocols.link.gre.GRE` only, which implements the extractor for the Generic Routing Encapsulation base header [:rfc:`2784`] plus the -optional Key and Sequence Number extensions [:rfc:`2890`], as seen on a +optional Key and Sequence Number extensions [:rfc:`2890`]. It is reached +through IP protocol number 47 behind any layer sharing +:attr:`Internet.__proto__ `, +IPv4 and IPv6 among them, and on a ``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` capture whose ``arphrd_type`` -is ``ARPHRD_IPGRE`` or ``ARPHRD_IP6GRE`` -- both land on this one class: +is ``ARPHRD_IPGRE`` or ``ARPHRD_IP6GRE`` -- ``ARPHRD_IPGRE`` and +``ARPHRD_IP6GRE`` both land on this one class: :class:`~pcapkit.protocols.link.linux_sll.LinuxSLL` dispatches here instead of falling back to :class:`~pcapkit.protocols.misc.raw.Raw` for either case; see :attr:`LinuxSLL.__proto__ `. The @@ -359,7 +363,9 @@ def __index__(cls) -> 'Enum_TransType': # pylint: disable=invalid-index-returne Returns: Numeral registry index of the protocol in `IANA`_ protocol - numbers. + numbers, which + :attr:`Internet.__proto__ ` + is keyed by. :attr:`LinuxSLL.__proto__ ` names its own keys for this class, :attr:`~pcapkit.const.linux.arphrd.ARPHRD.IPGRE` and diff --git a/pcapkit/protocols/misc/pcap/frame.py b/pcapkit/protocols/misc/pcap/frame.py index 189b745e46..b429994001 100644 --- a/pcapkit/protocols/misc/pcap/frame.py +++ b/pcapkit/protocols/misc/pcap/frame.py @@ -85,6 +85,8 @@ class Frame(ProtocolBase[Data_Frame, Schema_Frame], - :class:`pcapkit.protocols.link.ethernet.Ethernet` * - :attr:`pcapkit.const.reg.linktype.LinkType.IEEE802_11` - :class:`pcapkit.protocols.link.ieee802_11.IEEE802_11` + * - :attr:`pcapkit.const.reg.linktype.LinkType.FRELAY` + - :class:`pcapkit.protocols.link.frad.FRAD` * - :attr:`pcapkit.const.reg.linktype.LinkType.LOOP` - :class:`pcapkit.protocols.link.loopback.Loopback` * - :attr:`pcapkit.const.reg.linktype.LinkType.LINUX_SLL` @@ -119,6 +121,7 @@ class Frame(ProtocolBase[Data_Frame, Schema_Frame], Enum_LinkType.NULL: ModuleDescriptor('pcapkit.protocols.link', 'Loopback'), Enum_LinkType.ETHERNET: ModuleDescriptor('pcapkit.protocols.link', 'Ethernet'), Enum_LinkType.IEEE802_11: ModuleDescriptor('pcapkit.protocols.link', 'IEEE802_11'), + Enum_LinkType.FRELAY: ModuleDescriptor('pcapkit.protocols.link', 'FRAD'), Enum_LinkType.LOOP: ModuleDescriptor('pcapkit.protocols.link', 'Loopback'), Enum_LinkType.LINUX_SLL: ModuleDescriptor('pcapkit.protocols.link', 'LinuxSLL1'), Enum_LinkType.IEEE802_11_RADIOTAP: ModuleDescriptor('pcapkit.protocols.link', 'Radiotap'), diff --git a/pcapkit/protocols/misc/pcapng.py b/pcapkit/protocols/misc/pcapng.py index 7599176d3d..9ec4629ae1 100644 --- a/pcapkit/protocols/misc/pcapng.py +++ b/pcapkit/protocols/misc/pcapng.py @@ -482,6 +482,8 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG], - :class:`pcapkit.protocols.link.ethernet.Ethernet` * - :attr:`pcapkit.const.reg.linktype.LinkType.IEEE802_11` - :class:`pcapkit.protocols.link.ieee802_11.IEEE802_11` + * - :attr:`pcapkit.const.reg.linktype.LinkType.FRELAY` + - :class:`pcapkit.protocols.link.frad.FRAD` * - :attr:`pcapkit.const.reg.linktype.LinkType.LOOP` - :class:`pcapkit.protocols.link.loopback.Loopback` * - :attr:`pcapkit.const.reg.linktype.LinkType.LINUX_SLL` @@ -776,6 +778,7 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG], Enum_LinkType.NULL: ModuleDescriptor('pcapkit.protocols.link', 'Loopback'), Enum_LinkType.ETHERNET: ModuleDescriptor('pcapkit.protocols.link', 'Ethernet'), Enum_LinkType.IEEE802_11: ModuleDescriptor('pcapkit.protocols.link', 'IEEE802_11'), + Enum_LinkType.FRELAY: ModuleDescriptor('pcapkit.protocols.link', 'FRAD'), Enum_LinkType.LOOP: ModuleDescriptor('pcapkit.protocols.link', 'Loopback'), Enum_LinkType.LINUX_SLL: ModuleDescriptor('pcapkit.protocols.link', 'LinuxSLL1'), Enum_LinkType.IEEE802_11_RADIOTAP: ModuleDescriptor('pcapkit.protocols.link', 'Radiotap'), diff --git a/pcapkit/protocols/schema/link/frad.py b/pcapkit/protocols/schema/link/frad.py index b70b033eef..9c798a18dc 100644 --- a/pcapkit/protocols/schema/link/frad.py +++ b/pcapkit/protocols/schema/link/frad.py @@ -72,9 +72,10 @@ class FRAD(Schema): """Header schema for a Frame Relay Access Device (FRAD) frame. The frame is Frame Relay's multiprotocol encapsulation [:rfc:`2427`, - obsoleting :rfc:`1490`] as presented to a ``LINKTYPE_LINUX_SLL``/ - ``LINKTYPE_LINUX_SLL2`` capture whose ``arphrd_type`` is ``ARPHRD_FRAD``: - the Q.922 LAPF address onward, with no trailing FCS. + obsoleting :rfc:`1490`] as presented to a ``LINKTYPE_FRELAY`` capture, + or to a ``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` capture whose + ``arphrd_type`` is ``ARPHRD_FRAD``: the Q.922 LAPF address onward, with no + trailing FCS. """ diff --git a/pcapkit/protocols/schema/link/gre.py b/pcapkit/protocols/schema/link/gre.py index 305a7e7579..eb3cd17dd3 100644 --- a/pcapkit/protocols/schema/link/gre.py +++ b/pcapkit/protocols/schema/link/gre.py @@ -43,9 +43,9 @@ class GRE(Schema): """Header schema for a Generic Routing Encapsulation (GRE) frame. The base header [:rfc:`2784`] plus the optional Key and Sequence Number - extensions [:rfc:`2890`], as presented to a ``LINKTYPE_LINUX_SLL``/ - ``LINKTYPE_LINUX_SLL2`` capture whose ``arphrd_type`` is ``ARPHRD_IPGRE`` - or ``ARPHRD_IP6GRE``. + extensions [:rfc:`2890`], as carried under IP protocol number 47, or as + presented to a ``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` capture + whose ``arphrd_type`` is ``ARPHRD_IPGRE`` or ``ARPHRD_IP6GRE``. """ diff --git a/tests/protocols/link/test_frad_gre_binding_2649_unit.py b/tests/protocols/link/test_frad_gre_binding_2649_unit.py new file mode 100644 index 0000000000..b5f2ff708e --- /dev/null +++ b/tests/protocols/link/test_frad_gre_binding_2649_unit.py @@ -0,0 +1,301 @@ +# -*- coding: utf-8 -*- +"""GitHub issue #2649: link type 107 reaches FRAD, and IP protocol 47 reaches GRE. + +:class:`~pcapkit.protocols.misc.pcap.frame.Frame` and +:class:`~pcapkit.protocols.misc.pcapng.PCAPNG` bind ``LinkType.FRELAY`` (107) to +:class:`~pcapkit.protocols.link.frad.FRAD`, and +:class:`~pcapkit.protocols.internet.internet.Internet` binds ``TransType.GRE`` (47) +to :class:`~pcapkit.protocols.link.gre.GRE`, so IPv4 and IPv6 dispatch it. The +captures and datagrams here are built octet by octet, from :rfc:`2427` and +:rfc:`2784`/:rfc:`2890`; each parses through the dissector, every frame and layer +rebuilds byte-exactly, GRE's checksum (#2618) is verified behind IPv4 and IPv6, and +flow tracing and reassembly follow the tunnel's inner flow. + +Each test imports :mod:`pcapkit` itself, after +:func:`~tests._support.reimport_once_per_class`. + +""" + +import os +import struct +import tempfile +import unittest +import warnings +from unittest import mock + +from tests._support import reimport_once_per_class +from tests.foundation import _roundtrip as wire + +#: Test tier (#1958): hand-picked parse -> rebuild round trips. +__tier__ = 'ALL' + +#: UDP 12345 to 9 (discard) carrying ``abcd``, its checksum zero (absent over IPv4). +UDP = struct.pack('>HHHH', 12345, 9, 12, 0) + b'abcd' + + +#: The tunnel's endpoints, and those of the datagram it carries. +OUTER, TUNNELLED = ((192, 0, 2, 1), (198, 51, 100, 1)), ((10, 0, 0, 1), (10, 0, 0, 2)) + + +def _ipv4(proto: int, payload: bytes, *, mf: bool = False, offset: int = 0, ident: int = 1, + ends: 'tuple[tuple[int, ...], tuple[int, ...]]' = OUTER) -> bytes: + """An option-less IPv4 header (RFC 791) with a right header checksum.""" + head = struct.pack('>BBHHHBBH4s4s', 0x45, 0, 20 + len(payload), ident, (0x2000 if mf else 0) | offset, + 64, proto, 0, bytes(ends[0]), bytes(ends[1])) + return head[:10] + struct.pack('>H', wire.checksum(head)) + head[12:] + payload + + +def _tcp(seq: int, flags: int, data: bytes = b'') -> bytes: + """A TCP segment from port 40000 to 80, its checksum left zero.""" + return struct.pack('>HHIIBBHHH', 40000, 80, seq, 0, 0x50, flags, 8192, 0, 0) + data + + +def _ipv6(nxt: int, payload: bytes) -> bytes: + """A fixed IPv6 header (RFC 8200) carrying ``payload``.""" + return (struct.pack('>IHBB', 0x6000_0000, len(payload), nxt, 64) + + bytes.fromhex('20010db8000000000000000000000001') + + bytes.fromhex('20010db8000000000000000000000002') + payload) + + +#: The datagram the tunnels and Frame Relay frames carry: IPv4 over UDP. +INNER = _ipv4(17, UDP, ident=20, ends=TUNNELLED) + + +def _gre(payload: bytes, *, checksum: 'int | bool' = False, key: 'int | None' = None, + seq: 'int | None' = None, version: int = 0) -> bytes: + """A GRE header carrying IPv4; ``checksum`` is :data:`True` for the right one.""" + flags = ((0x8000 if checksum is not False else 0) | (0x2000 if key is not None else 0) + | (0x1000 if seq is not None else 0) | version) + head = struct.pack('>HH', flags, 0x0800) + extra = b''.join(struct.pack('>I', value) for value in (key, seq) if value is not None) + if checksum is False: + return head + extra + payload + value = wire.checksum(head + bytes(4) + extra + payload) if checksum is True else checksum + return head + struct.pack('>HH', value, 0) + extra + payload + + +#: A Q.922 address for DLCI 16, EA set on its second octet, then UI (0x03). +Q922 = bytes.fromhex('0401') + b'\x03' + +#: LinkType 107 records: direct NLPID IPv4 and IPv6, SNAP with an EtherType, Q.933. +FRELAY = ( + Q922 + b'\xcc' + INNER, + Q922 + b'\x8e' + _ipv6(17, UDP), + Q922 + b'\x00\x80' + bytes(3) + struct.pack('>H', 0x0800) + INNER, + Q922 + b'\x08' + b'\x00\x01\x02\x03', +) + + +def _ether(ethertype: int, payload: bytes) -> bytes: + return bytes.fromhex('020000000002' '020000000001') + struct.pack('>H', ethertype) + payload + + +def _pcap(linktype: int, records: 'tuple[bytes, ...]') -> bytes: + """A little-endian PCAP v2.4 file of ``records`` on ``linktype``.""" + data = struct.pack(' bytes: + """A little-endian PCAP-NG file: one section, one interface on ``linktype``.""" + out = struct.pack(' None: + reimport_once_per_class(self) + + def _extract(self, data: bytes, suffix: str) -> 'list': # type: ignore[type-arg] + import pcapkit + + with tempfile.TemporaryDirectory() as tmp: + path = os.path.join(tmp, f'probe{suffix}') + with open(path, 'wb') as file: + file.write(data) + with warnings.catch_warnings(): + warnings.simplefilter('ignore') + extractor = pcapkit.extract(fin=path, nofile=True, store=True) + return list(extractor.frame) + + def _assert_rebuilds(self, layer, **kwargs) -> None: # type: ignore[no-untyped-def] + """``layer`` and each layer under it rebuild byte-exactly from their info.""" + while type(layer).__name__ not in ('Raw', 'NoPayload'): + for data in (layer.info, layer.info.to_dict()): + with self.subTest(layer=type(layer).__name__, data=type(data).__name__): + self.assertEqual(type(layer).from_data(data, **kwargs).data.hex(), layer.data.hex()) + layer, kwargs = layer.payload, {} + + def _parse(self, cls: 'type', octets: bytes) -> 'tuple[object, list[tuple[type, str]]]': + """``octets`` parsed as ``cls`` with checksums verified, and the ProtocolWarnings.""" + from pcapkit.utilities import config + from pcapkit.utilities.warnings import ProtocolWarning + + with mock.patch.object(config, 'CHECKSUM_VERIFY', True), \ + warnings.catch_warnings(record=True) as caught: + warnings.simplefilter('always') + layer = cls(octets) + return layer, [(item.category, str(item.message)) + for item in caught if issubclass(item.category, ProtocolWarning)] + + def test_registered(self) -> None: + from pcapkit.const.reg.linktype import LinkType + from pcapkit.const.reg.transtype import TransType + from pcapkit.corekit.module import ModuleDescriptor + from pcapkit.protocols.internet.internet import Internet + from pcapkit.protocols.internet.ipv4 import IPv4 + from pcapkit.protocols.internet.ipv6 import IPv6 + from pcapkit.protocols.link.frad import FRAD + from pcapkit.protocols.link.gre import GRE + from pcapkit.protocols.misc.pcap.frame import Frame + from pcapkit.protocols.misc.pcapng import PCAPNG + + for cls in (Frame, PCAPNG): + with self.subTest(table=cls.__name__): + self.assertEqual(cls.__proto__[LinkType.FRELAY], ModuleDescriptor('pcapkit.protocols.link', 'FRAD')) + self.assertIs(cls._lookup_next_layer(cls.__proto__, FRAD.__index__()), FRAD) + self.assertEqual(Internet.__proto__[TransType.GRE], ModuleDescriptor('pcapkit.protocols.link.gre', 'GRE')) + for cls in (IPv4, IPv6): + with self.subTest(table=cls.__name__): + self.assertIs(cls.__proto__, Internet.__proto__) + self.assertIs(cls._lookup_next_layer(cls.__proto__, GRE.__index__()), GRE) + self.assertEqual((int(LinkType.FRELAY), int(TransType.GRE)), (107, 47)) + + def test_frelay_capture(self) -> None: + """Link type 107 carries the Q.922 address onward, with no FCS.""" + from pcapkit.const.reg.linktype import LinkType + + chains = ['FRAD:IPv4:UDP:Raw', 'FRAD:IPv6:UDP:Raw', 'FRAD:IPv4:UDP:Raw', 'FRAD:Raw'] + for pcapng, (data, suffix) in enumerate(((_pcap(LinkType.FRELAY, FRELAY), '.pcap'), + (_pcapng(LinkType.FRELAY, FRELAY), '.pcapng'))): + with self.subTest(format=suffix): + frames = self._extract(data, suffix) + self.assertEqual([frame.protochain.chain for frame in frames], chains) + for frame, record in zip(frames, FRELAY): + self.assertEqual(bytes(frame.payload.data), record) + if pcapng: + self._assert_rebuilds(frame, num=frame._fnum, sct=frame._sect, ctx=frame._ctx) + else: + self._assert_rebuilds(frame, num=frame._fnum, header=frame._ghdr) + + infos = [frame.payload.info for frame in frames] + self.assertEqual([(info.dlci, info.control, info.nlpid) for info in infos], + [(16, 0x03, 0xCC), (16, 0x03, 0x8E), (16, 0x03, 0x80), (16, 0x03, 0x08)]) + self.assertEqual((infos[2].snap_oui, infos[2].snap_pid), (bytes(3), 0x0800)) + self.assertEqual(bytes(frames[3].payload.payload.data), b'\x00\x01\x02\x03') + + def test_gre_over_ip(self) -> None: + """IPv4 and IPv6 hand protocol 47 to GRE, which hands its EtherType on.""" + from pcapkit.protocols.internet.ipv4 import IPv4 + from pcapkit.protocols.internet.ipv6 import IPv6 + + cases = [ + (IPv4, _ipv4(47, _gre(INNER)), 4, None, None), + (IPv4, _ipv4(47, _gre(INNER, checksum=True, key=0x11223344, seq=7)), 16, 0x11223344, 7), + (IPv6, _ipv6(47, _gre(INNER, checksum=True)), 8, None, None), + ] + for cls, octets, length, key, seq in cases: + with self.subTest(carrier=cls.__name__, length=length): + layer, messages = self._parse(cls, octets) + self.assertEqual(messages, []) + self.assertEqual(layer.protochain.chain, f'{cls.__name__}:GRE:IPv4:UDP:Raw') + info = layer.payload.info + self.assertEqual((info.len, info.key, info.sequence_number), (length, key, seq)) + self.assertEqual(int(info.protocol_type), 0x0800) + self.assertEqual(bytes(layer.payload.payload.data), INNER) + self._assert_rebuilds(layer) + + data = _pcap(1, (_ether(0x0800, _ipv4(47, _gre(INNER))),)) + self.assertEqual([frame.protochain.chain for frame in self._extract(data, '.pcap')], + ['Ethernet:IPv4:GRE:IPv4:UDP:Raw']) + + def test_gre_checksum_over_ip(self) -> None: + """The RFC 2784 checksum is verified behind IPv4 and IPv6, and not in a fragment.""" + from pcapkit.corekit.checksum.internet import ChecksumStatus + from pcapkit.protocols.internet.ipv4 import IPv4 + from pcapkit.protocols.internet.ipv6 import IPv6 + from pcapkit.utilities.warnings import ChecksumWarning + + good = _gre(INNER, checksum=True) + value = int.from_bytes(good[4:6], 'big') + bad = _gre(INNER, checksum=value ^ 0x0101) + warning = (ChecksumWarning, f'GRE: checksum {value ^ 0x0101:#06x} is wrong; {value:#06x} expected') + cases = { + 'valid': (IPv4, _ipv4(47, good), ChecksumStatus.VALID, []), + 'valid over IPv6': (IPv6, _ipv6(47, good), ChecksumStatus.VALID, []), + 'invalid': (IPv4, _ipv4(47, bad), ChecksumStatus.INVALID, [warning]), + 'C clear': (IPv4, _ipv4(47, _gre(INNER)), ChecksumStatus.NOT_COMPUTED, []), + 'fragment': (IPv4, _ipv4(47, bad, mf=True), ChecksumStatus.NO_PSEUDO_HEADER, []), + # The IP header states the payload length, which the cooked header cannot. + 'cut short': (IPv4, _ipv4(47, good)[:-6], ChecksumStatus.TRUNCATED, []), + 'cut short over IPv6': (IPv6, _ipv6(47, good)[:-6], ChecksumStatus.TRUNCATED, []), + } + self.assertEqual(wire.checksum(good), 0) + for name, (cls, octets, status, expected) in cases.items(): + with self.subTest(name): + layer, messages = self._parse(cls, octets) + self.assertEqual(type(layer.payload).__name__, 'GRE') + self.assertEqual((layer.payload.info.checksum_status, messages), (status, expected)) + self.assertEqual(cls.from_data(layer.info).data, octets) + + def test_a_refused_gre_header_is_kept_raw(self) -> None: + """Version 1 is refused, and IPv4 keeps it as Raw, as LinuxSLL does (#2588).""" + from pcapkit.protocols.internet.ipv4 import IPv4 + from pcapkit.protocols.misc.raw import Raw + + octets = _ipv4(47, _gre(INNER, version=1)) + layer, messages = self._parse(IPv4, octets) + self.assertEqual(messages, []) + self.assertIsInstance(layer.payload, Raw) + self.assertEqual(layer.payload.info.error, 'GRE: invalid version: 1') + self.assertEqual(IPv4.from_data(layer.info).data, octets) + + def test_analysis_follows_the_inner_flow(self) -> None: + """TCP through the tunnel is traced and reassembled under the tunnelled + datagram's addresses (#1581), and a fragmented outer datagram + reassembles to a parsed GRE layer. + """ + import ipaddress + + import pcapkit + + segments = (_tcp(1000, 0x02), _tcp(1001, 0x18, b'hello '), _tcp(1007, 0x18, b'world'), _tcp(1012, 0x11)) + records = [_ether(0x0800, _ipv4(47, _gre(_ipv4(6, segment, ident=10 + index, ends=TUNNELLED)), + ident=100 + index)) + for index, segment in enumerate(segments)] + tunnelled = _gre(INNER) + records += [_ether(0x0800, _ipv4(47, tunnelled[:16], mf=True, ident=200)), + _ether(0x0800, _ipv4(47, tunnelled[16:], offset=2, ident=200))] + + with tempfile.TemporaryDirectory() as tmp: + path = os.path.join(tmp, 'tunnel.pcap') + with open(path, 'wb') as file: + file.write(_pcap(1, tuple(records))) + with warnings.catch_warnings(): + warnings.simplefilter('ignore') + with pcapkit.extract(fin=path, nofile=True, store=True, reassembly=True, ipv4=True, tcp=True, + trace=True, trace_fout=os.path.join(tmp, 'trace')) as extraction: + flows, reassembly = extraction.trace.tcp, extraction.reassembly + + self.assertEqual([(flow.index, flow.label.split('-')[:2]) for flow in flows], + [((1, 2, 3, 4), ['10.0.0.1_40000', '10.0.0.2_80'])]) + inner = (ipaddress.ip_address('10.0.0.1'), 40000), (ipaddress.ip_address('10.0.0.2'), 80) + self.assertEqual([((datagram.id.src, datagram.id.dst), bytes(datagram.payload), bool(datagram.completed)) + for datagram in reassembly.tcp], [(inner, b'hello world', True)]) + fragmented = [datagram for datagram in reassembly.ipv4 if datagram.id.id == 200] + self.assertEqual([(bool(datagram.completed), datagram.packet.protochain.chain) for datagram in fragmented], + [(True, 'GRE:IPv4:UDP:Raw')]) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/protocols/link/test_gre_checksum_2618_unit.py b/tests/protocols/link/test_gre_checksum_2618_unit.py index 4241232e5f..216957ff6b 100644 --- a/tests/protocols/link/test_gre_checksum_2618_unit.py +++ b/tests/protocols/link/test_gre_checksum_2618_unit.py @@ -126,8 +126,7 @@ def test_c_clear_and_off(self) -> None: self.assertIs(self.status(bad)[0], self.Status.INVALID) def test_a_fragment_is_not_verified(self) -> None: - # Nothing binds GRE under IP, but a layer an IP fragment carries is not - # verified, whatever it is. + # A layer an IP fragment carries is not verified, whatever it is. from pcapkit.corekit.checksum.internet import fragment_payload with fragment_payload(True): diff --git a/tests/protocols/test_dispatch_reachability_unit.py b/tests/protocols/test_dispatch_reachability_unit.py index 69519daef2..ff2e82f90b 100644 --- a/tests/protocols/test_dispatch_reachability_unit.py +++ b/tests/protocols/test_dispatch_reachability_unit.py @@ -49,14 +49,7 @@ #: Claims nothing reaches, as ``(protocol, destination, found)``: why. Binding #: one changes parsed output, and deletes its entry in the same change (#2649). -UNBOUND = { - ('pcapkit.protocols.link.frad.FRAD', 'Frame', None): - 'LINKTYPE_FRELAY (107) is the Q.922 frame FRAD reads; Frame.__proto__ binds no 107', - ('pcapkit.protocols.link.frad.FRAD', 'PCAPNG', None): - 'LINKTYPE_FRELAY (107) is the Q.922 frame FRAD reads; PCAPNG.__proto__ binds no 107', - ('pcapkit.protocols.link.gre.GRE', 'Internet', None): - 'IP protocol 47 is GRE; Internet.__proto__ binds no 47', -} # type: dict[tuple[str, str, Any], str] +UNBOUND = {} # type: dict[tuple[str, str, Any], str] class Gap(NamedTuple): diff --git a/tests/protocols/test_protocol_code_registration_unit.py b/tests/protocols/test_protocol_code_registration_unit.py index 7d5db1cd7f..03db1db1e8 100644 --- a/tests/protocols/test_protocol_code_registration_unit.py +++ b/tests/protocols/test_protocol_code_registration_unit.py @@ -365,12 +365,14 @@ def test_end_to_end_class_statement_registers_the_real_table(self) -> None: from pcapkit.const.reg.transtype import TransType from pcapkit.protocols.internet.internet import Internet + # RFC 3692 reserves 254 for experimentation, so nothing ships bound there. + code = TransType.Use_for_experimentation_and_testing_254 with mock.patch.dict(Internet.__proto__, {}, clear=False): - class MyGre(Internet, code=TransType.GRE): + class Experimental(Internet, code=code): __layer__ = 'Internet' - self.assertIs(Internet.__proto__[TransType.GRE], MyGre) - self.assertNotIn(TransType.GRE, Internet.__proto__) + self.assertIs(Internet.__proto__[code], Experimental) + self.assertNotIn(code, Internet.__proto__) def test_class_keyword_with_an_arphrd_member_reaches_linux_sll_dispatch(self) -> None: """``code=ARPHRD.X`` registers where a cooked frame dispatches (#2533).""" @@ -404,19 +406,21 @@ def test_subclass_without_code_does_not_inherit_parent_registration(self) -> Non from pcapkit.const.reg.transtype import TransType from pcapkit.protocols.internet.internet import Internet + # RFC 3692 reserves 254 for experimentation, so nothing ships bound there. + code = TransType.Use_for_experimentation_and_testing_254 with mock.patch.dict(Internet.__proto__, {}, clear=False): - class Parent(Internet, code=TransType.GRE): + class Parent(Internet, code=code): __layer__ = 'Internet' - self.assertIs(Internet.__proto__[TransType.GRE], Parent) + self.assertIs(Internet.__proto__[code], Parent) class Child(Parent): __layer__ = 'Internet' # ``Child`` passed no ``code=``, so the entry must still be ``Parent``. - self.assertIs(Internet.__proto__[TransType.GRE], Parent) + self.assertIs(Internet.__proto__[code], Parent) self.assertNotIn(Child, Internet.__proto__.values()) - self.assertNotIn(TransType.GRE, Internet.__proto__) + self.assertNotIn(code, Internet.__proto__) def test_backward_compatible_dispatch_tables_are_unaffected(self) -> None: """No built-in protocol class passes ``code=``, so nothing shipped moves.