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 tracelibssl
calls from the application to thelibssl.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 tracelibcrypto
(or EVP) calls from the application to thelibcrypto.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:
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:
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:
$ 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:
$ 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:
$ 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:
$ 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