Skip to content

Commit a6f8103

Browse files
committed
fix(protocols): derive IP_Pseudo's upper-layer values from the wire (#2471)
- UDP: use the UDP Length field when it is present and non-zero. - IPv4: the destination of an LSR or SSR route is its last address. - IPv6: a Mobility Header or HIP ends IP_Pseudo's walk and is the upper layer. - Raise ProtocolError for an unwalked header, a truncated Routing or Fragment header, and a malformed Destination Options or Routing header. - Replace literal 6, 12, 40 and 65535 with the layout widths and IP_MAX_LENGTH. - Name IP_Pseudo.src and dst in the address-typed switch table. - Test the walk cases and the surviving mutants (last fragment, summed and duplicate extension headers). ip_pseudo.py is at 100% line and branch.
1 parent cad6006 commit a6f8103

4 files changed

Lines changed: 320 additions & 35 deletions

File tree

‎pcapkit/protocols/internet/ip_pseudo.py‎

Lines changed: 139 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
import ipaddress
3939
from typing import TYPE_CHECKING, overload
4040

41+
from pcapkit.const.ipv4.option_number import OptionNumber as Enum_IPv4Option
4142
from pcapkit.const.ipv6.extension_header import ExtensionHeader as Enum_ExtensionHeader
4243
from pcapkit.const.ipv6.option import Option as Enum_Option
4344
from pcapkit.const.reg.transtype import TransType as Enum_TransType
@@ -50,7 +51,7 @@
5051
from pcapkit.protocols.protocol import ProtocolBase
5152
from pcapkit.protocols.schema.internet.ip_pseudo import IPV4_PSEUDO_LEN, IPV6_PSEUDO_LEN
5253
from pcapkit.protocols.schema.internet.ip_pseudo import IP_Pseudo as Schema_IP_Pseudo
53-
from pcapkit.protocols.schema.internet.ipv6 import jumbo_payload_length
54+
from pcapkit.protocols.schema.internet.ipv6 import IP_MAX_LENGTH, jumbo_payload_length
5455
from pcapkit.utilities.exceptions import FieldValueError, ProtocolError, UnsupportedCall
5556

5657
if TYPE_CHECKING:
@@ -63,6 +64,10 @@
6364

6465
__all__ = ['IP_Pseudo']
6566

67+
#: Extension headers that end the chain, as the upper layer: the Mobility Header
68+
#: (:rfc:`6275#section-6.1.1`) and HIP (:rfc:`7401#section-5.1.1`).
69+
_TERMINAL_HEADERS = (Enum_ExtensionHeader.Mobility_Header, Enum_ExtensionHeader.HIP)
70+
6671

6772
class IP_Pseudo(ProtocolBase[Data_IP_Pseudo, Schema_IP_Pseudo],
6873
schema=Schema_IP_Pseudo, data=Data_IP_Pseudo):
@@ -91,7 +96,7 @@ def name(self) -> 'Literal["IP Pseudo-Header"]':
9196
@property
9297
def length(self) -> 'Literal[12, 40]':
9398
"""Header length of current protocol."""
94-
return IPV6_PSEUDO_LEN if self._info.version == 6 else IPV4_PSEUDO_LEN # type: ignore[return-value]
99+
return IPV6_PSEUDO_LEN if self._is_ipv6(self._info.src) else IPV4_PSEUDO_LEN # type: ignore[return-value]
95100

96101
@property
97102
def protocol(self) -> 'Enum_TransType':
@@ -174,7 +179,7 @@ def read(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_IP_Pseu
174179
src=schema.src,
175180
dst=schema.dst,
176181
protocol=Enum_TransType.get(schema.protocol),
177-
len=schema.ipv6_len if version == 6 else schema.ipv4_len,
182+
len=schema.ipv6_len if self._is_ipv6(schema.src) else schema.ipv4_len,
178183
zero=schema.zero,
179184
)
180185

