3.3.1. Initialization

Broccoli requires global initialization before most of its other other functions can be used. Generally, the way to initialize Broccoli is as follows:

bro_init(NULL);
        

The argument to bro_init() provides optional initialization context, and may be kept NULL for normal use. If required, you may allocate a BroCtx structure locally, initialize it using bro_ctx_init(), fill in additional values as required and and subsequently pass it to bro_init():

BroCtx ctx;
bro_ctx_init(&ctx);
/* Make adjustments to the context structure as required... */
bro_init(&ctx);
        

The BroCtx structure currently contains a set of five different callback function pointers. These are required for thread-safe operation of OpenSSL (Broccoli itself is thread-safe). If you intend to use Broccoli in a multithreaded environment, you need to implement functions and register them via the BroCtx structure. The O'Reilly book "Network Security with OpenSSL" by Viega et al. shows how to implement these callbacks.

You must call bro_init() at the start of your application. Undefined behavior may result if you don't.

3.3.2. Data types in Broccoli

Broccoli declares a number of data types in broccoli.h that you should know about. The more complex ones are kept opaque, while you do get access to the fields in the simpler ones. The full list is as follows:

• Simple signed and unsigned types: int, uint, uint32, uint16 and uchar.

• Connection handles: BroConn, kept opaque.

• Bro events: BroEvent, kept opaque.

• Buffer objects: BroBuf, kept opaque. See the separate section on buffer management for details.

• Ports: BroPort for network ports, defined as follows:

  typedef struct bro_port { uint16 port_num; /* port number in host byte order */ int port_proto; /* IPPROTO_xxx */ } BroPort;

• Records: BroRecord, kept opaque. See the separate section on record handling for details.

• Strings (character and binary): BroString, defined as follows:

  typedef struct bro_string { int str_len; char *str_val; } BroString;

  BroStrings are mostly kept transparent for convenience; please have a look at the string API: bro_string_init(), bro_string_set(), bro_string_set_data(), bro_string_copy(), bro_string_cleanup(), and bro_string_free().

• Tables: BroTable, kept opaque. See the separate section on table handling for details.

• Sets: BroSet, kept opaque. See the separate section on table handling for details.

• Subnets: BroSubnet, defined as follows:

  typedef struct bro_subnet { uint32 sn_net; /* IP address in network byte order */ uint32 sn_width; /* Length of prefix to consider. */ } BroSubnet;

3.3.3. Managing connections

You can use Broccoli to establish a connection to a remote Bro, or to create a Broccoli-enabled server application that other Bros will connect to. (This means that in principle, you can also use Broccoli purely as middleware and have multiple Broccoli applications communicate directly.)

In order to establish a connection to a remote Bro, you first obtain a connection handle. You then use this connection handle to request events, connect to the remote Bro, send events, etc. Connection handles are pointers to BroConn structures, which are kept opaque. Use bro_conn_new() or bro_conn_new_str() to obtain a handle, depending on what parameters are more convenient for you: the former accepts the IP address and port number as separate numerical arguments, the latter uses a single string to encode both, in "hostname:port" format.

To write a Broccoli-enabled server, you first need to implement the usual socket() / bind() / listen() / accept() routine. Once you have obtained a file descriptor for the new connection from accept(), you pass it to the third function that returns a BroConn handle, bro_conn_new_socket(). The rest of the connection handling then proceeds as in the client scenario.

All three calls accept additional flags for fine-tuning connection behaviour. These flags are:

• BRO_CFLAG_NONE: no functionality. Use when no flags are desired.

• BRO_CFLAG_RECONNECT: When using this option, Broccoli will attempt to reconnect to the peer after lost connectivity transparently. Essentially whenever you try to read from or write to the peer and its connection broke down, a full reconnect including complete handshaking is attempted. You can check whether the connection to a peer is alive at any time using bro_conn_alive().

• BRO_CFLAG_ALWAYS_QUEUE: When using this option, Broccoli will queue any events you send for later transmission when a connection is currently down. Without using this flag, any events you attempt to send while a connection is down get dropped on the floor. Note that Broccoli maintains a maximum queue size per connection so if you attempt to send lots of events while the connection is down, the oldest events may start to get dropped nonetheless. Again, you can check whether the connection is currently okay by using bro_conn_alive().

• BRO_CFLAG_DONTCACHE: When using this option, Broccoli will ask the peer not to use caching on the objects it sends to us. This is the default, and the flag need not normally be used. It is kept to maintain backward compatibility.

