rustls-letsencrypt 0.1.2

Automatic Let's Encrypt, ACME, and local-CA certificate management for rustls listeners
Documentation
use std::{path::{Path, PathBuf}, sync::{Arc, atomic::{AtomicU64, Ordering}}};

use async_trait::async_trait;
use serde::{Deserialize, Serialize, de::DeserializeOwned};
use sha2::{Digest, Sha256};
use tokio::sync::{Mutex, broadcast};
use url::Url;

use crate::{DnsName, StoreError, StoredCertificate, StoredLocalCa};

#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct StoreRevision(pub u64);

#[derive(Clone, Copy, Debug, Default)]
pub struct StoreCapabilities { pub transactions: bool, pub change_notifications: bool, pub multi_process_writers: bool, pub durable_quarantine: bool }

#[derive(Clone, Debug)]
pub enum StoreChange { AcmeCertificate(DnsName), LocalCertificate(DnsName), LocalCa, Account(String) }

pub type StoreChangeStream = broadcast::Receiver<StoreChange>;

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct StoredAccount { pub directory_url: Url, pub credentials_json: serde_json::Value }

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct StoredRetryState { pub domain: DnsName, pub issuer_id: String, pub failures: u32, pub retry_at: i64 }

#[async_trait]
pub trait CertStore: Send + Sync + 'static {
    fn acme(&self) -> &dyn AcmeStoreNamespace;
    fn local(&self) -> &dyn LocalStoreNamespace;
    fn subscribe_changes(&self) -> StoreChangeStream;
    fn capabilities(&self) -> StoreCapabilities;
}

#[async_trait]
pub trait AcmeStoreNamespace: Send + Sync {
    async fn load_certificate(&self, name: &DnsName, issuer: &str) -> Result<Option<StoredCertificate>, StoreError>;
    async fn list_certificates(&self) -> Result<Vec<StoredCertificate>, StoreError>;
    async fn commit_certificate(&self, cert: &StoredCertificate) -> Result<StoreRevision, StoreError>;
    async fn remove_certificate(&self, name: &DnsName, issuer: &str) -> Result<StoreRevision, StoreError>;
    async fn quarantine_certificate(&self, cert: &StoredCertificate, reason: &str) -> Result<StoreRevision, StoreError>;
    async fn load_account(&self, directory: &Url) -> Result<Option<StoredAccount>, StoreError>;
    async fn save_account(&self, account: &StoredAccount) -> Result<StoreRevision, StoreError>;
    async fn load_retry_state(&self, name: &DnsName, issuer: &str) -> Result<Option<StoredRetryState>, StoreError>;
    async fn save_retry_state(&self, state: &StoredRetryState) -> Result<StoreRevision, StoreError>;
}

#[async_trait]
pub trait LocalStoreNamespace: Send + Sync {
    async fn load_certificate(&self, name: &DnsName) -> Result<Option<StoredCertificate>, StoreError>;
    async fn list_certificates(&self) -> Result<Vec<StoredCertificate>, StoreError>;
    async fn commit_certificate(&self, cert: &StoredCertificate) -> Result<StoreRevision, StoreError>;
    async fn remove_certificate(&self, name: &DnsName) -> Result<StoreRevision, StoreError>;
    async fn quarantine_certificate(&self, cert: &StoredCertificate, reason: &str) -> Result<StoreRevision, StoreError>;
    async fn load_ca(&self) -> Result<Option<(StoreRevision, StoredLocalCa)>, StoreError>;
    async fn compare_and_swap_ca(&self, expected: Option<StoreRevision>, replacement: &StoredLocalCa) -> Result<StoreRevision, StoreError>;
    async fn load_retry_state(&self, name: &DnsName) -> Result<Option<StoredRetryState>, StoreError>;
    async fn save_retry_state(&self, state: &StoredRetryState) -> Result<StoreRevision, StoreError>;
}

pub struct FolderCertStore {
    root: PathBuf,
    write_lock: Mutex<()>,
    revision: AtomicU64,
    changes: broadcast::Sender<StoreChange>,
}

