didbot_tls/

lib.rs

//! The PDS's own TLS certificate: obtained over ACME DNS-01, renewed without
//! a restart, stored with the same care the signing keys get.
//!
//! # The shape
//!
//! * [`dns`] -- what ACME's DNS-01 step needs from a DNS backend, stated as
//!   its own seam because `didbot-dns` cannot do it yet. Read this module
//!   first; it explains the two-simultaneous-TXT-values problem that shapes
//!   everything downstream of it.
//! * [`directory`] -- staging vs. production, staging by default.
//! * [`acme`] -- one ACME order, start to finish, generic over [`dns`].
//! * [`http_client`] -- the HTTP client [`acme`] uses, and why it is not
//!   instant-acme's own default one.
//! * [`cert`] -- PEM in, `rustls::sign::CertifiedKey` and an expiry out.
//! * [`resolver`] -- the certificate as swappable state a live `rustls`
//!   handshake reads, so a renewal never touches the listener or an
//!   established connection. Read this module for the hot-reload story.
//! * [`renew`] -- when renewal is due, and how loudly a failing one should
//!   be surfaced, as pure functions of a supplied clock.
//! * [`storage`] -- the certificate, its key and the ACME account key on
//!   disk, `0600` inside `0700`.
//! * [`source`] -- which authority a zone's certificate comes from. One
//!   table, so ACME and the local authority can never both apply to a zone.
//! * [`test_support`] -- certificates for a test standing up a server over
//!   TLS, behind the `test-support` feature so nothing ships it.
//! * [`local`] -- the authority a developer's machine trusts, for a zone no
//!   public authority can issue for. Read this module for what bounds a
//!   certificate that sits in a trust store.
//! * [`fleet`] -- one [`manager::CertificateManager`] per configured zone,
//!   and the SNI dispatch between their certificates. Read this module for
//!   why a deployment cannot have one certificate.
//! * [`manager`] -- everything above, tied into one
//!   [`manager::CertificateManager`] a caller bootstraps once and hands a
//!   [`rustls::ServerConfig`] to a listener.
//!
//! # What this crate's tests do and do not verify
//!
//! `tests/acme_conformance.rs` drives the real `instant-acme` client through
//! a full order -- directory, nonce, account, order, authorization,
//! challenge, finalize, certificate -- against an in-process fake ACME
//! directory, with no network and no real zone. [`manager`]'s own
//! documentation says exactly which pieces that does and does not stand in
//! for -- most importantly, no real CA and no real DNS-01 propagation over
//! the network, so passing here is not proof that a real Let's Encrypt
//! exchange succeeds, only that this crate's own orchestration (the
//! apex+wildcard grouping, cleanup, renewal, retry and multi-zone
//! isolation) is correct against something that answers like a CA.

#![forbid(unsafe_code)]

pub mod acme;
pub mod cert;
pub mod directory;
pub mod dns;
pub mod fleet;
pub mod http_client;
pub mod local;
pub mod manager;
pub mod renew;
pub mod resolver;
pub mod source;
pub mod storage;

#[cfg(any(test, feature = "test-support"))]
pub mod test_support;