• BRO_CFLAG_CACHE: When using this option, Broccoli will ask the peer to use caching on the objects it sends to us. Caching is normally disabled.

• BRO_CFLAG_YIELD: When using this option, bro_conn_process_input() processes at most one event at a time and then returns.

By obtaining a connection handle, you do not also establish a connection right away. This is done using bro_conn_connect(). The main reason for this is to allow you to subscribe to events (using bro_event_registry_add(), see below) before establishing the connection. Upon returning from bro_conn_connect() you are guaranteed to receive all instances of the event types you have requested, while later on during the connection some time may elapse between the issuing of a request for events and the processing of that request at the remote end. Connections are established via TCP, optionally using SSL encryption. See "Configuring encrypted communication" below for more information on setting up enncryption. The port numbers Bro agents and Broccoli applications listen on can vary from peer to peer.

Finally, bro_conn_delete() terminates a connection and releases all resources associated with it. You can create as many connections as you like, to one or more peers. You can obtain the file descriptor of a connection using bro_conn_get_fd().

char host_str = "bro.yourorganization.com";
int port      = 1234;
struct hostent *host;
BroConn *bc;

if (! (host = gethostbyname(host_str)) ||
    ! (host->h_addr_list[0])) {
	/* Error handling -- could not resolve host */
}

/* In this example, we obtain a connection handle, then register event handlers,
 * and finally connect to the remote Bro.
 *
 * First obtain a connection handle:
 */
if (! (bc = bro_conn_new((struct in_addr*) host->h_addr_list[0], htons(port), BRO_CFLAG_NONE))) {
	/* Error handling  - could not get connection handle */
}

/* Register event handlers:
 */
bro_event_registry_add(bc, "foo", bro_foo_handler, NULL);
/* ... */

/* Now connect to the peer:
 */
if (! bro_conn_connect(bc)) {
	/* Error handling - could not connect to remote Bro. */
}

/* Send and receive events ... */

/* Disconnect from Bro and clean up connection */
bro_conn_delete(bc);
        

Or simply use the string-based version:

char host_str = "bro.yourcompany.com:1234";
BroConn *bc;

/* In this example we don't request any events from the peer, but
 * we ask it not to use the serialization cache.
 *
 * Again, first obtain a connection handle:
 */
if (! (bc = bro_conn_new_str(host_str, BRO_CFLAG_DONTCACHE))) {
	/* Error handling  - could not get connection handle */
}

/* Now connect to the peer:
 */
if (! bro_conn_connect(bc)) {
	/* Error handling - could not connect to remote Bro. */
}

/* ... */
        

3.3.4. Connection classes

When you want to establish connections from multiple Broccoli applications with different purposes, the peer needs a means to understand what kind of application each connection belongs to. The real meaning of "kind of application" here is "sets of event types to request", because depending on the class of an application, the peer will likey want to receive different types of events.

Broccoli lets you set the class of a connection using bro_conn_set_class(). When using this feature, you need to call that function before issuing a bro_conn_connect(), since the class of a connection is determined at connection startup.

if (! (bc = bro_conn_new_str(host_str, BRO_CFLAG_DONTCACHE))) {
	/* Error handling  - could not get connection handle */
}

/* Set class of this connection: */
bro_conn_set_class(bc, "syslog");

if (! bro_conn_connect(bc)) {
	/* Error handling - could not connect to remote Bro. */
}
        

If your peer is a Bro node, you need to match the chosen connection class in the remote Bro's Remote::destinations configuration. See below for how to do this. Finally, in order to obtain the class of a connection as indicated by the remote side, use bro_conn_get_peer_class().

3.3.5. Composing and sending events

In order to send an event to the remote Bro agent, you first create an empty event structure with the name of the event, then add parameters to pass to the event handler at the remote agent, and then send off the event.

Bro peers ignore unrequested events. You need to make sure that the remote Bro agent is interested in receiving the events you send. This interest is expressed in policy configuration. We'll explain this in more detail below and for now assume that our remote peer is configured to receive the events we send.

Let's assume we want to request a report of all connections a remote Bro currently keeps state for that match a given destination port and host name and that have amassed more than a certain number of bytes. The idea is to send an event to the remote Bro that contains the query, identifiable through a request ID, and have the remote Bro answer us with remote_conn events containing the information we asked for. The definition of our requesting event could look as follows in the Bro policy:

