feat:tofu certificate validation #193

lucasdbr05 · 2026-01-14T00:54:03Z

What does this merge request do?

This feature (see the reference issue #176) adds SSL certificate validation based on Trust On First Use (TOFU), storing the certificate on the first connection and verifying its consistency on subsequent connections.
It is implemented via the TofuStore trait, which allows customizable certificate persistence.

Introduces a refactored Trust On First Use (TOFU) implementation for SSL certificate verification.
Adds the TofuStore trait, allowing library consumers to provide their own certificate persistence mechanism.
Updates the Client configuration SSL client initialization flow to accept a TofuStore via ConfigBuilder.
Adds examples in examples directory and scripts to demonstrate how TOFU can be integrated and used in practice.

tnull

Took an initial quick look and added some comments (though have yet to do a full review). Though before I proceed, please rewrite the commit history to avoid changing the approach mid-history. Basically, you should try to avoid to touch the same code paths in following commits as far as possible.

Given the code structure and verbosity I'm also suspecting that some form of AI agent was involved here. If this is indeed the case, please note that it is best practice to disclose such use in the PR and commit descriptions.

tnull · 2026-01-14T11:23:00Z

src/tofu/mod.rs

+
+/// A trait for storing and retrieving TOFU (Trust On First Use) certificate data.
+/// Implementors of this trait are responsible for persisting certificate data and retrieving it based on the host.
+pub trait TofuStore: Send + Sync + Debug {


Why does this need to be Send + Sync?

I did it this way to ensure that the Client remains thread-safe for concurrent applications, so I designed it to allow the store to be shared and safely accessed across multiple threads via an Arc.

I guess? Though the Rust compiler should usually infer the bounds when needed.

tnull · 2026-01-14T11:24:51Z

src/config.rs

    /// when ssl, validate the domain, default true
    validate_domain: bool,
+    /// TOFU store for certificate validation
+    tofu_store: Option<Arc<dyn TofuStore>>,


As mentioned over at the issue, it would likely be preferable to add this via a separate constructor. Having an Arc<dyn ..> in a config is rather odd, as it mixes code and data, basically.

tnull · 2026-01-14T11:26:35Z

src/raw_client.rs

            .connect(&domain, stream)
            .map_err(Error::SslHandshakeError)?;

+        if !validate_domain {


Not quite sure why we here error out? Care to explain?

tnull · 2026-01-14T11:27:14Z

src/raw_client.rs

+        builder.set_verify(SslVerifyMode::NONE);
+        let connector = builder.build();
+
+        let domain = socket_addrs.domain().unwrap_or("NONE").to_string();


No, if we don't have a domain we should just abort rather than try to connect to NONE?

That makes sense, I’ll update it.

lucasdbr05 · 2026-01-15T04:58:44Z

Took an initial quick look and added some comments (though have yet to do a full review). Though before I proceed, please rewrite the commit history to avoid changing the approach mid-history. Basically, you should try to avoid to touch the same code paths in following commits as far as possible.

Given the code structure and verbosity I'm also suspecting that some form of AI agent was involved here. If this is indeed the case, please note that it is best practice to disclose such use in the PR and commit descriptions.

First of all, thanks for the feedback. When rewriting the history, the best approach would be to avoid keeping commits that record my refactor from persistence-based usage to the trait-based approach, right?

tnull · 2026-01-15T08:46:27Z

When rewriting the history, the best approach would be to avoid keeping commits that record my refactor from persistence-based usage to the trait-based approach, right?

Yes, this would be preferable. Basically, you could just do a git reset and then commit the individual pieces again.

oleonardolima

I agree with tnull's comments above, you should narrow it down to few commits, for example: feat(tofu): add tofu store mod; feat(client): add new tofu method/feature, docs(example): add new tofu example.

Also, it's best if it's added under a new feature, and by a separate constructor. I don't think many changes to already-existing methods are needed, maybe it's something remaining from previous changes you did.

It's failing in CI, please make sure that everything is building successfully and passing CI too.

oleonardolima · 2026-01-19T19:37:37Z

src/raw_client.rs


        let builder = ClientConfig::builder();

+        let domain = socket_addr.domain().unwrap_or("NONE").to_string();


Same as tnull's previous comment, it should error-out and it's been handled below.

oleonardolima · 2026-01-19T19:41:17Z

src/raw_client.rs

+            let error_msg = format!("{}", e);
+            if error_msg.contains("TLS certificate changed") {
+                Error::TlsCertificateChanged(domain.clone())
+            } else if error_msg.contains("TOFU") {
+                Error::TofuPersistError(error_msg)
+            } else {
+                Error::CouldNotCreateConnection(e)
+            }


IMHO it's not ideal to handle the error variants by checking if it contains certain strings on it, you should properly return an map a new error variant where needed.

Trust On First Use (TOFU) is a security model where a client trusts a certificate upon the first connection and subsequent connections are verified against that initially stored record. - Introduce the trait to manage certificates - Add module and export the trait in the library root

- Update signature to accept an optional - Implement for both OpenSSL and Rustls - Add custom certificate verifier for Rustls (with AI help) - Extend enum with error variants specifics to TOFU - Support TOFU validation in proxy SSL connections

Implemented a dedicated constructor in the to handle Trust On First Use (TOFU) certificate validation. - New method to initialize a client with TOFU from config - Update existing constructors to support the revised SSL backend signatures

- Implement for testing purposes - Add comprehensive tests covering first-use storage, certificate matching/replacement, and large payloads NOTE: Unit tests and supporting mock implementation were created with AI assistance.

- Provide an usage example for the trait - Demonstrate how to initialize a using - Include a sample in-memory store implementation for demonstration purposes

lucasdbr05 mentioned this pull request Jan 14, 2026

feat: check it out and use "TOFU" (trust on first use) for self-signed certificates #176

Open

lucasdbr05 changed the title ~~Feat/tofu certificate validation~~ feat:tofu certificate validation Jan 14, 2026

tnull reviewed Jan 14, 2026

View reviewed changes

luisschwab self-requested a review January 17, 2026 20:32

oleonardolima self-requested a review January 19, 2026 17:54

oleonardolima assigned lucasdbr05 Jan 19, 2026

oleonardolima added the new feature New feature or request label Jan 19, 2026

oleonardolima added this to BDK Chain Jan 19, 2026

oleonardolima moved this to Discussion in BDK Chain Jan 19, 2026

oleonardolima reviewed Jan 19, 2026

View reviewed changes

lucasdbr05 added 5 commits January 21, 2026 00:28

test(tofu): add unit tests for TofuStore trait

f1dd212

- Implement for testing purposes - Add comprehensive tests covering first-use storage, certificate matching/replacement, and large payloads NOTE: Unit tests and supporting mock implementation were created with AI assistance.

feat(example): add TOFU certificate validation example

42639ae

- Provide an usage example for the trait - Demonstrate how to initialize a using - Include a sample in-memory store implementation for demonstration purposes

lucasdbr05 force-pushed the feat/TOFU-certificate-validation branch from 9178ff9 to 42639ae Compare January 21, 2026 04:06


		let builder = ClientConfig::builder();

		let domain = socket_addr.domain().unwrap_or("NONE").to_string();

feat:tofu certificate validation #193

Are you sure you want to change the base?

feat:tofu certificate validation #193

Conversation

lucasdbr05 commented Jan 14, 2026

What does this merge request do?

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lucasdbr05 commented Jan 15, 2026

Uh oh!

tnull commented Jan 15, 2026

Uh oh!

oleonardolima left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oleonardolima Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

oleonardolima Jan 19, 2026 •

edited

Loading