Cisco SSL Appliance Session Tool

Requirements

• An x86 or x86-64 personal computer running Windows or Linux. The system must be running Python 2.6.x or 2.7.x; Python 3.x is not supported. This is called the "host" system in this document.
• Python version 2.6.x or 2.7.x
• pyOpenSSL version 0.12
• wxPython 2.9 (required for UI mode)
• A Cisco SSL Appliance sslsessions output file you want to run the tool on.

Install the SSL Sessions Tool

The SSL Sessions tool is provided as a zipped package which must be installed on the host system. The package file name is sslsessions-n.n.n.zip, where n.n.n is a version number for the package. After installation, the tool can be run from the command line or as a GUI application (requires wxPython 2.9).

Install the Package in a Linux environment

Step 1 Copy the file to the host system.

Step 2 At a command line type in the following:
unzip sslsessions-n.n.n.zip
cd sslsessions-n.n.n
python setup.py install

Tip You must be logged on as a user with privileges that allow software installation.

Install the Package in a Windows Environment

On Windows systems, additional steps are required to complete the installation. You must add the directory where the script was installed to your system path. To do this, open a Run window (click Start, type run, and click Enter),

Step 1 In the Run window, enter
C:\windows\system32\rundll32.exe" sysdm.cpl,EditEnvironmentVariables


Step 2 Click OK. The Environment Variables window displays.

Step 3 In the top panel labeled User variables for <user name>, select the PATH entry, then click Edit. The Edit User Variable windows displays.

Step 4 Enter the path to your unzipped file in the Variable value field, followed by a semicolon. An example is shown next.

Note The example uses Python 2.7. The SSL Sessions tool requires Python 2.6.x or 2.7.x (Python 3.x is not supported).

Step 5 When the entry is correct, click OK. Exit the Environment Variables window.

Verify the Installation

To verify that the SSL Diagnostics tool is installed correctly, open a command prompt and enter

sslsessions.py --version

You should see:

host:<path>/sslsessions/$ sslsessions.py --version
Usage: sslsessions.py [options] [output-path]
Export csv data from filtered ssl session log files. [output-path] is required.
If no command line arguments are provided, the tool starts up in ui mode.
Set the mode (-M or --mode) to csv or report when using the tool from command line.
Version: n.n.n

Using the SSL Sessions Tool

The SSL Session Log Tool is an application that can parse binary ssl session log files, filter on various

fields and save the data in CSV format. It can be used in command line mode or in ui mode.

In ui mode the application looks like this:

Here is an example of command-line mode:

sslsessions.py -M csv -S../sessions_logs/ssl_session_log-20150115T173613

-d *.google.com../session_log_output

The following options can be provided on the command-line:

Usage:

sslsessions.py [options]

Options:

API

The event reading library for the tool is also accessible from the python installation.

This is a code example that reads the 1st log file from a command-line path argument and prints a

few fields.:

import os, sys

from ssl_sessions import readevents

log_path = sys.argv[1]

for event in readevents.iter_session_log_events(

os.path.join(log_path, 'ssl_session_log.1.bin'), '3.8',

readevents.read_cert_store(log_path),

readevents.read_hsm_resigning_cas(log_path)):

print event.flowid.ID, event.flow, event.subject

if not event.match_result('OK'):

print 'ERROR:', event.result

ssl_sessions.readevents

class ssl_sessions.readevents.SessionLogEvent (data, sslng_version, cert_store=None,

hsm_resigning_cas=None)

Class representing a single session log event.

ssl_sessions.readevents.asn_parse_san_entry (data)

Parse an ASN entry to extract SAN IP and DNS name entries.

Parameters: data (str) -- String data for SAN entry.

Returns: List of tuples of ( 'san_ip', str) or ( 'dns_name, str)

ssl_sessions.readevents.inet_ntoa_6 (address)

Convert a network format IPv6 address into text.

Parameters: address (str) -- The binary address.

Returns: IP address in string format.

ssl_sessions.readevents.iter_all_filtered_events (options, progress_notify=None)

Iterator that returns only events filtered by options

ssl_sessions.readevents.read_cert_store (path)

Reads the certificate store pem file into a dict mapping fingerprints to dicts of certificate name

values.

Parameters: path (str) -- Filepath to the session log dictory.

Returns: Fingerprint to certificate info dictionary.

ssl_sessions.readevents.read_hsm_resigning_cas (path)

Reads the HSM Resigning CAs info from json format.

Parameters: path (str) -- Filepath to the session log dictory.

Returns: Fingerprint to HSM info dictionary.