PcapPlusPlus  20.08
Classes | Public Types | Public Member Functions | List of all members
pcpp::TcpReassembly Class Reference

#include <TcpReassembly.h>

Public Types

enum  ConnectionEndReason { TcpReassemblyConnectionClosedByFIN_RST, TcpReassemblyConnectionClosedManually }
 
enum  ReassemblyStatus {
  TcpMessageHandled, OutOfOrderTcpMessageBuffered, FIN_RSTWithNoData, Ignore_PacketWithNoData,
  Ignore_PacketOfClosedFlow, Ignore_Retransimission, NonIpPacket, NonTcpPacket,
  Error_PacketDoesNotMatchFlow
}
 
typedef std::map< uint32_t, ConnectionData > ConnectionInfoList
 
typedef void(* OnTcpMessageReady) (int8_t side, const TcpStreamData &tcpData, void *userCookie)
 
typedef void(* OnTcpConnectionStart) (const ConnectionData &connectionData, void *userCookie)
 
typedef void(* OnTcpConnectionEnd) (const ConnectionData &connectionData, ConnectionEndReason reason, void *userCookie)
 

Public Member Functions

 TcpReassembly (OnTcpMessageReady onMessageReadyCallback, void *userCookie=NULL, OnTcpConnectionStart onConnectionStartCallback=NULL, OnTcpConnectionEnd onConnectionEndCallback=NULL, const TcpReassemblyConfiguration &config=TcpReassemblyConfiguration())
 
ReassemblyStatus reassemblePacket (Packet &tcpData)
 
ReassemblyStatus reassemblePacket (RawPacket *tcpRawData)
 
void closeConnection (uint32_t flowKey)
 
void closeAllConnections ()
 
const ConnectionInfoList & getConnectionInformation () const
 
int isConnectionOpen (const ConnectionData &connection) const
 
uint32_t purgeClosedConnections (uint32_t maxNumToClean=0)
 

Detailed Description

A class containing the TCP reassembly logic. Please refer to the documentation at the top of TcpReassembly.h for understanding how to use this class

Member Typedef Documentation

◆ ConnectionInfoList

typedef std::map<uint32_t, ConnectionData> pcpp::TcpReassembly::ConnectionInfoList

The type for storing the connection information

◆ OnTcpConnectionEnd

pcpp::TcpReassembly::OnTcpConnectionEnd

A callback invoked when a TCP connection is terminated, either by a FIN or RST packet or manually by the user

Parameters
[in]connectionDataConnection information
[in]reasonThe reason for connection termination: FIN/RST packet or manually by the user
[in]userCookieA pointer to the cookie provided by the user in TcpReassembly c'tor (or NULL if no cookie provided)

◆ OnTcpConnectionStart

pcpp::TcpReassembly::OnTcpConnectionStart

A callback invoked when a new TCP connection is identified (whether it begins with a SYN packet or not)

Parameters
[in]connectionDataConnection information
[in]userCookieA pointer to the cookie provided by the user in TcpReassembly c'tor (or NULL if no cookie provided)

◆ OnTcpMessageReady

pcpp::TcpReassembly::OnTcpMessageReady

A callback invoked when new data arrives on a connection

Parameters
[in]sideThe side this data belongs to (MachineA->MachineB or vice versa). The value is 0 or 1 where 0 is the first side seen in the connection and 1 is the second side seen
[in]tcpDataThe TCP data itself + connection information
[in]userCookieA pointer to the cookie provided by the user in TcpReassembly c'tor (or NULL if no cookie provided)

Member Enumeration Documentation

◆ ConnectionEndReason

enum pcpp::TcpReassembly::ConnectionEndReason

An enum for connection end reasons

Enumerator
TcpReassemblyConnectionClosedByFIN_RST 

Connection ended because of FIN or RST packet

TcpReassemblyConnectionClosedManually 

Connection ended manually by the user

◆ ReassemblyStatus

enum pcpp::TcpReassembly::ReassemblyStatus

An enum for providing reassembly status for each processed packet

Enumerator
TcpMessageHandled 

The processed packet contains valid TCP payload, and its payload is processed by OnMessageReadyCallback callback function. The packet may be:

  1. An in-order TCP packet, meaning packet_sequence == sequence_expected. Note if there's any buffered out-of-order packet waiting for this packet, their associated callbacks are called in this reassemblePacket call.
  2. An out-of-order TCP packet which satisfy packet_sequence < sequence_expected && packet_sequence + packet_payload_length > sequence_expected. Note only the new data (the [sequence_expected, packet_sequence + packet_payload_length] part ) is processed by OnMessageReadyCallback callback funtion.
OutOfOrderTcpMessageBuffered 

The processed packet is an out-of-order TCP packet, meaning packet_sequence > sequence_expected. It's buffered so no OnMessageReadyCallback callback function is called. The callback function for this packet maybe called LATER, under different circumstances:

  1. When an in-order packet which is right before this packet arrives(case 1 and case 2 described in TcpMessageHandled section above).
  2. When a FIN or RST packet arrives, which will clear the buffered out-of-order packets of this side. If this packet contains "new data", meaning (packet_sequence <= sequence_expected) && (packet_sequence + packet_payload_length > sequence_expected), the new data is processed by OnMessageReadyCallback callback.
