IPv4 - Internet Protocol version 4

pcapkit.protocols.internet.ipv4 contains IPv4 only, which implements extractor for Internet Protocol version 4 (IPv4) [*], whose structure is described as below:

Octets	Bits	Name	Description
0	0	ip.version	Version (4)
0	4	ip.hdr_len	Internal Header Length (IHL)
1	8	ip.tos.pre	Precedence
1	11	ip.tos.del	Delay
1	12	ip.tos.thr	Throughput
1	13	ip.tos.rel	Reliability
1	14	ip.tos.ecn	Explicit Congestion Notification (ECN)
2	16	ip.len	Total Length
4	32	ip.id	Identification
6	48		Reserved Bit (must be \x00)
6	49	ip.flags.df	Don’t Fragment (DF)
6	50	ip.flags.mf	More Fragments (MF)
6	51	ip.offset	Fragment Offset
8	64	ip.ttl	Time To Live (TTL)
9	72	ip.protocol	Protocol (Transport Layer)
10	80	ip.checksum	Header Checksum
12	96	ip.src	Source IP Address
16	128	ip.dst	Destination IP Address
20	160	ip.options	IP Options (if IHL > 5)

class pcapkit.protocols.internet.ipv4.IPv4(file=None, length=None, **kwargs)

Bases: IP[IPv4, IPv4]

This class implements Internet Protocol version 4.

This class currently supports parsing of the following IPv4 options, which are registered in the self.__option__ attribute:

Option Code	Option Parser	Option Constructor
EOOL	_read_opt_eool()	_make_opt_eool()
NOP	_read_opt_nop()	_make_opt_nop()
SEC	_read_opt_sec()	_make_opt_sec()
LSR	_read_opt_lsr()	_make_opt_lsr()
TS	_read_opt_ts()	_make_opt_ts()
E_SEC	_read_opt_e_sec()	_make_opt_e_sec()
RR	_read_opt_rr()	_make_opt_rr()
SID	_read_opt_sid()	_make_opt_sid()
SSR	_read_opt_ssr()	_make_opt_ssr()
MTUP	_read_opt_mtup()	_make_opt_mtup()
MTUR	_read_opt_mtur()	_make_opt_mtur()
TR	_read_opt_tr()	_make_opt_tr()
RTRALT	_read_opt_rtralt()	_make_opt_rtralt()
QS	_read_opt_qs()	_make_opt_qs()

property name: Literal['Internet Protocol version 4']

Name of corresponding protocol.

property length: int

Header length of corresponding protocol.

property protocol: TransType

Name of next layer protocol.

property src: IPv4Address

Source IP address.

property dst: IPv4Address

Destination IP address.

classmethod id()

Index ID of the protocol.

Return type:

tuple[Literal['IPv4']]

Returns:

Index ID of the protocol.

classmethod register_option(code, meth)

Register an option parser.

Parameters:

• code (OptionNumber) – IPv4 option code.

• meth (str | tuple[Callable[[Option, OrderedMultiDict[OptionNumber, Option]], Option], Callable[[OptionNumber, Option | None, Any], Option]]) – Method name or callable to parse and/or construct the option.

read(length=None, *, __packet__=None, **kwargs)

Read Internet Protocol version 4 (IPv4).

Structure of IPv4 header [RFC 791]:

 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Version|  IHL  |Type of Service|          Total Length         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|         Identification        |Flags|      Fragment Offset    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  Time to Live |    Protocol   |         Header Checksum       |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       Source Address                          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                    Destination Address                        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                    Options                    |    Padding    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parameters:

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

• __packet__ (dict[str, Any] | None) – Optional packet data.

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

Return type:

IPv4

Returns:

Parsed packet data.

make(tos_pre=<ToSPrecedence.Routine: 0>, tos_pre_default=None, tos_pre_namespace=None, tos_pre_reversed=False, tos_del=<ToSDelay.NORMAL: 0>, tos_del_default=None, tos_del_namespace=None, tos_del_reversed=False, tos_thr=<ToSThroughput.NORMAL: 0>, tos_thr_default=None, tos_thr_namespace=None, tos_thr_reversed=False, tos_rel=<ToSReliability.NORMAL: 0>, tos_rel_default=None, tos_rel_namespace=None, tos_rel_reversed=False, tos_ecn=<ToSECN.Not_ECT: 0>, tos_ecn_default=None, tos_ecn_namespace=None, tos_ecn_reversed=False, id=0, df=False, mf=False, offset=0, ttl=0, protocol=<TransType.UDP: 17>, protocol_default=None, protocol_namespace=None, protocol_reversed=False, checksum=b'\\x00\\x00', src='127.0.0.1', dst='0.0.0.0', options=None, payload=b'', **kwargs)

Make (construct) packet data.

Parameters:

• tos_pre (ToSPrecedence | IntEnum | IntEnum | int | str) – Precedence of the packet.

• tos_pre_default (int | None) – Default value of tos_pre.

• tos_pre_namespace (dict[str, int] | dict[int, str] | Type[IntEnum] | Type[IntEnum] | None) – Namespace of tos_pre.

• tos_pre_reversed (bool) – If the namespace of tos_pre is reversed.

• tos_del (ToSDelay | IntEnum | IntEnum | int | str) – Delay of the packet.

• tos_del_default (int | None) – Default value of tos_del.

