Skip to content

OpenSSL Tracer getting started guide↑

This guide explains how to use the SandboxAQ OpenSSL Tracer to obtain a cryptography trace from an application.

Prerequisites↑

Before using the OpenSSL Tracer, make sure you’ve followed the installation instructions.

You’ll also need an application that uses OpenSSL libraries that you can run in a terminal.

Tracing the application↑

OpenSSL consists of two parts:

  • libssl - this handles TLS connections.
  • libcrypto - this contains high-level and low-level cryptographic APIs.

The OpenSSL Tracer consists of two components to handle both parts: libssl_tracer.so and evp_tracer.so. These two components are explained in detail in the following sections.

It’s possible to intercept calls made from an application to one of these dynamic libraries using the OpenSSL Tracer. This relies on the LD_PRELOAD mechanism of the dynamic linker in Linux.

Cryptographic calls are interpreted, forwarded to the typical OpenSSL library (ensuring identical outcomes), and the parameters of these calls are stored in a trace file.

Libssl_tracer.so component↑

The libssl_tracer.so component should be used to trace libssl calls from the application to the libssl.so library of OpenSSL. The slot type must be OpenSSL libssl usage (libssl in the API).

To trace the libssl part of a program named foo, you’d execute the following command when running the program:

Bash
$ LD_PRELOAD=/path/to/libssl_tracer.so foo

This generates a trace file in the /tmp directory named cs-trace-libssl-PID_TIMESTAMP.cst. You can configure the directory where the OpenSSL Tracer generates traces with the CS_TRACE_DIR environment variable.

Evp_tracer.so component↑

The evp_tracer.so component should be used to trace libcrypto (or EVP) calls from the application to the libcrypto.so library of OpenSSL. The slot type must be OpenSSL libcrypto usage (evp in the API).

To trace the libcrypto part of a program named foo, you’d execute the following command when running the program:

Bash
$ LD_PRELOAD=/path/to/evp_tracer.so foo

This generates a trace file in the /tmp directory named cs-trace-evp-PID_TIMESTAMP.cst, where PID is the process ID of the program and TIMESTAMP is the date and time in UTC when the program was traced.

Note

If the traced application is terminated abruptly, the resulting gzip file may be missing a trailer and appear to be corrupted. However, AQtive Guard should still be able to analyze the contents of the trace.

Upload the trace to AQtive Guard to run an analysis and generate a report. Refer to these instructions:

Refer to Configuration in the OpenSSL Tracer reference for a list of available parameters and how to use them.

Tracing text encryption↑

OpenSSL ships with a command-line tool named openssl. You can use it to encrypt text with the following command:

Bash
$ echo some text | openssl enc -aes-256-cbc -k secret -base64
U2FsdGVkX181z6PWd25ZnqNUqhVXGiy+ka7bwSu1tqE=

Since the openssl command-line tool uses libcrypto in this scenario, select the evp_tracer.so component of the OpenSSL Tracer. To obtain the trace for the execution of this command, set the LD_PRELOAD environment variable tracer’s path.

For instance, in an interactive shell session, the previous command would be modified to the following:

Bash
$ echo some text | LD_PRELOAD=/path/to/evp_tracer.so openssl enc -aes-256-cbc -k secret -base64
U2FsdGVkX1++v8mvWpXbogGGWV8NrE4LxWuQ/+0E/yw=

The encrypted text is still printed in the standard output. This also generates a trace file named cs-trace-evp-PID_TIMESTAMP.cst in the /tmp directory, where PID is the process ID.

Configuring where traces are stored↑

You can configure the directory where the OpenSSL Tracer generates traces with the CS_TRACE_DIR environment variable:

Bash
$ mkdir cs-tracer
$ export CS_TRACE_DIR=cs-tracer
$ echo some text | LD_PRELOAD=/path/to/evp_tracer.so openssl enc -aes-256-cbc -k secret -base64
U2FsdGVkX1+Gwdr9Zs0OyteehJdK40UBJSwQ+BWrq3w=
$ ls cs-tracer
cs-trace-evp-944387_2022-06-14-13-56-53.cst

Combining trace files↑

As each program run generates a unique trace file, you’ll likely end up with a substantial number of these files over time. For simplicity, you can concatenate these files before uploading them to the AQtive Guard web interface:

Bash
$ ls cs-tracer
 cs-trace-evp-944387_2022-06-14-13-56-53.cst
 cs-trace-evp-947560_2022-06-14-14-44-49.cst
 cs-trace-evp-947609_2022-06-14-14-44-50.cst
 cs-trace-evp-947654_2022-06-14-14-44-51.cst
 cs-trace-evp-947699_2022-06-14-14-44-53.cst
 cs-trace-evp-947744_2022-06-14-14-44-54.cst
$ cat cs-trace-evp-*.cst > cryptosense-evp-joined.cst