Skip to content

OpenSSL Tracer Manual


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/ openssl enc -aes-256-cbc -k secret -base64

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-tracer
$ export CS_TRACE_DIR=cs-tracer
$ echo test | LD_PRELOAD=/path/to/ openssl enc -aes-256-cbc -k secret -base64
$ ls cs-tracer

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-tracer
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


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.
  • CS_PREFIX: Optional custom file name prefix for traces (default is cs-trace).
  • CS_MAX_TRACE_SIZE: Set a maximum trace size limit in GB to override the default which is 4GB.
  • CS_UNLIMITED_TRACE_SIZE: Remove trace size limit (default is false).


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
ldd --verbose --function-relocs