event report_conns(req_id: int, dest_host: string, dest_port: port, min_size: count);
        

First, create a new event:

BroEvent *ev;

if (! (ev = bro_event_new("report_conns"))) {
	/* Error handling - could not allocate new event. */
}
        

Now we need to add parameters to the event. The sequence and types must match the event handler declaration — check the Bro policy to make sure they match. The function to use for adding parameter values is bro_event_add_val() All values are passed as pointer arguments and are copied internally, so the object you're pointing to stays unmodified at all times. You clean up what you allocate. In order to indicate the type of the value passed into the function, you need to pass a numerical type identifier along as well. Table 1 lists the value types that Broccoli supports along with the type identifier and data structures to point to.

Knowing these, we can now compose a request_connections event:

BroString dest_host;
BroPort dest_port;
uint32 min_size;
int req_id = 0;

bro_event_add_val(ev, BRO_TYPE_INT, NULL, &req_id);
req_id++;

bro_string_set(&dest_host, "desthost.destdomain.com");
bro_event_add_val(ev, BRO_TYPE_STRING, NULL, &dest_host);
bro_string_cleanup(&dest_host);

dest_port.dst_port = 80;
dest_port.dst_proto = IPPROTO_TCP;
bro_event_add_val(ev, BRO_TYPE_PORT, NULL, &dest_port);

min_size = 1000;
bro_event_add_val(ev, BRO_TYPE_COUNT, NULL, &min_size);
        

The third argument to bro_event_add_val() lets you specify a specialization of the types listed in Table 1. This is generally not necessary except for one situationn: When using BRO_TYPE_ENUM. You currently cannot define a Bro-level enum type in Broccoli, and thus when sending an enum value, you have to specify the type of the enum along with the value. For example, in order to add an instance of enum transport_type defined in Bro's bro.init, you would use

int transport_proto = 2;
/* ... */
bro_event_add_val(ev, BRO_TYPE_ENUM, "transport_proto", &transport_proto);
	    

All that's left to do now is to send off the event. For this, use bro_event_send() and pass it the connection handle and the event. The function returns TRUE when the event could be sent right away or if it was queued for later delivery. FALSE is returned on error. If the event get queued, this does not indicate an error — likely the connection was just not ready to send the event at this point. Whenever you call bro_event_send(), Broccoli attempts to send as much of an existing event queue as possible. Again, the event is copied internally to make it easier for you to send the same event repeatedly. You clean up what you allocate.

bro_event_send(bc, ev);
bro_event_free(ev);
        

Two other functions may be useful to you: bro_event_queue_length() tells you how many events are currently queued, and bro_event_queue_flush() attempts to flush the current event queue and returns the number of events that do remain in the queue after the flush. Note: you do not normally need to call this function, queue flushing is attempted every time you send an event.

3.3.6. Receiving events

Receiving events is a little more work because you need to

1. tell Broccoli what to do when requested events arrive,

2. let the remote Bro agent know that you would like to receive those events,

3. find a spot in the code path suitable for extracting and processing arriving events.

Each of these steps is explained in the following sections.

3.3.6.2. Requesting event delivery

At this point, Broccoli knows what to do with the requested events upon arrival. What's left to do is to let the remote Bro know that you would like to receive the events for which you registered. If you haven't yet called bro_conn_connect(), then there is nothing to do, since that function will request the registered events anyway. Once connected, you can still request events. To do so, call bro_event_registry_request():

bro_event_registry_request(bc);

This mechanism also implies that no unrequested events will be delivered to us (and if that happened for whatever reason, the event would simply be dropped on the floor).

Note that at the moment you cannot unrequest events, nor can you request events based on predicates on the values of the events' arguments.

3.3.7. Handling records

