How to Configure testssl.sh to Use a Specific or Custom OpenSSL Binary

Set the OPENSSL environment variable to the full path of your executable, or pass --openssl /path/to/binary as a command-line argument to override the automatic detection and force testssl.sh to use your custom OpenSSL installation.

testssl.sh is a comprehensive command-line tool for testing SSL/TLS encryption that relies on the underlying OpenSSL binary to perform cryptographic handshake operations. While the script includes robust auto-detection logic, security professionals often need to configure testssl.sh to use a specific or custom OpenSSL binary to test legacy protocols disabled in modern distributions or to access newer cipher suites. This guide explains the three supported override mechanisms and their implementation in the source code.

Why Use a Custom OpenSSL Binary?

Modern Linux distributions frequently compile OpenSSL with insecure protocols like SSLv3 or TLS 1.0 disabled, which prevents complete server testing. Additionally, you may need a statically linked binary for portability, a specific OpenSSL 3.x build for performance testing, or a Windows Subsystem for Linux (WSL) executable path. Configuring a custom binary ensures you can execute comprehensive scans regardless of the host system's default cryptographic library configuration.

Methods to Configure a Custom Binary

testssl.sh provides three distinct ways to specify which OpenSSL executable to use, implemented in the find_openssl_binary() function starting at line 21044 of testssl.sh.

Using the OPENSSL Environment Variable

The script checks for the OPENSSL environment variable before attempting any auto-detection. If the variable is set and points to an executable file, testssl.sh uses it immediately.

In testssl.sh at lines 21061–21067, the logic validates the variable with [[ -n "$OPENSSL" ]] && [[ -x "$OPENSSL" ]] before proceeding.

export OPENSSL=/opt/openssl-1.0.2/bin/openssl
./testssl.sh --sni www.example.com

This method is persistent across multiple invocations and applies to helper scripts like utils/curves.bash that replicate the same detection logic.

Using the --openssl Command-Line Option

You can override the detection for a single execution by passing the --openssl flag followed by the absolute path. The argument parsing block at lines 25117–25121 handles --openssl|--openssl=* patterns by setting the internal OPENSSL variable before the detection routine runs.

./testssl.sh --openssl /usr/local/openssl-3.3/bin/openssl --sni mail.example.org

When you use this flag, it takes precedence over the environment variable if both are set, ensuring explicit per-run control.

Understanding the Fallback Logic

If you provide neither the environment variable nor the command-line flag, find_openssl_binary() executes a hierarchical search:

1. Local binary test: Checks for openssl, openssl.<uname>.<arch>, or similar in the script's directory, its parent, or ../bin using the test_openssl_suffix helper.
2. System PATH search: Falls back to the first openssl executable found in the user's $PATH.
3. Validation: Executes $OPENSSL version -a to verify the binary works; if this fails, the script aborts with "cannot exec or find any openssl binary".

This sequence ensures the bundled OpenSSL binaries are prioritized when available, while maintaining compatibility with system installations.

Practical Code Examples

Override with Environment Variable for Persistent Use

Set the variable in your shell profile or per session to use a legacy OpenSSL build that supports SSLv3 testing:

export OPENSSL=/opt/openssl-1.0.2u/bin/openssl
./testssl.sh --sni legacy-server.example.com

Temporary Override with Command-Line Flag

Use the system binary for one specific test while keeping your environment variable pointing to a custom build:

export OPENSSL=/opt/openssl-1.1.1g/bin/openssl  # default for most runs

./testssl.sh --openssl /usr/bin/openssl --sni api.example.com  # temporary switch

Configuring Helper Scripts

The utils/curves.bash script contains its own find_openssl_binary implementation that respects the OPENSSL variable:

cd utils
OPENSSL=/opt/openssl-1.1.1/bin/openssl ./curves.bash -v example.com

Cross-Platform Windows Path

You can reference Windows Subsystem for Linux paths or native Windows executables:

export OPENSSL="/mnt/c/Program Files/OpenSSL-Win64/bin/openssl.exe"
./testssl.sh https://example.com

Key Implementation Details

The binary selection logic is centralized in find_openssl_binary() within testssl.sh (lines 21044–21078). The function first checks the OPENSSL variable state, then attempts to locate architecture-specific binaries (e.g., openssl.Linux.x86_64) in relative paths, and finally searches the system $PATH. If the chosen binary fails the version check, the script terminates immediately to prevent false negatives in test results.

According to the drwetter/testssl.sh documentation in doc/testssl.1.md (lines 66–78), both the --openssl option and OPENSSL environment variable are officially supported interfaces for binary selection, ensuring backward compatibility in future releases.

Summary

• Environment variable method: Set OPENSSL=/path/to/binary before running the script; checked first in find_openssl_binary() at lines 21061–21067.
• Command-line method: Use --openssl /path/to/binary for per-run overrides; parsed at lines 25117–25121.
• Auto-detection fallback: Searches local script directories, then $PATH, validating with version -a before execution.
• Helper compatibility: Scripts like utils/curves.bash respect the same OPENSSL variable conventions.
• Validation: The script aborts if the specified binary cannot execute the version -a command.

Frequently Asked Questions

Can I use a statically compiled OpenSSL binary with testssl.sh?

Yes, you can point OPENSSL or --openssl to any executable OpenSSL binary, including statically compiled versions. This is particularly useful when testing from systems without development libraries installed or when you need specific compilation flags not present in dynamic system packages.

Why does testssl.sh fail with "cannot exec or find any openssl binary"?

This error occurs when the script cannot locate a valid OpenSSL executable. Verify that the path specified in the OPENSSL variable or --openssl argument exists, has executable permissions (chmod +x), and can successfully run the command openssl version -a. The validation check at lines 21074–21078 explicitly tests this before proceeding with SSL checks.

Does the --openssl flag override the OPENSSL environment variable?

Yes, the command-line --openssl flag takes precedence over the environment variable. The argument parsing logic in testssl.sh (lines 25117–25121) processes command-line arguments after the environment is loaded but before the detection routine runs, allowing you to temporarily override persistent environment settings.

Can I use this method with the curves.bash helper script?

Yes, the utils/curves.bash script implements its own find_openssl_binary function that checks for the OPENSSL environment variable using the same logic as the main script. Set the variable before invoking the helper, or modify the script to accept command-line arguments if you need per-run overrides for curve testing specifically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}