Skip to content

Commit ad7cd10

Browse files
committed
fix(protocols)!: parse a malformed IPv6 extension header as Raw (#2477)
RFC 8200 §4 has a node discard such a packet, so the walk stops at it. - IPv6._import_next_layer: drop the IPv6_Ext fallback and __generic_ext_codes__. - The Raw the walk stopped on is the upper layer, so its error is logged once. - IPv6_Ext keeps Shim6, its only direct dispatch. - IPv6_Ext.error and read(error=) are no longer filled; see info.error on Raw. - Tests pin Raw for malformed and truncated HOPOPT/Routing/Opts/MH/HIP/AH. - mh.py docstrings and the round-trip tests no longer describe the fallback.
1 parent 798a878 commit ad7cd10

17 files changed

Lines changed: 341 additions & 360 deletions

‎docs/source/contributing/conventions/extension-header-subclassing.rst‎

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -158,22 +158,18 @@ carries the same extension-mode contract as its siblings.
158158
inside the *encrypted* trailer, so with no key material there is nothing to continue
159159
on: ESP's own data model reports ``next`` as :obj:`None`, and
160160
:meth:`IPv6._decode_next_layer <pcapkit.protocols.internet.ipv6.IPv6._decode_next_layer>`
161-
ends the ordinary way one iteration later. So ESP is absent from
162-
:attr:`IPv6.__generic_ext_codes__ <pcapkit.protocols.internet.ipv6.IPv6.__generic_ext_codes__>`
163-
-- not because it lacks a parser, which it has, but because it cannot hand the walk a
164-
successor.
161+
ends the ordinary way one iteration later -- not because ESP lacks a parser, which
162+
it has, but because it cannot hand the walk a successor.
165163

166164
The full reasoning, including how ESP's terminal case differs from 253/254's, is
167-
written where the code is and is deliberately not restated at length here: see the
168-
``#:`` comment on
169-
:attr:`IPv6.__generic_ext_codes__ <pcapkit.protocols.internet.ipv6.IPv6.__generic_ext_codes__>`
170-
(:file:`pcapkit/protocols/internet/ipv6.py`) and the module docstring of
171-
:mod:`pcapkit.protocols.internet.ipv6_ext`.
165+
written where the code is and is deliberately not restated at length here: see
166+
:meth:`IPv6._import_next_layer <pcapkit.protocols.internet.ipv6.IPv6._import_next_layer>`
167+
and the module docstring of :mod:`pcapkit.protocols.internet.ipv6_ext`.
172168

173169
.. caution::
174170

175171
The two facts have to be kept apart when reading any of this. "ESP is not an
176172
extension header" (wrong, and :rfc:`8200#section-4.5` quoted out of scope) is a
177173
different claim from "ESP cannot be walked past" (right, and about
178174
:rfc:`4303`'s wire format). Collapsing them is how ESP ends up either dropped
179-
from the extension-header contract or wrongly added to the generic-dispatch set.
175+
from the extension-header contract or wrongly walked past.

‎docs/source/pcapkit/protocols/internet/ipv6.rst‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,6 @@ Octets Bits Name Description
4545

4646
.. automethod:: __index__
4747

48-
.. autoattribute:: __generic_ext_codes__
49-
:no-value:
50-
5148
.. automethod:: _read_ip_hextet
5249

5350
Protocol Constants

‎docs/source/pcapkit/protocols/internet/ipv6_ext.rst‎

Lines changed: 21 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ unavailable on a header parsed as part of an IPv6 chain. Each subclass guards
1414
its own ``protocol`` the same way; this class's
1515
:attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.protocol` deliberately
1616
does not. It also implements a
17-
**generic** extractor for IPv6 extension headers [*]_, standing in whenever a
18-
header's own dedicated parser is unavailable or has failed. :rfc:`6564#section-4`
17+
**generic** extractor for IPv6 extension headers [*]_, for a header with no
18+
dedicated parser. :rfc:`6564#section-4`
1919
requires, with an RFC 2119 **MUST**, that any IPv6 extension header defined since
2020
April 2012 carry the same first two octets:
2121

@@ -123,32 +123,25 @@ carry a ``next`` at all?) rather than on a list of codes.
123123
Entry Paths
124124
-----------
125125

126-
This class is reached in these ways:
127-
128-
1. **An unrecognised protocol number.**
129-
:attr:`~pcapkit.const.ipv6.extension_header.ExtensionHeader.Shim6` is a real
130-
IANA extension header (:rfc:`5533`) with no dedicated parser, so
131-
:meth:`Internet._lookup_next_layer <pcapkit.protocols.protocol.Protocol._lookup_next_layer>`
132-
would default it to plain :class:`~pcapkit.protocols.misc.raw.Raw`. That
133-
has no ``next`` field, so the walk in
134-
:meth:`IPv6._decode_next_layer <pcapkit.protocols.internet.ipv6.IPv6._decode_next_layer>` would
135-
crash on it (:issue:`891`). This module registers this class for that code
136-
instead, at the bottom of the module, so dispatch reaches a working generic
137-
parser directly. The registration is global, shared by every
138-
:class:`~pcapkit.protocols.internet.internet.Internet` subclass, so
139-
:meth:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.__post_init__` gates on ``version == 6`` to
140-
keep it from also activating for an IPv4 payload that carries protocol
141-
number 140; see its docstring.
142-
2. **A recognised header whose own parser raises.** ``HOPOPT``,
143-
``IPv6-Route``, ``IPv6-Opts``, ``MH``, ``HIP``, ``IPv6-Frag`` and ``AH`` all
144-
have dedicated classes. When one of *those* raises,
145-
:func:`~pcapkit.corekit.decorators.beholder`
146-
(:meth:`Protocol._import_next_layer <pcapkit.protocols.protocol.Protocol._import_next_layer>`)
147-
would substitute plain :class:`~pcapkit.protocols.misc.raw.Raw`, which loses
148-
``next`` and crashes the walk as in path 1.
149-
:meth:`IPv6._import_next_layer <pcapkit.protocols.internet.ipv6.IPv6._import_next_layer>` catches
150-
the failure itself, one layer in from ``beholder``, and substitutes this
151-
class: the bad header costs only itself, not the rest of the chain.
126+
This class is reached by direct dispatch only.
127+
:attr:`~pcapkit.const.ipv6.extension_header.ExtensionHeader.Shim6` is a real
128+
IANA extension header (:rfc:`5533`) with no dedicated parser, so
129+
:meth:`Internet._lookup_next_layer <pcapkit.protocols.protocol.Protocol._lookup_next_layer>`
130+
would default it to plain :class:`~pcapkit.protocols.misc.raw.Raw`, whose
131+
missing ``next`` field would end the walk in
132+
:meth:`IPv6._decode_next_layer <pcapkit.protocols.internet.ipv6.IPv6._decode_next_layer>`
133+
there (:issue:`891`). This module registers this class for that code instead,
134+
at the bottom of the module, so dispatch reaches a working generic parser
135+
directly. The registration is global, shared by every
136+
:class:`~pcapkit.protocols.internet.internet.Internet` subclass, so
137+
:meth:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.__post_init__` gates on
138+
``version == 6`` to keep it from also activating for an IPv4 payload that
139+
carries protocol number 140; see its docstring.
140+
141+
A header with a dedicated class whose parser raises does not reach this class.
142+
:func:`~pcapkit.corekit.decorators.beholder` makes it plain
143+
:class:`~pcapkit.protocols.misc.raw.Raw`, and the walk stops there, as
144+
:rfc:`8200#section-4` has a node discard such a packet (:issue:`2477`).
152145

153146
.. _ipv6-ext-overrun-guard:
154147

‎pcapkit/protocols/data/internet/ipv6.py‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,8 +70,7 @@ class IPv6(Protocol):
7070
#: Extension header chain, in wire order, as pairs of the parser
7171
#: class and its info. The per-header keys hold the same infos, but in
7272
#: the order of the keys of this :class:`~pcapkit.corekit.infoclass.Info`,
73-
#: which differs on PyPy, so the chain is rebuilt from this alone; the
74-
#: parser class keeps the IPv6_Ext a header fell back to
73+
#: which differs on PyPy, so the chain is rebuilt from this alone
7574
#: (:issue:`1473`, :issue:`2003`).
7675
__exthdr__: 'tuple[tuple[Type[ProtocolBase], Data], ...]'
7776

‎pcapkit/protocols/data/internet/ipv6_ext.py‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,6 @@ class IPv6_Ext(Protocol):
4747
length: 'int'
4848
#: Header-specific content after the two fixed octets, as consumed.
4949
data: 'bytes'
50-
#: Original parsing error, if this instance was reached as a
51-
#: :func:`~pcapkit.corekit.decorators.beholder` fallback rather than by
52-
#: direct dispatch.
50+
#: Parsing error a caller passed to
51+
#: :meth:`read <pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.read>`, if any.
5352
error: 'Optional[Exception]'

0 commit comments

Comments
 (0)