diff --git a/docs/source/pcapkit/protocols/transport/sctp.rst b/docs/source/pcapkit/protocols/transport/sctp.rst index 4bce600335..5c48ac7f05 100644 --- a/docs/source/pcapkit/protocols/transport/sctp.rst +++ b/docs/source/pcapkit/protocols/transport/sctp.rst @@ -323,6 +323,10 @@ Header Schemas :members: :show-inheritance: +.. autoclass:: pcapkit.protocols.schema.transport.sctp.PaddedOptionField + :members: + :show-inheritance: + .. autoclass:: pcapkit.protocols.schema.transport.sctp.ChunkListField :members: :show-inheritance: diff --git a/pcapkit/corekit/fields/collections.py b/pcapkit/corekit/fields/collections.py index d5702818e9..1a8ddb4ba1 100644 --- a/pcapkit/corekit/fields/collections.py +++ b/pcapkit/corekit/fields/collections.py @@ -449,7 +449,8 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'list FieldValueError: If an option consumes nothing from ``buffer``, since the loop below has then no way to get past it. ProtocolError: If an option that begins with octets present reads - past the end of the data. + past the end of the data, unless :meth:`_accepts_short_read` + accepts it. .. versionchanged:: 1.5.0 @@ -553,7 +554,7 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'list # unpack option using option schema data = schema.unpack(file, length, packet) # type: ignore[call-arg,misc,var-annotated] - if tracker.short and consumed > 0: + if tracker.short and consumed > 0 and not self._accepts_short_read(data): raise ProtocolError( f'Field {self.name} has an option that runs past the end of ' f'the data: {code!r} at offset {offset - start} of ' @@ -598,3 +599,21 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'list self._option_padding = length return temp + + def _accepts_short_read(self, option: '_TS') -> 'bool': # pylint: disable=unused-argument + """Whether an option that read past the end of the data may stand. + + Args: + option: Option just unpacked, which read short. + + Returns: + :data:`False`, so that :meth:`unpack` refuses the option + (:issue:`1325`): padding cut short may be content the option's own + length declares, as a ``PadN`` option's is. A list whose items' + lengths leave out their trailing padding may override this, as + :class:`~pcapkit.protocols.schema.transport.sctp.PaddedOptionField` + does; :meth:`Schema.pack ` + then writes back only the octets read. + + """ + return False diff --git a/pcapkit/protocols/schema/schema.py b/pcapkit/protocols/schema/schema.py index f62358227f..77ac45fef3 100644 --- a/pcapkit/protocols/schema/schema.py +++ b/pcapkit/protocols/schema/schema.py @@ -727,9 +727,10 @@ def unpack(cls, data: 'bytes | IO[bytes]', declares the size of the whole area it may read, but stops at the end-of-option-list marker and reports the unconsumed remainder through ``__option_padding__``. Since that remainder has not been - parsed, we rewind ``data`` by it, so that the fields which size - themselves from ``__option_padding__`` read the remainder itself - rather than the same number of octets from beyond it. + parsed, we rewind ``data`` by as much of it as was read, so that the + fields which size themselves from ``__option_padding__`` read the + remainder itself rather than the same number of octets from beyond + it, and record a cut inside it (:issue:`2685`). """ # force cast arg type since decorator changed their signatures @@ -793,7 +794,7 @@ def unpack(cls, data: 'bytes | IO[bytes]', # NOTE: bounded as the payload read above is (#1975). byte = data.read(min(length, sys.maxsize)) self.__buffer__[field.name] = byte - if not isinstance(field, ForwardMatchField): + if not isinstance(field, (ForwardMatchField, OptionField)): self._note_short_read(field.name, length, byte) value = field.unpack(byte, packet.copy()) @@ -837,15 +838,22 @@ def unpack(cls, data: 'bytes | IO[bytes]', data.seek(-len(byte), io.SEEK_CUR) self.__buffer__[field.name] = b'' elif isinstance(field, OptionField) and field.option_padding > 0: - # the option list ended before the declared field length was - # exhausted; give the unconsumed remainder back to ``data`` - # so that the following fields can read it - data.seek(-field.option_padding, io.SEEK_CUR) + # NOTE: The option list ended before the declared area did, and + # ``option_padding`` is the rest of that area; give back as much + # of it as was read, so that the following fields read it and + # record a cut inside it themselves (#2685). consumed = length - field.option_padding + kept = min(consumed, len(byte)) + if kept < len(byte): + data.seek(kept - len(byte), io.SEEK_CUR) - self.__buffer__[field.name] = byte[:consumed] + self.__buffer__[field.name] = byte[:kept] packet['__length__'] -= consumed + if kept == len(byte): + self._note_short_read(field.name, length, byte) else: + if isinstance(field, OptionField): + self._note_short_read(field.name, length, byte) packet['__length__'] -= length if packet['__length__'] < 0: diff --git a/pcapkit/protocols/schema/transport/sctp.py b/pcapkit/protocols/schema/transport/sctp.py index fa4f908b81..cbf08d395f 100644 --- a/pcapkit/protocols/schema/transport/sctp.py +++ b/pcapkit/protocols/schema/transport/sctp.py @@ -3,7 +3,7 @@ """header schema for stream control transmission protocol""" import io -from typing import TYPE_CHECKING, cast +from typing import TYPE_CHECKING from pcapkit.const.reg.apptype import AppType as Enum_AppType from pcapkit.const.reg.apptype import TransportProtocol as Enum_TransportProtocol @@ -49,9 +49,7 @@ if TYPE_CHECKING: from ipaddress import IPv4Address, IPv6Address - from typing import IO, Any, Callable, Optional - - from typing_extensions import Self + from typing import IO, Any, Callable from pcapkit.protocols.protocol import ProtocolBase @@ -95,13 +93,15 @@ def padding_length(pkt: 'dict[str, Any]') -> 'int': pkt: Packet data. Returns: - Number of padding bytes, clamped to the number of bytes left in the - enclosing structure, so that a final chunk captured without (all of) - its padding still parses, although :rfc:`9260#section-3.2` has the - sender pad every chunk. When packing, it is clamped as well - to the ``__padding__`` width :func:`pre_pack_padding` hands over, so a - final chunk captured without (all of) its padding rebuilds without it - (:issue:`1474`). + Number of padding bytes the ``length`` calls for. A final chunk captured + without (all of) its padding, although :rfc:`9260#section-3.2` has the + sender pad every chunk, reads short, which :meth:`Schema.unpack + ` records so that + :meth:`Schema.pack ` writes + back only the octets read, and :class:`PaddedOptionField` lets it parse + (:issue:`2680`). When packing, it is clamped to the ``__padding__`` + width :func:`pre_pack_padding` hands over, so such a chunk rebuilt from + its data model is short of its padding as well (:issue:`1474`). """ length = pkt.get('length') or 0 @@ -110,11 +110,7 @@ def padding_length(pkt: 'dict[str, Any]') -> 'int': width = pkt.get('__padding__') if isinstance(width, int) and width >= 0: padding = min(padding, width) - - remaining = pkt.get('__length__') - if not isinstance(remaining, int) or remaining < 0: - return padding - return min(padding, remaining) + return padding def pre_pack_padding(schema: 'Schema', packet: 'dict[str, Any]') -> 'None': @@ -194,7 +190,8 @@ def nested_length(base: 'int') -> 'Callable[[dict[str, Any]], int]': ``__option_padding__``. The last chunk of a packet may omit that padding altogether, so the chunks wrap this callback in :func:`bounded`: the span then ends with the data, and the final parameter or cause reads only the - padding that is there (:issue:`1479`). + padding that is there (:issue:`1479`), recording the cut + (:issue:`2680`). * On construction, a separate padding field could not compute its own size: :meth:`Schema.pack ` passes one shared ``packet`` mapping down into the nested schemas, and each @@ -212,6 +209,39 @@ def callback(pkt: 'dict[str, Any]') -> 'int': return callback +class PaddedOptionField(OptionField): + """List of chunks, parameters or error causes, the last of which may be cut + inside its trailing padding. + + :meth:`OptionField.unpack ` + refuses an item that reads past the end of the data (:issue:`1325`). The + last chunk of a packet may lack (some of) its padding, though, and so may + the last parameter or cause of that chunk, which share it + (:func:`nested_length`). An item's ``length`` leaves its padding out and + the receiver ignores it (:rfc:`9260#section-3.2`), and + :class:`ChunkListField` hands on only chunks whose ``length`` octets are + all present, so an item short of its padding alone is cut rather than + overrun. It records that as a short read of its ``padding``, and is kept + (:issue:`2680`). + + """ + + def _accepts_short_read(self, option: 'Schema') -> 'bool': + """Whether ``option`` read short inside its trailing padding alone. + + Args: + option: Item just unpacked, which read short. + + Returns: + Whether the short read :meth:`Schema.unpack + ` recorded is of the + item's ``padding``. + + """ + record = option.__dict__.get('__short_read__') + return record is not None and record[0] == 'padding' + + class ErrorCause(EnumSchema[Enum_CauseCode]): """Header schema for SCTP error causes.""" @@ -643,7 +673,7 @@ class INITChunk(Chunk, code=Enum_Chunk.Initiation): init_tsn: 'int' = UInt32Field() #: Optional and variable-length parameters, including the chunk's own #: trailing padding; see :func:`nested_length`. - parameters: 'list[Parameter]' = OptionField( + parameters: 'list[Parameter]' = PaddedOptionField( length=bounded(nested_length(20)), base_schema=Parameter, type_name='type', @@ -673,7 +703,7 @@ class INITACKChunk(Chunk, code=Enum_Chunk.Initiation_Acknowledgement): init_tsn: 'int' = UInt32Field() #: Optional and variable-length parameters, including the chunk's own #: trailing padding; see :func:`nested_length`. - parameters: 'list[Parameter]' = OptionField( + parameters: 'list[Parameter]' = PaddedOptionField( length=bounded(nested_length(20)), base_schema=Parameter, type_name='type', @@ -728,7 +758,7 @@ class HeartbeatChunk(Chunk, code=Enum_Chunk.Heartbeat_Request): #: Heartbeat information parameters, including the chunk's own trailing #: padding; see :func:`nested_length`. - parameters: 'list[Parameter]' = OptionField( + parameters: 'list[Parameter]' = PaddedOptionField( length=bounded(nested_length(4)), base_schema=Parameter, type_name='type', @@ -746,7 +776,7 @@ class HeartbeatACKChunk(Chunk, code=Enum_Chunk.Heartbeat_Acknowledgement): #: Heartbeat information parameters, including the chunk's own trailing #: padding; see :func:`nested_length`. - parameters: 'list[Parameter]' = OptionField( + parameters: 'list[Parameter]' = PaddedOptionField( length=bounded(nested_length(4)), base_schema=Parameter, type_name='type', @@ -769,7 +799,7 @@ class AbortChunk(Chunk, code=Enum_Chunk.Abort): }) #: Zero or more error causes, including the chunk's own trailing padding; #: see :func:`nested_length`. - error: 'list[ErrorCause]' = OptionField( + error: 'list[ErrorCause]' = PaddedOptionField( length=bounded(nested_length(4)), base_schema=ErrorCause, type_name='code', @@ -812,7 +842,7 @@ class ErrorChunk(Chunk, code=Enum_Chunk.Operation_Error): #: One or more error causes, including the chunk's own trailing padding; #: see :func:`nested_length`. - error: 'list[ErrorCause]' = OptionField( + error: 'list[ErrorCause]' = PaddedOptionField( length=bounded(nested_length(4)), base_schema=ErrorCause, type_name='code', @@ -874,7 +904,7 @@ def whole_chunks_length(data: 'bytes') -> 'int': Returns: Number of octets up to the end of the last chunk whose declared ``length`` octets are all present, with as much of its padding as there - is, see :func:`padding_length`. A ``length`` below the four-octet chunk + is, see :class:`PaddedOptionField`. A ``length`` below the four-octet chunk header (:rfc:`9260#section-3.2`) delimits nothing, so the run stops there too; four zero octets would otherwise read as a DATA chunk. @@ -889,7 +919,7 @@ def whole_chunks_length(data: 'bytes') -> 'int': return end -class ChunkListField(OptionField): +class ChunkListField(PaddedOptionField): """Chunk list that stops at the last whole chunk. SCTP has no packet length field, so octets after the last whole chunk -- @@ -897,9 +927,12 @@ class ChunkListField(OptionField): cannot be told apart from a chunk cut short. They are not parsed but reported as option padding, which :meth:`Schema.unpack ` hands back to the stream for - :attr:`SCTP.trailer` to keep as captured (:issue:`1468`). The area reaches no - further than the octets present, as :meth:`SCTP.unpack` sizes it - (:issue:`2673`). + :attr:`SCTP.trailer` to keep as captured (:issue:`1468`). The padding is the + rest of the area declared, as for any + :class:`~pcapkit.corekit.fields.collections.OptionField`, so an area the data + ends inside hands back only the octets present (:issue:`2685`). The last + whole chunk may be cut inside its padding, and is kept as + :class:`PaddedOptionField` keeps one (:issue:`2680`). """ @@ -927,7 +960,7 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'list chunks = super().unpack(data[:whole], packet) finally: self._length = area - self._option_padding += len(data) - whole + self._option_padding += max(area, 0) - whole return chunks @@ -966,49 +999,6 @@ class SCTP(Schema): #: and :attr:`IPv4.trailer `. trailer: 'bytes' = PayloadField(default=b'') - @classmethod - def unpack(cls, data: 'bytes | IO[bytes]', # type: ignore[override] - length: 'Optional[int]' = None, packet: 'Optional[dict[str, Any]]' = None) -> 'Self': - """Unpack :obj:`bytes` into :class:`SCTP`, no further than the octets present. - - Args: - data: Packed data. - length: Length of data, as the enclosing layer declares it. - packet: Unpacked data. - - Returns: - Unpacked data as :class:`SCTP`. - - SCTP has no packet length field (:rfc:`9260#section-3`), so a ``length`` - past the octets present, as an IPv4 Total Length the capture cut short of - declares, is cut to them. Sized past them, :attr:`chunks` would record the - data as ending inside it while :class:`ChunkListField` hands the octets - after the last whole chunk to :attr:`trailer`, so :meth:`Schema.pack - ` would drop them and - ``bytes(schema)`` count them twice (:issue:`2673`). - - When no octet follows the last whole chunk, which the capture may have cut - inside its padding, the data does end inside :attr:`chunks`, so the cut is - recorded there as :meth:`Schema.unpack - ` records a short read, and - packing writes back only the octets read. - - """ - cut = False - if length is not None: - if isinstance(data, bytes): - present = len(data) - else: - start = data.tell() - present = data.seek(0, io.SEEK_END) - start - data.seek(start, io.SEEK_SET) - cut, length = length > present, min(length, present) - - schema = cast('Self', super().unpack(data, length, packet)) # type: ignore[call-arg,misc] - if cut and not schema.__buffer__['trailer'] and '__short_read__' not in schema.__dict__: - schema.__dict__['__short_read__'] = ('chunks', len(schema.__buffer__['chunks'])) - return schema - if TYPE_CHECKING: def __init__(self, srcport: 'Enum_AppType | int', dstport: 'Enum_AppType | int', vtag: 'int', chksum: 'bytes', diff --git a/tests/protocols/schema/test_option_area_cut_2685_unit.py b/tests/protocols/schema/test_option_area_cut_2685_unit.py new file mode 100644 index 0000000000..be60bc67c4 --- /dev/null +++ b/tests/protocols/schema/test_option_area_cut_2685_unit.py @@ -0,0 +1,175 @@ +# -*- coding: utf-8 -*- +"""An option area the data ends inside hands back only the octets present (#2685). + +``Schema.unpack`` gave back the rest of an ``OptionField``'s declared area by rewinding +the stream the full width of ``option_padding``, and kept ``length - option_padding`` +octets of the area, even when the read had come back short. It also charged the cut to +the option field before the field had parsed, so that ``_cut_short_read`` then emptied +the fields after it. A TCP header of data offset 8, its options ``NOP NOP EOL`` then +zeros, cut 25 octets in with the whole 40 declared, rewound into its own checksum: +``bytes(schema)`` gave 32 octets and ``schema.pack()`` 23. + +#2679 had worked round the same defect for SCTP alone, in an ``SCTP.unpack`` override +that measured the stream, and so could not read one that does not seek. + +Every case builds its own octets. + +""" + +import io +import struct +import unittest +import warnings + +from tests._support import reimport_once_per_class + +#: TCP header of data offset 8 (RFC 9293, section 3.1): options NOP, NOP and +#: End of Option List, then nine octets of zero padding, then eight of payload. +TCP_WHOLE = (struct.pack('!HHIIBBHHH', 1, 2, 3, 4, 8 << 4, 0x10, 0xffff, 0, 0) + + bytes([1, 1, 0]) + bytes(9) + b'abcdefgh') +#: Where the option area's padding starts and ends. +TCP_PADDING = (23, 32) + +#: SCTP common header (RFC 9260, section 3.1), a DATA chunk of five octets of user +#: data with its three pad octets (section 3.3.1), then a COOKIE ACK (section 3.3.12). +SCTP_WHOLE = (struct.pack('!HHII', 5000, 5001, 1, 0) + + struct.pack('!BBHIHHI', 0, 3, 21, 7, 1, 2, 0) + b'abcde' + bytes(3) + + struct.pack('!BBH', 11, 0, 4)) + + +def _over_reporting_schemas(): # type: ignore[no-untyped-def] + """An option list whose type-1 option reports four octets having read two. + + Its ``post_process`` returns a schema it packs itself, as an option may + return a schema other than the one read. No shipped option does this, so + the schemas are built here. + + """ + import collections + + from pcapkit.corekit.fields.collections import OptionField + from pcapkit.corekit.fields.numbers import UInt8Field + from pcapkit.corekit.fields.strings import BytesField + from pcapkit.protocols.schema.schema import Schema + + class Wide(Schema): + type: 'int' = UInt8Field() + value: 'bytes' = BytesField(length=3) + + class Option(Schema): + type: 'int' = UInt8Field() + value: 'bytes' = BytesField(length=lambda pkt: 1 if pkt['type'] else 0) + + def post_process(self, packet): # type: ignore[no-untyped-def] + if not self.type: + return self + wide = Wide(type=self.type, value=self.value + bytes(2)) + wide.pack() + return wide + + registry = collections.defaultdict(lambda: Option) + + def outer(area: int) -> type: + class Outer(Schema): + options: 'list[Option]' = OptionField(length=lambda pkt: area, base_schema=Option, + type_name='type', registry=registry, eool=0) + return Outer + + return outer + + +class _Unseekable(io.RawIOBase): + """A readable stream that cannot seek, as a pipe or a socket is.""" + + def __init__(self, data: bytes) -> None: + super().__init__() + self._data = data + self._offset = 0 + + def readable(self) -> bool: + return True + + def seekable(self) -> bool: + return False + + def readinto(self, buffer: 'bytearray') -> int: # type: ignore[override] + chunk = self._data[self._offset:self._offset + len(buffer)] + buffer[:len(chunk)] = chunk + self._offset += len(chunk) + return len(chunk) + + +class OptionAreaCutTests(unittest.TestCase): + """Schemas whose option area the data ends inside, unpacked with a longer length.""" + + def setUp(self) -> None: + reimport_once_per_class(self) + catcher = warnings.catch_warnings() + catcher.__enter__() + self.addCleanup(catcher.__exit__, None, None, None) + warnings.simplefilter('ignore') + + def test_tcp_cut_at_every_offset_packs_as_captured(self) -> None: + from pcapkit.protocols.schema.transport.tcp import TCP + + for keep in range(20, len(TCP_WHOLE) + 1): + raw = TCP_WHOLE[:keep] + for via in ('bytes', 'stream'): + with self.subTest(keep=keep, via=via): + schema = TCP.unpack(raw if via == 'bytes' else io.BytesIO(raw), len(TCP_WHOLE)) + self.assertEqual(bytes(schema), raw) + self.assertEqual(schema.pack(), raw) + self.assertEqual(schema.__buffer__['options'], raw[20:TCP_PADDING[0]]) + if keep <= TCP_PADDING[0]: + # nothing of the area is given back, so the cut is the options' own + self.assertEqual(schema.__dict__['__short_read__'], ('options', keep - 20)) + elif keep < TCP_PADDING[1]: + # the options are whole, and the data ends in the padding after them + self.assertEqual(schema.__dict__['__short_read__'], ('padding', keep - TCP_PADDING[0])) + else: + self.assertNotIn('__short_read__', schema.__dict__) + + def test_tcp_cut_inside_the_padding_leaves_the_header_alone(self) -> None: + from pcapkit.protocols.schema.transport.tcp import TCP + + raw = TCP_WHOLE[:25] + schema = TCP.unpack(raw, len(TCP_WHOLE)) + self.assertEqual(schema.checksum, b'\x00\x00') + self.assertEqual(schema.padding, bytes(2)) + self.assertEqual(schema.payload, b'') + + def test_an_option_reporting_more_than_it_read_still_records_the_cut(self) -> None: + # the options' reported size, four octets, passes the two read: an area of + # 8 gives back none of its remainder, and one of 4 has none to give back + outer = _over_reporting_schemas() + raw = b'\x01\x02' + for area in (8, 4): + for via in ('bytes', 'stream'): + with self.subTest(area=area, via=via): + data = raw if via == 'bytes' else io.BytesIO(raw) + schema = outer(area).unpack(data, area) + if via == 'stream': + self.assertEqual(data.tell(), len(raw)) # type: ignore[union-attr] + self.assertEqual(schema.__buffer__['options'], raw) + self.assertEqual(schema.__dict__['__short_read__'], ('options', len(raw))) + + def test_sctp_on_a_stream_that_cannot_seek(self) -> None: + from pcapkit.protocols.schema.transport.sctp import SCTP + + data_end = 12 + 24 + cases = { + 'whole': (SCTP_WHOLE, len(SCTP_WHOLE)), + # one of the DATA chunk's three pad octets, then nothing + 'padding, own length': (SCTP_WHOLE[:data_end - 2], data_end - 2), + 'padding, whole length declared': (SCTP_WHOLE[:data_end - 2], len(SCTP_WHOLE)), + 'after a whole chunk, whole length declared': (SCTP_WHOLE[:data_end], len(SCTP_WHOLE)), + } + for name, (raw, given) in cases.items(): + with self.subTest(case=name): + schema = SCTP.unpack(io.BufferedReader(_Unseekable(raw)), given) + self.assertEqual(bytes(schema), raw) + self.assertEqual(schema.pack(), raw) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/protocols/transport/test_sctp_schema_padding_2680_unit.py b/tests/protocols/transport/test_sctp_schema_padding_2680_unit.py new file mode 100644 index 0000000000..09d24dfe4c --- /dev/null +++ b/tests/protocols/transport/test_sctp_schema_padding_2680_unit.py @@ -0,0 +1,325 @@ +# -*- coding: utf-8 -*- +"""An SCTP schema cut inside the padding of its last item packs back as captured (#2680). + +``Schema_SCTP.unpack(raw)`` and ``unpack(raw, len(raw))`` read a final chunk cut inside +its padding, and packed it back at full width: a DATA chunk of Length 21 cut after one of +its three pad octets gave 34 octets in and 36 out, and ``DATAChunk.unpack`` alone 22 in +and 24 out. ``padding_length`` capped the padding at the octets left, so the read never +came up short and ``Schema.unpack`` recorded nothing for ``Schema.pack`` to cut back to. + +Each final chunk, parameter or cause below has a Length that leaves one, two or three pad +octets to follow (RFC 9260, section 3.2), and each is cut at every offset inside that +padding. Every case builds its own octets. + +""" + +import io +import struct +import unittest +import warnings + +from tests._support import reimport_once_per_class +from tests.foundation import _roundtrip as wire + +#: Test tier (#1958): a sweep that cuts each packet at every offset of its padding. +__tier__ = 'LATEST' + +#: SCTP common header from port 5000 to 5001 (RFC 9260, section 3.1), its checksum +#: zero, which nothing here checks. +COMMON = struct.pack('!HHII', 5000, 5001, 0x11223344, 0) +#: DATA chunk TSN, stream identifier, stream sequence number and PPID (RFC 9260, +#: section 3.3.1). +DATA_HEAD = struct.pack('!IHHI', 7, 1, 2, 0) +#: INIT and INIT ACK fixed part (RFC 9260, sections 3.3.2 and 3.3.3), then a whole +#: IPv4 Address parameter. +INIT_HEAD = struct.pack('!IIHHI', 0xaabbccdd, 65536, 10, 10, 1) + struct.pack('!HH4s', 5, 8, b'\xc0\x00\x02\x01') +#: A chunk type with no schema of its own (RFC 9260, section 3.2): upper bits 00. +UNKNOWN_CHUNK = 0x3f +#: A parameter type and a cause code with no schema of their own. +UNKNOWN_TLV = 0x3fff + + +def _tlv(code: int, value: bytes) -> bytes: + """A parameter or error cause, unpadded, its Length excluding the padding (section 3.2.1).""" + return struct.pack('!HH', code, 4 + len(value)) + value + + +def _chunk(code: int, flags: int, value: bytes) -> bytes: + """A chunk, unpadded, its Length excluding the padding and the last parameter's (section 3.2).""" + return struct.pack('!BBH', code, flags, 4 + len(value)) + value + + +def _pad(octets: bytes) -> bytes: + """``octets`` with the zeros that round them up to four (section 3.2).""" + return octets + bytes(-len(octets) % 4) + + +def _items(width: int) -> 'dict[str, tuple[str, int, bytes]]': + """Parameters and causes whose Length leaves ``width`` pad octets, unpadded, by kind. + + Each is the base schema's name, its code and its octets. + + """ + size = 4 - width + return { + # Host Name Address (11), its name ending in a NUL (section 3.3.2.1) + 'host-name': ('Parameter', 11, _tlv(11, b'h' * (size - 1) + b'\x00')), + # State Cookie (7) + 'state-cookie': ('Parameter', 7, _tlv(7, b's' * size)), + # Heartbeat Info (1) + 'heartbeat-info': ('Parameter', 1, _tlv(1, b'i' * size)), + 'unknown-parameter': ('Parameter', UNKNOWN_TLV, _tlv(UNKNOWN_TLV, b'p' * size)), + # Unrecognized Chunk Type (6) + 'unrecognized-chunk': ('ErrorCause', 6, _tlv(6, b'e' * size)), + # User-Initiated Abort (12) + 'user-abort': ('ErrorCause', 12, _tlv(12, b'a' * size)), + 'unknown-cause': ('ErrorCause', UNKNOWN_TLV, _tlv(UNKNOWN_TLV, b'u' * size)), + } + + +def _final(width: int) -> 'dict[str, bytes]': + """Final chunks whose Length leaves ``width`` pad octets, unpadded, by kind.""" + size, items = 4 - width, _items(width) + return { + 'data': _chunk(0, 0x03, DATA_HEAD + b'd' * size), + 'cookie-echo': _chunk(10, 0, b'c' * size), + 'unknown': _chunk(UNKNOWN_CHUNK, 0, b'x' * size), + 'init': _chunk(1, 0, INIT_HEAD + items['host-name'][2]), + 'init-ack': _chunk(2, 0, INIT_HEAD + items['state-cookie'][2]), + 'heartbeat': _chunk(4, 0, items['heartbeat-info'][2]), + 'heartbeat-ack': _chunk(5, 0, items['unknown-parameter'][2]), + 'error': _chunk(9, 0, items['unrecognized-chunk'][2]), + 'abort': _chunk(6, 0x01, items['user-abort'][2]), + } + + +#: Whole chunks ahead of the final one in a multi-chunk packet: a SACK (section +#: 3.3.4) with no gap blocks, then a DATA chunk with its three pad octets. +LEADING = _chunk(3, 0, struct.pack('!IIHH', 9, 4096, 0, 0)) + _pad(_chunk(0, 0x03, DATA_HEAD + b'x')) + + +def _cut(whole: bytes, width: int) -> 'list[tuple[int, bytes]]': + """Pad octets kept and octets, for every cut of ``whole`` inside its last ``width``.""" + return [(kept, whole[:len(whole) - width + kept]) for kept in range(width)] + + +def _cases() -> 'list[tuple[str, int, int, bytes]]': + """Name, padding width, pad octets kept and octets, for every cut packet.""" + return [(f'{shape}-{kind}', width, kept, raw) + for width in (1, 2, 3) for kind, chunk in _final(width).items() + for shape, ahead in (('single', b''), ('multi', LEADING)) + for kept, raw in _cut(COMMON + ahead + _pad(chunk), width)] + + +def _wholes() -> 'list[tuple[str, int, bytes]]': + """Name, padding width and octets of every packet above, with all its padding.""" + return [(f'{shape}-{kind}', width, COMMON + ahead + _pad(chunk)) + for width in (1, 2, 3) for kind, chunk in _final(width).items() + for shape, ahead in (('single', b''), ('multi', LEADING))] + + +def _last_item(schema: 'object') -> 'object': + """The item ``schema``'s data ends in: its last chunk, or that chunk's last parameter or cause.""" + item = schema.chunks[-1] # type: ignore[attr-defined] + for name in ('parameters', 'error'): + nested = item.__dict__.get(name) + if nested: + return nested[-1] + return item + + +class SCTPSchemaPaddingCutTests(unittest.TestCase): + """SCTP packets cut inside the padding of their final chunk, at the schema level.""" + + def setUp(self) -> None: + reimport_once_per_class(self) + catcher = warnings.catch_warnings() + catcher.__enter__() + self.addCleanup(catcher.__exit__, None, None, None) + warnings.simplefilter('ignore') + + def assert_packs_as_captured(self, schema: 'object', raw: bytes, kept: int) -> None: + """``schema`` records the cut in its last item's padding and packs ``raw`` back.""" + from pcapkit.protocols.schema.transport.sctp import SCTP + + assert isinstance(schema, SCTP) + self.assertEqual(_last_item(schema).__dict__['__short_read__'], ('padding', kept)) + self.assertEqual(schema.trailer, b'') + self.assertEqual(bytes(schema), raw) + self.assertEqual(schema.pack(), raw) + self.assertEqual(SCTP.from_dict(schema.to_dict()).pack(), raw) + + # a field ahead of the cut, changed, still packs no further than the octets read + schema.vtag = 0x55667788 + self.assertEqual(schema.pack(), raw[:4] + b'\x55\x66\x77\x88' + raw[8:]) + + def test_bytes_cut_inside_the_padding(self) -> None: + from pcapkit.protocols.schema.transport.sctp import SCTP + + for name, width, kept, raw in _cases(): + for given in (None, len(raw)): + with self.subTest(case=name, width=width, kept=kept, length=given): + schema = SCTP.unpack(raw, given) + # every chunk parsed, the last one's Length short of a multiple of + # four by its padding (RFC 9260, section 3.2) + self.assertEqual(len(schema.chunks), 3 if name.startswith('multi') else 1) + self.assertEqual(-schema.chunks[-1].length % 4, width) + self.assert_packs_as_captured(schema, raw, kept) + + def test_stream_cut_inside_the_padding(self) -> None: + from pcapkit.protocols.schema.transport.sctp import SCTP + + for name, width, kept, raw in _cases(): + with self.subTest(case=name, width=width, kept=kept, length=None): + # read from the middle of a stream, to its end + stream = io.BytesIO(b'\xff' * 3 + raw) + stream.seek(3) + schema = SCTP.unpack(stream) + self.assertEqual(stream.tell(), 3 + len(raw)) + self.assert_packs_as_captured(schema, raw, kept) + + with self.subTest(case=name, width=width, kept=kept, length=len(raw)): + # the length given stops short of the octets after it + stream = io.BytesIO(b'\xff' * 3 + raw + b'\xee' * 4) + stream.seek(3) + schema = SCTP.unpack(stream, len(raw)) + self.assertEqual(stream.tell(), 3 + len(raw)) + self.assert_packs_as_captured(schema, raw, kept) + + def test_chunk_schema_on_its_own(self) -> None: + from pcapkit.const.sctp.chunk import Chunk as Enum_Chunk + from pcapkit.protocols.schema.transport.sctp import Chunk + + for width in (1, 2, 3): + for kind, chunk in _final(width).items(): + schema_cls = Chunk.registry[Enum_Chunk.get(chunk[0])] + for kept, raw in _cut(_pad(chunk), width): + for via in ('bytes', 'stream'): + with self.subTest(case=kind, schema=schema_cls.__name__, width=width, + kept=kept, via=via): + schema = schema_cls.unpack(raw if via == 'bytes' else io.BytesIO(raw)) + nested = schema.__dict__.get('parameters') or schema.__dict__.get('error') + item = nested[-1] if nested else schema + self.assertEqual(item.__dict__['__short_read__'], ('padding', kept)) + self.assertEqual(bytes(schema), raw) + self.assertEqual(schema.pack(), raw) + + def test_parameter_and_cause_schemas_on_their_own(self) -> None: + from pcapkit.const.sctp.cause_code import CauseCode as Enum_CauseCode + from pcapkit.const.sctp.parameter import Parameter as Enum_Parameter + from pcapkit.protocols.schema.transport.sctp import ErrorCause, Parameter + + bases = {'Parameter': (Parameter, Enum_Parameter), 'ErrorCause': (ErrorCause, Enum_CauseCode)} + for width in (1, 2, 3): + for kind, (base, code, item) in _items(width).items(): + registry, enum = bases[base] + schema_cls = registry.registry[enum.get(code)] + for kept, raw in _cut(_pad(item), width): + with self.subTest(case=kind, schema=schema_cls.__name__, width=width, kept=kept): + schema = schema_cls.unpack(raw) + self.assertEqual(schema.__dict__['__short_read__'], ('padding', kept)) + self.assertEqual(schema.padding, raw[len(item):]) + self.assertEqual(bytes(schema), raw) + self.assertEqual(schema.pack(), raw) + + def test_parsed_header_packs_as_captured(self) -> None: + # the protocol's own info is as before: the cut is the chunk's, not the packet's + from pcapkit.protocols.transport.sctp import SCTP + + for name, width, kept, raw in _cases(): + with self.subTest(case=name, width=width, kept=kept): + sctp = SCTP(raw, len(raw)) + self.assertNotIn('__short_read__', sctp.info) + self.assertEqual(sctp.data, raw) + self.assertEqual(bytes(sctp.__header__), raw) + self.assertEqual(sctp.__header__.pack(), raw) + self.assertEqual(SCTP.from_data(sctp.info).data, raw) + self.assertEqual(SCTP.from_data(sctp.info.to_dict()).data, raw) + + def test_envelope_declaring_the_octets(self) -> None: + # an IPv4 Total Length or IPv6 Payload Length that ends where the capture does + from pcapkit.protocols.internet.ipv4 import IPv4 + from pcapkit.protocols.internet.ipv6 import IPv6 + from pcapkit.protocols.transport.sctp import SCTP + + for name, width, kept, raw in _cases(): + for cls, packet in ((IPv4, wire.ipv4(raw, proto=132)), (IPv6, wire.ipv6(raw, nxt=132))): + with self.subTest(case=name, width=width, kept=kept, via=cls.__name__): + outer = cls(packet, len(packet)) + sctp = outer.payload + self.assertIsInstance(sctp, SCTP) + self.assertEqual(sctp.__header__.pack(), raw) + self.assertEqual(cls.from_data(outer.info).data, packet) + self.assertEqual(cls.from_data(outer.info.to_dict()).data, packet) + + def test_an_item_running_past_its_chunk_is_refused(self) -> None: + # only a cut inside the padding is kept: a Length past the chunk is an overrun (#1325) + from pcapkit.protocols.schema.transport.sctp import SCTP, ErrorChunk, INITChunk + from pcapkit.utilities.exceptions import ProtocolError + + # a Host Name Address parameter and an Unrecognized Chunk Type cause each + # declaring 12 octets, of which their chunk holds 8 + chunks = { + 'init': (INITChunk, _chunk(1, 0, INIT_HEAD + struct.pack('!HH', 11, 12) + b'hhhh')), + 'error': (ErrorChunk, _chunk(9, 0, struct.pack('!HH', 6, 12) + b'eeee')), + } + for name, (schema_cls, chunk) in chunks.items(): + self.assertEqual(len(chunk) % 4, 0) + for via, call in (('chunk', lambda: schema_cls.unpack(chunk)), + ('packet', lambda: SCTP.unpack(COMMON + chunk)), + ('bundled', lambda: SCTP.unpack(COMMON + chunk + _chunk(11, 0, b'')))): + with self.subTest(case=name, via=via): + with self.assertRaisesRegex(ProtocolError, 'runs past the end of the data'): + call() + + def test_a_header_cut_keeps_its_own_record(self) -> None: + # a longer declared length must not displace the field the data ended inside + from pcapkit.protocols.schema.transport.sctp import SCTP + + names = ('srcport', 'dstport', 'vtag', 'chksum') + widths = (2, 2, 4, 4) + for keep in range(1, 12): + raw = COMMON[:keep] + field, offset = next((name, keep - start) for name, start, width in zip( + names, (0, 2, 4, 8), widths) if keep < start + width) + for given in (None, keep, 40): + with self.subTest(keep=keep, length=given): + schema = SCTP.unpack(raw, given) + self.assertEqual(schema.__dict__['__short_read__'], (field, offset)) + self.assertEqual(bytes(schema), raw) + self.assertEqual(schema.pack(), raw) + + def test_whole_padding_is_the_control(self) -> None: + from pcapkit.protocols.schema.transport.sctp import SCTP + from pcapkit.protocols.transport.sctp import SCTP as Protocol_SCTP + + for name, width, whole in _wholes(): + for given in (None, len(whole)): + with self.subTest(case=name, width=width, length=given): + schema = SCTP.unpack(whole, given) + self.assertNotIn('__short_read__', schema.__dict__) + self.assertNotIn('__short_read__', _last_item(schema).__dict__) + self.assertEqual(schema.trailer, b'') + self.assertEqual(schema.pack(), whole) + + with self.subTest(case=name, width=width, via='protocol'): + self.assertNotIn('__short_read__', Protocol_SCTP(whole, len(whole)).info) + + def test_issue_2680_repro(self) -> None: + from pcapkit.protocols.schema.transport.sctp import SCTP, DATAChunk + + data = struct.pack('!BBHIHHI', 0, 3, 21, 7, 1, 2, 0) + b'abcde' + raw = (struct.pack('!HHI', 5000, 5001, 1) + bytes(4) + data + bytes(3))[:34] + for given in (None, 34): + with self.subTest(length=given): + schema = SCTP.unpack(raw, given) + self.assertEqual(len(bytes(schema)), 34) + self.assertEqual(len(schema.pack()), 34) + + chunk = DATAChunk.unpack(raw[12:]) + self.assertEqual(chunk.__dict__['__short_read__'], ('padding', 1)) + self.assertEqual(len(chunk.pack()), 22) + + +if __name__ == '__main__': + unittest.main()