yafhooks.h
Go to the documentation of this file.
1/*
2 * Copyright 2007-2023 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.14.0
14 *
15 * Copyright 2023 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 * Released 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 * GOVERNMENT PURPOSE RIGHTS - Software and Software Documentation
34 *
35 * Contract No.: FA8702-15-D-0002
36 *
37 * Contractor Name: Carnegie Mellon University
38 *
39 * Contractor Address: 4500 Fifth Avenue, Pittsburgh, PA 15213
40 *
41 * The Government's rights to use, modify, reproduce, release, perform,
42 * display, or disclose this software are restricted by paragraph (b)(2) of
43 * the Rights in Noncommercial Computer Software and Noncommercial Computer
44 * Software Documentation clause contained in the above identified
45 * contract. No restrictions apply after the expiration date shown
46 * above. Any reproduction of the software or portions thereof marked with
47 * this legend must also reproduce the markings.
48 *
49 * Carnegie Mellon(R) and CERT(R) are registered in the U.S. Patent and
50 * Trademark Office by Carnegie Mellon University.
51 *
52 * This Software includes and/or makes use of Third-Party Software each
53 * subject to its own license.
54 *
55 * DM23-0544
56 * @DISTRIBUTION_STATEMENT_END@
57 * ------------------------------------------------------------------------
58 */
59
103/*
104 *
105 * Design notes:
106 *
107 * 1. For now, it is okay for the yfhook facility to only support a single
108 * hook.
109 *
110 * 5. Each hook needs to know when a flow is flushed, so that it can make the
111 * per-flow export fields available.
112 *
113 * Changes in Version 4:
114 *
115 * Added a function to pass a config file to the plugin from the command line.
116 *
117 * Changes in Version 3:
118 *
119 * Hooks export entire templates that will be added to Yaf's
120 * subTemplateMultiList.
121 * yfWriteFlow in yafcore.c will call ypGetTemplateCount (a function as of v.
122 * 3),
123 * which will return the number of templates Yaf should alloc in the STML.
124 * When
125 * yfHookWriteFlow is called the STML entry can be added. The hook should not
126 * add NULL entries, if no template is to be added, ypGetTemplateCount should
127 * return
128 * 0. If the STML entry contains list fields (BL's, STL's, STML's), it must
129 * free
130 * these in the call to ypFreeLists. This means that the hook must maintain
131 * access to the record so that it can free it.
132 * ypFreeList does NOT free Yaf's STML, yaf will free this after all the hook's
133 * lists have been freed.
134 *
135 * As of Version 3, ypGetTemplate will call fbTemplateAppendSpecArray and
136 * fbSessionAddTemplate. It does not need to internal templates, only
137 * external.
138 *
139 * ypGetInfoModel should no longer be used. ypGetTemplate should allocate the
140 * info model and add the elements to the info model & the template.
141 *
142 * Versions 2 or Below:
143 *
144 * Each hook needs to be able to hand YAF an export template for its fields.
145 * These fields will appear in every exported record; a facility for NULLs MUST
146 * be provided by the hook's representation.
147 *
148 */
149
150#ifndef _YAF_HOOKS_H_
151#define _YAF_HOOKS_H_
152
153#include <yaf/autoinc.h>
154#include <yaf/decode.h>
155#include <yaf/yafcore.h>
156#include <yaf/yaftab.h>
157#if YAF_ENABLE_APPLABEL
158#include <pcre.h>
159#endif
160
162#define YAF_HOOK_INTERFACE_VERSION 6
163
168 uint8_t version;
173};
174
175
188gboolean
190 yfFlowKey_t *key,
191 const uint8_t *pkt,
192 size_t caplen,
193 uint32_t iplen,
194 yfTCPInfo_t *tcpinfo,
195 yfL2Info_t *l2info);
196
209void
211 yfFlow_t *flow,
212 yfFlowVal_t *val,
213 const uint8_t *pkt,
214 size_t caplen,
215 uint32_t iplen,
216 yfTCPInfo_t *tcpinfo,
217 yfL2Info_t *l2info);
218
236void
238 void **yfctx,
239 uint32_t max_payload,
240 gboolean uniflow,
241 gboolean silkmode,
242 gboolean applabelmode,
243 gboolean entropymode,
244 gboolean fingerprintmode,
245 gboolean fpExportMode,
246 gboolean udp_max_payload,
247 uint16_t udp_uniflow_port);
248
256gboolean
258 yfFlow_t *flow);
259
271void
273 yfFlow_t *flow,
274 void **yfctx);
275
283void
285 yfFlow_t *flow);
286
293fbInfoElement_t *
295 void);
296
306gboolean
308 fbSession_t *session);
309
319gboolean
321 fbSubTemplateMultiList_t *rec,
322 fbSubTemplateMultiListEntry_t *stml,
323 yfFlow_t *flow,
324 GError **err);
325
339gboolean
341 const char *hookName,
342 const char *hookOpts,
343 const char *hookConf,
344 void **yfctx,
345 GError **err);
346
347#if YAF_ENABLE_APPLABEL
360void
361yfHookScanPayload(
362 yfFlow_t *flow,
363 const uint8_t *pkt,
364 size_t caplen,
365 pcre *expression,
366 uint32_t offset,
367 uint16_t elementID,
368 uint16_t applabel);
369
370#endif /* if YAF_ENABLE_APPLABEL */
371
379uint8_t
381 yfFlow_t *flow);
382
389void
391 yfFlow_t *flow);
392
393
394/*
395 * The following are the prototypes of the functions that must be defined for
396 * a hook to be loaded into YAF. They are declared here to help ensure the
397 * hook uses the correct function signature.
398 */
399
400const struct yfHookMetaData *
401ypGetMetaData(
402 void);
403
404gboolean
405ypHookPacket(
406 yfFlowKey_t *key,
407 const uint8_t *pkt,
408 size_t caplen,
409 uint32_t iplen,
410 yfTCPInfo_t *tcpinfo,
411 yfL2Info_t *l2info);
412
413void
414ypFlowPacket(
415 void *yfHookConext,
416 yfFlow_t *flow,
417 yfFlowVal_t *val,
418 const uint8_t *pkt,
419 size_t caplen,
420 uint32_t iplen,
421 yfTCPInfo_t *tcpinfo,
422 yfL2Info_t *l2info);
423
424gboolean
425ypFlowClose(
426 void *yfHookConext,
427 yfFlow_t *flow);
428
429void
430ypFlowAlloc(
431 void **yfHookConext,
432 yfFlow_t *flow,
433 void *yfctx);
434
435void
436ypFlowFree(
437 void *yfHookConext,
438 yfFlow_t *flow);
439
440gboolean
441ypFlowWrite(
442 void *yfHookConext,
443 fbSubTemplateMultiList_t *rec,
444 fbSubTemplateMultiListEntry_t *stml,
445 yfFlow_t *flow,
446 GError **err);
447
448fbInfoElement_t *
449ypGetInfoModel(
450 void);
451
452gboolean
453ypGetTemplate(
454 fbSession_t *session);
455
456void
457ypSetPluginOpt(
458 const char *pluginOpt,
459 void *yfctx);
460
461void
462ypSetPluginConf(
463 const char *pluginConf,
464 void **yfctx);
465
466#if YAF_ENABLE_APPLABEL
467void
468ypScanPayload(
469 void *yfHookConext,
470 yfFlow_t *flow,
471 const uint8_t *pkt,
472 size_t caplen,
473 pcre *expression,
474 uint32_t offset,
475 uint16_t elementID,
476 uint16_t applabel);
477
478#endif /* YAF_ENABLE_APPLABEL */
479
480gboolean
481ypValidateFlowTab(
482 void *yfctx,
483 uint32_t max_payload,
484 gboolean uniflow,
485 gboolean silkmode,
486 gboolean applabelmode,
487 gboolean entropymode,
488 gboolean fingerprintmode,
489 gboolean fpExportMode,
490 gboolean udp_max_payload,
491 uint16_t udp_uniflow_port,
492 GError **err);
493
494uint8_t
495ypGetTemplateCount(
496 void *yfHookConext,
497 yfFlow_t *flow);
498
499void
500ypFreeLists(
501 void *yfHookConext,
502 yfFlow_t *flow);
503
504#endif /* _YAF_HOOKS_H_ */
A YAF flow.
Definition: yafcore.h:374
A YAF flow key.
Definition: yafcore.h:211
A YAF uniflow value.
Definition: yafcore.h:279
Exported from the plugin to tell YAF about its export data & interface version.
Definition: yafhooks.h:166
uint8_t version
version of plugin interface
Definition: yafhooks.h:168
uint8_t requireAppLabel
turn on application labeling related functions
Definition: yafhooks.h:172
uint32_t exportDataSize
size of data plugin will export
Definition: yafhooks.h:170
Datalink layer information structure.
Definition: decode.h:112
TCP information structure.
Definition: decode.h:142
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.