yafhooks.h

Go to the documentation of this file.

/*
 *  Copyright 2007-2026 Carnegie Mellon University
 *  See license information in LICENSE.txt.
 */
/*
 *  yafhooks.h
 *  YAF Active Flow Table Plugin Interface
 *
 *  ------------------------------------------------------------------------
 *  Authors: Brian Trammell
 *  ------------------------------------------------------------------------
 *  @DISTRIBUTION_STATEMENT_BEGIN@
 *  YAF 2.19
 *
 *  Copyright 2026 Carnegie Mellon University.
 *
 *  NO WARRANTY. THIS CARNEGIE MELLON UNIVERSITY AND SOFTWARE ENGINEERING
 *  INSTITUTE MATERIAL IS FURNISHED ON AN "AS-IS" BASIS. CARNEGIE MELLON
 *  UNIVERSITY MAKES NO WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
 *  AS TO ANY MATTER INCLUDING, BUT NOT LIMITED TO, WARRANTY OF FITNESS FOR
 *  PURPOSE OR MERCHANTABILITY, EXCLUSIVITY, OR RESULTS OBTAINED FROM USE OF
 *  THE MATERIAL. CARNEGIE MELLON UNIVERSITY DOES NOT MAKE ANY WARRANTY OF
 *  ANY KIND WITH RESPECT TO FREEDOM FROM PATENT, TRADEMARK, OR COPYRIGHT
 *  INFRINGEMENT.
 *
 *  Licensed under a GNU GPL 2.0-style license, please see LICENSE.txt or
 *  contact permission@sei.cmu.edu for full terms.
 *
 *  [DISTRIBUTION STATEMENT A] This material has been approved for public
 *  release and unlimited distribution.  Please see Copyright notice for
 *  non-US Government use and distribution.
 *
 *  This Software includes and/or makes use of Third-Party Software each
 *  subject to its own license.
 *
 *  DM26-0194
 *  @DISTRIBUTION_STATEMENT_END@
 *  ------------------------------------------------------------------------
 */

 
/*
 *
 * Design notes:
 *
 * 1. For now, it is okay for the yfhook facility to only support a single
 * hook.
 *
 * 5. Each hook needs to know when a flow is flushed, so that it can make the
 * per-flow export fields available.
 *
 * Changes in Version 7:
 *
 * ypGetTemplate() takes the hook's context as an argument.
 *
 * Changes in Version 6:
 *
 * Added ability for ypSetPluginConf() to create a hook-specific context, and
 * added that context as an argument to ypSetPluginOpt() and ypFlowAlloc().
 *
 * Changes in Version 5: ???
 *
 * Changes in Version 4:
 *
 * Added a function to pass a config file to the plugin from the command line.
 *
 * Changes in Version 3:
 *
 * Hooks export entire templates that will be added to Yaf's
 * subTemplateMultiList.
 * yfWriteFlow in yafcore.c will call ypGetTemplateCount (a function as of v.
 * 3),
 * which will return the number of templates Yaf should alloc in the STML.
 *  When
 * yfHookWriteFlow is called the STML entry can be added.  The hook should not
 * add NULL entries, if no template is to be added, ypGetTemplateCount should
 * return
 * 0.  If the STML entry contains list fields (BL's, STL's, STML's), it must
 * free
 * these in the call to ypFreeLists.  This means that the hook must maintain
 * access to the record so that it can free it.
 * ypFreeList does NOT free Yaf's STML, yaf will free this after all the hook's
 * lists have been freed.
 *
 * As of Version 3, ypGetTemplate will call fbTemplateAppendSpecArray and
 * fbSessionAddTemplate.  It does not need to internal templates, only
 * external.
 *
 * ypGetInfoModel should no longer be used.  ypGetTemplate should allocate the
 * info model and add the elements to the info model & the template.
 *
 * Versions 2 or Below:
 *
 * Each hook needs to be able to hand YAF an export template for its fields.
 * These fields will appear in every exported record; a facility for NULLs MUST
 * be provided by the hook's representation.
 *
 */
 
#ifndef _YAF_HOOKS_H_
#define _YAF_HOOKS_H_
 
#include <yaf/autoinc.h>
#include <yaf/decode.h>
#include <yaf/yafcore.h>
#include <yaf/yaftab.h>
#if YAF_ENABLE_APPLABEL
#define PCRE2_CODE_UNIT_WIDTH 8
#include <pcre2.h>
#endif

#define YAF_HOOK_INTERFACE_VERSION 7

struct yfHookMetaData {
    uint8_t    version;
    uint32_t   exportDataSize;
    uint8_t    requireAppLabel;
};
 

