![]() |
Broccoli API Documentation
1.96
Broccoli API Documentation
|
00001 00005 /* 00006 B R O C C O L I -- The Bro Client Communications Library 00007 00008 Copyright (C) 2004-2007 Christian Kreibich <christian (at) icir.org> 00009 00010 Permission is hereby granted, free of charge, to any person obtaining a copy 00011 of this software and associated documentation files (the "Software"), to 00012 deal in the Software without restriction, including without limitation the 00013 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 00014 sell copies of the Software, and to permit persons to whom the Software is 00015 furnished to do so, subject to the following conditions: 00016 00017 The above copyright notice and this permission notice shall be included in 00018 all copies of the Software and its documentation and acknowledgment shall be 00019 given in the documentation and software packages that this Software was 00020 used. 00021 00022 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 00023 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 00024 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 00025 THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 00026 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 00027 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 00028 00029 */ 00030 #ifndef broccoli_h 00031 #define broccoli_h 00032 00033 #include <inttypes.h> 00034 #include <unistd.h> 00035 #include <sys/types.h> 00036 #include <stdlib.h> 00037 #ifdef __MINGW32__ 00038 #include <winsock.h> 00039 #else 00040 #include <netinet/in.h> 00041 #endif 00042 #include <openssl/crypto.h> 00043 00044 #ifdef __cplusplus 00045 extern "C" { 00046 #endif 00047 00055 extern int bro_debug_calltrace; 00056 00064 extern int bro_debug_messages; 00065 00066 #ifndef FALSE 00067 #define FALSE (0) 00068 #endif 00069 00070 #ifndef TRUE 00071 #define TRUE (!FALSE) 00072 #endif 00073 00074 /* Numeric values of Bro type identifiers, corresponding 00075 * to the values of the TypeTag enum in Bro's Type.h. Use 00076 * these values with bro_event_add_val(), bro_record_add_val(), 00077 * bro_record_get_nth_val() and bro_record_get_named_val(). 00078 */ 00084 #define BRO_TYPE_UNKNOWN 0 00085 #define BRO_TYPE_BOOL 1 00086 #define BRO_TYPE_INT 2 00087 #define BRO_TYPE_COUNT 3 00088 #define BRO_TYPE_COUNTER 4 00089 #define BRO_TYPE_DOUBLE 5 00090 #define BRO_TYPE_TIME 6 00091 #define BRO_TYPE_INTERVAL 7 00092 #define BRO_TYPE_STRING 8 00093 #define BRO_TYPE_PATTERN 9 00094 #define BRO_TYPE_ENUM 10 00095 #define BRO_TYPE_TIMER 11 00096 #define BRO_TYPE_PORT 12 00097 #define BRO_TYPE_IPADDR 13 00098 #define BRO_TYPE_SUBNET 14 00099 #define BRO_TYPE_ANY 15 00100 #define BRO_TYPE_TABLE 16 00101 #define BRO_TYPE_UNION 17 00102 #define BRO_TYPE_RECORD 18 00103 #define BRO_TYPE_LIST 19 00104 #define BRO_TYPE_FUNC 20 00105 #define BRO_TYPE_FILE 21 00106 #define BRO_TYPE_VECTOR 22 00107 #define BRO_TYPE_ERROR 23 00108 #define BRO_TYPE_PACKET 24 /* CAUTION -- not defined in Bro! */ 00109 #define BRO_TYPE_SET 25 /* CAUTION -- not defined in Bro! */ 00110 #define BRO_TYPE_MAX 26 00111 00112 /* Flags for new connections, to pass to bro_conn_new() 00113 * and bro_conn_new_str(). See manual for details. 00114 */ 00115 #define BRO_CFLAG_NONE 0 00116 #define BRO_CFLAG_RECONNECT (1 << 0) 00117 #define BRO_CFLAG_ALWAYS_QUEUE (1 << 1) 00118 #define BRO_CFLAG_SHAREABLE (1 << 2) 00119 #define BRO_CFLAG_DONTCACHE (1 << 3) 00120 #define BRO_CFLAG_YIELD (1 << 4) 00121 #define BRO_CFLAG_CACHE (1 << 5) 00124 /* ---------------------------- Typedefs ----------------------------- */ 00125 00126 00127 typedef uint64_t uint64; 00128 typedef uint32_t uint32; 00129 typedef uint16_t uint16; 00130 typedef uint8_t uint8; 00131 typedef unsigned char uchar; 00132 00133 typedef struct bro_conn BroConn; 00134 typedef struct bro_event BroEvent; 00135 typedef struct bro_buf BroBuf; 00136 typedef struct bro_record BroRecord; 00137 typedef struct bro_table BroTable; 00138 typedef struct bro_table BroSet; 00139 typedef struct bro_vector BroVector; 00140 typedef struct bro_ev_meta BroEvMeta; 00141 typedef struct bro_packet BroPacket; 00142 00143 /* ----------------------- Callback Signatures ----------------------- */ 00144 00155 typedef void (*BroEventFunc) (BroConn *bc, void *user_data, ...); 00156 00167 typedef void (*BroCompactEventFunc) (BroConn *bc, void *user_data, BroEvMeta *meta); 00168 00169 typedef void (*BroPacketFunc) (BroConn *bc, void *user_data, 00170 const BroPacket *packet); 00171 00190 typedef void (*OpenSSL_lock_func) (int mode, int n, const char *file, int line); 00191 00199 typedef unsigned long (*OpenSSL_thread_id_func) (void); 00200 00201 00210 typedef struct CRYPTO_dynlock_value* (*OpenSSL_dynlock_create_func) (const char *file, int line); 00211 00222 typedef void (*OpenSSL_dynlock_lock_func) (int mode, struct CRYPTO_dynlock_value *mutex, 00223 const char *file, int line); 00224 00234 typedef void (*OpenSSL_dynlock_free_func) (struct CRYPTO_dynlock_value *mutex, 00235 const char *file, int line); 00236 00237 00238 /* ---------------------------- Structures --------------------------- */ 00239 00240 00242 typedef struct bro_ctx { 00243 OpenSSL_lock_func lock_func; 00244 OpenSSL_thread_id_func id_func; 00245 OpenSSL_dynlock_create_func dl_create_func; 00246 OpenSSL_dynlock_lock_func dl_lock_func; 00247 OpenSSL_dynlock_free_func dl_free_func; 00248 } BroCtx; 00249 00251 typedef struct bro_conn_stats { 00252 int tx_buflen; 00253 int rx_buflen; 00254 } BroConnStats; 00255 00258 typedef struct bro_string { 00259 uint32 str_len; 00260 uchar *str_val; 00261 } BroString; 00262 00266 typedef struct bro_port { 00267 uint64 port_num; 00268 int port_proto; 00269 } BroPort; 00270 00275 typedef struct bro_addr 00276 { 00277 uint32 addr[4]; 00278 } BroAddr; 00279 00282 typedef struct bro_subnet 00283 { 00284 BroAddr sn_net; 00285 uint32 sn_width; 00286 } BroSubnet; 00287 00291 typedef struct bro_ev_arg 00292 { 00293 void *arg_data; 00294 int arg_type; 00295 } BroEvArg; 00296 00300 struct bro_ev_meta 00301 { 00302 const char *ev_name; 00303 double ev_ts; 00304 int ev_numargs; 00305 BroEvArg *ev_args; 00306 const uchar *ev_start; 00307 const uchar *ev_end; 00308 }; 00309 00310 #define BRO_PCAP_SUPPORT 00311 #ifdef BRO_PCAP_SUPPORT 00312 #include <pcap.h> 00313 00317 struct bro_packet 00318 { 00319 double pkt_time; 00320 uint32 pkt_hdr_size; 00321 uint32 pkt_link_type; 00322 00323 struct pcap_pkthdr pkt_pcap_hdr; 00324 const u_char *pkt_data; 00325 const char *pkt_tag; 00326 00327 }; 00328 00329 #endif 00330 00331 /* ============================ API ================================== */ 00332 00333 /* -------------------------- Initialization ------------------------- */ 00334 00347 int bro_init(const BroCtx *ctx); 00348 00349 00354 void bro_ctx_init(BroCtx *ctx); 00355 00356 00357 /* ----------------------- Connection Handling ----------------------- */ 00358 00374 BroConn *bro_conn_new(struct in_addr *ip_addr, uint16 port, int flags); 00375 00391 BroConn *bro_conn_new6(struct in6_addr *ip_addr, uint16 port, int flags); 00392 00407 BroConn *bro_conn_new_str(const char *hostname, int flags); 00408 00423 BroConn *bro_conn_new_socket(int socket, int flags); 00424 00438 void bro_conn_set_class(BroConn *bc, const char *classname); 00439 00447 const char *bro_conn_get_peer_class(const BroConn *bc); 00448 00449 00458 void bro_conn_get_connstats(const BroConn *bc, BroConnStats *cs); 00459 00460 00470 int bro_conn_connect(BroConn *bc); 00471 00472 00485 int bro_conn_reconnect(BroConn *bc); 00486 00487 00498 int bro_conn_delete(BroConn *bc); 00499 00500 00519 int bro_conn_alive(const BroConn *bc); 00520 00521 00530 void bro_conn_adopt_events(BroConn *src, BroConn *dst); 00531 00532 00543 int bro_conn_get_fd(BroConn *bc); 00544 00545 00559 int bro_conn_process_input(BroConn *bc); 00560 00561 00562 /* ---------------------- Connection data storage -------------------- */ 00563 00564 /* Connection handles come with a faciity to store and retrieve 00565 * arbitrary data items. Use the following functions to store, 00566 * query, and remove items from a connection handle. 00567 */ 00568 00579 void bro_conn_data_set(BroConn *bc, const char *key, void *val); 00580 00581 00592 void *bro_conn_data_get(BroConn *bc, const char *key); 00593 00594 00604 void *bro_conn_data_del(BroConn *bc, const char *key); 00605 00606 00607 /* ----------------------------- Bro Events -------------------------- */ 00608 00618 BroEvent *bro_event_new(const char *event_name); 00619 00620 00628 void bro_event_free(BroEvent *be); 00629 00630 00647 int bro_event_add_val(BroEvent *be, int type, 00648 const char *type_name,const void *val); 00649 00650 00668 int bro_event_set_val(BroEvent *be, int val_num, 00669 int type, const char *type_name, 00670 const void *val); 00671 00688 int bro_event_send(BroConn *bc, BroEvent *be); 00689 00690 00702 int bro_event_send_raw(BroConn *bc, const uchar *data, int data_len); 00703 00704 00714 int bro_event_queue_length(BroConn *bc); 00715 00716 00726 int bro_event_queue_length_max(BroConn *bc); 00727 00728 00738 int bro_event_queue_flush(BroConn *bc); 00739 00740 00741 /* ------------------------ Bro Event Callbacks ---------------------- */ 00742 00764 void bro_event_registry_add(BroConn *bc, 00765 const char *event_name, 00766 BroEventFunc func, 00767 void *user_data); 00768 00783 void bro_event_registry_add_compact(BroConn *bc, 00784 const char *event_name, 00785 BroCompactEventFunc func, 00786 void *user_data); 00787 00796 void bro_event_registry_remove(BroConn *bc, const char *event_name); 00797 00805 void bro_event_registry_request(BroConn *bc); 00806 00807 00808 00809 /* ------------------------ Dynamic-size Buffers --------------------- */ 00810 00817 BroBuf *bro_buf_new(void); 00818 00826 void bro_buf_free(BroBuf *buf); 00827 00844 int bro_buf_append(BroBuf *buf, void *data, int data_len); 00845 00846 00858 void bro_buf_consume(BroBuf *buf); 00859 00860 00868 void bro_buf_reset(BroBuf *buf); 00869 00870 00877 uchar *bro_buf_get(BroBuf *buf); 00878 00879 00887 uchar *bro_buf_get_end(BroBuf *buf); 00888 00889 00897 uint bro_buf_get_size(BroBuf *buf); 00898 00899 00906 uint bro_buf_get_used_size(BroBuf *buf); 00907 00908 00915 uchar *bro_buf_ptr_get(BroBuf *buf); 00916 00917 00924 uint32 bro_buf_ptr_tell(BroBuf *buf); 00925 00926 00943 int bro_buf_ptr_seek(BroBuf *buf, int offset, int whence); 00944 00945 00956 int bro_buf_ptr_check(BroBuf *buf, int size); 00957 00958 00974 int bro_buf_ptr_read(BroBuf *buf, void *data, int size); 00975 00990 int bro_buf_ptr_write(BroBuf *buf, void *data, int size); 00991 00992 00993 /* ------------------------ Configuration Access --------------------- */ 00994 01005 void bro_conf_set_domain(const char *domain); 01006 01007 01019 int bro_conf_get_int(const char *val_name, int *val); 01020 01021 01033 int bro_conf_get_dbl(const char *val_name, double *val); 01034 01035 01047 const char *bro_conf_get_str(const char *val_name); 01048 01049 01050 01051 /* ------------------------------ Strings ---------------------------- */ 01052 01061 void bro_string_init(BroString *bs); 01062 01075 int bro_string_set(BroString *bs, const char *s); 01076 01089 int bro_string_set_data(BroString *bs, const uchar *data, int data_len); 01090 01101 const uchar *bro_string_get_data(const BroString *bs); 01102 01109 uint32 bro_string_get_length(const BroString *bs); 01110 01118 BroString *bro_string_copy(BroString *bs); 01119 01129 void bro_string_assign(BroString *src, BroString *dst); 01130 01140 void bro_string_cleanup(BroString *bs); 01141 01149 void bro_string_free(BroString *bs); 01150 01151 01152 /* -------------------------- Record Handling ------------------------ */ 01153 01166 BroRecord *bro_record_new(void); 01167 01175 void bro_record_free(BroRecord *rec); 01176 01183 int bro_record_get_length(BroRecord *rec); 01184 01207 int bro_record_add_val(BroRecord *rec, const char *name, 01208 int type, const char *type_name, 01209 const void *val); 01210 01231 void* bro_record_get_nth_val(BroRecord *rec, int num, int *type); 01232 01233 01243 const char* bro_record_get_nth_name(BroRecord *rec, int num); 01244 01245 01259 void* bro_record_get_named_val(BroRecord *rec, const char *name, int *type); 01260 01261 01279 int bro_record_set_nth_val(BroRecord *rec, int num, 01280 int type, const char *type_name, 01281 const void *val); 01282 01300 int bro_record_set_named_val(BroRecord *rec, const char *name, 01301 int type, const char *type_name, 01302 const void *val); 01303 01304 01305 /* -------------------------- Tables & Sets -------------------------- */ 01306 01318 typedef int (*BroTableCallback) (void *key, void *val, void *user_data); 01319 01320 01321 BroTable *bro_table_new(void); 01322 void bro_table_free(BroTable *tbl); 01323 01324 int bro_table_insert(BroTable *tbl, 01325 int key_type, const void *key, 01326 int val_type, const void *val); 01327 01328 void *bro_table_find(BroTable *tbl, const void *key); 01329 01330 int bro_table_get_size(BroTable *tbl); 01331 01332 void bro_table_foreach(BroTable *tbl, BroTableCallback cb, 01333 void *user_data); 01334 01335 void bro_table_get_types(BroTable *tbl, 01336 int *key_type, int *val_type); 01337 01338 01349 typedef int (*BroSetCallback) (void *val, void *user_data); 01350 01351 BroSet *bro_set_new(void); 01352 void bro_set_free(BroSet *set); 01353 01354 int bro_set_insert(BroSet *set, int type, const void *val); 01355 01356 int bro_set_find(BroSet *set, const void *key); 01357 01358 int bro_set_get_size(BroSet *set); 01359 01360 void bro_set_foreach(BroSet *set, BroSetCallback cb, 01361 void *user_data); 01362 01363 void bro_set_get_type(BroSet *set, int *type); 01364 01365 /* ----------------------------- Vectors ----------------------------- */ 01366 01374 BroVector *bro_vector_new(void); 01375 01383 void bro_vector_free(BroVector *vec); 01384 01391 int bro_vector_get_length(BroVector *vec); 01392 01414 int bro_vector_add_val(BroVector *vec, 01415 int type, const char *type_name, 01416 const void *val); 01417 01438 void* bro_vector_get_nth_val(BroVector *vec, int num, int *type); 01439 01440 01458 int bro_vector_set_nth_val(BroVector *vec, int num, 01459 int type, const char *type_name, 01460 const void *val); 01461 01462 01463 /* ----------------------- Pcap Packet Handling ---------------------- */ 01464 #ifdef BRO_PCAP_SUPPORT 01465 01474 void bro_conn_set_packet_ctxt(BroConn *bc, int link_type); 01475 01483 void bro_conn_get_packet_ctxt(BroConn *bc, int *link_type); 01484 01495 BroPacket *bro_packet_new(const struct pcap_pkthdr *hdr, const u_char *data, const char* tag); 01496 01503 BroPacket *bro_packet_clone(const BroPacket *packet); 01504 01512 void bro_packet_free(BroPacket *packet); 01513 01523 int bro_packet_send(BroConn *bc, BroPacket *packet); 01524 01525 #endif 01526 01527 /* --------------------------- Miscellaneous ------------------------- */ 01528 01535 double bro_util_current_time(void); 01536 01544 double bro_util_timeval_to_double(const struct timeval *tv); 01545 01552 int bro_util_is_v4_addr(const BroAddr *a); 01553 01558 extern const uint8 BRO_IPV4_MAPPED_PREFIX[12]; 01559 01560 #ifdef __cplusplus 01561 } 01562 #endif 01563 01564 #endif