impl FolderCertStore {
    pub async fn open(path: impl Into<PathBuf>) -> Result<Self, StoreError> {
        let root = path.into();
        for child in ["accounts", "ACME", "Local", "quarantine/ACME", "quarantine/Local", "retry/ACME", "retry/Local"] {
            tokio::fs::create_dir_all(root.join(child)).await?;
        }
        let (changes, _) = broadcast::channel(256);
        Ok(Self { root, write_lock: Mutex::new(()), revision: AtomicU64::new(1), changes })
    }

    #[must_use] pub fn root(&self) -> &Path { &self.root }
    fn next_revision(&self) -> StoreRevision { StoreRevision(self.revision.fetch_add(1, Ordering::SeqCst)) }
    fn cert_file(&self, namespace: &str, name: &DnsName, issuer: Option<&str>) -> PathBuf {
        let key = match issuer { Some(i) => format!("{}\0{i}", name.as_str()), None => name.as_str().to_owned() };
        self.root.join(namespace).join(format!("{}.json", hash_name(&key)))
    }
    async fn read_json<T: DeserializeOwned>(&self, path: &Path) -> Result<Option<T>, StoreError> {
        match tokio::fs::read(path).await {
            Ok(bytes) => Ok(Some(serde_json::from_slice(&bytes)?)),
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
            Err(e) => Err(e.into()),
        }
    }
    async fn write_json<T: Serialize + Sync>(&self, path: &Path, value: &T, secret: bool) -> Result<(), StoreError> {
        let bytes = serde_json::to_vec_pretty(value)?;
        self.atomic_write(path, &bytes, secret).await
    }
    async fn atomic_write(&self, path: &Path, bytes: &[u8], secret: bool) -> Result<(), StoreError> {
        let parent = path.parent().ok_or_else(|| StoreError::Corrupt("path has no parent".into()))?;
        tokio::fs::create_dir_all(parent).await?;
        let temp = parent.join(format!(".{}.{}.tmp", path.file_name().and_then(|v| v.to_str()).unwrap_or("record"), self.revision.load(Ordering::Relaxed)));
        let mut options = tokio::fs::OpenOptions::new();
        options.create_new(true).write(true);
        #[cfg(unix)] { options.mode(if secret { 0o600 } else { 0o644 }); }
        let mut file = options.open(&temp).await?;
        use tokio::io::AsyncWriteExt;
        file.write_all(bytes).await?;
        file.sync_all().await?;
        drop(file);
        tokio::fs::rename(&temp, path).await?;
        Ok(())
    }
    async fn list_json<T: DeserializeOwned>(&self, dir: &Path) -> Result<Vec<T>, StoreError> {
        let mut entries = tokio::fs::read_dir(dir).await?;
        let mut values = Vec::new();
        while let Some(entry) = entries.next_entry().await? {
            if entry.path().extension().is_some_and(|v| v == "json") {
                if let Some(value) = self.read_json(&entry.path()).await? { values.push(value); }
            }
        }
        Ok(values)
    }
    async fn remove_file(&self, path: &Path) -> Result<(), StoreError> {
        match tokio::fs::remove_file(path).await { Ok(()) => Ok(()), Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()), Err(e) => Err(e.into()) }
    }
}

impl CertStore for FolderCertStore {
    fn acme(&self) -> &dyn AcmeStoreNamespace { self }
    fn local(&self) -> &dyn LocalStoreNamespace { self }
    fn subscribe_changes(&self) -> StoreChangeStream { self.changes.subscribe() }
    fn capabilities(&self) -> StoreCapabilities { StoreCapabilities { transactions: false, change_notifications: true, multi_process_writers: false, durable_quarantine: true } }
}