Broccoli supports record structures, i.e., types that pack a set of values together, placing each value into its own field. In Broccoli, the way you handle records is somewhat similar to events: after creating an empty record (of opaque type BroRecord, you can iteratively add fields and values to it. The main difference is that you must specify a field name with the value; each value in a record can be identified both by position (a numerical index starting from zero), and by field name. You can retrieve vals in a record by field index or field name. You can also reassign values. There is no explicit, IDL-style definition of record types. You define the type of a record implicitly by the sequence of field names and the sequence of the types of the values you put into the record.

Note that all fields in a record must be assigned before it can be shipped.

The API for record composition consists of bro_record_new(), bro_record_free(), bro_record_add_val(), bro_record_set_nth_val(), and bro_record_set_named_val().

On records that use field names, the names of individual fields can be extracted using bro_record_get_nth_name(). Extracting values from a record is done using bro_record_get_nth_val() and bro_record_get_named_val(). The former allows numerical indexing of the fields in the record, the latter provides name-based lookups. Both need to be passed the record you want to extract a value from, the index or name of the field, and either a pointer to an int holding a BRO_TYPE_xxx value (see again Table 1 for a summary of those types) or NULL. The pointer, if not NULL, serves two purposes: type checking and type retrieval. Type checking is performed if the value of the int upon calling the functions is not BRO_TYPE_UNKNOWN. The type tag of the requested record field then has to match the type tag stored in the int, otherwise NULL is returned. If the int stores BRO_TYPE_UNKNOWN upon calling, no type-checking is performed. In both cases, the actual type of the requested record field is returned in the int pointed to upon return from the function. Since you have no guarantees of the type of the value upon return if you pass NULL as the int pointer, this is a bad idea and either BRO_TYPE_UNKNOWN or another type value should always be used.

For example, you could extract the value of the record field "label", which we assume should be a string, in the following ways:

BroRecord *rec = /* obtained somehow */
BroString *string;
int type;

/* --- Example 1 --- */

type = BRO_TYPE_STRING; /* Use type-checking, will not accept other type */

if (! (string = bro_record_get_named_val(rec, "label", &type))) {
	/* Error handling, either there's no field of that value,
	 * or the value is not of BRO_TYPE_STRING. The actual
	 * type is now stored in "type".
	 */
}

/* --- Example 2 --- */

type = BRO_TYPE_UNKNOWN; /* No type checking, just report the existant type */

if (! (string = bro_record_get_named_val(rec, "label", &type))) {
	/* Error handling, no field of that name exists. */
}

printf("The type of the value in field 'label' is %i\n", type);

/* --- Example 3 --- */

if (! (string = bro_record_get_named_val(rec, "label", NULL))) {
	/* Error handling, no field of that name exists. */
}

/* We now have a value, but we can't really be sure of its type */

        

Record fields can be records, for example in the case of Bro's standard connection record type. In this case, in order to get to a nested record, you use BRO_TYPE_RECORD:

void remote_conn_cb(BroConn *bc, int *req_id, BroRecord *conn) {
	BroRecord *conn_id;
	int type = BRO_TYPE_RECORD;
	if (! (conn_id = bro_record_get_named_val(conn, "id", &type))) {
		/* Error handling */
	}
}
        

3.3.8. Handling tables

Broccoli supports Bro-style tables, i.e., associative containers that map instances of a key type to an instance of a value type. A given key can only ever point to a single value. The key type can be composite, i.e., it may consist of an ordered sequence ofdifferent types, or it can be direct, i.e., consisting of a single type (such as an integer, a string, or a record).

The API for table manipulation consists of bro_table_new(), bro_table_free(), bro_table_insert(), bro_table_find(), bro_table_get_size(), bro_table_get_types(), and bro_table_foreach().

Tables are handled similarly to records in that typing is determined dynamically by the initial key/value pair inserted. The resulting types can be obtained via bro_table_get_types(). Should the types not have been determined yet, BRO_TYPE_UNKNOWN will result. Also, as with records, values inserted into the table are copied internally, and the ones passed to the insertion functions remain unaffected.

In contrast to records, table entries can be iterated. By passing a function of signature BroTableCallback() and a pointer to data of your choosing, bro_table_foreach() will invoke the given function for each key/value pair stored in the table. Return TRUE to keep the iteration going, or FALSE to stop it.

The main thing to know about Broccoli's tables is how to use composite key types. To avoid additional API calls, you may treat composite key types exactly as records, though you do not need to use field names when assigning elements to individual fields. So in order to insert a key/value pair, you create a record with the needed items assigned to its slots, and use this record as the key object. In order to differentiate composite index types from direct ones consisting of a single record, use BRO_TYPE_LIST as the type of the record, as opposed to BRO_TYPE_RECORD. Broccoli will then know to interpret the record as an ordered sequence of items making up a composite element, not a regular record.

brotable.c in the test subdirectory of the Broccoli tree contains an extensive example of using tables with composite as well as direct indexing types.

3.3.9. Handling sets

Sets are essentially tables with void value types. The API for set manipulation consists of bro_set_new(), bro_set_free(), bro_set_insert(), bro_set_find(), bro_set_get_size(), bro_set_get_type(), and bro_set_foreach().

3.3.10. Associating data with connections

You will often find that you would like to connect data with a BroConn. Broccoli provides an API that lets you associate data items with a connection handle through a string-based key–value registry. The functions of interest are bro_conn_data_set(), bro_conn_data_get(), and bro_conn_data_del(). You need to provide a string identifier for a data item and can then use that string to register, look up, and remove the associated data item. Note that there is currently no mechanism to trigger a destructor function for registered data items when the Bro connection is terminated. You therefore need to make sure that all data items that you do not have pointers to via some other means are properly released before calling bro_disconnect().

3.3.11. Configuration files

Imagine you have instrumented the mother of all server applications. Building it takes forever, and every now and then you need to change some of the parameters that your Broccoli code uses, such as the host names of the Bro agents to talk to. To allow you to do this quickly, Broccoli comes with support for configuration files. All you need to do is change the settings in the file and restart the application (we're considering adding support for volatile configuration items that are read from the file every time they are requested).

A configuration is read from a single configuration file. This file can be read from two different locations:

• The system-wide configuration file. You can obtain the location of this config file by running broccoli-config --config.

• Alternatively, a per-user configuration file stored in ~/.broccoli.conf can be used.

~/.broccoli.conf will only be used if it is a regular file, not executable, and neither group nor others have any permissions on the file. That is, the file's permissions must look like -rw------- or -r--------.

In the configuration file, a "#" anywhere starts a comment that runs to the end of the line. Configuration items are specified as key-value pairs:

# This is the Broccoli system-wide configuration file.
#
# Entries are of the form <identifier> <value>, where the identifier
# is a sequence of letters, and value can be a string (including
# whitespace), and floating point or integer numbers. Comments start
# with a "#" and go to the end of the line. For boolean values, you
# may also use "yes", "on", "true", "no", "off", or "false".
# Strings may contain whitespace, but need to be surrounded by
# double quotes '"'.
#
# Examples:
#
Foo/PeerName          mybro.securesite.com
Foo/PortNum           123
Bar/SomeFloat         1.23443543
Bar/SomeLongStr       "Hello World"
        

You can also have multiple sections in your configuration. Your application can select a section as the current one, and queries for configuration settings will then only be answered with values specified in that section. A section is started by putting its name (no whitespace please) between square brackets. Configuration items positioned before the first section title are in the default domain and will be used by default.

# This section contains all settings for myapp.
[ myapp ]
        

You can name identifiers any way you like, but to keep things organized it is recommended to keep a namespace hierarchy similar to the file system. In the code, you can query configuration items using bro_conf_get_str(), bro_conf_get_int(), and bro_conf_get_dbl(). You can switch between sections using bro_conf_set_domain().

3.3.12. Using dynamic buffers

Broccoli provides an API for dynamically allocatable, growable, shrinkable, and consumable buffers with BroBufs. You may or may not find this useful — Broccoli mainly provides this feature in broccoli.h because these buffers are used internally anyway and because they are typical case of something that people implement themselves over and over again, for example to collect a set of data before sending it through a file descriptor, etc.

The buffers work as follows. The structure implementing a buffer is called BroBuf. BroBufs are initialized to a default size when created via bro_buf_new(), and released using bro_buf_free(). Each BroBuf has a content pointer that points to an arbitrary location between the start of the buffer and the first byte after the last byte currently used in the buffer (see buf_off in the illustration below). The content pointer can seek to arbitrary locations, and data can be copied from and into the buffer, adjusting the content pointer accordingly. You can repeatedly append data to end of the buffer's used contents using bro_buf_append().

   <---------------- allocated buffer space ------------>
   <======== used buffer space ========>
   ^              ^                    ^               ^                 
   |              |                    |               |
   `buf           `buf_ptr             `buf_off        `buf_len
        

Have a look at the following functions for the details: bro_buf_new(), bro_buf_free(), bro_buf_append(), bro_buf_consume(), bro_buf_reset(), bro_buf_get(), bro_buf_get_end(), bro_buf_get_size(), bro_buf_get_used_size(), bro_buf_ptr_get(), bro_buf_ptr_tell(), bro_buf_ptr_seek(), bro_buf_ptr_check(), and bro_buf_ptr_read().