FIN_RSTWithNoData 

The processed packet is a FIN or RST packet with no payload. Buffered out-of-order packets will be cleared. If they contain "new data", the new data is processed by OnMessageReadyCallback callback.

Ignore_PacketWithNoData 

The processed packet is not a SYN/SYNACK/FIN/RST packet and has no payload. Normally it's just a bare ACK packet. It's ignored and no callback function is called.

Ignore_PacketOfClosedFlow 

The processed packet comes from a closed flow(an in-order FIN or RST is seen). It's ignored and no callback function is called.

Ignore_Retransimission 

The processed packet is a restransmission packet with no new data, meaning the packet_sequence + packet_payload_length < sequence_expected. It's ignored and no callback function is called.

NonIpPacket 

The processed packet is not an IP packet. It's ignored and no callback function is called.

NonTcpPacket 

The processed packet is not a TCP packet. It's ignored and no callback function is called.

Error_PacketDoesNotMatchFlow 

The processed packet does not belong to any known TCP connection. It's ignored and no callback function is called. Normally this will be happen.

Constructor & Destructor Documentation

◆ TcpReassembly()

pcpp::TcpReassembly::TcpReassembly ( OnTcpMessageReady  onMessageReadyCallback,
void *  userCookie = NULL,
OnTcpConnectionStart  onConnectionStartCallback = NULL,
OnTcpConnectionEnd  onConnectionEndCallback = NULL,
const TcpReassemblyConfiguration &  config = TcpReassemblyConfiguration() 
)

A c'tor for this class

Parameters
[in]onMessageReadyCallbackThe callback to be invoked when new data arrives
[in]userCookieA pointer to an object provided by the user. This pointer will be returned when invoking the various callbacks. This parameter is optional, default cookie is NULL
[in]onConnectionStartCallbackThe callback to be invoked when a new connection is identified. This parameter is optional
[in]onConnectionEndCallbackThe callback to be invoked when a new connection is terminated (either by a FIN/RST packet or manually by the user). This parameter is optional
[in]configOptional parameter for defining special configuration parameters. If not set the default parameters will be set

Member Function Documentation

◆ closeAllConnections()

void pcpp::TcpReassembly::closeAllConnections ( )

Close all open connections manually. This method will cause the TcpReassembly::OnTcpConnectionEnd to be invoked for each connection with a reason of TcpReassembly::TcpReassemblyConnectionClosedManually

◆ closeConnection()

void pcpp::TcpReassembly::closeConnection ( uint32_t  flowKey)

Close a connection manually. If the connection doesn't exist or already closed an error log is printed. This method will cause the TcpReassembly::OnTcpConnectionEnd to be invoked with a reason of TcpReassembly::TcpReassemblyConnectionClosedManually

Parameters
[in]flowKeyA 4-byte hash key representing the connection. Can be taken from a ConnectionData instance

◆ getConnectionInformation()

const ConnectionInfoList& pcpp::TcpReassembly::getConnectionInformation ( ) const
inline

Get a map of all connections managed by this TcpReassembly instance (both connections that are open and those that are already closed)

Returns
A map of all connections managed. Notice this map is constant and cannot be changed by the user

◆ isConnectionOpen()

int pcpp::TcpReassembly::isConnectionOpen ( const ConnectionData &  connection) const

Check if a certain connection managed by this TcpReassembly instance is currently opened or closed

Parameters
[in]connectionThe connection to check
Returns
A positive number (> 0) if connection is opened, zero (0) if connection is closed, and a negative number (< 0) if this connection isn't managed by this TcpReassembly instance

◆ purgeClosedConnections()

uint32_t pcpp::TcpReassembly::purgeClosedConnections ( uint32_t  maxNumToClean = 0)

Clean up the closed connections from the memory

Parameters
[in]maxNumToCleanThe maximum number of items to be cleaned up per one call. This parameter, when its value is not zero, overrides the value that was set by the constructor.
Returns
The number of cleared items

◆ reassemblePacket() [1/2]

ReassemblyStatus pcpp::TcpReassembly::reassemblePacket ( Packet &  tcpData)

The most important method of this class which gets a packet from the user and processes it. If this packet opens a new connection, ends a connection or contains new data on an existing connection, the relevant callback will be called (TcpReassembly::OnTcpMessageReady, TcpReassembly::OnTcpConnectionStart, TcpReassembly::OnTcpConnectionEnd)

Parameters
[in]tcpDataA reference to the packet to process
Returns
A enum of TcpReassembly::ReassemblyStatus, indicating status of TCP reassembly

◆ reassemblePacket() [2/2]

ReassemblyStatus pcpp::TcpReassembly::reassemblePacket ( RawPacket *  tcpRawData)

The most important method of this class which gets a raw packet from the user and processes it. If this packet opens a new connection, ends a connection or contains new data on an existing connection, the relevant callback will be invoked (TcpReassembly::OnTcpMessageReady, TcpReassembly::OnTcpConnectionStart, TcpReassembly::OnTcpConnectionEnd)

Parameters
[in]tcpRawDataA reference to the raw packet to process
Returns
A enum of TcpReassembly::ReassemblyStatus, indicating status of TCP reassembly