Software Engineering Institute | Carnegie Mellon©
CERT NetSA Security Suite
Monitoring for Large-Scale Networks

YAF

Documentation

YAF

  • Documentation
  • Downloads
  • Main Page
  • Data Structures
  • Files
  • File List
  • Globals

yafhooks.h

Go to the documentation of this file.
00001 /*
00002  ** yafhooks.h
00003  ** YAF Active Flow Table Plugin Interface
00004  **
00005  ** ------------------------------------------------------------------------
00006  ** Copyright (C) 2007-2012 Carnegie Mellon University. All Rights Reserved.
00007  ** ------------------------------------------------------------------------
00008  ** Authors: Brian Trammell
00009  ** ------------------------------------------------------------------------
00010  ** @OPENSOURCE_HEADER_START@
00011  ** Use of the YAF system and related source code is subject to the terms
00012  ** of the following licenses:
00013  **
00014  ** GNU Public License (GPL) Rights pursuant to Version 2, June 1991
00015  ** Government Purpose License Rights (GPLR) pursuant to DFARS 252.227.7013
00016  **
00017  ** NO WARRANTY
00018  **
00019  ** ANY INFORMATION, MATERIALS, SERVICES, INTELLECTUAL PROPERTY OR OTHER
00020  ** PROPERTY OR RIGHTS GRANTED OR PROVIDED BY CARNEGIE MELLON UNIVERSITY
00021  ** PURSUANT TO THIS LICENSE (HEREINAFTER THE "DELIVERABLES") ARE ON AN
00022  ** "AS-IS" BASIS. CARNEGIE MELLON UNIVERSITY MAKES NO WARRANTIES OF ANY
00023  ** KIND, EITHER EXPRESS OR IMPLIED AS TO ANY MATTER INCLUDING, BUT NOT
00024  ** LIMITED TO, WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE,
00025  ** MERCHANTABILITY, INFORMATIONAL CONTENT, NONINFRINGEMENT, OR ERROR-FREE
00026  ** OPERATION. CARNEGIE MELLON UNIVERSITY SHALL NOT BE LIABLE FOR INDIRECT,
00027  ** SPECIAL OR CONSEQUENTIAL DAMAGES, SUCH AS LOSS OF PROFITS OR INABILITY
00028  ** TO USE SAID INTELLECTUAL PROPERTY, UNDER THIS LICENSE, REGARDLESS OF
00029  ** WHETHER SUCH PARTY WAS AWARE OF THE POSSIBILITY OF SUCH DAMAGES.
00030  ** LICENSEE AGREES THAT IT WILL NOT MAKE ANY WARRANTY ON BEHALF OF
00031  ** CARNEGIE MELLON UNIVERSITY, EXPRESS OR IMPLIED, TO ANY PERSON
00032  ** CONCERNING THE APPLICATION OF OR THE RESULTS TO BE OBTAINED WITH THE
00033  ** DELIVERABLES UNDER THIS LICENSE.
00034  **
00035  ** Licensee hereby agrees to defend, indemnify, and hold harmless Carnegie
00036  ** Mellon University, its trustees, officers, employees, and agents from
00037  ** all claims or demands made against them (and any related losses,
00038  ** expenses, or attorney's fees) arising out of, or relating to Licensee's
00039  ** and/or its sub licensees' negligent use or willful misuse of or
00040  ** negligent conduct or willful misconduct regarding the Software,
00041  ** facilities, or other rights or assistance granted by Carnegie Mellon
00042  ** University under this License, including, but not limited to, any
00043  ** claims of product liability, personal injury, death, damage to
00044  ** property, or violation of any laws or regulations.
00045  **
00046  ** Carnegie Mellon University Software Engineering Institute authored
00047  ** documents are sponsored by the U.S. Department of Defense under
00048  ** Contract FA8721-05-C-0003. Carnegie Mellon University retains
00049  ** copyrights in all material produced under this contract. The U.S.
00050  ** Government retains a non-exclusive, royalty-free license to publish or
00051  ** reproduce these documents, or allow others to do so, for U.S.
00052  ** Government purposes only pursuant to the copyright license under the
00053  ** contract clause at 252.227.7013.
00054  **
00055  ** @OPENSOURCE_HEADER_END@
00056  ** ------------------------------------------------------------------------
00057  */
00058 
00100 /*
00101 
00102 Design notes:
00103 
00104 1. For now, it is okay for the yfhook facility to only support a single hook.
00105 
00106 5. Each hook needs to know when a flow is flushed, so that it can make the
00107 per-flow export fields available.
00108 
00109 Changes in Version 4:
00110 
00111 Added a function to pass a config file to the plugin from the command line.
00112 
00113 Changes in Version 3:
00114 
00115 Hooks export entire templates that will be added to Yaf's subTemplateMultiList.
00116 yfWriteFlow in yafcore.c will call ypGetTemplateCount (a function as of v. 3),
00117 which will return the number of templates Yaf should alloc in the STML.  When
00118 yfHookWriteFlow is called the STML entry can be added.  The hook should not
00119 add NULL entries, if no template is to be added, ypGetTemplateCount should return
00120 0.  If the STML entry contains list fields (BL's, STL's, STML's), it must free
00121 these in the call to ypFreeLists.  This means that the hook must maintain
00122 access to the record so that it can free it.
00123 ypFreeList does NOT free Yaf's STML, yaf will free this after all the hook's
00124 lists have been freed.
00125 
00126 As of Version 3, ypGetTemplate will call fbTemplateAppendSpecArray and
00127 fbSessionAddTemplate.  It does not need to internal templates, only external.
00128 
00129 ypGetInfoModel should no longer be used.  ypGetTemplate should allocate the
00130 info model and add the elements to the info model & the template.
00131 
00132 Versions 2 or Below:
00133 
00134 Each hook needs to be able to hand YAF an export template for its fields.
00135 These fields will appear in every exported record; a facility for NULLs MUST
00136 be provided by the hook's representation.
00137 
00138 */
00139 
00140 #ifndef _YAF_HOOKS_H_
00141 #define _YAF_HOOKS_H_
00142 
00143 #include <yaf/autoinc.h>
00144 #include <yaf/decode.h>
00145 #include <yaf/yafcore.h>
00146 #include <yaf/yaftab.h>
00147 #if YAF_ENABLE_APPLABEL
00148 #include <pcre.h>
00149 #endif
00150 
00152 #define YAF_HOOK_INTERFACE_VERSION 4
00153 
00155 struct yfHookMetaData {
00157     uint8_t version;
00159     uint32_t exportDataSize;
00161     uint8_t requireAppLabel;
00162 };
00163 
00164 
00177 gboolean            yfHookPacket (
00178     yfFlowKey_t * key,
00179     const uint8_t * pkt,
00180     size_t caplen,
00181     uint16_t iplen,
00182     yfTCPInfo_t * tcpinfo,
00183     yfL2Info_t * l2info);
00184 
00197 void                yfHookFlowPacket (
00198     yfFlow_t * flow,
00199     yfFlowVal_t * val,
00200     const uint8_t *pkt,
00201     size_t caplen,
00202     uint16_t iplen,
00203     yfTCPInfo_t * tcpinfo,
00204     yfL2Info_t * l2info);
00205 
00220 void                yfHookValidateFlowTab (
00221     uint32_t        max_payload,
00222     gboolean        uniflow,
00223     gboolean        silkmode,
00224     gboolean        applabelmode,
00225     gboolean        entropymode,
00226     gboolean        fingerprintmode,
00227     gboolean        fpExportMode,
00228     gboolean        udp_max_payload,
00229     uint16_t        udp_uniflow_port);
00230 
00238 gboolean            yfHookFlowClose (
00239     yfFlow_t * flow);
00240 
00250 void                yfHookFlowAlloc (
00251     yfFlow_t * flow);
00252 
00260 void                yfHookFlowFree (
00261     yfFlow_t * flow);
00262 
00269 fbInfoElement_t    *yfHookGetInfoModel (
00270     void);
00271 
00281 gboolean yfHookGetTemplate (
00282     fbSession_t *session);
00283 
00293 gboolean            yfWriteFlowHook (
00294     fbSubTemplateMultiList_t *rec,
00295     fbSubTemplateMultiListEntry_t *stml,
00296     yfFlow_t * flow,
00297     GError ** err);
00298 
00310 gboolean yfHookAddNewHook(
00311     const char *hookName,
00312     const char *hookOpts,
00313     const char *hookConf,
00314     GError ** err);
00315 
00316 #if YAF_ENABLE_APPLABEL
00317 
00329 void yfHookScanPayload (
00330         yfFlow_t *flow,
00331         const uint8_t *pkt,
00332         size_t caplen,
00333         pcre *expression,
00334         uint16_t offset,
00335         uint16_t elementID,
00336         uint16_t applabel);
00337 
00338 #endif
00339 
00347 uint8_t yfHookGetTemplateCount(
00348     yfFlow_t *flow);
00349 
00356 void yfHookFreeLists(
00357     yfFlow_t *flow);
00358 
00359 #endif
© 2006-2012 Carnegie Mellon University