#include <yaf/autoinc.h>
#include <yaf/decode.h>
#include <yaf/yafcore.h>
#include <yaf/yaftab.h>

Data Structures
struct	yfHookMetaData
	Exported from the plugin to tell YAF about its export data & interface version. More...

Macros
#define	YAF_HOOK_INTERFACE_VERSION 7
	HOOKS Plugin Version.

Functions
gboolean	yfHookPacket (yfFlowKey_t key, const uint8_t pkt, size_t caplen, uint32_t iplen, yfTCPInfo_t tcpinfo, yfL2Info_t l2info)
	Function called to do processing on each packet as it comes in.
void	yfHookFlowPacket (yfFlow_t flow, yfFlowVal_t val, const uint8_t pkt, size_t caplen, uint32_t iplen, yfTCPInfo_t tcpinfo, yfL2Info_t *l2info)
	Similar to yfHookPacket but also given yfFlowVal_t struct for processing per flow direction.
void	yfHookValidateFlowTab (void **yfHookCtxArray, uint32_t max_payload, gboolean uniflow, gboolean silkmode, gboolean applabelmode, gboolean entropymode, gboolean fingerprintmode, gboolean fpExportMode, gboolean udp_multipkt_payload, uint16_t udp_uniflow_port)
	Validation function to make sure the plugin can and should operate based on the flowtable options.
gboolean	yfHookFlowClose (yfFlow_t *flow)
	Called upon flow close to do any necessary plugin processing upon flow close.
void	yfHookFlowAlloc (yfFlow_t flow, void *yfHookCtxArray)
	Allow plugins to allocate flow state information for each flow captured by yaf at the time of flow creation.
void	yfHookFlowFree (yfFlow_t *flow)
	Frees all memory associated with the flow state in all of the attached plugins.
fbInfoElement_t *	yfHookGetInfoModel (void)
	Returns the IPFIX info model aggregated for all plugins.
gboolean	yfHookGetTemplate (fbSession_t session, void *yfHookCtxArray)
	Gets the IPFIX info model template for the export data from all the plugins and turns it into a single template to return.
gboolean	yfHookFlowWrite (fbSubTemplateMultiList_t rec, fbSubTemplateMultiListEntry_t stml, yfFlow_t flow, GError *err)
	called by yfWriteFlow to add the data from all registered plugins to the outgoing IPFIX record
gboolean	yfHookAddNewHook (const char hookName, const char hookOpts, const char hookConf, void yfHookCtxArray, GError *err)
	Adds another hook (plugin) into yaf.
uint8_t	yfHookGetTemplateCount (yfFlow_t *flow)
	Returns the amount of templates to add to the SubtemplateMultiList from all plugins hooked.
void	yfHookFreeLists (yfFlow_t *flow)
	Sends control back to the plugin to free any BasicLists, SubTemplateLists, or SubTemplateMultiLists that may have been used in it's added templates.
const struct yfHookMetaData *	ypGetMetaData (void)
	Callback invoked by yfHookAddNewHook() to get the version, max export bytes, and whether the plugin requires applabel to be enabled.
gboolean	ypHookPacket (yfFlowKey_t key, const uint8_t pkt, size_t caplen, uint32_t iplen, yfTCPInfo_t tcpinfo, yfL2Info_t l2info)
	Callback invoked by yfHookPacket() to allow the plugin to prevent the packet from becoming a part of a flow by returning FALSE.
void	ypFlowPacket (void yfHookFlowContext, yfFlow_t flow, yfFlowVal_t val, const uint8_t pkt, size_t caplen, uint32_t iplen, yfTCPInfo_t tcpinfo, yfL2Info_t l2info)
	Callback invoked by yfHookFlowPacket() to allow the plugin to process each packet as it is read.
gboolean	ypFlowClose (void yfHookFlowContext, yfFlow_t flow)
	Callback invoked by yfHookFlowClose() when a flow is closed to allow the plugin to examine the complete flow record prior to export.
void	ypFlowAlloc (void *yfHookFlowContext, yfFlow_t flow, void *yfHookCtx)
	Callback invoked by yfHookFlowAlloc() when a new flow is opened to allow the plugin to create a per-flow context.
