Checksums

pcapkit.protocols.misc.checksum contains the pseudo-header that upper-layer checksums cover, IP_Pseudo. What the one’s-complement checksums share, such as ChecksumStatus, is in pcapkit.corekit.checksum.internet.

IP Pseudo-Header

pcapkit.protocols.misc.checksum.ip_pseudo contains IP_Pseudo, which implements the pseudo-header of the IP protocol family that the upper-layer checksums cover, and pseudo_header() and verify_upper(), through which the IP layers use it. The pseudo-header’s structure is described as below:

IPv4 (RFC 793 Section 3.1, RFC 768):

Octets	Bits	Name	Description
0	0	ip_pseudo.src	Source Address
4	32	ip_pseudo.dst	Destination Address
8	64	ip_pseudo.zero	Reserved
9	72	ip_pseudo.protocol	Protocol
10	80	ip_pseudo.len	Upper-Layer Packet Length

IPv6 (RFC 8200 Section 8.1):

Octets	Bits	Name	Description
0	0	ip_pseudo.src	Source Address
16	128	ip_pseudo.dst	Destination Address
32	256	ip_pseudo.len	Upper-Layer Packet Length
36	288	ip_pseudo.zero	Reserved
39	312	ip_pseudo.protocol	Next Header

A checksum over the IP pseudo-header is verified and computed by the enclosing IPv4 or IPv6 layer, which builds the IP_Pseudo, rather than by the upper layer reaching back to its parent. So an upper layer constructed alone, or behind another header such as an IPv6 extension header or an Authentication Header, has its checksum computed only if given the pseudo to compute it over, and one parsed alone records no outcome. The sum itself is in pcapkit.corekit.checksum.internet.

class pcapkit.protocols.misc.checksum.ip_pseudo.IP_Pseudo(file=None, length=None, **kwargs)

Bases: ProtocolBase[IP_Pseudo, IP_Pseudo]

This class implements the IP pseudo-header.

It is not a layer on the wire: it is built from the enclosing IPv4 or IPv6 layer, or from explicit values, and its data is the octets an upper-layer checksum covers ahead of that layer’s own. The layout follows the IP version of the source address, or the length of the octets parsed.

Added in version 1.6.0.

property name: Literal['IP Pseudo-Header']

Name of current protocol.

property length: Literal[12, 40]

Header length of current protocol.

property protocol: TransType

Upper-layer protocol.

property version: Literal[4, 6]

IP version of the enclosing layer.

property src: IPv4Address | IPv6Address

Source address.

property dst: IPv4Address | IPv6Address

Destination address.

read(length=None, **kwargs)

Read IP pseudo-header.

Structure of the IPv4 pseudo-header [RFC 793]:

+--------+--------+--------+--------+
|           Source Address          |
+--------+--------+--------+--------+
|         Destination Address       |
+--------+--------+--------+--------+
|  zero  |  PTCL  |    TCP Length   |
+--------+--------+--------+--------+

Structure of the IPv6 pseudo-header [RFC 8200]:

+--------+--------+--------+--------+
|                                   |
+                                   +
|                                   |
+         Source Address            +
|                                   |
+                                   +
|                                   |
+--------+--------+--------+--------+
|                                   |
+                                   +
|                                   |
+       Destination Address         +
|                                   |
+                                   +
|                                   |
+--------+--------+--------+--------+
|     Upper-Layer Packet Length     |
+--------+--------+--------+--------+
|          zero            |  Next  |
+--------+--------+--------+--------+

Parameters:

• length (int | None) – Length of packet data.

• **kwargs (Any) – Arbitrary keyword arguments.

Return type:

IP_Pseudo

Returns:

Parsed packet data.

make(ip=None, src=None, dst=None, protocol=None, upper_length=None, zero=b'', **kwargs)

Make (construct) packet data.

Values not given are read from ip. src is a Home Address option’s address (RFC 6275 Section 11.3.1); dst is the final destination of a Routing header with segments left, or of a source route (RFC 791) not yet exhausted; protocol and upper_length lie past the extension headers, a UDP upper layer giving its Length field (RFC 768) and a jumbogram its Jumbo Payload Length (RFC 2675). Values ip lacks are to be given: an unparsed Routing destination (RFC 8754), a fragment’s length, or an upper layer behind an unparsed header such as ESP.

