next up previous contents index
Next: The weird Module Up: Analyzers and Events Previous: The signature Module   Contents   Index

Subsections


The SSL Analyzer

The SSL analyzer processes traffic associated with the SSL (Secure Socket Layer) protocol versions 2.0 [SSLv2], 3.0 [SSLv30] and 3.1 [TLSv1]. SSL version 3.1 is also known as TLS (Transport Layer Security) version 1.0 since from that version onward the IETF has taken responsibility for further developement of SSL.

Bro instantiates an SSL analyzer for any connection with service ports 443/tcp (https), 563/tcp (nntps), 585/tcp (imap4-ssl), 614/tcp (sshell), 636/tcp (ldaps), 989/tcp (ftps-data), 990/tcp (ftps), 992/tcp (telnets), 993/tcp (imaps), 994/tcp (ircs), 995/tcp (pop3s), providing you have loaded the SSL analyzer, or defined a handler for one of the SSL events.

By default, the analyzer uses the above set of ports as a capture filter (§ ). It currently checks the SSL handshake process for consistency, tries to verify seen certificates, generates several events, does connection logging, tries to detect security weaknesses, and produces simple statistics. It is also able to store seen certificates on disk. However, it does no decryption, so analysis is limited to clear text SSL records. This means that analysis stops in the middle of the handshaking phase for SSLv2 and at the end of it for SSLv3.0/SSLv3.1 (TLS). For this reason we have not implemented the SSL session caching mechanism (yet).

The analyzer consists of the four files: ssl.bro, ssl-ciphers.bro, ssl-errors.bro, and ssl-alerts.bro, which are accessed by @load ssl. The analyzer writes to the weird and ssl log files. The first receives all non-conformant and ``weird'' activity, while the latter tracks the SSL handshaking phase.


The x509 record

