yafcore.h File Reference
#include <yaf/autoinc.h>
#include <fixbuf/public.h>
#include <yaf/yaftime.h>

Go to the source code of this file.

Data Structures

struct  yfFlowKey_st
 A YAF flow key. More...
 
struct  yfFlowStats_st
 yaf enhanced flow statistics More...
 
struct  yfFlowVal_st
 A YAF uniflow value. More...
 
struct  yaf_mptcp_st
 
struct  yfFlow_st
 A YAF flow. More...
 

Macros

#define CERT_PEN   6871
 This is the CERT Private Enterprise Number (PEN) assigned by IANA, used to define our enterprise data elements to extend IPFIX RFC 5103 data model.
 
#define YAF_ERROR_DOMAIN   (g_quark_from_string("certYAFError"))
 GError domain for YAF errors.
 
#define YAF_ERROR_HEADER   1
 A YAF file header was malformed.
 
#define YAF_ERROR_ARGUMENT   2
 Illegal argument error.
 
#define YAF_ERROR_IO   3
 General I/O error.
 
#define YAF_ERROR_IPFIX   4
 YAF could not accept IPFIX input due to missing fields.
 
#define YAF_ERROR_IMPL   5
 Requested feature is not available.
 
#define YAF_ERROR_INTERNAL   6
 Internal error occured (aka a bug)
 
#define YAF_ERROR_LIMIT   7
 Hard program limit reached.
 
#define YAF_ERROR_EOF   8
 End of file.
 
#define YAF_ERROR_ALIGNMENT   9
 Internal alignment error.
 
#define YAF_ERROR_PACKET_PAYLOAD   10
 Packet payload processing error.
 
#define YAF_FLOW_ACTIVE   0
 Pseudo end reason for flows still active during collection.
 
#define YAF_END_IDLE   1
 Flow ended due to idle timeout.
 
#define YAF_END_ACTIVE   2
 Flow ended due to active timeout.
 
#define YAF_END_CLOSED   3
 Flow ended due to FIN or RST close.
 
#define YAF_END_FORCED   4
 Flow ended due to YAF shutdown.
 
#define YAF_END_RESOURCE   5
 Flow flushed due to YAF resource exhaustion.
 
#define YAF_END_UDPFORCE   0x1F
 Flow flushed due to udp-uniflow on all or selected ports.
 
#define YAF_END_MASK   0x7F
 Flow reason mask.
 
#define YAF_ENDF_ISCONT   0x80
 SiLK mode flow reason flag - flow was created after active termination.
 
#define YAF_SAME_SIZE   0x01
 Attribute bit flag: Flow has same size packets in this direction.
 
#define YAF_OUT_OF_SEQUENCE   0x02
 Attribute bit flag: Flow was processed out of sequence.
 
#define YAF_MP_CAPABLE   0x04
 Attribute bit flag: Flow had MP_CAPABLE TCP Option.
 
#define YAF_FRAGMENTS   0x08
 Attribute bit flag: Flow contained packets that were fragmented.
 
#define YAF_PARTIAL_FRAGS   0x10
 Flow contains partial fragments.
 
#define YAF_FRAG_ACTIVE   0x03
 Flow has fragments that have reached active timeout.
 
#define YAF_FRAG_PASSIVE   0x04
 Flow has fragments that have reached passive timeout.
 
#define YAF_IP_ICMP   1
 IP protocol identifier for ICMP.
 
#define YAF_IP_TCP   6
 IP protocol identifier for TCP.
 
#define YAF_IP_UDP   17
 IP protocol identifier for UDP.
 
#define YFP_IPTCPHEADER_SIZE   128
 This is the size of the packet to store away for use primarily in passive OS fingerprinting, this value is only used if application labeling is enabled.
 
#define ETHERNET_MAC_ADDR_LENGTH   6
 length of Ethernet MAC Address
 
#define YAF_MAX_HOOKS   4
 maximum number of hooks (plugins) allowed at one time
 
#define YAF_HOOKS_MAX_EXPORT   1500
 this is the maximum amount of data that the plugins may export in sum total
 
#define YAF_MAX_PKT_BOUNDARY   25
 Maximum Number of Packet Boundaries to keep around per payload.
 
#define YAF_PCAP_MAX   5000000
 Maximum length of PCAP output file - 5MB.
 
