Skip to content

Custom TLS root bundle and mutual TLS (mTLS) options - #79

Open
geoHeil wants to merge 4 commits into
ClickHouse:mainfrom
geoHeil:feat/tls-roots-mtls
Open

geoHeil wants to merge 4 commits into
ClickHouse:mainfrom
geoHeil:feat/tls-roots-mtls

Conversation

@geoHeil

@geoHeil geoHeil commented Oct 3, 2026 •

Copy link
Copy Markdown

Adds custom trust roots and a client certificate/key to the TLS transport. These options require a rustls-tls-aws-lc or rustls-tls-ring feature.

Option Value
clickhouse.client.tls_root_certs PEM root bundle that replaces the built-in roots
clickhouse.client.tls_client_cert PEM client certificate, with any intermediate certificates needed by the server
clickhouse.client.tls_client_key PEM private key for the client certificate

Options can be set on a database or passed to new_connection_with_opts(). The transport is fixed when the connection is created. A declared TLS option requires an HTTPS URI; malformed PEM and an incomplete certificate/key pair return InvalidArguments. The key is redacted in Debug output and cannot be read back. The internal feature is _tls-mtls. PEM parsing uses the existing rustls::pki_types::pem::PemObject API.

The branch includes current main through a forward merge. It has no changelog addition.

The custom connector allows HTTPS, retains the 60-second TCP keepalive and two-second idle pool policy, and provides the Tokio pool timer. A new loopback TLS regression cell checks a driver request and idle socket closure.

Formatting and locked checks of all targets pass locally with default and all features. Tests run only in CI; hosted results, including the new cell, are pending. The loopback cell does not establish a successful query or mutual authentication with a ClickHouse server.


Note

Medium Risk
Touches connection TLS setup and secret handling (PEM keys); mistakes could break secure connections or leak credentials if read-back rules regress.

Overview
Adds custom TLS trust and client identity for Rustls builds (rustls-tls-aws-lc / rustls-tls-ring via internal _tls-mtls): three clickhouse.client.* options for a PEM root bundle that replaces built-in roots, plus optional mTLS cert/key pairs.

When any of these are set, connection creation merges database and new_connection_with_opts overrides, validates PEM (and paired cert/key), requires https, and swaps in a hyper-rustls HTTP client with a tailored rustls::ClientConfig. The transport is fixed after connect; changing TLS on an existing connection is rejected, and the client private key cannot be read back.

Cargo feature wiring now pulls optional rustls, hyper-rustls, and hyper-util, and README documents the new options. Unit/integration-style tests cover validation, https enforcement, and a loopback TLS handshake.

Reviewed by Cursor Bugbot for commit 48af568. Bugbot is set up for automated code reviews on this repo. Configure here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@geoHeil

geoHeil commented Oct 3, 2026

Copy link
Copy Markdown
Author

@CLAassistant check

A declared TLS option (root bundle, client certificate chain or client
private key) is now refused when the URI scheme is http, or when no URI is
set and the default http applies. The driver returns `InvalidArguments`
that names the option. Tests cover the refusal and an https URI that
still builds the connection.
@geoHeil

geoHeil commented Oct 23, 2026

Copy link
Copy Markdown
Author

Added a check: the driver now refuses a declared TLS option when the URI scheme is http.

@abonander abonander left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few nits, plus this needs to be rebased to fix the merge conflicts.

Comment thread CHANGELOG.md Resolved
Comment thread Cargo.toml Resolved
Comment thread src/options.rs Resolved

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

Fix All in Cursor

Reviewed by Cursor Bugbot for commit 0249b39. Configure here.

Comment thread src/tls.rs Resolved
Comment thread src/lib.rs Resolved
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

AI review gate — AI review passed

Clean review from: Cursor Bugbot.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants