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-2023 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;
172};
173
174
187gboolean
189 yfFlowKey_t *key,
190 const uint8_t *pkt,
191 size_t caplen,
192 uint32_t iplen,
193 yfTCPInfo_t *tcpinfo,
194 yfL2Info_t *l2info);
195
208void
210 yfFlow_t *flow,
211 yfFlowVal_t *val,
212 const uint8_t *pkt,
213 size_t caplen,
214 uint32_t iplen,
215 yfTCPInfo_t *tcpinfo,
216 yfL2Info_t *l2info);
217
235void
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
255gboolean
257 yfFlow_t *flow);
258
270void
272 yfFlow_t *flow,
273 void **yfctx);
274
282void
284 yfFlow_t *flow);
285
292fbInfoElement_t *
294 void);
295
305gboolean
307 fbSession_t *session);
308
318gboolean
320 fbSubTemplateMultiList_t *rec,
321 fbSubTemplateMultiListEntry_t *stml,
322 yfFlow_t *flow,
323 GError **err);
324
338gboolean
340 const char *hookName,
341 const char *hookOpts,
342 const char *hookConf,
343 void **yfctx,
344 GError **err);
345
346#if YAF_ENABLE_APPLABEL
359void
360yfHookScanPayload(
361 yfFlow_t *flow,
362 const uint8_t *pkt,
363 size_t caplen,
364 pcre *expression,
365 uint32_t offset,
366 uint16_t elementID,
367 uint16_t applabel);
368
369#endif /* if YAF_ENABLE_APPLABEL */
370
378uint8_t
380 yfFlow_t *flow);
381
388void
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
399const struct yfHookMetaData *
400ypGetMetaData(
401 void);
402
403gboolean
404ypHookPacket(
405 yfFlowKey_t *key,
406 const uint8_t *pkt,
407 size_t caplen,
408 uint32_t iplen,
409 yfTCPInfo_t *tcpinfo,
410 yfL2Info_t *l2info);
411
412void
413ypFlowPacket(
414 void *yfHookConext,
415 yfFlow_t *flow,
416 yfFlowVal_t *val,
417 const uint8_t *pkt,
418 size_t caplen,
419 uint32_t iplen,
420 yfTCPInfo_t *tcpinfo,
421 yfL2Info_t *l2info);
422
423gboolean
424ypFlowClose(
425 void *yfHookConext,
426 yfFlow_t *flow);
427
428void
429ypFlowAlloc(
430 void **yfHookConext,
431 yfFlow_t *flow,
432 void *yfctx);
433
434void
435ypFlowFree(
436 void *yfHookConext,
437 yfFlow_t *flow);
438
439gboolean
440ypFlowWrite(
441 void *yfHookConext,
442 fbSubTemplateMultiList_t *rec,
443 fbSubTemplateMultiListEntry_t *stml,
444 yfFlow_t *flow,
445 GError **err);
446
447fbInfoElement_t *
448ypGetInfoModel(
449 void);
450
451gboolean
452ypGetTemplate(
453 fbSession_t *session);
454
455void
456ypSetPluginOpt(
457 const char *pluginOpt,
458 void *yfctx);
459
460void
461ypSetPluginConf(
462 const char *pluginConf,
463 void **yfctx);
464
465#if YAF_ENABLE_APPLABEL
466void
467ypScanPayload(
468 void *yfHookConext,
469 yfFlow_t *flow,
470 const uint8_t *pkt,
471 size_t caplen,
472 pcre *expression,
473 uint32_t offset,
474 uint16_t elementID,
475 uint16_t applabel);
476
477#endif /* YAF_ENABLE_APPLABEL */
478
479gboolean
480ypValidateFlowTab(
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
493uint8_t
494ypGetTemplateCount(
495 void *yfHookConext,
496 yfFlow_t *flow);
497
498void
499ypFreeLists(
500 void *yfHookConext,
501 yfFlow_t *flow);
502
503#endif /* _YAF_HOOKS_H_ */
A YAF flow.
Definition: yafcore.h:371
A YAF flow key.
Definition: yafcore.h:208
A YAF uniflow value.
Definition: yafcore.h:276
Exported from the plugin to tell YAF about its export data & interface version.
Definition: yafhooks.h:165
uint8_t version
version of plugin interface
Definition: yafhooks.h:167
uint8_t requireAppLabel
turn on application labeling related functions
Definition: yafhooks.h:171
uint32_t exportDataSize
size of data plugin will export
Definition: yafhooks.h:169
Datalink layer information structure.
Definition: decode.h:110
TCP information structure.
Definition: decode.h:140
YAF Core Library.
void yfHookFlowFree(yfFlow_t *flow)
Frees all memory associated with the flow state in all of the attached plugins.
void yfHookFlowPacket(yfFlow_t *flow, yfFlowVal_t *val, const uint8_t *pkt, size_t caplen, uint32_t iplen, yfTCPInfo_t *tcpinfo, yfL2Info_t *l2info)
Similar to yfHookPacket but also given yfFlowVal_t struct for processing per flow direction.
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
gboolean yfHookAddNewHook(const char *hookName, const char *hookOpts, const char *hookConf, void **yfctx, GError **err)
Adds another hook (plugin) into yaf.
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...
fbInfoElement_t * yfHookGetInfoModel(void)
Returns the IPFIX info model aggregated for all plugins.
uint8_t yfHookGetTemplateCount(yfFlow_t *flow)
Returns the amount of templates to add to the SubtemplateMultiList from all plugins hooked.
gboolean yfHookPacket(yfFlowKey_t *key, const uint8_t *pkt, size_t caplen, uint32_t iplen, yfTCPInfo_t *tcpinfo, yfL2Info_t *l2info)
Function called to do processing on each packet as it comes in.
void yfHookFreeLists(yfFlow_t *flow)
Sends control back to the plugin to free any BasicLists, SubTemplateLists, or SubTemplateMultiLists t...
gboolean yfHookFlowClose(yfFlow_t *flow)
Called upon flow close to do any necessary plugin processing upon flow close.
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...
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.
Flow generation interface for YAF.