ICMPv4 - Internet Control Message Protocol¶

pcapkit.protocols.internet.icmpv4 contains ICMPv4 only, which implements extractor for Internet Control Message Protocol (ICMP) [*], whose structure is described as below:

Octets	Bits	Name	Description
0	0	`icmpv4.type`	Type
1	8	`icmpv4.code`	Code
2	16	`icmpv4.checksum`	Checksum
4	32	`icmpv4.data`	Message Body

class pcapkit.protocols.internet.icmpv4.ICMPv4(file=None, length=None, **kwargs)[source]¶

Bases: ICMP[ICMPv4, ICMPv4]

This class implements Internet Control Message Protocol.

This class parses the following ICMP message types, which are registered in the self.__type__ attribute:

Type	Data Parser	Data Constructor
Echo Reply / Echo Request	`_read_data_type_echo()`	`_make_data_type_echo()`
Destination Unreachable	`_read_data_type_destination_unreachable()`	`_make_data_type_destination_unreachable()`
Time Exceeded	`_read_data_type_time_exceeded()`	`_make_data_type_time_exceeded()`
Parameter Problem	`_read_data_type_parameter_problem()`	`_make_data_type_parameter_problem()`

Any other type is kept as its raw message body, see _read_data_type_none() and _make_data_type_none().

