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.dsfield.dscp

Differentiated Services Code Point (DSCP)

1

14

ip.dsfield.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.frag_offset

Fragment Offset

8

64

ip.ttl

Time To Live (TTL)

9

72

ip.proto

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)[source]

Bases: pcapkit.protocols.internet.ip.IP

This class implements Internet Protocol version 4.

classmethod __index__()[source]

Numeral registry index of the protocol.

Returns

Numeral registry index of the protocol in IANA.

Return type

pcapkit.const.reg.transtype.TransType

__length_hint__()[source]

Return an estimated length for the object.

Return type

Literal[20]

_read_ipv4_addr()[source]

Read IP address.

Returns

Parsed IP address.

Return type

ipaddress.IPv4Address

_read_ipv4_options(size=None)[source]

Read IPv4 option list.

Parameters

size (Optional[int]) – buffer size

Returns

Tuple[Tuple[pcapkit.const.ipv4.option_number.OptionNumber], Dict[str, Union[DataType_Opt, Tuple[DataType_Opt]]]]: IPv4 option list and extracted IPv4 options

_read_mode_donone(size, kind)[source]

Read options require no process.

Parameters
  • size (int) – length of option

  • kind (int) – option kind value

Returns

extracted option

Return type

DataType_Opt_Do_None

Raises

ProtocolError – If size is LESS THAN 3.

_read_mode_qs(size, kind)[source]

Read Quick Start option.

Structure of 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
  • size (int) – length of option

  • kind (Literal[25]) – option kind value (QS)

Returns

extracted Quick Start option

Return type

DataType_Opt_QuickStart

Raises

ProtocolError – If the option is malformed.

_read_mode_route(size, kind)[source]

Read options with route data.

Structure of these options [RFC 791]:

  • Loose Source Route

    +--------+--------+--------+---------//--------+
    |10000011| length | pointer|     route data    |
    +--------+--------+--------+---------//--------+
    
  • Strict Source Route

    +--------+--------+--------+---------//--------+
    |10001001| length | pointer|     route data    |
    +--------+--------+--------+---------//--------+
    
  • Record Route

    +--------+--------+--------+---------//--------+
    |00000111| length | pointer|     route data    |
    +--------+--------+--------+---------//--------+
    
Parameters
  • size (int) – length of option

  • kind (Literal[7, 131, 137]) – option kind value (RR/LSR/SSR)

Returns

extracted option with route data

Return type

DataType_Opt_Route_Data

Raises

ProtocolError – If the option is malformed.

_read_mode_rsralt(size, kind)[source]

Read Router Alert option.

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

+--------+--------+--------+--------+
|10010100|00000100|  2 octet value  |
+--------+--------+--------+--------+
Parameters
  • size (int) – length of option

  • kind (Literal[140]) – option kind value (RTRALT)

Returns

extracted option with security info

Return type

DataType_Opt_RouterAlert

Raises

ProtocolError – If size is NOT 4.

_read_mode_sec(size, kind)[source]

Read options with security info.

Structure of these options [RFC 1108]:

  • Security (SEC)

    +------------+------------+------------+-------------//----------+
    |  10000010  |  XXXXXXXX  |  SSSSSSSS  |  AAAAAAA[1]    AAAAAAA0 |
    |            |            |            |         [0]             |
    +------------+------------+------------+-------------//----------+
      TYPE = 130     LENGTH   CLASSIFICATION         PROTECTION
                                   LEVEL              AUTHORITY
                                                        FLAGS
    
  • Extended Security (ESEC)

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

c

_read_mode_tr(size, kind)[source]

Read Traceroute option.

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

 0               8              16              24
+-+-+-+-+-+-+-+-+---------------+---------------+---------------+
|F| C |  Number |    Length     |          ID Number            |
+-+-+-+-+-+-+-+-+---------------+---------------+---------------+
|      Outbound Hop Count       |       Return Hop Count        |
+---------------+---------------+---------------+---------------+
|                     Originator IP Address                     |
+---------------+---------------+---------------+---------------+
Parameters
  • size (int) – length of option

  • kind (Literal[82]) – option kind value (TR)

Returns

extracted Traceroute option

Return type

DataType_Opt_Traceroute

Raises

ProtocolError – If size is NOT 12.

_read_mode_ts(size, kind)[source]

Read Time Stamp option.

Structure of Timestamp (TS) option [RFC 791]:

+--------+--------+--------+--------+
|01000100| length | pointer|oflw|flg|
+--------+--------+--------+--------+
|         internet address          |
+--------+--------+--------+--------+
|             timestamp             |
+--------+--------+--------+--------+
|                 .                 |
                  .
                  .