Parameters:

• ip (IPv4 | IPv6 | None) – Parsed or constructed IP layer enclosing the upper layer.

• src (bytes | str | int | IPv4Address | IPv6Address | None) – Source address; its IP version selects the layout.

• dst (bytes | str | int | IPv4Address | IPv6Address | None) – Destination address, of the same IP version as src.

• protocol (TransType | int | None) – Upper-layer protocol number.

• upper_length (int | None) – Upper-layer packet length, header included.

• zero (bytes) – Reserved octets, one for IPv4 and three for IPv6; empty for zeros.

• **kwargs (Any) – Arbitrary keyword arguments.

Return type:

IP_Pseudo

Returns:

Constructed packet data.

Raises:

• ProtocolError – If ip is neither IPv4 nor IPv6, a value is given by neither the arguments nor ip, a header of ip is malformed or not parsed, protocol is a name, a bool, or a member or code the 8-bit protocol field cannot carry, or zero is neither empty nor the layout’s width.

• FieldValueError – If src or dst is not a valid address, they differ in IP version, or upper_length does not fit the layout’s length field.

classmethod _make_data(data)

Create key-value pairs from data for protocol construction.

Parameters:

data (IP_Pseudo) – protocol data

Return type:

dict[str, Any]

Returns:

Key-value pairs for protocol construction.

_source(ip)

Read the pseudo-header source address from an IP layer.

Parameters:

ip (IPv4 | IPv6) – IPv4 or IPv6 layer.

Return type:

IPv4Address | IPv6Address

Returns:

The address of a Home Address option (RFC 6275 Section 11.3.1) if any, the source address otherwise.

Raises:

ProtocolError – If a Destination Options header is not parsed, however deep in the chain.

_destination(ip)

Read the pseudo-header destination address from an IP layer.

Parameters:

ip (IPv4 | IPv6) – IPv4 or IPv6 layer.

Return type:

IPv4Address | IPv6Address

Returns:

The last address still to be visited of a source route (RFC 791) not yet exhausted, or of a Routing header with segments left; the destination address otherwise.

Raises:

ProtocolError – If a source route or Routing header is not parsed, or a Routing header with segments left has no parsed last address.

_upper_protocol(ip)

Read the upper-layer protocol from an IP layer.

Parameters:

ip (IPv4 | IPv6) – IPv4 or IPv6 layer.

Return type:

TransType

Returns:

The protocol past the extension headers.

Raises:

ProtocolError – If the walk ended at an unparsed header: none, or an IPv6 extension header that was not walked, as past the header limit, or a truncated Routing or Fragment header.

_upper_length(ip, *, from_layer=True)

Read the upper-layer packet length from an IP layer.

Parameters:

• ip (IPv4 | IPv6) – IPv4 or IPv6 layer.

• from_layer (bool) – Whether the upper layer is the one ip carries, rather than one given by the caller.

Return type:

int

Returns:

The Length field of a UDP header that is present, else the length past the IP header and extension headers.

Raises:

ProtocolError – If ip is a fragment, ends at an unparsed header, or has a zero Payload Length and no Jumbo Payload option.

__post_init__(file=None, length=None, **kwargs)

Post initialisation hook.

Overloads:

• file (IO[bytes] | bytes), length (int | None) = ..., **kwargs (Any) → None

• **kwargs (Any) → None

Parameters:

• file (IO[bytes] | bytes | None) – Source packet stream.

• length (int | None) – Length of packet data.

• **kwargs (Any) – Arbitrary keyword arguments.

Raises:

ProtocolError – If the octets parsed are not length long, or not 12 (IPv4) or 40 (IPv6) long.

See also

For construction arguments, please refer to make().

classmethod __index__()

Numeral registry index of the protocol.

Raises:

UnsupportedCall – This protocol has no registry entry.

Return type:

NoReturn

pcapkit.protocols.misc.checksum.ip_pseudo.pseudo_header(pseudo, length)

Octets of pseudo with length as its upper-layer length.

