yafhooks.h
Go to the documentation of this file.
1 /*
2  ** yafhooks.h
3  ** YAF Active Flow Table Plugin Interface
4  **
5  ** ------------------------------------------------------------------------
6  ** Copyright (C) 2007-2015 Carnegie Mellon University. All Rights Reserved.
7  ** ------------------------------------------------------------------------
8  ** Authors: Brian Trammell
9  ** ------------------------------------------------------------------------
10  ** @OPENSOURCE_HEADER_START@
11  ** Use of the YAF system and related source code is subject to the terms
12  ** of the following licenses:
13  **
14  ** GNU Public License (GPL) Rights pursuant to Version 2, June 1991
15  ** Government Purpose License Rights (GPLR) pursuant to DFARS 252.227.7013
16  **
17  ** NO WARRANTY
18  **
19  ** ANY INFORMATION, MATERIALS, SERVICES, INTELLECTUAL PROPERTY OR OTHER
20  ** PROPERTY OR RIGHTS GRANTED OR PROVIDED BY CARNEGIE MELLON UNIVERSITY
21  ** PURSUANT TO THIS LICENSE (HEREINAFTER THE "DELIVERABLES") ARE ON AN
22  ** "AS-IS" BASIS. CARNEGIE MELLON UNIVERSITY MAKES NO WARRANTIES OF ANY
23  ** KIND, EITHER EXPRESS OR IMPLIED AS TO ANY MATTER INCLUDING, BUT NOT
24  ** LIMITED TO, WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE,
25  ** MERCHANTABILITY, INFORMATIONAL CONTENT, NONINFRINGEMENT, OR ERROR-FREE
26  ** OPERATION. CARNEGIE MELLON UNIVERSITY SHALL NOT BE LIABLE FOR INDIRECT,
27  ** SPECIAL OR CONSEQUENTIAL DAMAGES, SUCH AS LOSS OF PROFITS OR INABILITY
28  ** TO USE SAID INTELLECTUAL PROPERTY, UNDER THIS LICENSE, REGARDLESS OF
29  ** WHETHER SUCH PARTY WAS AWARE OF THE POSSIBILITY OF SUCH DAMAGES.
30  ** LICENSEE AGREES THAT IT WILL NOT MAKE ANY WARRANTY ON BEHALF OF
31  ** CARNEGIE MELLON UNIVERSITY, EXPRESS OR IMPLIED, TO ANY PERSON
32  ** CONCERNING THE APPLICATION OF OR THE RESULTS TO BE OBTAINED WITH THE
33  ** DELIVERABLES UNDER THIS LICENSE.
34  **
35  ** Licensee hereby agrees to defend, indemnify, and hold harmless Carnegie
36  ** Mellon University, its trustees, officers, employees, and agents from
37  ** all claims or demands made against them (and any related losses,
38  ** expenses, or attorney's fees) arising out of, or relating to Licensee's
39  ** and/or its sub licensees' negligent use or willful misuse of or
40  ** negligent conduct or willful misconduct regarding the Software,
41  ** facilities, or other rights or assistance granted by Carnegie Mellon
42  ** University under this License, including, but not limited to, any
43  ** claims of product liability, personal injury, death, damage to
44  ** property, or violation of any laws or regulations.
45  **
46  ** Carnegie Mellon University Software Engineering Institute authored
47  ** documents are sponsored by the U.S. Department of Defense under
48  ** Contract FA8721-05-C-0003. Carnegie Mellon University retains
49  ** copyrights in all material produced under this contract. The U.S.
50  ** Government retains a non-exclusive, royalty-free license to publish or
51  ** reproduce these documents, or allow others to do so, for U.S.
52  ** Government purposes only pursuant to the copyright license under the
53  ** contract clause at 252.227.7013.
54  **
55  ** @OPENSOURCE_HEADER_END@
56  ** ------------------------------------------------------------------------
57  */
58 
100 /*
101 
102 Design notes:
103 
104 1. For now, it is okay for the yfhook facility to only support a single hook.
105 
106 5. Each hook needs to know when a flow is flushed, so that it can make the
107 per-flow export fields available.
108 
109 Changes in Version 4:
110 
111 Added a function to pass a config file to the plugin from the command line.
112 
113 Changes in Version 3:
114 
115 Hooks export entire templates that will be added to Yaf's subTemplateMultiList.
116 yfWriteFlow in yafcore.c will call ypGetTemplateCount (a function as of v. 3),
117 which will return the number of templates Yaf should alloc in the STML. When
118 yfHookWriteFlow is called the STML entry can be added. The hook should not
119 add NULL entries, if no template is to be added, ypGetTemplateCount should return
120 0. If the STML entry contains list fields (BL's, STL's, STML's), it must free
121 these in the call to ypFreeLists. This means that the hook must maintain
122 access to the record so that it can free it.
123 ypFreeList does NOT free Yaf's STML, yaf will free this after all the hook's
124 lists have been freed.
125 
126 As of Version 3, ypGetTemplate will call fbTemplateAppendSpecArray and
127 fbSessionAddTemplate. It does not need to internal templates, only external.
128 
129 ypGetInfoModel should no longer be used. ypGetTemplate should allocate the
130 info model and add the elements to the info model & the template.
131 
132 Versions 2 or Below:
133 
134 Each hook needs to be able to hand YAF an export template for its fields.
135 These fields will appear in every exported record; a facility for NULLs MUST
136 be provided by the hook's representation.
137 
138 */
139 
140 #ifndef _YAF_HOOKS_H_
141 #define _YAF_HOOKS_H_
142 
143 #include <yaf/autoinc.h>
144 #include <yaf/decode.h>
145 #include <yaf/yafcore.h>
146 #include <yaf/yaftab.h>
147 #if YAF_ENABLE_APPLABEL
148 #include <pcre.h>
149 #endif
150 
152 #define YAF_HOOK_INTERFACE_VERSION 6
153 
157  uint8_t version;
159  uint32_t exportDataSize;
162 };
163 
164 
177 gboolean yfHookPacket (
178  yfFlowKey_t * key,
179  const uint8_t * pkt,
180  size_t caplen,
181  uint16_t iplen,
182  yfTCPInfo_t * tcpinfo,
183  yfL2Info_t * l2info);
184 
197 void yfHookFlowPacket (
198  yfFlow_t * flow,
199  yfFlowVal_t * val,
200  const uint8_t *pkt,
201  size_t caplen,
202  uint16_t iplen,
203  yfTCPInfo_t * tcpinfo,
204  yfL2Info_t * l2info);
205 
222  void **yfctx,
223  uint32_t max_payload,
224  gboolean uniflow,
225  gboolean silkmode,
226  gboolean applabelmode,
227  gboolean entropymode,
228  gboolean fingerprintmode,
229  gboolean fpExportMode,
230  gboolean udp_max_payload,
231  uint16_t udp_uniflow_port);
232 
240 gboolean yfHookFlowClose (
241  yfFlow_t * flow);
242 
254 void yfHookFlowAlloc (
255  yfFlow_t * flow,
256  void ** yfctx);
257 
265 void yfHookFlowFree (
266  yfFlow_t * flow);
267 
274 fbInfoElement_t *yfHookGetInfoModel (
275  void);
276 
286 gboolean yfHookGetTemplate (
287  fbSession_t *session);
297 gboolean yfWriteFlowHook (
298  fbSubTemplateMultiList_t *rec,
299  fbSubTemplateMultiListEntry_t *stml,
300  yfFlow_t * flow,
301  GError ** err);
302 
316 gboolean yfHookAddNewHook(
317  const char *hookName,
318  const char *hookOpts,
319  const char *hookConf,
320  void **yfctx,
321  GError ** err);
322 
323 #if YAF_ENABLE_APPLABEL
324 
336 void yfHookScanPayload (
337  yfFlow_t *flow,
338  const uint8_t *pkt,
339  size_t caplen,
340  pcre *expression,
341  uint16_t offset,
342  uint16_t elementID,
343  uint16_t applabel);
344 
345 #endif
346 
354 uint8_t yfHookGetTemplateCount(
355  yfFlow_t *flow);
356 
363 void yfHookFreeLists(
364  yfFlow_t *flow);
365 
366 #endif
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.
uint8_t yfHookGetTemplateCount(yfFlow_t *flow)
Returns the amount of templates to add to the SubtemplateMultiList from all plugins hooked...
void yfHookFlowAlloc(yfFlow_t *flow, void **yfctx)
Allow plugins to allocate flow state information for each flow captured by yaf at the time of flow cr...
Exported from the plugin to tell YAF about its export data & interface version.
Definition: yafhooks.h:155
fbInfoElement_t * yfHookGetInfoModel(void)
Returns the IPFIX info model aggregated for all plugins.
uint32_t exportDataSize
size of data plugin will export
Definition: yafhooks.h:159
void yfHookValidateFlowTab(void **yfctx, 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...
YAF Core Library.
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, void **yfctx, GError **err)
Adds another hook (plugin) into yaf.
gboolean yfHookFlowClose(yfFlow_t *flow)
Called upon flow close to do any necessary plugin processing upon flow close.
gboolean yfHookGetTemplate(fbSession_t *session)
Gets the IPFIX info model template for the export data from all the plugins and turns it into a singl...
A YAF flow.
Definition: yafcore.h:371
TCP information structure.
Definition: decode.h:139
Flow generation interface for YAF.
A YAF uniflow value.
Definition: yafcore.h:276
void yfHookFlowFree(yfFlow_t *flow)
Frees all memory associated with the flow state in all of the attached plugins.
void yfHookFreeLists(yfFlow_t *flow)
Sends control back to the plugin to free any BasicLists, SubTemplateLists, or SubTemplateMultiLists t...
A YAF flow key.
Definition: yafcore.h:208
Datalink layer information structure.
Definition: decode.h:109
uint8_t requireAppLabel
turn on application labeling related functions
Definition: yafhooks.h:161
uint8_t version
version of plugin interface
Definition: yafhooks.h:157
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...