Skip to content

OpenSSL Tracer Reference Manual

Installation

Before you can use the OpenSSL Tracers, see installation instructions.

Tracer versions

OpenSSL has two parts, that are traced using different tracers:

  • libssl handles TLS connections, and is traced using libssl-tracer.so;
  • libcrypto contains high-level and low-level cryptographic APIs, and is traced using evp-tracer.so.

Furthermore, there is a version of each tracer for the different OpenSSL versions. At the time of this writing, OpenSSL 0.9.8, 1.0.x and 1.1.x are supported. If your program runs with OpenSSL 1.0 as provided by RHEL 7 or CentOS 7, there is also a dedicated version.

If you don't know which part of OpenSSL your program uses, or which version of OpenSSL it uses, the following command should help you figure that out:

$ readelf -d /path/to/program | grep NEEDED | grep 'ssl\|crypto'

Configuration

The tracers 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-evp for libcrypto tracer and cs-trace-ssl for libssl tracer).
  • CS_MAX_TRACE_SIZE: Maximum uncompressed trace size in MB (4 GB by default). Just before the limit is reached, the tracer stops writing to the trace. This limit can be disabled by setting the variable to 0.
  • CS_USE_TMP_TRACE_NAME (experimental): If set to 1, make the tracer use a temporary .tmp suffix for the name of the trace. At the end of execution, the suffix is removed. Note that if the traced application doesn't exit normally (e.g. with a segfault), the suffix will remain. This behavior is disabled by default.

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