00001 /* 00002 ** yafhooks.h 00003 ** YAF Active Flow Table Plugin Interface 00004 ** 00005 ** ------------------------------------------------------------------------ 00006 ** Copyright (C) 2007-2011 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 00098 /* 00099 00100 Design notes: 00101 00102 1. For now, it is okay for the yfhook facility to only support a single hook. 00103 00104 5. Each hook needs to know when a flow is flushed, so that it can make the 00105 per-flow export fields available. 00106 00107 Changes in Version 3: 00108 00109 Hooks export entire templates that will be added to Yaf's subTemplateMultiList. 00110 yfWriteFlow in yafcore.c will call ypGetTemplateCount (a function as of v. 3), 00111 which will return the number of templates Yaf should alloc in the STML. When 00112 yfHookWriteFlow is called the STML entry can be added. The hook should not 00113 add NULL entries, if no template is to be added, ypGetTemplateCount should return 00114 0. If the STML entry contains list fields (BL's, STL's, STML's), it must free 00115 these in the call to ypFreeLists. This means that the hook must maintain 00116 access to the record so that it can free it. 00117 ypFreeList does NOT free Yaf's STML, yaf will free this after all the hook's 00118 lists have been freed. 00119 00120 As of Version 3, ypGetTemplate will call fbTemplateAppendSpecArray and 00121 fbSessionAddTemplate. It does not need to internal templates, only external. 00122 00123 ypGetInfoModel should no longer be used. ypGetTemplate should allocate the 00124 info model and add the elements to the info model & the template. 00125 00126 Versions 2 or Below: 00127 00128 Each hook needs to be able to hand YAF an export template for its fields. 00129 These fields will appear in every exported record; a facility for NULLs MUST 00130 be provided by the hook's representation. 00131 00132 */ 00133 00134 #ifndef _YAF_HOOKS_H_ 00135 #define _YAF_HOOKS_H_ 00136 00137 #include <yaf/autoinc.h> 00138 #include <yaf/decode.h> 00139 #include <yaf/yafcore.h> 00140 #include <yaf/yaftab.h> 00141 #if YAF_ENABLE_APPLABEL 00142 #include <pcre.h> 00143 #endif 00144 00146 #define YAF_HOOK_INTERFACE_VERSION 3 00147 00149 struct yfHookMetaData { 00151 uint8_t version; 00153 uint32_t exportDataSize; 00155 uint8_t requireAppLabel; 00156 }; 00157 00158 00171 gboolean yfHookPacket ( 00172 yfFlowKey_t * key, 00173 const uint8_t * pkt, 00174 size_t caplen, 00175 uint16_t iplen, 00176 yfTCPInfo_t * tcpinfo, 00177 yfL2Info_t * l2info); 00178 00191 void yfHookFlowPacket ( 00192 yfFlow_t * flow, 00193 yfFlowVal_t * val, 00194 const uint8_t *pkt, 00195 size_t caplen, 00196 uint16_t iplen, 00197 yfTCPInfo_t * tcpinfo, 00198 yfL2Info_t * l2info); 00199 00214 void yfHookValidateFlowTab ( 00215 uint32_t max_payload, 00216 gboolean uniflow, 00217 gboolean silkmode, 00218 gboolean applabelmode, 00219 gboolean entropymode, 00220 gboolean fingerprintmode, 00221 gboolean fpExportMode, 00222 gboolean udp_max_payload, 00223 uint16_t udp_uniflow_port); 00224 00232 gboolean yfHookFlowClose ( 00233 yfFlow_t * flow); 00234 00244 void yfHookFlowAlloc ( 00245 yfFlow_t * flow); 00246 00254 void yfHookFlowFree ( 00255 yfFlow_t * flow); 00256 00263 fbInfoElement_t *yfHookGetInfoModel ( 00264 void); 00265 00275 gboolean yfHookGetTemplate ( 00276 fbSession_t *session); 00277 00287 gboolean yfWriteFlowHook ( 00288 fbSubTemplateMultiList_t *rec, 00289 fbSubTemplateMultiListEntry_t *stml, 00290 yfFlow_t * flow, 00291 GError ** err); 00292 00303 gboolean yfHookAddNewHook( 00304 const char *hookName, 00305 const char *hookOpts, 00306 GError ** err); 00307 00308 #if YAF_ENABLE_APPLABEL 00309 00321 void yfHookScanPayload ( 00322 yfFlow_t *flow, 00323 const uint8_t *pkt, 00324 size_t caplen, 00325 pcre *expression, 00326 uint16_t offset, 00327 uint16_t elementID, 00328 uint16_t applabel); 00329 00330 #endif 00331 00339 uint8_t yfHookGetTemplateCount( 00340 yfFlow_t *flow); 00341 00348 void yfHookFreeLists( 00349 yfFlow_t *flow); 00350 00351 #endif