Environment:ClickHouse ClickHouse OpenSSL Runtime
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Security |
| Last Updated | 2026-02-08 18:00 GMT |
Overview
OpenSSL dependency environment for TLS/SSL support in ClickHouse server connections, HTTPS clients, and certificate management via the Poco NetSSL library.
Description
ClickHouse uses a vendored OpenSSL build (compiled from `contrib/`) through the Poco NetSSL_OpenSSL library for all SSL/TLS operations. The `SSLManager` singleton manages server and client SSL contexts, certificate verification handlers, and private key passphrase handlers. OpenSSL is added first in the contrib build order to ensure all downstream libraries use the vendored version rather than any system-installed OpenSSL.
Usage
Use this environment for any Server Deployment workflow that requires encrypted connections (HTTPS, TLS for native protocol, inter-server encryption). It is required when configuring SSL certificates, enabling HTTPS endpoints, or setting up encrypted replication. Also needed by the `HTTPSClientSession` for outbound HTTPS requests (e.g., to S3, external dictionaries).
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, macOS, FreeBSD | All supported platforms |
| Software | OpenSSL (vendored) | Built from `contrib/openssl`; system OpenSSL optionally used via `ENABLE_OPENSSL_DYNAMIC` |
| Files | SSL certificate + private key | Required for server TLS; paths configured in `config.xml` |
Dependencies
System Packages
- OpenSSL is vendored and compiled from source by default
- Optional: System OpenSSL via `ENABLE_OPENSSL_DYNAMIC=ON` (removes SSL from ClickHouse binary and links dynamically)
Poco Libraries
- `Poco::NetSSL_OpenSSL` (SSL socket wrappers)
- `Poco::Crypto` (certificate handling)
- `Poco::Net` (base networking)
Credentials
The following are configured in ClickHouse server configuration (`config.xml`):
- `certificateFile`: Path to server SSL certificate (PEM format)
- `privateKeyFile`: Path to server private key (PEM format)
- `caConfig`: Path to CA certificate bundle for client verification
- `dhParamsFile`: Optional Diffie-Hellman parameters file
- Private key passphrase: Can be provided via `KeyFileHandler` (from config) or `KeyConsoleHandler` (interactive)
Quick Install
# OpenSSL is built automatically from contrib/ during cmake configure
# No separate installation needed
# To use system OpenSSL instead (not recommended):
cmake -DENABLE_OPENSSL_DYNAMIC=ON ...
# Generate self-signed certificate for testing
openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt -days 365 -nodes
Code Evidence
OpenSSL added first in contrib build order from `contrib/CMakeLists.txt:46`:
# We need to add OpenSSL first so that all our projects use our own version
# instead of the system one.
add_contrib (openssl-cmake openssl)
SSLManager singleton from `base/poco/NetSSL_OpenSSL/include/Poco/Net/SSLManager.h:169-172`:
static SSLManager& instance();
/// Returns the instance of the SSLManager singleton.
void initializeServer(
PrivateKeyPassphraseHandlerPtr ptrPassphraseHandler,
InvalidCertificateHandlerPtr ptrHandler,
Context::Ptr ptrContext);
Context configuration from `base/poco/NetSSL_OpenSSL/include/Poco/Net/Context.h:397`:
// Supported verification modes:
// VERIFY_NONE, VERIFY_RELAXED, VERIFY_STRICT, VERIFY_ONCE
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `SSLException: SSL handshake failed` | Certificate mismatch or expired cert | Verify certificate validity and hostname matching |
| `Cannot load certificate file` | Wrong path in config.xml | Check `certificateFile` path; must be readable by clickhouse user |
| `Cannot load private key file` | Wrong path or passphrase | Check `privateKeyFile` path; provide passphrase via handler if encrypted |
Compatibility Notes
- Vendored vs System: By default, OpenSSL is compiled from source in `contrib/`. Use `ENABLE_OPENSSL_DYNAMIC=ON` to link against system OpenSSL, but this removes SSL from the ClickHouse binary itself.
- Certificate Handlers: Two built-in handlers: `AcceptCertificateHandler` (accepts all, for testing only) and `RejectCertificateHandler` (rejects all invalid, for production).
- Fuzzing builds: SSL is force-enabled (`ENABLE_SSL=1`) during fuzzing to ensure SSL code paths are tested.