PcapPlusPlus  Next
Classes | Public Types | Public Member Functions | List of all members
pcpp::IPReassembly Class Reference

#include <IPReassembly.h>

Classes

class  IPv4PacketKey
 
class  IPv6PacketKey
 
class  PacketKey
 

Public Types

enum  ReassemblyStatus {
  NON_IP_PACKET = 0x00 , NON_FRAGMENT = 0x01 , FIRST_FRAGMENT = 0x02 , FRAGMENT = 0x04 ,
  OUT_OF_ORDER_FRAGMENT = 0x08 , MALFORMED_FRAGMENT = 0x10 , REASSEMBLED = 0x20
}
 
typedef void(* OnFragmentsClean) (const PacketKey *key, void *userCookie)
 

Public Member Functions

 IPReassembly (OnFragmentsClean onFragmentsCleanCallback=nullptr, void *callbackUserCookie=nullptr, size_t maxPacketsToStore=500000)
 
 ~IPReassembly ()
 
Packet * processPacket (Packet *fragment, ReassemblyStatus &status, ProtocolType parseUntil=UnknownProtocol, OsiModelLayer parseUntilLayer=OsiModelLayerUnknown)
 
Packet * processPacket (RawPacket *fragment, ReassemblyStatus &status, ProtocolType parseUntil=UnknownProtocol, OsiModelLayer parseUntilLayer=OsiModelLayerUnknown)
 
Packet * getCurrentPacket (const PacketKey &key)
 
void removePacket (const PacketKey &key)
 
size_t getMaxCapacity () const
 
size_t getCurrentCapacity () const
 

Detailed Description

Contains the IP reassembly (a.k.a IP de-fragmentation) mechanism. Encapsulates both IPv4 and IPv6 reassembly. Please refer to the documentation at the top of IPReassembly.h to understand how this mechanism works. The main APIs are:

  • IPReassembly::processPacket() - process a fragment. This is the main method which should be called whenever a new fragment arrives. This method processes the fragment, runs the reassembly logic and returns the result packet when it's fully reassembled
  • IPReassembly::getCurrentPacket() - get the reassembled data that is currently available, even if reassembly process is not yet completed
  • IPReassembly::removePacket() - remove all data that is currently stored for a packet, including the reassembled data that was gathered so far

Member Typedef Documentation

◆ OnFragmentsClean

pcpp::IPReassembly::OnFragmentsClean

The IP reassembly mechanism has a certain capacity of concurrent packets it can handle. This capacity is determined in its c'tor (default value is PCPP_IP_REASSEMBLY_DEFAULT_MAX_PACKETS_TO_STORE). When traffic volume exceeds this capacity the mechanism starts dropping packets in a LRU manner (least recently used are dropped first). Whenever a packet is dropped this callback is fired

Parameters
[in]keyA pointer to the identifier of the packet that is being dropped
[in]userCookieA pointer to the cookie provided by the user in IPReassemby c'tor (or nullptr if no cookie provided)

Member Enumeration Documentation

◆ ReassemblyStatus

enum pcpp::IPReassembly::ReassemblyStatus

An enum representing the status returned from processing a fragment

Enumerator
NON_IP_PACKET 

The processed packet isn't of type IPv4 or IPv6

NON_FRAGMENT 

The processed packet isn't a fragment

FIRST_FRAGMENT 

The processed fragment is the first fragment

FRAGMENT 

The processed fragment is a fragment (but not the first one)

OUT_OF_ORDER_FRAGMENT 

The processed fragment is not the fragment that was expected at this time

MALFORMED_FRAGMENT 

The processed fragment is malformed, meaning a fragment which has offset of zero but isn't the first fragment

REASSEMBLED 

Packet is now fully reassembled

Constructor & Destructor Documentation

◆ IPReassembly()

pcpp::IPReassembly::IPReassembly ( OnFragmentsClean  onFragmentsCleanCallback = nullptr,
void *  callbackUserCookie = nullptr,
size_t  maxPacketsToStore = 500000 
)
inlineexplicit

A c'tor for this class.

Parameters
[in]onFragmentsCleanCallbackThe callback to be called when packets are dropped due to capacity limit. Please read more about capacity limit in IPReassembly.h file description. This parameter is optional, default value is nullptr (no callback)
[in]callbackUserCookieA pointer to an object provided by the user. This pointer will be returned when invoking the onFragmentsCleanCallback. This parameter is optional, default cookie is nullptr
[in]maxPacketsToStoreSet the capacity limit of the IP reassembly mechanism. Default capacity is PCPP_IP_REASSEMBLY_DEFAULT_MAX_PACKETS_TO_STORE

◆ ~IPReassembly()

pcpp::IPReassembly::~IPReassembly ( )

A d'tor for this class

Member Function Documentation

◆ getCurrentCapacity()

size_t pcpp::IPReassembly::getCurrentCapacity ( ) const
inline

Get the current number of packets being processed

◆ getCurrentPacket()

Packet* pcpp::IPReassembly::getCurrentPacket ( const PacketKey &  key)

Get a partially reassembled packet. This method returns all the reassembled data that was gathered so far which is obviously not a fully reassembled packet (otherwise it would have returned by processPacket()). Notice all data is being copied so the user is responsible to free the returned Packet object when done using it. Notice#2 - calling this method doesn't interfere with the reassembly of this packet - all internal structures and data remain

Parameters
[in]keyThe identifiers of the packet to return
Returns
A pointer to a Packet object containing the partially reassembled packet. Notice the user is responsible to free this object when done using it

◆ getMaxCapacity()

