Skip to content

Commit 6323852

Browse files
authored
fix(sctp)!: keep the octets after the last whole chunk as captured (#1468) (#1472)
1 parent 3180d41 commit 6323852

6 files changed

Lines changed: 257 additions & 13 deletions

File tree

‎pcapkit/protocols/data/transport/sctp.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -614,4 +614,8 @@ class SCTP(Protocol):
614614
chunks: 'OrderedMultiDict[ChunkType, Chunk]'
615615

616616
if TYPE_CHECKING:
617+
#: Octets captured after the last whole chunk, present only when there
618+
#: are any.
619+
trailer: 'bytes'
620+
617621
def __init__(self, srcport: 'AppType', dstport: 'AppType', vtag: 'int', chksum: 'bytes', chunks: 'OrderedMultiDict[ChunkType, Chunk]') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,line-too-long,redefined-builtin

‎pcapkit/protocols/schema/transport/sctp.py‎

Lines changed: 73 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
# mypy: disable-error-code=assignment
33
"""header schema for stream control transmission protocol"""
44

5+
import io
56
from typing import TYPE_CHECKING
67

78
from pcapkit.const.reg.apptype import AppType as Enum_AppType
@@ -13,7 +14,7 @@
1314
PayloadProtocolIdentifier as Enum_PayloadProtocolIdentifier
1415
from pcapkit.corekit.fields.collections import ListField, OptionField
1516
from pcapkit.corekit.fields.ipaddress import IPv4AddressField, IPv6AddressField
16-
from pcapkit.corekit.fields.misc import SchemaField
17+
from pcapkit.corekit.fields.misc import PayloadField, SchemaField
1718
from pcapkit.corekit.fields.numbers import EnumField, UInt16Field, UInt32Field
1819
from pcapkit.corekit.fields.strings import BitField, BytesField, PaddingField
1920
from pcapkit.protocols.schema.schema import EnumSchema, Schema, schema_final
@@ -49,7 +50,7 @@
4950

5051
if TYPE_CHECKING:
5152
from ipaddress import IPv4Address, IPv6Address
52-
from typing import Any, Callable
53+
from typing import IO, Any, Callable
5354

5455
from pcapkit.protocols.protocol import ProtocolBase
5556

@@ -890,6 +891,70 @@ class ShutdownCompleteChunk(Chunk, code=Enum_Chunk.Shutdown_Complete):
890891
def __init__(self, type: 'Enum_Chunk', flags: 'TBitFlags', length: 'int') -> 'None': ...
891892

892893

894+
def whole_chunks_length(data: 'bytes') -> 'int':
895+
"""Length of the run of whole chunks at the front of ``data``.
896+
897+
Args:
898+
data: Chunk area of an SCTP packet.
899+
900+
Returns:
901+
Number of octets up to the end of the last chunk whose declared
902+
``length`` octets are all present, with as much of its padding as there
903+
is, c.f. :func:`padding_length`. A ``length`` below the four-octet chunk
904+
header (:rfc:`9260#section-3.2`) delimits nothing, so the run stops
905+
there too; four zero octets would otherwise read as a DATA chunk.
906+
907+
"""
908+
end, size = 0, len(data)
909+
while size - end >= 4:
910+
length = int.from_bytes(data[end + 2:end + 4], 'big')
911+
stop = end + length
912+
if length < 4 or stop > size:
913+
break
914+
end = min(stop + (-length % 4), size)
915+
return end
916+
917+
918+
class ChunkListField(OptionField):
919+
"""Chunk list that stops at the last whole chunk.
920+
921+
SCTP has no packet length field, so octets after the last whole chunk --
922+
fewer than a chunk header, or a chunk whose ``length`` runs past the data --
923+
cannot be told apart from a chunk cut short. They are not parsed but
924+
reported as option padding, which :meth:`Schema.unpack
925+
<pcapkit.protocols.schema.schema.Schema.unpack>` hands back to the stream for
926+
:attr:`SCTP.trailer` to keep as captured (:issue:`1468`).
927+
928+
"""
929+
930+
def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'list[Chunk]':
931+
"""Unpack field value from :obj:`bytes`.
932+
933+
Args:
934+
buffer: Field buffer.
935+
packet: Packet data.
936+
937+
Returns:
938+
Unpacked whole chunks.
939+
940+
"""
941+
if isinstance(buffer, bytes):
942+
data = buffer
943+
else:
944+
start = buffer.tell()
945+
data = buffer.read(max(self._length, 0))
946+
buffer.seek(start, io.SEEK_SET)
947+
948+
area, whole = self._length, whole_chunks_length(data)
949+
self._length = whole
950+
try:
951+
chunks = super().unpack(data[:whole], packet)
952+
finally:
953+
self._length = area
954+
self._option_padding += len(data) - whole
955+
return chunks
956+
957+
893958
@schema_final
894959
class SCTP(Schema):
895960
"""Header schema for SCTP packets.
@@ -913,14 +978,18 @@ class SCTP(Schema):
913978
#: Checksum, as a CRC32c over the whole packet with this field zeroed.
914979
chksum: 'bytes' = BytesField(length=4)
915980
#: Chunks.
916-
chunks: 'list[Chunk]' = OptionField(
981+
chunks: 'list[Chunk]' = ChunkListField(
917982
length=lambda pkt: max(pkt['__length__'], 0),
918983
base_schema=Chunk,
919984
type_name='type',
920985
registry=Chunk.registry,
921986
)
987+
#: Octets captured after the last whole chunk, c.f. :class:`ChunkListField`
988+
#: and :attr:`IPv4.trailer <pcapkit.protocols.schema.internet.ipv4.IPv4.trailer>`.
989+
trailer: 'bytes' = PayloadField(default=b'')
922990

923991
if TYPE_CHECKING:
924992
def __init__(self, srcport: 'Enum_AppType | int', dstport: 'Enum_AppType | int',
925993
vtag: 'int', chksum: 'bytes',
926-
chunks: 'list[Chunk | bytes] | bytes') -> 'None': ...
994+
chunks: 'list[Chunk | bytes] | bytes',
995+
trailer: 'bytes' = b'') -> 'None': ...

‎pcapkit/protocols/transport/sctp.py‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -566,6 +566,14 @@ def read(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_SCTP':
566566
chunks=self._read_sctp_chunks(),
567567
)
568568

569+
# NOTE: With no packet length field, octets after the last whole chunk
570+
# cannot be told apart from a chunk cut short, so they are kept as
571+
# captured rather than rejected (:issue:`1468`).
572+
if schema.trailer:
573+
sctp.__update__([
574+
('trailer', schema.trailer),
575+
])
576+
569577
# NOTE: The next layer is named by the DATA chunk's payload protocol
570578
# identifier, not by a port number. A packet may bundle several DATA
571579
# chunks; we dispatch on the first one, and the rest stay recorded in
@@ -587,6 +595,7 @@ def make(self,
587595
vtag: 'int' = 0,
588596
chksum: 'Optional[bytes]' = None,
589597
chunks: 'Optional[list[Schema_Chunk | tuple[Enum_Chunk, dict[str, Any]] | bytes] | Chunks]' = None, # pylint: disable=line-too-long
598+
trailer: 'bytes' = b'',
590599
**kwargs: 'Any') -> 'Schema_SCTP':
591600
"""Make (construct) packet data.
592601
@@ -598,6 +607,8 @@ def make(self,
598607
constructed packet is computed and inserted, per
599608
:rfc:`9260#section-6.8`.
600609
chunks: SCTP chunks.
610+
trailer: Octets after the last chunk, written as is and covered by
611+
the computed checksum.
601612
**kwargs: Arbitrary keyword arguments.
602613
603614
Returns:
@@ -620,6 +631,7 @@ def make(self,
620631
vtag=vtag,
621632
chksum=b'\x00\x00\x00\x00' if chksum is None else chksum,
622633
chunks=chunks_value,
634+
trailer=trailer,
623635
)
624636

625637
if chksum is None:
@@ -856,6 +868,7 @@ def _make_data(cls, data: 'Data_SCTP') -> 'dict[str, Any]': # type: ignore[over
856868
'vtag': data.vtag,
857869
'chksum': data.chksum,
858870
'chunks': data.chunks,
871+
'trailer': data.get('trailer', b''),
859872
}
860873

861874
def _get_payload(self) -> 'bytes':
@@ -918,10 +931,20 @@ def _read_sctp_chunks(self) -> 'Chunks':
918931
Returns:
919932
Extracted SCTP chunks.
920933
934+
Raises:
935+
ProtocolError: If a raw chunk given to :meth:`make` is not a whole
936+
chunk. Parsed, its octets would fall to the trailer rather than
937+
to the chunk list, so it is rejected, as it was before
938+
:issue:`1468`.
939+
921940
"""
922941
chunks = OrderedMultiDict() # type: Chunks
923942

924-
for schema in self.__header__.chunks:
943+
for schema in cast('list[Schema_Chunk | bytes]', self.__header__.chunks):
944+
if isinstance(schema, bytes):
945+
raise ProtocolError(f'{self.alias}: raw chunk {schema!r} runs past the end of '
946+
'the data, so it is not a whole chunk')
947+
925948
code = schema.type
926949
name = self._lookup_registry(self.__chunk__, code)
927950

‎tests/protocols/test_declared_length_overrun_unit.py‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -73,8 +73,9 @@ def _ipv6(proto: int, payload: bytes) -> bytes:
7373
bytes.fromhex('3b010000 00000000 010400000000 0103')),
7474
'HOPOPT PadN': ('pcapkit.protocols.internet.hopopt', 'HOPOPT', _ext6(bytes.fromhex('010700000000'))),
7575
'IPv6-Opts PadN': ('pcapkit.protocols.internet.ipv6_opts', 'IPv6_Opts', _ext6(bytes.fromhex('010700000000'))),
76-
'SCTP INIT parameter': ('pcapkit.protocols.transport.sctp', 'SCTP', _sctp(
77-
bytes.fromhex('01000020 00000001 00010000 00010001 00000001 000c0010 00050000'))),
76+
# An SCTP chunk declaring more octets than the packet holds is not here:
77+
# with no packet length field it is kept as the packet's trailer instead,
78+
# c.f. ``tests/protocols/transport/test_sctp_stray_octets_unit.py`` (#1468).
7879
# an unassigned kind declaring 12 octets, 8 present
7980
'TCP unassigned': ('pcapkit.protocols.transport.tcp', 'TCP', _tcp(bytes.fromhex('4f0caabb ccddeeff'))),
8081
# an unassigned option declaring 12 octets, 8 present in a complete
@@ -103,8 +104,6 @@ def _ipv6(proto: int, payload: bytes) -> bytes:
103104
'MH PadN': ('pcapkit.protocols.internet.ipv6', 'IPv6', _ipv6(135, OVERRUNS['MH PadN'][2])),
104105
'HOPOPT PadN': ('pcapkit.protocols.internet.ipv6', 'IPv6', _ipv6(0, OVERRUNS['HOPOPT PadN'][2])),
105106
'IPv6-Opts PadN': ('pcapkit.protocols.internet.ipv6', 'IPv6', _ipv6(60, OVERRUNS['IPv6-Opts PadN'][2])),
106-
'SCTP INIT parameter': ('pcapkit.protocols.internet.ipv4', 'IPv4',
107-
_ipv4(b'', ihl=5, proto=132, payload=OVERRUNS['SCTP INIT parameter'][2])),
108107
'TCP unassigned': ('pcapkit.protocols.internet.ipv4', 'IPv4',
109108
_ipv4(b'', ihl=5, proto=6, payload=OVERRUNS['TCP unassigned'][2])),
110109
'IPv4 unassigned': ('pcapkit.protocols.link.ethernet', 'Ethernet',
Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# -*- coding: utf-8 -*-
2+
"""Octets after the last whole SCTP chunk parse and survive a rebuild.
3+
4+
GitHub issue #1468: SCTP has no packet length field, so octets left after the
5+
last whole chunk -- fewer than a chunk header, or a chunk whose declared length
6+
runs past the data -- cannot be told apart from a chunk cut short. They made
7+
:class:`~pcapkit.protocols.transport.sctp.SCTP` raise ``ProtocolError: Field
8+
chunks has an option that runs past the end of the data``, so the packet had no
9+
round trip at all.
10+
11+
Per the #1458 ruling they are now recorded rather than rejected: the chunk list
12+
stops at the last whole chunk and the rest is kept as ``trailer``, as IPv4,
13+
IPv6 (#1209), L2TPv2 and OSPF (#1455) do. :meth:`make` writes a ``trailer``
14+
after the chunks.
15+
16+
Every case builds its own octets in memory and reads no capture. Classes are
17+
imported inside each test, after :func:`~tests._support.reimport_once_per_class`,
18+
c.f. ``tests/protocols/link/test_ethernet_mac_roundtrip_unit.py``.
19+
20+
"""
21+
22+
import struct
23+
import unittest
24+
import warnings
25+
26+
from tests._support import reimport_once_per_class
27+
28+
#: SCTP common header.
29+
COMMON = struct.pack('!HHII', 1, 2, 0, 0)
30+
#: COOKIE ACK chunk.
31+
COOKIE_ACK = struct.pack('!BBH', 11, 0, 4)
32+
#: DATA chunk carrying ``b'hi'`` under PPID 0, padded to eight octets.
33+
DATA = struct.pack('!BBHIHHI', 0, 3, 18, 1, 0, 0, 0) + b'hi' + bytes(2)
34+
#: INIT chunk declaring 32 octets, 28 present.
35+
INIT_CUT = bytes.fromhex('01000020 00000001 00010000 00010001 00000001 000c0010 00050000')
36+
37+
#: Packets with octets after the last whole chunk: (octets, chunk count, trailer).
38+
STRAY = {
39+
'1 octet': (COMMON + COOKIE_ACK + b'x', 1, b'x'),
40+
'3 octets': (COMMON + COOKIE_ACK + b'xyz', 1, b'xyz'),
41+
'4 octets': (COMMON + COOKIE_ACK + b'wxyz', 1, b'wxyz'),
42+
'4 zero octets': (COMMON + COOKIE_ACK + bytes(4), 1, bytes(4)),
43+
'5 octets': (COMMON + COOKIE_ACK + b'vwxyz', 1, b'vwxyz'),
44+
'after DATA': (COMMON + DATA + b'x', 1, b'x'),
45+
'chunk length past the data': (COMMON + COOKIE_ACK + struct.pack('!BBH', 11, 0, 40) + b'abcd', 1,
46+
struct.pack('!BBH', 11, 0, 40) + b'abcd'),
47+
'first chunk past the data': (COMMON + DATA[:14], 0, DATA[:14]),
48+
'chunk length below its header': (COMMON + COOKIE_ACK + struct.pack('!BBH', 11, 0, 2), 1,
49+
struct.pack('!BBH', 11, 0, 2)),
50+
'under a chunk header': (COMMON + b'ab', 0, b'ab'),
51+
# formerly rejected by tests/protocols/test_declared_length_overrun_unit.py
52+
'INIT past the data': (COMMON + INIT_CUT, 0, INIT_CUT),
53+
}
54+
55+
#: Packets that end on a chunk boundary.
56+
NO_STRAY = {
57+
'header only': COMMON,
58+
'COOKIE ACK': COMMON + COOKIE_ACK,
59+
'DATA then COOKIE ACK': COMMON + DATA + COOKIE_ACK,
60+
}
61+
62+
63+
class TestSCTPStrayOctets(unittest.TestCase):
64+
"""Pin the octets after the last whole SCTP chunk through ``from_data``."""
65+
66+
def setUp(self) -> None:
67+
reimport_once_per_class(self)
68+
69+
def test_packet_parses_and_rebuilds_byte_for_byte(self) -> None:
70+
from pcapkit.protocols.transport.sctp import SCTP
71+
72+
for name, (raw, count, trailer) in STRAY.items():
73+
with self.subTest(packet=name):
74+
parsed = SCTP(raw, len(raw))
75+
self.assertEqual(len(parsed.info.chunks), count)
76+
self.assertEqual(parsed.info.trailer, trailer)
77+
self.assertEqual(SCTP.from_data(parsed.info).data, raw)
78+
self.assertEqual(SCTP.from_data(parsed.info.to_dict()).data, raw)
79+
80+
def test_schema_keeps_the_trailer(self) -> None:
81+
from pcapkit.protocols.schema.transport.sctp import SCTP as Schema_SCTP
82+
83+
for name, (raw, count, trailer) in STRAY.items():
84+
with self.subTest(packet=name):
85+
schema = Schema_SCTP.unpack(raw)
86+
self.assertEqual(len(schema.chunks), count)
87+
self.assertEqual(schema.trailer, trailer)
88+
self.assertEqual(schema.pack(), raw)
89+
90+
def test_no_trailer_key_on_a_chunk_boundary(self) -> None:
91+
from pcapkit.protocols.transport.sctp import SCTP
92+
93+
for name, raw in NO_STRAY.items():
94+
with self.subTest(packet=name):
95+
parsed = SCTP(raw, len(raw))
96+
self.assertNotIn('trailer', parsed.info)
97+
self.assertEqual(SCTP.from_data(parsed.info).data, raw)
98+
99+
def test_data_chunk_still_dispatches(self) -> None:
100+
from pcapkit.protocols.transport.sctp import SCTP
101+
102+
raw = COMMON + DATA + b'x'
103+
parsed = SCTP(raw, len(raw))
104+
self.assertEqual(parsed.info.trailer, b'x')
105+
self.assertEqual(bytes(parsed.payload.data), b'hi')
106+
107+
def test_parent_rebuilds_byte_for_byte(self) -> None:
108+
from pcapkit.protocols.internet.ipv4 import IPv4
109+
from pcapkit.protocols.transport.sctp import SCTP
110+
111+
for name, (raw, _, trailer) in STRAY.items():
112+
with self.subTest(packet=name):
113+
frame = (struct.pack('!BBHHHBBH4s4s', 0x45, 0, 20 + len(raw), 1, 0, 64, 132, 0,
114+
bytes(4), bytes(4)) + raw)
115+
with warnings.catch_warnings():
116+
warnings.simplefilter('ignore')
117+
parsed = IPv4(frame, len(frame))
118+
self.assertIsInstance(parsed.payload, SCTP)
119+
self.assertEqual(parsed.payload.info.trailer, trailer)
120+
self.assertEqual(IPv4.from_data(parsed.info).data, frame)
121+
122+
def test_raw_chunk_that_is_not_whole_is_rejected(self) -> None:
123+
from pcapkit.protocols.transport.sctp import SCTP
124+
from pcapkit.utilities.exceptions import ProtocolError
125+
126+
with warnings.catch_warnings():
127+
warnings.simplefilter('ignore')
128+
with self.assertRaisesRegex(ProtocolError, r"raw chunk b'\\x01' runs past the end of the data"):
129+
SCTP(chunks=[b'\x01'])
130+
131+
def test_make_writes_the_trailer_under_the_checksum(self) -> None:
132+
from pcapkit.const.sctp.chunk import Chunk as Enum_Chunk
133+
from pcapkit.protocols.transport.sctp import SCTP
134+
135+
with warnings.catch_warnings():
136+
warnings.simplefilter('ignore')
137+
raw = SCTP(srcport=1, dstport=2, chunks=[(Enum_Chunk.Cookie_Acknowledgement, {})],
138+
trailer=b'xyz').data
139+
self.assertEqual(raw[12:], COOKIE_ACK + b'xyz')
140+
parsed = SCTP(raw, len(raw))
141+
self.assertEqual(parsed.info.trailer, b'xyz')
142+
self.assertTrue(parsed.checksum_valid)
143+
144+
145+
if __name__ == '__main__':
146+
unittest.main()

‎tests/protocols/transport/test_sctp_unit.py‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -854,12 +854,15 @@ def test_malformed_chunk_lengths_raise(self) -> None:
854854
'0002' '0003' '0005' '0005',
855855
# SHUTDOWN must be exactly 8.
856856
'shutdown': '07' '00' '0004' '0a0b0c10',
857-
# SHUTDOWN ACK must be exactly 4.
858-
'shutdown_ack': '08' '00' '0008',
857+
# SHUTDOWN ACK must be exactly 4. The schema reads only the
858+
# header, so the other four declared octets are a well-formed
859+
# chunk of the same type; with them absent, the chunk would run
860+
# past the data and be kept as the packet's trailer (#1468).
861+
'shutdown_ack': '08' '00' '0008' '08000004',
859862
# COOKIE ACK must be exactly 4.
860-
'cookie_ack': '0b' '00' '0008',
863+
'cookie_ack': '0b' '00' '0008' '0b000004',
861864
# SHUTDOWN COMPLETE must be exactly 4.
862-
'shutdown_complete': '0e' '00' '0008',
865+
'shutdown_complete': '0e' '00' '0008' '0e000004',
863866
}
864867
for name, body in cases.items():
865868
with self.subTest(chunk=name):

0 commit comments

Comments
 (0)