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.15.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 * 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 * GOVERNMENT PURPOSE RIGHTS - Software and Software Documentation
34 * Contract No.: FA8702-15-D-0002
35 * Contractor Name: Carnegie Mellon University
36 * Contractor Address: 4500 Fifth Avenue, Pittsburgh, PA 15213
37 *
38 * The Government's rights to use, modify, reproduce, release, perform,
39 * display, or disclose this software are restricted by paragraph (b)(2) of
40 * the Rights in Noncommercial Computer Software and Noncommercial Computer
41 * Software Documentation clause contained in the above identified
42 * contract. No restrictions apply after the expiration date shown
43 * above. Any reproduction of the software or portions thereof marked with
44 * this legend must also reproduce the markings.
45 *
46 * This Software includes and/or makes use of Third-Party Software each
47 * subject to its own license.
48 *
49 * DM23-2313
50 * @DISTRIBUTION_STATEMENT_END@
51 * ------------------------------------------------------------------------
52 */
53
97/*
98 *
99 * Design notes:
100 *
101 * 1. For now, it is okay for the yfhook facility to only support a single
102 * hook.
103 *
104 * 5. Each hook needs to know when a flow is flushed, so that it can make the
105 * per-flow export fields available.
106 *
107 * Changes in Version 4:
108 *
109 * Added a function to pass a config file to the plugin from the command line.
110 *
111 * Changes in Version 3:
112 *
113 * Hooks export entire templates that will be added to Yaf's
114 * subTemplateMultiList.
115 * yfWriteFlow in yafcore.c will call ypGetTemplateCount (a function as of v.
116 * 3),
117 * which will return the number of templates Yaf should alloc in the STML.
118 * When
119 * yfHookWriteFlow is called the STML entry can be added. The hook should not
120 * add NULL entries, if no template is to be added, ypGetTemplateCount should
121 * return
122 * 0. If the STML entry contains list fields (BL's, STL's, STML's), it must
123 * free
124 * these in the call to ypFreeLists. This means that the hook must maintain
125 * access to the record so that it can free it.
126 * ypFreeList does NOT free Yaf's STML, yaf will free this after all the hook's
127 * lists have been freed.
128 *
129 * As of Version 3, ypGetTemplate will call fbTemplateAppendSpecArray and
130 * fbSessionAddTemplate. It does not need to internal templates, only
131 * external.
132 *
133 * ypGetInfoModel should no longer be used. ypGetTemplate should allocate the
134 * info model and add the elements to the info model & the template.
135 *
136 * Versions 2 or Below:
137 *
138 * Each hook needs to be able to hand YAF an export template for its fields.
139 * These fields will appear in every exported record; a facility for NULLs MUST
140 * be provided by the hook's representation.
141 *
142 */
143
144#ifndef _YAF_HOOKS_H_
145#define _YAF_HOOKS_H_
146
147#include <yaf/autoinc.h>
148#include <yaf/decode.h>
149#include <yaf/yafcore.h>
150#include <yaf/yaftab.h>
151#if YAF_ENABLE_APPLABEL
152#include <pcre.h>
153#endif
154
156#define YAF_HOOK_INTERFACE_VERSION 6
157
160struct yfHookMetaData {
162 uint8_t version;
164 uint32_t exportDataSize;
166 uint8_t requireAppLabel;
167};
168
169
182gboolean
183yfHookPacket(
184 yfFlowKey_t *key,
185 const uint8_t *pkt,
186 size_t caplen,
187 uint32_t iplen,
188 yfTCPInfo_t *tcpinfo,
189 yfL2Info_t *l2info);
190
203void
204yfHookFlowPacket(
205 yfFlow_t *flow,
206 yfFlowVal_t *val,
207 const uint8_t *pkt,
208 size_t caplen,
209 uint32_t iplen,
210 yfTCPInfo_t *tcpinfo,
211 yfL2Info_t *l2info);
212
230void
231yfHookValidateFlowTab(
232 void **yfctx,
233 uint32_t max_payload,
234 gboolean uniflow,
235 gboolean silkmode,
236 gboolean applabelmode,
237 gboolean entropymode,
238 gboolean fingerprintmode,
239 gboolean fpExportMode,
240 gboolean udp_max_payload,
241 uint16_t udp_uniflow_port);
242
250gboolean
251yfHookFlowClose(
252 yfFlow_t *flow);
253
265void
266yfHookFlowAlloc(
267 yfFlow_t *flow,
268 void **yfctx);
269
277void
278yfHookFlowFree(
279 yfFlow_t *flow);
280
287fbInfoElement_t *
288yfHookGetInfoModel(
289 void);
290
300gboolean
301yfHookGetTemplate(
302 fbSession_t *session);
303
313gboolean
314yfHookFlowWrite(
315 fbSubTemplateMultiList_t *rec,
316 fbSubTemplateMultiListEntry_t *stml,
317 yfFlow_t *flow,
318 GError **err);
319
333gboolean
334yfHookAddNewHook(
335 const char *hookName,
336 const char *hookOpts,
337 const char *hookConf,
338 void **yfctx,
339 GError **err);
340
341#if YAF_ENABLE_APPLABEL
354void
355yfHookScanPayload(
356 yfFlow_t *flow,
357 const uint8_t *pkt,
358 size_t caplen,
359 pcre *expression,
360 uint32_t offset,
361 uint16_t elementID,
362 uint16_t applabel);
363
364#endif /* if YAF_ENABLE_APPLABEL */
365
373uint8_t
374yfHookGetTemplateCount(
375 yfFlow_t *flow);
376
383void
384yfHookFreeLists(
385 yfFlow_t *flow);
386
387
388/*
389 * The following are the prototypes of the functions that must be defined for
390 * a hook to be loaded into YAF. They are declared here to help ensure the
391 * hook uses the correct function signature.
392 */
393
394const struct yfHookMetaData *
395ypGetMetaData(
396 void);
397
398gboolean
399ypHookPacket(
400 yfFlowKey_t *key,
401 const uint8_t *pkt,
402 size_t caplen,
403 uint32_t iplen,
404 yfTCPInfo_t *tcpinfo,
405 yfL2Info_t *l2info);
406
407void
408ypFlowPacket(
409 void *yfHookConext,
410 yfFlow_t *flow,
411 yfFlowVal_t *val,
412 const uint8_t *pkt,
413 size_t caplen,
414 uint32_t iplen,
415 yfTCPInfo_t *tcpinfo,
416 yfL2Info_t *l2info);
417
418gboolean
419ypFlowClose(
420 void *yfHookConext,
421 yfFlow_t *flow);
422
423void
424ypFlowAlloc(
425 void **yfHookConext,
426 yfFlow_t *flow,
427 void *yfctx);
428
429void
430ypFlowFree(
431 void *yfHookConext,
432 yfFlow_t *flow);
433
434gboolean
435ypFlowWrite(
436 void *yfHookConext,
437 fbSubTemplateMultiList_t *rec,
438 fbSubTemplateMultiListEntry_t *stml,
439 yfFlow_t *flow,
440 GError **err);
441
442fbInfoElement_t *
443ypGetInfoModel(
444 void);
445
446gboolean
447ypGetTemplate(
448 fbSession_t *session);
449
450void
451ypSetPluginOpt(
452 const char *pluginOpt,
453 void *yfctx);
454
455void
456ypSetPluginConf(
457 const char *pluginConf,
458 void **yfctx);
459
460#if YAF_ENABLE_APPLABEL
461void
462ypScanPayload(
463 void *yfHookConext,
464 yfFlow_t *flow,
465 const uint8_t *pkt,
466 size_t caplen,
467 pcre *expression,
468 uint32_t offset,
469 uint16_t elementID,
470 uint16_t applabel);
471
472#endif /* YAF_ENABLE_APPLABEL */
473
474gboolean
475ypValidateFlowTab(
476 void *yfctx,
477 uint32_t max_payload,
478 gboolean uniflow,
479 gboolean silkmode,
480 gboolean applabelmode,
481 gboolean entropymode,
482 gboolean fingerprintmode,
483 gboolean fpExportMode,
484 gboolean udp_max_payload,
485 uint16_t udp_uniflow_port,
486 GError **err);
487
488uint8_t
489ypGetTemplateCount(
490 void *yfHookConext,
491 yfFlow_t *flow);
492
493void
494ypFreeLists(
495 void *yfHookConext,
496 yfFlow_t *flow);
497
498#endif /* _YAF_HOOKS_H_ */
yfFlow_st
A YAF flow.
Definition yafcore.h:377
yfFlowKey_st
A YAF flow key.
Definition yafcore.h:212
yfFlowVal_st
A YAF uniflow value.
Definition yafcore.h:282
yfHookMetaData
Exported from the plugin to tell YAF about its export data & interface version.
Definition yafhooks.h:160
yfHookMetaData::version
uint8_t version
version of plugin interface
Definition yafhooks.h:162
yfHookMetaData::requireAppLabel
uint8_t requireAppLabel
turn on application labeling related functions
Definition yafhooks.h:166
yfHookMetaData::exportDataSize
uint32_t exportDataSize
size of data plugin will export
Definition yafhooks.h:164
yfL2Info_st
Datalink layer information structure.
Definition decode.h:106
yfTCPInfo_st
TCP information structure.
Definition decode.h:136
yafcore.h
YAF Core Library.
yfHookFlowFree
void yfHookFlowFree(yfFlow_t *flow)
Frees all memory associated with the flow state in all of the attached plugins.
yfHookFlowPacket
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.
yfHookFlowWrite
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
yfHookAddNewHook
gboolean yfHookAddNewHook(const char *hookName, const char *hookOpts, const char *hookConf, void **yfctx, GError **err)
Adds another hook (plugin) into yaf.
yfHookGetTemplate
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...
yfHookGetInfoModel
fbInfoElement_t * yfHookGetInfoModel(void)
Returns the IPFIX info model aggregated for all plugins.
yfHookGetTemplateCount
uint8_t yfHookGetTemplateCount(yfFlow_t *flow)
Returns the amount of templates to add to the SubtemplateMultiList from all plugins hooked.
yfHookPacket
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.
yfHookFreeLists
void yfHookFreeLists(yfFlow_t *flow)
Sends control back to the plugin to free any BasicLists, SubTemplateLists, or SubTemplateMultiLists t...
yfHookFlowClose
gboolean yfHookFlowClose(yfFlow_t *flow)
Called upon flow close to do any necessary plugin processing upon flow close.
yfHookFlowAlloc
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...
yfHookValidateFlowTab
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.
yaftab.h
Flow generation interface for YAF.