yafcore.h File Reference

YAF core I/O routines. 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   6
 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_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

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 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 I/O routines.

YAF Core Library.

------------------------------------------------------------------------ Copyright (C) 2006-2011 Carnegie Mellon University. All Rights Reserved. ------------------------------------------------------------------------ Authors: Brian Trammell ------------------------------------------------------------------------ @ Use of the YAF system and related source code is subject to the terms of the following licenses:

GNU Public License (GPL) Rights pursuant to Version 2, June 1991 Government Purpose License Rights (GPLR) pursuant to DFARS 252.227.7013

NO WARRANTY

ANY INFORMATION, MATERIALS, SERVICES, INTELLECTUAL PROPERTY OR OTHER PROPERTY OR RIGHTS GRANTED OR PROVIDED BY CARNEGIE MELLON UNIVERSITY PURSUANT TO THIS LICENSE (HEREINAFTER THE "DELIVERABLES") ARE ON AN "AS-IS" BASIS. CARNEGIE MELLON UNIVERSITY MAKES NO WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED AS TO ANY MATTER INCLUDING, BUT NOT LIMITED TO, WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, INFORMATIONAL CONTENT, NONINFRINGEMENT, OR ERROR-FREE OPERATION. CARNEGIE MELLON UNIVERSITY SHALL NOT BE LIABLE FOR INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, SUCH AS LOSS OF PROFITS OR INABILITY TO USE SAID INTELLECTUAL PROPERTY, UNDER THIS LICENSE, REGARDLESS OF WHETHER SUCH PARTY WAS AWARE OF THE POSSIBILITY OF SUCH DAMAGES. LICENSEE AGREES THAT IT WILL NOT MAKE ANY WARRANTY ON BEHALF OF CARNEGIE MELLON UNIVERSITY, EXPRESS OR IMPLIED, TO ANY PERSON CONCERNING THE APPLICATION OF OR THE RESULTS TO BE OBTAINED WITH THE DELIVERABLES UNDER THIS LICENSE.

Licensee hereby agrees to defend, indemnify, and hold harmless Carnegie Mellon University, its trustees, officers, employees, and agents from all claims or demands made against them (and any related losses, expenses, or attorney's fees) arising out of, or relating to Licensee's and/or its sub licensees' negligent use or willful misuse of or negligent conduct or willful misconduct regarding the Software, facilities, or other rights or assistance granted by Carnegie Mellon University under this License, including, but not limited to, any claims of product liability, personal injury, death, damage to property, or violation of any laws or regulations.

Carnegie Mellon University Software Engineering Institute authored documents are sponsored by the U.S. Department of Defense under Contract F19628-00-C-0003. Carnegie Mellon University retains copyrights in all material produced under this contract. The U.S. Government retains a non-exclusive, royalty-free license to publish or reproduce these documents, or allow others to do so, for U.S. Government purposes only pursuant to the copyright license under the contract clause at 252.227.7013.

@ ------------------------------------------------------------------------

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   6

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.