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
(§
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.
This record is a very simplified structure for storing X.509 [X509] certificate information. It currently supports only the issuer and subject names.
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:
[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).
The standard script defines the following redefinable variables:
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.
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.
The standard script handles the following events:
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: