YAF - Documentation - Core Library 1.0.0 API
Documentation | Downloads

decode.h File Reference

Packet decoding interface for YAF. More...

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

Go to the source code of this file.


Data Structures

struct  yfIPFragInfo_st
 Fragmentation information structure. More...
struct  yfL2Info_st
 Datalink layer information structure. More...
struct  yfTCPInfo_st
 TCP information structure. More...
struct  yfPBuf_st
 Full packet information structure. More...

Defines

#define YF_MPLS_LABEL_COUNT_MAX   10
 Maximum MPLS label count.
#define YF_PBUFLEN_NOL2INFO   offsetof(yfPBuf_t, l2info)
 Size of a packet buffer with payload capture disabled.
#define YF_PBUFLEN_NOPAYLOAD   offsetof(yfPBuf_t, paylen)
 Size of a packet buffer with payload capture disabled.
#define YF_PBUFLEN_BASE   offsetof(yfPBuf_t, payload)
 Size of a packet buffer minus payload buffer.
#define YF_TYPE_IPv4   0x0800
 Ethertype for IP version 4 packets.
#define YF_TYPE_IPv6   0x86DD
 Ethertype for IP version 6 packets.
#define YF_TYPE_IPANY   0x0000
 Pseudo-ethertype for any IP version packets.
#define YF_PROTO_IP6_HOP   0
 IPv6 Next Header for Hop-by-Hop Options.
#define YF_PROTO_ICMP   1
 IPv4 Protocol Identifier and IPv6 Next Header for ICMP.
#define YF_PROTO_TCP   6
 IPv4 Protocol Identifier and IPv6 Next Header for TCP.
#define YF_PROTO_UDP   17
 IPv4 Protocol Identifier and IPv6 Next Header for UDP.
#define YF_PROTO_IP6_ROUTE   43
 IPv6 Next Header for Routing Options.
#define YF_PROTO_IP6_FRAG   44
 IPv6 Next Header for Fragment Options.
#define YF_PROTO_GRE   47
 IPv4 Protocol Identifier and IPv6 Next Header for GRE.
#define YF_PROTO_ICMP6   58
 IPv4 Protocol Identifier and IPv6 Next Header for ICMP6.
#define YF_PROTO_IP6_DOPT   60
 IPv6 Next Header for Destination Options.
#define YF_TF_FIN   0x01
 TCP FIN flag.
#define YF_TF_SYN   0x02
 TCP SYN flag.
#define YF_TF_RST   0x04
 TCP FIN flag.
#define YF_TF_PSH   0x08
 TCP PSH flag.
#define YF_TF_ACK   0x10
 TCP ACK flag.
#define YF_TF_URG   0x20
 TCP URG flag.
#define YF_TF_ECE   0x40
 TCP ECE flag.
#define YF_TF_CWR   0x80
 TCP CWR flag.

Typedefs

typedef struct yfIPFragInfo_st yfIPFragInfo_t
typedef struct yfL2Info_st yfL2Info_t
typedef struct yfTCPInfo_st yfTCPInfo_t
typedef struct yfPBuf_st yfPBuf_t
typedef struct yfDecodeCtx_st yfDecodeCtx_t
 An opaque decode context.

Functions

yfDecodeCtx_tyfDecodeCtxAlloc (int datalink, uint16_t reqtype, gboolean gremode)
 Allocate a decode context.
void yfDecodeCtxFree (yfDecodeCtx_t *ctx)
 Free a decode context.
gboolean yfDecodeToPBuf (yfDecodeCtx_t *ctx, uint64_t ptime, size_t caplen, const uint8_t *pkt, yfIPFragInfo_t *fraginfo, size_t pbuflen, yfPBuf_t *pbuf)
 Decode a packet into a durable packet buffer.
uint64_t yfDecodeTimeval (const struct timeval *tv)
 Utility call to convert a struct timeval (as returned from pcap) into a 64-bit epoch millisecond timestamp suitable for use with yfDecodeToPBuf.
uint64_t yfDecodeTimeNTP (uint64_t ntp)
 Utility call to convert an NTP timestamp (as returned from DAG) into a 64-bit epoch millisecond timestamp suitable for use with.
void yfDecodeDumpStats (yfDecodeCtx_t *ctx)
 Print decoder statistics to the log.

Detailed Description

Packet decoding interface for YAF.

This file's single function decodes IPv4 and IPv6 packets within loopback, raw, Ethernet, Linux SLL ("cooked"), and C-HDLC frames, encapsulated within MPLS, 802.1q VLAN, and/or GRE. It provides high-performance partial reassembly of IPv4 and IPv6 fragments to properly generate flows from fragmented data, and to support the export of the first N bytes of a given flow.

The structures filled in by yfDecodePkt() are used within the flow generator, and are suitable for other similar purposes.


Define Documentation

#define YF_TF_ACK   0x10

TCP ACK flag.

Acknowledgment number is valid.

