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

> Configure testssl.sh to use a specific OpenSSL binary. Learn to set the OPENSSL environment variable or use the --openssl command-line flag for custom OpenSSL installations. Ensure accurate SSL/TLS testing.

- Repository: [Dirk Wetter/testssl.sh](https://github.com/drwetter/testssl.sh)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/drwetter/testssl.sh/blob/main/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`](https://github.com/drwetter/testssl.sh/blob/main/testssl.sh) at lines 21061–21067, the logic validates the variable with `[[ -n "$OPENSSL" ]] && [[ -x "$OPENSSL" ]]` before proceeding.

```bash
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`](https://github.com/drwetter/testssl.sh/blob/main/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.

```bash
./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:

```bash
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:

```bash
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`](https://github.com/drwetter/testssl.sh/blob/main/utils/curves.bash) script contains its own `find_openssl_binary` implementation that respects the `OPENSSL` variable:

```bash
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:

```bash
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`](https://github.com/drwetter/testssl.sh/blob/main/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`](https://github.com/drwetter/testssl.sh/blob/main/drwetter/testssl.sh) documentation in [`doc/testssl.1.md`](https://github.com/drwetter/testssl.sh/blob/main/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`](https://github.com/drwetter/testssl.sh/blob/main/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`](https://github.com/drwetter/testssl.sh/blob/main/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`](https://github.com/drwetter/testssl.sh/blob/main/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.