void	ypFlowFree (void yfHookFlowContext, yfFlow_t flow)
	Callback invoked by yfHookFlowFree() when a flow is destroyed to allow the plugin to free the flow-specific context set by ypFlowAlloc().
gboolean	ypFlowWrite (void yfHookFlowContext, fbSubTemplateMultiList_t rec, fbSubTemplateMultiListEntry_t stml, yfFlow_t flow, GError **err)
	Callback invoked by yfHookFlowWrite() when the data is copied into an IPFIX record immediately prior to export to allow the plugin to fill its portions of the IPFIX record.
fbInfoElement_t *	ypGetInfoModel (void)
	Callback invoked by yfHookGetInfoModel() to allow the plugin to add elements to the InfoModel.
gboolean	ypGetTemplate (fbSession_t session, void yfHookCtx)
	Callback invoked by yfHookGetTemplate() to allow the plugin to add its templates to the export session.
void	ypSetPluginOpt (const char pluginOpt, void yfHookCtx)
	Callback invoked by yfHookAddNewHook() to provide the plugin with command line options other than the configuration file name.
void	ypSetPluginConf (const char pluginConf, void *yfHookCtx)
	Callback invoked by yfHookAddNewHook() to provide the plugin with the name of the configuration file and to allow the callback to create a plugin specific context.
gboolean	ypValidateFlowTab (void yfHookCtx, uint32_t max_payload, gboolean uniflow, gboolean silkmode, gboolean applabelmode, gboolean entropymode, gboolean fingerprintmode, gboolean fpExportMode, gboolean udp_multipkt_payload, uint16_t udp_uniflow_port, GError *err)
	Callback invoked by yfFlowTabAlloc() to allow the plugin to confirm it can be used given the flow-table settings.
uint8_t	ypGetTemplateCount (void yfHookFlowContext, yfFlow_t flow)
	Callback invoked by yfHookGetTemplateCount() when sizing the STML to allow the plugin to reserve space in the STML.
void	ypFreeLists (void yfHookFlowContext, yfFlow_t flow)
	Callback invoked by yfHookFreeLists() after the IPFIX record has been written to allow the plugin to clear its structured data.

Detailed Description

Processing hook interface for YAF.

VERSION 3 - REQUIRES FIXBUF 1.0

The plugin must implement all of the following functions:

ypGetMetaData() - called by yfHookAddNewHook(), returns the version, max export bytes, and whether the plugin requires applabel to be enabled

ypSetPluginConf() - called by yfHookAddNewHook() to provide the plugin with the name of the configuration file and to allow the callback to create a plugin specific context

ypSetPluginOpt() - called by yfHookAddNewHook() to provide the plugin with command line options other than the configuration file name

ypValidateFlowTab() - called by yfFlowTabAlloc() (via yfHookValidateFlowTab()), the callback allows the plugin to confirm it can be used given the flow-table settings

ypGetInfoModel() - called by yfInitExporterSession() (via yfInfoModel() via yfHookGetInfoModel()), the callback allows the plugin to add elements to the InfoModel. Old (outdated?) comment: This should not be used for v.3

ypGetTemplate() - called by yfInitExporterSession(), (via yfHookGetTemplate()) the callback allows the plugin to add its templates to the export session

ypHookPacket() - called early in yfFlowPBuf() per packet (via a call to yfHookPacket()), the callback allows the plugin to prevent the packet from becoming a part of a flow by returning FALSE.

ypFlowAlloc() - called by yfFlowGetNode() (via yfHookFlowAlloc()) when a new flow is opened, the callback allows the plugin to create a per-flow context

ypFlowPacket() - called by yfHookFlowPacket() which is called in two places: (1)late in yfFlowPBuf() per packet after creating/adding the packet to a flow, and (2)by yfFlowLabelApp() (via yfAppLabelFlow()) that is called when the flow is closed. When called by yfAppLabelFlow() - the last 3 parameters are 0. The callback allows the plugin to process each packet of a flow as it is read.

ypScanPayload() - if Application labeling is enabled, yfAppLabelFlow() calls ycScanPayload() calls the application-specific code (e.g. in tlsplugin.c) calls yfHookScanPayload() in yafhooks.c which in turn invokes this callback to scan the data.

ypFlowClose() - called by yfFlowClose() (via yfHookFlowClose()) when a flow is closed, the callback allows the plugin to examine the complete flow record prior to export

