diff --git a/pcapkit/protocols/link/frad.py b/pcapkit/protocols/link/frad.py index 5b13d8e30d..a1b84fb6c0 100644 --- a/pcapkit/protocols/link/frad.py +++ b/pcapkit/protocols/link/frad.py @@ -69,6 +69,12 @@ class FRAD(Link[Data_FRAD, Schema_FRAD], whose OUI names a bridged medium rather than an EtherType) is kept as :class:`~pcapkit.protocols.misc.raw.Raw`, exactly as every ``arphrd_type`` this module's docstring lists already was before this class existed. + A frame whose Q.922 address is not the 2-octet form is refused: + :meth:`read` raises :exc:`~pcapkit.utilities.exceptions.ProtocolError`. + It becomes :class:`~pcapkit.protocols.misc.raw.Raw` only behind a caller + that catches the error, such as + :class:`~pcapkit.protocols.link.linux_sll.LinuxSLL` or a + ``LINKTYPE_FRELAY`` capture. """ @@ -148,12 +154,24 @@ def read(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_FRAD': Returns: Parsed packet data. + Raises: + ProtocolError: If the address is not the 2-octet Q.922 form, the + only one the schema reads (:rfc:`2427#section-3`): an EA bit + other than ``0`` then ``1``. An EA bit the capture cut off is + not checked. + """ if length is None: length = len(self) schema = self.__header__ addr = schema.addr + # NOTE: The data model keeps no EA bits, so another address form would + # rebuild as the 2-octet one (#2710). + cut = schema.__dict__.get('__short_read__') + if addr['ea1'] or not (addr['ea2'] or (cut is not None and cut[0] == 'addr')): + raise ProtocolError(f'{self.alias}: not a 2-octet Q.922 address: ' + f'EA bits {addr["ea1"]} and {addr["ea2"]}') _dlci = (addr['dlci_hi'] << 4) | addr['dlci_lo'] _raw_nlpid = schema.nlpid @@ -232,15 +250,19 @@ def make(self, ``0x80``. Note: - ``nlpid`` is not refused for being ``0`` -- the SNAP pad marker, - never a value of its own on the wire -- even though no caller + ``nlpid`` is not refused for being ``0`` -- the value of the one + pad octet :rfc:`2427#section-3` allows, if present, ahead of any + NLPID, never an NLPID of its own -- even though no caller building a frame from scratch should pass it: :meth:`from_data ` replays a capture that ended inside the header through this same method, and a capture cut short of the ``nlpid`` octet reads as ``0`` (zero rather than missing). Rejecting it here would make a short capture fail to rebuild, the one invariant every protocol in - this package keeps (:issue:`1458`). + this package keeps (:issue:`1458`). It is written as the pad and + an NLPID of ``0``, the octets that read back as it, and the + schema's own short read cuts them back to those captured + (:issue:`2710`). """ dlci = self._make_uint(dlci, bits=10, name='DLCI') @@ -263,6 +285,10 @@ def make(self, f'when nlpid is 0x80, not {nlpid!r}') _schema_nlpid, _ext_nlpid = nlpid, None _oui, _pid = None, None + if not nlpid: + # NOTE: A zero NLPID is the pad, which the schema follows with + # ``ext_nlpid``, so that is written too (#2710). + _ext_nlpid = 0 return Schema_FRAD( addr={ diff --git a/tests/protocols/link/test_frad_cut_rebuild_2710_unit.py b/tests/protocols/link/test_frad_cut_rebuild_2710_unit.py new file mode 100644 index 0000000000..2191143920 --- /dev/null +++ b/tests/protocols/link/test_frad_cut_rebuild_2710_unit.py @@ -0,0 +1,190 @@ +# -*- coding: utf-8 -*- +"""A FRAD header rebuilds as captured and quietly at every cut, or is refused. + +GitHub issue #2710: a :class:`~pcapkit.protocols.link.frad.FRAD` header the data ends +before its NLPID reads that octet as the ``0x00`` pad, so its data model holds an NLPID +of zero. :meth:`FRAD.make ` then left out the +``ext_nlpid`` the schema reads after the pad, and the rebuild logged ``NoDefaultValue`` +at ``CRITICAL``. It writes the pad and an NLPID of zero instead, which the schema's own +short read cuts back. + +The data model keeps no EA bits of the Q.922 address, so a header whose EA bits are not +the 2-octet form, ``0`` then ``1``, rebuilt other octets, cut or whole. +:meth:`FRAD.read ` refuses it, which a +:class:`~pcapkit.protocols.link.linux_sll.LinuxSLL` frame keeps as +:class:`~pcapkit.protocols.misc.raw.Raw`, quietly. An EA bit the data never held is not +checked. + +The frames are built here; this module is unit-tier and reads no capture file. + +""" +from __future__ import annotations + +import contextlib +import logging +import struct +import unittest +import warnings +from typing import TYPE_CHECKING + +from tests._support import reimport_once_per_class + +if TYPE_CHECKING: + from typing import Any, Callable, Iterator + +#: Test tier (#1958): hand-picked parse -> rebuild round trips. +__tier__ = 'ALL' + +#: An IPv4 header (protocol UDP) and an 8-octet UDP header. +IPV4 = (bytes.fromhex('4500001c00010000401100000a0000010a000002') + + bytes.fromhex('3039003500080000')) +#: A minimal ARP request (RFC 826), 28 octets. +ARP = bytes.fromhex('00010800060400010011223344550a0000010000000000000a000002') + +#: Each frame cut at every octet: the RFC 2427 address of DLCI 50, UI control, then a +#: direct NLPID, a SNAP header, or the pad and an NLPID of zero. +FRAMES = { + 'direct': bytes.fromhex('0c21' '03' 'cc') + IPV4, + 'SNAP': bytes.fromhex('0c21' '03' '00' '80' '000000' '0806') + ARP, + 'pad, zero NLPID': bytes.fromhex('0c21' '03' '00' '00') + b'\xaa\xbb', +} + +#: Addresses of DLCI 50 whose EA bits are not ``0`` then ``1``. +OTHER_FORMS = { + 'EA 1 then 1': bytes.fromhex('0d21'), + 'EA 0 then 0': bytes.fromhex('0c20'), + 'EA 1 then 0': bytes.fromhex('0d20'), +} + +#: A Linux cooked-capture source address, padded to its 8 octets. +LINK_ADDR = bytes.fromhex('001122334455') + bytes(2) + + +class _Logged(logging.Handler): + """Collect what the ``pcapkit`` logger reports.""" + + def __init__(self) -> None: + super().__init__(logging.DEBUG) + self.messages = [] # type: list[str] + + def emit(self, record: 'logging.LogRecord') -> None: + self.messages.append(f'logged: {record.getMessage()}') + + +@contextlib.contextmanager +def _reported() -> 'Iterator[list[str]]': + """Collect what the block reports, on the :mod:`warnings` channel and the logger.""" + handler = _Logged() + logger = logging.getLogger('pcapkit') + logger.addHandler(handler) + try: + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter('always') + yield handler.messages + finally: + logger.removeHandler(handler) + handler.messages.extend(f'warned: {item.message}' for item in caught) + + +class FRADCutRebuildTests(unittest.TestCase): + """A FRAD header rebuilds as captured, or the address form is refused.""" + + def setUp(self) -> None: + reimport_once_per_class(self) + from pcapkit.const.linux.arphrd import ARPHRD + from pcapkit.protocols.link.frad import FRAD + from pcapkit.protocols.link.linux_sll1 import LinuxSLL1 + from pcapkit.protocols.link.linux_sll2 import LinuxSLL2 + from pcapkit.utilities.exceptions import ProtocolError + + self.FRAD = FRAD + self.ProtocolError = ProtocolError + self.cooked = { + 'LinuxSLL1': (LinuxSLL1, struct.pack('>HHH', 0, ARPHRD.FRAD, 6) + LINK_ADDR + + struct.pack('>H', 0)), + 'LinuxSLL2': (LinuxSLL2, struct.pack('>HHIHBB', 0, 0, 1, ARPHRD.FRAD, 0, 6) + LINK_ADDR), + } # type: dict[str, tuple[Any, bytes]] + + def parse(self, build: 'Callable[[], Any]') -> 'tuple[Any, list[str]]': + """What ``build`` returns, and what it reported.""" + with _reported() as messages: + layer = build() + return layer, messages + + def assertRebuildsQuietly(self, layer: 'Any') -> 'None': # pylint: disable=invalid-name + """``layer`` rebuilt from its data model and its dict: its octets, and nothing reported.""" + for path, data in (('model', layer.info), ('dict', layer.info.to_dict())): + with self.subTest(path=path): + rebuilt, messages = self.parse(lambda: type(layer).from_data(data)) # pylint: disable=cell-var-from-loop + self.assertEqual((rebuilt.data.hex(), messages), (layer.data.hex(), [])) + + def test_every_cut_rebuilds_as_captured(self) -> None: + for label, frame in FRAMES.items(): + for count in range(1, len(frame) + 1): + with self.subTest(frame=label, captured=count): + with warnings.catch_warnings(): + warnings.simplefilter('ignore') + layer = self.FRAD(frame[:count], count) + self.assertEqual(layer.data, frame[:count]) + self.assertRebuildsQuietly(layer) + + def test_a_cut_before_the_nlpid_reads_the_pad(self) -> None: + for count in (1, 2, 3): + with self.subTest(captured=count): + with warnings.catch_warnings(): + warnings.simplefilter('ignore') + layer = self.FRAD(FRAMES['direct'][:count], count) + self.assertIsNotNone(layer.info.get('__short_read__')) + self.assertEqual((layer.info.nlpid, layer.info.len), (0, 5)) + + def test_make_writes_the_pad_and_a_zero_nlpid(self) -> None: + made, messages = self.parse(lambda: self.FRAD(dlci=50, nlpid=0)) + self.assertEqual((made.data.hex(), messages), ('0c21030000', [])) + + def test_another_address_form_is_refused(self) -> None: + from pcapkit.utilities.exceptions import CaughtByCaller + + for label, addr in OTHER_FORMS.items(): + frame = addr + FRAMES['direct'][2:] + for count in range(2, len(frame) + 1): + with self.subTest(address=label, captured=count), CaughtByCaller(self.ProtocolError), \ + self.assertRaisesRegex(self.ProtocolError, r'^FRAD: not a 2-octet Q\.922 address: EA bits'): + self.FRAD(frame[:count], count) + + def test_an_ea_bit_cut_off_is_not_checked(self) -> None: + # One octet holds the first EA bit alone: 0 reads, 1 is refused. + from pcapkit.utilities.exceptions import CaughtByCaller + + with warnings.catch_warnings(): + warnings.simplefilter('ignore') + layer = self.FRAD(b'\x0c', 1) + self.assertEqual(layer.info.get('__short_read__'), ('addr', 1)) + self.assertRebuildsQuietly(layer) + with CaughtByCaller(self.ProtocolError), self.assertRaises(self.ProtocolError): + self.FRAD(b'\x0d', 1) + + def test_linux_sll_keeps_another_address_form_raw(self) -> None: + for name, (cls, head) in self.cooked.items(): + for label, addr in OTHER_FORMS.items(): + raw = head + addr + FRAMES['direct'][2:] + with self.subTest(cooked=name, address=label): + frame, messages = self.parse(lambda: cls(raw, len(raw))) # pylint: disable=cell-var-from-loop + self.assertEqual(messages, []) + self.assertEqual(type(frame.payload).__name__, 'Raw') + self.assertRegex(frame.payload.info.error, r'^FRAD: not a 2-octet Q\.922 address: ') + self.assertEqual(frame.data, raw) + self.assertRebuildsQuietly(frame) + + def test_linux_sll_dispatches_the_2_octet_form(self) -> None: + # The control: the RFC 2427 address is still FRAD behind LinuxSLL. + for name, (cls, head) in self.cooked.items(): + raw = head + FRAMES['direct'] + with self.subTest(cooked=name): + frame, messages = self.parse(lambda: cls(raw, len(raw))) # pylint: disable=cell-var-from-loop + self.assertEqual(messages, []) + self.assertIsInstance(frame.payload, self.FRAD) + self.assertRebuildsQuietly(frame) + + +if __name__ == '__main__': + unittest.main()