Parameters
  • size (int) – length of option

  • kind (Literal[68]) – option kind value (TS)

Returns

extracted Time Stamp option

Return type

DataType_Opt_TimeStamp

Raises

ProtocolError – If the option is malformed.

_read_mode_unpack(size, kind)[source]

Read options require unpack process.

Parameters
  • size (int) – length of option

  • kind (int) – option kind value

Returns

extracted option

Return type

DataType_Opt_Unpack

Raises

ProtocolError – If size is LESS THAN 3.

_read_opt_type(kind)[source]

Read option type field.

Parameters

kind (int) – option kind value

Returns

extracted IPv4 option

Return type

DataType_IPv4_Option_Type

classmethod id()[source]

Index ID of the protocol.

Returns

Index ID of the protocol.

Return type

Literal[‘IPv4’]

make(**kwargs)[source]

Make (construct) packet data.

Keyword Arguments

**kwargs – Arbitrary keyword arguments.

Returns

Constructed packet data.

Return type

bytes

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

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 (Optional[int]) – Length of packet data.

Keyword Arguments

**kwargs – Arbitrary keyword arguments.

Returns

Parsed packet data.

Return type

DataType_IPv4

property length

Header length of corresponding protocol.

Return type

int

property name

Name of corresponding protocol.

Return type

Literal[‘Internet Protocol version 4’]

property protocol

Name of next layer protocol.

Return type

pcapkit.const.reg.transtype.TransType

pcapkit.protocols.internet.ipv4.IPv4_OPT: DataType_IPv4_OPT

IPv4 option dict parsing mapping.

copy

class

number

kind

length

process

name

0

0

0

0

[RFC 791] End of Option List

0

0

1

1

[RFC 791] No-Operation

0

0

7

7

?

2

[RFC 791] Record Route

0

0

11

11

4

1

[RFC 1063][RFC 1191] MTU Probe

0

0

12

12

4

1

[RFC 1063][RFC 1191] MTU Reply

0

0

25

25

8

3

[RFC 4782] Quick-Start

0

2

4

68

?

4

[RFC 791] Time Stamp

0

2

18

82

?

5

[RFC 1393][RFC 6814] Traceroute

1

0

2

130

?

6

[RFC 1108] Security

1

0

3

131

?

2

[RFC 791] Loose Source Route

1

0

5

133

?

6

[RFC 1108] Extended Security

1

0

8

136

4

1

[RFC 791][RFC 6814] Stream ID

1

0

9

137

?

2

[RFC 791] Strict Source Route

1

0

17

145

?

0

[RFC 1385][RFC 6814] Ext. Inet. Protocol

1

0

20

148

4

7

[RFC 2113] Router Alert

pcapkit.protocols.internet.ipv4.process_opt: Dict[int, Callable[[pcapkit.protocols.internet.ipv4.IPv4, int, int], DataType_Opt]]

Process method for IPv4 options.

Code

Method

Description

0

_read_mode_donone()

do nothing

1

_read_mode_unpack()

unpack according to size

2

_read_mode_route()

unpack route data options

3

_read_mode_qs()

unpack Quick-Start

4

_read_mode_ts()

unpack Time Stamp

5

_read_mode_tr()

unpack Traceroute

6

_read_mode_sec()

unpack (Extended) Security

7

_read_mode_rsralt()

unpack Router Alert

Data Structure

Important

Following classes are only for documentation purpose. They do NOT exist in the pcapkit module.

class pcapkit.protocols.internet.ipv4.DataType_IPv4
Bases

TypedDict

Structure of IPv4 header [RFC 791].

version: Literal[4]

Version (4).

hdr_len: int

Internal header length (IHL).

dsfield: DataType_DS_Field

Type of services.

len: int

Total length.

id: int

Identification.

flags: DataType_IPv4_Flags

Flags.

frag_offset: int

Fragment offset.

ttl: int

Time to live (TTL).

proto: pcapkit.const.reg.transtype.TransType

Protocol (transport layer).

checksum: bytes

Header checksum.

src: ipaddress.IPv4Address

Source IP address.

dst: ipaddress.IPv4Address

Destination IP address.

opt: Tuple[pcapkit.const.ipv4.option_number.OptionNumber]

Tuple of option acronyms.

packet: bytes

Rase packet data.

class pcapkit.protocols.internet.ipv4.DataType_DS_Field
Bases

TypedDict

IPv4 DS fields.

dscp: DataType_IPv4_DSCP

Differentiated services code point (DSCP).

ecn: pcapkit.const.ipv4.tos_ecn.ToSECN

Explicit congestion notification (ECN).

class pcapkit.protocols.internet.ipv4.DataType_IPv4_DSCP
Bases