#define YAF_MAX_MPLS_LABELS   3
 Maximum number of labels we're going to keep around.
 
#define YAF_SMALL_PKT_BOUND   60
 Upper bound of a packet's payload octets to be a "small packet" in the detailed flow-stats.
 
#define YAF_LARGE_PKT_BOUND   225
 Lower bound of a packet's payload octets to be a "large packet" in the detailed flow-stats.
 
#define YF_TIME_IE__FIRST   YF_TIME_IE_MILLI
 First valid yfRecordTimeIE_t value.
 
#define YF_TIME_IE__LAST   YF_TIME_IE_NANO
 Last valid yfRecordTimeIE_t value.
 
#define YF_TIME_IE__DEFAULT   (YF_TIME_IE_MILLI | YF_TIME_IE_MICRO)
 Default yfRecordTimeIE_t to use.
 
#define yfRecordTimeIEBitSet(t_)   (1 << ((t_) - 1))
 Converts a yfRecordTimeIE_t to a value for adding to a bitfield.
 
#define yfRecordTimeIEBitCheck(bits_, t_)   ((bits_) & yfRecordTimeIEBitSet(t_))
 Check if the bitfield bits_ contains the yfRecordTimeIE_t t_
 

Typedefs

typedef struct yfConfig_st yfConfig_t
 YAF Configuration Settings.
 
typedef enum yfRecordTimeIE_en yfRecordTimeIE_t
 Type to specify which timestamps are included.
 
typedef struct yfFlowKey_st yfFlowKey_t
 A YAF flow key.
 
typedef struct yfFlowStats_st yfFlowStats_t
 yaf enhanced flow statistics
 
typedef struct yfFlowVal_st yfFlowVal_t
 A YAF uniflow value.
 
typedef struct yaf_mptcp_st yaf_mptcp_t
 
typedef struct yfFlow_st yfFlow_t
 A YAF flow.
 

Enumerations

enum  yfRecordTimeIE_en { YF_TIME_IE__UNSET , YF_TIME_IE_MILLI , YF_TIME_IE_MICRO , YF_TIME_IE_NANO }
 Type to specify which timestamps are included. More...
 

Functions

void yfAlignmentCheck (void)
 yfAlignmentCheck
 
void yfFlowPrepare (yfFlow_t *flow)
 Prepare a static flow buffer for use with yaf_flow_read().
 
void yfFlowCleanup (yfFlow_t *flow)
 Clean up after a static flow buffer prepared by yfFlowPrepare.
 
fBuf_t * yfWriterForFile (const char *path, const yfConfig_t *yfConfig, GError **err)
 Get an IPFIX message buffer for writing YAF flows to a named file.
 
fBuf_t * yfWriterForFP (FILE *fp, const yfConfig_t *yfConfig, GError **err)
 Get an IPFIX message buffer for writing YAF flows to an open file pointer.
 
fBuf_t * yfWriterForSpec (fbConnSpec_t *spec, const yfConfig_t *yfConfig, GError **err)
 Get an IPFIX message buffer for writing YAF flows to a socket.
 
gboolean yfWriteOptionsDataFlows (void *yfContext, uint32_t pcap_drop, GTimer *timer, GError **err)
 A wrapper that calls both yfWriteStatsFlow and yfWriteDataFlow with appropriate condition checking.
 
gboolean yfWriteStatsFlow (void *yfContext, uint32_t pcap_drop, GTimer *timer, GError **err)
 Write a statistics options data record to an IPFIX Message buffer.
 
gboolean yfWriteTombstoneFlow (void *yfContext, GError **err)
 Write a tombstone options data record to an IPFIX Message buffer.
 
gboolean yfWriteFlow (void *yfContext, yfFlow_t *flow, GError **err)
 Write a single flow to an IPFIX message buffer.
 
gboolean yfWriterClose (fBuf_t *fbuf, gboolean flush, GError **err)
 Close the connection underlying an IPFIX message buffer created by yfWriterForFP() or yfWriterForSpec().
 
fBuf_t * yfReaderForFP (fBuf_t *fbuf, FILE *fp, GError **err)
 Get an IPFIX message buffer for reading YAF flows from an open file pointer.
 
fbListener_t * yfListenerForSpec (fbConnSpec_t *spec, fbListenerAppInit_fn appinit, fbListenerAppFree_fn appfree, GError **err)
 Get an IPFIX connection listener for collecting YAF flows via IPFIX from the network.
 
