Broccoli API Documentation  1.96
Broccoli API Documentation
broccoli.h
Go to the documentation of this file.
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
 All Data Structures Files Functions Variables Typedefs Defines