didbot_tls/

acme.rs

//! Orchestrating one ACME order against DNS-01, generic over the DNS seam in
//! [`crate::dns`].
//!
//! # The two-value collision, made concrete
//!
//! An order for `["pds.did.bot", "*.pds.did.bot"]` gets two authorizations.
//! Both put their DNS-01 challenge at the *same* record name --
//! `_acme-challenge.pds.did.bot` -- because RFC 8555 §8.4 strips the
//! wildcard label before constructing the challenge name. This module makes
//! two passes over the order's authorizations rather than the
//! compute-then-immediately-set-ready loop instant-acme's own docs show,
//! because that loop publishes and confirms one value at a time: the second
//! `publish_challenge` call would replace the first identifier's value
//! before the CA ever saw both. Pass one collects every value, grouped by
//! name; then every name's whole set is published once; only after that does
//! pass two mark each challenge ready.
//!
//! # What is, and is not, exercised here
//!
//! This module's own unit tests below only cover `group_challenges_by_name`
//! as a pure function -- there is no way to construct a real
//! [`instant_acme::Account`] without an HTTP round trip to a directory, so a
//! fake `Account` was never attempted here. The full exchange -- a real
//! `Account`, a real order, both DNS-01 authorizations grouped and
//! published together, cleanup on every exit path -- is instead exercised
//! by `tests/acme_conformance.rs`, against an in-process fake ACME
//! directory (`tests/support::FakeAcmeServer`); no real CA has ever
//! answered a call from this module. See that test file and this crate's
//! top-level documentation for exactly what the fake does and does not
//! stand in for.

use std::collections::BTreeMap;
use std::sync::Arc;

use instant_acme::{
    Account, AuthorizationStatus, ChallengeType, Identifier, NewOrder, OrderStatus, RetryPolicy,
};

use crate::dns::{AcmeDnsChallenge, AcmeDnsError};

/// A certificate chain and its private key, both PEM, as ACME hands them
/// back.
#[derive(Clone)]
pub struct IssuedCertificate {
    /// Leaf certificate followed by intermediates.
    pub cert_chain_pem: String,
    /// The key ACME generated for this certificate.
    pub key_pem: String,
}

impl std::fmt::Debug for IssuedCertificate {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Written by hand so that no derive, now or after a future field is
        // added, can put the key into a log line or a panic message. The
        // chain is public and identifies the certificate on its own.
        f.debug_struct("IssuedCertificate")
            .field("cert_chain_pem", &self.cert_chain_pem)
            .finish_non_exhaustive()
    }
}

