Skip to content

Commit 517cd70

Browse files
authored
fix(protocols)!: pad two octets with one PadN, not two Pad1 (#1793) (#1812)
HOPOPT, IPv6-Opts and MH each filled a two-octet alignment shortfall with two Pad1 options. RFC 8200 section 4.2, and RFC 6275 section 6.2.2 for mobility options, say a PadN should be used rather than multiple Pad1. - `_make_pad_options` in hopopt.py, ipv6_opts.py and mh.py: two octets are now one PadN of length 0 (`01 00`); one octet stays a Pad1 and three or more keep the PadN they had. Docstrings follow. - Parsed padding is untouched: a header carrying two Pad1 still rebuilds byte for byte, since parsed options are re-emitted as read. - Tests: new test_padn_two_octets_1793_unit pins the helper and the built headers for all three protocols, plus the two-Pad1 parsed rebuild; the fresh-build pins in five existing modules move to `01 00`. Closes #1793
1 parent 71df8b1 commit 517cd70

9 files changed

Lines changed: 177 additions & 44 deletions

File tree

‎pcapkit/protocols/internet/hopopt.py‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1356,20 +1356,19 @@ def _make_pad_options(self, offset: 'int') -> 'tuple[list[Schema_PadOption], int
13561356
A ``PadN`` option spends two octets on its own type and
13571357
``Opt Data Len`` fields before any padding data, so occupying
13581358
``pad_len`` octets means an ``Opt Data Len`` of ``pad_len - 2``.
1359-
One or two octets are padded with ``Pad1`` options instead, that
1360-
being the only form which can occupy a single octet
1361-
[:rfc:`8200#section-4.2`]; two octets need two separate ``Pad1``
1362-
schemas, since a schema instance is mutable and must not be shared
1363-
between two entries of the option list.
1359+
One octet is padded with a ``Pad1`` option instead, that being the
1360+
only form which can occupy a single octet. Two octets are one
1361+
``PadN`` with an ``Opt Data Len`` of ``0``, not two ``Pad1``:
1362+
:rfc:`8200#section-4.2` says a ``PadN`` should be used rather than
1363+
multiple ``Pad1`` options.
13641364
13651365
"""
13661366
if offset % 8 == 0:
13671367
return [], 0
13681368

13691369
pad_len = 8 - (offset % 8)
1370-
if pad_len <= 2:
1371-
return [self._make_opt_pad(Enum_Option.Pad1, length=0) # type: ignore[arg-type]
1372-
for _ in range(pad_len)], pad_len
1370+
if pad_len == 1:
1371+
return [self._make_opt_pad(Enum_Option.Pad1, length=0)], pad_len # type: ignore[arg-type]
13731372
return [self._make_opt_pad(Enum_Option.PadN, length=pad_len - 2)], pad_len # type: ignore[arg-type]
13741373

13751374
def _make_hopopt_options(self, options: 'list[Schema_Option | tuple[Enum_Option, dict[str, Any]] | bytes] | Option') -> 'tuple[list[Schema_Option | bytes], int]':

‎pcapkit/protocols/internet/ipv6_opts.py‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1345,20 +1345,19 @@ def _make_pad_options(self, offset: 'int') -> 'tuple[list[Schema_PadOption], int
13451345
A ``PadN`` option spends two octets on its own type and
13461346
``Opt Data Len`` fields before any padding data, so occupying
13471347
``pad_len`` octets means an ``Opt Data Len`` of ``pad_len - 2``.
1348-
One or two octets are padded with ``Pad1`` options instead, that
1349-
being the only form which can occupy a single octet
1350-
[:rfc:`8200#section-4.2`]; two octets need two separate ``Pad1``
1351-
schemas, since a schema instance is mutable and must not be shared
1352-
between two entries of the option list.
1348+
One octet is padded with a ``Pad1`` option instead, that being the
1349+
only form which can occupy a single octet. Two octets are one
1350+
``PadN`` with an ``Opt Data Len`` of ``0``, not two ``Pad1``:
1351+
:rfc:`8200#section-4.2` says a ``PadN`` should be used rather than
1352+
multiple ``Pad1`` options.
13531353
13541354
"""
13551355
if offset % 8 == 0:
13561356
return [], 0
13571357

13581358
pad_len = 8 - (offset % 8)
1359-
if pad_len <= 2:
1360-
return [self._make_opt_pad(Enum_Option.Pad1, length=0) # type: ignore[arg-type]
1361-
for _ in range(pad_len)], pad_len
1359+
if pad_len == 1:
1360+
return [self._make_opt_pad(Enum_Option.Pad1, length=0)], pad_len # type: ignore[arg-type]
13621361
return [self._make_opt_pad(Enum_Option.PadN, length=pad_len - 2)], pad_len # type: ignore[arg-type]
13631362

13641363
def _make_ipv6_opts(self, options: 'list[Schema_Option | tuple[Enum_Option, dict[str, Any]] | bytes] | Option') -> 'tuple[list[Schema_Option | bytes], int]':

‎pcapkit/protocols/internet/mh.py‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7742,20 +7742,19 @@ def _make_pad_options(self, offset: 'int') -> 'tuple[list[Schema_PadOption], int
77427742
A ``PadN`` option spends two octets on its own type and
77437743
``Option Length`` fields before any padding data, so occupying
77447744
``pad_len`` octets means an ``Option Length`` of ``pad_len - 2``.
7745-
One or two octets are padded with ``Pad1`` options instead, that
7746-
being the only form which can occupy a single octet
7747-
[:rfc:`6275#section-6.2.2`]; two octets need two separate ``Pad1``
7748-
schemas, since a schema instance is mutable and must not be shared
7749-
between two entries of the option list.
7745+
One octet is padded with a ``Pad1`` option instead, that being the
7746+
only form which can occupy a single octet. Two octets are one
7747+
``PadN`` with an ``Option Length`` of ``0``, not two ``Pad1``:
7748+
:rfc:`6275#section-6.2.2` says a ``PadN`` should be used rather than
7749+
multiple ``Pad1`` options.
77507750
77517751
"""
77527752
if offset % 8 == 0:
77537753
return [], 0
77547754

77557755
pad_len = 8 - (offset % 8)
7756-
if pad_len <= 2:
7757-
return [self._make_opt_pad(Enum_Option.Pad1, length=0) # type: ignore[arg-type]
7758-
for _ in range(pad_len)], pad_len
7756+
if pad_len == 1:
7757+
return [self._make_opt_pad(Enum_Option.Pad1, length=0)], pad_len # type: ignore[arg-type]
77597758
return [self._make_opt_pad(Enum_Option.PadN, length=pad_len - 2)], pad_len # type: ignore[arg-type]
77607759

77617760
def _pad_mh_message(self, data: 'Schema_Packet | bytes') -> 'Schema_Packet | bytes':

‎tests/protocols/internet/test_ipv6_extension_unit.py‎

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1068,17 +1068,19 @@ def _assert_option_constructors_cover_branchy_values(self, protocol_cls: type) -
10681068
self.assertEqual(schema_length, 14)
10691069
self.assertEqual(type(schema_options[0]).__name__, 'UnassignedOption')
10701070

1071-
# NOTE: Two ``Pad1`` options are emitted when the shortfall is exactly 2
1072-
# octets, i.e. when ``2 + opt_len`` is 6 past a multiple of 8. That is a
1073-
# 4-octet option, not the 6-octet one this case used to pass -- 2 + 6 is
1074-
# already aligned and now needs no padding at all.
1075-
pad1_options, pad1_length = make_options([
1071+
# NOTE: A shortfall of exactly 2 octets, i.e. ``2 + opt_len`` 6 past a
1072+
# multiple of 8, is one ``PadN`` of ``Opt Data Len`` 0 rather than two
1073+
# ``Pad1`` (#1793). That is a 4-octet option, not the 6-octet one this
1074+
# case used to pass -- 2 + 6 is already aligned and needs no padding.
1075+
pad2_options, pad2_length = make_options([
10761076
bytes([Option.CALIPSO]) + b'123',
10771077
])
1078-
# 4 octets of CALIPSO + two 1-octet Pad1 = 6; 2 + 6 = 8
1079-
self.assertEqual(pad1_length, 6)
1078+
# 4 octets of CALIPSO + a 2-octet PadN = 6; 2 + 6 = 8
1079+
self.assertEqual(pad2_length, 6)
10801080
self.assertEqual([type(item).__name__ if not isinstance(item, bytes) else 'bytes'
1081-
for item in pad1_options], ['bytes', 'PadOption', 'PadOption'])
1081+
for item in pad2_options], ['bytes', 'PadOption'])
1082+
self.assertEqual(pad2_options[1].type, Option.PadN)
1083+
self.assertEqual(pad2_options[1].pack(), b'\x01\x00')
10821084

10831085
# NOTE: Likewise, the option that needs no padding is the 6-octet one; the
10841086
# 8-octet option this case used to pass leaves 2 + 8 = 10 and now draws 6
@@ -1113,7 +1115,7 @@ def _assert_option_constructors_cover_branchy_values(self, protocol_cls: type) -
11131115
for label, (built, built_len) in {
11141116
'bytes + padn': (options, total_length),
11151117
'schema + padn': (schema_options, schema_length),
1116-
'two pad1': (pad1_options, pad1_length),
1118+
'two-octet padn': (pad2_options, pad2_length),
11171119
'no padding': (no_pad_options, no_pad_length),
11181120
'from dict': (dict_options, dict_length),
11191121
}.items():
@@ -2287,8 +2289,9 @@ def _assert_constructed_header_round_trips(self, protocol_cls: type) -> None:
22872289
22882290
The option lengths are chosen for the padding they draw: the whole
22892291
header, its two fixed octets included, has to be a multiple of 8, so an
2290-
option of ``8n + 5`` octets needs a single ``Pad1``, one of ``8n + 4``
2291-
needs two, and anything else needs a ``PadN``.
2292+
option of ``8n + 5`` octets needs a single ``Pad1``, and anything else
2293+
short of the boundary needs a ``PadN`` -- including one of ``8n + 4``,
2294+
whose two spare octets are a ``PadN`` of ``Opt Data Len`` 0.
22922295
22932296
"""
22942297
from pcapkit.const.ipv6.option import Option
@@ -2298,9 +2301,9 @@ def _assert_constructed_header_round_trips(self, protocol_cls: type) -> None:
22982301
# a 5-octet option leaves one octet, which only a Pad1 can fill
22992302
('one pad1', [(Option.get(250), {'data': b'abc'})], 8,
23002303
[(Option.get(250), 5), (Option.Pad1, 1)]),
2301-
# a 4-octet option leaves two, i.e. two Pad1 rather than a PadN
2302-
('two pad1', [(Option.Router_Alert, {'alert': 0})], 8,
2303-
[(Option.Router_Alert, 4), (Option.Pad1, 1), (Option.Pad1, 1)]),
2304+
# a 4-octet option leaves two, i.e. one PadN of length 0 (#1793)
2305+
('two-octet padn', [(Option.Router_Alert, {'alert': 0})], 8,
2306+
[(Option.Router_Alert, 4), (Option.PadN, 2)]),
23042307
# three or more spare octets are a PadN, whose own two octets of
23052308
# overhead have to come out of the padding it is asked to occupy
23062309
('padn', [(Option.Tunnel_Encapsulation_Limit, {'limit': 3})], 8,

‎tests/protocols/internet/test_mh_flags_reserved_unit.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,14 @@
5252
'PerSessionBitRateAttribute': ('3b020000000000003a0e00000000000003063fff000003e8', 14),
5353
}
5454

55+
#: ``site -> octets make() emits``, where they differ from :data:`FRAMES`. Two
56+
#: octets of fresh padding are one ``PadN`` of length 0 (#1793), whereas these
57+
#: frames end in two ``Pad1``, which a parsed header keeps on rebuild.
58+
MADE = {
59+
'DynamicIPMulticastSelectorOption': '3b0100000000000036048f7f00000100',
60+
'IPv4TrafficOffloadSelectorOption': '3b0100000000000035047fffffff0100',
61+
}
62+
5563
MESSAGES = {
5664
'BindingRevocationMessage': 'Binding_Revocation_Message',
5765
'FastBindingAcknowledgmentMessage': 'Fast_Binding_Acknowledgment',
@@ -169,7 +177,7 @@ def test_make_writes_the_reserved_bits(self) -> None:
169177
for site, (frame, width) in FRAMES.items():
170178
with self.subTest(site=site):
171179
built = self._make(site, value=(1 << width) - 1)
172-
self.assertEqual(built.hex(), frame)
180+
self.assertEqual(built.hex(), MADE.get(site, frame))
173181
model, attr = self._site(self._parse(built).info, site) # type: ignore[attr-defined]
174182
self.assertEqual(getattr(model, attr), (1 << width) - 1)
175183

‎tests/protocols/internet/test_mh_unit.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2052,8 +2052,9 @@ def test_mh_constructed_header_round_trips(self) -> None:
20522052

20532053
brr = Packet.Binding_Refresh_Request
20542054
cases = (
2055-
# 2 octets of reserved + a 6-octet PadN = 8, so 6 + 8 = 14 needs 2 more
2056-
('padn then two pad1', [(Option.PadN, {'length': 4})], 16),
2055+
# 2 octets of reserved + a 6-octet PadN = 8, so 6 + 8 = 14 needs 2
2056+
# more, which are one PadN of Option Length 0 (#1793)
2057+
('padn then a two-octet padn', [(Option.PadN, {'length': 4})], 16),
20572058
# 2 + 8 = 10, and 6 + 10 = 16 is already aligned
20582059
('padn, already aligned', [(Option.PadN, {'length': 6})], 16),
20592060
# 2 + 4 = 6, and 6 + 6 = 12 needs 4 more octets

‎tests/protocols/internet/test_mpl_seed_rebuild_unit.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,9 @@ def test_address_seed_keyword_selects_source_address_kind(self) -> None:
7676
with self.subTest(proto=name):
7777
built = cls(options=[(Option.MPL_Option, {'seed': SRC, 'seq': 7, 'max': True})],
7878
next=TransType.IPv6_NoNxt, payload=b'')
79-
self.assertEqual(built.data, HEADERS[0])
79+
# HEADERS[0] ends in two Pad1, which a parsed header keeps; two
80+
# octets of fresh padding are one PadN of length 0 (#1793)
81+
self.assertEqual(built.data, HEADERS[0][:-2] + b'\x01\x00')
8082

8183
def test_seed_that_does_not_fit_its_kind_is_rejected(self) -> None:
8284
from pcapkit.const.ipv6.option import Option
Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# -*- coding: utf-8 -*-
2+
"""Two octets of option padding are one ``PadN``, not two ``Pad1``.
3+
4+
GitHub issue #1793: HOPOPT, IPv6-Opts and MH each filled a two-octet shortfall
5+
with two ``Pad1`` options. :rfc:`8200#section-4.2`, and :rfc:`6275#section-6.2.2`
6+
for mobility options, say a ``PadN`` should be used rather than multiple
7+
``Pad1``, so two octets are now one ``PadN`` of length ``0``: the octets
8+
``01 00``. One octet is still a ``Pad1``, and parsed padding is still rebuilt as
9+
it was read -- only freshly built padding changed.
10+
11+
Every case builds its own octets in memory and reads no capture. Classes are
12+
imported inside each test, after :func:`~tests._support.reimport_once_per_class`.
13+
14+
"""
15+
16+
import importlib
17+
import io
18+
import unittest
19+
import warnings
20+
21+
from tests._support import reimport_once_per_class
22+
23+
#: Protocol module, class name and option enum module of each padding builder.
24+
PROTOCOLS = (
25+
('pcapkit.protocols.internet.hopopt', 'HOPOPT', 'pcapkit.const.ipv6.option'),
26+
('pcapkit.protocols.internet.ipv6_opts', 'IPv6_Opts', 'pcapkit.const.ipv6.option'),
27+
('pcapkit.protocols.internet.mh', 'MH', 'pcapkit.const.mh.option'),
28+
)
29+
30+
#: Parsed headers whose padding is two ``Pad1`` options, which have to rebuild
31+
#: unchanged: a Router Alert in an options header, and a Binding Refresh Request
32+
#: carrying a 6-octet ``PadN``.
33+
TWO_PAD1 = {
34+
'HOPOPT': '3b00' '05020000' '00' '00',
35+
'IPv6_Opts': '3b00' '05020000' '00' '00',
36+
'MH': '3b01000000000000' '010400000000' '00' '00',
37+
}
38+
39+
40+
class TestTwoOctetPadding(unittest.TestCase):
41+
"""Pin the wire form of two octets of HOPOPT, IPv6-Opts and MH padding."""
42+
43+
def setUp(self) -> None:
44+
reimport_once_per_class(self)
45+
46+
def _protocols(self) -> 'list[tuple[type, type]]':
47+
return [(getattr(importlib.import_module(mod), name),
48+
importlib.import_module(enum).Option)
49+
for mod, name, enum in PROTOCOLS]
50+
51+
def test_two_octets_are_one_zero_length_padn(self) -> None:
52+
for cls, option in self._protocols():
53+
proto = object.__new__(cls)
54+
# the offset counts the fixed header too, so 6 and 14 are two short
55+
for offset in (6, 14):
56+
with self.subTest(protocol=cls.__name__, offset=offset):
57+
with warnings.catch_warnings():
58+
warnings.simplefilter('error')
59+
pads, pad_len = proto._make_pad_options(offset)
60+
self.assertEqual(pad_len, 2)
61+
self.assertEqual([pad.type for pad in pads], [option.PadN])
62+
self.assertEqual(pads[0].pack(), b'\x01\x00')
63+
64+
def test_one_and_three_octets_keep_their_form(self) -> None:
65+
for cls, option in self._protocols():
66+
proto = object.__new__(cls)
67+
with self.subTest(protocol=cls.__name__, octets=1):
68+
pads, pad_len = proto._make_pad_options(7)
69+
self.assertEqual(pad_len, 1)
70+
self.assertEqual([(pad.type, pad.pack()) for pad in pads],
71+
[(option.Pad1, b'\x00')])
72+
with self.subTest(protocol=cls.__name__, octets=3):
73+
pads, pad_len = proto._make_pad_options(5)
74+
self.assertEqual(pad_len, 3)
75+
self.assertEqual([(pad.type, pad.pack()) for pad in pads],
76+
[(option.PadN, b'\x01\x01\x00')])
77+
78+
def test_constructed_header_ends_in_one_zero_length_padn(self) -> None:
79+
from pcapkit.const.ipv6.option import Option as IPv6_Option
80+
from pcapkit.const.mh.option import Option as MH_Option
81+
from pcapkit.const.mh.packet import Packet
82+
from pcapkit.const.reg.transtype import TransType
83+
84+
protocols = {cls.__name__: cls for cls, _ in self._protocols()}
85+
built = {
86+
# 2 + a 4-octet Router Alert = 6, two short of 8
87+
'HOPOPT': (protocols['HOPOPT'](next=TransType.IPv6_NoNxt,
88+
options=[(IPv6_Option.Router_Alert, {'alert': 0})]),
89+
'3b00' '05020000' '0100',
90+
[(IPv6_Option.Router_Alert, 4), (IPv6_Option.PadN, 2)]),
91+
'IPv6_Opts': (protocols['IPv6_Opts'](next=TransType.IPv6_NoNxt,
92+
options=[(IPv6_Option.Router_Alert, {'alert': 0})]),
93+
'3b00' '05020000' '0100',
94+
[(IPv6_Option.Router_Alert, 4), (IPv6_Option.PadN, 2)]),
95+
# 6 + 2 octets of reserved + a 6-octet PadN = 14, two short of 16
96+
'MH': (protocols['MH'](next=TransType.IPv6_NoNxt, type=Packet.Binding_Refresh_Request,
97+
chksum=b'\x00\x00', data={'options': [(MH_Option.PadN, {'length': 4})]}),
98+
'3b01000000000000' '010400000000' '0100',
99+
[(MH_Option.PadN, 6), (MH_Option.PadN, 2)]),
100+
}
101+
for name, (proto, hexstr, expected) in built.items():
102+
with self.subTest(protocol=name):
103+
raw = bytes(proto)
104+
self.assertEqual(raw.hex(), hexstr)
105+
parsed = type(proto)(io.BytesIO(raw), len(raw), extension=True)
106+
self.assertEqual([(code, opt.length)
107+
for code, opt in parsed.info.options.items(multi=True)],
108+
expected)
109+
110+
def test_parsed_two_pad1_rebuild_byte_for_byte(self) -> None:
111+
for cls, option in self._protocols():
112+
octets = bytes.fromhex(TWO_PAD1[cls.__name__])
113+
with self.subTest(protocol=cls.__name__):
114+
parsed = cls(io.BytesIO(octets), len(octets), extension=True)
115+
pads = list(parsed.info.options.items(multi=True))[-2:]
116+
self.assertEqual([code for code, _ in pads], [option.Pad1, option.Pad1])
117+
self.assertEqual(bytes(cls.from_data(parsed.info)).hex(), octets.hex())
118+
119+
120+
if __name__ == '__main__':
121+
unittest.main()

‎tests/protocols/test_protocol_make_unit.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,12 +51,13 @@ def _attr(path: 'str') -> 'Any':
5151
'TCP options': ('pcapkit.protocols.transport.tcp.TCP',
5252
{'options': [b'\x02\x04\x05\xb4']},
5353
'0000000000000000000000006000ffff00000000020405b4'),
54+
# two octets of padding follow the option, as one zero-length PadN (#1793)
5455
'HOPOPT options': ('pcapkit.protocols.internet.hopopt.HOPOPT',
5556
{'extension': True, 'options': [b'\x05\x02\x00\x00']},
56-
'1100050200000000'),
57+
'1100050200000100'),
5758
'IPv6_Opts options': ('pcapkit.protocols.internet.ipv6_opts.IPv6_Opts',
5859
{'extension': True, 'options': [b'\x05\x02\x00\x00']},
59-
'1100050200000000'),
60+
'1100050200000100'),
6061
'MH options': ('pcapkit.protocols.internet.mh.MH',
6162
{'data': {'options': [b'\x01\x02\x00\x00']}},
6263
'11010000000000000102000001020000'),

0 commit comments

Comments
 (0)