ypGetTemplateCount() - called by yfWriteFlow() (via yfHookGetTemplateCount()) when sizing the STML, the callback allows the plugin to reserve space in the STML

ypFlowWrite() - called by yfWriteFlow() (via yfHookFlowWrite()) when the data is copied into an IPFIX record immediately prior to export, the callback allows the plugin to fill its portions of the IPFIX record

ypFreeLists() - called by yfWriteFlow() (via yfHookFreeLists()) after the IPFIX record has been written, the callback allows the plugin to clear its structured data

ypFlowFree() - called by yfFlowFree() (via yfHookFlowFree()) when a flow is destroyed, the callback allows the plugin to free context set by ypFlowAlloc()

Function Documentation

◆ yfHookAddNewHook()

gboolean yfHookAddNewHook	(	const char *	hookName,
		const char *	hookOpts,
		const char *	hookConf,
		void **	yfHookCtxArray,
		GError **	err )

Adds another hook (plugin) into yaf.

Parameters

hookName	the file name of the plugin to load
hookOpts	a string of command line options for the plugin to process
hookConf	the config file for the plugin
yfHookCtxArray	array holding each hook's hook-specific context
err	the error value that gets set if this call didn't work

Returns: TRUE if plugin loaded fine, other FALSE

◆ yfHookFlowAlloc()

void yfHookFlowAlloc	(	yfFlow_t *	flow,
		void **	yfHookCtxArray )

Allow plugins to allocate flow state information for each flow captured by yaf at the time of flow creation.

Parameters

flow	the pointer to the flow context state structure, but more importantly contains the array of pointers (hfctx) which hold the plugin context state
yfHookCtxArray	array holding each hook's hook context

◆ yfHookFlowClose()

gboolean yfHookFlowClose ( yfFlow_t * flow )

Called upon flow close to do any necessary plugin processing upon flow close.

Parameters

flow

Returns: TRUE or FALSE upon error

◆ yfHookFlowFree()

void yfHookFlowFree ( yfFlow_t * flow )

Frees all memory associated with the flow state in all of the attached plugins.

Parameters

flow	- a pointer to the flow context structure

◆ yfHookFlowPacket()

void yfHookFlowPacket	(	yfFlow_t *	flow,
		yfFlowVal_t *	val,
		const uint8_t *	pkt,
		size_t	caplen,
		uint32_t	iplen,
		yfTCPInfo_t *	tcpinfo,
		yfL2Info_t *	l2info )

Similar to yfHookPacket but also given yfFlowVal_t struct for processing per flow direction.

Parameters

flow	pointer to yfFlow_t
val	pointer to yfFlowVal_t struct
pkt	pointer to pkt data
caplen	size of pkt data
iplen
tcpinfo
l2info

◆ yfHookFlowWrite()

gboolean yfHookFlowWrite	(	fbSubTemplateMultiList_t *	rec,
		fbSubTemplateMultiListEntry_t *	stml,
		yfFlow_t *	flow,
		GError **	err )

called by yfWriteFlow to add the data from all registered plugins to the outgoing IPFIX record

Parameters

rec	outgoing subTemplateMultiList
stml	Current entry of subTemplateMultiList
flow	pointer to the flow context structure
err	Error

◆ yfHookFreeLists()

void yfHookFreeLists ( yfFlow_t * flow )

Sends control back to the plugin to free any BasicLists, SubTemplateLists, or SubTemplateMultiLists that may have been used in it's added templates.

Parameters

flow

◆ yfHookGetInfoModel()

fbInfoElement_t * yfHookGetInfoModel ( void )

Returns the IPFIX info model aggregated for all plugins.

Returns: pointer to an array of fbInfoElement_t that contains the sum of the IPFIX IE's from all active plugins

◆ yfHookGetTemplate()

gboolean yfHookGetTemplate	(	fbSession_t *	session,
		void **	yfHookCtxArray )

Gets the IPFIX info model template for the export data from all the plugins and turns it into a single template to return.

It caches the results so that future queries are a lot faster. It can validate the cached result if the numer of plugins registered changes.

Parameters

session	pointer to an array of fbInfoElementSpec_t structures that describes the info model template
yfHookCtxArray	array holding each hook's hook-specific context