TypedDict

Differentiated services code point (DSCP).

pre: pcapkit.const.ipv4.tos_pre.ToSPrecedence

ToS precedence.

del: pcapkit.const.ipv4.tos_del.ToSDelay

ToS delay.

thr: pcapkit.const.ipv4.tos_thr.ToSThroughput

ToS throughput.

rel: pcapkit.const.ipv4.tos_rel.ToSReliability

ToS reliability.

class pcapkit.protocols.internet.ipv4.DataType_IPv4_Flags
Bases

TypedDict

IPv4 flags.

df: bool

Dont’s fragment (DF).

mf: bool

More fragments (MF).

class pcapkit.protocols.internet.ipv4.DataType_Opt
Bases

TypedDict

IPv4 option data.

kind: int

Option kind.

type: DataType_IPv4_Option_Type

Option type info.

length: int

Option length.

class pcapkit.protocols.internet.ipv4.DataType_IPv4_OPT
Bases

TypedDict

IPv4 option dict parsing mapping.

flag: bool

If the length of option is GREATER THAN 1.

desc: str

Description string, also attribute name.

proc: Optional[int]

Process method that data bytes need (when flag is True).

IPv4 Option Type

For IPv4 option type field as described in RFC 791, its structure is described as below:

Octets

Bits

Name

Descriptions

0

0

ip.opt.type.copy

Copied Flag (0/1)

0

1

ip.opt.type.class

Option Class (0-3)

0

3

ip.opt.type.number

Option Number


class pcapkit.protocols.internet.ipv4.DataType_IPv4_Option_Type
Bases

TypedDict

Structure of option type field [RFC 791].

copy: bool

Copied flag.

class: pcapkit.const.ipv4.option_class.OptionClass

Option class.

number: int

Option number.

IPv4 Miscellaneous Options

1-Byte Options

class pcapkit.protocols.internet.ipv4.DataType_Opt_1_Byte
Bases

DataType_Opt

1-byte options.

length: Literal[1]

Option length.

Permission Options

class pcapkit.protocols.internet.ipv4.DataType_Opt_Permission
Bases

DataType_Opt

Permission options (length is 2).

length: Literal[2]

Option length.

flag: Literal[True]

Permission flag.

No Process Options

For IPv4 options require no process, its structure is described as below:

Octets

Bits

Name

Description

0

0

ip.opt.kind

Kind

0

0

ip.opt.type.copy

Copied Flag

0

1

ip.opt.type.class

Option Class

0

3

ip.opt.type.number

Option Number

1

8

ip.opt.length

Length

2

16

ip.opt.data

Kind-specific Data


class pcapkit.protocols.internet.ipv4.DataType_Opt_Do_None
Bases

DataType_Opt

Structure of IPv4 options.

data: bytes

Kind-specific data.

Unpack Process Options

For IPv4 options require unpack process, its structure is described as below:

Octets

Bits

Name

Description

0

0

ip.opt.kind

Kind

0

0

ip.opt.type.copy

Copied Flag

0

1

ip.opt.type.class

Option Class

0

3

ip.opt.type.number

Option Number

1

8

ip.opt.length

Length

2

16

ip.opt.data

Kind-specific Data


class pcapkit.protocols.internet.ipv4.DataType_Opt_Unpack
Bases

DataType_Opt

Structure of IPv4 options.

data: int

Kind-specific data.

IPv4 Options with Route Data

For IPv4 options with route data as described in RFC 791, its structure is described as below:

Octets

Bits

Name

Description

0

0

ip.opt.kind

Kind (7/131/137)

0

0

ip.opt.type.copy

Copied Flag (0)

0

1

ip.opt.type.class

Option Class (0/1)

0

3

ip.opt.type.number

Option Number (3/7/9)

1

8

ip.opt.length

Length

2

16

ip.opt.pointer

Pointer (≥4)

3

24

ip.opt.data

Route Data


class pcapkit.protocols.internet.ipv4.DataType_Opt_Route_Data
Bases

DataType_Opt

Structure of IPv4 options with route data [RFC 791].

pointer: int

Pointer.

data: Optional[Tuple[ipaddress.IPv4Address]]

Route data.

IPv4 Quick Start Options

For IPv4 Quick Start options as described in RFC 4782, its structure is described as below:

Octets

Bits

Name

Description

0

0

ip.qs.kind

Kind (25)

0

0

ip.qs.type.copy

Copied Flag (0)

0

1

ip.qs.type.class

Option Class (0)

0

3

ip.qs.type.number

Option Number (25)

1

8

ip.qs.length

Length (8)

2

16

ip.qs.func

Function (0/8)

