didbot_tls/

local.rs

//! A certificate authority for a zone no public authority can issue for.
//!
//! A server always serves TLS, including on a developer's machine. A
//! `.localhost` zone has no public DNS, so ACME cannot complete a challenge
//! for it; this module is where its certificate comes from instead.
//!
//! The authority lives in a directory of its own, one per machine rather
//! than one per server: a developer trusts its certificate once, and every
//! local server on that machine then presents leaves it signed. It signs a
//! `<zone>` + `*.<zone>` leaf for each configured zone, cached in the data
//! directory when there is one and signed afresh at every start when there
//! is not.
//!
//! # What makes this safe to put in a trust store
//!
//! A developer installs this certificate into their own trust store, so it
//! can vouch for names on their machine the way a public authority vouches
//! for names on the internet. Two things bound what it can vouch for:
//!
//! * The certificate carries a name constraint permitting `localhost` and
//!   everything under it, and nothing else. A verifier that honours name
//!   constraints — rustls, and the browsers — refuses a leaf from this
//!   authority for any other name, so a key that leaks cannot be used to
//!   impersonate a real site.
//! * [`crate::source`] refuses this mode for any zone that is not under
//!   `.localhost`, so the authority is never asked to issue outside that
//!   constraint in the first place.
//!
//! The key still belongs to whoever can read the data directory, which is
//! why it is written `0600` and why the directory is `0700`.

use std::path::{Path, PathBuf};
use std::sync::Arc;

use rcgen::{
    BasicConstraints, CertificateParams, DistinguishedName, DnType, ExtendedKeyUsagePurpose,
    GeneralSubtree, IsCa, Issuer, KeyPair, KeyUsagePurpose, NameConstraints,
};
use rustls::pki_types::pem::PemObject;
use rustls::pki_types::CertificateDer;
use time::{Duration, OffsetDateTime};

use crate::cert::{certified_key_from_pem, leaf_expiry, CertError};
use crate::fleet::{FleetError, ZoneResolver};
use crate::resolver::SwappableCert;
use crate::storage::{CaStore, CertMeta, CertStore, StorageError};

/// What [`CertMeta::directory_url`] records for a leaf this module signed,
/// where an ACME leaf records the directory that issued it. No ACME
/// directory URL can collide with it: they are absolute `https://` URLs.
pub const LOCAL_SOURCE: &str = "local";

/// The subject of the authority's own certificate, and what a developer sees
/// in their trust store's list.
pub const CA_COMMON_NAME: &str = "didbot local development authority";

/// The one name this authority may vouch for, plus everything under it.
/// Written into the certificate as an RFC 5280 name constraint, so a
/// verifier enforces it rather than taking this module's word for it.
const PERMITTED_SUBTREE: &str = "localhost";

/// How long the authority's own certificate is good for.
///
/// Five years: long enough that trusting it is a one-time step rather than a
/// recurring chore, short enough that a key a developer forgot about stops
/// working eventually. A run past the expiry generates a new authority,
/// which has to be trusted again.
pub const CA_VALIDITY: Duration = Duration::days(5 * 365);

/// How long a zone's leaf is good for. Under the 398 days browsers accept,
/// and short enough that a leaf outlives neither the machine it was minted
/// on nor anyone's memory of minting it.
pub const LEAF_VALIDITY: Duration = Duration::days(90);

/// How close to a leaf's expiry a start signs a fresh one rather than
/// serving what is on disk. There is no renewal loop here: signing costs a
/// few milliseconds and needs nothing off this machine, so a start does it
/// whenever the answer is in doubt.
pub const LEAF_REISSUE_BEFORE: Duration = Duration::days(30);

/// Backdating on both the authority and the leaves, so a machine whose clock
/// is a little behind the one that signed still accepts them.
const CLOCK_SKEW: Duration = Duration::hours(1);