Parameters:

• pseudo (IP_Pseudo) – Pseudo-header of the enclosing IP layer.

• length (int) – Upper-layer length the checksum is computed for.

Return type:

bytes

Returns:

pseudo.data, made anew if it carries another length.

Raises:

FieldValueError – If length does not fit the length field.

pcapkit.protocols.misc.checksum.ip_pseudo.verify_upper(ip)

Verify the checksum of the upper layer ip carries over its pseudo-header.

The upper layer is the payload of ip, past any Authentication Header of IPv4. It is verified if it defines _verify_pseudo_checksum, against the IP_Pseudo of ip, or against None if that cannot be derived or names another protocol.

Parameters:

ip (IPv4 | IPv6) – Parsed IPv4 or IPv6 layer.

Header Schemas

pcapkit.protocols.schema.misc.checksum.ip_pseudo.IPV4_PSEUDO_LEN = 12

Length of the IPv4 pseudo-header, RFC 793 Section 3.1 – source, destination, zero, protocol and length.

Added in version 1.6.0.

pcapkit.protocols.schema.misc.checksum.ip_pseudo.IPV6_PSEUDO_LEN = 40

Length of the IPv6 pseudo-header, RFC 8200 Section 8.1 – source, destination, length, zero and next header.

Added in version 1.6.0.

class pcapkit.protocols.schema.misc.checksum.ip_pseudo.IP_Pseudo(src=NO_VALUE, dst=NO_VALUE, ipv6_len=NO_VALUE, zero=NO_VALUE, protocol=NO_VALUE, ipv4_len=NO_VALUE, *, __packet__=None, **kwargs)

Bases: Schema

Header schema for the IP pseudo-header.

The layout follows the source address: RFC 793 Section 3.1 for IPv4, whose length is ipv4_len, and RFC 8200 Section 8.1 for IPv6, whose length is ipv6_len.

Added in version 1.6.0.

src: IPv4Address | IPv6Address = <SwitchField src>

Source address.

dst: IPv4Address | IPv6Address = <SwitchField dst>

Destination address.

ipv6_len: int = <ConditionalField ipv6_len>

Upper-layer packet length (IPv6 only).

zero: bytes = <SwitchField zero>

Zero octets.

protocol: TransType = <EnumField protocol>

Upper-layer protocol number.

ipv4_len: int = <ConditionalField ipv4_len>

Upper-layer packet length (IPv4 only).

Auxiliary Functions

pcapkit.protocols.schema.misc.checksum.ip_pseudo.is_ipv6(packet)

Tell whether packet holds an IPv6 pseudo-header.

Parameters:

packet (dict[str, Any]) – Packet data.

Returns:

by the version of the source address once it is known, by the octets to unpack before that.

Return type:

bool

Added in version 1.6.0.

pcapkit.protocols.schema.misc.checksum.ip_pseudo.ip_pseudo_address_selector(packet)

Selector function for IP_Pseudo.src and IP_Pseudo.dst.

Parameters:

packet (dict[str, Any]) – Packet data.

Return type:

FieldBase

Returns:

An IPv6AddressField for the IPv6 layout, an IPv4AddressField otherwise.

Added in version 1.6.0.

pcapkit.protocols.schema.misc.checksum.ip_pseudo.ip_pseudo_zero_selector(packet)

Selector function for IP_Pseudo.zero.

Parameters:

packet (dict[str, Any]) – Packet data.

Return type:

FieldBase

Returns:

A PaddingField of three octets for the IPv6 layout, of one octet otherwise.

Added in version 1.6.0.

Data Models

class pcapkit.protocols.data.misc.checksum.ip_pseudo.IP_Pseudo(version, src, dst, protocol, len, zero)

Bases: Protocol

Data model for the IP pseudo-header.

Added in version 1.6.0.

version: Literal[4, 6]

IP version of the enclosing layer.

src: IPv4Address | IPv6Address

Source address.

dst: IPv4Address | IPv6Address

Destination address.

protocol: TransType

Upper-layer protocol number.

len: int

Upper-layer packet length, header included.

zero: bytes

Reserved octets, as parsed.