2

20

ip.qs.rate

Rate Request / Report (in Kbps)

3

24

ip.qs.ttl

QS TTL / None

4

32

ip.qs.nounce

QS Nounce

7

62

Reserved (\x00\x00)


class pcapkit.protocols.internet.ipv4.DataType_Opt_QuickStart
Bases

DataType_Opt

Structure of Quick-Start (QS) option [RFC 4782].

func: pcapkit.const.ipv4.qs_function.QSFunction

Function.

rate: int

Rate request / report (in Kbps).

ttl: Optional[int]

QS TTL.

nounce: int

QS nounce.

IPv4 Time Stamp Option

For IPv4 Time Stamp option as described in RFC 791, its structure is described as below:

Octets

Bits

Name

Description

0

0

ip.ts.kind

Kind (25)

0

0

ip.ts.type.copy

Copied Flag (0)

0

1

ip.ts.type.class

Option Class (0)

0

3

ip.ts.type.number

Option Number (25)

1

8

ip.ts.length

Length (≤40)

2

16

ip.ts.pointer

Pointer (≥5)

3

24

ip.ts.overflow

Overflow Octets

3

28

ip.ts.flag

Flag

4

32

ip.ts.ip

Internet Address

8

64

ip.ts.timestamp

Timestamp


class pcapkit.protocols.internet.ipv4.DataType_Opt_TimeStamp
Bases

DataType_Opt

Structure of Timestamp (TS) option [RFC 791].

pointer: int

Pointer.

overflow: int

Overflow octets.

flag: int

Flag.

ip: Optional[Tuple[ipaddress.IPv4Address]]

Array of Internet addresses (if flag is 1/3).

timestamp: Optional[Tuple[datetime.datetime]]

Array of timestamps (if flag is 0/1/3).

data: Optional[bytes]

Timestamp data (if flag is unknown).

IPv4 Traceroute Option

For IPv4 Traceroute option as described in RFC 6814, its structure is described as below:

Octets

Bits

Name

Description

0

0

ip.tr.kind

Kind (82)

0

0

ip.tr.type.copy

Copied Flag (0)

0

1

ip.tr.type.class

Option Class (0)

0

3

ip.tr.type.number

Option Number (18)

1

8

ip.tr.length

Length (12)

2

16

ip.tr.id

ID Number

4

32

ip.tr.ohc

Outbound Hop Count

6

48

ip.tr.rhc

Return Hop Count

8

64

ip.tr.ip

Originator IP Address


class pcapkit.protocols.internet.ipv4.DataType_Opt_Traceroute
Bases

DataType_Opt

Structure of Traceroute (TR) option [RFC 6814].

id: int

ID number.

ohc: int

Outbound hop count.

rhc: int

Return hop count.

ip: ipaddress.IPv4Address

Originator IP address.

IPv4 Options with Security Info

For IPv4 options with security info as described in RFC 1108, its structure is described as below:

Octets

Bits

Name

Description

0

0

ip.sec.kind

Kind (130/133)

0

0

ip.sec.type.copy

Copied Flag (1)

0

1

ip.sec.type.class

Option Class (0)

0

3

ip.sec.type.number

Option Number (2)

1

8

ip.sec.length

Length (≥3)

2

16

ip.sec.level

Classification Level

3

24

ip.sec.flags

Protection Authority Flags


class pcapkit.protocols.internet.ipv4.DataType_Opt_Security_Info
Bases

DataType_Opt

Structure of IPv4 options with security info [RFC 791].

level: pcapkit.const.ipv4.classification_level.ClassificationLevel

Classification level.

flags: Tuple[DataType_SEC_Flags]

Array of protection authority flags.

class pcapkit.protocols.internet.ipv4.DataType_SEC_Flags
Bases

pcapkit.corekit.infoclass.Info

Protection authority flags, as mapping of protection authority bit assignments enumeration and bool flags.

IPv4 Traceroute Option

For IPv4 Router Alert option as described in RFC 2113, its structure is described as below:

Octets

Bits

Name

Description

0

0

ip.rsralt.kind

Kind (148)

0

0

ip.rsralt.type.copy

Copied Flag (1)

0

1

ip.rsralt.type.class

Option Class (0)

0

3

ip.rsralt.type.number

Option Number (20)

1

8

ip.rsralt.length

Length (4)

2

16

ip.rsralt.alert

Alert

2

16

ip.rsralt.code

Alert Code


class pcapkit.protocols.internet.ipv4.DataType_Opt_RouterAlert
Bases

DataType_Opt

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

alert: pcapkit.const.ipv4.router_alert.RouterAlert

Alert.

code: int

Alert code.


*

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