TCP - Transmission Control Protocol

pcapkit.protocols.transport.tcp contains TCP only, which implements extractor for Transmission Control Protocol (TCP) [*], whose structure is described as below:

Octets	Bits	Name	Description
0	0	tcp.srcport	Source Port
2	16	tcp.dstport	Destination Port
4	32	tcp.seq	Sequence Number
8	64	tcp.ack	Acknowledgement Number (if ACK set)
12	96	tcp.hdr_len	Data Offset
12	100	tcp.flags.reserved	Reserved (must be \x00)
12	103	tcp.flags.ns	ECN Concealment Protection (NS)
13	104	tcp.flags.cwr	Congestion Window Reduced (CWR)
13	105	tcp.flags.ece	ECN-Echo (ECE)
13	106	tcp.flags.urg	Urgent (URG)
13	107	tcp.flags.ack	Acknowledgement (ACK)
13	108	tcp.flags.psh	Push Function (PSH)
13	109	tcp.flags.rst	Reset Connection (RST)
13	110	tcp.flags.syn	Synchronize Sequence Numbers (SYN)
13	111	tcp.flags.fin	Last Packet from Sender (FIN)
14	112	tcp.window_size	Size of Receive Window
16	128	tcp.checksum	Checksum
18	144	tcp.urgent_pointer	Urgent Pointer (if URG set)
20	160	tcp.options	TCP Options (if data offset > 5)

class pcapkit.protocols.transport.tcp.TCP(file=None, length=None, **kwargs)

Bases: Transport[TCP, TCP]

This class implements Transmission Control Protocol.

This class supports parsing of the following protocols, which are registered in the self.__proto__ attribute:

Port Number	Protocol
20	pcapkit.protocols.application.ftp.FTP_DATA
21	pcapkit.protocols.application.ftp.FTP
80	pcapkit.protocols.application.http.HTTP
8080	pcapkit.protocols.application.http.HTTP

This class supports parsing of the following TCP options, which are directly mapped to the pcapkit.const.tcp.option.Option enumeration:

Option Code	Option Parser	Option Constructor
End_of_Option_List	_read_mode_eool()	_make_mode_eool()
No_Operation	_read_mode_nop()	_make_mode_nop()
Maximum_Segment_Size	_read_mode_mss()	_make_mode_mss()
Window_Scale	_read_mode_ws()	_make_mode_ws()
SACK_Permitted	_read_mode_sackpmt()	_make_mode_sackpmt()
SACK	_read_mode_sack()	_make_mode_sack()
Echo	_read_mode_echo()	_make_mode_echo()
Echo_Reply	_read_mode_echore()	_make_mode_echore()
Timestamps	_read_mode_ts()	_make_mode_ts()
Partial_Order_Connection_Permitted	_read_mode_poc()	_make_mode_poc()
Partial_Order_Service_Profile	_read_mode_pocsp()	_make_mode_pocsp()
CC	_read_mode_cc()	_make_mode_cc()
CC_NEW	_read_mode_ccnew()	_make_mode_ccnew()
CC_ECHO	_read_mode_ccecho()	_make_mode_ccecho()
TCP_Alternate_Checksum_Request	_read_mode_chkreq()	_make_mode_chkreq()
TCP_Alternate_Checksum_Data	_read_mode_chksum()	_make_mode_chksum()
MD5_Signature_Option	_read_mode_sig()	_make_mode_sig()
Quick_Start_Response	_read_mode_qs()	_make_mode_qs()
User_Timeout_Option	_read_mode_timeout()	_make_mode_timeout()
TCP_Authentication_Option	_read_mode_ao()	_make_mode_ao()
Multipath_TCP	_read_mode_mp()	_make_mode_mp()
TCP_Fast_Open_Cookie	_read_mode_fastopen()	_make_mode_fastopen()

This class supports parsing of the following Multipath TCP options, which are directly mapped to the pcapkit.const.tcp.mp_tcp_option.MPTCPOption enumeration:

Option Code	Option Parser	Option Constructor
MP_CAPABLE	_read_mptcp_capable()	_make_mptcp_capable()
MP_JOIN	_read_mptcp_join()	_make_mptcp_join()
DSS	_read_mptcp_dss()	_make_mptcp_dss()
ADD_ADDR	_read_mptcp_addaddr()	_make_mptcp_addaddr()
REMOVE_ADDR	_read_mptcp_remove()	_make_mptcp_remove()
MP_PRIO	_read_mptcp_prio()	_make_mptcp_prio()
MP_FAIL	_read_mptcp_fail()	_make_mptcp_fail()
MP_FASTCLOSE	_read_mptcp_fastclose()	_make_mptcp_fastclose()

Changed in version 1.5.0:

• read() reports the connection flags of a flagless segment, and info.connection, as an empty Flags rather than a plain int (#616).

• A constructed MPTCP option sets its subtype (#566), and MP_CAPABLE is written at the RFC 8684 lengths (#567) and read at all five of them (#1042).

• A rebuild keeps what was parsed: the option order and padding (#1151), the reserved bits of the header and of the POCSP, Quick-Start and MPTCP options (#1211, #1212), the octets after EOOL (#1218), the User Timeout granularity (#1219), and the MP_CAPABLE C flag and D-G bits (#1220).

• read() refuses a Data Offset that declares more header than the data holds, rather than reading the missing octets as zeros (#1404).

• MPTCP parsing follows the flags and the option length: MP_FAIL reads its DSN at the right offset (#1213), an unknown subtype stays within its option (#1214), DSS sizes its Data ACK and DSN from the a and m flags and reads a checksum only when one is present (#1215, #1216), and ADD_ADDR parses the RFC 8684 layout (#1217).

property name: Literal['Transmission Control Protocol']

Name of current protocol.

property length: int

Header length of current protocol.

property src: AppType

Source port.

property dst: AppType

Destination port.

property connection: Flags

Connection flags.

classmethod register_option(code, meth)

Register an option parser.

Parameters:

• code (Option) – TCP option code.

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

Warns:

RegistryWarning – If a different entry is already registered for code; it is overwritten. Handing back the entry already stored, or one equal to it, is a silent no-op. The entry code shipped with is accepted like any other, so an override can be undone (#1362, #1363).

classmethod register_mp_option(code, meth)

Register an MPTCP option parser.

Parameters:

• code (MPTCPOption) – MPTCP option code.

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

Warns:

RegistryWarning – If a different entry is already registered for code; it is overwritten. Handing back the entry already stored, or one equal to it, is a silent no-op. The entry code shipped with is accepted like any other, so an override can be undone (#1362, #1363).

read(length=None, **kwargs)

Read Transmission Control Protocol (TCP).

Structure of TCP header [RFC 793]:

 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          Source Port          |       Destination Port        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                        Sequence Number                        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                   Acknowledgement Number                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  Data |           |U|A|P|R|S|F|                               |
| Offset| Reserved  |R|C|S|S|Y|I|            Window             |
|       |           |G|K|H|T|N|N|                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|           Checksum            |         Urgent Pointer        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                    Options                    |    Padding    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                             data                              |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parameters:

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

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

Return type:

TCP

Returns:

Parsed packet data.

Raises:

ProtocolError – If the Data Offset declares more header than the data holds.

make(srcport=0, dstport=0, seq_no=0, ack_no=0, ns=False, cwr=False, ece=False, urg=False, ack=False, psh=False, rst=False, syn=False, fin=False, window=65535, checksum=b'\\x00\\x00', urgent=0, options=None, payload=b'', padding=b'', reserved=0, **kwargs)

Make (construct) packet data.

Parameters:

• srcport (AppType | int) – Source port.

• dstport (AppType | int) – Destination port.

• seq_no (int) – Sequence number.

• ack_no (int) – Acknowledgement number.

• ns (bool) – ECN-nonce concealment protection.

• cwr (bool) – Congestion window reduced.

• ece (bool) – ECN-Echo.

• urg (bool) – Urgent.

• ack (bool) – Acknowledgement.

• psh (bool) – Push function.

• rst (bool) – Reset connection.

• syn (bool) – Synchronize sequence numbers.

• fin (bool) – Last packet from sender.

• window (int) – Window size.

• checksum (bytes) – Checksum.

• urgent (int) – Urgent pointer.

• options (list[Option | tuple[Option, dict[str, Any]] | bytes] | OrderedMultiDict[Option, Option] | None) – TCP options.

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

• padding (bytes) – Octets after the End of Option List option; dropped unless options end with one.

• reserved (int) – Reserved bits 4-6 of octet 12.

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

Return type:

TCP

Returns:

Constructed packet data.

classmethod _make_data(data)

Create key-value pairs from data for protocol construction.

Parameters:

data (TCP) – protocol data

Return type:

dict[str, Any]

Returns:

Key-value pairs for protocol construction.

_read_tcp_options(size)

Read TCP option list.

Parameters:

size (int) – length of option list

Return type:

OrderedMultiDict[Option, Option]

Returns:

Extracted TCP options.

Raises:

ProtocolError – If the threshold is NOT matching.

_read_mode_donone(schema, *, options)

Read options request no process.

Parameters:

• schema (UnassignedOption) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

UnassignedOption

Returns:

Parsed option data.

_read_mode_eool(schema, *, options)

Read TCP End of Option List option.

Structure of TCP end of option list option [RFC 793]:

+--------+
|00000000|
+--------+
 Kind=0

Parameters:

• schema (EndOfOptionList) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

EndOfOptionList

Returns:

Parsed option data.

_read_mode_nop(schema, *, options)

Read TCP No Operation option.

Structure of TCP no-operation option [RFC 793]:

+--------+
|00000001|
+--------+
 Kind=1

Parameters:

• schema (NoOperation) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

NoOperation

Returns:

Parsed option data.

_read_mode_mss(schema, *, options)

Read TCP max segment size option.

Structure of TCP maximum segment size option [RFC 793]:

+--------+--------+---------+--------+
|00000010|00000100|   max seg size   |
+--------+--------+---------+--------+
 Kind=2   Length=4

Parameters:

• schema (MaximumSegmentSize) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MaximumSegmentSize

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 4.

_read_mode_ws(schema, *, options)

Read TCP windows scale option.

Structure of TCP window scale option [RFC 7323]:

+---------+---------+---------+
| Kind=3  |Length=3 |shift.cnt|
+---------+---------+---------+
     1         1         1

Parameters:

• schema (WindowScale) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

WindowScale

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 3.

_read_mode_sackpmt(schema, *, options)

Read TCP SACK permitted option.

Structure of TCP SACK permitted option [RFC 2018]:

+---------+---------+
| Kind=4  | Length=2|
+---------+---------+

Parameters:

• schema (SACKPermitted) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

SACKPermitted

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 2.

_read_mode_sack(schema, *, options)

Read TCP SACK option.

Structure of TCP SACK option [RFC 2018]:

                  +--------+--------+
                  | Kind=5 | Length |
+--------+--------+--------+--------+
|      Left Edge of 1st Block       |
+--------+--------+--------+--------+
|      Right Edge of 1st Block      |
+--------+--------+--------+--------+
|                                   |
/            . . .                  /
|                                   |
+--------+--------+--------+--------+
|      Left Edge of nth Block       |
+--------+--------+--------+--------+
|      Right Edge of nth Block      |
+--------+--------+--------+--------+

Parameters:

• schema (SACK) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

SACK

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT a multiple of 8 plus 2.

_read_mode_echo(schema, *, options)

Read TCP echo option.

Structure of TCP echo option [RFC 1072]:

+--------+--------+--------+--------+--------+--------+
| Kind=6 | Length |   4 bytes of info to be echoed    |
+--------+--------+--------+--------+--------+--------+

Parameters:

• schema (Echo) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

Echo

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 6.

_read_mode_echore(schema, *, options)

Read TCP echo reply option.

Structure of TCP echo reply option [RFC 1072]:

+--------+--------+--------+--------+--------+--------+
| Kind=7 | Length |    4 bytes of echoed info         |
+--------+--------+--------+--------+--------+--------+

Parameters:

• schema (EchoReply) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

EchoReply

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 6.

_read_mode_ts(schema, *, options)

Read TCP timestamps option.

Structure of TCP timestamp option [RFC 7323]:

+-------+-------+---------------------+---------------------+
|Kind=8 |  10   |   TS Value (TSval)  |TS Echo Reply (TSecr)|
+-------+-------+---------------------+---------------------+
    1       1              4                     4

Parameters:

• schema (Timestamps) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

Timestamps

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 10.

_read_mode_poc(schema, *, options)

Read TCP partial order connection permitted option.

Structure of TCP POC-Permitted option [RFC 1693][RFC 6247]:

+-----------+-------------+
|  Kind=9   |  Length=2   |
+-----------+-------------+

Parameters:

• schema (PartialOrderConnectionPermitted) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

PartialOrderConnectionPermitted

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 2.

_read_mode_pocsp(schema, *, options)

Read TCP partial order connection service profile option.

Structure of TCP POC-SP option [RFC 1693][RFC 6247]:

                          1 bit        1 bit    6 bits
+----------+----------+------------+----------+--------+
|  Kind=10 | Length=3 | Start_flag | End_flag | Filler |
+----------+----------+------------+----------+--------+

Parameters:

• schema (PartialOrderServiceProfile) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

PartialOrderServiceProfile

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 3.

_read_mode_cc(schema, *, options)

Read TCP connection count option.

Structure of TCP CC option [RFC 1644]:

+--------+--------+--------+--------+--------+--------+
|00001011|00000110|    Connection Count:  SEG.CC      |
+--------+--------+--------+--------+--------+--------+
 Kind=11  Length=6

Parameters:

• schema (CC) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

CC

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 6.

_read_mode_ccnew(schema, *, options)

Read TCP connection count (new) option.

Structure of TCP CC.NEW option [RFC 1644]:

+--------+--------+--------+--------+--------+--------+
|00001100|00000110|    Connection Count:  SEG.CC      |
+--------+--------+--------+--------+--------+--------+
 Kind=12  Length=6

Parameters:

• schema (CCNew) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

CCNew

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 6.

_read_mode_ccecho(schema, *, options)

Read TCP connection count (echo) option.

Structure of TCP CC.ECHO option [RFC 1644]:

+--------+--------+--------+--------+--------+--------+
|00001101|00000110|    Connection Count:  SEG.CC      |
+--------+--------+--------+--------+--------+--------+
 Kind=13  Length=6

Parameters:

• schema (CCEcho) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

CCEcho

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 6.

_read_mode_chkreq(schema, *, options)

Read TCP Alternate Checksum Request option.

Structure of TCP CHKSUM-REQ [RFC 1146][RFC 6247]:

+----------+----------+----------+
|  Kind=14 | Length=3 |  chksum  |
+----------+----------+----------+

Parameters:

• schema (AlternateChecksumRequest) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

AlternateChecksumRequest

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 3.

_read_mode_chksum(schema, *, options)

Read Alternate Checksum Data option.

Structure of TCP CHKSUM [RFC 1146][RFC 6247]:

+---------+---------+---------+     +---------+
| Kind=15 |Length=N |  data   | ... |  data   |
+---------+---------+---------+     +---------+

Parameters:

• schema (AlternateChecksumData) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

AlternateChecksumData

Returns:

Parsed option data.

_read_mode_sig(schema, *, options)

Read MD5 Signature option.

Structure of TCP SIG option [RFC 2385]:

+---------+---------+-------------------+
| Kind=19 |Length=18|   MD5 digest...   |
+---------+---------+-------------------+
|                                       |
+---------------------------------------+
|                                       |
+---------------------------------------+
|                                       |
+-------------------+-------------------+
|                   |
+-------------------+

Parameters:

• schema (MD5Signature) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MD5Signature

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 18.

_read_mode_qs(schema, *, options)

Read Quick-Start Response option.

Structure of TCP QSopt [RFC 4782]:

 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     Kind      |  Length=8     | Resv. | Rate  |   TTL Diff    |
|               |               |       |Request|               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                   QS Nonce                                | R |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parameters:

• schema (QuickStartResponse) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

QuickStartResponse

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 8.

_read_mode_timeout(schema, *, options)

Read User Timeout option.

Structure of TCP TIMEOUT [RFC 5482]:

 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   Kind = 28   |   Length = 4  |G|        User Timeout         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parameters:

• schema (UserTimeout) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

UserTimeout

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 4.

_read_mode_ao(schema, *, options)

Read Authentication option.

Structure of TCP AOopt [RFC 5925]:

+------------+------------+------------+------------+
|  Kind=29   |   Length   |   KeyID    | RNextKeyID |
+------------+------------+------------+------------+
|                     MAC           ...
+-----------------------------------...

...-----------------+
...  MAC (con't)    |
...-----------------+

Parameters:

• schema (Authentication) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

Authentication

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT larger than or equal to 4.

_read_mode_mp(schema, *, options)

Read Multipath TCP option.

Structure of MP-TCP [RFC 6824]:

                     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
+---------------+---------------+-------+-----------------------+
|     Kind      |    Length     |Subtype|                       |
+---------------+---------------+-------+                       |
|                     Subtype-specific data                     |
|                       (variable length)                       |
+---------------------------------------------------------------+

Parameters:

• schema (MPTCP) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MPTCP

Returns:

Parsed option data.

_read_mode_fastopen(schema, *, options)

Read Fast Open option.

Structure of TCP FASTOPEN [RFC 7413]:

                                +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                                |      Kind     |    Length     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
~                            Cookie                             ~
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parameters:

• schema (FastOpenCookie) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

FastOpenCookie

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT valid.

_read_mptcp_unknown(schema, *, options)

Read unknown MPTCP subtype.

Parameters:

• schema (MPTCPUnknown) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MPTCPUnknown

Returns:

Parsed option data.

_read_mptcp_capable(schema, *, options)

Read Multipath Capable option.

Structure of MP_CAPABLE [RFC 8684]:

                     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
+---------------+---------------+-------+-------+---------------+
|     Kind      |    Length     |Subtype|Version|A|B|C|D|E|F|G|H|
+---------------+---------------+-------+-------+---------------+
|                   Option Sender's Key (64 bits)               |
|                      (if option Length > 4)                   |
|                                                               |
+---------------------------------------------------------------+
|                  Option Receiver's Key (64 bits)              |
|                      (if option Length > 12)                  |
|                                                               |
+-------------------------------+-------------------------------+
|  Data-Level Length (16 bits)  |  Checksum (16 bits, optional) |
+-------------------------------+-------------------------------+

Parameters:

• schema (MPTCPCapable) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MPTCPCapable

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 4, 12, 20, 22 or 24.

_read_mptcp_join(schema, *, options)

Read Join Connection option.

Parameters:

• schema (MPTCPJoin) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MPTCPJoin

Returns:

Parsed option data.

Raises:

ProtocolError – If the segment carries neither SYN nor ACK.

_read_mptcp_dss(schema, *, options)

Read Data Sequence Signal (Data ACK and Data Sequence Mapping) option.

Structure of DSS [RFC 8684, section 3.3, figure 9]:

                     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
+---------------+---------------+-------+----------------------+
|     Kind      |    Length     |Subtype| (reserved) |F|m|M|a|A|
+---------------+---------------+-------+----------------------+
|                                                              |
|           Data ACK (4 or 8 octets, depending on flags)       |
|                                                              |
+--------------------------------------------------------------+
|                                                              |
|   Data sequence number (4 or 8 octets, depending on flags)   |
|                                                              |
+--------------------------------------------------------------+
|              Subflow Sequence Number (4 octets)              |
+-------------------------------+------------------------------+
|  Data-Level Length (2 octets) |      Checksum (2 octets)     |
+-------------------------------+------------------------------+

Parameters:

• schema (MPTCPDSS) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MPTCPDSS

Returns:

Parsed option data.

Note

The reserved field spans the 4 low bits of the subtype octet and the 3 high bits of the flags octet; it is kept as one 7-bit value. The checksum is absent when the option length leaves no room for it, i.e., when checksums were not negotiated.

_read_mptcp_addaddr(schema, *, options)

Read Add Address option.

Structure of ADD_ADDR [RFC 8684, section 3.4.1, figure 12]:

                     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
+---------------+---------------+-------+-------+---------------+
|     Kind      |     Length    |Subtype|(rsv)|E|  Address ID   |
+---------------+---------------+-------+-------+---------------+
|           Address (IPv4: 4 octets / IPv6: 16 octets)          |
+-------------------------------+-------------------------------+
|   Port (2 octets, optional)   |                               |
+-------------------------------+                               |
|                Truncated HMAC (8 octets, if E=0)              |
|                               +-------------------------------+
|                               |
+-------------------------------+

Parameters:

• schema (MPTCPAddAddress) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MPTCPAddAddress

Returns:

Parsed option data.

Raises:

ProtocolError – If the length is not one of the RFC 8684 lengths.

Note

The address family, the port and the HMAC all follow from the option length, never from the E flag, so an RFC 6824 option, whose IPVer nibble overlaps the reserved bits and E, parses the same way and round-trips unchanged.

_read_mptcp_remove(schema, *, options)

Read Remove Address option.

Structure of REMOVE_ADDR [RFC 8684, section 3.4.2, figure 13]:

                     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
+---------------+---------------+-------+-------+---------------+
|     Kind      |  Length = 3+n |Subtype|(resvd)|   Address ID  | ...
+---------------+---------------+-------+-------+---------------+
                           (followed by n-1 Address IDs, if required)

Parameters:

• schema (MPTCPRemoveAddress) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MPTCPRemoveAddress

Returns:

Parsed option data.

Raises:

ProtocolError – If the length is smaller than 3.

Note

Length = 3 + n, per the figure above: the 3 is Kind (1) + Length (1) + subtype-and-reserved (1), and each of the n Address IDs is one further octet. addr_id sizes its list as pkt['length'] - 3 from exactly this, so the declared length governs the parse as well as the pack.

The guard permits 3, i.e. n = 0, which the figure does not describe – it shows one Address ID plus “n-1 Address IDs, if required”. It is left permissive: a zero-ID REMOVE_ADDR round-trips honestly, and rejecting an empty list would be a behaviour change.

_read_mptcp_prio(schema, *, options)

Read Change Subflow Priority option.

Structure of MP_PRIO [RFC 6824, section 3.3.8, figure 11]:

                      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
+---------------+---------------+-------+-----+-+--------------+
|     Kind      |     Length    |Subtype|     |B| AddrID (opt) |
+---------------+---------------+-------+-----+-+--------------+

Parameters:

• schema (MPTCPPriority) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MPTCPPriority

Returns:

Parsed option data.

Raises:

ProtocolError – If the length is neither 3 nor 4.

Note

The figure above is RFC 6824’s, deliberately, because it is the one with an Address ID in it and this method accepts both forms. RFC 8684 section 3.3.8 figure 11 draws MP_PRIO as 3 octets and nothing more – Kind (1) + Length (1) + subtype/reserved/B (1) – since section 5 of that document “specifies the removal of the AddrID field [RFC6824] in the MP_PRIO option”, closing a theoretical attack in which a subflow could be forced into backup mode. The 4-octet RFC 6824 form is therefore legacy, and the guard stays permissive so that traffic carrying it still parses.

On the construction side, MPTCPPriority’s addr_id is conditional on length being 4, so length has to follow whether the caller supplied an Address ID.

_read_mptcp_fail(schema, *, options)

Read Fallback option.

Structure of MP_FAIL [RFC 8684, section 3.7, figure 16]:

                     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
+---------------+---------------+-------+----------------------+
|     Kind      |   Length=12   |Subtype|      (reserved)      |
+---------------+---------------+-------+----------------------+
|                                                              |
|                 Data Sequence Number (8 octets)              |
|                                                              |
+--------------------------------------------------------------+

Parameters:

• schema (MPTCPFallback) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MPTCPFallback

Returns:

Parsed option data.

Raises:

ProtocolError – If the length is NOT 12.

_read_mptcp_fastclose(schema, options)

Read Fast Close option.

Structure of MP_FASTCLOSE [RFC 8684, section 3.5, figure 14]:

                     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
+---------------+---------------+-------+-----------------------+
|     Kind      |    Length     |Subtype|      (reserved)       |
+---------------+---------------+-------+-----------------------+
|                      Option Receiver's Key                    |
|                            (64 bits)                          |
|                                                               |
+---------------------------------------------------------------+

Parameters:

• schema (MPTCPFastclose) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MPTCPFastclose

Returns:

Parsed option data.

Raises:

ProtocolError – If the length is NOT 12.

Note

The figure above is RFC 8684 section 3.5 figure 14, and the option it draws is 12 octets: Kind (1) + Length (1) + subtype-and-reserved (2, being 4 subtype bits and 12 reserved) + the option receiver’s key (64 bits, 8). The guard, _make_mptcp_fastclose and the schema must all agree on 12, the schema reading the 12 reserved bits along with the subtype.

_read_join_syn(schema, *, options)

Read Join Connection option for Initial SYN.

Structure of MP_JOIN-SYN [RFC 8684, section 3.2, figure 5]:

                     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
+---------------+---------------+-------+-----+-+---------------+
|     Kind      |  Length = 12  |Subtype|     |B|   Address ID  |
+---------------+---------------+-------+-----+-+---------------+
|                   Receiver's Token (32 bits)                  |
+---------------------------------------------------------------+
|                Sender's Random Number (32 bits)               |
+---------------------------------------------------------------+

Parameters:

• schema (MPTCPJoinSYN) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MPTCPJoinSYN

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 12.

_read_join_synack(schema, options)

Read Join Connection option for Responding SYN/ACK.

Structure of MP_JOIN-SYN/ACK [RFC 8684, section 3.2, figure 6]:

                     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
+---------------+---------------+-------+-----+-+---------------+
|     Kind      |  Length = 16  |Subtype|     |B|   Address ID  |
+---------------+---------------+-------+-----+-+---------------+
|                                                               |
|                Sender's Truncated HMAC (64 bits)              |
|                                                               |
+---------------------------------------------------------------+
|                Sender's Random Number (32 bits)               |
+---------------------------------------------------------------+

Parameters:

• schema (MPTCPJoinSYNACK) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MPTCPJoinSYNACK

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 16.

Note

The accepted length is 16, as in the figure above (RFC 8684 section 3.2 figure 6) and in what MPTCPJoinSYNACK packs and unpacks: Kind (1) + Length (1) + subtype/flags (1) + Address ID (1) + the truncated HMAC (8) + the random number (4).

_read_join_ack(schema, *, options)

Read Join Connection option for Third ACK.

Structure of MP_JOIN-ACK [RFC 8684, section 3.2, figure 7]:

                     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
+---------------+---------------+-------+-----------------------+
|     Kind      |  Length = 24  |Subtype|      (reserved)       |
+---------------+---------------+-------+-----------------------+
|                                                               |
|                                                               |
|                   Sender's HMAC (160 bits)                    |
|                                                               |
|                                                               |
+---------------------------------------------------------------+

Parameters:

• schema (MPTCPJoinACK) – parsed option schema

• options (OrderedMultiDict[Option, Option]) – extracted TCP options

Return type:

MPTCPJoinACK

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 24.

_make_tcp_options(options, padding=b'')

Make options for TCP.

Parameters:

• options (list[Option | tuple[Option, dict[str, Any]] | bytes] | OrderedMultiDict[Option, Option]) – TCP options

• padding (bytes) – octets after the End of Option List option

Return type:

tuple[list[Option | bytes], int]

Returns:

Tuple of options and total length of options.

Note

The options are emitted in the given order, NOP and EOOL included, so that a parsed option list re-emits the same octets. padding follows them as given if they end with EOOL, and is dropped otherwise. Alignment is added only once, after that, when the list does not end on a 32-bit boundary: zero octets if the list already ends with EOOL, otherwise NOP options followed by an EOOL.

_make_mode_donone(code, opt=None, *, data=b'', **kwargs)

Make TCP unassigned option.

Parameters:

• code (Option) – option code

• opt (UnassignedOption | None) – option data

• data (bytes) – option payload in bytes

• **kwargs (Any) – arbitrary keyword arguments

Return type:

UnassignedOption

Returns:

Constructed option schema.

_make_mode_eool(code, opt=None, **kwargs)

Make TCP End of Option List option.

Parameters:

• code (Option) – option code

• opt (EndOfOptionList | None) – option data

• **kwargs (Any) – arbitrary keyword arguments

Return type:

EndOfOptionList

Returns:

Constructed option schema.

_make_mode_nop(code, opt=None, **kwargs)

Make TCP NoOperation option.

Parameters:

• code (Option) – option code

• opt (NoOperation | None) – option data

• **kwargs (Any) – arbitrary keyword arguments

Return type:

NoOperation

Returns:

Constructed option schema.

_make_mode_mss(code, opt=None, *, mss=65535, **kwargs)

Make TCP maximum segment size option.

Parameters:

• code (Option) – option code

• opt (MaximumSegmentSize | None) – option data

• mss (int) – maximum segment size

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MaximumSegmentSize

Returns:

Constructed option schema.

_make_mode_ws(code, opt=None, *, shift=0, **kwargs)

Make TCP window scale option.

Parameters:

• code (Option) – option code

• opt (WindowScale | None) – option data

• shift (int) – window scale shift count

• **kwargs (Any) – arbitrary keyword arguments

Return type:

WindowScale

Returns:

Constructed option schema.

_make_mode_sackpmt(code, opt=None, **kwargs)

Make TCP SACK permitted option.

Parameters:

• code (Option) – option code

• opt (SACKPermitted | None) – option data

• **kwargs (Any) – arbitrary keyword arguments

Return type:

SACKPermitted

Returns:

Constructed option schema.

_make_mode_sack(code, opt=None, *, sack=None, **kwargs)

Make TCP SACK option.

Parameters:

• code (Option) – option code

• opt (SACK | None) – option data

• sack (list[tuple[int, int]] | None) – SACK blocks

• **kwargs (Any) – arbitrary keyword arguments

Return type:

SACK

Returns:

Constructed option schema.

_make_mode_echo(code, opt=None, *, data=b'\\x00\\x00\\x00\\x00', **kwargs)

Make TCP echo option.

Parameters:

• code (Option) – option code

• opt (Echo | None) – option data

• data (bytes) – 4 bytes of info to be echoed

• **kwargs (Any) – arbitrary keyword arguments

Return type:

Echo

Returns:

Constructed option schema.

_make_mode_echore(code, opt=None, *, data=b'\\x00\\x00\\x00\\x00', **kwargs)

Make TCP echo reply option.

Parameters:

• code (Option) – option code

• opt (EchoReply | None) – option data

• data (bytes) – 4 bytes of echoed info

• **kwargs (Any) – arbitrary keyword arguments

Return type:

EchoReply

Returns:

Constructed option schema.

_make_mode_ts(code, opt=None, *, tsval=0, tsecr=0, **kwargs)

Make TCP timestamps option.

Parameters:

• code (Option) – option code

• opt (Timestamps | None) – option data

• tsval (int) – timestamp value

• tsecr (int) – timestamp echo reply

• **kwargs (Any) – arbitrary keyword arguments

Return type:

Timestamps

Returns:

Constructed option schema.

_make_mode_poc(code, opt=None, **kwargs)

Make TCP partial order connection option.

Parameters:

• code (Option) – option code

• opt (PartialOrderConnectionPermitted | None) – option data

• **kwargs (Any) – arbitrary keyword arguments

Return type:

PartialOrderConnectionPermitted

Returns:

Constructed option schema.

_make_mode_pocsp(code, opt=None, *, start=False, end=False, reserved=0, **kwargs)

Make TCP partial order connection service profile option.

Parameters:

• code (Option) – option code

• opt (PartialOrderServiceProfile | None) – option data

• start (bool) – start partial order connection

• end (bool) – end partial order connection

• reserved (int) – reserved bits (Filler, 6 bits)

• **kwargs (Any) – arbitrary keyword arguments

Return type:

PartialOrderServiceProfile

Returns:

Constructed option schema.

_make_mode_cc(code, opt=None, *, count=0, **kwargs)

Make TCP connection count option.

Parameters:

• code (Option) – option code

• opt (CC | None) – option data

• count (int) – connection count

• **kwargs (Any) – arbitrary keyword arguments

Return type:

CC

Returns:

Constructed option schema.

_make_mode_ccnew(code, opt=None, *, count=0, **kwargs)

Make TCP connection count new option.

Parameters:

• code (Option) – option code

• opt (CCNew | None) – option data

• count (int) – connection count

• **kwargs (Any) – arbitrary keyword arguments

Return type:

CCNew

Returns:

Constructed option schema.

_make_mode_ccecho(code, opt=None, *, count=0, **kwargs)

Make TCP connection count echo option.

Parameters:

• code (Option) – option code

• opt (CCEcho | None) – option data

• count (int) – connection count

• **kwargs (Any) – arbitrary keyword arguments

Return type:

CCEcho

Returns:

Constructed option schema.

_make_mode_chkreq(code, opt=None, *, algorithm=<Checksum.TCP_checksum: 0>, algorithm_default=None, algorithm_namespace=None, algorithm_reversed=False, **kwargs)

Make TCP alternate checksum request option.

Parameters:

• code (Option) – option code

• opt (AlternateChecksumRequest | None) – option data

• algorithm (Checksum | IntEnum | IntEnum | int | str) – checksum algorithm

• algorithm_default (int | None) – default value for checksum algorithm

• algorithm_namespace (dict[str, int] | dict[int, str] | Type[IntEnum] | Type[IntEnum] | None) – namespace for checksum algorithm

• algorithm_reversed (bool) – reversed flag for checksum algorithm

• **kwargs (Any) – arbitrary keyword arguments

Return type:

AlternateChecksumRequest

Returns:

Constructed option schema.

_make_mode_chksum(code, opt=None, *, data=b'', **kwargs)

Make TCP alternate checksum data option.

Parameters:

• code (Option) – option code

• opt (AlternateChecksumData | None) – option data

• data (bytes) – checksum data

• **kwargs (Any) – arbitrary keyword arguments

Return type:

AlternateChecksumData

Returns:

Constructed option schema.

_make_mode_sig(code, opt=None, *, digest=b'\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00', **kwargs)

Make TCP MD5 signature option.

Parameters:

• code (Option) – option code

• opt (MD5Signature | None) – option data

• digest (bytes) – digest

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MD5Signature

Returns:

Constructed option schema.

_make_mode_qs(code, opt=None, *, rate=0, diff=0, nonce=0, reserved=0, nonce_reserved=0, **kwargs)

Make TCP quick start response option.

Parameters:

• code (Option) – option code

• opt (QuickStartResponse | None) – option data

• rate (int) – rate (in kbps)

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

• nonce (int) – nonce value

• reserved (int) – reserved bits before the rate request (Resv., 4 bits)

• nonce_reserved (int) – reserved bits after the nonce (R, 2 bits)

• **kwargs (Any) – arbitrary keyword arguments

Return type:

QuickStartResponse

Returns:

Constructed option schema.

_make_mode_timeout(code, opt=None, *, timeout=0, granularity=None, **kwargs)

Make TCP user timeout option.

Parameters:

• code (Option) – option code

• opt (UserTimeout | None) – option data

• timeout (timedelta | int) – timeout value (in seconds, if an int)

• granularity (bool | None) – preferred unit, minutes (G set) or seconds; it is kept only while the value still fits in it – seconds within 15 bits, minutes as a whole number of them. Otherwise, and if not given, seconds are used when they fit in 15 bits, and minutes if not.

• **kwargs (Any) – arbitrary keyword arguments

Return type:

UserTimeout

Returns:

Constructed option schema.

Raises:

ProtocolError – If the timeout does not fit in 15 bits of minutes.

_make_mode_ao(code, opt=None, *, key_id=0, next_key_id=0, mac=b'', **kwargs)

Make TCP authentication option.

Parameters:

• code (Option) – option code

• opt (Authentication | None) – option data

• key_id (int) – key ID

• next_key_id (int) – next key ID

• mac (bytes) – MAC value

• **kwargs (Any) – arbitrary keyword arguments

Return type:

Authentication

Returns:

Constructed option schema.

_make_mode_mp(code, opt=None, *, subtype=<MPTCPOption.MP_CAPABLE: 0>, subtype_default=None, subtype_namespace=None, subtype_reversed=False, **kwargs)

Make multipath TCP option.

Parameters:

• code (Option) – option code

• opt (MPTCP | None) – option data

• subtype (MPTCPOption | IntEnum | IntEnum | int | str) – MPTCP subtype

• subtype_default (int | None) – default value for MPTCP subtype

• subtype_namespace (dict[str, int] | dict[int, str] | Type[IntEnum] | Type[IntEnum] | None) – namespace for MPTCP subtype

• subtype_reversed (bool) – reversed flag for MPTCP subtype

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MPTCP

Returns:

Constructed option schema.

_make_mode_fastopen(code, opt=None, *, cookie=None, **kwargs)

Make TCP Fast Open option.

Parameters:

• code (Option) – option code

• opt (FastOpenCookie | None) – option data

• cookie (bytes | None) – fast open cookie

• **kwargs (Any) – arbitrary keyword arguments

Return type:

FastOpenCookie

Returns:

Constructed option schema.

_make_mptcp_unknown(subtype, opt=None, *, data=b'\\x00', **kwargs)

Make unknown multipath TCP option.

Parameters:

• subtype (MPTCPOption) – MPTCP subtype

• opt (MPTCPUnknown | None) – option data

• data (bytes) – option payload data

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MPTCPUnknown

Returns:

Constructed option schema.

_make_mptcp_capable(subtype, opt=None, *, version=0, flag_req=False, flag_ext=False, flag_deny_join=False, flag_reserved=0, flag_hsa=False, skey=0, rkey=0, dl_len=None, checksum=None, **kwargs)

Make multipath TCP capable option.

Each field is present only if every field before it is, which selects one of the five RFC 8684 section 3.1 lengths: 4 (skey=None), 12 (rkey=None), 20 (dl_len=None), 22 (checksum=None) or 24.

Parameters:

• subtype (MPTCPOption) – MPTCP subtype

• opt (MPTCPCapable | None) – option data

• version (int) – MPTCP version

• flag_req (bool) – checksum required flag

• flag_ext (bool) – extensibility flag

• flag_deny_join (bool) – flag for not establishing new subflows to the source address

• flag_reserved (int) – reserved flags (D to G)

• flag_hsa (bool) – use of HMAC-SHA1 (version 0) or HMAC-SHA256 (version 1) flag

• skey (int | None) – option sender’s key

• rkey (int | None) – option receiver’s key

• dl_len (int | None) – data-level length

• checksum (bytes | None) – checksum

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MPTCPCapable

Returns:

Constructed option schema.

Raises:

ProtocolError – If a field is given without the field before it.

_make_mptcp_join(subtype, opt=None, **kwargs)

Make multipath TCP join option.

Parameters:

• subtype (MPTCPOption) – MPTCP subtype

• opt (MPTCPJoin | None) – option data

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MPTCPJoin

Returns:

Constructed option schema.

_make_mptcp_dss(subtype, opt=None, *, reserved=0, data_fin=False, ack_wide=None, ack=None, dsn_wide=None, dsn=None, ssn=None, dl_len=None, checksum=None, **kwargs)

Make multipath TCP DSS option.

Parameters:

• subtype (MPTCPOption) – MPTCP subtype

• opt (MPTCPDSS | None) – option data

• reserved (int) – reserved bits (7 bits)

• data_fin (bool) – DATA_FIN flag

• ack_wide (bool | None) – whether Data ACK is 8 octets; if not given, it is 8 octets only when ack does not fit in 4

• ack (int | None) – Data ACK

• dsn_wide (bool | None) – whether data sequence number is 8 octets; if not given, it is 8 octets only when dsn does not fit in 4

• dsn (int | None) – data sequence number

• ssn (int | None) – subflow sequence number

• dl_len (int | None) – data-level length

• checksum (bytes | None) – checksum, or None if checksums were not negotiated

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MPTCPDSS

Returns:

Constructed option schema.

Raises:

ProtocolError – If the mapping fields are given only in part, or a 4-octet field is asked to hold a value wider than 32 bits.

_make_mptcp_addaddr(subtype, opt=None, *, reserved=None, echo=None, addr_id=0, addr='0.0.0.0', port=None, hmac=None, **kwargs)

Make multipath TCP add address option.

Parameters:

• subtype (MPTCPOption) – MPTCP subtype

• opt (MPTCPAddAddress | None) – option data

• reserved (int | None) – reserved bits

• echo (bool | None) – echo flag

• addr_id (int) – address ID

• addr (IPv4Address | IPv6Address | int | bytes | str) – address

• port (int | None) – port number

• hmac (bytes | None) – truncated HMAC

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MPTCPAddAddress

Returns:

Constructed option schema.

Raises:

ProtocolError – If hmac is not 8 octets, or is given together with echo set.

Note

RFC 8684 section 3.4.1 allows an ADD_ADDR without the truncated HMAC only as an echo (E set). So when none of reserved, echo and hmac is given, the option is built in the RFC 6824 layout instead, its IPVer nibble taking the place of the reserved bits and E; otherwise reserved defaults to 0 and echo to whether hmac is absent. A parsed opt is rebuilt as it was read, without those checks.

_make_mptcp_remove(subtype, opt=None, *, reserved=0, addr_id=None, **kwargs)

Make multipath TCP remove address option.

Parameters:

• subtype (MPTCPOption) – MPTCP subtype

• opt (MPTCPRemoveAddress | None) – option data

• reserved (int) – reserved bits

• addr_id (list[int] | None) – address ID list

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MPTCPRemoveAddress

Returns:

Constructed option schema.

_make_mptcp_prio(subtype, opt=None, *, reserved=0, backup=False, addr_id=None, **kwargs)

Make multipath TCP priority option.

Parameters:

• subtype (MPTCPOption) – MPTCP subtype

• opt (MPTCPPriority | None) – option data

• reserved (int) – reserved bits

• backup (bool) – backup flag

• addr_id (int | None) – address ID

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MPTCPPriority

Returns:

Constructed option schema.

_make_mptcp_fail(subtype, opt=None, *, reserved=0, dsn=0, **kwargs)

Make multipath TCP fail option.

Parameters:

• subtype (MPTCPOption) – MPTCP subtype

• opt (MPTCPFallback | None) – option data

• reserved (int) – reserved bits

• dsn (int) – data sequence number

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MPTCPFallback

Returns:

Constructed option schema.

_make_mptcp_fastclose(subtype, opt=None, *, reserved=0, key=0, **kwargs)

Make multipath TCP fastclose option.

Parameters:

• subtype (MPTCPOption) – MPTCP subtype

• opt (MPTCPFastclose | None) – option data

• reserved (int) – reserved bits

• key (int) – option receiver’s key

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MPTCPFastclose

Returns:

Constructed option schema.

_make_join_syn(subtype, opt=None, *, reserved=0, backup=False, addr_id=0, token=0, nonce=0, **kwargs)

Make multipath TCP join SYN option.

Parameters:

• subtype (MPTCPOption) – MPTCP subtype

• opt (MPTCPJoinSYN | None) – option data

• reserved (int) – reserved bits

• backup (bool) – backup flag

• addr_id (int) – address ID

• token (int) – receiver’s token

• nonce (int) – sender’s random number

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MPTCPJoinSYN

Returns:

Constructed option schema.

_make_join_synack(subtype, opt=None, *, reserved=0, backup=False, addr_id=0, hmac=b'\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00', nonce=0, **kwargs)

Make multipath TCP join SYN/ACK option.

Parameters:

• subtype (MPTCPOption) – MPTCP subtype

• opt (MPTCPJoinSYNACK | None) – option data

• reserved (int) – reserved bits

• backup (bool) – backup flag

• addr_id (int) – address ID

• hmac (bytes) – sender’s truncated HMAC

• nonce (int) – sender’s random number

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MPTCPJoinSYNACK

Returns:

Constructed option schema.

_make_join_ack(subtype, opt=None, *, reserved=0, hmac=b'\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00', **kwargs)

Make multipath TCP join ACK option.

Parameters:

• subtype (MPTCPOption) – MPTCP subtype

• opt (MPTCPJoinACK | None) – option data

• reserved (int) – reserved bits

• hmac (bytes) – sender’s HMAC

• **kwargs (Any) – arbitrary keyword arguments

Return type:

MPTCPJoinACK

Returns:

Constructed option schema.

__proto__: DefaultDict[int, ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]]

Protocol index mapping for decoding next layer, c.f. self._decode_next_layer & self._import_next_layer.

Type:

DefaultDict[int, ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]]

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

Option code to method mapping, c.f. _read_tcp_options() and _make_tcp_options(). Method names are expected to be referred to the class by _read_mode_${name} and _make_mode_${name}, and if such name not found, the value should then be a method that can parse the option by itself.

Type:

DefaultDict[Enum_Option, str | tuple[OptionParser, OptionConstructor]]

__mp_option__: DefaultDict[int, str | tuple[Callable[[MPTCP, OrderedMultiDict[Option, Option]], MPTCP], Callable[[MPTCPOption, MPTCP | None, Any], MPTCP]]]

Option code to method mapping, c.f. _read_mode_mp() and _make_mode_mp(). Method names are expected to be referred to the class by _read_mptcp_${name} and _make_mptcp_${name}, and if such name not found, the value should then be a method that can parse the option by itself.

Type:

DefaultDict[Enum_MPTCPOption, str | tuple[MPOptionParser, MPOptionConstructor]]

classmethod __index__()

Numeral registry index of the protocol.

Return type:

TransType

Returns:

Numeral registry index of the protocol in IANA.

Header Schemas

pcapkit.protocols.schema.transport.tcp.TCP_MIN_HEADER_LEN = 20

Minimum length of a TCP header, i.e. the fixed part with no options, RFC 9293 Section 3.1. The one home of this value (#1739), here so that the schema’s option length and the protocol modules read the same one; it is fixed by the RFC, so it is never configurable.

Added in version 1.5.0.

pcapkit.protocols.schema.transport.tcp.TCP_DATA_OFFSET_OCTET = 12

Offset of the octet whose high four bits are the Data Offset field – the header length in 32-bit words – within a TCP header, RFC 9293 Section 3.1. The one home of this value (#1739), beside TCP_MIN_HEADER_LEN; it is fixed by the RFC, so it is never configurable.

Added in version 1.5.0.

class pcapkit.protocols.schema.transport.tcp.TCP(*args: _VT, **kwargs: _VT)

Bases: Schema

Header schema for TCP packet.

srcport: AppType = <PortEnumField srcport>

Source port.

dstport: AppType = <PortEnumField dstport>

Destination port.

seq: int = <UInt32Field seq>

Sequence number.

ack: int = <UInt32Field ack>

Acknowledgement number.

offset: OffsetFlag = <BitField offset>

Data offset.

flags: Flags = <BitField flags>

TCP flags.

window: int = <UInt16Field window>

Window size.

checksum: bytes = <BytesField checksum>

Checksum.

urgent: int = <UInt16Field urgent>

Urgent pointer.

options: list[Option] = <OptionField options>

Options.

padding: bytes = <PaddingField padding>

Padding.

payload: bytes = <PayloadField payload>

Payload.

class pcapkit.protocols.schema.transport.tcp.Flags

Bases: TypedDict

TCP flags.

cwr: int

Congestion window reduced.

ece: int

ECN-Echo.

urg: int

Urgent pointer.

ack: int

Acknowledgment.

psh: int

Push function.

rst: int

Reset connection.

syn: int

Synchronize sequence numbers.

fin: int

Last packet from sender.

class pcapkit.protocols.schema.transport.tcp.Option(dict_=None, **kwargs)

Bases: EnumSchema[Option]

Header schema for TCP options.

kind: Option = <EnumField kind>

Option kind.

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.transport.tcp.UnassignedOption(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP unassigned options.

data: bytes = <BytesField data>

Option data.

class pcapkit.protocols.schema.transport.tcp.EndOfOptionList(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP end of option list.

class pcapkit.protocols.schema.transport.tcp.NoOperation(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP no operation.

class pcapkit.protocols.schema.transport.tcp.MaximumSegmentSize(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP max segment size option.

mss: int = <UInt16Field mss>

Maximum segment size.

class pcapkit.protocols.schema.transport.tcp.WindowScale(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP window scale option.

shift: int = <UInt8Field shift>

Window scale (shift count).

class pcapkit.protocols.schema.transport.tcp.SACKPermitted(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP SACK permitted option.

class pcapkit.protocols.schema.transport.tcp.SACK(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP SACK option.

sack: list[SACKBlock] = <ListField sack>

Selected ACK data.

class pcapkit.protocols.schema.transport.tcp.SACKBlock(*args: _VT, **kwargs: _VT)

Bases: Schema

Header schema for TCP SACK option data.

left: int = <UInt32Field left>

Left edge of the block.

right: int = <UInt32Field right>

Right edge of the block.

class pcapkit.protocols.schema.transport.tcp.Echo(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP echo option.

data: bytes = <BytesField data>

Info to be echoed.

class pcapkit.protocols.schema.transport.tcp.EchoReply(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP echo reply option.

data: bytes = <BytesField data>

Echoed info.

class pcapkit.protocols.schema.transport.tcp.Timestamps(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP timestamps option.

Changed in version 1.1.0: Renamed from Timestamp, which pcapkit.protocols.schema exported as TCP_Timestamp; the export is TCP_Timestamps.

value: int = <UInt32Field value>

Timestamp value.

reply: int = <UInt32Field reply>

Timestamp echo reply.

class pcapkit.protocols.schema.transport.tcp.PartialOrderConnectionPermitted(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP partial order connection permitted option.

class pcapkit.protocols.schema.transport.tcp.PartialOrderServiceProfile(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP partial order connection service profile option.

Changed in version 1.1.0: Renamed from PartialOrderConnectionProfile, which pcapkit.protocols.schema exported as TCP_PartialOrderConnectionProfile; the export is TCP_PartialOrderServiceProfile.

profile: POCProfile = <BitField profile>

Profile data.

class pcapkit.protocols.schema.transport.tcp.CC(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP CC option.

count: int = <UInt32Field count>

Connection count.

class pcapkit.protocols.schema.transport.tcp.CCNew(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP connection count (new) option.

count: int = <UInt32Field count>

Connection count.

class pcapkit.protocols.schema.transport.tcp.CCEcho(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP connection count (echo) option.

count: int = <UInt32Field count>

Connection count.

class pcapkit.protocols.schema.transport.tcp.AlternateChecksumRequest(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP alternate checksum request option.

algorithm: Checksum = <EnumField algorithm>

Checksum algorithm.

class pcapkit.protocols.schema.transport.tcp.AlternateChecksumData(kind, length, data)

Bases: Option

Header schema for TCP alternate checksum data option.

data: bytes = <BytesField data>

Checksum data.

class pcapkit.protocols.schema.transport.tcp.MD5Signature(kind, length, digest)

Bases: Option

Header schema for TCP MD5 signature option.

digest: bytes = <BytesField digest>

MD5 digest.

class pcapkit.protocols.schema.transport.tcp.QuickStartResponse(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP quick start response option.

flags: QuickStartFlags = <BitField flags>

Flags.

diff: int = <UInt8Field diff>

TTL difference.

nonce: QuickStartNonce = <BitField nonce>

QS nonce.

class pcapkit.protocols.schema.transport.tcp.UserTimeout(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP user timeout option.

info: TimeoutInfo = <BitField info>

Granularity and user timeout.

class pcapkit.protocols.schema.transport.tcp.Authentication(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP authentication option.

key_id: int = <UInt8Field key_id>

Key ID.

next_key_id: int = <UInt8Field next_key_id>

Next key ID.

mac: bytes = <BytesField mac>

MAC value.

class pcapkit.protocols.schema.transport.tcp.FastOpenCookie(*args: _VT, **kwargs: _VT)

Bases: Option

Header schema for TCP Fast Open option.

cookie: bytes = <ConditionalField cookie>

Cookie.

class pcapkit.protocols.schema.transport.tcp._MPTCP(*args: _VT, **kwargs: _VT)

Bases: Schema

Header schema for Multipath TCP options in a generic representation.

test: MPTCPSubtypeTest = <ForwardMatchField test>

Subtype and flags.

The forward match is anchored at the option’s first octet, not after the option header: this schema is what Option.registry dispatches to for kind == Multipath_TCP and, unlike the other option schemas, it does not inherit Option and so consumes kind and length itself. RFC 8684 section 3 therefore puts kind in bits 0-7, length in bits 8-15, and the subtype in bits 16-19 of this 3-octet window – which is why subtype reads from bit 16 and length has to read from bit 8.

data: MPTCP = <SwitchField data>

Subtype-specific data.

post_process(packet)

Revise schema data after unpacking process.

Parameters:

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

Return type:

MPTCP

Returns:

Revised schema.

class pcapkit.protocols.schema.transport.tcp.MPTCP(dict_=None, **kwargs)

Bases: EnumSchema[MPTCPOption]

Header schema for Multipath TCP options.

Changed in version 1.1.0: An EnumSchema keyed on MPTCPOption rather than a subclass of Option, which registers _MPTCP under Multipath_TCP instead.

kind: Option = <EnumField kind>

Option kind.

length: int = <UInt8Field length>

MPTCP length.

subtype: MPTCPOption

MPTCP subtype.

class pcapkit.protocols.schema.transport.tcp.MPTCPUnknown(*args: _VT, **kwargs: _VT)

Bases: MPTCP

Header schema for unknown Multipath TCP option.

test: MPTCPSubtypeUnknown = <BitField test>

Subtype and data.

data: bytes = <BytesField data>

Data.

class pcapkit.protocols.schema.transport.tcp.MPTCPCapable(*args: _VT, **kwargs: _VT)

Bases: MPTCP

Header schema for Multipath TCP capable option.

test: MPTCPSubtypeCapable = <BitField test>

Subtype and version.

flags: MPTCPCapableFlags = <BitField flags>

Flags.

skey: int = <ConditionalField skey>

Option sender’s key (if option length > 4).

rkey: int = <ConditionalField rkey>

Option receiver’s key (if option length > 12).

dl_len: int = <ConditionalField dl_len>

Data-level length (if option length > 20).

checksum: bytes = <ConditionalField checksum>

Checksum (if option length > 22).

class pcapkit.protocols.schema.transport.tcp.MPTCPJoin(dict_=None, **kwargs)

Bases: MPTCP

Header schema for Multipath TCP join option.

class pcapkit.protocols.schema.transport.tcp.MPTCPJoinSYN(*args: _VT, **kwargs: _VT)

Bases: MPTCPJoin

Header schema for Multipath TCP join option for SYN connection.

test: MPTCPSubtypeJoin = <BitField test>

Subtype and flags.

addr_id: int = <UInt8Field addr_id>

Address ID.

token: int = <UInt32Field token>

Receiver’s token.

nonce: int = <UInt32Field nonce>

Sender’s random number.

class pcapkit.protocols.schema.transport.tcp.MPTCPJoinSYNACK(*args: _VT, **kwargs: _VT)

Bases: MPTCPJoin

Header schema for Multipath TCP join option for SYN/ACK connection.

test: MPTCPSubtypeJoin = <BitField test>

Subtype and flags.

addr_id: int = <UInt8Field addr_id>

Address ID.

hmac: bytes = <BytesField hmac>

Sender’s truncated HMAC

nonce: int = <UInt32Field nonce>

Sender’s random number.

class pcapkit.protocols.schema.transport.tcp.MPTCPJoinACK(*args: _VT, **kwargs: _VT)

Bases: MPTCPJoin

Header schema for Multipath TCP join option for ACK connection.

test: MPTCPSubtype = <BitField test>

Subtype and reserved.

hmac: bytes = <BytesField hmac>

Sender’s HMAC.

class pcapkit.protocols.schema.transport.tcp.MPTCPDSS(*args: _VT, **kwargs: _VT)

Bases: MPTCP

Header schema for Multipath TCP DSS option.

test: MPTCPSubtype = <BitField test>

Subtype and reserved.

flags: MPTCPDSSFlags = <BitField flags>

Flags.

ack: int = <SwitchField ack>

Data ACK.

4 octets when A is set, 8 when a is set as well, absent otherwise – RFC 8684 section 3.3 figure 9. Both the presence test and the width live in mptcp_dss_ack_selector(), whose note explains why the switch form is used.

dsn: int = <SwitchField dsn>

Data sequence number.

4 octets when M is set, 8 when m is set as well, absent otherwise – RFC 8684 section 3.3 figure 9. C.f. mptcp_dss_dsn_selector().

ssn: int = <ConditionalField ssn>

Subflow sequence number.

dl_len: int = <ConditionalField dl_len>

Data level length.

checksum: bytes = <ConditionalField checksum>

Checksum (if negotiated, c.f. mptcp_dss_checksum()).

class pcapkit.protocols.schema.transport.tcp.MPTCPAddAddress(*args: _VT, **kwargs: _VT)

Bases: MPTCP

Header schema for Multipath TCP add address option.

test: MPTCPSubtypeAddAddress = <BitField test>

Subtype and flags.

addr_id: int = <UInt8Field addr_id>

Address ID.

address: IPv4Address | IPv6Address = <SwitchField address>

Address.

port: int = <ConditionalField port>

Port.

hmac: bytes = <ConditionalField hmac>

Truncated HMAC.

class pcapkit.protocols.schema.transport.tcp.MPTCPRemoveAddress(*args: _VT, **kwargs: _VT)

Bases: MPTCP

Header schema for Multipath TCP remove address option.

test: MPTCPSubtype = <BitField test>

Subtype and reserved.

addr_id: list[int] = <ListField addr_id>

Address ID.

class pcapkit.protocols.schema.transport.tcp.MPTCPPriority(*args: _VT, **kwargs: _VT)

Bases: MPTCP

Header schema for Multipath TCP priority option.

test: MPTCPSubtypePriority = <BitField test>

Subtype.

addr_id: int = <ConditionalField addr_id>

Address ID.

class pcapkit.protocols.schema.transport.tcp.MPTCPFallback(*args: _VT, **kwargs: _VT)

Bases: MPTCP

Header schema for Multipath TCP fallback option.

test: MPTCPSubtype = <BitField test>

Subtype and reserved.

RFC 8684 section 3.7 figure 16 follows the subtype’s 4 bits with 12 reserved bits, so the Data Sequence Number starts at the fifth octet of the 12-octet option.

dsn: int = <UInt64Field dsn>

Data sequence number.

class pcapkit.protocols.schema.transport.tcp.MPTCPFastclose(*args: _VT, **kwargs: _VT)

Bases: MPTCP

Header schema for Multipath TCP fastclose option.

test: MPTCPSubtype = <BitField test>

Subtype and reserved.

RFC 8684 section 3.5 figure 14 spends a whole 32-bit row on Kind/Length/Subtype/(reserved), i.e. the subtype’s 4 bits are followed by 12 reserved bits, not 4 – so the subtype-and-reserved part is 2 octets and the option is 12 octets in total.

key: int = <UInt64Field key>

Option receiver’s key.

Type Stubs

class pcapkit.protocols.schema.transport.tcp.OffsetFlag

Bases: TypedDict

TCP offset field flag.

offset: int

Data offset.

reserved: int

Reserved bits.

ns: int

ECN-nonce concealment protection.

class pcapkit.protocols.schema.transport.tcp.Flags

Bases: TypedDict

TCP flags.

cwr: int

Congestion window reduced.

ece: int

ECN-Echo.

urg: int

Urgent pointer.

ack: int

Acknowledgment.

psh: int

Push function.

rst: int

Reset connection.

syn: int

Synchronize sequence numbers.

fin: int

Last packet from sender.

class pcapkit.protocols.schema.transport.tcp.POCProfile

Bases: TypedDict

TCP partial order connection service profile.

start: int

Start flag.

end: int

End flag.

reserved: int

Reserved bits (Filler).

class pcapkit.protocols.schema.transport.tcp.QuickStartFlags

Bases: TypedDict

TCP quick start flags.

reserved: int

Reserved bits.

rate: int

Rate request.

class pcapkit.protocols.schema.transport.tcp.QuickStartNonce

Bases: TypedDict

TCP quick start nonce.

nonce: int

Nonce.

reserved: int

Reserved bits (R).

class pcapkit.protocols.schema.transport.tcp.TimeoutInfo

Bases: TypedDict

User timeout information.

granularity: int

Granularity.

timeout: int

Timeout value.

class pcapkit.protocols.schema.transport.tcp.MPTCPSubtypeTest

Bases: TypedDict

TCP MPTCP subtype.

length: int

Length.

subtype: int

Subtype.

class pcapkit.protocols.schema.transport.tcp.MPTCPSubtypeUnknown

Bases: TypedDict

TCP unknown MPTCP subtype field.

subtype: int

Subtype.

data: int

Data.

class pcapkit.protocols.schema.transport.tcp.MPTCPSubtypeCapable

Bases: TypedDict

MPTCP Capable subtype field.

subtype: int

Subtype.

version: int

Version.

class pcapkit.protocols.schema.transport.tcp.MPTCPCapableFlags

Bases: TypedDict

MPTCP Capable flags.

req: int

Checksum required.

ext: int

Extensibility flag.

deny_join: int

Do not establish new subflows to the source address.

reserved: int

Reserved flags (D to G).

hsa: int

Use of HMAC-SHA1 under version 0, HMAC-SHA256 under version 1.

class pcapkit.protocols.schema.transport.tcp.MPTCPSubtypeJoin

Bases: TypedDict

MPTCP Join subtype field.

subtype: int

Subtype.

reserved: int

Reserved.

backup: int

Backup flag.

class pcapkit.protocols.schema.transport.tcp.MPTCPSubtype

Bases: TypedDict

MPTCP subtype field.

subtype: int

Subtype.

reserved: int

Reserved.

class pcapkit.protocols.schema.transport.tcp.MPTCPDSSFlags

Bases: TypedDict

MPTCP-DSS flags.

reserved: int

Reserved.

F: int

DATA_FIN flag.

m: int

Data sequence number is 8 octets (if not set, DSN is 4 octets).

M: int

Data Sequence Number (DSN), Subflow Sequence Number (SSN), Data-Level Length, and Checksum present.

a: int

Data ACK is 8 octets (if not set, Data ACK is 4 octets).

A: int

Data ACK present.

class pcapkit.protocols.schema.transport.tcp.MPTCPSubtypeAddAddress

Bases: TypedDict

MPTCP Add Address subtype field.

subtype: int

Subtype.

reserved: int

Reserved.

echo: int

Echo flag.

class pcapkit.protocols.schema.transport.tcp.MPTCPSubtypePriority

Bases: TypedDict

MPTCP Priority subtype field.

subtype: int

Subtype.

reserved: int

Reserved.

backup: int

Backup flag.

Auxiliary Functions

pcapkit.protocols.schema.transport.tcp.mptcp_data_selector(pkt)

Selector function for _MPTCP.data field.

Parameters:

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

Return type:

FieldBase

Returns:

A SchemaField wrapped MPTCP subclass instance.

pcapkit.protocols.schema.transport.tcp.mptcp_add_address_selector(pkt)

Selector function for MPTCPAddAddress.address field.

Parameters:

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

Return type:

FieldBase

Returns:

• If the option length is one of the IPv4 lengths, a IPv4AddressField instance.

• If the option length is one of the IPv6 lengths, a IPv6AddressField instance.

Note

RFC 8684 section 3.4.1 figure 12 has no IP version field: the address family follows from the option length, which is 8 or 20 for an IPv4 or IPv6 address, plus 2 with the port, plus 8 with the truncated HMAC. The RFC 6824 IPVer nibble occupies the bits RFC 8684 reserves and spends on E, and its lengths are the HMAC-less ones, so both layouts are read the same way.

pcapkit.protocols.schema.transport.tcp.mptcp_dss_checksum(pkt)

Condition function for MPTCPDSS.checksum field.

RFC 8684 section 3.3 makes the checksum part of the mapping only when checksums were negotiated, so a mapping without one is 2 octets shorter and only the option length tells the two forms apart.

Parameters:

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

Return type:

bool

Returns:

Whether the option length leaves room for the checksum after the Data ACK and the mapping.

pcapkit.protocols.schema.transport.tcp.mptcp_dss_ack_selector(pkt)

Selector function for MPTCPDSS.ack field.

RFC 8684 section 3.3 figure 9 gives the Data ACK as “4 or 8 octets, depending on flags”: present only when A is set, and 8 octets wide only when a is also set – “a = Data ACK is 8 octets (if not set, Data ACK is 4 octets)”.

Parameters:

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

Return type:

FieldBase

Returns:

• If A is clear, a NoValueField instance – the field is absent from the wire.

• If A is set and a is set, a UInt64Field instance.

• If A is set and a is clear, a UInt32Field instance.

Note

This is a SwitchField selector rather than a ConditionalField wrapping NumberField(length=lambda pkt: ...). An unextended Data ACK is 4 octets, so a width lambda returning 0 for it would leave the length octet counting 4 octets that were never packed.

The ConditionalField form could express this field correctly, since a callable-length NumberField packs and unpacks both the 4- and the 8-octet form, and wire absence is no obstacle: MPTCPDSS.ssn, MPTCPDSS.dl_len and MPTCPDSS.checksum are each a ConditionalField on the sibling M flag (the checksum on the option length as well). The SwitchField form is kept for a narrower reason about composition. A ConditionalField’s length forwards to the wrapped field unconditionally, never consulting the condition, so reading it while the condition is false – the wrapped field then still unresolved, at its -1 placeholder – raises struct.error: bad char in struct format. Nothing here meets that only because Schema’s pack and unpack special-case ConditionalField by type and skip the wrapped field outright before any length is read. A SwitchField needs no such special case: its selector always hands back an already-concrete field, NoValueField included, so its length is safe wherever it is read. Swapping the two would be a behaviour change, not a tidy-up.

pcapkit.protocols.schema.transport.tcp.mptcp_dss_dsn_selector(pkt)

Selector function for MPTCPDSS.dsn field.

RFC 8684 section 3.3 figure 9 gives the Data Sequence Number as “4 or 8 octets, depending on flags”: present only when M is set, and 8 octets wide only when m is also set – “m = Data Sequence Number is 8 octets (if not set, DSN is 4 octets)”.

Parameters:

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

Return type:

FieldBase

Returns:

• If M is clear, a NoValueField instance – the field is absent from the wire.

• If M is set and m is set, a UInt64Field instance.

• If M is set and m is clear, a UInt32Field instance.

Note

Identical in shape to mptcp_dss_ack_selector(); see that function’s note for why a SwitchField is used in place of a ConditionalField around a callable-length NumberField.

Data Models

class pcapkit.protocols.data.transport.tcp.TCP(*args: VT, **kwargs: VT)

Bases: Protocol

Data model for TCP packet.

srcport: AppType

Source port.

dstport: AppType

Destination port.

seq: int

Sequence number.

ack: int

Acknowledgment number.

hdr_len: int

Header length, i.e. the Data Offset in octets.

flags: Flags

Flags.

window_size: int

Window size.

checksum: bytes

Checksum.

urgent_pointer: int

Urgent pointer.

options: OrderedMultiInfo[Option, Option]

TCP options.

padding: bytes

Octets of the option area after the End of Option List option.

connection: Flags

Connection control flags.

class pcapkit.protocols.data.transport.tcp.Flags(*args: VT, **kwargs: VT)

Bases: Data

Data model for TCP flags.

ns: bool

ECN-nonce concealment protection.

cwr: bool

Congestion window reduced.

ece: bool

ECN-Echo.

urg: bool

Urgent.

ack: bool

Acknowledgment.

psh: bool

Push function.

rst: bool

Reset connection.

syn: bool

Synchronize sequence numbers.

fin: bool

Last packet from sender.

reserved: int

Reserved bits 4-6 of octet 12, between the Data Offset and NS.

class pcapkit.protocols.data.transport.tcp.Option(dict_=None, **kwargs)

Bases: Data

Data model for TCP options.

kind: Option

Option kind.

length: int

Option length.

class pcapkit.protocols.data.transport.tcp.UnassignedOption(*args: VT, **kwargs: VT)

Bases: Option

Data model for unassigned TCP option.

data: bytes

Option data.

class pcapkit.protocols.data.transport.tcp.EndOfOptionList(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP end of option list option.

class pcapkit.protocols.data.transport.tcp.NoOperation(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP no operation option.

class pcapkit.protocols.data.transport.tcp.MaximumSegmentSize(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP maximum segment size option.

mss: int

Maximum segment size.

class pcapkit.protocols.data.transport.tcp.WindowScale(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP window scale option.

shift: int

Window scale.

class pcapkit.protocols.data.transport.tcp.SACKPermitted(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP SACK permitted option.

class pcapkit.protocols.data.transport.tcp.SACK(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP SACK option.

sack: tuple[SACKBlock, ...]

SACK blocks.

class pcapkit.protocols.data.transport.tcp.SACKBlock(*args: VT, **kwargs: VT)

Bases: Data

Data model for TCP SACK block.

left: int

Left edge.

right: int

Right edge.

class pcapkit.protocols.data.transport.tcp.Echo(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP echo option.

data: bytes

Echo data.

class pcapkit.protocols.data.transport.tcp.EchoReply(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP echo reply option.

data: bytes

Echo data.

class pcapkit.protocols.data.transport.tcp.Timestamps(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP timestamp option.

Changed in version 1.1.0: Renamed from Timestamp, which pcapkit.protocols.data exported as TCP_Timestamp; the export is TCP_Timestamps.

timestamp: int

Timestamp value.

echo: int

Timestamp echo reply.

class pcapkit.protocols.data.transport.tcp.PartialOrderConnectionPermitted(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP partial order connection permitted option.

class pcapkit.protocols.data.transport.tcp.PartialOrderServiceProfile(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP partial order connection service profile option.

Changed in version 1.1.0: Renamed from PartialOrderConnectionProfile, which pcapkit.protocols.data exported as TCP_PartialOrderConnectionProfile; the export is TCP_PartialOrderServiceProfile.

start: bool

Start flag.

end: bool

End flag.

reserved: int

Reserved bits (Filler).

class pcapkit.protocols.data.transport.tcp.CC(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP CC option.

cc: int

Connection count.

class pcapkit.protocols.data.transport.tcp.CCNew(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP CC.NEW option.

cc: int

Connection count.

class pcapkit.protocols.data.transport.tcp.CCEcho(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP CC.ECHO option.

cc: int

Connection count.

class pcapkit.protocols.data.transport.tcp.AlternateChecksumRequest(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP alternate checksum request option.

chksum: Checksum

Checksum algorithm.

class pcapkit.protocols.data.transport.tcp.AlternateChecksumData(kind, length, data)

Bases: Option

Data model for TCP alternate checksum data option.

data: bytes

Checksum data.

class pcapkit.protocols.data.transport.tcp.MD5Signature(kind, length, digest)

Bases: Option

Data model for TCP MD5 signature option.

digest: bytes

MD5 signature.

class pcapkit.protocols.data.transport.tcp.QuickStartResponse(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP quick start response option.

req_rate: int

Rate request.

ttl_diff: int

TTL difference.

nonce: int

QS nonce.

reserved: int

Reserved bits before the rate request (Resv.).

nonce_reserved: int

Reserved bits after the QS nonce (R).

class pcapkit.protocols.data.transport.tcp.UserTimeout(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP user timeout option.

timeout: timedelta

User timeout.

granularity: bool

the timeout is in minutes if set, in seconds if not.

Type:

Granularity (G)

class pcapkit.protocols.data.transport.tcp.Authentication(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP authentication option.

key_id: int

Key ID.

next_key_id: int

Receive next key ID.

mac: bytes

MAC.

class pcapkit.protocols.data.transport.tcp.FastOpenCookie(*args: VT, **kwargs: VT)

Bases: Option

Data model for TCP fast open cookie option.

cookie: bytes

Cookie.

class pcapkit.protocols.data.transport.tcp.MPTCP(dict_=None, **kwargs)

Bases: Option

Data model for TCP MPTCP option.

subtype: MPTCPOption

Subtype.

class pcapkit.protocols.data.transport.tcp.MPTCPUnknown(*args: VT, **kwargs: VT)

Bases: MPTCP

Data model for TCP unknown MPTCP option.

data: bytes

Data.

class pcapkit.protocols.data.transport.tcp.MPTCPCapable(*args: VT, **kwargs: VT)

Bases: MPTCP

Data model for TCP MP_CAPABLE option.

version: int

Version.

flags: MPTCPCapableFlag

Flags.

skey: int | None

Option sender’s key.

rkey: int | None

Option receiver’s key.

dl_len: int | None

Data-level length.

checksum: bytes | None

Checksum.

class pcapkit.protocols.data.transport.tcp.MPTCPCapableFlag(*args: VT, **kwargs: VT)

Bases: Data

Data model for TCP MPTCP capable option flags.

req: bool

Checksum required flag.

ext: bool

Extensibility flag.

deny_join: bool

Flag for not establishing new subflows to the source address (C).

reserved: int

Reserved flags (D to G).

hsa: bool

HMAC-SHA1 under version 0 (RFC 6824), HMAC-SHA256 under version 1 (RFC 8684).

Type:

HMAC algorithm flag (H)

class pcapkit.protocols.data.transport.tcp.MPTCPJoin(dict_=None, **kwargs)

Bases: MPTCP

Data model for TCP MP_JOIN option.

connection: Flags

Connection type.

class pcapkit.protocols.data.transport.tcp.MPTCPJoinSYN(*args: VT, **kwargs: VT)

Bases: MPTCPJoin

Data model for TCP MP_JOIN-SYN option.

reserved: int

Reserved.

backup: bool

Backup path flag.

addr_id: int

Address ID.

token: int

Receiver’s token.

nonce: int

Sender’s random number.

class pcapkit.protocols.data.transport.tcp.MPTCPJoinSYNACK(*args: VT, **kwargs: VT)

Bases: MPTCPJoin

Data model for TCP MP_JOIN-SYNACK option.

reserved: int

Reserved.

backup: bool

Backup path flag.

addr_id: int

Address ID.

hmac: bytes

Sender’s truncated HMAC.

nonce: int

Sender’s random number.

class pcapkit.protocols.data.transport.tcp.MPTCPJoinACK(*args: VT, **kwargs: VT)

Bases: MPTCPJoin

Data model for TCP MP_JOIN-ACK option.

reserved: int

Reserved.

hmac: bytes

HMAC value.

class pcapkit.protocols.data.transport.tcp.MPTCPDSS(*args: VT, **kwargs: VT)

Bases: MPTCP

Data model for TCP DSS option.

reserved: int

Reserved.

data_fin: bool

DATA_FIN flag.

ack_wide: bool

Data ACK is 8 octets (a flag).

ack: int | None

Data ACK.

dsn_wide: bool

Data sequence number is 8 octets (m flag).

dsn: int | None

Data sequence number.

ssn: int | None

Subflow sequence number.

dl_len: int | None

Data-level length.

checksum: bytes | None

Checksum.

class pcapkit.protocols.data.transport.tcp.MPTCPAddAddress(*args: VT, **kwargs: VT)

Bases: MPTCP

Data model for TCP ADD_ADDR option.

version: int

IP version.

reserved: int

Reserved.

echo: bool

Echo flag.

addr_id: int

Address ID.

addr: IPv4Address | IPv6Address

Address.

port: int | None

Port number.

hmac: bytes | None

Truncated HMAC.

class pcapkit.protocols.data.transport.tcp.MPTCPRemoveAddress(*args: VT, **kwargs: VT)

Bases: MPTCP

Data model for TCP REMOVE_ADDR option.

reserved: int

Reserved.

addr_id: tuple[int, ...]

Address ID.

class pcapkit.protocols.data.transport.tcp.MPTCPPriority(*args: VT, **kwargs: VT)

Bases: MPTCP

Data model for TCP MP_PRIO option.

reserved: int

Reserved.

backup: bool

Backup path flag.

addr_id: int | None

Address ID.

class pcapkit.protocols.data.transport.tcp.MPTCPFallback(*args: VT, **kwargs: VT)

Bases: MPTCP

Data model for TCP MP_FAIL option.

reserved: int

Reserved.

dsn: int

Data sequence number.

class pcapkit.protocols.data.transport.tcp.MPTCPFastclose(*args: VT, **kwargs: VT)

Bases: MPTCP

Data model for TCP MP_FASTCLOSE option.

reserved: int

Reserved.

rkey: int

Option receiver’s key.

Footnotes

[*]

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