◆ yfHookGetTemplateCount()

uint8_t yfHookGetTemplateCount ( yfFlow_t * flow )

Returns the amount of templates to add to the SubtemplateMultiList from all plugins hooked.

Parameters

flow

Returns: number of templates to add to SubTemplateMultiList in yaf

◆ yfHookPacket()

gboolean yfHookPacket	(	yfFlowKey_t *	key,
		const uint8_t *	pkt,
		size_t	caplen,
		uint32_t	iplen,
		yfTCPInfo_t *	tcpinfo,
		yfL2Info_t *	l2info )

Function called to do processing on each packet as it comes in.

Parameters

key	pointer to flowkey
pkt	pointer to pkt data
caplen	size of pkt data
iplen
tcpinfo
l2info

Returns: TRUE if pkt processing should continue, FALSE if not

◆ yfHookValidateFlowTab()

void yfHookValidateFlowTab	(	void **	yfHookCtxArray,
		uint32_t	max_payload,
		gboolean	uniflow,
		gboolean	silkmode,
		gboolean	applabelmode,
		gboolean	entropymode,
		gboolean	fingerprintmode,
		gboolean	fpExportMode,
		gboolean	udp_multipkt_payload,
		uint16_t	udp_uniflow_port )

Validation function to make sure the plugin can and should operate based on the flowtable options.

Parameters

yfHookCtxArray	array holding each hook's hook context
max_payload	value
uniflow
silkmode
applabelmode
entropymode
fingerprintmode	p0f finger printing mode
fpExportMode	handshake header export mode
udp_multipkt_payload	concatenate udp payloads similar to TCP
udp_uniflow_port	export all udp packets if have this src or dst port

◆ ypFlowAlloc()

void ypFlowAlloc	(	void **	yfHookFlowContext,
		yfFlow_t *	flow,
		void *	yfHookCtx )

Callback invoked by yfHookFlowAlloc() when a new flow is opened to allow the plugin to create a per-flow context.

Parameters

yfHookFlowContext	where the hook store's this flow's context
flow	newly created flow record
yfHookCtx	this hook's context

◆ ypFlowClose()

gboolean ypFlowClose	(	void *	yfHookFlowContext,
		yfFlow_t *	flow )

Callback invoked by yfHookFlowClose() when a flow is closed to allow the plugin to examine the complete flow record prior to export.

Parameters

yfHookFlowContext	this hook's context for this flow
flow	flow record being closed

◆ ypFlowFree()

void ypFlowFree	(	void *	yfHookFlowContext,
		yfFlow_t *	flow )

Callback invoked by yfHookFlowFree() when a flow is destroyed to allow the plugin to free the flow-specific context set by ypFlowAlloc().

Parameters

yfHookFlowContext	this hook's context for this flow
flow	flow record being freed

◆ ypFlowPacket()

void ypFlowPacket	(	void *	yfHookFlowContext,
		yfFlow_t *	flow,
		yfFlowVal_t *	val,
		const uint8_t *	pkt,
		size_t	caplen,
		uint32_t	iplen,
		yfTCPInfo_t *	tcpinfo,
		yfL2Info_t *	l2info )

Callback invoked by yfHookFlowPacket() to allow the plugin to process each packet as it is read.

This is called in two places: (1)late in yfFlowPBuf() per packet after creating/adding the packet to a flow, and (2)by yfFlowLabelApp() (via yfAppLabelFlow()) that is called when the flow is closed.

When called by yfAppLabelFlow() the last 3 parameters are 0. The callback allows the plugin to process each packet of a flow as it is read.

Parameters

yfHookFlowContext	this hook's context for this flow
flow
val
pkt
caplen
iplen
tcpinfo
l2info

◆ ypFlowWrite()

gboolean ypFlowWrite	(	void *	yfHookFlowContext,
		fbSubTemplateMultiList_t *	rec,
		fbSubTemplateMultiListEntry_t *	stml,
		yfFlow_t *	flow,
		GError **	err )

Callback invoked by yfHookFlowWrite() when the data is copied into an IPFIX record immediately prior to export to allow the plugin to fill its portions of the IPFIX record.

Parameters

yfHookFlowContext	this hook's context for this flow
rec
stml
flow	flow record being written
err	to return an error code

