yafhooks.h
Go to the documentation of this file.
1/*
2 * Copyright 2007-2025 Carnegie Mellon University
3 * See license information in LICENSE.txt.
4 */
5/*
6 * yafhooks.h
7 * YAF Active Flow Table Plugin Interface
8 *
9 * ------------------------------------------------------------------------
10 * Authors: Brian Trammell
11 * ------------------------------------------------------------------------
12 * @DISTRIBUTION_STATEMENT_BEGIN@
13 * YAF 2.17
14 *
15 * Copyright 2025 Carnegie Mellon University.
16 *
17 * NO WARRANTY. THIS CARNEGIE MELLON UNIVERSITY AND SOFTWARE ENGINEERING
18 * INSTITUTE MATERIAL IS FURNISHED ON AN "AS-IS" BASIS. CARNEGIE MELLON
19 * UNIVERSITY MAKES NO WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
20 * AS TO ANY MATTER INCLUDING, BUT NOT LIMITED TO, WARRANTY OF FITNESS FOR
21 * PURPOSE OR MERCHANTABILITY, EXCLUSIVITY, OR RESULTS OBTAINED FROM USE OF
22 * THE MATERIAL. CARNEGIE MELLON UNIVERSITY DOES NOT MAKE ANY WARRANTY OF
23 * ANY KIND WITH RESPECT TO FREEDOM FROM PATENT, TRADEMARK, OR COPYRIGHT
24 * INFRINGEMENT.
25 *
26 * Licensed under a GNU GPL 2.0-style license, please see LICENSE.txt or
27 * contact permission@sei.cmu.edu for full terms.
28 *
29 * [DISTRIBUTION STATEMENT A] This material has been approved for public
30 * release and unlimited distribution. Please see Copyright notice for
31 * non-US Government use and distribution.
32 *
33 * This Software includes and/or makes use of Third-Party Software each
34 * subject to its own license.
35 *
36 * DM25-0934
37 * @DISTRIBUTION_STATEMENT_END@
38 * ------------------------------------------------------------------------
39 */
40
115/*
116 *
117 * Design notes:
118 *
119 * 1. For now, it is okay for the yfhook facility to only support a single
120 * hook.
121 *
122 * 5. Each hook needs to know when a flow is flushed, so that it can make the
123 * per-flow export fields available.
124 *
125 * Changes in Version 6:
126 *
127 * Added ability for ypSetPluginConf() to create a hook-specific context, and
128 * added that context as an argument to ypSetPluginOpt() and ypFlowAlloc().
129 *
130 * Changes in Version 5: ???
131 *
132 * Changes in Version 4:
133 *
134 * Added a function to pass a config file to the plugin from the command line.
135 *
136 * Changes in Version 3:
137 *
138 * Hooks export entire templates that will be added to Yaf's
139 * subTemplateMultiList.
140 * yfWriteFlow in yafcore.c will call ypGetTemplateCount (a function as of v.
141 * 3),
142 * which will return the number of templates Yaf should alloc in the STML.
143 * When
144 * yfHookWriteFlow is called the STML entry can be added. The hook should not
145 * add NULL entries, if no template is to be added, ypGetTemplateCount should
146 * return
147 * 0. If the STML entry contains list fields (BL's, STL's, STML's), it must
148 * free
149 * these in the call to ypFreeLists. This means that the hook must maintain
150 * access to the record so that it can free it.
151 * ypFreeList does NOT free Yaf's STML, yaf will free this after all the hook's
152 * lists have been freed.
153 *
154 * As of Version 3, ypGetTemplate will call fbTemplateAppendSpecArray and
155 * fbSessionAddTemplate. It does not need to internal templates, only
156 * external.
157 *
158 * ypGetInfoModel should no longer be used. ypGetTemplate should allocate the
159 * info model and add the elements to the info model & the template.
160 *
161 * Versions 2 or Below:
162 *
163 * Each hook needs to be able to hand YAF an export template for its fields.
164 * These fields will appear in every exported record; a facility for NULLs MUST
165 * be provided by the hook's representation.
166 *
167 */
168
169#ifndef _YAF_HOOKS_H_
170#define _YAF_HOOKS_H_
171
172#include <yaf/autoinc.h>
173#include <yaf/decode.h>
174#include <yaf/yafcore.h>
175#include <yaf/yaftab.h>
176#if YAF_ENABLE_APPLABEL
177#include <pcre.h>
178#endif
179
181#define YAF_HOOK_INTERFACE_VERSION 6
182
187 uint8_t version;
192};
193
194
207gboolean
209 yfFlowKey_t *key,
210 const uint8_t *pkt,
211 size_t caplen,
212 uint32_t iplen,
213 yfTCPInfo_t *tcpinfo,
214 yfL2Info_t *l2info);
215
228void
230 yfFlow_t *flow,
231 yfFlowVal_t *val,
232 const uint8_t *pkt,
233 size_t caplen,
234 uint32_t iplen,
235 yfTCPInfo_t *tcpinfo,
236 yfL2Info_t *l2info);
237
255void
257 void **yfctx,
258 uint32_t max_payload,
259 gboolean uniflow,
260 gboolean silkmode,
261 gboolean applabelmode,
262 gboolean entropymode,
263 gboolean fingerprintmode,
264 gboolean fpExportMode,
265 gboolean udp_multipkt_payload,
266 uint16_t udp_uniflow_port);
267
275gboolean
277 yfFlow_t *flow);
278
290void
292 yfFlow_t *flow,
293 void **yfctx);
294
302void
304 yfFlow_t *flow);
305
312fbInfoElement_t *
314 void);
315
325gboolean
327 fbSession_t *session);
328
338gboolean
340 fbSubTemplateMultiList_t *rec,
341 fbSubTemplateMultiListEntry_t *stml,
342 yfFlow_t *flow,
343 GError **err);
344
358gboolean
360 const char *hookName,
361 const char *hookOpts,
362 const char *hookConf,
363 void **yfctx,
364 GError **err);
365
366#if YAF_ENABLE_APPLABEL
379void
380yfHookScanPayload(
381 yfFlow_t *flow,
382 const uint8_t *pkt,
383 size_t caplen,
384 pcre *expression,
385 uint32_t offset,
386 uint16_t elementID,
387 uint16_t applabel);
388
389#endif /* if YAF_ENABLE_APPLABEL */
390
398uint8_t
400 yfFlow_t *flow);
401
408void
410 yfFlow_t *flow);
411
412
413/*
414 * The following are the prototypes of the functions that must be defined for
415 * a hook to be loaded into YAF. They are declared here to help ensure the
416 * hook uses the correct function signature.
417 */
418
419const struct yfHookMetaData *
420ypGetMetaData(
421 void);
422
423gboolean
424ypHookPacket(
425 yfFlowKey_t *key,
426 const uint8_t *pkt,
427 size_t caplen,
428 uint32_t iplen,
429 yfTCPInfo_t *tcpinfo,
430 yfL2Info_t *l2info);
431
432void
433ypFlowPacket(
434 void *yfHookConext,
435 yfFlow_t *flow,
436 yfFlowVal_t *val,
437 const uint8_t *pkt,
438 size_t caplen,
439 uint32_t iplen,
440 yfTCPInfo_t *tcpinfo,
441 yfL2Info_t *l2info);
442
443gboolean
444ypFlowClose(
445 void *yfHookConext,
446 yfFlow_t *flow);
447
448void
449ypFlowAlloc(
450 void **yfHookConext,
451 yfFlow_t *flow,
452 void *yfctx);
453
454void
455ypFlowFree(
456 void *yfHookConext,
457 yfFlow_t *flow);
458
459gboolean
460ypFlowWrite(
461 void *yfHookConext,
462 fbSubTemplateMultiList_t *rec,
463 fbSubTemplateMultiListEntry_t *stml,
464 yfFlow_t *flow,
465 GError **err);
466
467fbInfoElement_t *
468ypGetInfoModel(
469 void);
470
471gboolean
472ypGetTemplate(
473 fbSession_t *session);
474
475void
476ypSetPluginOpt(
477 const char *pluginOpt,
478 void *yfctx);
479
480void
481ypSetPluginConf(
482 const char *pluginConf,
483 void **yfctx);
484
485#if YAF_ENABLE_APPLABEL
486void
487ypScanPayload(
488 void *yfHookConext,
489 yfFlow_t *flow,
490 const uint8_t *pkt,
491 size_t caplen,
492 pcre *expression,
493 uint32_t offset,
494 uint16_t elementID,
495 uint16_t applabel);
496
497#endif /* YAF_ENABLE_APPLABEL */
498
499gboolean
500ypValidateFlowTab(
501 void *yfctx,
502 uint32_t max_payload,
503 gboolean uniflow,
504 gboolean silkmode,
505 gboolean applabelmode,
506 gboolean entropymode,
507 gboolean fingerprintmode,
508 gboolean fpExportMode,
509 gboolean udp_multipkt_payload,
510 uint16_t udp_uniflow_port,
511 GError **err);
512
513uint8_t
514ypGetTemplateCount(
515 void *yfHookConext,
516 yfFlow_t *flow);
517
518void
519ypFreeLists(
520 void *yfHookConext,
521 yfFlow_t *flow);
522
523#endif /* _YAF_HOOKS_H_ */
A YAF flow.
Definition yafcore.h:409
A YAF flow key.
Definition yafcore.h:244
A YAF uniflow value.
Definition yafcore.h:314
Exported from the plugin to tell YAF about its export data & interface version.
Definition yafhooks.h:185
uint8_t version
version of plugin interface
Definition yafhooks.h:187
uint8_t requireAppLabel
turn on application labeling related functions
Definition yafhooks.h:191
uint32_t exportDataSize
size of data plugin will export
Definition yafhooks.h:189
Datalink layer information structure.
Definition decode.h:93
TCP information structure.
Definition decode.h:123
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.
void yfHookValidateFlowTab(void **yfctx, uint32_t max_payload, gboolean uniflow, gboolean silkmode, gboolean applabelmode, gboolean entropymode, gboolean fingerprintmode, gboolean fpExportMode, gboolean udp_multipkt_payload, uint16_t udp_uniflow_port)
Validation function to make sure the plugin can and should operate based on the flowtable options.
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...
Flow generation interface for YAF.