#define YF_TF_CWR   0x80

TCP CWR flag.

Used for explicit congestion notification.

#define YF_TF_ECE   0x40

TCP ECE flag.

Used for explicit congestion notification.

#define YF_TF_FIN   0x01

TCP FIN flag.

End of connection.

#define YF_TF_PSH   0x08

TCP PSH flag.

#define YF_TF_RST   0x04

TCP FIN flag.

Abnormal end of connection.

#define YF_TF_SYN   0x02

TCP SYN flag.

Start of connection.

#define YF_TF_URG   0x20

TCP URG flag.

Urgent pointer is valid.

#define YF_TYPE_IPANY   0x0000

Pseudo-ethertype for any IP version packets.

Used as the reqtype argument to yfDecodeIP().

#define YF_TYPE_IPv4   0x0800

Ethertype for IP version 4 packets.

#define YF_TYPE_IPv6   0x86DD

Ethertype for IP version 6 packets.


Function Documentation

yfDecodeCtx_t* yfDecodeCtxAlloc ( int  datalink,
uint16_t  reqtype,
gboolean  gremode 
)

Allocate a decode context.

Decode contexts are used to store decoder internal state, configuration, and statistics.

Parameters:
datalink libpcap DLT_ constant describing the layer 2 headers on the packet in pkt. Supported datalink types are DLT_EN10MB (Ethernet), DLT_CHDLC (Cisco HDLC), DLT_LINUX_SLL (Linux "cooked" capture interface), DLT_RAW (raw IP packet, no layer 2), DLT_NULL (loopback), and DLT_LOOP (OpenBSD loopback).
reqtype Required IP packet ethertype. Pass YF_TYPE_IPv4 to decode only IPv4 packets, YF_TYPE_IPv6 to decode only IPv6 packets, or YP_TYPE_IPANY to decode both IPv4 and IPv6 packets.
gremode TRUE to enable GREv1 decoding; otherwise, GRE packets will be left encapsulated.
Returns:
a new decode context

void yfDecodeCtxFree ( yfDecodeCtx_t ctx  ) 

Free a decode context.

Parameters:
ctx A decode context allocated with yfDecodeCtxAlloc()

void yfDecodeDumpStats ( yfDecodeCtx_t ctx  ) 

Print decoder statistics to the log.

Parameters:
ctx decode context to print statistics from

uint64_t yfDecodeTimeNTP ( uint64_t  ntp  ) 

Utility call to convert an NTP timestamp (as returned from DAG) into a 64-bit epoch millisecond timestamp suitable for use with.

Parameters:
tv Pointer to struct timeval to convert
Returns:
the corresponding timestamp in epoch milliseconds

uint64_t yfDecodeTimeval ( const struct timeval *  tv  ) 

Utility call to convert a struct timeval (as returned from pcap) into a 64-bit epoch millisecond timestamp suitable for use with yfDecodeToPBuf.

Parameters:
tv Pointer to struct timeval to convert
Returns:
the corresponding timestamp in epoch milliseconds

gboolean yfDecodeToPBuf ( yfDecodeCtx_t ctx,
uint64_t  ptime,
size_t  caplen,
const uint8_t *  pkt,
yfIPFragInfo_t fraginfo,
size_t  pbuflen,
yfPBuf_t pbuf 
)

Decode a packet into a durable packet buffer.

It is assumed the packet is encapsulated within a link layer frame described by the datalink parameter. It fills in the pbuf structure, copying payload if necessary.

Parameters:
ctx Decode context obtained from yfDecodeCtxAlloc() containing decoder configuration and internal state.
ptime Packet observation time in epoch milliseconds. Use yfDecodeTimeval() or yfDecodeTimeNTP() to get epoch milliseconds from a struct timeval or a 64-bit NTP timestamp, respectively.
caplen Length of the packet to decode pkt.
pkt Pointer to packet to decode. Is assumed to start with the layer 2 header described by the datalink parameter.
fraginfo Pointer to IP Fragment information structure which will be filled in with fragment id and offset information from the decoded IP headers. MAY be NULL if the caller does not require fragment information; in this case, all fragmented packets will be dropped.
pbuflen Total length of the packet buffer pbuf. Use the YF_PBUFLEN_ macros to set this value. YF_PUBFLEN_NOFRAG disables fragment decode, layer 2 decode, and payload capture. YF_PBUFLEN_NOL2INFO disables layer 2 decode and payload capture. YF_PBUFLEN_NOPAYLOAD disables payload capture only. To enable full decode including payload, use YF_PBUFLEN_BASE plus the payload length. The buffer at pbuf MUST be able to contain pbuflen bytes.
pbuf Packet buffer to decode packet into. Will contain copies of all packet data and payload; this buffer is durable.
Returns:
TRUE on success (a packet of the required type was decoded and all the decode structures are valid), FALSE otherwise. Failures are counted in the decode statistics which can be logged with the yfDecodeDumpStats() call;