broccoli.h

Go to the documentation of this file.

/*
       B R O C C O L I  --  The Bro Client Communications Library

Copyright (C) 2004-2007 Christian Kreibich <christian (at) icir.org>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies of the Software and its documentation and acknowledgment shall be
given in the documentation and software packages that this Software was
used.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

*/
#ifndef broccoli_h
#define broccoli_h

#include <inttypes.h>
#include <unistd.h>
#include <sys/types.h>
#include <stdlib.h>
#ifdef __MINGW32__
#include <winsock.h>
#else
#include <netinet/in.h>
#endif
#include <openssl/crypto.h>

#ifdef __cplusplus
extern "C" {
#endif

extern int bro_debug_calltrace;

extern int bro_debug_messages;

#ifndef FALSE
#define FALSE   (0)
#endif

#ifndef TRUE
#define TRUE    (!FALSE)
#endif

/* Numeric values of Bro type identifiers, corresponding
 * to the values of the TypeTag enum in Bro's Type.h. Use
 * these values with bro_event_add_val(), bro_record_add_val(),
 * bro_record_get_nth_val() and bro_record_get_named_val().
 */
#define BRO_TYPE_UNKNOWN           0
#define BRO_TYPE_BOOL              1
#define BRO_TYPE_INT               2
#define BRO_TYPE_COUNT             3
#define BRO_TYPE_COUNTER           4
#define BRO_TYPE_DOUBLE            5
#define BRO_TYPE_TIME              6
#define BRO_TYPE_INTERVAL          7
#define BRO_TYPE_STRING            8
#define BRO_TYPE_PATTERN           9
#define BRO_TYPE_ENUM             10
#define BRO_TYPE_TIMER            11
#define BRO_TYPE_PORT             12
#define BRO_TYPE_IPADDR           13
#define BRO_TYPE_SUBNET           14
#define BRO_TYPE_ANY              15
#define BRO_TYPE_TABLE            16
#define BRO_TYPE_UNION            17
#define BRO_TYPE_RECORD           18
#define BRO_TYPE_LIST             19
#define BRO_TYPE_FUNC             20
#define BRO_TYPE_FILE             21
#define BRO_TYPE_VECTOR           22
#define BRO_TYPE_ERROR            23
#define BRO_TYPE_PACKET           24 /* CAUTION -- not defined in Bro! */
#define BRO_TYPE_SET              25 /* CAUTION -- not defined in Bro! */
#define BRO_TYPE_MAX              26

/* Flags for new connections, to pass to bro_conn_new()
 * and bro_conn_new_str(). See manual for details.
 */
#define BRO_CFLAG_NONE                      0
#define BRO_CFLAG_RECONNECT           (1 << 0) 
#define BRO_CFLAG_ALWAYS_QUEUE        (1 << 1) 
#define BRO_CFLAG_SHAREABLE           (1 << 2) 
#define BRO_CFLAG_DONTCACHE           (1 << 3) 
#define BRO_CFLAG_YIELD               (1 << 4) 
#define BRO_CFLAG_CACHE               (1 << 5) 
/* ---------------------------- Typedefs ----------------------------- */


typedef uint64_t uint64;
typedef uint32_t uint32;
typedef uint16_t uint16;
typedef uint8_t uint8;
typedef unsigned char  uchar;

typedef struct bro_conn BroConn;
typedef struct bro_event BroEvent;
typedef struct bro_buf BroBuf;
typedef struct bro_record BroRecord;
typedef struct bro_table BroTable;
typedef struct bro_table BroSet;
typedef struct bro_vector BroVector;
typedef struct bro_ev_meta BroEvMeta;
typedef struct bro_packet BroPacket;

/* ----------------------- Callback Signatures ----------------------- */

typedef void (*BroEventFunc) (BroConn *bc, void *user_data, ...);

typedef void (*BroCompactEventFunc) (BroConn *bc, void *user_data, BroEvMeta *meta);

typedef void (*BroPacketFunc) (BroConn *bc, void *user_data,
                               const BroPacket *packet);

typedef void (*OpenSSL_lock_func) (int mode, int n, const char *file, int line);

typedef unsigned long (*OpenSSL_thread_id_func) (void);


typedef struct CRYPTO_dynlock_value* (*OpenSSL_dynlock_create_func) (const char *file, int line);

typedef void (*OpenSSL_dynlock_lock_func) (int mode, struct CRYPTO_dynlock_value *mutex,
                                           const char *file, int line);

typedef void (*OpenSSL_dynlock_free_func) (struct CRYPTO_dynlock_value *mutex,
                                           const char *file, int line);


/* ---------------------------- Structures --------------------------- */


typedef struct bro_ctx {
  OpenSSL_lock_func lock_func;
  OpenSSL_thread_id_func id_func;
  OpenSSL_dynlock_create_func dl_create_func;
  OpenSSL_dynlock_lock_func dl_lock_func;
  OpenSSL_dynlock_free_func dl_free_func;
} BroCtx;

typedef struct bro_conn_stats {
  int tx_buflen; 
  int rx_buflen; 
} BroConnStats;

typedef struct bro_string {
  uint32       str_len;
  uchar       *str_val;
} BroString;

typedef struct bro_port {
  uint64       port_num;   
  int          port_proto; 
} BroPort;

typedef struct bro_addr
{
  uint32       addr[4];    
} BroAddr;

typedef struct bro_subnet
{
  BroAddr      sn_net;     
  uint32       sn_width;   
} BroSubnet;

typedef struct bro_ev_arg
{
  void        *arg_data;   
  int          arg_type;   
} BroEvArg;

struct bro_ev_meta
{
  const char  *ev_name;   
  double       ev_ts;     
  int          ev_numargs;
  BroEvArg    *ev_args;   
  const uchar *ev_start;  
  const uchar *ev_end;    
};

#define BRO_PCAP_SUPPORT
#ifdef BRO_PCAP_SUPPORT
#include <pcap.h>

struct bro_packet
{
  double       pkt_time;
  uint32       pkt_hdr_size;
  uint32       pkt_link_type;
  
  struct pcap_pkthdr  pkt_pcap_hdr;
  const u_char       *pkt_data;
  const char         *pkt_tag;

};

#endif

/* ============================ API ================================== */

/* -------------------------- Initialization ------------------------- */

int            bro_init(const BroCtx *ctx);


void           bro_ctx_init(BroCtx *ctx);


/* ----------------------- Connection Handling ----------------------- */

BroConn       *bro_conn_new(struct in_addr *ip_addr, uint16 port, int flags);

BroConn       *bro_conn_new6(struct in6_addr *ip_addr, uint16 port, int flags);

BroConn       *bro_conn_new_str(const char *hostname, int flags);

BroConn       *bro_conn_new_socket(int socket, int flags);

void           bro_conn_set_class(BroConn *bc, const char *classname);

const char    *bro_conn_get_peer_class(const BroConn *bc);


void           bro_conn_get_connstats(const BroConn *bc, BroConnStats *cs);


int            bro_conn_connect(BroConn *bc);


int            bro_conn_reconnect(BroConn *bc);


int            bro_conn_delete(BroConn *bc);


int            bro_conn_alive(const BroConn *bc);


void           bro_conn_adopt_events(BroConn *src, BroConn *dst);


int            bro_conn_get_fd(BroConn *bc);


int            bro_conn_process_input(BroConn *bc);


/* ---------------------- Connection data storage -------------------- */

/* Connection handles come with a faciity to store and retrieve
 * arbitrary data items. Use the following functions to store,
 * query, and remove items from a connection handle.
 */

void           bro_conn_data_set(BroConn *bc, const char *key, void *val);


void          *bro_conn_data_get(BroConn *bc, const char *key);


void          *bro_conn_data_del(BroConn *bc, const char *key);


/* ----------------------------- Bro Events -------------------------- */

BroEvent      *bro_event_new(const char *event_name);


void           bro_event_free(BroEvent *be);


int            bro_event_add_val(BroEvent *be, int type,
                                 const char *type_name,const void *val);


int            bro_event_set_val(BroEvent *be, int val_num,
                                 int type, const char *type_name,
                                 const void *val);

int            bro_event_send(BroConn *bc, BroEvent *be);
        

int            bro_event_send_raw(BroConn *bc, const uchar *data, int data_len);


int            bro_event_queue_length(BroConn *bc);


int            bro_event_queue_length_max(BroConn *bc);


int            bro_event_queue_flush(BroConn *bc);


/* ------------------------ Bro Event Callbacks ---------------------- */

void           bro_event_registry_add(BroConn *bc,
                                      const char *event_name,
                                      BroEventFunc func,
                                      void *user_data);

void           bro_event_registry_add_compact(BroConn *bc,
                                              const char *event_name,
                                              BroCompactEventFunc func,
                                              void *user_data);

void           bro_event_registry_remove(BroConn *bc, const char *event_name);

void           bro_event_registry_request(BroConn *bc);



/* ------------------------ Dynamic-size Buffers --------------------- */

BroBuf        *bro_buf_new(void);

void           bro_buf_free(BroBuf *buf);

int            bro_buf_append(BroBuf *buf, void *data, int data_len);


void           bro_buf_consume(BroBuf *buf);


void           bro_buf_reset(BroBuf *buf);


uchar         *bro_buf_get(BroBuf *buf);


uchar         *bro_buf_get_end(BroBuf *buf);


uint           bro_buf_get_size(BroBuf *buf);


uint           bro_buf_get_used_size(BroBuf *buf);


uchar         *bro_buf_ptr_get(BroBuf *buf);


uint32         bro_buf_ptr_tell(BroBuf *buf);


int            bro_buf_ptr_seek(BroBuf *buf, int offset, int whence);


int            bro_buf_ptr_check(BroBuf *buf, int size);


int            bro_buf_ptr_read(BroBuf *buf, void *data, int size);

int            bro_buf_ptr_write(BroBuf *buf, void *data, int size);


/* ------------------------ Configuration Access --------------------- */

void           bro_conf_set_domain(const char *domain);


int            bro_conf_get_int(const char *val_name, int *val);


int            bro_conf_get_dbl(const char *val_name, double *val);


const char    *bro_conf_get_str(const char *val_name);



/* ------------------------------ Strings ---------------------------- */

void           bro_string_init(BroString *bs);

int            bro_string_set(BroString *bs, const char *s);

int            bro_string_set_data(BroString *bs, const uchar *data, int data_len);

const uchar   *bro_string_get_data(const BroString *bs);

uint32         bro_string_get_length(const BroString *bs);
  
BroString     *bro_string_copy(BroString *bs);

void           bro_string_assign(BroString *src, BroString *dst);

void           bro_string_cleanup(BroString *bs);

void           bro_string_free(BroString *bs);


/* -------------------------- Record Handling ------------------------ */

BroRecord     *bro_record_new(void);

void           bro_record_free(BroRecord *rec);
 
int            bro_record_get_length(BroRecord *rec);

int            bro_record_add_val(BroRecord *rec, const char *name,
                                  int type, const char *type_name,
                                  const void *val);

void*          bro_record_get_nth_val(BroRecord *rec, int num, int *type);


const char*    bro_record_get_nth_name(BroRecord *rec, int num);


void*          bro_record_get_named_val(BroRecord *rec, const char *name, int *type);


int            bro_record_set_nth_val(BroRecord *rec, int num,
                                      int type, const char *type_name,
                                      const void *val);

int            bro_record_set_named_val(BroRecord *rec, const char *name,
                                        int type, const char *type_name,
                                        const void *val);


/* -------------------------- Tables & Sets -------------------------- */

typedef int (*BroTableCallback) (void *key, void *val, void *user_data);


BroTable      *bro_table_new(void);
void           bro_table_free(BroTable *tbl);

int            bro_table_insert(BroTable *tbl,
                                int key_type, const void *key,
                                int val_type, const void *val);

void          *bro_table_find(BroTable *tbl, const void *key);

int            bro_table_get_size(BroTable *tbl);

void           bro_table_foreach(BroTable *tbl, BroTableCallback cb,
                                 void *user_data);

void           bro_table_get_types(BroTable *tbl,
                                   int *key_type, int *val_type);


typedef int (*BroSetCallback) (void *val, void *user_data);

BroSet        *bro_set_new(void);
void           bro_set_free(BroSet *set);

int            bro_set_insert(BroSet *set, int type, const void *val);

int            bro_set_find(BroSet *set, const void *key);

int            bro_set_get_size(BroSet *set);

void           bro_set_foreach(BroSet *set, BroSetCallback cb,
                               void *user_data);

void           bro_set_get_type(BroSet *set, int *type);

/* ----------------------------- Vectors ----------------------------- */

BroVector     *bro_vector_new(void);

void           bro_vector_free(BroVector *vec);

int            bro_vector_get_length(BroVector *vec);

int            bro_vector_add_val(BroVector *vec,
                                  int type, const char *type_name,
                                  const void *val);

void*          bro_vector_get_nth_val(BroVector *vec, int num, int *type);


int            bro_vector_set_nth_val(BroVector *vec, int num,
                                      int type, const char *type_name,
                                      const void *val);


/* ----------------------- Pcap Packet Handling ---------------------- */
#ifdef BRO_PCAP_SUPPORT

void           bro_conn_set_packet_ctxt(BroConn *bc, int link_type);

void           bro_conn_get_packet_ctxt(BroConn *bc, int *link_type);

BroPacket     *bro_packet_new(const struct pcap_pkthdr *hdr, const u_char *data, const char* tag);

BroPacket     *bro_packet_clone(const BroPacket *packet);

void           bro_packet_free(BroPacket *packet);

int            bro_packet_send(BroConn *bc, BroPacket *packet);

#endif

/* --------------------------- Miscellaneous ------------------------- */

double         bro_util_current_time(void);

double         bro_util_timeval_to_double(const struct timeval *tv);

int            bro_util_is_v4_addr(const BroAddr *a);

extern const uint8 BRO_IPV4_MAPPED_PREFIX[12];

#ifdef __cplusplus
}
#endif

#endif