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.
OpenSSL has two parts:
libssl (handling TLS connections) and
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
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
PID is the
It is possible to configure where traces are stored using the
$ mkdir cs-tracer $ export CS_TRACE_DIR=cs-tracer $ echo test | LD_PRELOAD=/path/to/evp_tracer.so openssl enc -aes-256-cbc -k secret -base64 U2FsdGVkX18hVdVJYKcULBEychnWY74IronRe/tA/Sg= $ ls cs-tracer 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
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
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 evp_tracer.so ldd --verbose --function-relocs libssl_tracer.so