gboolean
yfHookPacket(
    yfFlowKey_t    *key,
    const uint8_t  *pkt,
    size_t          caplen,
    uint32_t        iplen,
    yfTCPInfo_t    *tcpinfo,
    yfL2Info_t     *l2info);

void
yfHookFlowPacket(
    yfFlow_t       *flow,
    yfFlowVal_t    *val,
    const uint8_t  *pkt,
    size_t          caplen,
    uint32_t        iplen,
    yfTCPInfo_t    *tcpinfo,
    yfL2Info_t     *l2info);

void
yfHookValidateFlowTab(
    void     **yfHookCtxArray,
    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);

gboolean
yfHookFlowClose(
    yfFlow_t  *flow);

void
yfHookFlowAlloc(
    yfFlow_t  *flow,
    void     **yfHookCtxArray);

void
yfHookFlowFree(
    yfFlow_t  *flow);

fbInfoElement_t *
yfHookGetInfoModel(
    void);

gboolean
yfHookGetTemplate(
    fbSession_t  *session,
    void        **yfHookCtxArray);

gboolean
yfHookFlowWrite(
    fbSubTemplateMultiList_t       *rec,
    fbSubTemplateMultiListEntry_t  *stml,
    yfFlow_t                       *flow,
    GError                        **err);

gboolean
yfHookAddNewHook(
    const char  *hookName,
    const char  *hookOpts,
    const char  *hookConf,
    void       **yfHookCtxArray,
    GError     **err);
 
#if YAF_ENABLE_APPLABEL
void
yfHookScanPayload(
    yfFlow_t       *flow,
    const uint8_t  *pkt,
    size_t          caplen,
    pcre2_code     *expression,
    uint32_t        offset,
    uint16_t        elementID,
    uint16_t        applabel);
 
#endif /* if YAF_ENABLE_APPLABEL */

uint8_t
yfHookGetTemplateCount(
    yfFlow_t  *flow);

void
yfHookFreeLists(
    yfFlow_t  *flow);
 
 
/*
 *  --------------------------------------------------------------------------
 *
 *  The following are the prototypes of the functions that must be defined for
 *  a hook to be loaded into YAF.  They are declared here to help ensure the
 *  hook uses the correct function signature.
 */

const struct yfHookMetaData *
ypGetMetaData(
    void);

gboolean
ypHookPacket(
    yfFlowKey_t    *key,
    const uint8_t  *pkt,
    size_t          caplen,
    uint32_t        iplen,
    yfTCPInfo_t    *tcpinfo,
    yfL2Info_t     *l2info);

void
ypFlowPacket(
    void           *yfHookFlowContext,
    yfFlow_t       *flow,
    yfFlowVal_t    *val,
    const uint8_t  *pkt,
    size_t          caplen,
    uint32_t        iplen,
    yfTCPInfo_t    *tcpinfo,
    yfL2Info_t     *l2info);

gboolean
ypFlowClose(
    void      *yfHookFlowContext,
    yfFlow_t  *flow);

void
ypFlowAlloc(
    void     **yfHookFlowContext,
    yfFlow_t  *flow,
    void      *yfHookCtx);

void
ypFlowFree(
    void      *yfHookFlowContext,
    yfFlow_t  *flow);

gboolean
ypFlowWrite(
    void                           *yfHookFlowContext,
    fbSubTemplateMultiList_t       *rec,
    fbSubTemplateMultiListEntry_t  *stml,
    yfFlow_t                       *flow,
    GError                        **err);

fbInfoElement_t *
ypGetInfoModel(
    void);

gboolean
ypGetTemplate(
    fbSession_t  *session,
    void         *yfHookCtx);

void
ypSetPluginOpt(
    const char  *pluginOpt,
    void        *yfHookCtx);

void
ypSetPluginConf(
    const char  *pluginConf,
    void       **yfHookCtx);
 
#if YAF_ENABLE_APPLABEL
void
ypScanPayload(
    void           *yfHookFlowContext,
    yfFlow_t       *flow,
    const uint8_t  *pkt,
    size_t          caplen,
    pcre2_code     *expression,
    uint32_t        offset,
    uint16_t        elementID,
    uint16_t        applabel);
 
#endif /* YAF_ENABLE_APPLABEL */

gboolean
ypValidateFlowTab(
    void      *yfHookCtx,
    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,
    GError   **err);

uint8_t
ypGetTemplateCount(
    void      *yfHookFlowContext,
    yfFlow_t  *flow);

void
ypFreeLists(
    void      *yfHookFlowContext,
    yfFlow_t  *flow);
 
#endif /* _YAF_HOOKS_H_ */