yafcore.h File Reference

YAF Core Library. More...

#include <yaf/autoinc.h>
#include <fixbuf/public.h>

Go to the source code of this file.

Data Structures

struct  yfFlowKey_st
 A YAF flow key. More...
struct  yfFlowVal_st
 A YAF uniflow value. More...
struct  yfFlow_st
 A YAF flow. More...

Defines

#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_SAME_SIZE   0x01
 Flow has same size packets in this direction.
#define YAF_OUT_OF_SEQUENCE   0x02
 Flow was processed out of sequence.
#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_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   256
 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.

Typedefs

typedef struct yfFlowKey_st yfFlowKey_t
 A YAF flow key.
typedef struct yfFlowVal_st yfFlowVal_t
 A YAF uniflow value.
typedef struct yfFlow_st yfFlow_t
 A YAF flow.

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, uint32_t domain, GError **err)
 Get an IPFIX message buffer for writing YAF flows to a named file.
fBuf_t * yfWriterForFP (FILE *fp, uint32_t domain, GError **err)
 Get an IPFIX message buffer for writing YAF flows to an open file pointer.
fBuf_t * yfWriterForSpec (fbConnSpec_t *spec, uint32_t domain, GError **err)
 Get an IPFIX message buffer for writing YAF flows to a socket.
gboolean yfWriteStatsFlow (void *yfContext, uint32_t pcap_drop, GTimer *timer, GError **err)
 Write an 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().
void yfWriterExportPayload (gboolean payload_mode)
 FIXME doc.
void yfWriterExportMappedV6 (gboolean map_mode)
 FIXME doc.
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.


Define Documentation

#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_IDLE   1

Flow ended due to idle timeout.

#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_ERROR_ARGUMENT   2

Illegal argument error.

#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.

#define YAF_ERROR_HEADER   1

A YAF file header was malformed.

The file is probably not a YAF file.

#define YAF_ERROR_IPFIX   4

YAF could not accept IPFIX input due to missing fields.

#define YAF_FLOW_ACTIVE   0

Pseudo end reason for flows still active during collection.

Not valid on disk.


Typedef Documentation

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
typedef struct yfFlowKey_st yfFlowKey_t

A YAF flow key.

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

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.


Function Documentation

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.

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:
flow a yfFlow_t to free
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:
flow a yfFlow_t to initialize
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:
spec fixbuf connection specifier for local end of socket.
appinit Application context initialization function, for creating application-specific collector contexts. Pass NULL for no appinit function.
appfree Application context cleanup function. Pass NULL for no appfree function.
err an 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().
gboolean yfPrint ( FILE *  out,
yfFlow_t flow,
GError **  err 
)

Print a YAF flow to a file.

Parameters:
out file to print to.
flow flow to print.
err an error descriptor.
Returns:
TRUE on success, FALSE otherwise.
void yfPrintColumnHeaders ( FILE *  out,
gboolean  yaft_mac,
GError **  err 
)

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

Parameters:
out file to print to.
yaft_mac print mac address column headers if enabled
err an error descriptor.
Returns:
TRUE on success, FALSE otherwise.
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:
out file to print to.
flow flow to print.
yaft_mac print mac addresses in tabular format
err an error descriptor.
Returns:
TRUE on success, FALSE otherwise.
void yfPrintDelimitedString ( GString *  rstr,
yfFlow_t flow,
gboolean  yaft_mac 
)

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

Parameters:
rstr string to append text representation of flow to.
flow flow to print.
yaft_mac Add mac addresses to tabular format.
void yfPrintString ( GString *  rstr,
yfFlow_t flow 
)

Print a YAF flow to a GString.

Parameters:
rstr string to append text representation of flow to.
flow flow to print.
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:
fbuf IPFIX message buffer to reuse; must have been returned by a prior call to yfReaderForFP(). Pass NULL to create a new buffer.
fp File pointer to open file to read from.
err an error description, set on failure.
Returns:
a new reader, or a reused reader, for reading the given open file. NULL on failure.
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:
fbuf Buffer to read message from, returned by yfReaderForFP() or from a YAF listener.
flow pointer to yfFlow_t structure to fill from file or stream.
err an 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.
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:
fbuf Buffer to read message from, returned by yfReaderForFP() or from a YAF listener.
flow pointer to yfFlow_t structure to fill from file or stream.
err an 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.
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:
yfContext Context pointer for the yaf state, used to get the fbuf pointer, a buffer to write the message to, returned from yfWriterForFP() or yfWriterForSpec()
flow pointer to yfFlow_t to write to file or stream.
err an error description; required.
Returns:
TRUE on success, FALSE otherwise.
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:
fbuf buffer to close.
flush TRUE to flush buffer before closing.
err an error description, set on failure.
Returns:
TRUE on success, FALSE otherwise.
fBuf_t* yfWriterForFile ( const char *  path,
uint32_t  domain,
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:
path Name of the file to write to, or - for stdout.
domain observation domain
err an 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.
fBuf_t* yfWriterForFP ( FILE *  fp,
uint32_t  domain,
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:
fp File pointer to open file to write to.
domain observation domain
err an 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.
fBuf_t* yfWriterForSpec ( fbConnSpec_t *  spec,
uint32_t  domain,
GError **  err 
)

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

Parameters:
spec fixbuf connection specifier for remote end of socket.
domain observation domain
err an error description, set on failure.
Returns:
a new writer for export to the given address.
gboolean yfWriteStatsFlow ( void *  yfContext,
uint32_t  pcap_drop,
GTimer *  timer,
GError **  err 
)

Write an options data record to an IPFIX Message buffer.

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

Parameters:
yfContext Context pointer for the yaf state, used to get the fbuf pointer.
pcap_drop Number of packets dropped reported by libpcap
timer Pointer to yafstats GTimer
err an error description; required.
Returns:
TRUE on success, FALSE otherwise.