gboolean yfReadFlow (fBuf_t *fbuf, yfFlow_t *flow, GError **err)
 Read a single flow from an IPFIX message buffer.
 
gboolean yfReadFlowExtended (fBuf_t *fbuf, yfFlow_t *flow, GError **err)
 Read a single flow from an IPFIX message buffer.
 
void yfPrintString (GString *rstr, yfFlow_t *flow)
 Print a YAF flow to a GString.
 
void yfPrintDelimitedString (GString *rstr, yfFlow_t *flow, gboolean yaft_mac)
 Print a YAF flow to a GString in pipe-delimited (tabular) format.
 
gboolean yfPrint (FILE *out, yfFlow_t *flow, GError **err)
 Print a YAF flow to a file.
 
gboolean yfPrintDelimited (FILE *out, yfFlow_t *flow, gboolean yaft_mac, GError **err)
 Print a YAF flow to a file in pipe-delimited (tabular) format.
 
void yfPrintColumnHeaders (FILE *out, gboolean yaft_mac, GError **err)
 Print column headers for the pipe-delimited (tabular) format.
 

Detailed Description

YAF Core Library.

Defines API for reading and writing YAF files, and the yfFlow_t data structures.

Macro Definition Documentation

◆ YAF_ERROR_DOMAIN

#define YAF_ERROR_DOMAIN   (g_quark_from_string("certYAFError"))

GError domain for YAF errors.

All YAF errors belong to this domain. In addition, YAF core library routines can return libfixbuf errors if reading or writing fails.

◆ YAF_ERROR_HEADER

#define YAF_ERROR_HEADER   1

A YAF file header was malformed.

The file is probably not a YAF file.

◆ YAF_FLOW_ACTIVE

#define YAF_FLOW_ACTIVE   0

Pseudo end reason for flows still active during collection.

Not valid on disk.

◆ YAF_LARGE_PKT_BOUND

#define YAF_LARGE_PKT_BOUND   225

Lower bound of a packet's payload octets to be a "large packet" in the detailed flow-stats.

Payload octets must be greater than this value.

◆ YAF_SMALL_PKT_BOUND

#define YAF_SMALL_PKT_BOUND   60

Upper bound of a packet's payload octets to be a "small packet" in the detailed flow-stats.

Payload octets must be less than this value.

Typedef Documentation

◆ yfFlow_t

typedef struct yfFlow_st yfFlow_t

A YAF flow.

Joins a flow key with forward and reverse flow values in time.

Note
if you edit the layout of this structure, you must make a corresponding edit of the yfFlowIPv4_t structure in yaftab.c

◆ yfFlowKey_t

typedef struct yfFlowKey_st yfFlowKey_t

A YAF flow key.

Contains a flow's five-tuple; used at runtime in the flow table.

Note
if you edit the layout of this structure, you must make a corresponding edit of the yfFlowKeyIPv4_t structure in yaftab.c

◆ yfFlowVal_t

typedef struct yfFlowVal_st yfFlowVal_t

A YAF uniflow value.

Contains directional packet header fields and counters; two of these are used to build a biflow.

Enumeration Type Documentation

◆ yfRecordTimeIE_en

Type to specify which timestamps are included.

Enumerator
YF_TIME_IE__UNSET 

Unset value.

YF_TIME_IE_MILLI 

Include flowStartMilliseconds, etc in the export template.

YF_TIME_IE_MICRO 

Include flowStartMicrioseconds, etc in the export template.

YF_TIME_IE_NANO 

Include flowStartNanoseconds, etc in the export template.

Function Documentation

◆ yfAlignmentCheck()

void yfAlignmentCheck ( void )

yfAlignmentCheck

This is a purely internal diagnostic function. It checks the alignment of the internal data structures that are used with fixbuf and causes the program to abort if there is an alignment issue.

◆ yfFlowCleanup()

void yfFlowCleanup ( yfFlow_t * flow)

Clean up after a static flow buffer prepared by yfFlowPrepare.

This is used to free storage for payload information.

Parameters
flowa yfFlow_t to free

◆ yfFlowPrepare()

void yfFlowPrepare ( yfFlow_t * flow)

Prepare a static flow buffer for use with yaf_flow_read().

Call this before the first yaf_flow_read() call; subsequent reads do not need initialization. This is used to prepare storage for payload information.

Parameters
flowa yfFlow_t to initialize

◆ yfListenerForSpec()

fbListener_t * yfListenerForSpec ( fbConnSpec_t * spec,
fbListenerAppInit_fn appinit,
fbListenerAppFree_fn appfree,
GError ** err )

Get an IPFIX connection listener for collecting YAF flows via IPFIX from the network.

Parameters
specfixbuf connection specifier for local end of socket.
appinitApplication context initialization function, for creating application-specific collector contexts. Pass NULL for no appinit function.
appfreeApplication context cleanup function. Pass NULL for no appfree function.
erran error description, set on failure.
Returns
a new listener, initialized for reading YAF flows, for use with fbListenerWait(). Buffers returned from this call can then be used with yfReadFlow() and yfReadFlowExtended().

◆ yfPrint()

gboolean yfPrint ( FILE * out,
yfFlow_t * flow,
GError ** err )

Print a YAF flow to a file.

Parameters
outfile to print to.
flowflow to print.
erran error descriptor.
Returns
TRUE on success, FALSE otherwise.

◆ yfPrintColumnHeaders()

void yfPrintColumnHeaders ( FILE * out,
gboolean yaft_mac,
GError ** err )

Print column headers for the pipe-delimited (tabular) format.

Parameters
outfile to print to.
yaft_macprint mac address column headers if enabled
erran error descriptor.
Returns
TRUE on success, FALSE otherwise.

◆ yfPrintDelimited()

gboolean yfPrintDelimited ( FILE * out,
yfFlow_t * flow,
gboolean yaft_mac,
GError ** err )

Print a YAF flow to a file in pipe-delimited (tabular) format.

Parameters
outfile to print to.
flowflow to print.
yaft_macprint mac addresses in tabular format
erran error descriptor.
Returns
TRUE on success, FALSE otherwise.

◆ yfPrintDelimitedString()

void yfPrintDelimitedString ( GString * rstr,
yfFlow_t * flow,
gboolean yaft_mac )

Print a YAF flow to a GString in pipe-delimited (tabular) format.

Parameters
rstrstring to append text representation of flow to.
flowflow to print.
yaft_macAdd mac addresses to tabular format.

◆ yfPrintString()

void yfPrintString ( GString * rstr,
yfFlow_t * flow )

Print a YAF flow to a GString.

Parameters
rstrstring to append text representation of flow to.
flowflow to print.

◆ yfReaderForFP()

fBuf_t * yfReaderForFP ( fBuf_t * fbuf,
FILE * fp,
GError ** err )

Get an IPFIX message buffer for reading YAF flows from an open file pointer.

Reuses an existing buffer if supplied.

Parameters
fbufIPFIX message buffer to reuse; must have been returned by a prior call to yfReaderForFP(). Pass NULL to create a new buffer.
fpFile pointer to open file to read from.
erran error description, set on failure.
Returns
a new reader, or a reused reader, for reading the given open file. NULL on failure.

◆ yfReadFlow()

gboolean yfReadFlow ( fBuf_t * fbuf,
yfFlow_t * flow,
GError ** err )

Read a single flow from an IPFIX message buffer.

The buffer must have been returned by yfReaderForFP(), or by fbListenerWait() called on a listener created by yfListenerForSpec().

Parameters
fbufBuffer to read message from, returned by yfReaderForFP() or from a YAF listener.
flowpointer to yfFlow_t structure to fill from file or stream.
erran error description; required.
Returns
TRUE on success, FALSE otherwise. If false, check error against FB_ERROR_EOF to determine if the message reader is at end of file or stream, or against FB_ERROR_EOM to see if the listener should be waited upon.

◆ yfReadFlowExtended()

gboolean yfReadFlowExtended ( fBuf_t * fbuf,
yfFlow_t * flow,
GError ** err )

Read a single flow from an IPFIX message buffer.

The buffer must have been returned by yfReaderForFP(), or by fbListenerWait() called on a listener created by yfListenerForSpec(). This function does not necessarily require its input to have been written by yfWriteFlow(); it supports additional flow timestamp and counter IEs that may be exported by other IPFIX exporting processes.

Parameters
fbufBuffer to read message from, returned by yfReaderForFP() or from a YAF listener.
flowpointer to yfFlow_t structure to fill from file or stream.
erran error description; required.
Returns
TRUE on success, FALSE otherwise. If false, check error against FB_ERROR_EOF to determine if the message reader is at end of file or stream, or against FB_ERROR_EOM to see if the listener should be waited upon.

