Skip to content

OpenSSL Tracer reference↑

Tracer components↑

The SandboxAQ OpenSSL Tracer consists of two components to handle the two parts of OpenSSL:

The first component is libssl_tracer.so. This component should be used to trace libssl calls from the application to the libssl.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 trace libcrypto (or EVP) calls from the application to the libcrypto.so part of OpenSSL. The slot type must be OpenSSL libcrypto usage (evp in the API).

Caution

The slot type must match the analysis type that will be used for the uploaded trace. The analysis will fail if the types don’t match.

A version of each tracer exists for different OpenSSL versions. Supported versions are OpenSSL 0.9.8, 1.0.x, and 1.1.x. There’s also a dedicated version if your program runs with OpenSSL 1.0 as provided by RHEL 7 or CentOS 7.

If you’re unsure which part of OpenSSL your program uses, or which version your program uses, the command below should help:

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

Configuration↑

The tracers can be configured with the following environment variables:

  • CS_TRACE_DIR: Existing directory path where the tracer creates the trace files. Defaults to /tmp.
  • CS_PREFIX: Optional custom file name prefix for traces (default is cs-trace-evp for the libcrypto tracer and cs-trace-ssl for the libssl tracer).
  • CS_MAX_TRACE_SIZE: Maximum uncompressed trace size in MB (default is 4GB). The tracer stops writing to the trace file just before the limit is reached. Set the variable to 0 to remove this limit.
  • CS_USE_TMP_TRACE_NAME (experimental): If this is set to 1, the tracer uses a temporary .tmp suffix for the name of the trace. The suffix is removed once execution of the trace is completed. Note that if the traced application doesn’t exit normally (for example with a segmentation fault), the suffix remains. This behavior is disabled by default.

Compilation flags and stack trace information↑

The OpenSSL Tracer generates the stack trace linked to each instrumented call. The level of detail in the stack traces varies based on the compilation of both the traced application and the OpenSSL library.

Function names can be retrieved if symbols remain in the associated ELF binaries. By default, both the gcc and clang compilers (and their associated static linkers) include symbols inside their generated binaries. However, these symbols can be stripped from third-party proprietary binaries, rendering the OpenSSL tracer unable to generate a meaningful trace.

File and line information are extracted from debug information that’s generated using the -g compilation flag. The absence of this information in a trace typically means that the debug information weren’t included in the associated ELF binaries.

Compiler optimizations usually inline small functions, causing them to be absent from the extracted stack trace.

Recommendations↑

In a CI/CD environment, it’s recommended to compile the traced application without optimizations (-O0), but with debug information (-g) for accurate stack traces.

Caution

Disabling compiler optimizations can significantly impact the performance of the traced application and potentially affect the CI/CD runtime).

In a production environment where optimized binaries are commonly used, it’s still possible to get file and line number information by building optimized binaries that include debug information by using the -g flag. Note that the debug information size can be non-negligible. Keep in mind that this approach may also lead to inaccurate line number details.

To ensure accurate stack traces in your reports, it’s crucial not to strip information from the generated binaries (that is don’t use the strip command on the generated binary).

Troubleshooting↑

If the tracer isn’t working as expected, please send us the error message you’re seeing, as well as the output of the following commands executed in the same environment as the OpenSSL Tracer:

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