Changed in version 1.6.0: The checksum is computed when make() is given none, and verified on read under CHECKSUM_VERIFY, unless the enclosing IP layer is a fragment (#2470). A message whose header records a cut reads TRUNCATED (#2711).

property name: Literal['Internet Control Message Protocol']¶: Name of current protocol.

property alias: Literal['ICMP']¶: Acronym of corresponding protocol.

property length: int¶: Header length of current protocol.

classmethod id()[source]¶

Index ID of the protocol.

RFC 792 names the protocol ICMP, without a version.

String == compares against (cls, *id()), so == 'ICMPv4' is False, while 'ICMPv4' in matches by class.

Return type:: tuple[Literal['ICMP']]
Returns:: Index ID of the protocol.

classmethod register_type(code, meth)[source]¶

Parameters:

code (Type) – ICMP type code.
meth (str | tuple[Callable[[ICMPv4Type, ICMPv4, int], ICMPv4], Callable[[Type, ICMPv4 | None, Any], ICMPv4Type]]) – Name X of the _read_data_type_X and _make_data_type_X methods, or a (parser, constructor) pair of callables, see __type__.

Warns:

RegistryWarning – If a different entry is already registered for code; it is overwritten.

read(length=None, *, __packet__=None, **kwargs)[source]¶

Read Internet Control Message Protocol (ICMP).

Structure of ICMP header [RFC 792]:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     Type      |     Code      |          Checksum             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
.                         Message Body                         .
.                                                               .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parameters:

length (int | None) – Length of packet data.
__packet__ (dict[str, Any] | None) – Optional packet data, unused.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

ICMPv4

Returns:

Parsed packet data.

make(type=Type.Echo, code=0, checksum=None, body=b'\x00\x00\x00\x00', **kwargs)[source]¶

Make (construct) packet data.

Parameters:

type (Type | int) – ICMP type.
code (int) – ICMP code; meaning is entirely type-dependent.
checksum (bytes | None) – Checksum; if None, computed over the message (RFC 792) when CHECKSUM_COMPUTE is on, zero when it is off.
body (bytes | ICMPv4 | ICMPv4Type | dict[str, Any]) – Message body. bytes is parsed against type’s own schema; a dict or a ICMPv4 data model is handed to that type’s own constructor method (see __type__); any other ICMPv4Type is used as is.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

ICMPv4

Returns:

Constructed packet data.

Raises:

ProtocolError – If type is a name, a bool, or a member or code that does not fit in one octet; if body is bytes that do not parse as the message body of type, or is of none of the accepted types; or if checksum is not two octets.

classmethod _make_data(data)[source]¶

Create key-value pairs from data for protocol construction.

Parameters:: data (ICMPv4) – protocol data
Return type:: dict[str, Any]
Returns:: Key-value pairs for protocol construction.

_read_data_type_none(schema, *, header, length)[source]¶

Read ICMP message of unknown type.

Parameters:

schema (Unknown) – parsed message body schema
header (ICMPv4) – parsed ICMP header schema
length (int) – total length of the current ICMP message

Return type:

Unknown

Returns:

Parsed message data.

_read_data_type_echo(schema, *, header, length)[source]¶

Read ICMP Echo Request/Reply message.

Structure of ICMP Echo Request/Reply message [RFC 792]:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     Type      |     Code      |          Checksum             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|           Identifier          |        Sequence Number        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
.                             Data                              .
.                                                               .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parameters:

schema (Echo) – parsed message body schema
header (ICMPv4) – parsed ICMP header schema
length (int) – total length of the current ICMP message

Return type:

Echo

Returns:

Parsed message data.

_read_data_type_destination_unreachable(schema, *, header, length)[source]¶

Read ICMP Destination Unreachable message.

Structure of ICMP Destination Unreachable message [RFC 792]:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     Type      |     Code      |          Checksum             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                             unused                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|      Internet Header + 64 bits of Original Data Datagram      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parameters:

schema (DestinationUnreachable) – parsed message body schema
header (ICMPv4) – parsed ICMP header schema
length (int) – total length of the current ICMP message

Return type:

DestinationUnreachable

Returns:

Parsed message data.

_read_data_type_time_exceeded(schema, *, header, length)[source]¶

Read ICMP Time Exceeded message.

Structure of ICMP Time Exceeded message [RFC 792] is identical to that of _read_data_type_destination_unreachable(), but for the type code.

Parameters:

schema (TimeExceeded) – parsed message body schema
header (ICMPv4) – parsed ICMP header schema
length (int) – total length of the current ICMP message

Return type:

TimeExceeded

Returns:

Parsed message data.

_read_data_type_parameter_problem(schema, *, header, length)[source]¶

Read ICMP Parameter Problem message.

Structure of ICMP Parameter Problem message [RFC 792]:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     Type      |     Code      |          Checksum             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|    Pointer    |                   unused                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|      Internet Header + 64 bits of Original Data Datagram      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parameters:

schema (ParameterProblem) – parsed message body schema
header (ICMPv4) – parsed ICMP header schema
length (int) – total length of the current ICMP message

Return type:

ParameterProblem

Returns:

Parsed message data.

_make_data_type_none(type, message=None, *, data=b'', **kwargs)[source]¶

Make ICMP message of unknown type.

Parameters:

type (Type) – ICMP type.
message (Unknown | None) – message data.
data (bytes) – raw message body as bytes.
**kwargs (Any) – arbitrary keyword arguments.

Return type:

Unknown

Returns:

Constructed message body schema.

_make_data_type_echo(type, message=None, *, id=0, seq=0, data=b'', **kwargs)[source]¶

Make ICMP Echo Request/Reply message.

Parameters:

type (Type) – ICMP type.
message (Echo | None) – message data.
id (int) – identifier.
seq (int) – sequence number.
data (bytes) – data, echoed back verbatim by a reply to the same identifier and sequence number.
**kwargs (Any) – arbitrary keyword arguments.

Return type:

Echo

Returns:

Constructed message body schema.

_make_data_type_destination_unreachable(type, message=None, *, unused=b'\x00\x00\x00\x00', data=b'', **kwargs)[source]¶

Make ICMP Destination Unreachable message.

Parameters:

type (Type) – ICMP type.
message (DestinationUnreachable | None) – message data.
unused (bytes) – the four unused octets.
data (bytes) – internet header plus the first eight octets of the original datagram’s payload.
**kwargs (Any) – arbitrary keyword arguments.

Return type:

DestinationUnreachable

Returns:

Constructed message body schema.

Raises:

ProtocolError – If unused is not four octets.

_make_data_type_time_exceeded(type, message=None, *, unused=b'\x00\x00\x00\x00', data=b'', **kwargs)[source]¶

Make ICMP Time Exceeded message.

Parameters:

type (Type) – ICMP type.
message (TimeExceeded | None) – message data.
unused (bytes) – the four unused octets.
data (bytes) – internet header plus the first eight octets of the original datagram’s payload.
**kwargs (Any) – arbitrary keyword arguments.

Return type:

TimeExceeded

Returns:

Constructed message body schema.

Raises:

ProtocolError – If unused is not four octets.

_make_data_type_parameter_problem(type, message=None, *, pointer=0, unused=b'\x00\x00\x00', data=b'', **kwargs)[source]¶

Make ICMP Parameter Problem message.

Parameters:

type (Type) – ICMP type.
message (ParameterProblem | None) – message data.
pointer (int) – pointer to the octet of the original datagram that caused the error.
unused (bytes) – the three unused octets.
data (bytes) – internet header plus the first eight octets of the original datagram’s payload.
**kwargs (Any) – arbitrary keyword arguments.

Return type:

ParameterProblem

Returns:

Constructed message body schema.

Raises:

ProtocolError – If unused is not three octets.

__type__: DefaultDict[Type | int, str | tuple[Callable[[ICMPv4Type, ICMPv4, int], ICMPv4], Callable[[Type, ICMPv4 | None, Any], ICMPv4Type]]]¶: Type code to method mapping. A str value names the methods _read_data_type_${name} and _make_data_type_${name}, falling back to _read_data_type_none / _make_data_type_none when they do not exist; any other value is a (parser, constructor) pair of callables.

__length_hint__()[source]¶

Return an estimated length for the object.

Return type:: Literal[4]

classmethod __index__()[source]¶

Numeral registry index of the protocol.

Return type:: TransType
Returns:: Numeral registry index of the protocol in IANA.

Header Schemas¶

class pcapkit.protocols.schema.internet.icmpv4.ICMPv4(type=NO_VALUE, code=NO_VALUE, checksum=NO_VALUE, data=NO_VALUE, *, __packet__=None, **kwargs)[source]¶

Bases: Schema

Header schema for ICMP packet.

type: Type = <EnumField type>¶: ICMP type.

code: int = <UInt8Field code>¶: ICMP code.

checksum: bytes = <BytesField checksum>¶: Checksum.

data: ICMPv4Type = <SwitchField data>¶: Message body, selected by type.

class pcapkit.protocols.schema.internet.icmpv4.ICMPv4Type(*args, **kwargs)[source]¶

Bases: EnumSchema[Type]

Header schema for ICMP type-specific message body.

class pcapkit.protocols.schema.internet.icmpv4.Unknown(data=NO_VALUE, *, __packet__=None, **kwargs)[source]¶

Bases: ICMPv4Type

Header schema for ICMP message of unknown type.

data: bytes = <BytesField data>¶: Message body.

class pcapkit.protocols.schema.internet.icmpv4.Echo(id=NO_VALUE, seq=NO_VALUE, data=NO_VALUE, *, __packet__=None, **kwargs)[source]¶

Bases: ICMPv4Type

Header schema for ICMP Echo Request/Reply message.

id: int = <UInt16Field id>¶: Identifier.

seq: int = <UInt16Field seq>¶: Sequence number.

data: bytes = <BytesField data>¶: Data.

class pcapkit.protocols.schema.internet.icmpv4.DestinationUnreachable(unused=NO_VALUE, data=NO_VALUE, *, __packet__=None, **kwargs)[source]¶

Bases: ICMPv4Type

Header schema for ICMP Destination Unreachable message.

unused: bytes = <PaddingField unused>¶: Unused.

data: bytes = <BytesField data>¶: Internet header plus the first eight octets of the original datagram’s payload.

class pcapkit.protocols.schema.internet.icmpv4.TimeExceeded(unused=NO_VALUE, data=NO_VALUE, *, __packet__=None, **kwargs)[source]¶

Bases: ICMPv4Type

Header schema for ICMP Time Exceeded message.

unused: bytes = <PaddingField unused>¶: Unused.

data: bytes = <BytesField data>¶: Internet header plus the first eight octets of the original datagram’s payload.

class pcapkit.protocols.schema.internet.icmpv4.ParameterProblem(pointer=NO_VALUE, unused=NO_VALUE, data=NO_VALUE, *, __packet__=None, **kwargs)[source]¶

Bases: ICMPv4Type

Header schema for ICMP Parameter Problem message.

pointer: int = <UInt8Field pointer>¶: Pointer.

unused: bytes = <PaddingField unused>¶: Unused.

data: bytes = <BytesField data>¶: Internet header plus the first eight octets of the original datagram’s payload.

Auxiliary Functions¶

pcapkit.protocols.schema.internet.icmpv4.icmpv4_data_selector(pkt)[source]¶

Selector function for ICMPv4.data field.

Parameters:: pkt (dict[str, Any]) – Packet data.
Return type:: FieldBase
Returns:: A SchemaField wrapped ICMPv4Type instance based on ICMPv4.type.

Data Models¶

class pcapkit.protocols.data.internet.icmpv4.ICMPv4(*args, **kwargs)[source]¶

Bases: Protocol

Data model for ICMP protocol.

The fields below are the only ones every ICMP message shares (RFC 792); what follows them is read entirely differently depending on type, which is why each message kind below adds its own fields rather than this base class growing a union of them all.

type: Type¶: ICMP type.

code: int¶: ICMP code. Left untyped as a bare int here because its meaning is entirely type-dependent; each subclass below documents which registry (if any) its own code values are drawn from.

checksum: bytes¶: Checksum.

length: int¶: Message length, in octets, header included. ICMP messages carry no length field of their own – this is simply how many octets ICMPv4.read was handed, kept here so the whole message can be told apart from a truncated capture.

checksum_status: ChecksumStatus¶: Outcome of verifying checksum, present only when CHECKSUM_VERIFY is on.

class pcapkit.protocols.data.internet.icmpv4.Unknown(type, code, checksum, length, data)[source]¶

Bases: ICMPv4

Data model for ICMP packet of unknown type.

code carries no pcapkit.const registry for a type this package does not recognise, so it is read as a bare int.

data: bytes¶: Message body, as captured.

class pcapkit.protocols.data.internet.icmpv4.Echo(type, code, checksum, length, id, seq, data)[source]¶

Bases: ICMPv4

Data model for ICMP Echo Request/Reply message (types 8 and 0).

code is always 0 for both types (RFC 792), so it is read as a bare int rather than typed against a registry of one member.

id: int¶: Identifier.

seq: int¶: Sequence number.

data: bytes¶: Data, echoed back verbatim by a reply to the same identifier and sequence number.

class pcapkit.protocols.data.internet.icmpv4.DestinationUnreachable(type, code, checksum, length, unused, data)[source]¶

Bases: ICMPv4

Data model for ICMP Destination Unreachable message (type 3).