feat(tofu): add option for Trust On First Use validation for SSL connections

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.

This commit introduces the following features:

- `TofuStore` trait to manage certificates
- Implement TOFU validations both for OpenSSL and Rustls configurations
- Add custom certificate verifier for Rustls
- Support TOFU validation in proxy SSL connections
- Extend enum with error variants specifics to TOFU
- New method to initialize a client with TOFU from config
- Update existing constructors to support the revised SSL backend signatures
- Add some unit tests related to TOFU. The tests cover the following cases: first-use storage and certificate matching/replacement
- Add a TOFU certificates validation example, based on a in-memory store implementation for demonstration purposes

NOTE: Unit tests, supporting mock implementation, and the custom verifier for Rustls were created with AI assistance.

Author: lucasdbr05

examples/tofu.rs

@@ -0,0 +1,39 @@
+extern crate electrum_client;
+
+use electrum_client::{Client, Config, ElectrumApi, TofuStore};
+use std::collections::HashMap;
+use std::io::Result;
+use std::sync::{Arc, Mutex};
+
+/// A simple in-memory implementation of TofuStore for demonstration purposes.
+#[derive(Debug, Default)]
+struct MyTofuStore {
+    certs: Mutex<HashMap<String, Vec<u8>>>,
+}
+
+impl TofuStore for MyTofuStore {
+    fn get_certificate(&self, host: &str) -> Result<Option<Vec<u8>>> {
+        let certs = self.certs.lock().unwrap();
+        Ok(certs.get(host).cloned())
+    }
+
+    fn set_certificate(&self, host: &str, cert: Vec<u8>) -> Result<()> {
+        let mut certs = self.certs.lock().unwrap();
+        certs.insert(host.to_string(), cert);
+        Ok(())
+    }
+}
+
+fn main() {
+    let store = Arc::new(MyTofuStore::default());
+
+    let client = Client::from_config_with_tofu(
+        "ssl://electrum.blockstream.info:50002",
+        Config::default(),
+        store,
+    )
+    .unwrap();
+
+    let res = client.server_features();
+    println!("{:#?}", res);
+}

src/client.rs

@@ -1,5 +1,6 @@
 //! Electrum Client
 
+use std::sync::Arc;
 use std::{borrow::Borrow, sync::RwLock};
 
 use log::{info, warn};
@@ -10,6 +11,7 @@ use crate::api::ElectrumApi;
 use crate::batch::Batch;
 use crate::config::Config;
 use crate::raw_client::*;
+use crate::tofu::TofuStore;
 use crate::types::*;
 use std::convert::TryFrom;
 
@@ -35,6 +37,7 @@ pub struct Client {
     client_type: RwLock<ClientType>,
     config: Config,
     url: String,
+    tofu_store: Option<Arc<dyn TofuStore>>,
 }
 
 macro_rules! impl_inner_call {
@@ -74,7 +77,7 @@ macro_rules! impl_inner_call {
                     if let Ok(mut write_client) = $self.client_type.try_write() {
                         loop {
                             std::thread::sleep(std::time::Duration::from_secs((1 << errors.len()).min(30) as u64));
-                            match ClientType::from_config(&$self.url, &$self.config) {
+                            match ClientType::from_config(&$self.url, &$self.config, $self.tofu_store.clone()) {
                                 Ok(new_client) => {
                                     info!("Succesfully created new client");
                                     *write_client = new_client;
@@ -111,7 +114,11 @@ fn retries_exhausted(failed_attempts: usize, configured_retries: u8) -> bool {
 impl ClientType {
     /// Constructor that supports multiple backends and allows configuration through
     /// the [Config]
-    pub fn from_config(url: &str, config: &Config) -> Result<Self, Error> {
+    pub fn from_config(
+        url: &str,
+        config: &Config,
+        tofu_store: Option<Arc<dyn TofuStore>>,
+    ) -> Result<Self, Error> {
         #[cfg(any(feature = "openssl", feature = "rustls", feature = "rustls-ring"))]
         if url.starts_with("ssl://") {
             let url = url.replacen("ssl://", "", 1);
@@ -122,14 +129,22 @@ impl ClientType {
                     config.validate_domain(),
                     socks5,
                     config.timeout(),
+                    tofu_store,
+                )?,
+                None => RawClient::new_ssl(
+                    url.as_str(),
+                    config.validate_domain(),
+                    config.timeout(),
+                    tofu_store,
                 )?,
-                None => {
-                    RawClient::new_ssl(url.as_str(), config.validate_domain(), config.timeout())?
-                }
             };
             #[cfg(not(feature = "proxy"))]
-            let client =
-                RawClient::new_ssl(url.as_str(), config.validate_domain(), config.timeout())?;
+            let client = RawClient::new_ssl(
+                url.as_str(),
+                config.validate_domain(),
+                config.timeout(),
+                tofu_store,
+            )?;
 
             return Ok(ClientType::SSL(client));
         }
@@ -142,6 +157,12 @@ impl ClientType {
         }
 
         {
+            if tofu_store.is_some() {
+                return Err(Error::Message(
+                    "TOFU validation is available only for SSL connections".to_string(),
+                ));
+            }
+
             let url = url.replacen("tcp://", "", 1);
             #[cfg(feature = "proxy")]
             let client = match config.socks5() {
@@ -178,12 +199,34 @@ impl Client {
     /// Generic constructor that supports multiple backends and allows configuration through
     /// the [Config]
     pub fn from_config(url: &str, config: Config) -> Result<Self, Error> {
-        let client_type = RwLock::new(ClientType::from_config(url, &config)?);
+        let client_type = RwLock::new(ClientType::from_config(url, &config, None)?);
+
+        Ok(Client {
+            client_type,
+            config,
+            url: url.to_string(),
+            tofu_store: None,
+        })
+    }
+
+    /// Creates a new client with TOFU (Trust On First Use) certificate validation.
+    /// This constructor creates a SSL client that uses TOFU for certificate validation.
+    pub fn from_config_with_tofu(
+        url: &str,
+        config: Config,
+        tofu_store: Arc<dyn TofuStore>,
+    ) -> Result<Self, Error> {
+        let client_type = RwLock::new(ClientType::from_config(
+            url,
+            &config,
+            Some(tofu_store.clone()),
+        )?);
 
         Ok(Client {
             client_type,
             config,
             url: url.to_string(),
+            tofu_store: Some(tofu_store),
         })
     }
 }

src/lib.rs

@@ -60,3 +60,6 @@ pub use batch::Batch;
 pub use client::*;
 pub use config::{Config, ConfigBuilder, Socks5Config};
 pub use types::*;
+
+mod tofu;
+pub use tofu::TofuStore;