Internet Checksum

pcapkit.corekit.checksum.internet contains the one’s-complement Internet checksum (RFC 1071) of the IPv4 header, TCP, UDP, ICMP, ICMPv6, IGMP, GRE and OSPF. Parsing verifies a checksum only if CHECKSUM_VERIFY is on, and records the outcome as checksum_status; construction computes one left out unless CHECKSUM_COMPUTE is off (#2471). A mismatch warns with a ChecksumWarning, which a filter can silence alone (#2470).

It imports nothing from pcapkit.protocols, which builds on it (#2580). A checksum over the IP pseudo-header is left to the enclosing IP layer, see pcapkit.protocols.misc.checksum.ip_pseudo. ICMP’s, IGMP’s and GRE’s checksums, over the message alone, are verified as it is parsed, unless the IP layer it is parsed from is a fragment, see verify_message() (#2618).

Added in version 1.6.0.

class pcapkit.corekit.checksum.internet.ChecksumStatus(*values)[source]

Bases: EnumLookup, IntEnum

Outcome of verifying a checksum, as recorded in checksum_status.

get / get_all come from EnumLookup; the class defines no _missing_, so an unknown value raises ValueError.

VALID = 0

The checksum matches.

INVALID = 1

The checksum does not match, which warns with a ChecksumWarning.

NOT_COMPUTED = 2

The field holds no checksum: one the protocol lets the sender leave out, as UDP over IPv4 does with zero (RFC 768), or what checksum offload leaves in a capture taken on the sending host. This is the expected state for such a capture, and is not an error.

TRUNCATED = 3

Fewer octets were captured than the checksum covers.

NO_PSEUDO_HEADER = 4

The enclosing IP layer does not give what the checksum covers: it is a fragment, holding only part of the datagram, or the pseudo-header cannot be derived from it.

pcapkit.corekit.checksum.internet.internet_checksum(data)[source]

Compute the Internet checksum of data (RFC 1071).

Parameters:

data (bytes) – Octets the checksum covers, with the checksum field zeroed.

Return type:

int

Returns:

The one’s complement of the one’s-complement sum of data.

pcapkit.corekit.checksum.internet.compute_checksum(data, *, prefix=b'', nonzero=False)[source]

Compute the checksum field of data.

Parameters:

  • data (bytes) – Octets the checksum covers, with the checksum field zeroed.

  • prefix (bytes) – Pseudo-header octets the checksum covers ahead of data.

  • nonzero (bool) – Whether a computed zero is written as 0xFFFF, as UDP does (RFC 768), since its zero means no checksum.

Return type:

bytes

Returns:

The two octets of the checksum field.

pcapkit.corekit.checksum.internet.partial_checksum(prefix)[source]

The field checksum offload leaves for a pseudo-header checksum.

A sender that offloads the checksum to its NIC writes the one’s-complement sum of the pseudo-header alone, uncomplemented, for the NIC to finish, as Linux does for TCP and UDP; a capture taken on that host records it so.

Parameters:

prefix (bytes) – Pseudo-header octets.

Return type:

bytes

Returns:

The two octets of that partial checksum.

pcapkit.corekit.checksum.internet.verify_checksum(alias, data, field, *, length=None, prefix=b'', absent=None, offload=())[source]

Verify the checksum field of data.

Parameters:

  • alias (str) – Protocol alias, to name in the warning.

  • data (bytes) – Octets the checksum covers, the checksum field included.

  • field (bytes) – The checksum field, as on the wire.

  • length (int | None) – Octets the checksum covers, as the headers declare it; the length of data by default.

  • prefix (bytes) – Pseudo-header octets the checksum covers ahead of data.

  • absent (bytes | None) – Field value that means the sender left the checksum out.

  • offload (Collection[bytes]) – Field values checksum offload leaves on the sending host.

Return type:

ChecksumStatus

Returns:

VALID if the sum of prefix and data is all ones (RFC 1071), or the reason it is not.

Warns:

ChecksumWarning – If the checksum is INVALID, unless a payload is being rebuilt: the layer it is rebuilt for parses the same octets again, so a rebuilt frame warns once.

pcapkit.corekit.checksum.internet.verify_message(alias, data, field, *, length=None)[source]

Verify the checksum field of a message that covers itself alone.

ICMP’s (RFC 792), IGMP’s (RFC 2236 Section 2.3, RFC 3376 Section 4.1.2) and GRE’s (RFC 2784 Section 2.5) checksums cover the octets of their own message, with no pseudo-header, so they are verified as the message is parsed, unless an IP fragment carries it; see fragment_payload().

Where no layer before the message declares its length, the message runs to the end of its frame, and the octets the capture cut off the frame, as frame_length gives them, are covered too (#2653, #2689).

Parameters:

  • alias (str) – Protocol alias, to name in the warning.

  • data (bytes) – Octets the checksum covers, the checksum field included.

  • field (bytes) – The checksum field, as on the wire.

  • length (int | None) – Octets the checksum covers, as the headers declare it; the length of data by default.

Return type:

ChecksumStatus

Returns:

NO_PSEUDO_HEADER for the payload of an IP fragment, otherwise as verify_checksum().

Warns:

ChecksumWarning – As verify_checksum() does.

pcapkit.corekit.checksum.internet.fragment_payload(fragment)[source]

Mark the payload an IP layer parses as a fragment’s, or not.

A checksum over the message alone, as ICMP’s (RFC 792), covers all of the datagram’s data, which a fragment carries part of, so verify_message() records NO_PSEUDO_HEADER for the upper layer of one rather than verifying it (#2470). The nearest enclosing IP layer decides.

Parameters:

fragment (bool) – Whether the IP layer is a fragment; an atomic one is not.

Return type:

Iterator[None]