1 /* 2 ** yafhooks.h 3 ** YAF Active Flow Table Plugin Interface 4 ** 5 ** ------------------------------------------------------------------------ 6 ** Copyright (C) 2007-2015 Carnegie Mellon University. All Rights Reserved. 7 ** ------------------------------------------------------------------------ 8 ** Authors: Brian Trammell 9 ** ------------------------------------------------------------------------ 10 ** @OPENSOURCE_HEADER_START@ 11 ** Use of the YAF system and related source code is subject to the terms 12 ** of the following licenses: 13 ** 14 ** GNU Public License (GPL) Rights pursuant to Version 2, June 1991 15 ** Government Purpose License Rights (GPLR) pursuant to DFARS 252.227.7013 16 ** 17 ** NO WARRANTY 18 ** 19 ** ANY INFORMATION, MATERIALS, SERVICES, INTELLECTUAL PROPERTY OR OTHER 20 ** PROPERTY OR RIGHTS GRANTED OR PROVIDED BY CARNEGIE MELLON UNIVERSITY 21 ** PURSUANT TO THIS LICENSE (HEREINAFTER THE "DELIVERABLES") ARE ON AN 22 ** "AS-IS" BASIS. CARNEGIE MELLON UNIVERSITY MAKES NO WARRANTIES OF ANY 23 ** KIND, EITHER EXPRESS OR IMPLIED AS TO ANY MATTER INCLUDING, BUT NOT 24 ** LIMITED TO, WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE, 25 ** MERCHANTABILITY, INFORMATIONAL CONTENT, NONINFRINGEMENT, OR ERROR-FREE 26 ** OPERATION. CARNEGIE MELLON UNIVERSITY SHALL NOT BE LIABLE FOR INDIRECT, 27 ** SPECIAL OR CONSEQUENTIAL DAMAGES, SUCH AS LOSS OF PROFITS OR INABILITY 28 ** TO USE SAID INTELLECTUAL PROPERTY, UNDER THIS LICENSE, REGARDLESS OF 29 ** WHETHER SUCH PARTY WAS AWARE OF THE POSSIBILITY OF SUCH DAMAGES. 30 ** LICENSEE AGREES THAT IT WILL NOT MAKE ANY WARRANTY ON BEHALF OF 31 ** CARNEGIE MELLON UNIVERSITY, EXPRESS OR IMPLIED, TO ANY PERSON 32 ** CONCERNING THE APPLICATION OF OR THE RESULTS TO BE OBTAINED WITH THE 33 ** DELIVERABLES UNDER THIS LICENSE. 34 ** 35 ** Licensee hereby agrees to defend, indemnify, and hold harmless Carnegie 36 ** Mellon University, its trustees, officers, employees, and agents from 37 ** all claims or demands made against them (and any related losses, 38 ** expenses, or attorney's fees) arising out of, or relating to Licensee's 39 ** and/or its sub licensees' negligent use or willful misuse of or 40 ** negligent conduct or willful misconduct regarding the Software, 41 ** facilities, or other rights or assistance granted by Carnegie Mellon 42 ** University under this License, including, but not limited to, any 43 ** claims of product liability, personal injury, death, damage to 44 ** property, or violation of any laws or regulations. 45 ** 46 ** Carnegie Mellon University Software Engineering Institute authored 47 ** documents are sponsored by the U.S. Department of Defense under 48 ** Contract FA8721-05-C-0003. Carnegie Mellon University retains 49 ** copyrights in all material produced under this contract. The U.S. 50 ** Government retains a non-exclusive, royalty-free license to publish or 51 ** reproduce these documents, or allow others to do so, for U.S. 52 ** Government purposes only pursuant to the copyright license under the 53 ** contract clause at 252.227.7013. 54 ** 55 ** @OPENSOURCE_HEADER_END@ 56 ** ------------------------------------------------------------------------ 57 */ 58 59 /** 60 * @file 61 * 62 * Processing hook interface for YAF. 63 * 64 * VERSION 3 - REQUIRES FIXBUF 1.0 65 * 66 * The plugin must implement all of the following functions: 67 * 68 * ypGetMetaData - returns the version, max export bytes, applabel enabled 69 * 70 * ypHookPacket - called by yfFlowPBuf() 71 * 72 * ypFlowPacket - called by yfFlowPBuf() and yfAppLabelFlow() 73 * when called by yfAppLabelFlow - the last 3 parameters are 0 74 * 75 * ypFlowClose - called by yfFlowClose() 76 * 77 * ypFlowAlloc - called by yfFlowGetNode() 78 * 79 * ypFlowFree - called by yfFlowFree() 80 * 81 * ypGetInfoModel - called by yfInfoModel() - this should not be used for v.3 82 * 83 * ypGetTemplate - called by yfInitExporterSession() 84 * 85 * ypSetPluginOpt - called by yfHookAddNewHook() 86 * 87 * ypSetPluginConf - called by yfHookAddNewHook() 88 * 89 * ypScanPayload - if Application labeling is enabled, called by app plugins 90 * 91 * ypValidateFlowTab - called by yfFlowTabAlloc() 92 * 93 * ypGetTemplateCount - called by yfWriteFlow() 94 * 95 * ypFreeLists - called by yfWriteFlow() 96 * 97 * 98 */ 99 100 /* 101 102 Design notes: 103 104 1. For now, it is okay for the yfhook facility to only support a single hook. 105 106 5. Each hook needs to know when a flow is flushed, so that it can make the 107 per-flow export fields available. 108 109 Changes in Version 4: 110 111 Added a function to pass a config file to the plugin from the command line. 112 113 Changes in Version 3: 114 115 Hooks export entire templates that will be added to Yaf's subTemplateMultiList. 116 yfWriteFlow in yafcore.c will call ypGetTemplateCount (a function as of v. 3), 117 which will return the number of templates Yaf should alloc in the STML. When 118 yfHookWriteFlow is called the STML entry can be added. The hook should not 119 add NULL entries, if no template is to be added, ypGetTemplateCount should return 120 0. If the STML entry contains list fields (BL's, STL's, STML's), it must free 121 these in the call to ypFreeLists. This means that the hook must maintain 122 access to the record so that it can free it. 123 ypFreeList does NOT free Yaf's STML, yaf will free this after all the hook's 124 lists have been freed. 125 126 As of Version 3, ypGetTemplate will call fbTemplateAppendSpecArray and 127 fbSessionAddTemplate. It does not need to internal templates, only external. 128 129 ypGetInfoModel should no longer be used. ypGetTemplate should allocate the 130 info model and add the elements to the info model & the template. 131 132 Versions 2 or Below: 133 134 Each hook needs to be able to hand YAF an export template for its fields. 135 These fields will appear in every exported record; a facility for NULLs MUST 136 be provided by the hook's representation. 137 138 */ 139 140 #ifndef _YAF_HOOKS_H_ 141 #define _YAF_HOOKS_H_ 142 143 #include <yaf/autoinc.h> 144 #include <yaf/decode.h> 145 #include <yaf/yafcore.h> 146 #include <yaf/yaftab.h> 147 #if YAF_ENABLE_APPLABEL 148 #include <pcre.h> 149 #endif 150 151 /** HOOKS Plugin Version */ 152 #define YAF_HOOK_INTERFACE_VERSION 6 153 154 /** Exported from the plugin to tell YAF about its export data & interface version */ 155 struct yfHookMetaData { 156 /** version of plugin interface */ 157 uint8_t version; 158 /** size of data plugin will export */ 159 uint32_t exportDataSize; 160 /** turn on application labeling related functions */ 161 uint8_t requireAppLabel; 162 }; 163 164 165 /** 166 * Function called to do processing on each packet as it comes in 167 * 168 * @param key pointer to flowkey 169 * @param pkt pointer to pkt data 170 * @param caplen size of pkt data 171 * @param iplen 172 * @param tcpinfo 173 * @param l2info 174 * @return TRUE if pkt processing should continue, FALSE if not 175 * 176 */ 177 gboolean yfHookPacket ( 178 yfFlowKey_t * key, 179 const uint8_t * pkt, 180 size_t caplen, 181 uint16_t iplen, 182 yfTCPInfo_t * tcpinfo, 183 yfL2Info_t * l2info); 184 185 /** 186 * Similar to yfHookPacket but also given yfFlowVal_t struct for 187 * processing per flow direction 188 * 189 * @param flow pointer to yfFlow_t 190 * @param val pointer to yfFlowVal_t struct 191 * @param pkt pointer to pkt data 192 * @param caplen size of pkt data 193 * @param iplen 194 * @param tcpinfo 195 * @param l2info 196 */ 197 void yfHookFlowPacket ( 198 yfFlow_t * flow, 199 yfFlowVal_t * val, 200 const uint8_t *pkt, 201 size_t caplen, 202 uint16_t iplen, 203 yfTCPInfo_t * tcpinfo, 204 yfL2Info_t * l2info); 205 206 /** 207 * Validation function to make sure the plugin can and should operate 208 * based on the flowtable options 209 * 210 * @param yfctx pointer to the yaf ctx which contains configuration specifics 211 * @param max_payload value 212 * @param uniflow 213 * @param silkmode 214 * @param applabelmode 215 * @param entropymode 216 * @param fingerprintmode p0f finger printing mode 217 * @param fpExportMode handshake header export mode 218 * @param udp_max_payload concatenate udp payloads similar to TCP 219 * @param udp_uniflow_port export all udp packets if have this src or dst port 220 */ 221 void yfHookValidateFlowTab ( 222 void **yfctx, 223 uint32_t max_payload, 224 gboolean uniflow, 225 gboolean silkmode, 226 gboolean applabelmode, 227 gboolean entropymode, 228 gboolean fingerprintmode, 229 gboolean fpExportMode, 230 gboolean udp_max_payload, 231 uint16_t udp_uniflow_port); 232 233 /** 234 * Called upon flow close to do any necessary 235 * plugin processing upon flow close 236 * 237 * @param flow 238 * @return TRUE or FALSE upon error 239 */ 240 gboolean yfHookFlowClose ( 241 yfFlow_t * flow); 242 243 /** 244 * Allow plugins to allocate flow state information for 245 * each flow captured by yaf at the time of flow creation. 246 * 247 * @param flow the pointer to the flow context state structure, but 248 * more importantly contains the array of pointers (hfctx) which 249 * hold the plugin context state 250 * @param yfctx pointer to the yaf ctx which contains configuration specifics 251 * for this instance of yaf 252 * 253 */ 254 void yfHookFlowAlloc ( 255 yfFlow_t * flow, 256 void ** yfctx); 257 258 /** 259 * Frees all memory associated with the flow state in all of the 260 * attached plugins 261 * 262 * @param flow - a pointer to the flow context structure 263 * 264 */ 265 void yfHookFlowFree ( 266 yfFlow_t * flow); 267 268 /** 269 * Returns the IPFIX info model aggregated for all plugins 270 * 271 * @return pointer to an array of fbInfoElement_t that contains 272 * the sum of the IPFIX IE's from all active plugins 273 */ 274 fbInfoElement_t *yfHookGetInfoModel ( 275 void); 276 277 /** 278 * Gets the IPFIX info model template for the export data from _all_ 279 * the plugins and turns it into a single template to return. It caches 280 * the results so that future queries are a lot faster. It can validate 281 * the cached result if the numer of plugins registered changes. 282 * 283 * @param session pointer to an array of fbInfoElementSpec_t structures 284 * that describes the info model template 285 */ 286 gboolean yfHookGetTemplate ( 287 fbSession_t *session); 288 /** 289 * called by yfWriteFlow to add the data from all registered plugins 290 * to the outgoing IPFIX record 291 * 292 * @param rec outgoing subTemplateMultiList 293 * @param stml Current entry of subTemplateMultiList 294 * @param flow pointer to the flow context structure 295 * @param err Error 296 */ 297 gboolean yfWriteFlowHook ( 298 fbSubTemplateMultiList_t *rec, 299 fbSubTemplateMultiListEntry_t *stml, 300 yfFlow_t * flow, 301 GError ** err); 302 303 /** 304 * Adds another hook (plugin) into yaf 305 * 306 * @param hookName the file name of the plugin to load 307 * @param hookOpts a string of command line options for the plugin to process 308 * @param hookConf the config file for the plugin 309 * @param yfctx pointer to the yaf ctx which contains configuration specifics 310 * for this instance of yaf 311 * @param err the error value that gets set if this call didn't work 312 * 313 * @return TRUE if plugin loaded fine, other FALSE 314 * 315 */ 316 gboolean yfHookAddNewHook( 317 const char *hookName, 318 const char *hookOpts, 319 const char *hookConf, 320 void **yfctx, 321 GError ** err); 322 323 #if YAF_ENABLE_APPLABEL 324 /** 325 * Specifically if application labeling is enabled for deep packet 326 * inspection plugin. 327 * 328 * @param flow 329 * @param pkt pointer to payload 330 * @param caplen payloadSize 331 * @param expression PCRE expression to evaluate against payload 332 * @param offset in payload to begin 333 * @param elementID label for regex 334 * @param applabel 335 */ 336 void yfHookScanPayload ( 337 yfFlow_t *flow, 338 const uint8_t *pkt, 339 size_t caplen, 340 pcre *expression, 341 uint16_t offset, 342 uint16_t elementID, 343 uint16_t applabel); 344 345 #endif 346 347 /** 348 * Returns the amount of templates to add to the SubtemplateMultiList 349 * from all plugins hooked. 350 * 351 * @param flow 352 * @return number of templates to add to SubTemplateMultiList in yaf 353 */ 354 uint8_t yfHookGetTemplateCount( 355 yfFlow_t *flow); 356 357 /** 358 * Sends control back to the plugin to free any BasicLists, SubTemplateLists, 359 * or SubTemplateMultiLists that may have been used in it's added templates. 360 * 361 * @param flow 362 */ 363 void yfHookFreeLists( 364 yfFlow_t *flow); 365 366 #endif 367