@@ -197,14 +202,20 @@ def make(self,
197202
Address option (:rfc:`6275#section-11.3.1`), ``dst`` the final
198203
destination of a Routing header with segments left, and ``protocol``
199204
and ``upper_length`` those past the extension headers, a jumbogram's
200-
length being its Jumbo Payload Length (:rfc:`2675`).
205+
length being its Jumbo Payload Length (:rfc:`2675`). A Mobility Header
206+
or HIP is the upper layer itself. From an IPv4 layer, ``dst`` is the
207+
last address of a source route (:rfc:`791`), not the next hop in flight.
208+
A UDP upper layer's length is its Length field (:rfc:`768`) when that
209+
is present.
201210
202211
Values ``ip`` does not determine are to be given, or ``make`` raises:
203212
the final destination of a Routing header whose addresses are not parsed,
204213
such as the Segment List[0] of a Segment Routing Header
205214
(:rfc:`8754`); the upper-layer length of a fragment, which only
206215
reassembly gives; and the upper layer behind an unparsed header, such
207-
as an encrypted ESP.
216+
as an encrypted ESP, or one the walk left, such as past the header limit.
217+
``src``, ``dst``, ``protocol`` and ``upper_length`` given explicitly
218+
override those read from ``ip``.
208219
209220
Args:
210221
ip: Parsed or constructed IP layer enclosing the upper layer.
@@ -223,8 +234,9 @@ def make(self,
223234
Constructed packet data.
224235
225236
Raises:
226-
ProtocolError: If ``ip`` is neither IPv4 nor IPv6, or a value is
227-
given by neither the arguments nor ``ip``.
237+
ProtocolError: If ``ip`` is neither IPv4 nor IPv6, a value is given
238+
by neither the arguments nor ``ip``, or a header of ``ip`` is
239+
malformed or not parsed.
228240
FieldValueError: If ``src`` or ``dst`` is not a valid address,
229241
they differ in IP version, or ``upper_length`` does not fit
230242
the layout's length field.
@@ -238,18 +250,20 @@ def make(self,
238250
src = self._source(ip)
239251
if dst is None:
240252
dst = self._destination(ip)
241-
if protocol is None:
253+
from_layer = protocol is None
254+
if from_layer:
242255
protocol = self._upper_protocol(ip)
243256
if upper_length is None:
244-
upper_length = self._upper_length(ip)
257+
upper_length = self._upper_length(ip, from_layer=from_layer)
245258

246259
if src is None or dst is None or protocol is None or upper_length is None:
247260
raise ProtocolError(f'{self.alias}: src, dst, protocol and upper_length '
248261
'are required without ip')
249262

250263
src_val = parse_ip_address(src, f'{self.alias}: source address')
251264
dst_val = parse_ip_address(dst, f'{self.alias}: destination address', src_val.version)
252-
limit = 0xFFFFFFFF if src_val.version == 6 else 0xFFFF
265+
is_v6 = self._is_ipv6(src_val)
266+
limit = 0xFFFFFFFF if is_v6 else IP_MAX_LENGTH
253267
if not 0 <= upper_length <= limit:
254268
raise FieldValueError(f'{self.alias}: upper-layer length {upper_length} '
255269
f'out of range 0 to {limit:#x}')
@@ -260,10 +274,10 @@ def make(self,
260274

261275
# NOTE: Kept at the layout's width, so that a constructed data model
262276
# matches the parsed one.
263-
width = 3 if src_val.version == 6 else 1
277+
width = 3 if is_v6 else 1
264278
zero = zero[:width].ljust(width, b'\x00')
265279

266-
if src_val.version == 6:
280+
if is_v6:
267281
return Schema_IP_Pseudo(
268282
src=src_val,
269283
dst=dst_val,
@@ -369,11 +383,18 @@ def _source(self, ip: 'IPv4 | IPv6') -> 'IPv4Address | IPv6Address':
369383
The address of a Home Address option (:rfc:`6275#section-11.3.1`)
370384
if any, the source address otherwise.
371385
386+
Raises:
387+
ProtocolError: If a Destination Options header is not parsed.
388+
372389
"""
373390
src = ip.info.src
374391
if isinstance(ip, IPv6):
375392
for header in ip.extension_headers.getlist(Enum_ExtensionHeader.IPv6_Opts): # type: ignore[arg-type]
376-
option = header.info.options.get(Enum_Option.Home_Address)
393+
options = header.info.get('options')
394+
if options is None:
395+
raise ProtocolError(f'{self.alias}: Destination Options of {ip.alias} not '
396+
'parsed; give src')
397+
option = options.get(Enum_Option.Home_Address)
377398
if option is not None:
378399
src = option.address
379400
return src
@@ -385,20 +406,35 @@ def _destination(self, ip: 'IPv4 | IPv6') -> 'IPv4Address | IPv6Address':
385406
ip: IPv4 or IPv6 layer.
386407
387408
Returns:
388-
The last address of a Routing header with segments left if any,
389-
the destination address otherwise.
409+
The last address of a source route (:rfc:`791`) or of a Routing
410+
header with segments left, the destination address otherwise.
390411
391412
Raises:
392-
ProtocolError: If a Routing header with segments left has no
393-
parsed last address.
413+
ProtocolError: If a source route or Routing header is not parsed,
414+
or a Routing header with segments left has no parsed last
415+
address.
394416
395417
"""
396418
dst = ip.info.dst
397419
if isinstance(ip, IPv4):
420+
# NOTE: In flight the header holds the next hop; the final
421+
# destination is the last address the source route lists.
422+
options = ip.info.get('options')
423+
if options is None:
424+
return dst
425+
for code in (Enum_IPv4Option.LSR, Enum_IPv4Option.SSR):
426+
for option in options.getlist(code):
427+
# NOTE: The option splits its addresses at the pointer; the
428+
# last of both halves is the final destination.
429+
if option.route or option.remaining:
430+
dst = (*option.route, *option.remaining)[-1]
398431
return dst
399432
for header in ip.extension_headers.getlist(Enum_ExtensionHeader.IPv6_Route): # type: ignore[arg-type]
400433
route = header.info
401-
if not route.seg_left:
434+
seg_left = route.get('seg_left')
435+
if seg_left is None or route.get('__short_read__') is not None:
436+
raise ProtocolError(f'{self.alias}: Routing header of {ip.alias} not parsed; give dst')
437+
if not seg_left:
402438
continue
403439
# NOTE: Type 2 carries one address, the source routes a tuple. A
404440
# truncated RPL address stays bytes; unparsed types carry none.
@@ -421,23 +457,71 @@ def _upper_protocol(self, ip: 'IPv4 | IPv6') -> 'Enum_TransType':
421457
The protocol past the extension headers.
422458
423459
Raises:
424-
ProtocolError: If the walk ended at an unparsed header.
460+
ProtocolError: If the walk ended at an unparsed header: none, or
461+
an IPv6 extension header that was not walked, as past the
462+
header limit, or a truncated Routing or Fragment header.
463+
464+
"""
465+
return self._upper(ip)[0]
466+
467+
def _upper(self, ip: 'IPv4 | IPv6') -> 'tuple[Enum_TransType, int]':
468+
"""Read the upper-layer protocol and the octets of the headers ahead of it.
469+
470+
For IPv6 the chain ends at a Mobility Header or HIP (:rfc:`6275#section-6.1.1`,
471+
:rfc:`7401#section-5.1.1`), which is then the upper layer whether or not
472+
the walk went on past it.
473+
474+
Args:
475+
ip: IPv4 or IPv6 layer.
476+
477+
Returns:
478+
The protocol past the extension headers, and the octets of those
479+
headers ahead of it.
480+
481+
Raises:
482+
ProtocolError: If the walk ended at an unparsed header: none, or an
483+
IPv6 extension header that was not walked.
425484
426485
"""
427-
protocol = ip.info.protocol
428-
if protocol is None:
486+
if isinstance(ip, IPv4):
487+
return ip.info.protocol, 0
488+
489+
code, before = ip.info.next, 0
490+
for _, header in ip.extension_headers.items(multi=True):
491+
if code in _TERMINAL_HEADERS:
492+
break
493+
before += header.length
494+
code = header.info.next
495+
if code is None or (code not in _TERMINAL_HEADERS and self._is_extension_header(code)):
429496
raise ProtocolError(f'{self.alias}: upper layer of {ip.alias} not parsed; '
430497
'give protocol and upper_length')
431-
return protocol
432-
433-
def _upper_length(self, ip: 'IPv4 | IPv6') -> 'int':
498+
return code, before
499+
500+
@staticmethod
501+
def _is_ipv6(address: 'IPv4Address | IPv6Address') -> 'bool':
502+
"""Tell whether ``address`` selects the IPv6 layout."""
503+
return isinstance(address, ipaddress.IPv6Address)
504+
505+
@staticmethod
506+
def _is_extension_header(code: 'int') -> 'bool':
507+
"""Tell whether ``code`` is an IPv6 extension header number."""
508+
try:
509+
Enum_ExtensionHeader(code)
510+
except ValueError:
511+
return False
512+
return True
513+
514+
def _upper_length(self, ip: 'IPv4 | IPv6', *, from_layer: 'bool' = True) -> 'int':
434515
"""Read the upper-layer packet length from an IP layer.
435516
436517
Args:
437518
ip: IPv4 or IPv6 layer.
519+
from_layer: Whether the upper layer is the one ``ip`` carries,
520+
rather than one given by the caller.
438521
439522
Returns:
440-
The length past the IP header and extension headers.
523+
The Length field of a UDP header that is present, else the length
524+
past the IP header and extension headers.
441525
442526
Raises:
443527
ProtocolError: If ``ip`` is a fragment, ends at an unparsed header,
@@ -448,9 +532,10 @@ def _upper_length(self, ip: 'IPv4 | IPv6') -> 'int':
448532
info4 = ip.info
449533
if info4.offset or info4.flags.mf:
450534
raise ProtocolError(f'{self.alias}: {ip.alias} fragment; give upper_length')
451-
return info4.len - info4.hdr_len
535+
protocol, _ = self._upper(ip)
536+
return self._udp_length(ip, protocol, info4.hdr_len, info4.len - info4.hdr_len, from_layer)
452537

453-
self._upper_protocol(ip)
538+
protocol, before = self._upper(ip)
454539
info = ip.info
455540
for frag in ip.extension_headers.getlist(Enum_ExtensionHeader.IPv6_Frag): # type: ignore[arg-type]
456541
if frag.info.offset or frag.info.mf:
@@ -463,4 +548,30 @@ def _upper_length(self, ip: 'IPv4 | IPv6') -> 'int':
463548
raise ProtocolError(f'{self.alias}: Payload Length 0 and no Jumbo Payload '
464549
'option; give upper_length')
465550
extent = jumbo
466-
return extent - sum(header.length for _, header in ip.extension_headers.items(multi=True))
551+
return self._udp_length(ip, protocol, info.hdr_len, extent - before, from_layer)
552+
553+
def _udp_length(self, ip: 'IPv4 | IPv6', protocol: 'int', hdr_len: 'int', length: 'int',
554+
from_layer: 'bool') -> 'int':
555+
"""Prefer the Length field of a UDP header to the length from the IP layer.
556+
557+
Args:
558+
ip: IPv4 or IPv6 layer.
559+
protocol: Upper-layer protocol.
560+
hdr_len: Length of the IP header and extension headers.
561+
length: Length from the IP layer.
562+
from_layer: Whether the upper layer is the one ``ip`` carries.
563+
564+
Returns:
565+
The UDP Length field (:rfc:`768`) if the upper layer is UDP and its
566+
header is present with a non-zero field, ``length`` otherwise.
567+
568+
"""
569+
if not from_layer or protocol != Enum_TransType.UDP:
570+
return length
571+
# NOTE: Octets 4 and 5 of the UDP header are its Length field. A zero
572+
# field is a jumbogram's, so the IP layer's length stands.
573+
start = hdr_len + 4
574+
octets = ip.data[start:start + 2]
575+
if len(octets) < 2:
576+
return length
577+
return int.from_bytes(octets, 'big') or length

‎pcapkit/protocols/schema/internet/ip_pseudo.py‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,15 +20,17 @@
2020

2121
from pcapkit.corekit.fields.field import FieldBase as Field
2222

23-
#: Length of the IPv4 pseudo-header, :rfc:`793#section-3.1`.
23+
#: Length of the IPv4 pseudo-header, :rfc:`793#section-3.1`: source, destination,
24+
#: zero, protocol and length.
2425
#:
2526
#: .. versionadded:: 1.6.0
26-
IPV4_PSEUDO_LEN = 12
27+
IPV4_PSEUDO_LEN = 2 * (ipaddress.IPV4LENGTH // 8) + 1 + 1 + 2
2728

28-
#: Length of the IPv6 pseudo-header, :rfc:`8200#section-8.1`.
29+
#: Length of the IPv6 pseudo-header, :rfc:`8200#section-8.1`: source, destination,
30+
#: length, zero and next header.
2931
#:
3032
#: .. versionadded:: 1.6.0
31-
IPV6_PSEUDO_LEN = 40
33+
IPV6_PSEUDO_LEN = 2 * (ipaddress.IPV6LENGTH // 8) + 4 + 3 + 1
3234

3335

3436
def is_ipv6(packet: 'dict[str, Any]') -> 'bool':
@@ -46,7 +48,7 @@ def is_ipv6(packet: 'dict[str, Any]') -> 'bool':
4648
"""
4749
src = packet.get('src')
4850
if isinstance(src, (ipaddress.IPv4Address, ipaddress.IPv6Address)):
49-
return src.version == 6
51+
return isinstance(src, ipaddress.IPv6Address)
5052
return packet['__length__'] >= IPV6_PSEUDO_LEN
5153

5254

‎tests/corekit/test_fields_misc.py‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,17 @@
6262
'tcp mptcp add_addr IPv4', {'length': 8}),
6363
('pcapkit.protocols.schema.transport.tcp', 'MPTCPAddAddress', 'address',
6464
'tcp mptcp add_addr IPv6', {'length': 20}),
65+
66+
# The layout follows ``__length__`` when no address is given yet, 12 for IPv4
67+
# and 40 for IPv6.
68+
('pcapkit.protocols.schema.internet.ip_pseudo', 'IP_Pseudo', 'src',
69+
'ip_pseudo src IPv4', {'__length__': 12}),
70+
('pcapkit.protocols.schema.internet.ip_pseudo', 'IP_Pseudo', 'src',
71+
'ip_pseudo src IPv6', {'__length__': 40}),
72+
('pcapkit.protocols.schema.internet.ip_pseudo', 'IP_Pseudo', 'dst',
73+
'ip_pseudo dst IPv4', {'__length__': 12}),
74+
('pcapkit.protocols.schema.internet.ip_pseudo', 'IP_Pseudo', 'dst',
75+
'ip_pseudo dst IPv6', {'__length__': 40}),
6576
]
6677

6778

0 commit comments

Comments
 (0)