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:

  • The first component is libssl_tracer.so. This component should be used to trace libssl calls from the application to the libssl.so part of OpenSSL. The slot type must be OpenSSL libssl usage (libssl in the API).
  • The second component is evp_tracer.so. This component should be used to trace libcrypto (or EVP) calls from the application to the libcrypto.so part of OpenSSL. The slot type must be OpenSSL libcrypto usage (evp in the API).

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.

If you wanted 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.

Similarly, if you wanted 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.

Refer to the API Client documentation for instructions to upload a trace.

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