/// Why issuance did not produce a certificate.
#[derive(Debug, thiserror::Error)]
pub enum IssueError {
    /// The ACME exchange itself failed.
    #[error("acme: {0}")]
    Acme(#[from] instant_acme::Error),
    /// Publishing or withdrawing a challenge value failed.
    #[error("dns-01: {0}")]
    Dns(#[from] AcmeDnsError),
    /// The CA offered no `dns-01` challenge for one of the identifiers.
    #[error("no dns-01 challenge offered for {identifier}")]
    NoDns01Challenge {
        /// The identifier (without a leading `*.`) that lacked one.
        identifier: String,
    },
    /// The order finished somewhere other than `ready`/`valid`.
    #[error("order finished in an unexpected state: {0:?}")]
    UnexpectedOrderStatus(OrderStatus),
}

/// The full domain name(s) a certificate should cover: `<zone>` and
/// `*.<zone>`.
pub fn zone_and_wildcard(zone: &str) -> Vec<String> {
    vec![zone.to_owned(), format!("*.{zone}")]
}

/// The `_acme-challenge.<name>` record a DNS-01 answer for `identifier` (as
/// rendered by `instant_acme`'s `AuthorizedIdentifier`'s `Display`,
/// which prints `*.<name>` for a wildcard authorization) belongs at.
///
/// Stripping the `*.` here, rather than trusting the CA never to send one, is
/// what makes an apex-plus-wildcard order collapse onto one record name --
/// which is the entire reason this crate cannot publish one value and move
/// on.
fn challenge_record_name(displayed_identifier: &str) -> String {
    let base = displayed_identifier
        .strip_prefix("*.")
        .unwrap_or(displayed_identifier);
    format!("_acme-challenge.{base}")
}

/// Groups (name, value) into the value *sets* that must be published
/// together. Exposed for tests without needing a real order: this is where
/// the apex-plus-wildcard collision either is or is not avoided.
pub(crate) fn group_challenges_by_name(
    pairs: &[(String, String)],
) -> BTreeMap<String, Vec<String>> {
    let mut grouped: BTreeMap<String, Vec<String>> = BTreeMap::new();
    for (name, value) in pairs {
        grouped.entry(name.clone()).or_default().push(value.clone());
    }
    grouped
}

/// Requests a certificate covering every domain in `domains` from `account`,
/// completing every `dns-01` challenge through `dns`.
///
/// Withdraws every challenge record it published before returning, whether
/// issuance succeeded or failed -- a stale challenge TXT is not dangerous the
/// way a stale `did:web` record is, but nothing should have to notice and
/// clean it up by hand.
pub async fn issue<D: AcmeDnsChallenge>(
    account: &Account,
    domains: &[String],
    dns: &Arc<D>,
) -> Result<IssuedCertificate, IssueError> {
    let identifiers: Vec<Identifier> = domains.iter().cloned().map(Identifier::Dns).collect();
    let mut order = account.new_order(&NewOrder::new(&identifiers)).await?;

    // Pass 1: collect every challenge value, grouped by the record name it
    // shares with any other identifier in this order.
    let mut pairs = Vec::new();
    {
        let mut authorizations = order.authorizations();
        while let Some(result) = authorizations.next().await {
            let mut authz = result?;
            if authz.status != AuthorizationStatus::Pending {
                continue;
            }
            let identifier = authz.identifier().to_string();
            let challenge = authz.challenge(ChallengeType::Dns01).ok_or_else(|| {
                IssueError::NoDns01Challenge {
                    identifier: identifier.clone(),
                }
            })?;
            let value = challenge.key_authorization().dns_value();
            pairs.push((challenge_record_name(&identifier), value));
        }
    }
    let grouped = group_challenges_by_name(&pairs);

    for (name, values) in &grouped {
        dns.publish_challenge(name, values)?;
    }

    let cleanup = |dns: &Arc<D>, grouped: &BTreeMap<String, Vec<String>>| {
        for name in grouped.keys() {
            if let Err(err) = dns.clear_challenge(name) {
                tracing::warn!(name, %err, "could not withdraw an acme dns-01 challenge");
            }
        }
    };

    // Pass 2: now that every name's complete value set is visible, tell the
    // CA each challenge is ready to be checked.
    {
        let mut authorizations = order.authorizations();
        while let Some(result) = authorizations.next().await {
            let mut authz = match result {
                Ok(authz) => authz,
                Err(err) => {
                    cleanup(dns, &grouped);
                    return Err(err.into());
                }
            };
            if authz.status != AuthorizationStatus::Pending {
                continue;
            }
            let identifier = authz.identifier().to_string();
            let Some(mut challenge) = authz.challenge(ChallengeType::Dns01) else {
                cleanup(dns, &grouped);
                return Err(IssueError::NoDns01Challenge { identifier });
            };
            if let Err(err) = challenge.set_ready().await {
                cleanup(dns, &grouped);
                return Err(err.into());
            }
        }
    }

    let result = finish_order(&mut order).await;
    cleanup(dns, &grouped);
    result
}

async fn finish_order(order: &mut instant_acme::Order) -> Result<IssuedCertificate, IssueError> {
    let status = order.poll_ready(&RetryPolicy::default()).await?;
    if status != OrderStatus::Ready {
        return Err(IssueError::UnexpectedOrderStatus(status));
    }
    let key_pem = order.finalize().await?;
    let cert_chain_pem = order.poll_certificate(&RetryPolicy::default()).await?;
    Ok(IssuedCertificate {
        cert_chain_pem,
        key_pem,
    })
}

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

    #[test]
    fn debug_never_prints_the_private_key() {
        let issued = IssuedCertificate {
            cert_chain_pem: "-----BEGIN CERTIFICATE-----\nchain\n".to_string(),
            key_pem: "-----BEGIN PRIVATE KEY-----\nscalar\n".to_string(),
        };
        let rendered = format!("{issued:?}");

        // The whole rendering, not a search through it: any added field, any
        // switch back to a derived `Debug`, changes this string and fails
        // here rather than waiting for a key to appear in a log.
        let chain = &issued.cert_chain_pem;
        assert_eq!(
            rendered,
            format!("IssuedCertificate {{ cert_chain_pem: {chain:?}, .. }}")
        );
        assert!(!rendered.contains("scalar"), "leaked the key in {rendered}");
    }

    #[test]
    fn challenge_record_name_strips_the_wildcard_label() {
        assert_eq!(
            challenge_record_name("*.pds.did.bot"),
            "_acme-challenge.pds.did.bot"
        );
        assert_eq!(
            challenge_record_name("pds.did.bot"),
            "_acme-challenge.pds.did.bot"
        );
    }

    #[test]
    fn apex_and_wildcard_collapse_onto_one_name_with_two_values() {
        // This is the exact case the epic calls out: a certificate over
        // both `<zone>` and `*.<zone>` needs two TXT values live at once
        // under one name.
        let pairs = vec![
            (
                challenge_record_name("pds.did.bot"),
                "apex-token".to_string(),
            ),
            (
                challenge_record_name("*.pds.did.bot"),
                "wildcard-token".to_string(),
            ),
        ];
        let grouped = group_challenges_by_name(&pairs);
        assert_eq!(grouped.len(), 1, "both identifiers share one record name");
        let values = &grouped["_acme-challenge.pds.did.bot"];
        assert_eq!(values.len(), 2);
        assert!(values.contains(&"apex-token".to_string()));
        assert!(values.contains(&"wildcard-token".to_string()));
    }

    #[test]
    fn unrelated_identifiers_do_not_share_a_name() {
        let pairs = vec![
            (challenge_record_name("pds.did.bot"), "a".to_string()),
            (challenge_record_name("other.example"), "b".to_string()),
        ];
        let grouped = group_challenges_by_name(&pairs);
        assert_eq!(grouped.len(), 2);
    }

    #[test]
    fn zone_and_wildcard_covers_both_names() {
        let domains = zone_and_wildcard("pds.did.bot");
        assert_eq!(
            domains,
            vec!["pds.did.bot".to_string(), "*.pds.did.bot".to_string()]
        );
    }
}