Skip to content

OpenSSL Tracer Manual

Requirements

The tracer requires installing libunwind library which is used to retrieve stack traces.

If you want the trace to contain complete stack traces for calls to the OpenSSL library, the application should be built with debug symbols. It is not necessary to build the OpenSSL libraries in debug mode. If the application is not built with debug symbols, the tracer will still work, but you will only see the calls to the libraries, and not the stack traces.

Getting Started

OpenSSL has two parts: libssl (handling TLS connections) and libcrypto (containing high-level and low-level cryptographic APIs).

Using the Cryptosense OpenSSL tracers, it is possible to intercept calls made from an application to one of these dynamic libraries. This relies on the LD_PRELOAD mechanism of the dynamic linker in Linux. Cryptographic calls are interpreted, they are forwarded to the usual OpenSSL library (so, results are identical), and the parameters of these calls are stored in a trace file.

For example, the openssl command line tool uses libcrypto. To obtain traces corresponding to the execution of a command, the LD_PRELOAD environment variable needs to be set to the path of the tracer. For example, in an interactive shell session:

$ echo test | LD_PRELOAD=/path/to/evp_tracer.so openssl enc -aes-256-cbc -k secret -base64
U2FsdGVkX198ngJ8NyTPBUoh+yo+tHGErViNw4ZSfJs=

This creates a trace file under /tmp, named cryptosense-evp-PID.cst where PID is the Process ID.

It is possible to configure where traces are stored using the CS_TRACE_DIR environment variable:

$ mkdir cs-traces
$ export CS_TRACE_DIR=cs-traces
$ echo test | LD_PRELOAD=/path/to/evp_tracer.so openssl enc -aes-256-cbc -k secret -base64
U2FsdGVkX18hVdVJYKcULBEychnWY74IronRe/tA/Sg=
$ ls cs-traces
cryptosense-evp-377.cst

Typically, commands invoking openssl are not directly run in a shell, but in an init script or similar. It is then necessary to locate and modify this script to include the environment variables.

Since every program has its own PID, it is possible that a large number of trace files is created. It is possible to concatenate these files together before submitting them to the Cryptosense Analyzer web application:

$ ls cs-traces
cryptosense-evp-702.cst   cryptosense-evp-767.cst
cryptosense-evp-809.cst   cryptosense-evp-894.cst
cryptosense-evp-745.cst   cryptosense-evp-788.cst
cryptosense-evp-851.cst   cryptosense-evp-931.cst
$ cat cryptosense-evp-*.cst > cryptosense-evp-joined.cst

Configuration

The tracer can be configured with the following environment variables:

  • CS_TRACE_DIR: Path of an existing directory where the tracer will create the trace files. Defaults to /tmp.

Troubleshooting

If, for some reason, the tracer doesn't work, please send us the error message you're seeing and the output of the following commands, to be executed in the same environment as the OpenSSL tracer:

uname --all
ldd --verbose --function-relocs evp_tracer.so
ldd --verbose --function-relocs libssl_tracer.so