Skip to the content.

MMT Packet


Definition

A packet in MMT is a structured data element that can be analysed and classified in order to extract attributes of interest. A packet can be any data entry like a log entry, a network packet, a structured data, etc. A packet can belong to a path of protocols identified by the classification process of MMT. A packet is therefore the elementary data unit fed by the user to the MMT core.

Packet Journey in the Core

Please refer to Packet Journey page.

API

Packet Structure

An MMT user needs to feed the core with packets. A packet is identified by a the data place holder and some meta data including the packet real length, the packet snapshot length (what is really available). MMT has only one entry point: packet_process. This is the API to feed MMT with data packets. Internally, MMT will create an internal packet

/**
 * Defines the meta-data of a packet.
 */
typedef struct pkthdr {
    struct timeval ts;                    /**< time stamp that indicates the packet arrival time */
    unsigned int caplen;                  /**< length of portion of the packet that is present */
    unsigned int len;                     /**< length of the packet (off wire) */
    unsigned int original_caplen;         /**< Original capture len */
    unsigned int original_len;            /**< Original capture len */
    unsigned int probe_id;                /**< ID of the probe processing current packet */
    unsigned int source_id;               /**< ID of the interface/source */
    void * user_args;                     /**< Pointer to a user defined argument. Can be NULL. */
} pkthdr_t;
/**
 * Defines a packet structure.
 */
struct ipacket_struct {
    uint64_t packet_id;                       /**< identifier of the packet. */
    uint64_t total_caplen;                    /**< Total captured length of all assembled packets */
    uint8_t is_completed[PROTO_PATH_SIZE];    /**< 1 - yes, 0 - no */
    uint8_t is_fragment[PROTO_PATH_SIZE];     /**< 1 - yes, 0 - no */
    uint16_t ipv6_ext_headers_path[PROTO_PATH_SIZE];
    uint32_t ipv6_ext_headers_offset[PROTO_PATH_SIZE];
    uint16_t ipv6_ext_headers_len;
    uint16_t ipv6_overlapping[PROTO_PATH_SIZE];
    uint16_t ipv6_outoforder[PROTO_PATH_SIZE];
    int last_callback_fct_id;
    unsigned nb_reassembled_packets[PROTO_PATH_SIZE];
    proto_hierarchy_t * proto_hierarchy;      /**< the protocol layers corresponding to this packet */
    proto_hierarchy_t * proto_headers_offset; /**< the offsets corresponding to the protocol layers of this packet */
    proto_hierarchy_t * proto_classif_status; /**< the classification status of the protocols in the path */
    mmt_session_t * session;                  /**< pointer to the session structure to which the packet belongs */
    mmt_tcpip_internal_packet_t * internal_packet;  /**< pointer to opaque packet structure. for internal use only. */
    mmt_handler_t * mmt_handler;              /**< pointer to the MMT handler that processed this packet */
    pkthdr_t * p_hdr;                         /**< the meta-data of the packet */
    const u_char * data;                      /**< pointer to the packet data */
};

Structures from src/mmt_core/public_include/data_defs.h:141-194 (installed as sdk/include/data_defs.h). The structure holds the public fields only (issue #535): the engine’s per-packet state — embedded storage for the path arrays and the meta-data, the original data pointer, the offset cache and the classifier-walk bookkeeping — lives in a private extension that embeds it (src/mmt_core/private_include/ipacket_internal.h). The library always owns the packet: a consumer receives an ipacket_t * and must never allocate, copy or embed an ipacket_t. The offsets of the public fields are pinned by _Static_asserts on the shipped LP64 targets (src/mmt_core/public_include/data_defs.h:197-224); after an in-place write to proto_headers_offset->proto_path[], call the exported invalidate_packet_offset_cache().

User API

   bool packet_process(
      mmt_handler_t *mmt_handler,
      struct pkthdr *header,
      const u_char *packet);

This is the entry point for MMT. It feeds packets to the Core for processing by the given MMT handler.

   bool register_packet_handler(
      mmt_handler_t *mmt_handler,
      int packet_handler_id,
      generic_packet_handler_callback function,
      mmt_opaque_t user);

   bool is_registered_packet_handler(
      mmt_handler_t *mmt_handler,
      int packet_handler_id);

   bool unregister_packet_handler(
      mmt_handler_t *mmt_handler,
      int packet_handler_id);

In addition to attributes handlers, the user can register packet handlers. It consists of user defined functions that will be called for every processed packet. These functions provide the API for registering packet handlers, checking the existing of a particular packet handler, and, unregistering a packet handler.

Getters and Setters API

MMTAPI int MMTCALL get_packet_offset_at_index(
    const ipacket_t *ipacket,
    unsigned index
);

This function returns the offset in number of bytes from the beginning of the packet for the protocol at the given index.

MMTAPI uint32_t MMTCALL get_protocol_id_at_index(
    const ipacket_t *ipacket,
    unsigned index
);

This function returns the identifier of the protocol at the given index if such index exists, MMT_NO_PROTO_ID otherwise (src/mmt_core/public_include/data_defs.h:373).

MMTAPI unsigned MMTCALL get_protocol_index_by_id(
    const ipacket_t *ipacket,
    mmt_proto_id_t proto_id
);

This function returns the index of the protocol given by its id. If the protocol id is not valid or the protocol does not appear in the protocol hierarchy, MMT_NO_PROTO_INDEX is returned (src/mmt_core/public_include/data_defs.h:374).

MMTAPI unsigned MMTCALL get_protocol_index_by_name(
    const ipacket_t *ipacket,
    const char *proto_name
);

This function returns the index of the protocol given by its name. If the protocol name is not valid or the protocol does not appear in the protocol hierarchy, MMT_NO_PROTO_INDEX is returned (src/mmt_core/public_include/data_defs.h:374).

MMTAPI uint64_t MMTCALL get_session_id_from_packet(
    const ipacket_t *ipacket
);

This function returns the session ID associated to ipacket

MMTAPI void* MMTCALL get_user_session_context_from_packet(
    const ipacket_t *ipacket
);

This function returns the user session context

MMTAPI void MMTCALL set_user_session_context_for_packet(
    const ipacket_t *ipacket,
    mmt_opaque_t user_data
);

This function sets the user session context for a given packet

MMTAPI void* MMTCALL get_proto_session_data_from_packet(
    const ipacket_t *ipacket,
    unsigned index
);

This function returns pointer to initialized the session data of the protocol at the given index. NULL if the protocol has no registered session data.

MMTAPI mmt_session_t* MMTCALL get_session_from_packet(
    const ipacket_t *ipacket
);

This function returns pointer to the associated session if it exists, NULL otherise.

Open Issues