size_t pcpp::IPReassembly::getMaxCapacity ( ) const
inline

Get the maximum capacity as determined in the c'tor

◆ processPacket() [1/2]

Packet* pcpp::IPReassembly::processPacket ( Packet *  fragment,
ReassemblyStatus &  status,
ProtocolType  parseUntil = UnknownProtocol,
OsiModelLayer  parseUntilLayer = OsiModelLayerUnknown 
)

The main API that drives IPReassembly. This method should be called whenever a fragment arrives. This method finds the relevant packet this fragment belongs to and runs the IP reassembly logic that is described in IPReassembly.h.

Parameters
[in]fragmentThe fragment to process (IPv4 or IPv6). Please notice that the reassembly logic doesn't change or manipulate this object in any way. All of its data is copied to internal structures and manipulated there
[out]statusAn indication of the packet reassembly status following the processing of this fragment. Possible values are:
  • The input fragment is not a IPv4 or IPv6 packet
  • The input fragment is not a IPv4 or IPv6 fragment packet
  • The input fragment is the first fragment of the packet
  • The input fragment is not the first or last fragment
  • The input fragment came out-of-order, meaning that wasn't the fragment that was currently expected (it's data is copied to the out-of-order fragment list)
  • The input fragment is malformed and will be ignored
  • The input fragment is the last one and the packet is now fully reassembled. In this case the return value will contain a pointer to the reassembled packet
[in]parseUntilOptional parameter. Parse the reassembled packet until you reach a certain protocol (inclusive). Can be useful for cases when you need to parse only up to a certain layer and want to avoid the performance impact and memory consumption of parsing the whole packet. Note that setting this to a protocol which doesn't include the IP-Layer will result in IPReassembly not finding the IP-Layer and thus failing to work properly. Default value is UnknownProtocol which means don't take this parameter into account
[in]parseUntilLayerOptional parameter. Parse the reassembled packet until you reach a certain layer in the OSI model (inclusive). Can be useful for cases when you need to parse only up to a certain OSI layer (for example transport layer) and want to avoid the performance impact and memory consumption of parsing the whole packet. Note that setting this value to OsiModelPhysicalLayer will result in IPReassembly not finding the IP-layer and thus failing to work properly. Default value is OsiModelLayerUnknown which means don't take this parameter into account
Returns
  • If the input fragment isn't an IPv4/IPv6 packet or if it isn't an IPv4/IPv6 fragment, the return value is a pointer to the input fragment
  • If the input fragment is the last one and the reassembled packet is ready - a pointer to the reassembled packet is returned. Notice it's the user's responsibility to free this pointer when done using it
  • If the reassembled packet isn't ready then nullptr is returned

◆ processPacket() [2/2]

Packet* pcpp::IPReassembly::processPacket ( RawPacket *  fragment,
ReassemblyStatus &  status,
ProtocolType  parseUntil = UnknownProtocol,
OsiModelLayer  parseUntilLayer = OsiModelLayerUnknown 
)

The main API that drives IPReassembly. This method should be called whenever a fragment arrives. This method finds the relevant packet this fragment belongs to and runs the IPv4 reassembly logic that is described in IPReassembly.h.

Parameters
[in]fragmentThe fragment to process (IPv4 or IPv6). Please notice that the reassembly logic doesn't change or manipulate this object in any way. All of its data is copied to internal structures and manipulated there
[out]statusAn indication of the packet reassembly status following the processing of this fragment. Possible values are:
  • The input fragment is not a IPv4 or IPv6 packet
  • The input fragment is not a IPv4 or IPv6 fragment packet
  • The input fragment is the first fragment of the packet
  • The input fragment is not the first or last fragment
  • The input fragment came out-of-order, meaning that wasn't the fragment that was currently expected (it's data is copied to the out-of-order fragment list)
  • The input fragment is malformed and will be ignored
  • The input fragment is the last one and the packet is now fully reassembled. In this case the return value will contain a pointer to the reassembled packet
[in]parseUntilOptional parameter. Parse the raw and reassembled packets until you reach a certain protocol (inclusive). Can be useful for cases when you need to parse only up to a certain layer and want to avoid the performance impact and memory consumption of parsing the whole packet. Note that setting this to a protocol which doesn't include the IP-Layer will result in IPReassembly not finding the IP-Layer and thus failing to work properly. Default value is UnknownProtocol which means don't take this parameter into account
[in]parseUntilLayerOptional parameter. Parse the raw and reassembled packets until you reach a certain layer in the OSI model (inclusive). Can be useful for cases when you need to parse only up to a certain OSI layer (for example transport layer) and want to avoid the performance impact and memory consumption of parsing the whole packet. Note that setting this value to OsiModelPhysicalLayer will result in IPReassembly not finding the IP-layer and thus failing to work properly. Default value is UnknownProtocol which means don't take this parameter into account Default value is OsiModelLayerUnknown which means don't take this parameter into account
Returns
  • If the input fragment isn't an IPv4/IPv6 packet or if it isn't an IPv4/IPv6 fragment, the return value is a pointer to a Packet object wrapping the input fragment RawPacket object. It's the user responsibility to free this instance
  • If the input fragment is the last one and the reassembled packet is ready - a pointer to the reassembled packet is returned. Notice it's the user's responsibility to free this pointer when done using it
  • If the reassembled packet isn't ready then nullptr is returned

◆ removePacket()

void pcpp::IPReassembly::removePacket ( const PacketKey &  key)

Remove a partially reassembled packet from all internal structures. That means that if another fragment of this packet appears it will be treated as a new packet

Parameters
[in]keyThe identifiers of the packet to remove