• tos_del_namespace (dict[str, int] | dict[int, str] | Type[IntEnum] | Type[IntEnum] | None) – Namespace of tos_del.

• tos_del_reversed (bool) – If the namespace of tos_del is reversed.

• tos_thr (ToSThroughput | IntEnum | IntEnum | int | str) – Throughput of the packet.

• tos_thr_default (int | None) – Default value of tos_thr.

• tos_thr_namespace (dict[str, int] | dict[int, str] | Type[IntEnum] | Type[IntEnum] | None) – Namespace of tos_thr.

• tos_thr_reversed (bool) – If the namespace of tos_thr is reversed.

• tos_rel (ToSReliability | IntEnum | IntEnum | int | str) – Reliability of the packet.

• tos_rel_default (int | None) – Default value of tos_rel.

• tos_rel_namespace (dict[str, int] | dict[int, str] | Type[IntEnum] | Type[IntEnum] | None) – Namespace of tos_rel.

• tos_rel_reversed (bool) – If the namespace of tos_rel is reversed.

• tos_ecn (ToSECN | IntEnum | IntEnum | int | str) – ECN of the packet.

• tos_ecn_default (int | None) – Default value of tos_ecn.

• tos_ecn_namespace (dict[str, int] | dict[int, str] | Type[IntEnum] | Type[IntEnum] | None) – Namespace of tos_ecn.

• tos_ecn_reversed (bool) – If the namespace of tos_ecn is reversed.

• id (int) – Identification of the packet.

• df (bool) – Don’t fragment flag.

• mf (bool) – More fragments flag.

• offset (int) – Fragment offset.

• ttl (timedelta | int) – Time to live of the packet.

• protocol (TransType | IntEnum | IntEnum | int | str) – Payload protocol of the packet.

• protocol_default (int | None) – Default value of protocol.

• protocol_namespace (dict[str, int] | dict[int, str] | Type[IntEnum] | Type[IntEnum] | None) – Namespace of protocol.

• protocol_reversed (bool) – If the namespace of protocol is reversed.

• checksum (bytes) – Checksum of the packet.

• src (IPv4Address | str | int | bytes) – Source address of the packet.

• dst (IPv4Address | str | int | bytes) – Destination address of the packet.

• options (list[Option | tuple[OptionNumber, dict[str, Any]] | bytes] | OrderedMultiDict[OptionNumber, Option] | None) – Options of the packet.

• payload (bytes | ProtocolBase | Schema) – Payload of the packet.

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

Return type:

IPv4

Returns:

Constructed packet data.

classmethod _make_data(data)

Create key-value pairs from data for protocol construction.

Parameters:

data (IPv4) – protocol data

Return type:

dict[str, Any]

Returns:

Key-value pairs for protocol construction.

_read_ipv4_options(length)

Read IPv4 option list.

Parameters:

length (int) – length of options

Return type:

OrderedMultiDict[OptionNumber, Option]

Returns:

Extracted IPv4 options.

Raises:

ProtocolError – If the threshold is NOT matching.

_read_opt_unassigned(schema, *, options)

Read IPv4 unassigned options.

Structure of IPv4 unassigned options [RFC 791]:

 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      |    length     |         option data ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parameters:

• schema (UnassignedOption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

UnassignedOption

Returns:

Parsed option data.

Raises:

ProtocolError – If length is LESS THAN 3.

_read_opt_eool(schema, *, options)

Read IPv4 End of Option List (EOOL) option.

Structure of IPv4 End of Option List (EOOL) option [RFC 719]:

+--------+
|00000000|
+--------+
  Type=0

Parameters:

• schema (EOOLOption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

EOOLOption

Returns:

Parsed option data.

_read_opt_nop(schema, *, options)

Read IPv4 No Operation (NOP) option.

Structure of IPv4 No Operation (NOP) option [RFC 719]:

+--------+
|00000001|
+--------+
  Type=1

Parameters:

• schema (NOPOption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

NOPOption

Returns:

Parsed option data.

_read_opt_sec(schema, *, options)

Read IPv4 Security (SEC) option.

Structure of IPv4 Security (SEC) option [RFC 1108]:

+------------+------------+------------+-------------//----------+
|  10000010  |  XXXXXXXX  |  SSSSSSSS  |  AAAAAAA[1]    AAAAAAA0 |
|            |            |            |         [0]             |
+------------+------------+------------+-------------//----------+
  TYPE = 130     LENGTH   CLASSIFICATION         PROTECTION
                               LEVEL              AUTHORITY
                                                    FLAGS

Parameters:

• schema (SECOption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

SECOption

Returns:

Parsed option data.

Raises:

ProtocolError – If length is LESS THAN 3.

_read_opt_lsr(schema, *, options)

Read IPv4 Loose Source Route (LSR) option.

Structure of IPv4 Loose Source Route (LSR) option [RFC 791]:

+--------+--------+--------+---------//--------+
|10000011| length | pointer|     route data    |
+--------+--------+--------+---------//--------+

Parameters:

• schema (LSROption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

LSROption

Returns:

Parsed option data.

Raises:

ProtocolError – If option is malformed.

_read_opt_ts(schema, *, options)

Read IPv4 Time Stamp (TS) option.

Structure of IPv4 Time Stamp (TS) option [RFC 791]:

+--------+--------+--------+--------+
|01000100| length | pointer|oflw|flg|
+--------+--------+--------+--------+
|         internet address          |
+--------+--------+--------+--------+
|             timestamp             |
+--------+--------+--------+--------+
|                 .                 |
                  .
                  .

Parameters:

• schema (TSOption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

TSOption

Returns:

Parsed option data.

Raises:

ProtocolError – If the option is malformed.

_read_opt_e_sec(schema, *, options)

Read IPv4 Extended Security (E-SEC) option.

Structure of IPv4 Extended Security (E-SEC) option [RFC 1108]:

+------------+------------+------------+-------//-------+
|  10000101  |  000LLLLL  |  AAAAAAAA  |  add sec info  |
+------------+------------+------------+-------//-------+
 TYPE = 133      LENGTH     ADDITIONAL      ADDITIONAL
                           SECURITY INFO     SECURITY
                            FORMAT CODE        INFO

Parameters:

• schema (ESECOption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

ESECOption

Returns:

Parsed option data.

Raises:

ProtocolError – If length is LESS THAN 3.

_read_opt_rr(schema, *, options)

Read IPv4 Record Route (RR) option.

Structure of IPv4 Record Route (RR) option [RFC 791]:

+--------+--------+--------+---------//--------+
|00000111| length | pointer|     route data    |
+--------+--------+--------+---------//--------+
  Type=7

Parameters:

• schema (RROption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

RROption

Returns:

Parsed option data.

Raises:

ProtocolError – If option is malformed.

_read_opt_sid(schema, *, options)

Read IPv4 Stream ID (SID) option.

Structure of IPv4 Stream ID (SID) option [RFC 791][RFC 6814]:

+--------+--------+--------+--------+
|10001000|00000010|    Stream ID    |
+--------+--------+--------+--------+
 Type=136 Length=4

Parameters:

• schema (SIDOption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

SIDOption

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 4.

_read_opt_ssr(schema, *, options)

Read IPv4 Strict Source Route (SSR) option.

Structure of IPv4 Strict Source Route (SSR) option [RFC 791]:

+--------+--------+--------+---------//--------+
|10001001| length | pointer|     route data    |
+--------+--------+--------+---------//--------+
 Type=137

Parameters:

• schema (SSROption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

SSROption

Returns:

Parsed option data.

Raises:

ProtocolError – If option is malformed.

_read_opt_mtup(schema, *, options)

Read IPv4 MTU Probe (MTUP) option.

Structure of IPv4 MTU Probe (MTUP) option [RFC 1063][RFC 1191]:

+--------+--------+--------+--------+
|00001011|00000100|   2 octet value |
+--------+--------+--------+--------+

Parameters:

• schema (MTUPOption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

MTUPOption

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 4.

_read_opt_mtur(schema, *, options)

Read IPv4 MTU Reply (MTUR) option.

Structure of IPv4 MTU Reply (MTUR) option [RFC 1063][RFC 1191]:

+--------+--------+--------+--------+
|00001100|00000100|   2 octet value |
+--------+--------+--------+--------+

Parameters:

• schema (MTUROption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

MTUROption

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 4.

_read_opt_tr(schema, *, options)

Read IPv4 Traceroute (TR) option.

Structure of IPv4 Traceroute (TR) option [RFC 1393][RFC 6814]:

 0               8              16              24
+-+-+-+-+-+-+-+-+---------------+---------------+---------------+
|F| C |  Number |    Length     |          ID Number            |
+-+-+-+-+-+-+-+-+---------------+---------------+---------------+
|      Outbound Hop Count       |       Return Hop Count        |
+---------------+---------------+---------------+---------------+
|                     Originator IP Address                     |
+---------------+---------------+---------------+---------------+

Parameters:

• schema (TROption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

TROption

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 12.

_read_opt_rtralt(schema, *, options)

Read IPv4 Router Alert (RTRALT) option.

Structure of IPv4 Router Alert (RTRALT) option [RFC 2113]:

+--------+--------+--------+--------+
|10010100|00000100|  2 octet value  |
+--------+--------+--------+--------+

Parameters:

• schema (RTRALTOption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

RTRALTOption

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 4.

_read_opt_qs(schema, *, options)

Read IPv4 Quick Start (QS) option.

Structure of IPv4 Quick Start (QS) option [RFC 4782]:

• A Quick-Start Request

   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
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |   Option      |  Length=8     | Func. | Rate  |   QS TTL      |
  |               |               | 0000  |Request|               |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                        QS Nonce                           | R |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  

• Report of Approved Rate

   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
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |   Option      |  Length=8     | Func. | Rate  |   Not Used    |
  |               |               | 1000  | Report|               |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                        QS Nonce                           | R |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  

Parameters:

• schema (QSOption) – parsed option schema

• options (OrderedMultiDict[OptionNumber, Option]) – extracted IPv4 options

Return type:

QSOption

Returns:

Parsed option data.

Raises:

ProtocolError – If the option is malformed.

_make_ipv4_options(options)

Make options for IPv4.

Parameters:

option – IPv4 options

Return type:

tuple[list[Option | bytes], int]

Returns:

Tuple of options and total length of options.

_make_opt_unassigned(kind, option=None, *, data, **kwargs)

Make IPv4 unassigned options.

Parameters:

• kind (OptionNumber) – option type code

• option (UnassignedOption | None) – option data

• data (bytes) – option payload

• **kwargs (Any) – arbitrary keyword arguments

Return type:

Option

Returns:

Constructured option schema.

_make_opt_eool(kind, option=None, **kwargs)

Make IPv4 End of Option List (EOOL) option.

Parameters:

• kind (OptionNumber) – option type code

• option (EOOLOption | None) – option data

• **kwargs (Any) – arbitrary keyword arguments

Return type:

EOOLOption

Returns:

Constructured option schema.

_make_opt_nop(kind, option=None, **kwargs)

Make IPv4 No Operation (NOP) option.

Parameters:

• kind (OptionNumber) – option type code

• option (NOPOption | None) – option data

• **kwargs (Any) – arbitrary keyword arguments

Return type:

NOPOption

Returns:

Constructured option schema.

_make_opt_sec(kind, option=None, *, level=<ClassificationLevel.Unclassified: 171>, level_default=None, level_namespace=None, level_reversed=False, authorities=None, **kwargs)

Make IPv4 Security (SEC) option.

Parameters:

• kind (OptionNumber) – option type code

• option (SECOption | None) – option data

• level (ClassificationLevel | IntEnum | IntEnum | int | str) – classification level

• level_default (int | None) – default value for classification level

• level_namespace (dict[str, int] | dict[int, str] | Type[IntEnum] | Type[IntEnum] | None) – namespace for classification level

• level_reversed (bool) – whether classification level is reversed

• authorities (list[ProtectionAuthority] | None) – list of protection authority flags

• **kwargs (Any) – arbitrary keyword arguments

Return type:

SECOption

Returns:

Constructured option schema.

Raises:

ProtocolError – If authorities names a bit position that is not a protection authority – a negative one, or one that RFC 1108 reserves as a field termination indicator.

Notes

RFC 1108 section 2.2 lays each protection authority octet out as seven authority bits followed by a field termination indicator in bit 0: 0 means another octet follows, 1 means this is the last. So the authority numbering skips every position that is a termination bit – 7, 15, 23 – which is what _read_opt_sec() encodes by looping over range(7) per octet, and the reason Field_Termination_Indicator is rejected here rather than written: the enumeration names it as structure, and a value written there would be dropped on the way back in. See #537.

_make_opt_lsr(kind, option=None, *, counts=10, route=None, **kwargs)

Make IPv4 Loose Source and Record Route (LSR) option.

Parameters:

• kind (OptionNumber) – option type code

• option (LSROption | None) – option data

• counts (int) – maximum number of addresses to record

• route (list[IPv4Address | str | bytes | int] | None) – list of IPv4 addresses as recorded routes

• **kwargs (Any) – arbitrary keyword arguments

Return type:

LSROption

Returns:

Constructured option schema.

_make_opt_ts(kind, option=None, *, counts=5, overflow=0, timestamp=None, **kwargs)

Make IPv4 Timestamp (TS) option.

Parameters:

• kind (OptionNumber) – option type code

• option (TSOption | None) – option data

• counts (int) – maximum number of timestamps to record

• timestamp (list[int | timedelta] | dict[IPv4Address, int | timedelta] | None) – list of timestamps

• **kwargs (Any) – arbitrary keyword arguments

Return type:

TSOption

Returns:

Constructured option schema.

_make_opt_e_sec(kind, option=None, *, format=0, info=None, **kwargs)

Make IPv4 Extended Security (E-SEC) option.

Parameters:

• kind (OptionNumber) – option type code

• option (ESECOption | None) – option data

• format (int) – additional security information format code

• info (bytes | None) – additional security information

• **kwargs (Any) – arbitrary keyword arguments

• Returns – Constructured option schema.

Return type:

ESECOption

_make_opt_rr(kind, option=None, *, counts=10, route=None, **kwargs)

Make IPv4 Record Route (RR) option.

Parameters:

• kind (OptionNumber) – option type code

• option (RROption | None) – option data

• counts (int) – maximum number of addresses to record

• route (list[IPv4Address | str | bytes | int] | None) – list of IPv4 addresses as recorded routes

• **kwargs (Any) – arbitrary keyword arguments

Return type:

RROption

Returns:

Constructured option schema.

_make_opt_sid(kind, option=None, *, sid=0, **kwargs)

Make IPv4 Stream ID (SID) option.

Parameters:

• kind (OptionNumber) – option type code

• option (SIDOption | None) – option data

• sid (int) – stream ID

• **kwargs (Any) – arbitrary keyword arguments

Return type:

SIDOption

Returns:

Constructured option schema.

_make_opt_ssr(kind, option=None, *, counts=10, route=None, **kwargs)

Make IPv4 Strict Source Route (SSR) option.

Parameters:

• kind (OptionNumber) – option type code

• option (SSROption | None) – option data

• counts (int) – maximum number of addresses to record

• route (list[IPv4Address | str | bytes | int] | None) – list of IPv4 addresses as recorded routes

• **kwargs (Any) – arbitrary keyword arguments

Return type:

SSROption

Returns:

Constructured option schema.

_make_opt_mtup(kind, option=None, *, mtu=0, **kwargs)

Make IPv4 MTU Probe (MTUP) option.

Parameters:

• kind (OptionNumber) – option type code

• option (MTUPOption | None) – option data

• mtu (int) – MTU value

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MTUPOption

Returns:

Constructured option schema.

_make_opt_mtur(kind, option=None, *, mtu=0, **kwargs)

Make IPv4 MTU Reply (MTUR) option.

Parameters:

• kind (OptionNumber) – option type code

• option (MTUROption | None) – option data

• mtu (int) – MTU value

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MTUROption

Returns:

Constructured option schema.

_make_opt_tr(kind, option=None, *, id=0, out=0, ret=0, origin='127.0.0.1', **kwargs)

Make IPv4 Traceroute (TR) option.

Parameters:

• kind (OptionNumber) – option type code

• option (TROption | None) – option data

• id (int) – ID number

• out (int) – outbound hop count

• ret (int) – return hop count

• origin (IPv4Address | str | bytes | int) – originator IP address

• **kwargs (Any) – arbitrary keyword arguments

Return type:

TROption

Returns:

Constructured option schema.

_make_opt_rtralt(kind, option=None, *, alert=<RouterAlert.Aggregated_Reservation_Nesting_Level_0: 1>, alert_default=None, alert_namespace=None, alert_reversed=False, **kwargs)

Make IPv4 Router Alert (RTRALT) option.

Parameters:

• kind (OptionNumber) – option type code

• option (RTRALTOption | None) – option data

• alert (RouterAlert | IntEnum | IntEnum | int | str) – router alert type

• alert_default (int | None) – default value for router alert type

• alert_namespace (dict[str, int] | dict[int, str] | Type[IntEnum] | Type[IntEnum] | None) – namespace for router alert type

• alert_reversed (bool) – whether router alert type is reversed

• **kwargs (Any) – arbitrary keyword arguments

Return type:

RTRALTOption

Returns:

Constructured option schema.

_make_opt_qs(kind, option=None, *, func=<QSFunction.Quick_Start_Request: 0>, func_default=None, func_namespace=None, func_reversed=False, rate=0, ttl=0, nonce=0, **kwargs)

Make IPv4 Quick-Start (QS) option.

Parameters:

• kind (OptionNumber) – option type code

• option (QuickStartRequestOption | QuickStartReportOption | None) – option data

• func (QSFunction | IntEnum | IntEnum | str | int) – QS function type

• func_default (int | None) – default value for QS function type

• func_namespace (dict[str, int] | dict[int, str] | Type[IntEnum] | Type[IntEnum] | None) – namespace for QS function type

• func_reversed (bool) – reversed flag for QS function type

• rate (int) – rate (in kbps)

• ttl (timedelta | int) – time to live (in seconds)

• nonce (int) – nonce value

• **kwargs (Any) – arbitrary keyword arguments

Return type:

QSOption

Returns:

Constructured option schema.

__option__: DefaultDict[OptionNumber | int, str | tuple[Callable[[Option, OrderedMultiDict[OptionNumber, Option]], Option], Callable[[OptionNumber, Option | None, Any], Option]]]

DefaultDict[Enum_OptionNumber, str | tuple[OptionParser, OptionConstructor]]: Option code to method mapping, c.f. _read_ipv4_options() and/or _make_ipv4_options(). Method names are expected to be referred to the class by _read_opt_${name} and/or _make_opt_${name}, and if such name not found, the value should then be a method that can parse the option by itself.

classmethod __index__()

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.ipv4.IPv4(*args: _VT, **kwargs: _VT)

Bases: Schema

Header schema for IPv4 packet.

vihl: VerIHLField = <BitField vihl>

Version and header length.

tos: ToSField = <BitField tos>

Type of service.

length: int = <UInt16Field length>

Total length.

id: int = <UInt16Field id>

Identification.

flags: Flags = <BitField flags>

Flags and fragment offset.

ttl: int = <UInt8Field ttl>

Time to live.

proto: TransType = <EnumField proto>

Protocol.

chksum: bytes = <BytesField chksum>

Header checksum.

src: IPv4Address = <IPv4AddressField src>

Source address.

dst: IPv4Address = <IPv4AddressField dst>

Destination address.

options: list[Option] = <OptionField options>

Options.

padding: bytes = <PaddingField padding>

Padding.

payload: bytes = <PayloadField payload>

Payload.

class pcapkit.protocols.schema.internet.ipv4.Option(dict_=None, **kwargs)

Bases: EnumSchema[OptionNumber]

Header schema for IPv4 options.

type: OptionNumber = <EnumField type>

Option type.

length: int = <ConditionalField length>

Option length.

post_process(packet)

Revise schema data after unpacking process.

Parameters:

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

Return type:

Schema

Returns:

Revised schema.

class pcapkit.protocols.schema.internet.ipv4.UnassignedOption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for IPv4 unassigned options.

data: bytes = <BytesField data>

Option data.

class pcapkit.protocols.schema.internet.ipv4.EOOLOption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for IPv4 end of option list (EOOL) option.

class pcapkit.protocols.schema.internet.ipv4.NOPOption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for IPv4 no operation (NOP) option.

class pcapkit.protocols.schema.internet.ipv4.SECOption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for IPv4 security (SEC) option.

level: ClassificationLevel = <EnumField level>

Classification level.

data: bytes = <ConditionalField data>

Protection authority flags.

class pcapkit.protocols.schema.internet.ipv4.LSROption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for IPv4 loose source route (LSR) option.

pointer: int = <UInt8Field pointer>

Pointer.

route: list[IPv4Address] = <ListField route>

Route.

remainder: bytes = <PaddingField remainder>

Remaining data buffer0.

class pcapkit.protocols.schema.internet.ipv4.TSOption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for IPv4 timestamp (TS) option.

pointer: int = <UInt8Field pointer>

Pointer.

flags: TSFlags = <BitField flags>

Overflow and flags.

ts_data: list[int] = <ListField ts_data>

Timestamps and internet addresses.

remainder: bytes = <PaddingField remainder>

Remaining data buffer.

post_process(packet)

Revise schema data after unpacking process.

Parameters:

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

Return type:

Schema

Returns:

Revised schema.

Raises:

FieldValueError – If an entry of ts_data that the timestamp flag makes an address is a bool, is not a valid IP address, or is not IPv4 – c.f. parse_ip_address().

Notes

This runs on the packing path as well as the unpacking one – Schema.pack calls it once the buffer is filled – so the ts_data entries it converts below are whatever the caller passed to the constructor, not octets read off the wire. That is why those conversions go through parse_ip_address() rather than ipaddress.ip_address(): this schema is reachable from public IPv4.make, which accepts a caller-built option schema and packs it, and ts_data’s UInt32Field item type takes a bool as the int it is a subclass of, so nothing downstream can question it. Measured before this fix: ts_data=[True, 5] packed as 0000000100000005 and reported IPv4Address('0.0.0.1') with no exception and no warning. This was the fifth site of that defect – #481, #500, #539 and #540 are the first four – and the reason it is the fifth is that each of those fixed the sites it could see. See #552.

class pcapkit.protocols.schema.internet.ipv4.ESECOption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for IPv4 extended security (ESEC) option.

format: int = <UInt8Field format>

Additional security information format code.

info: bytes = <ConditionalField info>

Additional security information.

class pcapkit.protocols.schema.internet.ipv4.RROption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for IPv4 record route (RR) option.

pointer: int = <UInt8Field pointer>

Pointer.

route: list[IPv4Address] = <ListField route>

Route.

remainder: bytes = <PaddingField remainder>

Remaining data buffer0.

class pcapkit.protocols.schema.internet.ipv4.SIDOption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for IPv4 stream identifier (SID) option.

sid: int = <UInt16Field sid>

Stream identifier. Two octets, per RFC 791 section 3.1, which gives the option as four octets in total: one of type, one of length, and a 16-bit stream identifier. This was a UInt32Field, which over-read a well-formed option by two octets on the way in – the packet length < 0: -2 the library warned about – and re-emitted it two octets too wide on the way out, against the length=4 that _make_opt_sid() had always written. See #534.

class pcapkit.protocols.schema.internet.ipv4.SSROption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for IPv4 strict source route (SSR) option.

pointer: int = <UInt8Field pointer>

Pointer.

route: list[IPv4Address] = <ListField route>

Route.

remainder: bytes = <PaddingField remainder>

Remaining data buffer0.

class pcapkit.protocols.schema.internet.ipv4.MTUPOption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for IPv4 MTU probe (MTUP) option.

mtu: int = <UInt16Field mtu>

MTU.

class pcapkit.protocols.schema.internet.ipv4.MTUROption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for IPv4 MTU reply (MTUR) option.

mtu: int = <UInt16Field mtu>

MTU.

class pcapkit.protocols.schema.internet.ipv4.TROption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for IPv4 traceroute (TR) option.

id: int = <UInt16Field id>

ID number.

out: int = <UInt16Field out>

Outbound hop count.

ret: int = <UInt16Field ret>

Return hop count.

origin: IPv4Address = <IPv4AddressField origin>

Originator IP address.

class pcapkit.protocols.schema.internet.ipv4.RTRALTOption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for IPv4 router alert (RTRALT) option.

alert: RouterAlert = <EnumField alert>

Router alert value.

class pcapkit.protocols.schema.internet.ipv4._QSOption(*args: _VT, **kwargs: _VT)

Bases: Schema

Header schema for IPv4 quick start (QS) options in generic representation.

flags: QSTestFlags = <ForwardMatchField flags>

Flags.

data: QuickStartRequestOption | QuickStartReportOption = <SwitchField data>

QS data.

post_process(packet)

Revise schema data after unpacking process.

Parameters:

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

Return type:

QSOption

Returns:

Revised schema.

class pcapkit.protocols.schema.internet.ipv4.QSOption(dict_=None, **kwargs)

Bases: Option, EnumSchema[QSFunction]

Header schema for IPV4 quick start (QS) options.

flags: QuickStartFlags = <BitField flags>

Flags.

class pcapkit.protocols.schema.internet.ipv4.QuickStartRequestOption(*args: _VT, **kwargs: _VT)

Bases: QSOption

Header schema for IPV4 quick start request options.

ttl: int = <UInt8Field ttl>

QS time-to-live (TTL).

nonce: QSNonce = <BitField nonce>

QS nonce.

class pcapkit.protocols.schema.internet.ipv4.QuickStartReportOption(*args: _VT, **kwargs: _VT)

Bases: QSOption

Header schema for IPV4 quick start report of approved rate options.

reserved: bytes = <PaddingField reserved>

Not used. One octet, holding the place a Quick-Start Request fills with QS TTL: RFC 4782 Section 3.1 says in as many words that “for a Report of Approved Rate, the fourth byte of the Quick-Start Option is not used”, and that “bytes 5-8 contain a 30-bit QS Nonce and a 2-bit Reserved field” – so the nonce begins at the fifth octet for both functions, and figure 4 gives this option as Length=8 like figure 3 gives its sibling. The field was missing, so the schema was seven octets wide against the eight _make_opt_qs() writes into length and the eight _read_opt_qs() demands of it, which meant a spec-correct Report of Approved Rate read off the wire decoded its nonce one octet early – measured, with the selector length fixed and this field still absent: 19088100deadbee0 warned packet length < 0: -1 and then died with a bare struct.error: bad char in struct format, the unconsumed octet having been read as another option. Declared as padding rather than as data because RFC 4782 gives it no meaning and no caller should be setting it. See #552.

nonce: QSNonce = <BitField nonce>

QS nonce.

Type Stubs

class pcapkit.protocols.schema.internet.ipv4.VerIHLField

Bases: TypedDict

Version and header length field.

version: int

IP version.

ihl: int

Internet header length.

class pcapkit.protocols.schema.internet.ipv4.ToSField

Bases: TypedDict

Type of service field.

class pcapkit.protocols.schema.internet.ipv4.Flags

Bases: TypedDict

Flags and fragment offset field.

df: int

Don’t fragment flag.

mf: int

More fragments flag.

offset: int

Fragment offset.

class pcapkit.protocols.schema.internet.ipv4.TSFlags

Bases: TypedDict

Timestamp flags field.

oflw: int

Timestamp overflow flag.

flag: int

Timestamp type flag.

class pcapkit.protocols.schema.internet.ipv4.QuickStartFlags

Bases: TypedDict

Quick-Start flags.

func: int

QS function.

rate: int

Rate request/report.

class pcapkit.protocols.schema.internet.ipv4.QSTestFlags

Bases: TypedDict

Quick start test flag.

func: int

QS function.

class pcapkit.protocols.schema.internet.ipv4.QSNonce

Bases: TypedDict

Quick start nonce field.

nonce: int

Nonce.

Auxiliary Functions

pcapkit.protocols.schema.internet.ipv4.quick_start_option_length(schema)

On-the-wire length, in octets, of a resolved Quick-Start (QS) suboption.

The Quick-Start suboption schemas re-declare the option’s own type and length octets – they inherit them from Option – so what quick_start_data_selector() has to hand the nested SchemaField is the length of the whole option, not of the data after its header. Per RFC 4782 Section 3.1 – figure 3 for a Quick-Start Request and figure 4 for a Report of Approved Rate – that is eight octets for both functions, which differ in what the fourth octet holds rather than in how many there are: “The second byte contains the length field, indicating an option length of eight bytes”, and “For a Report of Approved Rate, the fourth byte of the Quick-Start Option is not used”. And _read_opt_qs() rejects any other value in the length field outright.

It is summed from the resolved schema’s own fields rather than written as that literal, for two reasons. The registry is open – QSOption is an EnumSchema, so a caller may register a further function code with a schema of its own width – and a number written here has to be kept in step by hand with every field the suboptions declare, which is precisely how #552 arose: the length was 5, the width of a Quick-Start Request’s ttl and nonce alone, with the type, length and flags octets in front of them unaccounted for.

Parameters:

schema (Type[QSOption]) – Quick-Start suboption schema, as resolved from the func sub-field by quick_start_data_selector().

Return type:

int

Returns:

Length, in octets, that schema occupies on the wire.

Raises:

FieldValueError – If schema declares a field whose width is not fixed. Every field of a Quick-Start suboption is fixed-width, because the option is, and a variable-width one cannot be summed here without a packet to size it against – which is the one thing a selector does not have for the schema it is about to return. It fails rather than guessing, since guessing is the defect being fixed.

pcapkit.protocols.schema.internet.ipv4.quick_start_data_selector(pkt)

Selector function for _QSOption.data field.

Parameters:

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

Return type:

FieldBase

Returns:

• If func is 0, returns a SchemaField wrapped QuickStartRequestOption instance.

• If func is 8, returns a SchemaField wrapped QuickStartReportOption instance.

Notes

The length handed to the SchemaField comes from quick_start_option_length(), i.e. from the suboption that was just resolved. It used to be the literal 5 for both, which is not the width of either: a well-formed eight-octet Quick-Start Request 1908002adeadbee0 parsed with SchemaWarning: packet length < 0: -3 and decoded its nonce as 55 instead of 933982136, then left three octets to be read as a further, fabricated option – which made the enclosing datagram fail with ProtocolError: IPv4: invalid format. That is silent corruption on the way to a misleading failure, and it was logged in review twice before #552 filed it.

Data Models

class pcapkit.protocols.data.internet.ipv4.IPv4(*args: VT, **kwargs: VT)

Bases: Protocol

Data model for IPv4 packet.

version: Literal[4]

Version.

hdr_len: int

Internet header length.

tos: ToSField

Type of services.

len: int

Total length.

id: int

Identification.

flags: Flags

Flags.

offset: int

Fragment offset.

ttl: timedelta

Time to live.

protocol: TransType

Protocol.

checksum: bytes

Header checksum.

src: IPv4Address

Source address.

dst: IPv4Address

Destination address.

class pcapkit.protocols.data.internet.ipv4.ToSField(*args: Any, **kwargs: Any)

Bases: Data

Data model for IPv4 ToS fields.

Important

Due to the preserved keyword conflict, please use from_dict() to create an instance of this data model.

del: pcapkit.const.ipv4.tos_del.ToSDelay

Delay.

Note

This field is conflict with del keyword. To access this field, directly use getattr() instead.

pre: ToSPrecedence

Precedence.

thr: ToSThroughput

Throughput.

rel: ToSReliability

Reliability.

ecn: ToSECN

Explicit congestion notification (ECN).

class pcapkit.protocols.data.internet.ipv4.Flags(*args: VT, **kwargs: VT)

Bases: Data

Data model for IPv4 Flags.

df: bool

Don’t fragment.

mf: bool

More fragments.

class pcapkit.protocols.data.internet.ipv4.Option(dict_=None, **kwargs)

Bases: Data

Data model for IPv4 options.

code: OptionNumber

Option code.

length: int

Option length.

type: OptionType

Option type.

class pcapkit.protocols.data.internet.ipv4.OptionType(*args: Any, **kwargs: Any)

Bases: Data

Data model for IPv4 option type data.

class: pcapkit.const.ipv4.option_class.OptionClass

Option class.

Note

This field is conflict with class keyword. To access this field, directly use getattr() instead.

change: bool

Change flag.

number: int

Number.

class pcapkit.protocols.data.internet.ipv4.UnassignedOption(*args: VT, **kwargs: VT)

Bases: Option

Data model for IPv4 unassigned option.

data: bytes

Option data.

class pcapkit.protocols.data.internet.ipv4.EOOLOption(*args: VT, **kwargs: VT)

Bases: Option

Data model for IPv4 End of Option List (EOOL) option.

class pcapkit.protocols.data.internet.ipv4.NOPOption(*args: VT, **kwargs: VT)

Bases: Option

Data model for IPv4 No Operation (NOP) option.

class pcapkit.protocols.data.internet.ipv4.SECOption(*args: VT, **kwargs: VT)

Bases: Option

Data model for IPv4 Security (SEC) option.

level: ClassificationLevel

Classification level.

flags: tuple[ProtectionAuthority, ...]

Protection authority flags.

class pcapkit.protocols.data.internet.ipv4.LSROption(*args: VT, **kwargs: VT)

Bases: Option

Data model for IPv4 Loose Source Route (LSR) option.

pointer: int

Pointer.

route: tuple[IPv4Address, ...]

Route.

class pcapkit.protocols.data.internet.ipv4.TSOption(*args: VT, **kwargs: VT)

Bases: Option

Data model for IPv4 Time Stamp (TS) option.

pointer: int

Pointer.

overflow: int

Overflow.

flag: TSFlag

Flag.

timestamp: tuple[timedelta | int, ...] | OrderedMultiDict[IPv4Address, timedelta | int]

Timestamp data.

class pcapkit.protocols.data.internet.ipv4.ESECOption(*args: VT, **kwargs: VT)

Bases: Option

Data model for IPv4 Extended Security (ESEC) option.

format: int

Additional security information format code.

info: bytes

Additional security information.

class pcapkit.protocols.data.internet.ipv4.RROption(*args: VT, **kwargs: VT)

Bases: Option

Data model for IPv4 Record Route (RR) option.

pointer: int

Pointer.

route: tuple[IPv4Address, ...] | None

Route.

class pcapkit.protocols.data.internet.ipv4.SIDOption(*args: VT, **kwargs: VT)

Bases: Option

Data model for IPv4 Stream ID (SID) option.

sid: int

Stream ID.

class pcapkit.protocols.data.internet.ipv4.SSROption(*args: VT, **kwargs: VT)

Bases: Option

Data model for IPv4 Strict Source Route (SSR) option.

pointer: int

Pointer.

route: tuple[IPv4Address, ...] | None

Route.

class pcapkit.protocols.data.internet.ipv4.MTUPOption(*args: VT, **kwargs: VT)

Bases: Option

Data model for IPv4 MTU Probe (MTUP) option.

mtu: int

MTU.

class pcapkit.protocols.data.internet.ipv4.MTUROption(*args: VT, **kwargs: VT)

Bases: Option

Data model for IPv4 MTU Reply (MTUR) option.

mtu: int

MTU.

class pcapkit.protocols.data.internet.ipv4.TROption(*args: Any, **kwargs: Any)

Bases: Option

Data model for IPv4 Traceroute (TR) option.

Important

Due to the preserved keyword conflict, please use from_dict() to create an instance of this data model.

return: int

Return hop count.

Note

This field is conflict with return keyword. To access this field, directly use getattr() instead.

id: int

ID number.

outbound: int

Outbound hop count.

class pcapkit.protocols.data.internet.ipv4.RTRALTOption(*args: VT, **kwargs: VT)

Bases: Option

Data model for IPv4 Router Alert (RTRALT) option.

alert: RouterAlert

Router alert.

class pcapkit.protocols.data.internet.ipv4.QSOption(dict_=None, **kwargs)

Bases: Option

Data model for IPv4 Quick Start (QS) option.

func: QSFunction

QS function.

rate: int

Rate request/report.

Footnotes

[*]

https://en.wikipedia.org/wiki/IPv4