#[async_trait]
impl AcmeStoreNamespace for FolderCertStore {
    async fn load_certificate(&self, name: &DnsName, issuer: &str) -> Result<Option<StoredCertificate>, StoreError> { self.read_json(&self.cert_file("ACME", name, Some(issuer))).await }
    async fn list_certificates(&self) -> Result<Vec<StoredCertificate>, StoreError> { self.list_json(&self.root.join("ACME")).await }
    async fn commit_certificate(&self, cert: &StoredCertificate) -> Result<StoreRevision, StoreError> { let _g = self.write_lock.lock().await; self.write_json(&self.cert_file("ACME", &cert.primary_name, Some(&cert.issuer_id)), cert, true).await?; let r = self.next_revision(); let _ = self.changes.send(StoreChange::AcmeCertificate(cert.primary_name.clone())); Ok(r) }
    async fn remove_certificate(&self, name: &DnsName, issuer: &str) -> Result<StoreRevision, StoreError> { let _g = self.write_lock.lock().await; self.remove_file(&self.cert_file("ACME", name, Some(issuer))).await?; Ok(self.next_revision()) }
    async fn quarantine_certificate(&self, cert: &StoredCertificate, reason: &str) -> Result<StoreRevision, StoreError> { let _g = self.write_lock.lock().await; let p = self.root.join("quarantine/ACME").join(format!("{}-{}.json", hash_name(cert.primary_name.as_str()), hash_name(reason))); self.write_json(&p, cert, true).await?; self.remove_file(&self.cert_file("ACME", &cert.primary_name, Some(&cert.issuer_id))).await?; Ok(self.next_revision()) }
    async fn load_account(&self, directory: &Url) -> Result<Option<StoredAccount>, StoreError> { self.read_json(&self.root.join("accounts").join(format!("{}.json", hash_name(directory.as_str())))).await }
    async fn save_account(&self, account: &StoredAccount) -> Result<StoreRevision, StoreError> { let _g = self.write_lock.lock().await; self.write_json(&self.root.join("accounts").join(format!("{}.json", hash_name(account.directory_url.as_str()))), account, true).await?; Ok(self.next_revision()) }
    async fn load_retry_state(&self, name: &DnsName, issuer: &str) -> Result<Option<StoredRetryState>, StoreError> { self.read_json(&self.root.join("retry/ACME").join(format!("{}.json", hash_name(&format!("{name}\0{issuer}"))))).await }
    async fn save_retry_state(&self, state: &StoredRetryState) -> Result<StoreRevision, StoreError> { let _g = self.write_lock.lock().await; self.write_json(&self.root.join("retry/ACME").join(format!("{}.json", hash_name(&format!("{}\0{}", state.domain, state.issuer_id)))), state, false).await?; Ok(self.next_revision()) }
}