◆ yfWriteFlow()

gboolean yfWriteFlow ( void * yfContext,
yfFlow_t * flow,
GError ** err )

Write a single flow to an IPFIX message buffer.

The buffer must have been returned by yfWriterForFP() or yfWriterForSpec().

Parameters
yfContextContext pointer for the yaf state, used to get the fbuf pointer, a buffer to write the message to, returned from yfWriterForFP() or yfWriterForSpec()
flowpointer to yfFlow_t to write to file or stream.
erran error description; required.
Returns
TRUE on success, FALSE otherwise.

◆ yfWriteOptionsDataFlows()

gboolean yfWriteOptionsDataFlows ( void * yfContext,
uint32_t pcap_drop,
GTimer * timer,
GError ** err )

A wrapper that calls both yfWriteStatsFlow and yfWriteDataFlow with appropriate condition checking.

Parameters
yfContextContext pointer for the yaf state, used to get the fbuf pointer.
pcap_dropNumber of packets dropped reported by libpcap
timerPointer to yafstats GTimer
erran error description; required.
Returns
TRUE on success, FALSE otherwise.

◆ yfWriterClose()

gboolean yfWriterClose ( fBuf_t * fbuf,
gboolean flush,
GError ** err )

Close the connection underlying an IPFIX message buffer created by yfWriterForFP() or yfWriterForSpec().

If flush is TRUE, forces any message in progress to be emitted before close; use FALSE if closing the buffer in response to a write error. Does not free the buffer.

Parameters
fbufbuffer to close.
flushTRUE to flush buffer before closing.
erran error description, set on failure.
Returns
TRUE on success, FALSE otherwise.

◆ yfWriterForFile()

fBuf_t * yfWriterForFile ( const char * path,
const yfConfig_t * yfConfig,
GError ** err )

Get an IPFIX message buffer for writing YAF flows to a named file.

Sets the observation domain of the buffer to the given value.

Parameters
pathName of the file to write to, or - for stdout.
yfConfigYAF configuration settings
erran error description, set on failure.
Returns
fBuf_t a new writer, or a reused writer, for writing on the given open file. NULL on failure.

◆ yfWriterForFP()

fBuf_t * yfWriterForFP ( FILE * fp,
const yfConfig_t * yfConfig,
GError ** err )

Get an IPFIX message buffer for writing YAF flows to an open file pointer.

Sets the observation domain of the buffer to the given value. Note that this is intended for use with Airframe MIO based applications; non-MIO applications writing YAF IPFIX files should use yfWriterForFile instead.

Parameters
fpFile pointer to open file to write to.
yfConfigYAF configuration settings
erran error description, set on failure.
Returns
fBuf_t a new writer, or a reused writer, for writing on the given open file. NULL on failure.

◆ yfWriterForSpec()

fBuf_t * yfWriterForSpec ( fbConnSpec_t * spec,
const yfConfig_t * yfConfig,
GError ** err )

Get an IPFIX message buffer for writing YAF flows to a socket.

Parameters
specfixbuf connection specifier for remote end of socket.
yfConfigYAF configuration settings
erran error description, set on failure.
Returns
a new writer for export to the given address.

◆ yfWriteStatsFlow()

gboolean yfWriteStatsFlow ( void * yfContext,
uint32_t pcap_drop,
GTimer * timer,
GError ** err )

Write a statistics options data record to an IPFIX Message buffer.

To turn off stats output - use –nostats. Sets the internal template to the stats option template, builds the record, and sends it - then sets the internal template back to the full flow record.

Parameters
yfContextContext pointer for the yaf state, used to get the fbuf pointer.
pcap_dropNumber of packets dropped reported by libpcap
timerPointer to yafstats GTimer
erran error description; required.
Returns
TRUE on success, FALSE otherwise.

◆ yfWriteTombstoneFlow()

gboolean yfWriteTombstoneFlow ( void * yfContext,
GError ** err )

Write a tombstone options data record to an IPFIX Message buffer.

Sets the internal template to the tombstone option template, builds the record, and sends it - then sets the internal template back to the full flow record.

Parameters
yfContextContext pointer for the yaf state, used to get the fbuf pointer.
erran error description; required.
Returns
TRUE on success, FALSE otherwise.