Skip to main content

Module acme

Module acme 

Source
Expand description

ACME HTTP-01 auto-issuance and renewal.

The pure logic in this module (validation, JSON cache, renewal math, the challenge router) compiles with the base dependency set so cargo test stays offline. Only the network flow that talks to the ACME directory needs instant-acme and lives behind the acme cargo feature:

# see /tmp/CARGO_DEPS_NOTE.md for the exact snippet
features = ["acme"]  # enables instant-acme (rustls 0.23 compatible)

§Flow

  1. AcmeConfig::from_config derives strict ACME settings from crate::config::Config (domains + cache dir required, email optional).
  2. AcmeManager::load_or_create restores the account credentials and the last certificate from --acme-cache-dir/acme-cache.json when present.
  3. ensure_cert (feature acme) creates/reuses the account, places an order for the domains, serves the HTTP-01 responses via challenge_router on --acme-http-port, finalizes, and installs the chain into the SharedCert handle.
  4. AcmeManager::spawn_renewal_task (feature acme) sleeps until the installed cert is within RENEW_BEFORE of expiry (plus jitter) and re-issues. Restarts reuse the cache, so no re-issue (rate-limit safety).

§Integration contract for http.rs / tls.rs

  • tls.rs builds its first rustls::ServerConfig from SharedCert::current (cert_pem + key_pem) via tls::build.
  • The HTTP-01 listener and the issuance flow share one ChallengeTokens map: http.rs binds the listener, spawns serve_challenges with the map, then calls AcmeManager::ensure_cert_with with the same map so the CA’s fetches hit the responses this order published. ensure_cert (no map) is back-compat only; it issues into a throwaway map no listener serves, so the serve path must use ensure_cert_with.
  • After each renewal the manager calls SharedCert::install, which bumps CertSnapshot::generation. http.rs detects rotation by polling current().generation and reloading the acceptor. This module never touches the acceptor.
  • http.rs spawn order: load_or_create → bind the challenge listener → spawn serve_challenges for the process lifetime (renewals need it) → ensure_cert_with(&tokens) → build the acceptor → spawn the renewal task with the same tokens plus a generation-poll rotation watcher.

§Security notes

  • Key material (account credentials, private key, cert PEM) is never logged: AcmeCache and CertSnapshot have hand-written Debug impls that redact secrets, following the Config precedent.
  • The cache directory is created with 0700 and the cache file with 0600 on unix. The cache holds a private key: the operator must mount it read-write for USER nobody (or whatever the process user is).
  • --acme-directory-url must be https://, except http:// loopback hosts (Pebble / local test servers).

Structs§

AcmeCache
On-disk ACME state: opaque account credentials plus the last chain.
AcmeConfig
Strict ACME settings derived from crate::config::Config.
AcmeManager
Owns the ACME settings, the shared cert handle, and the renewal lifecycle.
CertSnapshot
A certificate + key installed for the TLS acceptor to serve.
ChallengeTokens
Token → key-authorization map backing the HTTP-01 challenge listener.
SharedCert
Cheaply cloneable handle to the currently installed certificate.

Constants§

ASSUMED_CERT_LIFETIME
Assumed certificate lifetime when the CA does not tell us otherwise.
CACHE_FILE_NAME
File inside --acme-cache-dir holding account credentials + cert chain.
CACHE_VERSION
Current schema of AcmeCache; bump on any incompatible change.
LETSENCRYPT_PROD_URL
Default --acme-directory-url values, kept here so tests can reference them.
LETSENCRYPT_STAGING_URL
RENEW_BEFORE
Renew when the installed cert has less than this much lifetime left.
RENEW_JITTER_MAX
Upper bound added on top of the renewal sleep to avoid thundering herds.

Functions§

cache_path
Path of the cache file inside cache_dir.
challenge_router
Axum router answering /.well-known/acme-challenge/<token>.
load_cache
Read the cache, or None when no cache file exists yet.
mailto_contacts
Build the ACME contact URIs from the optional email flag.
renewal_delay_with_jitter
base plus a deterministic jitter in [0, RENEW_JITTER_MAX).
renewal_due
True when expiry is within RENEW_BEFORE of now (or past it).
serve_challenges
Serve challenge responses until shutdown resolves.
store_cache
Persist the cache, creating the directory with 0700 and the file with 0600 on unix.
time_until_renewal
How long to sleep before the next issuance attempt. Zero when due now.
validate_directory_url
The directory URL must be https://, except loopback http:// for Pebble.
validate_domains
Reject domains the CA cannot issue for over HTTP-01.
validate_email
Check an --acme-email value loosely: present, one @, dot in domain.