#[async_trait]
impl LocalStoreNamespace for FolderCertStore {
    async fn load_certificate(&self, name: &DnsName) -> Result<Option<StoredCertificate>, StoreError> { self.read_json(&self.cert_file("Local", name, None)).await }
    async fn list_certificates(&self) -> Result<Vec<StoredCertificate>, StoreError> { self.list_json(&self.root.join("Local")).await }
    async fn commit_certificate(&self, cert: &StoredCertificate) -> Result<StoreRevision, StoreError> { let _g = self.write_lock.lock().await; self.write_json(&self.cert_file("Local", &cert.primary_name, None), cert, true).await?; let r = self.next_revision(); let _ = self.changes.send(StoreChange::LocalCertificate(cert.primary_name.clone())); Ok(r) }
    async fn remove_certificate(&self, name: &DnsName) -> Result<StoreRevision, StoreError> { let _g = self.write_lock.lock().await; self.remove_file(&self.cert_file("Local", name, None)).await?; Ok(self.next_revision()) }
    async fn quarantine_certificate(&self, cert: &StoredCertificate, reason: &str) -> Result<StoreRevision, StoreError> { let _g = self.write_lock.lock().await; let p = self.root.join("quarantine/Local").join(format!("{}-{}.json", hash_name(cert.primary_name.as_str()), hash_name(reason))); self.write_json(&p, cert, true).await?; self.remove_file(&self.cert_file("Local", &cert.primary_name, None)).await?; Ok(self.next_revision()) }
    async fn load_ca(&self) -> Result<Option<(StoreRevision, StoredLocalCa)>, StoreError> {
        let cert = tokio::fs::read_to_string(self.root.join("Local/CA.pem")).await;
        let key = tokio::fs::read_to_string(self.root.join("Local/CA.key")).await;
        match (cert, key) {
            (Err(a), Err(b)) if a.kind() == std::io::ErrorKind::NotFound && b.kind() == std::io::ErrorKind::NotFound => Ok(None),
            (Ok(c), Ok(k)) => { let ca = StoredLocalCa::from_pem(c, k).map_err(|e| StoreError::Corrupt(e.to_string()))?; Ok(Some((StoreRevision(1), ca))) }
            (Err(e), _) | (_, Err(e)) if e.kind() == std::io::ErrorKind::NotFound => Err(StoreError::Corrupt("Local/CA.pem and Local/CA.key must both exist".into())),
            (Err(e), _) | (_, Err(e)) => Err(e.into()),
        }
    }
    async fn compare_and_swap_ca(&self, expected: Option<StoreRevision>, replacement: &StoredLocalCa) -> Result<StoreRevision, StoreError> { let _g = self.write_lock.lock().await; let current_exists = tokio::fs::try_exists(self.root.join("Local/CA.pem")).await?; if expected.is_none() && current_exists { return Err(StoreError::Conflict); } self.atomic_write(&self.root.join("Local/CA.pem"), replacement.certificate_pem.as_bytes(), false).await?; self.atomic_write(&self.root.join("Local/CA.key"), replacement.private_key_pem.expose().as_bytes(), true).await?; let r = self.next_revision(); let _ = self.changes.send(StoreChange::LocalCa); Ok(r) }
    async fn load_retry_state(&self, name: &DnsName) -> Result<Option<StoredRetryState>, StoreError> { self.read_json(&self.root.join("retry/Local").join(format!("{}.json", hash_name(name.as_str())))).await }
    async fn save_retry_state(&self, state: &StoredRetryState) -> Result<StoreRevision, StoreError> { let _g = self.write_lock.lock().await; self.write_json(&self.root.join("retry/Local").join(format!("{}.json", hash_name(state.domain.as_str()))), state, false).await?; Ok(self.next_revision()) }
}

fn hash_name(value: &str) -> String { Sha256::digest(value.as_bytes()).iter().map(|b| format!("{b:02x}")).collect() }

impl From<FolderCertStore> for Arc<dyn CertStore> { fn from(value: FolderCertStore) -> Self { Arc::new(value) } }

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{CertificateProvenance, cert::SecretPem};

    fn record(name: &str, provenance: CertificateProvenance, issuer: &str) -> StoredCertificate {
        StoredCertificate {
            schema_version: 1, primary_name: DnsName::parse(name).unwrap(), sans: vec![DnsName::parse(name).unwrap()],
            private_key_pem: SecretPem::new("secret".into()), leaf_pem: "leaf".into(), chain_pem: vec![],
            not_before: 1, not_after: 2, stored_at: 1, provenance, issuer_id: issuer.into(), fingerprint_sha256: "fp".into(), local_ca_fingerprint_sha256: None,
        }
    }

    #[tokio::test]
    async fn namespaces_coexist() {
        let directory = tempfile::tempdir().unwrap();
        let store = FolderCertStore::open(directory.path()).await.unwrap();
        let acme = record("example.com", CertificateProvenance::Acme, "staging");
        let local = record("example.com", CertificateProvenance::Local, "AcmeLocalCA");
        store.acme().commit_certificate(&acme).await.unwrap();
        store.local().commit_certificate(&local).await.unwrap();
        assert_eq!(store.acme().load_certificate(&DnsName::parse("example.com").unwrap(), "staging").await.unwrap().unwrap().provenance, CertificateProvenance::Acme);
        assert_eq!(store.local().load_certificate(&DnsName::parse("example.com").unwrap()).await.unwrap().unwrap().provenance, CertificateProvenance::Local);
    }
}