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-2021 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 General 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 
102 /*
103  *
104  * Design notes:
105  *
106  * 1. For now, it is okay for the yfhook facility to only support a single
107  * hook.
108  *
109  * 5. Each hook needs to know when a flow is flushed, so that it can make the
110  * per-flow export fields available.
111  *
112  * Changes in Version 4:
113  *
114  * Added a function to pass a config file to the plugin from the command line.
115  *
116  * Changes in Version 3:
117  *
118  * Hooks export entire templates that will be added to Yaf's
119  * subTemplateMultiList.
120  * yfWriteFlow in yafcore.c will call ypGetTemplateCount (a function as of v.
121  * 3),
122  * which will return the number of templates Yaf should alloc in the STML.
123  * When
124  * yfHookWriteFlow is called the STML entry can be added. The hook should not
125  * add NULL entries, if no template is to be added, ypGetTemplateCount should
126  * return
127  * 0. If the STML entry contains list fields (BL's, STL's, STML's), it must
128  * free
129  * these in the call to ypFreeLists. This means that the hook must maintain
130  * access to the record so that it can free it.
131  * ypFreeList does NOT free Yaf's STML, yaf will free this after all the hook's
132  * lists have been freed.
133  *
134  * As of Version 3, ypGetTemplate will call fbTemplateAppendSpecArray and
135  * fbSessionAddTemplate. It does not need to internal templates, only
136  * external.
137  *
138  * ypGetInfoModel should no longer be used. ypGetTemplate should allocate the
139  * info model and add the elements to the info model & the template.
140  *
141  * Versions 2 or Below:
142  *
143  * Each hook needs to be able to hand YAF an export template for its fields.
144  * These fields will appear in every exported record; a facility for NULLs MUST
145  * be provided by the hook's representation.
146  *
147  */
148 
149 #ifndef _YAF_HOOKS_H_
150 #define _YAF_HOOKS_H_
151 
152 #include <yaf/autoinc.h>
153 #include <yaf/decode.h>
154 #include <yaf/yafcore.h>
155 #include <yaf/yaftab.h>
156 #if YAF_ENABLE_APPLABEL
157 #include <pcre.h>
158 #endif
159 
161 #define YAF_HOOK_INTERFACE_VERSION 6
162 
167  uint8_t version;
169  uint32_t exportDataSize;
172 };
173 
174 
187 gboolean
189  yfFlowKey_t *key,
190  const uint8_t *pkt,
191  size_t caplen,
192  uint16_t iplen,
193  yfTCPInfo_t *tcpinfo,
194  yfL2Info_t *l2info);
195 
208 void
210  yfFlow_t *flow,
211  yfFlowVal_t *val,
212  const uint8_t *pkt,
213  size_t caplen,
214  uint16_t iplen,
215  yfTCPInfo_t *tcpinfo,
216  yfL2Info_t *l2info);
217 
235 void
237  void **yfctx,
238  uint32_t max_payload,
239  gboolean uniflow,
240  gboolean silkmode,
241  gboolean applabelmode,
242  gboolean entropymode,
243  gboolean fingerprintmode,
244  gboolean fpExportMode,
245  gboolean udp_max_payload,
246  uint16_t udp_uniflow_port);
247 
255 gboolean
257  yfFlow_t *flow);
258 
270 void
272  yfFlow_t *flow,
273  void **yfctx);
274 
282 void
284  yfFlow_t *flow);
285 
292 fbInfoElement_t *
294  void);
295 
305 gboolean
307  fbSession_t *session);
308 
318 gboolean
320  fbSubTemplateMultiList_t *rec,
321  fbSubTemplateMultiListEntry_t *stml,
322  yfFlow_t *flow,
323  GError **err);
324 
338 gboolean
340  const char *hookName,
341  const char *hookOpts,
342  const char *hookConf,
343  void **yfctx,
344  GError **err);
345 
346 #if YAF_ENABLE_APPLABEL
347 
359 void
360 yfHookScanPayload(
361  yfFlow_t *flow,
362  const uint8_t *pkt,
363  size_t caplen,
364  pcre *expression,
365  uint16_t offset,
366  uint16_t elementID,
367  uint16_t applabel);
368 
369 #endif /* if YAF_ENABLE_APPLABEL */
370 
378 uint8_t
380  yfFlow_t *flow);
381 
388 void
390  yfFlow_t *flow);
391 
392 
393 /*
394  * The following are the prototypes of the functions that must be defined for
395  * a hook to be loaded into YAF. They are declared here to help ensure the
396  * hook uses the correct function signature.
397  */
398 
399 const struct yfHookMetaData *
400 ypGetMetaData(
401  void);
402 
403 gboolean
404 ypHookPacket(
405  yfFlowKey_t *key,
406  const uint8_t *pkt,
407  size_t caplen,
408  uint16_t iplen,
409  yfTCPInfo_t *tcpinfo,
410  yfL2Info_t *l2info);
411 
412 void
413 ypFlowPacket(
414  void *yfHookConext,
415  yfFlow_t *flow,
416  yfFlowVal_t *val,
417  const uint8_t *pkt,
418  size_t caplen,
419  uint16_t iplen,
420  yfTCPInfo_t *tcpinfo,
421  yfL2Info_t *l2info);
422 
423 gboolean
424 ypFlowClose(
425  void *yfHookConext,
426  yfFlow_t *flow);
427 
428 void
429 ypFlowAlloc(
430  void **yfHookConext,
431  yfFlow_t *flow,
432  void *yfctx);
433 
434 void
435 ypFlowFree(
436  void *yfHookConext,
437  yfFlow_t *flow);
438 
439 gboolean
440 ypFlowWrite(
441  void *yfHookConext,
442  fbSubTemplateMultiList_t *rec,
443  fbSubTemplateMultiListEntry_t *stml,
444  yfFlow_t *flow,
445  GError **err);
446 
447 fbInfoElement_t *
448 ypGetInfoModel(
449  void);
450 
451 gboolean
452 ypGetTemplate(
453  fbSession_t *session);
454 
455 void
456 ypSetPluginOpt(
457  const char *pluginOpt,
458  void *yfctx);
459 
460 void
461 ypSetPluginConf(
462  const char *pluginConf,
463  void **yfctx);
464 
465 #if YAF_ENABLE_APPLABEL
466 void
467 ypScanPayload(
468  void *yfHookConext,
469  yfFlow_t *flow,
470  const uint8_t *pkt,
471  size_t caplen,
472  pcre *expression,
473  uint16_t offset,
474  uint16_t elementID,
475  uint16_t applabel);
476 
477 #endif /* YAF_ENABLE_APPLABEL */
478 
479 gboolean
480 ypValidateFlowTab(
481  void *yfctx,
482  uint32_t max_payload,
483  gboolean uniflow,
484  gboolean silkmode,
485  gboolean applabelmode,
486  gboolean entropymode,
487  gboolean fingerprintmode,
488  gboolean fpExportMode,
489  gboolean udp_max_payload,
490  uint16_t udp_uniflow_port,
491  GError **err);
492 
493 uint8_t
494 ypGetTemplateCount(
495  void *yfHookConext,
496  yfFlow_t *flow);
497 
498 void
499 ypFreeLists(
500  void *yfHookConext,
501  yfFlow_t *flow);
502 
503 #endif /* _YAF_HOOKS_H_ */
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...
TCP information structure.
Definition: decode.h:140
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.
fbInfoElement_t * yfHookGetInfoModel(void)
Returns the IPFIX info model aggregated for all plugins.
A YAF uniflow value.
Definition: yafcore.h:276
A YAF flow key.
Definition: yafcore.h:208
uint8_t requireAppLabel
turn on application labeling related functions
Definition: yafhooks.h:171
uint8_t version
version of plugin interface
Definition: yafhooks.h:167
gboolean yfHookAddNewHook(const char *hookName, const char *hookOpts, const char *hookConf, void **yfctx, GError **err)
Adds another hook (plugin) into yaf.
gboolean yfHookFlowWrite(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
Exported from the plugin to tell YAF about its export data & interface version.
Definition: yafhooks.h:165
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.
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...
uint32_t exportDataSize
size of data plugin will export
Definition: yafhooks.h:169
Flow generation interface for YAF.
YAF Core Library.
uint8_t yfHookGetTemplateCount(yfFlow_t *flow)
Returns the amount of templates to add to the SubtemplateMultiList from all plugins hooked.
Datalink layer information structure.
Definition: decode.h:110
void yfHookFreeLists(yfFlow_t *flow)
Sends control back to the plugin to free any BasicLists, SubTemplateLists, or SubTemplateMultiLists t...
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.
void yfHookFlowFree(yfFlow_t *flow)
Frees all memory associated with the flow state in all of the attached plugins.
A YAF flow.
Definition: yafcore.h:371