Bro events in an SSL session

The following image lists all events that are supported by the Bro SSL analyzer and shows when they are triggered in the protocol flow.

Each SSL session begins with an SSL client hello message, in which the client sends information about the protocol Versions it supports as well as the supported cryptographic algorithms.

event ssl_client_hello(c: connection, version: count, possible_ts: time, client_random: string, session_id: string, ciphers: index_vec);

In this event, the two main points of interest are the version as well as the list of ciphers. The conversion between the cipher numerals and the human-readable SSL versions is maintained in the table SSL::version_strings. The version represents the maximal TLS protocol version the client supports. Ciphers is a numeric vector of all the different cipher suites the client can support. Bro contains a mapping between the numerals and the string representation, which is maintained in the table SSL::cipher_desc.

More interestingly, the client may send a number of different extensions together with its client hello. Bro has one generic event which is generated for each extension that is sent either by the client after the client hello or by the server after the server hello:

event ssl_extension(c: connection, is_orig: bool, code: count, val: string);

code contains the number identifying the extension. It can be converted to a string using the SSL::extensions record. val contains the raw binary data contained in the extension.

For some extensions, Bro offers more specialized events that parse more information out of the extension data. The most interesting of these extensions is the Server Name Indication (SNI) which contains the name of the host the client wants to connect to:

event ssl_extension_server_name(c: connection, is_orig: bool, names: string_vec);

The server name is given as a vector of strings. In theory, a client can send a number of different server names. In practice, clients usually only send exactly one server name.

Another example of an extension where a specialized event is provided is the Application Layer Next Protocol Negotiation (ALNP). It is used by the client to signalize which protocol it understands. It is used to negotiate support for Google’s SPDY or HTTP/2. In this case, the extension contains a list of protocol names supported:

event ssl_extension_application_layer_protocol_negotiation(c: connection, is_orig: bool, protocols: string_vec);

After the client has sent its client hello message, the server replies with the server hello.

event ssl_server_hello(c: connection, version: count, possible_ts: time, server_random: string, session_id: string, cipher: count, comp_method: count);

The server hello message contains two interesting pieces of information. The first is the SSL version used for the remainder of the session. This version has to be equal to or less than the maximum version supported by the client.

Second, the server hello contains the cipher suite that the server chose to be used for the remainder of the session. The server can only choose one of the algorithms supported by the clients.

As with the client hello, there is a huge number of extensions that can be sent by the server. Many extensions can be sent by both the server and the client. An example for this is the aforementioned ALNP. When the clients sends the extension, it contains a list of supported application layer protocols. The server can, in turn, reply with the exact same extension. In this case, it contains exactly one protocol, which is the application layer protocol the server chose to use.

Usually, the server also sends an X509 certificate when establishing the connection. The SSL analyzer automatically passes X509 certificates to the X509 analyzer, which raises an event for each certificate that is encountered.

event x509_certificate(f: fa_file, cert_ref: opaque, cert: X509::Certificate)

The certificate is provided as an opaque reference to an object. This reference can be fed into several different functions, e.g. to verify the validity of a certificate. These will be explained below. The cert record contains parsed information about the certificate like the subject, the issuer, the cryptographic algorithms, the key length, etc. Note that a list of all certificates encountered in a connection will automatically be held in the connection record (see next section).

If supported by the client, the server can also choose to send a stapled OCSP reply to prove that the server certificate has not yet expired.

event ssl_stapled_ocsp(c: connection, is_orig: bool, response: string;

After the server and client handshake completes without errors, the SSL connection is established. Bro raises a dedicated event when this occurs:

event ssl_established(c: connection);

The c$ssl record

The SSL scripts provided by Bro as part of the installation automatically store a lot of the data provided by the different events in the connection-record and usually accessible as c$ssl. The full documentation of all fields that are provided in the default installation can be found here.

This record contains several pieces of useful information by default, including the full certificate chain sent from the server in cert_chain The certificate chain is especially relevant to this exercise.

SSL and X509 related functions

Bro also offers a few functions for handling X509 certificates. The most interesting of them is the x509_verify function, which tries to validate a given certificate chain against a list of root certificates.

function x509_verify(certs: x509_opaque_vector, root_certs: table_string_of_string, verify_time: time &default=network_time()): X509::Result

By default, Bro ships with the current Mozilla root store as used by Firefox, Thunderbird, etc. This store is automatically loaded into the SSL::root_certs table.

x509_verify returns a record containing the result of the certificate verification:

type X509::Result: record {
  ## OpenSSL result code
  result: int;
  ## Result as string
  result_string: string;
  ## References to the final certificate chain, if verification successful. End-host certificate is first.
  chain_certs: vector of opaque of x509 &optional;
};

result_string is ok when the validation succeeded. Errors that can occur are e.g. expired or issuer certificate unknown if no valid certificate chain can be built.

If the certificate validation succeeded, chain_certs contains all the certificates from the end-host certificate to the root-certificate that was used for validation.

There are a number of other utility functions that can be used with opaque certificate values. x509_get_certificate_string can be used to convert a Bro opaque certificate value back to its binary representation (default), or to a base64 encoded pem-form (when pem = T).:

function x509_get_certificate_string(cert: opaque of x509, pem: bool &default=F): string

Bro also offers several other functions, e.g. to support the verification of ocsp replies.