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