yafhooks.h File Reference

Processing hook interface for YAF. More...

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

Go to the source code of this file.

Data Structures

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

Defines

#define YAF_HOOK_INTERFACE_VERSION   5
 HOOKS Plugin Version.

Functions

gboolean yfHookPacket (yfFlowKey_t *key, const uint8_t *pkt, size_t caplen, uint16_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, uint16_t iplen, yfTCPInfo_t *tcpinfo, yfL2Info_t *l2info)
 Similar to yfHookPacket but also given yfFlowVal_t struct for processing per flow direction.
void yfHookValidateFlowTab (uint32_t max_payload, gboolean uniflow, gboolean silkmode, gboolean applabelmode, gboolean entropymode, gboolean fingerprintmode, gboolean fpExportMode, gboolean udp_max_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)
 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)
 Gets the IPFIX info model template for the export data from _all_ the plugins and turns it into a single template to return.
gboolean yfWriteFlowHook (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, GError **err)
 Adds another hook (plugin) into yaf.
void yfHookScanPayload (yfFlow_t *flow, const uint8_t *pkt, size_t caplen, pcre *expression, uint16_t offset, uint16_t elementID, uint16_t applabel)
 Specifically if application labeling is enabled for deep packet inspection plugin.
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.

Detailed Description

Processing hook interface for YAF.

VERSION 3 - REQUIRES FIXBUF 1.0

The plugin must implement all of the following functions:

ypGetMetaData - returns the version, max export bytes, applabel enabled

ypHookPacket - called by yfFlowPBuf()

ypFlowPacket - called by yfFlowPBuf() and yfAppLabelFlow() when called by yfAppLabelFlow - the last 3 parameters are 0

ypFlowClose - called by yfFlowClose()

ypFlowAlloc - called by yfFlowGetNode()

ypFlowFree - called by yfFlowFree()

ypGetInfoModel - called by yfInfoModel() - this should not be used for v.3

ypGetTemplate - called by yfInitExporterSession()

ypSetPluginOpt - called by yfHookAddNewHook()

ypSetPluginConf - called by yfHookAddNewHook()

ypScanPayload - if Application labeling is enabled, called by app plugins

ypValidateFlowTab - called by yfFlowTabAlloc()

ypGetTemplateCount - called by yfWriteFlow()

ypFreeLists - called by yfWriteFlow()

Function Documentation

gboolean yfHookAddNewHook ( const char *  hookName,
const char *  hookOpts,
const char *  hookConf,
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
err the error value that gets set if this call didn't work
Returns:
TRUE if plugin loaded fine, other FALSE
void yfHookFlowAlloc ( yfFlow_t *  flow  ) 

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
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
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
void yfHookFlowPacket ( yfFlow_t *  flow,
yfFlowVal_t *  val,
const uint8_t *  pkt,
size_t  caplen,
uint16_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 
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 
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
gboolean yfHookGetTemplate ( fbSession_t *  session  ) 

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
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
gboolean yfHookPacket ( yfFlowKey_t *  key,
const uint8_t *  pkt,
size_t  caplen,
uint16_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
void yfHookScanPayload ( yfFlow_t *  flow,
const uint8_t *  pkt,
size_t  caplen,
pcre *  expression,
uint16_t  offset,
uint16_t  elementID,
uint16_t  applabel 
)

Specifically if application labeling is enabled for deep packet inspection plugin.

Parameters:
flow 
pkt pointer to payload
caplen payloadSize
expression PCRE expression to evaluate against payload
offset in payload to begin
elementID label for regex
applabel 
void yfHookValidateFlowTab ( uint32_t  max_payload,
gboolean  uniflow,
gboolean  silkmode,
gboolean  applabelmode,
gboolean  entropymode,
gboolean  fingerprintmode,
gboolean  fpExportMode,
gboolean  udp_max_payload,
uint16_t  udp_uniflow_port 
)

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

Parameters:
max_payload value
uniflow 
silkmode 
applabelmode 
entropymode 
fingerprintmode p0f finger printing mode
fpExportMode handshake header export mode
udp_max_payload concatenate udp payloads similar to TCP
udp_uniflow_port export all udp packets if have this src or dst port
gboolean yfWriteFlowHook ( 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