1 /* 2 * Copyright (c) 2015 by Farsight Security, Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef NMSG_FLTMOD_H 18 #define NMSG_FLTMOD_H 19 20 /*! \file nmsg/fltmod.h 21 * \brief Loading and calling external message filter modules. 22 * 23 * This file defines the interface for loading and calling filter modules. For 24 * the interface that developers of message filter modules must implement, see 25 * nmsg/fltmod_plugin.h. 26 * 27 * Message filter modules allow a message filtering function to be implemented 28 * externally in a dynamically loaded plugin. 29 * 30 * A filter module must first be loaded with nmsg_fltmod_init(). If this 31 * succeeds, nmsg_fltmod_thread_init() must be called by each thread that wants 32 * to perform filtering with this module, even if the caller is 33 * single-threaded. The 'thr_data' value returned by nmsg_fltmod_thread_init() 34 * must be provided as the 'thr_data' parameter to nmsg_fltmod_filter_message(). 35 * 36 * Filter functions may alter or replace the message object. 37 * 38 * Each thread that calls nmsg_fltmod_thread_init() must clean up by calling 39 * nmsg_fltmod_thread_fini(), and after each thread has cleaned up, the module 40 * itself may be cleaned up by calling nmsg_fltmod_destroy(). 41 */ 42 43 #include <nmsg/filter.h> 44 45 /** 46 * Initialize a filter module with the given parameters. Calls the module's 47 * 'module_init' function. 48 * 49 * \param name 50 * The name of the filter module, which is used to construct the filesystem 51 * path to the shared object containing the filter module. This may either 52 * be a real, complete filesystem path (absolute or relative) that begins 53 * with "/" or "./", or it may be a short "convenience" name that will be 54 * expanded to a real filesystem path. For example, the short name "sample" 55 * might be expanded to a long name like 56 * "/usr/lib/nmsg/nmsg_flt1_sample.so". 57 * 58 * \param param 59 * Pointer to a value that will be passed to the 'module_init' function. 60 * Specifies module-specific configuration. 61 * 62 * \param len_param 63 * Length of the 'param' value. Passed to the 'module_init' function. 64 * 65 * \return Opaque pointer that is NULL on failure or non-NULL on success. 66 */ 67 nmsg_fltmod_t 68 nmsg_fltmod_init(const char *name, const void *param, const size_t len_param); 69 70 /** 71 * Destroy a filter module. Calls the module's 'module_fini' function. All 72 * calls to nmsg_fltmod_thread_fini() must complete before calling this 73 * function. 74 * 75 * \param[in] fltmod 76 * Initialized fltmod. 77 */ 78 void 79 nmsg_fltmod_destroy(nmsg_fltmod_t *fltmod); 80 81 /** 82 * Initialize thread-specific data for the filter module. Must be called by a 83 * processing thread before calling nmsg_fltmod_filter_message(). Calls the 84 * module's 'thread_init' function. 85 * 86 * Each thread that calls nmsg_fltmod_thread_init() must perform a 87 * corresponding call to nmsg_fltmod_thread_fini() before nmsg_fltmod_destroy() 88 * can be called. 89 * 90 * \param fltmod 91 * Initialized fltmod. 92 * 93 * \param[out] thr_data 94 * Opaque data pointer specific to the calling thread. This pointer must be 95 * supplied in subsequent calls to nmsg_fltmod_filter_message() or 96 * nmsg_fltmod_thread_fini(). 97 * 98 * \return #nmsg_res_success 99 * If the thread data was successfully initialized. 100 * \return 101 * Any other result may be returned by the module's 'thread_init' function 102 * to indicate an error. 103 */ 104 nmsg_res 105 nmsg_fltmod_thread_init(nmsg_fltmod_t fltmod, void **thr_data); 106 107 /** 108 * Release any thread-specific resources acquired by nmsg_fltmod_thread_init(). 109 * Calls the module's 'thread_fini' function. 110 * 111 * \param fltmod 112 * Initialized fltmod. 113 * 114 * \param thr_data 115 * Opaque data pointer originally returned by nmsg_fltmod_thread_init(). 116 * 117 * \return #nmsg_res_success 118 * If the thread data was successfully released. 119 * \return 120 * Any other result may be returned by the module's 'thread_fini' function 121 * to indicate an error. 122 */ 123 nmsg_res 124 nmsg_fltmod_thread_fini(nmsg_fltmod_t fltmod, void *thr_data); 125 126 /** 127 * Filter a message object and return the filter verdict. Calls the module's 128 * 'filter_message' function. 129 * 130 * The thread that calls this function must have first called 131 * nmsg_fltmod_thread_init(), and the 'thr_data' value returned by that 132 * function must be passed as the 'thr_data' parameter to this function. 133 * 134 * \param fltmod 135 * Initialized fltmod. 136 * 137 * \param[in,out] msg 138 * The NMSG message object to be filtered. The filter function may alter 139 * the message object, or it may replace it with a new message object. 140 * 141 * \param thr_data 142 * Opaque data pointer originally returned by nmsg_fltmod_thread_init(). 143 * 144 * \param[out] vres 145 * The filter verdict. \see #nmsg_filter_message_verdict for the possible 146 * verdict results and meanings. 147 * 148 * \return #nmsg_res_success 149 * The filtering completed and returned a verdict in 'vres'. 150 * \return 151 * Any other result may be returned to indicate a fatal error. 152 */ 153 nmsg_res 154 nmsg_fltmod_filter_message(nmsg_fltmod_t fltmod, 155 nmsg_message_t *msg, 156 void *thr_data, 157 nmsg_filter_message_verdict *vres); 158 159 #endif /* NMSG_FLTMOD_H */ 160