/// Why a local certificate could not be generated, loaded or served.
#[derive(Debug, thiserror::Error)]
pub enum LocalError {
    /// The data directory could not be read or written.
    #[error("data directory: {0}")]
    Storage(#[from] StorageError),
    /// Generating or signing a certificate failed.
    #[error("generating a local certificate: {0}")]
    Generate(#[from] rcgen::Error),
    /// A certificate this module just signed or loaded could not be turned
    /// into something `rustls` can serve.
    #[error("the local certificate this run signed or loaded: {0}")]
    Cert(#[from] CertError),
    /// The zones could not be assembled into one resolver.
    #[error("{0}")]
    Fleet(#[from] FleetError),
    /// A zone this mode was asked to serve is not one it may serve. Carries
    /// [`crate::source::CertificateSource::refusal_for`]'s sentence.
    #[error("{0}")]
    Refused(String),
}

/// This machine's own certificate authority, loaded from the data directory
/// or generated into it.
pub struct LocalAuthority {
    store: CaStore,
    issuer: Issuer<'static, KeyPair>,
    ca_pem: String,
    generated: bool,
}

impl std::fmt::Debug for LocalAuthority {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("LocalAuthority")
            .field("certificate", &self.certificate_path())
            .field("generated", &self.generated)
            .finish_non_exhaustive()
    }
}

impl LocalAuthority {
    /// The authority in `dir`, generated the first time and reused after.
    ///
    /// Reused means reused: a second start signs no new authority, so a
    /// developer trusts one certificate once rather than every time they
    /// restart a server.
    pub fn open(dir: &Path) -> Result<Self, LocalError> {
        let store = CaStore::open(dir)?;
        if let Some((ca_pem, key_pem)) = store.load()? {
            match KeyPair::from_pem(&key_pem) {
                Ok(key) => {
                    return Ok(Self {
                        issuer: Issuer::new(ca_params(OffsetDateTime::now_utc())?, key),
                        ca_pem,
                        store,
                        generated: false,
                    })
                }
                Err(error) => {
                    // A key that does not parse is a key nothing can sign
                    // with, so the alternative to replacing it is refusing
                    // to start. Loud, because every leaf signed by the old
                    // authority stops verifying and the certificate in the
                    // developer's trust store is now the wrong one.
                    tracing::warn!(
                        %error,
                        path = %store.certificate_path().display(),
                        "the local authority's key does not parse; generating a new authority, \
                         which has to be trusted again"
                    );
                }
            }
        }

        let key = KeyPair::generate()?;
        let params = ca_params(OffsetDateTime::now_utc())?;
        let ca_pem = params.self_signed(&key)?.pem();
        store.save(&ca_pem, &key.serialize_pem())?;
        Ok(Self {
            issuer: Issuer::new(params, key),
            ca_pem,
            store,
            generated: true,
        })
    }

    /// The authority certificate's path: the file to trust.
    pub fn certificate_path(&self) -> PathBuf {
        self.store.certificate_path()
    }

    /// Whether this run generated the authority rather than finding it.
    pub fn was_generated(&self) -> bool {
        self.generated
    }

    /// What to do with [`Self::certificate_path`], as lines to print.
    ///
    /// One instruction per tool that has its own trust store, because a
    /// machine does not have one: the system store covers `curl` and
    /// anything reading it, and the browsers and Node each keep their own.
    pub fn trust_instructions(&self) -> Vec<String> {
        let path = self.certificate_path();
        let path = path.display();
        vec![
            format!("sudo cp {path} /usr/local/share/ca-certificates/didbot-local.crt && sudo update-ca-certificates"),
            format!("certutil -d sql:$HOME/.pki/nssdb -A -t C,, -n didbot-local -i {path}"),
            format!("export DIDBOT_EXTRA_CA_CERTS={path} NODE_EXTRA_CA_CERTS={path}"),
        ]
    }

    /// A `<zone>` + `*.<zone>` certificate chain and key for `zone`, both
    /// PEM, signed now.
    ///
    /// The chain is the leaf followed by the authority, the order a public
    /// authority hands its own back in, so a client that already trusts the
    /// authority verifies from the leaf up without holding anything else.
    ///
    /// A wildcard matches exactly one label, which is why a zone needs its
    /// own certificate rather than one at the root; see [`crate::fleet`].
    pub fn issue(&self, zone: &str) -> Result<(String, String), LocalError> {
        self.issue_names(&[zone.to_owned(), format!("*.{zone}")])
    }

    /// A certificate for exactly `names`, for a caller that wants something
    /// other than a zone and its wildcard.
    ///
    /// A wildcard needs a name to sit under: `*.localhost` is not a DNS
    /// identifier a verifier will accept, so a server answering as
    /// `localhost` itself asks for that one name here.
    pub fn issue_names(&self, names: &[String]) -> Result<(String, String), LocalError> {
        let mut params = CertificateParams::new(names.to_vec())?;
        let now = OffsetDateTime::now_utc();
        params.not_before = now - CLOCK_SKEW;
        params.not_after = now + LEAF_VALIDITY;
        params.distinguished_name = DistinguishedName::new();
        params.distinguished_name.push(
            DnType::CommonName,
            names.first().cloned().unwrap_or_default(),
        );
        params.use_authority_key_identifier_extension = true;
        params.key_usages = vec![
            KeyUsagePurpose::DigitalSignature,
            KeyUsagePurpose::KeyEncipherment,
        ];
        params.extended_key_usages = vec![ExtendedKeyUsagePurpose::ServerAuth];

        let key = KeyPair::generate()?;
        let leaf = params.signed_by(&key, &self.issuer)?;
        Ok((
            format!("{}{}", leaf.pem(), self.ca_pem),
            key.serialize_pem(),
        ))
    }

    /// `zone`'s certificate: the one under `leaves` if this authority
    /// signed it and it has life left, and a freshly signed one otherwise,
    /// saved over it.
    ///
    /// `leaves` is a data directory, or `None` for a server that keeps
    /// nothing — which then signs a leaf at every start. Signing costs
    /// milliseconds and needs nothing off this machine, so a run with no
    /// data directory loses nothing by it.
    fn certificate_for(
        &self,
        zone: &str,
        leaves: Option<&Path>,
        provider: &rustls::crypto::CryptoProvider,
    ) -> Result<rustls::sign::CertifiedKey, LocalError> {
        if let Some(certified) = leaves.and_then(|dir| self.stored_certificate(zone, dir, provider))
        {
            tracing::debug!(zone, "reusing the local certificate on disk");
            return Ok(certified);
        }
        let (chain_pem, key_pem) = self.issue(zone)?;
        // Loaded before it is saved, so a pair that does not load is never
        // written where the next start reads it.
        let certified = certified_key_from_pem(&chain_pem, &key_pem, provider)?;
        if let Some(dir) = leaves {
            CertStore::open_zone(dir, zone)?.save_certificate(
                &chain_pem,
                &key_pem,
                &CertMeta {
                    directory_url: LOCAL_SOURCE.to_owned(),
                    issued_at: OffsetDateTime::now_utc(),
                },
            )?;
        }
        tracing::info!(zone, "signed a local certificate for this zone and *.zone");
        Ok(certified)
    }

    /// The stored certificate for `zone` if this run can serve it.
    ///
    /// `None` — sign a new one — covers every way it could be unusable, and
    /// they are not distinguished because the answer to all of them is the
    /// same: nothing saved, a set a crash left incomplete, a leaf from an
    /// ACME directory or from an authority this one replaced, one that does
    /// not load, and one close enough to expiry that this run would outlive
    /// it.
    fn stored_certificate(
        &self,
        zone: &str,
        leaves: &Path,
        provider: &rustls::crypto::CryptoProvider,
    ) -> Option<rustls::sign::CertifiedKey> {
        let store = CertStore::open_zone(leaves, zone).ok()?;
        let (chain_pem, key_pem, meta) = store.certificate().ok()??;
        if meta.directory_url != LOCAL_SOURCE {
            return None;
        }
        let certified = certified_key_from_pem(&chain_pem, &key_pem, provider).ok()?;
        // The authority at the end of the stored chain, against this run's:
        // a leaf whose authority was replaced verifies against nothing a
        // developer has trusted.
        if certified.cert.last()? != &self.certificate_der().ok()? {
            return None;
        }
        let expiry = leaf_expiry(&certified.cert).ok()?;
        (expiry - OffsetDateTime::now_utc() > LEAF_REISSUE_BEFORE).then_some(certified)
    }

    /// The authority's certificate as DER, for comparing a stored chain's
    /// last entry against.
    fn certificate_der(&self) -> Result<CertificateDer<'static>, CertError> {
        CertificateDer::pem_slice_iter(self.ca_pem.as_bytes())
            .next()
            .unwrap_or(Err(rustls::pki_types::pem::Error::NoItemsFound))
            .map_err(CertError::Chain)
    }
}

/// Every zone served from [`LocalAuthority`], behind the one SNI-dispatching
/// resolver a multi-zone deployment uses for ACME certificates.
///
/// No renewal loop: a certificate is signed at start whenever what is on
/// disk will not last, which is all a certificate nothing but this machine
/// trusts needs.
#[derive(Debug)]
pub struct LocalFleet {
    authority: LocalAuthority,
    resolver: Arc<ZoneResolver>,
}

impl LocalFleet {
    /// Loads or signs a certificate for every zone in `zones`, refusing any
    /// zone [`crate::source`] does not put under this authority.
    ///
    /// `ca_dir` holds the authority itself — one per machine — and `leaves`
    /// is the data directory the signed certificates are cached in, or
    /// `None` for a server that keeps nothing.
    ///
    /// The first entry in `zones` is the primary: the certificate a
    /// `ClientHello` with no server name gets.
    pub fn bootstrap(
        ca_dir: &Path,
        leaves: Option<&Path>,
        zones: &[String],
    ) -> Result<Self, LocalError> {
        let _ = rustls::crypto::ring::default_provider().install_default();
        let provider = rustls::crypto::ring::default_provider();

        for zone in zones {
            if let Some(refusal) = crate::source::CertificateSource::Local.refusal_for(zone) {
                return Err(LocalError::Refused(refusal));
            }
        }

        let authority = LocalAuthority::open(ca_dir)?;
        let mut certificates = Vec::with_capacity(zones.len());
        for zone in zones {
            let certified = authority.certificate_for(zone, leaves, &provider)?;
            certificates.push((zone.clone(), SwappableCert::new(certified)));
        }
        let resolver = ZoneResolver::new(certificates)?;
        tracing::info!(
            zones = ?resolver.zones(),
            authority = %authority.certificate_path().display(),
            "local tls certificates ready, one pair per zone"
        );
        Ok(Self {
            authority,
            resolver,
        })
    }

    /// The authority behind these certificates, for printing its path.
    pub fn authority(&self) -> &LocalAuthority {
        &self.authority
    }

    /// The one `rustls::ServerConfig` this process serves with.
    pub fn server_config(&self) -> Arc<rustls::ServerConfig> {
        let mut config = rustls::ServerConfig::builder()
            .with_no_client_auth()
            .with_cert_resolver(self.resolver.clone());
        config.alpn_protocols = vec![b"h2".to_vec(), b"http/1.1".to_vec()];
        Arc::new(config)
    }
}

/// The authority certificate's parameters, fixed so that a later start
/// rebuilds the same issuer from the saved key alone.
fn ca_params(now: OffsetDateTime) -> Result<CertificateParams, rcgen::Error> {
    let mut params = CertificateParams::new(Vec::<String>::new())?;
    params.is_ca = IsCa::Ca(BasicConstraints::Constrained(0));
    params.not_before = now - CLOCK_SKEW;
    params.not_after = now + CA_VALIDITY;
    params.distinguished_name = DistinguishedName::new();
    params
        .distinguished_name
        .push(DnType::CommonName, CA_COMMON_NAME);
    params.key_usages = vec![
        KeyUsagePurpose::KeyCertSign,
        KeyUsagePurpose::CrlSign,
        KeyUsagePurpose::DigitalSignature,
    ];
    params.name_constraints = Some(NameConstraints {
        permitted_subtrees: vec![GeneralSubtree::DnsName(PERMITTED_SUBTREE.to_owned())],
        excluded_subtrees: Vec::new(),
    });
    Ok(params)
}

#[cfg(test)]
mod tests {
    use super::*;

    fn provider() -> rustls::crypto::CryptoProvider {
        rustls::crypto::ring::default_provider()
    }

    #[test]
    fn a_second_start_reuses_the_authority_and_the_leaf() {
        let dir = tempdir();
        let first = LocalFleet::bootstrap(
            &dir.path().join("ca"),
            Some(dir.path()),
            &["agents.localhost".to_owned()],
        )
        .unwrap();
        assert!(first.authority().was_generated());
        let first_leaf = first
            .resolver
            .certificate_for("agents.localhost")
            .unwrap()
            .cert
            .clone();

        let second = LocalFleet::bootstrap(
            &dir.path().join("ca"),
            Some(dir.path()),
            &["agents.localhost".to_owned()],
        )
        .unwrap();
        assert!(!second.authority().was_generated());
        assert_eq!(
            first.authority().certificate_path(),
            second.authority().certificate_path()
        );
        assert_eq!(
            first_leaf,
            second
                .resolver
                .certificate_for("agents.localhost")
                .unwrap()
                .cert
                .clone()
        );
    }

    #[test]
    fn a_leaf_from_a_replaced_authority_is_signed_again() {
        let dir = tempdir();
        let first = LocalFleet::bootstrap(
            &dir.path().join("ca"),
            Some(dir.path()),
            &["agents.localhost".to_owned()],
        )
        .unwrap();
        let before = first
            .resolver
            .certificate_for("agents.localhost")
            .unwrap()
            .cert
            .clone();

        // What a developer who deleted half the data directory leaves
        // behind: the zone's leaf, signed by an authority no longer there.
        std::fs::remove_file(first.authority().certificate_path()).unwrap();
        let second = LocalFleet::bootstrap(
            &dir.path().join("ca"),
            Some(dir.path()),
            &["agents.localhost".to_owned()],
        )
        .unwrap();
        assert!(second.authority().was_generated());
        assert_ne!(
            before,
            second
                .resolver
                .certificate_for("agents.localhost")
                .unwrap()
                .cert
                .clone()
        );
    }

    #[test]
    fn a_zone_that_is_not_local_is_refused() {
        let dir = tempdir();
        let err = LocalFleet::bootstrap(
            &dir.path().join("ca"),
            Some(dir.path()),
            &["pds.did.bot".to_owned()],
        )
        .unwrap_err();
        assert!(matches!(err, LocalError::Refused(_)), "{err:?}");
        // Nothing was generated for a zone this mode refuses.
        assert!(!dir.path().join("ca").join("ca.pem").exists());
    }

    #[test]
    fn a_leaf_covers_its_zone_and_one_label_under_it() {
        let dir = tempdir();
        let authority = LocalAuthority::open(&dir.path().join("ca")).unwrap();
        let (chain, key) = authority.issue("agents.localhost").unwrap();
        let certified = certified_key_from_pem(&chain, &key, &provider()).unwrap();
        // Leaf then authority: what a client verifying from the leaf up
        // reads, and what tells a later start which authority signed this.
        assert_eq!(certified.cert.len(), 2);
        let (_, leaf) = x509_parser::parse_x509_certificate(certified.cert[0].as_ref()).unwrap();
        let names: Vec<String> = leaf
            .subject_alternative_name()
            .unwrap()
            .unwrap()
            .value
            .general_names
            .iter()
            .map(|name| name.to_string())
            .collect();
        assert!(names.iter().any(|n| n.contains("agents.localhost")));
        assert!(names.iter().any(|n| n.contains("*.agents.localhost")));
    }

    /// A directory that removes itself, so a test that signs certificates
    /// leaves nothing behind.
    fn tempdir() -> TempDir {
        let mut path = std::env::temp_dir();
        path.push(format!(
            "didbot-local-tls-{}-{:?}",
            std::process::id(),
            std::thread::current().id()
        ));
        let _ = std::fs::remove_dir_all(&path);
        std::fs::create_dir_all(&path).unwrap();
        TempDir(path)
    }

    struct TempDir(PathBuf);

    impl TempDir {
        fn path(&self) -> &Path {
            &self.0
        }
    }

    impl Drop for TempDir {
        fn drop(&mut self) {
            let _ = std::fs::remove_dir_all(&self.0);
        }
    }
}