◆ ypFreeLists()

void ypFreeLists	(	void *	yfHookFlowContext,
		yfFlow_t *	flow )

Callback invoked by yfHookFreeLists() after the IPFIX record has been written to allow the plugin to clear its structured data.

Parameters

yfHookFlowContext	this hook's context for this flow
flow	flow record

◆ ypGetInfoModel()

fbInfoElement_t * ypGetInfoModel ( void )

Callback invoked by yfHookGetInfoModel() to allow the plugin to add elements to the InfoModel.

Old (outdated?) comment: This should not be used for v.3

◆ ypGetTemplate()

gboolean ypGetTemplate	(	fbSession_t *	session,
		void *	yfHookCtx )

Callback invoked by yfHookGetTemplate() to allow the plugin to add its templates to the export session.

Parameters

session	where to add templates
yfHookCtx	this hook's context

◆ ypGetTemplateCount()

uint8_t ypGetTemplateCount	(	void *	yfHookFlowContext,
		yfFlow_t *	flow )

Callback invoked by yfHookGetTemplateCount() when sizing the STML to allow the plugin to reserve space in the STML.

Parameters

yfHookFlowContext	this hook's context for this flow
flow	flow record

◆ ypHookPacket()

gboolean ypHookPacket	(	yfFlowKey_t *	key,
		const uint8_t *	pkt,
		size_t	caplen,
		uint32_t	iplen,
		yfTCPInfo_t *	tcpinfo,
		yfL2Info_t *	l2info )

Callback invoked by yfHookPacket() to allow the plugin to prevent the packet from becoming a part of a flow by returning FALSE.

This is called early in yfFlowPBuf() per packet.

Parameters

key	flow key
pkt	first byte of payload
caplen	length of payload
iplen	length of complete packet
tcpinfo	packets TCP info
l2info	packet's layer 2 info

◆ ypSetPluginConf()

void ypSetPluginConf	(	const char *	pluginConf,
		void **	yfHookCtx )

Callback invoked by yfHookAddNewHook() to provide the plugin with the name of the configuration file and to allow the callback to create a plugin specific context.

Parameters

pluginConf	plugin configuration file name
yfHookCtx	location where this hook should store its context

◆ ypSetPluginOpt()

void ypSetPluginOpt	(	const char *	pluginOpt,
		void *	yfHookCtx )

Callback invoked by yfHookAddNewHook() to provide the plugin with command line options other than the configuration file name.

Parameters

pluginOpt	plugin options
yfHookCtx	this hook's context

◆ ypValidateFlowTab()

gboolean ypValidateFlowTab	(	void *	yfHookCtx,
		uint32_t	max_payload,
		gboolean	uniflow,
		gboolean	silkmode,
		gboolean	applabelmode,
		gboolean	entropymode,
		gboolean	fingerprintmode,
		gboolean	fpExportMode,
		gboolean	udp_multipkt_payload,
		uint16_t	udp_uniflow_port,
		GError **	err )

Callback invoked by yfFlowTabAlloc() to allow the plugin to confirm it can be used given the flow-table settings.

Parameters

yfHookCtx	this hook's context
max_payload
uniflow

param silkmode

Parameters

applabelmode
entropymode
fingerprintmode
fpExportMode
udp_multipkt_payload
udp_uniflow_port
err

Data Structures

Macros

Functions

Detailed Description

Function Documentation

◆ yfHookAddNewHook()

◆ yfHookFlowAlloc()

◆ yfHookFlowClose()

◆ yfHookFlowFree()

◆ yfHookFlowPacket()

◆ yfHookFlowWrite()

◆ yfHookFreeLists()

◆ yfHookGetInfoModel()

◆ yfHookGetTemplate()

◆ yfHookGetTemplateCount()

◆ yfHookPacket()

◆ yfHookValidateFlowTab()

◆ ypFlowAlloc()

◆ ypFlowClose()

◆ ypFlowFree()

◆ ypFlowPacket()

◆ ypFlowWrite()

◆ ypFreeLists()

◆ ypGetInfoModel()

◆ ypGetTemplate()

◆ ypGetTemplateCount()

◆ ypHookPacket()

◆ ypSetPluginConf()

◆ ypSetPluginOpt()

◆ ypValidateFlowTab()