TCP - Transmission Control Protocol

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

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.protocol.TCP(file=None, length=None, **kwargs)[source]

Bases: Transport[TCP, TCP]

This class implements Transmission Control Protocol.

The self.__proto__ registry binds these ports:

Port Number

Protocol

20

pcapkit.protocols.application.ftp_data.protocol.FTP_DATA

21

pcapkit.protocols.application.ftp.protocol.FTP

80

pcapkit.protocols.application.http.protocol.HTTP

443

pcapkit.protocols.application.tls.protocol.TLS

8080

pcapkit.protocols.application.http.protocol.HTTP

The TCP options it parses, by pcapkit.const.tcp.option.Option code:

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()

The Multipath TCP options it parses, by pcapkit.const.tcp.mp_tcp_option.MPTCPOption subtype:

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 each 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).

Changed in version 1.6.0:

  • Port 443 binds TLS (#2437).

  • The checksum is computed when make() is given none, over the pseudo it is given or by the enclosing IP layer, and verified by that layer under CHECKSUM_VERIFY (#2473).

  • A Quick-Start rate the four-bit rate code cannot carry, or a nonce or reserved value outside its field, raises ProtocolError, rather than a bare ValueError, an OverflowError or a FieldValueError, or a rate of zero written in its place (#2617).

  • make() and the option makers raise ProtocolError for an integer field given a value its width cannot hold, rather than writing its low bits or raising a FieldValueError or a bare ValueError, and for a fixed-size octet field given the wrong number of octets, rather than padding or cutting them. A User Timeout that is neither an int nor a timedelta raises the same, rather than an AttributeError. The Quick-Start TTL Diff wraps, as RFC 4782 defines it modulo 256 (#2614).

  • Each enumeration field of the option makers, the alternate checksum algorithm and the Multipath TCP subtype, and the kind of each option given to make(), takes a member or an int code, resolved with the enumeration’s get; a name, a bool, or a code the field cannot carry raises ProtocolError, rather than resolving against an enumeration inferred from the caller’s frame, writing a different value or raising another exception (#2594).

  • An option given to make() as raw octets, of a kind no member of Option holds, such as 255, which parses as an unassigned option, builds as its (code, arguments) pair does, rather than raising EnumValueError; and empty raw octets, which hold no kind, raise ProtocolError rather than an IndexError (#2708).

  • A header make() builds, such as the one from_data() rebuilds, reads the octets after its End of Option List as padding, as a parse of its octets does, rather than as empty (#2769).

Removed in version 1.6.0: The algorithm_default, algorithm_namespace and algorithm_reversed arguments of the alternate checksum request option maker, and the subtype_default, subtype_namespace and subtype_reversed arguments of the Multipath TCP option maker; resolve a name with resolve_index() first (#2594).

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

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

__proto_key__: ClassVar[tuple[Type[EnumRegistry], bool]]

What __proto__ is keyed by – the enum a key must be a member of, and whether a bare int is valid too. Read by register_protocol_code() to check a code= key as register_tcp() checks its own; a bare int is a port number, which an AppType member carries (#2268).

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

Option code to method mapping, see _read_tcp_options() and _make_tcp_options(). A str value names the methods _read_mode_${name} and _make_mode_${name}, falling back to _read_mode_donone() and _make_mode_donone() when the class has no such method; any other value is a (parser, constructor) pair of callables.

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

Option code to method mapping, see _read_mode_mp() and _make_mode_mp(). A str value names the methods _read_mptcp_${name} and _make_mptcp_${name}, falling back to _read_mptcp_unknown() and _make_mptcp_unknown() when the class has no such method; any other value is a (parser, constructor) pair of callables.

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.

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

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=None, urgent=0, options=None, payload=b'', padding=b'', reserved=0, pseudo=None, **kwargs)[source]

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 | None) – Checksum; if None and CHECKSUM_COMPUTE is on, computed over pseudo (RFC 793 Section 3.1), or left to an IP layer this segment is the payload of; zero otherwise.

  • urgent (int) – Urgent pointer.

  • options (list[Option | tuple[Option | int, 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.

  • pseudo (IP_Pseudo | None) – Pseudo-header of the enclosing IP layer; its length is replaced by this segment’s own.

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

Return type:

TCP

Returns:

Constructed packet data.

Raises:

ProtocolError – If srcport or dstport is a bool (#2287), a numeric field does not fit its width, or checksum is not two octets.

Changed in version 1.5.0: An out-of-range srcport or dstport raises ValueError rather than being accepted (#758).

classmethod register_option(code, meth)[source]

Register an option parser.

Parameters:
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. Re-registering the entry code shipped with is accepted like any other, so an override can be undone (#1362, #1363).

classmethod register_mp_option(code, meth)[source]

Register an MPTCP option parser.

Parameters:
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. Re-registering the entry code shipped with is accepted like any other, so an override can be undone (#1362, #1363).

classmethod __index__()[source]

Numeral registry index of the protocol.

Return type:

TransType

Returns:

Numeral registry index of the protocol in IANA.

classmethod _make_data(data)[source]

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

Read TCP option list.

Parameters:

size (int) – length of option list

Return type:

OrderedMultiDict[Option, Option]

Returns:

Extracted TCP options.

Raises:

ProtocolError – If the options run past size.

_make_tcp_options(options, padding=b'')[source]

Make options for TCP.

Parameters:
Return type:

tuple[list[Option | bytes], int]

Returns:

Tuple of options and total length of options.

Raises:

  • ProtocolError – If an option’s kind is a name, a bool, or a code the 8-bit kind octet cannot carry (#2594), if an option given as raw octets is empty (#2708), or if an option maker rejects its option, e.g. a user timeout too large for 15 bits of minutes, an MPTCP subtype or an alternate checksum algorithm given by name, or an MPTCP option whose fields, or the segment’s flags, it cannot encode.

  • FieldValueError – If an ADD_ADDR addr is a bool or not a valid IP address.

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.

_read_mode_donone(schema, *, options)[source]

Read TCP unassigned option.

Parameters:
Return type:

UnassignedOption

Returns:

Parsed option data.

_read_mode_eool(schema, *, options)[source]

Read TCP End of Option List option.

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

+--------+
|00000000|
+--------+
 Kind=0
Parameters:
Return type:

EndOfOptionList

Returns:

Parsed option data.

_read_mode_nop(schema, *, options)[source]

Read TCP No Operation option.

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

+--------+
|00000001|
+--------+
 Kind=1
Parameters:
Return type:

NoOperation

Returns:

Parsed option data.

_read_mode_mss(schema, *, options)[source]

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:
Return type:

MaximumSegmentSize

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 4.

_read_mode_ws(schema, *, options)[source]

Read TCP window scale option.

Structure of TCP window scale option [RFC 7323]:

+---------+---------+---------+
| Kind=3  |Length=3 |shift.cnt|
+---------+---------+---------+
     1         1         1
Parameters:
Return type:

WindowScale

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 3.

_read_mode_sackpmt(schema, *, options)[source]

Read TCP SACK permitted option.

Structure of TCP SACK permitted option [RFC 2018]:

+---------+---------+
| Kind=4  | Length=2|
+---------+---------+
Parameters:
Return type:

SACKPermitted

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 2.

_read_mode_sack(schema, *, options)[source]

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:
Return type:

SACK

Returns:

Parsed option data.

Raises:

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

_read_mode_echo(schema, *, options)[source]

Read TCP echo option.

Structure of TCP echo option [RFC 1072]:

+--------+--------+--------+--------+--------+--------+
| Kind=6 | Length |   4 bytes of info to be echoed    |
+--------+--------+--------+--------+--------+--------+
Parameters:
Return type:

Echo

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 6.

_read_mode_echore(schema, *, options)[source]

Read TCP echo reply option.

Structure of TCP echo reply option [RFC 1072]:

+--------+--------+--------+--------+--------+--------+
| Kind=7 | Length |    4 bytes of echoed info         |
+--------+--------+--------+--------+--------+--------+
Parameters:
Return type:

EchoReply

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 6.

_read_mode_ts(schema, *, options)[source]

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:
Return type:

Timestamps

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 10.

_read_mode_poc(schema, *, options)[source]

Read TCP partial order connection permitted option.

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

+-----------+-------------+
|  Kind=9   |  Length=2   |
+-----------+-------------+
Parameters:
Return type:

PartialOrderConnectionPermitted

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 2.

_read_mode_pocsp(schema, *, options)[source]

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:
Return type:

PartialOrderServiceProfile

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 3.

_read_mode_cc(schema, *, options)[source]

Read TCP connection count option.

Structure of TCP CC option [RFC 1644]:

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

CC

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 6.

_read_mode_ccnew(schema, *, options)[source]

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:
Return type:

CCNew

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 6.

_read_mode_ccecho(schema, *, options)[source]

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:
Return type:

CCEcho

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 6.

_read_mode_chkreq(schema, *, options)[source]

Read TCP Alternate Checksum Request option.

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

+----------+----------+----------+
|  Kind=14 | Length=3 |  chksum  |
+----------+----------+----------+
Parameters:
Return type:

AlternateChecksumRequest

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 3.

_read_mode_chksum(schema, *, options)[source]

Read Alternate Checksum Data option.

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

+---------+---------+---------+     +---------+
| Kind=15 |Length=N |  data   | ... |  data   |
+---------+---------+---------+     +---------+
Parameters:
Return type:

AlternateChecksumData

Returns:

Parsed option data.

_read_mode_sig(schema, *, options)[source]

Read MD5 Signature option.

Structure of TCP SIG option [RFC 2385]:

+---------+---------+-------------------+
| Kind=19 |Length=18|   MD5 digest...   |
+---------+---------+-------------------+
|                                       |
+---------------------------------------+
|                                       |
+---------------------------------------+
|                                       |
+-------------------+-------------------+
|                   |
+-------------------+
Parameters:
Return type:

MD5Signature

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 18.

_read_mode_qs(schema, *, options)[source]

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:
Return type:

QuickStartResponse

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 8.

_read_mode_timeout(schema, *, options)[source]

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:
Return type:

UserTimeout

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 4.

_read_mode_ao(schema, *, options)[source]

Read Authentication option.

Structure of TCP AOopt [RFC 5925]:

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

...-----------------+
...  MAC (con't)    |
...-----------------+
Parameters:
Return type:

Authentication

Returns:

Parsed option data.

Raises:

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

_read_mode_mp(schema, *, options)[source]

Read Multipath TCP option.

Structure of MP-TCP [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|                       |
+---------------+---------------+-------+                       |
|                     Subtype-specific data                     |
|                       (variable length)                       |
+---------------------------------------------------------------+
Parameters:
Return type:

MPTCP

Returns:

Parsed option data.

_read_mptcp_unknown(schema, *, options)[source]

Read unknown MPTCP subtype.

Parameters:
Return type:

MPTCPUnknown

Returns:

Parsed option data.

_read_mptcp_capable(schema, *, options)[source]

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:
Return type:

MPTCPCapable

Returns:

Parsed option data.

Raises:

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

_read_mptcp_join(schema, *, options)[source]

Read Join Connection option.

Parameters:
Return type:

MPTCPJoin

Returns:

Parsed option data.

Raises:

ProtocolError – If the segment carries neither SYN nor ACK.

_read_mptcp_dss(schema, *, options)[source]

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:
Return type:

MPTCPDSS

Returns:

Parsed option data.

Raises:

ProtocolError – If the length is not the one the A, a, M and m flags give, or, with M set, that plus the 2-octet checksum.

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.

Changed in version 1.6.0: A length the flags do not give is refused, rather than read with the missing fields as zeros or the extra octets dropped (#2669).

_read_mptcp_addaddr(schema, *, options)[source]

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

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

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:
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, the one with an Address ID, as this method accepts both forms. RFC 8684 section 3.3.8 figure 11 draws MP_PRIO as 3 octets – Kind (1) + Length (1) + subtype/reserved/B (1) – since its section 5 “specifies the removal of the AddrID field [RFC6824] in the MP_PRIO option”, closing an attack that could force a subflow into backup mode. The 4-octet form is 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)[source]

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:
Return type:

MPTCPFallback

Returns:

Parsed option data.

Raises:

ProtocolError – If the length is NOT 12.

_read_mptcp_fastclose(schema, options)[source]

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:
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_mode_fastopen(schema, *, options)[source]

Read Fast Open option.

Structure of TCP FASTOPEN [RFC 7413]:

                                +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                                |      Kind     |    Length     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
~                            Cookie                             ~
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Parameters:
Return type:

FastOpenCookie

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT valid.

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

Make TCP unassigned option.

Parameters:
Return type:

UnassignedOption

Returns:

Constructed option schema.

_make_mode_eool(code, opt=None, **kwargs)[source]

Make TCP End of Option List option.

Parameters:
Return type:

EndOfOptionList

Returns:

Constructed option schema.

_make_mode_nop(code, opt=None, **kwargs)[source]

Make TCP NoOperation option.

Parameters:
Return type:

NoOperation

Returns:

Constructed option schema.

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

Make TCP maximum segment size option.

Parameters:
Return type:

MaximumSegmentSize

Returns:

Constructed option schema.

Raises:

ProtocolError – If mss does not fit 16 bits.

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

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.

Raises:

ProtocolError – If shift does not fit 8 bits.

_make_mode_sackpmt(code, opt=None, **kwargs)[source]

Make TCP SACK permitted option.

Parameters:
Return type:

SACKPermitted

Returns:

Constructed option schema.

_make_mode_sack(code, opt=None, *, sack=None, **kwargs)[source]

Make TCP SACK option.

Parameters:
Return type:

SACK

Returns:

Constructed option schema.

Raises:

ProtocolError – If an edge of sack does not fit 32 bits.

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

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.

Raises:

ProtocolError – If data is not four octets.

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

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.

Raises:

ProtocolError – If data is not four octets.

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

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.

Raises:

ProtocolError – If tsval or tsecr does not fit 32 bits.

_make_mode_poc(code, opt=None, **kwargs)[source]

Make TCP partial order connection option.

Parameters:
Return type:

PartialOrderConnectionPermitted

Returns:

Constructed option schema.

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

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.

Raises:

ProtocolError – If reserved does not fit 6 bits.

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

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.

Raises:

ProtocolError – If count does not fit 32 bits.

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

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.

Raises:

ProtocolError – If count does not fit 32 bits.

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

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.

Raises:

ProtocolError – If count does not fit 32 bits.

_make_mode_chkreq(code, opt=None, *, algorithm=Checksum.TCP_checksum, **kwargs)[source]

Make TCP alternate checksum request option.

Parameters:
Return type:

AlternateChecksumRequest

Returns:

Constructed option schema.

Raises:

ProtocolError – If algorithm is a name, a bool, or a member or code that does not fit 8 bits.

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

Make TCP alternate checksum data option.

Parameters:
Return type:

AlternateChecksumData

Returns:

Constructed option schema.

_make_mode_sig(code, opt=None, *, digest=bytes(16), **kwargs)[source]

Make TCP MD5 signature option.

Parameters:
Return type:

MD5Signature

Returns:

Constructed option schema.

Raises:

ProtocolError – If digest is not 16 octets.

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

Make TCP quick start response option.

Parameters:

  • code (Option) – option code

  • opt (QuickStartResponse | None) – option data

  • rate (int) – rate (in kbps), rounded down to the nearest rate the four-bit rate code carries (RFC 4782 Section 4.2)

  • diff (timedelta | int) – TTL Diff, the IP TTL minus the QS TTL, modulo 256 (RFC 4782 Section 4.2); a timedelta is taken as its whole seconds

  • 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.

Raises:

ProtocolError – If the rate code cannot carry rate, or nonce, reserved or nonce_reserved does not fit its field.

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

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 is a bool, is neither an int nor a timedelta, is negative, or does not fit in 15 bits of minutes.

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

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.

Raises:

ProtocolError – If key_id or next_key_id does not fit 8 bits.

_make_mode_mp(code, opt=None, *, subtype=MPTCPOption.MP_CAPABLE, **kwargs)[source]

Make multipath TCP option.

Parameters:
Return type:

MPTCP

Returns:

Constructed option schema.

Raises:

ProtocolError – If subtype is a name, a bool, or a member or code that does not fit 4 bits.

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

Make unknown multipath TCP option.

Parameters:

  • subtype (MPTCPOption) – MPTCP subtype

  • opt (MPTCPUnknown | None) – option data

  • data (bytes) – option payload data, its first octet the four bits after the subtype

  • **kwargs (Any) – arbitrary keyword arguments

Return type:

MPTCPUnknown

Returns:

Constructed option schema.

Raises:

ProtocolError – If the first octet of data does not fit four bits.

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

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, or does not fit its width.

_make_mptcp_join(subtype, opt=None, **kwargs)[source]

Make multipath TCP join option.

Parameters:
Return type:

MPTCPJoin

Returns:

Constructed option schema.

Raises:

ProtocolError – If the segment’s flags are none of SYN, SYN/ACK and ACK.

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

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, a 4-octet field is asked to hold a value wider than 32 bits, or a field does not fit its width.

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

Make multipath TCP add address option.

Parameters:
Return type:

MPTCPAddAddress

Returns:

Constructed option schema.

Raises:

  • ProtocolError – If hmac is not 8 octets, or is given together with echo set, or a field does not fit its width.

  • FieldValueError – If addr is a bool or not a valid IP address.

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

Make multipath TCP remove address option.

Parameters:
Return type:

MPTCPRemoveAddress

Returns:

Constructed option schema.

Raises:

ProtocolError – If reserved does not fit 4 bits, or an address ID 8 bits.

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

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.

Raises:

ProtocolError – If reserved does not fit 3 bits, or addr_id 8 bits.

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

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.

Raises:

ProtocolError – If reserved does not fit 12 bits, or dsn 64 bits.

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

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.

Raises:

ProtocolError – If reserved does not fit 12 bits, or key 64 bits.

_make_mode_fastopen(code, opt=None, *, cookie=None, **kwargs)[source]

Make TCP Fast Open option.

Parameters:
Return type:

FastOpenCookie

Returns:

Constructed option schema.

_verify_pseudo_checksum(pseudo)[source]

Verify the checksum over the pseudo-header of the enclosing IP layer.

That layer calls this once parsed, see verify_upper(). A zero checksum, or the pseudo-header’s sum alone, is what checksum offload leaves on the sending host, and is NOT_COMPUTED.

Parameters:

pseudo (IP_Pseudo | None) – Pseudo-header, or None if the IP layer gives none.

_read_join_syn(schema, *, options)[source]

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:
Return type:

MPTCPJoinSYN

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 12.

_read_join_synack(schema, options)[source]

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

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:
Return type:

MPTCPJoinACK

Returns:

Parsed option data.

Raises:

ProtocolError – If length is NOT 24.

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

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.

Raises:

ProtocolError – If a field does not fit its width.

_make_join_synack(subtype, opt=None, *, reserved=0, backup=False, addr_id=0, hmac=bytes(8), nonce=0, **kwargs)[source]

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.

Raises:

ProtocolError – If a field does not fit its width, or hmac is not eight octets.

_make_join_ack(subtype, opt=None, *, reserved=0, hmac=bytes(20), **kwargs)[source]

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.

Raises:

ProtocolError – If reserved does not fit 12 bits, or hmac is not 20 octets.

Header Schemas

Removed in version 1.6.0: pcapkit.protocols.schema.transport.tcp, with no alias: the module moved here (#2534).

pcapkit.protocols.transport.tcp.schema.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.transport.tcp.schema.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.transport.tcp.schema.TCP(srcport=NO_VALUE, dstport=NO_VALUE, seq=NO_VALUE, ack=NO_VALUE, offset=NO_VALUE, flags=NO_VALUE, window=NO_VALUE, checksum=NO_VALUE, urgent=NO_VALUE, options=NO_VALUE, padding=NO_VALUE, payload=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.Flags[source]

Bases: TypedDict

TCP flags.

cwr: int

Congestion window reduced.

ece: int

ECN-Echo.

urg: int

Urgent.

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.transport.tcp.schema.Option(*args, **kwargs)[source]

Bases: EnumSchema[Option]

Header schema for TCP options.

kind: Option = <EnumField kind>

Option kind.

length: int = <ConditionalField length>

Option length.

post_process(packet)[source]

Revise schema data after unpacking process.

Parameters:

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

Return type:

Schema

Returns:

Revised schema.

class pcapkit.protocols.transport.tcp.schema.UnassignedOption(kind=NO_VALUE, length=NO_VALUE, data=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP unassigned options.

data: bytes = <BytesField data>

Option data.

class pcapkit.protocols.transport.tcp.schema.EndOfOptionList(kind=NO_VALUE, length=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP end of option list.

class pcapkit.protocols.transport.tcp.schema.NoOperation(kind=NO_VALUE, length=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP no operation.

class pcapkit.protocols.transport.tcp.schema.MaximumSegmentSize(kind=NO_VALUE, length=NO_VALUE, mss=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP max segment size option.

mss: int = <UInt16Field mss>

Maximum segment size.

class pcapkit.protocols.transport.tcp.schema.WindowScale(kind=NO_VALUE, length=NO_VALUE, shift=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP window scale option.

shift: int = <UInt8Field shift>

Window scale (shift count).

class pcapkit.protocols.transport.tcp.schema.SACKPermitted(kind=NO_VALUE, length=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP SACK permitted option.

class pcapkit.protocols.transport.tcp.schema.SACK(kind=NO_VALUE, length=NO_VALUE, sack=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP SACK option.

sack: list[SACKBlock] = <ListField sack>

Selected ACK data.

class pcapkit.protocols.transport.tcp.schema.SACKBlock(left=NO_VALUE, right=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.Echo(kind=NO_VALUE, length=NO_VALUE, data=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP echo option.

data: bytes = <BytesField data>

Info to be echoed.

class pcapkit.protocols.transport.tcp.schema.EchoReply(kind=NO_VALUE, length=NO_VALUE, data=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP echo reply option.

data: bytes = <BytesField data>

Echoed info.

class pcapkit.protocols.transport.tcp.schema.Timestamps(kind=NO_VALUE, length=NO_VALUE, value=NO_VALUE, reply=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.PartialOrderConnectionPermitted(kind=NO_VALUE, length=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP partial order connection permitted option.

class pcapkit.protocols.transport.tcp.schema.PartialOrderServiceProfile(kind=NO_VALUE, length=NO_VALUE, profile=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.CC(kind=NO_VALUE, length=NO_VALUE, count=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP CC option.

count: int = <UInt32Field count>

Connection count.

class pcapkit.protocols.transport.tcp.schema.CCNew(kind=NO_VALUE, length=NO_VALUE, count=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP connection count (new) option.

count: int = <UInt32Field count>

Connection count.

class pcapkit.protocols.transport.tcp.schema.CCEcho(kind=NO_VALUE, length=NO_VALUE, count=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP connection count (echo) option.

count: int = <UInt32Field count>

Connection count.

class pcapkit.protocols.transport.tcp.schema.AlternateChecksumRequest(kind=NO_VALUE, length=NO_VALUE, algorithm=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP alternate checksum request option.

algorithm: Checksum = <EnumField algorithm>

Checksum algorithm.

class pcapkit.protocols.transport.tcp.schema.AlternateChecksumData(kind=NO_VALUE, length=NO_VALUE, data=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP alternate checksum data option.

data: bytes = <BytesField data>

Checksum data.

class pcapkit.protocols.transport.tcp.schema.MD5Signature(kind=NO_VALUE, length=NO_VALUE, digest=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP MD5 signature option.

digest: bytes = <BytesField digest>

MD5 digest.

class pcapkit.protocols.transport.tcp.schema.QuickStartResponse(kind=NO_VALUE, length=NO_VALUE, flags=NO_VALUE, diff=NO_VALUE, nonce=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.UserTimeout(kind=NO_VALUE, length=NO_VALUE, info=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP user timeout option.

info: TimeoutInfo = <BitField info>

Granularity and user timeout.

class pcapkit.protocols.transport.tcp.schema.Authentication(kind=NO_VALUE, length=NO_VALUE, key_id=NO_VALUE, next_key_id=NO_VALUE, mac=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.FastOpenCookie(kind=NO_VALUE, length=NO_VALUE, cookie=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Option

Header schema for TCP Fast Open option.

cookie: bytes = <ConditionalField cookie>

Cookie.

class pcapkit.protocols.transport.tcp.schema._MPTCP(test=NO_VALUE, data=NO_VALUE, *, __packet__=None, **kwargs)[source]

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, so it consumes kind and length itself. In this 3-octet window length is bits 8-15 and the subtype bits 16-19 (RFC 8684 section 3).

data: MPTCP = <SwitchField data>

Subtype-specific data.

post_process(packet)[source]

Revise schema data after unpacking process.

Parameters:

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

Return type:

MPTCP

Returns:

Revised schema.

class pcapkit.protocols.transport.tcp.schema.MPTCP(*args, **kwargs)[source]

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.

Each subtype schema is handed the whole option from its first octet, through mptcp_data_selector, so a subclass’s test field starts at the third octet, after kind and length, and its conditions can read pkt['length'].

kind: Option = <EnumField kind>

Option kind.

length: int = <UInt8Field length>

MPTCP length.

subtype: MPTCPOption

MPTCP subtype.

class pcapkit.protocols.transport.tcp.schema.MPTCPUnknown(kind=NO_VALUE, length=NO_VALUE, test=NO_VALUE, data=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: MPTCP

Header schema for unknown Multipath TCP option.

test: MPTCPSubtypeUnknown = <BitField test>

Subtype and data.

data: bytes = <BytesField data>

Data.

class pcapkit.protocols.transport.tcp.schema.MPTCPCapable(kind=NO_VALUE, length=NO_VALUE, test=NO_VALUE, flags=NO_VALUE, skey=NO_VALUE, rkey=NO_VALUE, dl_len=NO_VALUE, checksum=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.MPTCPJoin(*args, **kwargs)[source]

Bases: MPTCP

Header schema for Multipath TCP join option.

class pcapkit.protocols.transport.tcp.schema.MPTCPJoinSYN(kind=NO_VALUE, length=NO_VALUE, test=NO_VALUE, addr_id=NO_VALUE, token=NO_VALUE, nonce=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.MPTCPJoinSYNACK(kind=NO_VALUE, length=NO_VALUE, test=NO_VALUE, addr_id=NO_VALUE, hmac=NO_VALUE, nonce=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.MPTCPJoinACK(kind=NO_VALUE, length=NO_VALUE, test=NO_VALUE, hmac=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.MPTCPDSS(kind=NO_VALUE, length=NO_VALUE, test=NO_VALUE, flags=NO_VALUE, ack=NO_VALUE, dsn=NO_VALUE, ssn=NO_VALUE, dl_len=NO_VALUE, checksum=NO_VALUE, *, __packet__=None, **kwargs)[source]

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. See 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, see mptcp_dss_checksum()).

class pcapkit.protocols.transport.tcp.schema.MPTCPAddAddress(kind=NO_VALUE, length=NO_VALUE, test=NO_VALUE, addr_id=NO_VALUE, address=NO_VALUE, port=NO_VALUE, hmac=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.MPTCPRemoveAddress(kind=NO_VALUE, length=NO_VALUE, test=NO_VALUE, addr_id=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.MPTCPPriority(kind=NO_VALUE, length=NO_VALUE, test=NO_VALUE, addr_id=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.MPTCPFallback(kind=NO_VALUE, length=NO_VALUE, test=NO_VALUE, dsn=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.MPTCPFastclose(kind=NO_VALUE, length=NO_VALUE, test=NO_VALUE, key=NO_VALUE, *, __packet__=None, **kwargs)[source]

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.transport.tcp.schema.OffsetFlag[source]

Bases: TypedDict

TCP offset field flag.

offset: int

Data offset.

reserved: int

Reserved bits.

ns: int

ECN-nonce concealment protection.

class pcapkit.protocols.transport.tcp.schema.POCProfile[source]

Bases: TypedDict

TCP partial order connection service profile.

start: int

Start flag.

end: int

End flag.

reserved: int

Reserved bits (Filler).

class pcapkit.protocols.transport.tcp.schema.QuickStartFlags[source]

Bases: TypedDict

TCP quick start flags.

reserved: int

Reserved bits.

rate: int

Rate request.

class pcapkit.protocols.transport.tcp.schema.QuickStartNonce[source]

Bases: TypedDict

TCP quick start nonce.

nonce: int

Nonce.

reserved: int

Reserved bits (R).

class pcapkit.protocols.transport.tcp.schema.TimeoutInfo[source]

Bases: TypedDict

User timeout information.

granularity: int

Granularity.

timeout: int

Timeout value.

class pcapkit.protocols.transport.tcp.schema.MPTCPSubtypeTest[source]

Bases: TypedDict

TCP MPTCP subtype.

length: int

Length.

subtype: int

Subtype.

class pcapkit.protocols.transport.tcp.schema.MPTCPSubtypeUnknown[source]

Bases: TypedDict

TCP unknown MPTCP subtype field.

subtype: int

Subtype.

data: int

Data.

class pcapkit.protocols.transport.tcp.schema.MPTCPSubtypeCapable[source]

Bases: TypedDict

MPTCP Capable subtype field.

subtype: int

Subtype.

version: int

Version.

class pcapkit.protocols.transport.tcp.schema.MPTCPCapableFlags[source]

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.transport.tcp.schema.MPTCPSubtypeJoin[source]

Bases: TypedDict

MPTCP Join subtype field.

subtype: int

Subtype.

reserved: int

Reserved.

backup: int

Backup flag.

class pcapkit.protocols.transport.tcp.schema.MPTCPSubtype[source]

Bases: TypedDict

MPTCP subtype field.

subtype: int

Subtype.

reserved: int

Reserved.

class pcapkit.protocols.transport.tcp.schema.MPTCPDSSFlags[source]

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.transport.tcp.schema.MPTCPSubtypeAddAddress[source]

Bases: TypedDict

MPTCP Add Address subtype field.

subtype: int

Subtype.

reserved: int

Reserved.

echo: int

Echo flag.

class pcapkit.protocols.transport.tcp.schema.MPTCPSubtypePriority[source]

Bases: TypedDict

MPTCP Priority subtype field.

subtype: int

Subtype.

reserved: int

Reserved.

backup: int

Backup flag.

Auxiliary Functions

pcapkit.protocols.transport.tcp.schema.mptcp_data_selector(pkt)[source]

Selector function for _MPTCP.data field.

Parameters:

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

Return type:

FieldBase

Returns:

A SchemaField wrapped MPTCP subclass instance.

Raises:

FieldError – If an MP_JOIN option is carried by a segment with neither SYN nor ACK set.

pcapkit.protocols.transport.tcp.schema.mptcp_add_address_selector(pkt)[source]

Selector function for MPTCPAddAddress.address field.

Parameters:

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

Return type:

FieldBase

Returns:

An IPv4AddressField instance if the option length is one of the IPv4 lengths, or an IPv6AddressField instance if it is one of the IPv6 lengths.

Raises:

FieldError – If the option length is neither.

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.transport.tcp.schema.mptcp_dss_checksum(pkt)[source]

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.transport.tcp.schema.mptcp_dss_ack_selector(pkt)[source]

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:

A NoValueField instance if A is clear, since the field is then absent from the wire; otherwise a UInt64Field instance if a is set, or a UInt32Field instance if it is clear.

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.transport.tcp.schema.mptcp_dss_dsn_selector(pkt)[source]

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:

A NoValueField instance if M is clear, since the field is then absent from the wire; otherwise a UInt64Field instance if m is set, or a UInt32Field instance if it is clear.

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

Removed in version 1.6.0: pcapkit.protocols.data.transport.tcp, with no alias: the module moved here (#2534).

class pcapkit.protocols.transport.tcp.data.TCP(srcport, dstport, seq, ack, hdr_len, flags, window_size, checksum, urgent_pointer)[source]

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.

checksum_status: ChecksumStatus

Outcome of verifying checksum, present only when the enclosing IP layer verified it under CHECKSUM_VERIFY.

class pcapkit.protocols.transport.tcp.data.Flags(ns, cwr, ece, urg, ack, psh, rst, syn, fin, reserved)[source]

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.transport.tcp.data.Option(*args, **kwargs)[source]

Bases: Data

Data model for TCP options.

kind: Option

Option kind.

length: int

Option length.

class pcapkit.protocols.transport.tcp.data.UnassignedOption(kind, length, data)[source]

Bases: Option

Data model for unassigned TCP option.

data: bytes

Option data.

class pcapkit.protocols.transport.tcp.data.EndOfOptionList(kind, length)[source]

Bases: Option

Data model for TCP end of option list option.

class pcapkit.protocols.transport.tcp.data.NoOperation(kind, length)[source]

Bases: Option

Data model for TCP no operation option.

class pcapkit.protocols.transport.tcp.data.MaximumSegmentSize(kind, length, mss)[source]

Bases: Option

Data model for TCP maximum segment size option.

mss: int

Maximum segment size.

class pcapkit.protocols.transport.tcp.data.WindowScale(kind, length, shift)[source]

Bases: Option

Data model for TCP window scale option.

shift: int

Window scale.

class pcapkit.protocols.transport.tcp.data.SACKPermitted(kind, length)[source]

Bases: Option

Data model for TCP SACK permitted option.

class pcapkit.protocols.transport.tcp.data.SACK(kind, length, sack)[source]

Bases: Option

Data model for TCP SACK option.

sack: tuple[SACKBlock, ...]

SACK blocks.

class pcapkit.protocols.transport.tcp.data.SACKBlock(left, right)[source]

Bases: Data

Data model for TCP SACK block.

left: int

Left edge.

right: int

Right edge.

class pcapkit.protocols.transport.tcp.data.Echo(kind, length, data)[source]

Bases: Option

Data model for TCP echo option.

data: bytes

Echo data.

class pcapkit.protocols.transport.tcp.data.EchoReply(kind, length, data)[source]

Bases: Option

Data model for TCP echo reply option.

data: bytes

Echo data.

class pcapkit.protocols.transport.tcp.data.Timestamps(kind, length, timestamp, echo)[source]

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.transport.tcp.data.PartialOrderConnectionPermitted(kind, length)[source]

Bases: Option

Data model for TCP partial order connection permitted option.

class pcapkit.protocols.transport.tcp.data.PartialOrderServiceProfile(kind, length, start, end, reserved)[source]

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.transport.tcp.data.CC(kind, length, cc)[source]

Bases: Option

Data model for TCP CC option.

cc: int

Connection count.

class pcapkit.protocols.transport.tcp.data.CCNew(kind, length, cc)[source]

Bases: Option

Data model for TCP CC.NEW option.

cc: int

Connection count.

class pcapkit.protocols.transport.tcp.data.CCEcho(kind, length, cc)[source]

Bases: Option

Data model for TCP CC.ECHO option.

cc: int

Connection count.

class pcapkit.protocols.transport.tcp.data.AlternateChecksumRequest(kind, length, chksum)[source]

Bases: Option

Data model for TCP alternate checksum request option.

chksum: Checksum

Checksum algorithm.

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

Bases: Option

Data model for TCP alternate checksum data option.

data: bytes

Checksum data.

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

Bases: Option

Data model for TCP MD5 signature option.

digest: bytes

MD5 signature.

class pcapkit.protocols.transport.tcp.data.QuickStartResponse(kind, length, req_rate, ttl_diff, nonce, reserved, nonce_reserved)[source]

Bases: Option

Data model for TCP quick start response option.

Changed in version 1.5.0: req_rate is an int rather than a float (#2167).

req_rate: int

Rate request, in kbps – 40 * 2 ** N for the Rate Request field N, or 0 if N is 0 (RFC 4782 Section 3.1).

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.transport.tcp.data.UserTimeout(kind, length, timeout, granularity)[source]

Bases: Option

Data model for TCP user timeout option.

timeout: timedelta

User timeout.

granularity: bool

Granularity (G). The timeout is in minutes if set, in seconds if not.

class pcapkit.protocols.transport.tcp.data.Authentication(kind, length, key_id, next_key_id, mac)[source]

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.transport.tcp.data.FastOpenCookie(kind, length, cookie)[source]

Bases: Option

Data model for TCP fast open cookie option.

Changed in version 1.5.0: cookie is b'' rather than None for a cookie request (#2167).

cookie: bytes

Cookie, b'' for a cookie request.

class pcapkit.protocols.transport.tcp.data.MPTCP(*args, **kwargs)[source]

Bases: Option

Data model for TCP MPTCP option.

subtype: MPTCPOption

Subtype.

class pcapkit.protocols.transport.tcp.data.MPTCPUnknown(kind, length, subtype, data)[source]

Bases: MPTCP

Data model for TCP unknown MPTCP option.

data: bytes

Data.

class pcapkit.protocols.transport.tcp.data.MPTCPCapable(kind, length, subtype, version, flags, skey, rkey, dl_len, checksum)[source]

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.transport.tcp.data.MPTCPCapableFlag(req, ext, deny_join, reserved, hsa)[source]

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 algorithm flag (H), selecting HMAC-SHA1 under version 0 (RFC 6824) and HMAC-SHA256 under version 1 (RFC 8684).

class pcapkit.protocols.transport.tcp.data.MPTCPJoin(*args, **kwargs)[source]

Bases: MPTCP

Data model for TCP MP_JOIN option.

connection: Flags

Connection type.

class pcapkit.protocols.transport.tcp.data.MPTCPJoinSYN(kind, length, subtype, connection, reserved, backup, addr_id, token, nonce)[source]

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.transport.tcp.data.MPTCPJoinSYNACK(kind, length, subtype, connection, reserved, backup, addr_id, hmac, nonce)[source]

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.transport.tcp.data.MPTCPJoinACK(kind, length, subtype, connection, reserved, hmac)[source]

Bases: MPTCPJoin

Data model for TCP MP_JOIN-ACK option.

reserved: int

Reserved.

hmac: bytes

HMAC value.

class pcapkit.protocols.transport.tcp.data.MPTCPDSS(kind, length, subtype, reserved, data_fin, ack_wide, ack, dsn_wide, dsn, ssn, dl_len, checksum)[source]

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.transport.tcp.data.MPTCPAddAddress(kind, length, subtype, version, reserved, echo, addr_id, addr, port, hmac)[source]

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.transport.tcp.data.MPTCPRemoveAddress(kind, length, subtype, reserved, addr_id)[source]

Bases: MPTCP

Data model for TCP REMOVE_ADDR option.

reserved: int

Reserved.

addr_id: tuple[int, ...]

Address ID.

class pcapkit.protocols.transport.tcp.data.MPTCPPriority(kind, length, subtype, reserved, backup, addr_id)[source]

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.transport.tcp.data.MPTCPFallback(kind, length, subtype, reserved, dsn)[source]

Bases: MPTCP

Data model for TCP MP_FAIL option.

reserved: int

Reserved.

dsn: int

Data sequence number.

class pcapkit.protocols.transport.tcp.data.MPTCPFastclose(kind, length, subtype, reserved, rkey)[source]

Bases: MPTCP

Data model for TCP MP_FASTCLOSE option.

reserved: int

Reserved.

rkey: int

Option receiver’s key.

Footnotes