Figure: Definition of the x509 record.
\begin{figure}\begin{verbatim}type x509: record {
issuer: string;  ...

This record is a very simplified structure for storing X.509 [X509] certificate information. It currently supports only the issuer and subject names.


The ssl_connection_info record

Figure: Definition of the ssl_connection_info record.
\begin{figure}\begin{verbatim}type ssl_connection_info: record {
id: count;  ...

The main data structure managed by the SSL analyzer is a collection of ssl_connection_info records, where the record type is shown in Figure [*]. The corresponding fields are Fix me: the description here is out of date:

[id] The unique connection identifier assigned to this connection. Connections are numbered starting at 1 and incrementing with each new connection.

[connection_id] The TCP connection which this SSL connection is based on.

[version] The SSL version number for this connection. Possible values are SSLv20, for SSL version 2.0, SSLv30 for version 3.0, and SSLv31 for version 3.1.

[client_cert] The information from the client certificate, if available.

[server_cert] The information from the server certificate, if available.

[id_index] Index into associated SSL_sessionID_record table.

[handshake_cipher] The cipher suite client and server agreed upon. Note: For SSLv2 cached sessions, this is a placeholder (0xABCD).


SSL variables

The standard script defines the following redefinable variables:

[ssl_compare_cipherspecs : bool] If true, remember the client and server cipher specs and perform additional tests. This costs an extra amount of memory (normally only for a short time) but enables detection of non-intersecting cipher sets, for example.

Default: T.

[ssl_analyze_certificates : bool] If true, analyze certificates seen in SSL connections, which includes the following steps:

Default: T.

[ssl_store_certificates : bool] If certificates are analyzed, this variable determines they should be stored on disk.

Default: T.

[ssl_store_cert_path : string] Path where certificates are stored. If empty, use the current directory. Note: The path must not end with a slash!

Default: "../certs".

[ssl_verify_certificates : bool] If certificates are analyzed, wheter to verify them.

Default: T.

[x509_trusted_cert_path : string] Path where OpenSSL looks for trusted certificates. If empty, use the default OpenSSL path.

Default: "".

[ssl_max_cipherspec_size : count] Maximum size in bytes for an SSL cipherspec. If we see attempted use of larger cipherspecs, warn and skip comparing it.

Default: 45.

[ssl_store_key_material : bool] If true, stores key material exchanged in the handshaking phase. Note: This is mainly for decryption purposes and currently useless.

Default: T.

Figure: Example of SSL log file with a single SSL session.
\begin{figure}\begin{verbatim}1046778101.534846  ...

In addition, ssl_log holds the name of the SSL log file to which Bro writes SSL connection summaries. It defaults to open_log_file("ssl").

Figure [*] shows an example of how entries in the SSL log file look like. We see a transcript of the first SSL connection seen since Bro started running. The first line gives its start and the participating hosts and ports. Next, we see a client trying to attempt a SSL (Version 3.1) connection and the cipher suites offered. The server replies with a SSL 3.1 SERVER-REPLY and the desired cipher suite. Note: In SSL v3.0/v3.1 this determines which cipher suite will be used for the connection. Following this is the certificate the server sends, including the issuer and subject. Finally, we see that the handshaking phase for this SSL connection is finished now, and that client and server agreed on the cipher suite: RSA_WITH_RC4_128_MD5. Due to encryption, the SSL analyzer skips all further data. We only see the end of the connection. When Bro finishes, we get some statistics about the cipher suites used in all monitored SSL connections.


SSL event handlers

The standard script handles the following events:

[ssl_conn_attempt (c: connection, version: count, cipherSuites: cipher_suites_list)]

Invoked upon the client side of connection c when the analyzer sees a CLIENT-HELLO of SSL version version including the cipher suites the client offers cipherSuites.

The version can be 0x0002, 0x0300 or 0x0301. A new entry is generated inside the SSL connection table and the cipher suites are listed. Ciphers, that are known as weak (according to a corresponding table of weak ciphers) are logged inside the weak.log file. This also happens to cipher suites that we do not know yet. Note: See the file ssl-ciphers.bro for a list of known cipher suites.

[ssl_conn_server_reply (c: connection, version: count, cipherSuites: cipher_suites_list)]

This event is invoked upon the analyzer receiving a SERVER-HELLO of the SSL server. It contains the SSL version the server wishes to use (Note: This finally determines, which SSL version will be used further) and the cipher suite he offers. If it is SSL version 3.0 or 3.1, the server determines within this SERVER-HELLO the cipher suite for the following connection (so it will only be one). But if it's a SSL version 2.0 connection, the server only announces the cipher suites he supports and it's up to the client to decide which one to use.

Again, the cipher suites are listed and weak and unknown cipher suites are reported inside weak.log.

[ssl_certificate_seen ( c: connection, isServer: int )]

Invoked whenever we see a certificate from client or server but before verification of the certificate takes place. This may be useful, if you want to do something before certificate verification (e.g. do not verify certificates of some given servers).

[ssl_certificate ( c: connection, cert: x509, isServer: bool)]

Invoked after the certificate from server or client (isServer) has been verified. Note: We only verify certificates once. If we see them again, we only check if they have changed! cert holds the issuer and subject of the certificate, which gets stored inside this SSL connection's information record inside the SSL connection table and are written to ssl.log.

[ssl_conn_reused (c: connection, session_id: string)]

Invoked whenever a former SSL session is reused. session_id holds the session ID as string of the reused session and is written to ssl.log. Currently we don't do session tracking, because SSL version 2.0 doesn't send the session ID in clear text when it's generated.

[ssl_conn_established (c: connection, version: count, cipher_suite: count)]

Invoked when the handshaking phase of an SSL connection is finished. We see the used SSL version and the cipher suite that will be used for cryptography (written to ssl.log) if we have SSL version 3.0 or 3.1. In case of SSL version 2.0 we can only determine the used cipher suite for new sessions, not for reused ones. (Note: In SSL version 3.0 and 3.1 the cipher suite to be used is already anounced in the SERVER-HELLO.)

[ssl_conn_alert (c: connection, version: count, level: count, description: count)]

Invoked when the analyzer receives an SSL alert. The level of the alert (warning or fatal) and the description are written into ssl.log. (Note: See ssl-alerts.bro).

[ssl_conn_weak (name: string, c: connection)]

This event is called when the analyzer sees:

See weak.bro.


next up previous contents index
Next: The weird Module Up: Analyzers and Events Previous: The signature Module   Contents   Index
Vern Paxson 2004-03-21