Principle:ClickHouse ClickHouse SSL TLS Configuration
| Knowledge Sources | |
|---|---|
| Domains | Deployment, Server_Administration |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
TLS/SSL configuration for ClickHouse server and client connections uses OpenSSL through the Poco framework's `SSLManager` singleton, providing certificate management, peer verification, cipher suite selection, and session caching.
Description
ClickHouse encrypts network connections using the TLS protocol via OpenSSL, managed through the Poco NetSSL library. The configuration system supports both server-side and client-side SSL contexts, each with independent certificate chains, verification policies, and cipher suites.
SSL Context Management: The central abstraction is the `SSLManager` singleton, which holds default server and client `Context` objects. Each `Context` wraps an OpenSSL `SSL_CTX` structure and encapsulates all TLS parameters for one side of the connection. The singleton pattern ensures that all server sockets share the same SSL configuration, avoiding inconsistencies and reducing memory overhead from duplicate certificate loading.
Certificate and Key Configuration: TLS requires at minimum a private key and a certificate for the server. These are specified as PEM-format files via the `privateKeyFile` and `certificateFile` parameters. An optional CA location (`caLocation`) specifies the trusted root certificates used to verify peer certificates. The CA location can be either a single PEM file or a directory of certificate files.
Verification Modes: ClickHouse supports four peer certificate verification modes:
- `VERIFY_NONE` -- No peer certificate verification. The server does not request a client certificate; the client ignores server certificate errors.
- `VERIFY_RELAXED` (default) -- Peer certificates are verified if presented, and verification failures terminate the handshake. However, the server does not require clients to present a certificate.
- `VERIFY_STRICT` -- Like relaxed, but the server will immediately terminate the handshake if the client does not present a certificate.
- `VERIFY_ONCE` -- The server requests a client certificate only on the initial handshake, not on renegotiation.
Cipher Suite Control: The cipher list defaults to `"ALL:!ADH:!LOW:!EXP:!MD5:!3DES:@STRENGTH"`, which enables all ciphers except anonymous Diffie-Hellman, low-strength, export-grade, MD5-based, and 3DES ciphers, and sorts the remaining by strength. The `preferServerCiphers` option causes the server to impose its cipher preference order on clients.
Protocol Version Control: Specific TLS versions can be required via the `Usage` enum (e.g., `TLSV1_2_SERVER_USE`) or disabled via the `disableProtocols` configuration property, which accepts a comma-separated list of protocol names (`sslv2`, `sslv3`, `tlsv1`, `tlsv1_1`, `tlsv1_2`).
Key Exchange Parameters: Diffie-Hellman parameters can be loaded from a file (`dhParamsFile`) for forward secrecy. Elliptic-curve Diffie-Hellman uses a configurable named curve (default `"prime256v1"`, also known as P-256 or secp256r1).
Session Caching: Server-side TLS session caching can be enabled to reduce the overhead of repeated TLS handshakes from the same clients. Configuration options include session cache size (default 20480 according to OpenSSL), session timeout, and a session ID context string that becomes part of each server-generated session identifier.
Event-Driven Error Handling: The `SSLManager` uses Poco's event system to handle certificate verification errors and private key passphrase requests. Applications register delegates for `ServerVerificationError`, `ClientVerificationError`, and `PrivateKeyPassphraseRequired` events. Certificate handlers (e.g., `RejectCertificateHandler`) and passphrase handlers (e.g., `KeyConsoleHandler`, `KeyFileHandler`) provide concrete implementations.
Usage
Configure TLS when deploying ClickHouse in environments that require encrypted connections between clients and the server, between ClickHouse nodes in a cluster (for distributed queries and replication), or between ClickHouse and external systems. TLS is essential for any deployment handling sensitive data, operating across untrusted networks, or subject to compliance requirements such as SOC 2, PCI DSS, or HIPAA.
Theoretical Basis
Singleton pattern for SSL context: The `SSLManager` uses the singleton pattern (`Poco::SingletonHolder`) to ensure exactly one instance manages all SSL contexts. This is appropriate because OpenSSL's `SSL_CTX` objects are heavyweight (they load certificates, build verification chains, and allocate internal caches), and sharing them across connections is both memory-efficient and operationally correct since all server connections should present the same certificate.
Verification chain depth: The `verificationDepth` parameter (default 9) controls the maximum length of the certificate chain from the peer certificate to the trusted root. This prevents denial-of-service through excessively long certificate chains while accommodating typical enterprise PKI hierarchies that may have intermediate CAs.
Forward secrecy: Diffie-Hellman (DH) and Elliptic-Curve Diffie-Hellman (ECDH) parameters enable forward secrecy, ensuring that compromise of the server's long-term private key does not retroactively compromise past session keys. The default curve `prime256v1` provides 128-bit equivalent security, which is considered sufficient for most current applications.
Callback architecture: OpenSSL uses C-style callbacks for certificate verification and passphrase retrieval. The Poco framework wraps these into its event/delegate system, where static callback methods (`verifyServerCallback`, `verifyClientCallback`, `privateKeyPassphraseCallback`) dispatch to registered event handlers. This allows application-specific policy (accept, reject, log) without modifying the SSL library code.
Configuration-driven initialization: The `SSLManager` supports two initialization paths: explicit programmatic initialization via `initializeServer`/`initializeClient`, and automatic configuration-driven initialization from the application's XML configuration under the `openSSL.server` or `openSSL.client` prefix. The automatic path reads all parameters from the configuration hierarchy, allowing deployment-time TLS configuration without code changes.