feat:tofu certificate validation by lucasdbr05 · Pull Request #193 · bitcoindevkit/rust-electrum-client

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.

src/config.rs

src/raw_client.rs

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.

src/raw_client.rs

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

tnull · 2026-02-10T09:27:10Z

src/tofu/mod.rs

+    /// Retrieves the certificate for the given host.
+    /// Returns `Ok(Some(cert))` if a certificate is found, `Ok(None)` if no certificate
+    /// is stored for this host, or an error if the operation fails.
+    fn get_certificate(&self, host: &str) -> Result<Option<Vec<u8>>, Box<dyn Send + Sync + Error>>;


Can we avoid the Box<dyn ..> error and simply make this a std::io::Error?

tnull · 2026-02-10T09:28:30Z

src/lib.rs

 pub use config::{Config, ConfigBuilder, Socks5Config};
 pub use types::*;
+
+mod tofu;


I guess we want to feature-gate the whole module?

tnull · 2026-02-10T09:33:20Z

src/raw_client.rs

    }
+
+    /// Creates a new SSL client with TOFU from an existing TcpStream
+    fn new_ssl_with_tofu_from_stream<A: ToSocketAddrsDomain>(


Can we DRY this up with new_ssl_from_stream?

tnull · 2026-02-10T09:33:44Z

src/raw_client.rs

+    pub struct TofuVerifier {
+        provider: CryptoProvider,
+        host: String,
+        tofu_store: std::sync::Arc<dyn TofuStore>,


nit: Just import std::sync::Arc above.

tnull · 2026-02-10T09:39:28Z

src/raw_client.rs

+            _now: UnixTime,
+        ) -> Result<ServerCertVerified, rustls::Error> {
+            // Verify using TOFU
+            self.verify_tofu(end_entity.as_ref())


Shouldn't we also offer a mode where the TofuVerifier just wraps the rustls verifier, i.e., we'd still also validate the certificate as usual if validate_domain is set? Or do we think that wouldn't ever be used, and doing only TOFU would suffice?

tnull · 2026-02-10T09:40:14Z

src/raw_client.rs

    }
+
+    /// Creates a new SSL client with TOFU from an existing TcpStream
+    fn new_ssl_with_tofu_from_stream(


It seems this could also get somewhat DRYed up?

tnull · 2026-02-10T09:41:58Z

src/client.rs

+
+    /// Constructor that supports TOFU (Trust On First Use) certificate validation.
+    /// Only works with SSL connections.
+    pub fn from_config_with_tofu(


Same here, please DRY this up, do the additional thing, and then call in to Self::from_config. If that isn't easily possible, extract the common behavior into an _inner method and reuse that by both constructors (similarly elsewhere) to keep the code DRY.

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

src/raw_client.rs Outdated Show resolved Hide resolved

src/raw_client.rs Outdated Show resolved Hide resolved

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

lucasdbr05 requested review from oleonardolima and tnull February 5, 2026 22:00

tnull reviewed Feb 10, 2026

View reviewed changes

oleonardolima moved this from Discussion to Needs Review in BDK Chain Feb 10, 2026

oleonardolima added the api API breaking change label Feb 10, 2026

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!

Uh oh!

Uh oh!

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!

Uh oh!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants