Skip to content

Commit 982b542

Browse files
authored
fix(link): keep a captured FRAD pad octet through a whole-frame rebuild (#2716) (#2721)
RFC 2427 section 3 allows the one zero pad octet ahead of any NLPID, and FRAD reads one wherever it is, but the data model did not record it, so make() wrote the pad ahead of a SNAP header alone. A pad ahead of a direct NLPID (0c21 03 00 cc) was lost on a rebuild, and one was invented ahead of a SNAP header captured without it (0c21 03 80 ...). - The FRAD data model records pad, and _make_data passes it on. - make() takes pad. When it is None, the pad goes ahead of a SNAP header alone, as RFC 2427 section 4.1 writes it, and ahead of an NLPID of 0, which reads as the pad, so a direct build is unchanged. pad=False with an NLPID of 0 raises ProtocolError. - The FRAD prose stops calling the pad SNAP's alone. test_frad_pad_rebuild_2716_unit fails without the pcapkit/ change, but for the control that a direct build is unchanged. Shipped captures parse identically. The link, internet, project and root protocols modules, both schema round trips, and the #2710 and short-read sweeps pass. Closes #2716
1 parent 0c07940 commit 982b542

5 files changed

Lines changed: 226 additions & 27 deletions

File tree

‎docs/source/pcapkit/protocols/link/frad.rst‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,12 @@ LAPF address onward with no trailing FCS, is described as below:
1818
====== ==== ================= ==========================================
1919
0 0 ``frad.addr`` Q.922 Address (2-octet form)
2020
2 16 ``frad.control`` Control (``0x03``, UI, for data traffic)
21-
3 24 ``frad.nlpid`` NLPID, or the ``0x00`` pad ahead of a SNAP
22-
header
21+
3 24 ``frad.nlpid`` NLPID, or the ``0x00`` pad ahead of one
2322
====== ==== ================= ==========================================
2423

25-
When ``nlpid`` is the ``0x00`` pad marker, a further NLPID octet (``0x80``
26-
for SNAP), a 3-octet OUI and a 2-octet PID follow, kept as ``frad.ext_nlpid``,
27-
``frad.oui`` and ``frad.pid``.
24+
When ``nlpid`` is the ``0x00`` pad, the NLPID follows it as ``frad.ext_nlpid``.
25+
An NLPID of ``0x80``, with or without the pad, is followed by a SNAP header, a
26+
3-octet OUI and a 2-octet PID, kept as ``frad.oui`` and ``frad.pid``.
2827

2928
.. autoclass:: pcapkit.protocols.link.frad.FRAD
3029
:no-members:

‎pcapkit/protocols/data/link/frad.py‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,15 +31,17 @@ class FRAD(Protocol):
3131
#: NLPID selecting the encapsulated protocol, with any ``0x00`` pad
3232
#: already resolved to the real value that followed it.
3333
nlpid: 'int'
34+
#: Whether a ``0x00`` pad octet precedes the NLPID (:rfc:`2427#section-3`).
35+
pad: 'bool'
3436
#: SNAP OUI, present only when :attr:`nlpid` is ``0x80``.
3537
snap_oui: 'Optional[bytes]'
3638
#: SNAP PID, present only when :attr:`nlpid` is ``0x80``.
3739
snap_pid: 'Optional[int]'
38-
#: Header length, in octets -- 4 for a direct NLPID, 5 with the pad byte,
39-
#: or 10 with the SNAP header besides.
40+
#: Header length, in octets -- 4 for a direct NLPID, one more with the pad
41+
#: octet, and 5 more with a SNAP header.
4042
len: 'int'
4143

4244
if TYPE_CHECKING:
4345
def __init__(self, dlci: 'int', cr: 'int', fecn: 'int', becn: 'int', de: 'int', # pylint: disable=unused-argument,super-init-not-called
44-
control: 'int', nlpid: 'int', snap_oui: 'Optional[bytes]', # pylint: disable=unused-argument
46+
control: 'int', nlpid: 'int', pad: 'bool', snap_oui: 'Optional[bytes]', # pylint: disable=unused-argument
4547
snap_pid: 'Optional[int]', len: 'int') -> 'None': ... # pylint: disable=unused-argument,redefined-builtin

‎pcapkit/protocols/link/frad.py‎

Lines changed: 31 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,9 @@
1515
:attr:`LinuxSLL.__proto__ <pcapkit.protocols.link.linux_sll.LinuxSLL.__proto__>`. Its
1616
structure is the Q.922 LAPF address onward, with no trailing FCS: a 2-octet
1717
``frad.addr``, a 1-octet ``frad.control`` (``0x03``, UI, for ordinary data
18-
traffic), then a 1-octet ``frad.nlpid`` -- or, when SNAP-encapsulated, the
19-
``0x00`` pad RFC 2427 writes in its place, followed by the real NLPID
20-
(``0x80``) and a 5-octet SNAP header (OUI and PID). See
18+
traffic), then a 1-octet ``frad.nlpid``, which a ``0x00`` pad octet may
19+
precede. RFC 2427 writes the pad ahead of a SNAP header: the NLPID ``0x80``,
20+
then a 5-octet OUI and PID. See
2121
:meth:`FRAD.read <pcapkit.protocols.link.frad.FRAD.read>` for the full byte
2222
diagram and :mod:`pcapkit.protocols.schema.link.frad` for the field-by-field
2323
schema.
@@ -54,8 +54,8 @@ class FRAD(Link[Data_FRAD, Schema_FRAD],
5454
schema=Schema_FRAD, data=Data_FRAD):
5555
"""This class implements Frame Relay Access Device (FRAD) frames.
5656
57-
A frame whose NLPID (after resolving the ``0x00`` pad RFC 2427 writes
58-
ahead of a SNAP header) is ``0xCC`` or ``0x8E`` dispatches to
57+
A frame whose NLPID (after resolving any ``0x00`` pad ahead of it) is
58+
``0xCC`` or ``0x8E`` dispatches to
5959
:class:`~pcapkit.protocols.internet.ipv4.IPv4` or
6060
:class:`~pcapkit.protocols.internet.ipv6.IPv6` respectively, registered
6161
in the :attr:`self.__proto__ <pcapkit.protocols.link.frad.FRAD.__proto__>`
@@ -145,7 +145,10 @@ def read(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_FRAD':
145145
146146
A SNAP-encapsulated frame inserts a ``0x00`` pad and a ``0x80`` NLPID
147147
in place of the single NLPID octet above, followed by a 3-octet OUI
148-
and a 2-octet PID (:rfc:`2427#section-4.1`).
148+
and a 2-octet PID (:rfc:`2427#section-4.1`). The pad may precede any
149+
NLPID, or be left out ahead of ``0x80`` (:rfc:`2427#section-3`), and
150+
:attr:`~pcapkit.protocols.data.link.frad.FRAD.pad` records whether
151+
it is there.
149152
150153
Args:
151154
length: Length of packet data.
@@ -175,7 +178,8 @@ def read(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_FRAD':
175178
_dlci = (addr['dlci_hi'] << 4) | addr['dlci_lo']
176179

177180
_raw_nlpid = schema.nlpid
178-
if not _raw_nlpid:
181+
_pad = not _raw_nlpid
182+
if _pad:
179183
_ext = schema.ext_nlpid
180184
_nlpid = _ext if isinstance(_ext, int) else 0
181185
_hdr_len = 5
@@ -201,6 +205,7 @@ def read(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_FRAD':
201205
de=addr['de'],
202206
control=schema.control,
203207
nlpid=_nlpid,
208+
pad=_pad,
204209
snap_oui=_snap_oui,
205210
snap_pid=_snap_pid,
206211
len=_hdr_len,
@@ -215,6 +220,7 @@ def make(self,
215220
de: 'int' = 0,
216221
control: 'int' = 0x03,
217222
nlpid: 'int' = 0xCC,
223+
pad: 'Optional[bool]' = None,
218224
snap_oui: 'Optional[bytes]' = None,
219225
snap_pid: 'Optional[int]' = None,
220226
payload: 'bytes | ProtocolBase | Schema' = b'',
@@ -230,6 +236,10 @@ def make(self,
230236
control: Control field; ``0x03`` (UI) for ordinary data traffic.
231237
nlpid: NLPID selecting the encapsulated protocol; ``0xCC`` for
232238
IPv4, ``0x8E`` for IPv6, ``0x80`` for a SNAP header.
239+
pad: Whether a ``0x00`` pad octet precedes ``nlpid``
240+
(:rfc:`2427#section-3`). When :data:`None`, there is one ahead
241+
of a SNAP header alone, as :rfc:`2427#section-4.1` writes it,
242+
and ahead of an ``nlpid`` of ``0``, which reads as the pad.
233243
snap_oui: SNAP OUI; required, and only meaningful, when ``nlpid``
234244
is ``0x80``.
235245
snap_pid: SNAP PID; required, and only meaningful, when ``nlpid``
@@ -245,9 +255,10 @@ def make(self,
245255
``fecn``, ``becn`` or ``de`` is not ``0`` or ``1``; if
246256
``control`` or ``nlpid`` does not fit in 8 bits; if ``nlpid``
247257
is ``0x80`` and ``snap_oui`` is not exactly 3 octets or
248-
``snap_pid`` does not fit in 16 bits; or if either
258+
``snap_pid`` does not fit in 16 bits; if either
249259
``snap_oui`` or ``snap_pid`` is given while ``nlpid`` is not
250-
``0x80``.
260+
``0x80``; or if ``pad`` is :data:`False` with an ``nlpid`` of
261+
``0``.
251262
252263
Note:
253264
``nlpid`` is not refused for being ``0`` -- the value of the one
@@ -273,22 +284,25 @@ def make(self,
273284
control = self._make_uint(control, bits=8, name='control')
274285
nlpid = self._make_uint(nlpid, bits=8, name='nlpid')
275286

287+
if pad is None:
288+
pad = nlpid in (0x00, 0x80)
289+
elif not pad and not nlpid:
290+
raise ProtocolError(f'{self.alias}: an nlpid of 0 reads as the pad, so pad cannot be False')
291+
276292
if nlpid == 0x80:
277293
if not isinstance(snap_oui, (bytes, bytearray)) or len(snap_oui) != 3:
278294
raise ProtocolError(f'{self.alias}: invalid snap_oui: {snap_oui!r}, '
279295
f'must be exactly 3 octets when nlpid is 0x80')
280-
_schema_nlpid, _ext_nlpid = 0, 0x80
281296
_oui, _pid = bytes(snap_oui), self._make_uint(snap_pid, bits=16, name='snap_pid')
282297
else:
283298
if snap_oui is not None or snap_pid is not None:
284299
raise ProtocolError(f'{self.alias}: snap_oui and snap_pid are only meaningful '
285300
f'when nlpid is 0x80, not {nlpid!r}')
286-
_schema_nlpid, _ext_nlpid = nlpid, None
287301
_oui, _pid = None, None
288-
if not nlpid:
289-
# NOTE: A zero NLPID is the pad, which the schema follows with
290-
# ``ext_nlpid``, so that is written too (#2710).
291-
_ext_nlpid = 0
302+
303+
# NOTE: The pad is a zero ``nlpid`` octet, which the schema follows with
304+
# ``ext_nlpid``: a zero NLPID is written that way too (#2710, #2716).
305+
_schema_nlpid, _ext_nlpid = (0, nlpid) if pad else (nlpid, None)
292306

293307
return Schema_FRAD(
294308
addr={
@@ -318,7 +332,7 @@ def register(cls, code: 'int', protocol: 'ModuleDescriptor[ProtocolBase] | Type[
318332
should be ``{protocol.module}.{protocol.name}``.
319333
320334
Arguments:
321-
code: NLPID, after resolving the ``0x00`` pad ahead of a SNAP header
335+
code: NLPID, after resolving any ``0x00`` pad ahead of it
322336
protocol: module descriptor or a
323337
:class:`~pcapkit.protocols.protocol.ProtocolBase` subclass
324338
@@ -405,6 +419,7 @@ def _make_data(cls, data: 'Data_FRAD') -> 'dict[str, Any]': # type: ignore[over
405419
'de': data.de,
406420
'control': data.control,
407421
'nlpid': data.nlpid,
422+
'pad': data.pad,
408423
'snap_oui': data.snap_oui,
409424
'snap_pid': data.snap_pid,
410425
'payload': cls._make_payload(data),

‎pcapkit/protocols/schema/link/frad.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ def _effective_nlpid(packet: 'dict[str, Any]') -> 'int':
5151
5252
Returns:
5353
:attr:`~FRAD.ext_nlpid` when :attr:`~FRAD.nlpid` is the ``0x00`` pad
54-
marker :rfc:`2427#section-3` writes ahead of a SNAP header; otherwise
54+
:rfc:`2427#section-3` allows ahead of any NLPID; otherwise
5555
:attr:`~FRAD.nlpid` itself.
5656
5757
"""
@@ -92,9 +92,9 @@ class FRAD(Schema):
9292
})
9393
#: Control field; ``0x03`` (UI) for ordinary data traffic.
9494
control: 'int' = UInt8Field()
95-
#: NLPID, or the ``0x00`` pad marker ahead of a SNAP header.
95+
#: NLPID, or the ``0x00`` pad octet ahead of one.
9696
nlpid: 'int' = UInt8Field()
97-
#: NLPID proper, present only when :attr:`nlpid` is the pad marker.
97+
#: NLPID proper, present only when :attr:`nlpid` is the pad.
9898
ext_nlpid: 'Optional[int]' = ConditionalField(
9999
UInt8Field(),
100100
lambda packet: not packet['nlpid'],
Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# -*- coding: utf-8 -*-
2+
"""A FRAD pad octet is kept, and never invented, through a rebuild.
3+
4+
GitHub issue #2716: :rfc:`2427#section-3` allows a single ``0x00`` pad octet ahead of
5+
any NLPID, and :class:`~pcapkit.protocols.link.frad.FRAD` reads one ahead of every
6+
NLPID, but its data model did not record whether one was there. So
7+
:meth:`FRAD.make <pcapkit.protocols.link.frad.FRAD.make>` wrote the pad ahead of a
8+
SNAP header alone: a pad before a direct NLPID was lost on a rebuild, and one was
9+
invented ahead of a SNAP header captured without it. The data model's ``pad``
10+
records it, and ``make()`` takes it, writing the pad ahead of a SNAP header alone
11+
when it is not given.
12+
13+
The frames are built here; this module is unit-tier and reads no capture file.
14+
15+
"""
16+
from __future__ import annotations
17+
18+
import contextlib
19+
import logging
20+
import struct
21+
import unittest
22+
import warnings
23+
from typing import TYPE_CHECKING
24+
25+
from tests._support import reimport_once_per_class
26+
27+
if TYPE_CHECKING:
28+
from typing import Any, Callable, Iterator
29+
30+
#: Test tier (#1958): hand-picked parse -> rebuild round trips.
31+
__tier__ = 'ALL'
32+
33+
#: An IPv4 header (protocol UDP) and an 8-octet UDP header.
34+
IPV4 = (bytes.fromhex('4500001c00010000401100000a0000010a000002')
35+
+ bytes.fromhex('3039003500080000'))
36+
#: A minimal ARP request (RFC 826), 28 octets.
37+
ARP = bytes.fromhex('00010800060400010011223344550a0000010000000000000a000002')
38+
39+
#: Each frame: the RFC 2427 address of DLCI 50 and UI control, then the NLPID with
40+
#: or without the pad; its ``pad``, ``nlpid`` and header length; and its protocol chain.
41+
FRAMES = {
42+
'pad, IPv4': (bytes.fromhex('0c21' '03' '00' 'cc') + IPV4, (True, 0xCC, 5), 'FRAD:IPv4:UDP'),
43+
'SNAP without the pad': (bytes.fromhex('0c21' '03' '80' '000000' '0806') + ARP, (False, 0x80, 9),
44+
'FRAD:ARP'),
45+
# the forms the maker writes when ``pad`` is not given, as controls
46+
'IPv4': (bytes.fromhex('0c21' '03' 'cc') + IPV4, (False, 0xCC, 4), 'FRAD:IPv4:UDP'),
47+
'pad, SNAP': (bytes.fromhex('0c21' '03' '00' '80' '000000' '0806') + ARP, (True, 0x80, 10), 'FRAD:ARP'),
48+
} # type: dict[str, tuple[bytes, tuple[bool, int, int], str]]
49+
50+
#: A Linux cooked-capture source address, padded to its 8 octets.
51+
LINK_ADDR = bytes.fromhex('001122334455') + bytes(2)
52+
53+
54+
class _Logged(logging.Handler):
55+
"""Collect what the ``pcapkit`` logger reports."""
56+
57+
def __init__(self) -> None:
58+
super().__init__(logging.DEBUG)
59+
self.messages = [] # type: list[str]
60+
61+
def emit(self, record: 'logging.LogRecord') -> None:
62+
self.messages.append(f'logged: {record.getMessage()}')
63+
64+
65+
@contextlib.contextmanager
66+
def _reported() -> 'Iterator[list[str]]':
67+
"""Collect what the block reports, on the :mod:`warnings` channel and the logger."""
68+
handler = _Logged()
69+
logger = logging.getLogger('pcapkit')
70+
logger.addHandler(handler)
71+
try:
72+
with warnings.catch_warnings(record=True) as caught:
73+
warnings.simplefilter('always')
74+
yield handler.messages
75+
finally:
76+
logger.removeHandler(handler)
77+
handler.messages.extend(f'warned: {item.message}' for item in caught)
78+
79+
80+
class FRADPadRebuildTests(unittest.TestCase):
81+
"""A FRAD frame rebuilds with the pad octet it was captured with, and no other."""
82+
83+
def setUp(self) -> None:
84+
reimport_once_per_class(self)
85+
from pcapkit.const.linux.arphrd import ARPHRD
86+
from pcapkit.protocols.link.frad import FRAD
87+
from pcapkit.protocols.link.linux_sll1 import LinuxSLL1
88+
from pcapkit.protocols.link.linux_sll2 import LinuxSLL2
89+
from pcapkit.utilities.exceptions import ProtocolError
90+
91+
self.FRAD = FRAD
92+
self.ProtocolError = ProtocolError
93+
self.cooked = {
94+
'LinuxSLL1': (LinuxSLL1, struct.pack('>HHH', 0, ARPHRD.FRAD, 6) + LINK_ADDR
95+
+ struct.pack('>H', 0)),
96+
'LinuxSLL2': (LinuxSLL2, struct.pack('>HHIHBB', 0, 0, 1, ARPHRD.FRAD, 0, 6) + LINK_ADDR),
97+
} # type: dict[str, tuple[Any, bytes]]
98+
99+
def parse(self, build: 'Callable[[], Any]') -> 'tuple[Any, list[str]]':
100+
"""What ``build`` returns, and what it reported."""
101+
with _reported() as messages:
102+
layer = build()
103+
return layer, messages
104+
105+
def assertRebuildsQuietly(self, layer: 'Any') -> 'None': # pylint: disable=invalid-name
106+
"""``layer`` rebuilt from its data model and its dict: its octets, and nothing reported."""
107+
for path, data in (('model', layer.info), ('dict', layer.info.to_dict())):
108+
with self.subTest(path=path):
109+
rebuilt, messages = self.parse(lambda: type(layer).from_data(data)) # pylint: disable=cell-var-from-loop
110+
self.assertEqual((rebuilt.data.hex(), messages), (layer.data.hex(), []))
111+
112+
def test_a_whole_frame_reads_its_pad(self) -> None:
113+
for label, (frame, (pad, nlpid, length), chain) in FRAMES.items():
114+
with self.subTest(frame=label):
115+
layer, messages = self.parse(lambda: self.FRAD(frame, len(frame))) # pylint: disable=cell-var-from-loop
116+
self.assertEqual(messages, [])
117+
self.assertEqual((layer.info.pad, layer.info.nlpid, layer.info.len), (pad, nlpid, length))
118+
self.assertEqual(str(layer.protochain), chain)
119+
120+
def test_a_whole_frame_rebuilds_as_captured(self) -> None:
121+
for label, (frame, _, _) in FRAMES.items():
122+
with self.subTest(frame=label):
123+
layer = self.FRAD(frame, len(frame))
124+
self.assertRebuildsQuietly(layer)
125+
126+
def test_every_cut_rebuilds_as_captured(self) -> None:
127+
for label, (frame, _, _) in FRAMES.items():
128+
for count in range(1, len(frame)):
129+
with self.subTest(frame=label, captured=count):
130+
with warnings.catch_warnings():
131+
warnings.simplefilter('ignore')
132+
layer = self.FRAD(frame[:count], count)
133+
self.assertEqual(layer.data, frame[:count])
134+
self.assertRebuildsQuietly(layer)
135+
136+
def test_linux_sll_rebuilds_the_pad_as_captured(self) -> None:
137+
for name, (cls, head) in self.cooked.items():
138+
for label, (frame, (pad, _, _), chain) in FRAMES.items():
139+
raw = head + frame
140+
with self.subTest(cooked=name, frame=label):
141+
sll, messages = self.parse(lambda: cls(raw, len(raw))) # pylint: disable=cell-var-from-loop
142+
self.assertEqual(messages, [])
143+
self.assertEqual(str(sll.protochain).split(':', 1)[1], chain)
144+
self.assertIs(sll.payload.info.pad, pad)
145+
self.assertRebuildsQuietly(sll)
146+
147+
def test_make_writes_the_pad_ahead_of_snap_alone_by_default(self) -> None:
148+
# A direct build is as it was: the pad ahead of a SNAP header, and an
149+
# NLPID of 0 written as the pad it reads as.
150+
cases = {
151+
'IPv4': ({'nlpid': 0xCC}, '0c2103cc'),
152+
'SNAP': ({'nlpid': 0x80, 'snap_oui': bytes(3), 'snap_pid': 0x0806}, '0c2103008000000008' '06'),
153+
'zero NLPID': ({'nlpid': 0}, '0c21030000'),
154+
}
155+
for label, (kwargs, octets) in cases.items():
156+
with self.subTest(case=label):
157+
made, messages = self.parse(lambda: self.FRAD(dlci=50, **kwargs)) # pylint: disable=cell-var-from-loop
158+
self.assertEqual((made.data.hex(), messages), (octets, []))
159+
160+
def test_make_takes_the_pad(self) -> None:
161+
cases = {
162+
'pad, IPv4': ({'nlpid': 0xCC, 'pad': True}, '0c2103' '00cc'),
163+
'IPv4 without the pad': ({'nlpid': 0xCC, 'pad': False}, '0c2103' 'cc'),
164+
'SNAP without the pad': ({'nlpid': 0x80, 'pad': False, 'snap_oui': bytes(3), 'snap_pid': 0x0806},
165+
'0c2103' '80' '000000' '0806'),
166+
'pad, zero NLPID': ({'nlpid': 0, 'pad': True}, '0c2103' '0000'),
167+
}
168+
for label, (kwargs, octets) in cases.items():
169+
with self.subTest(case=label):
170+
made, messages = self.parse(lambda: self.FRAD(dlci=50, **kwargs)) # pylint: disable=cell-var-from-loop
171+
self.assertEqual((made.data.hex(), messages), (octets, []))
172+
self.assertIs(self.FRAD(made.data, len(made.data)).info.pad, kwargs['pad'])
173+
174+
def test_make_refuses_a_zero_nlpid_without_the_pad(self) -> None:
175+
from pcapkit.utilities.exceptions import CaughtByCaller
176+
177+
with CaughtByCaller(self.ProtocolError), self.assertRaisesRegex(
178+
self.ProtocolError, r'^FRAD: an nlpid of 0 reads as the pad, so pad cannot be False$'):
179+
self.FRAD(nlpid=0, pad=False)
180+
181+
182+
if __name__ == '__main__':
183+
unittest.main()

0 commit comments

Comments
 (0)