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
AcmeConfig::from_configderives strict ACME settings fromcrate::config::Config(domains + cache dir required, email optional).AcmeManager::load_or_createrestores the account credentials and the last certificate from--acme-cache-dir/acme-cache.jsonwhen present.ensure_cert(featureacme) creates/reuses the account, places an order for the domains, serves the HTTP-01 responses viachallenge_routeron--acme-http-port, finalizes, and installs the chain into theSharedCerthandle.AcmeManager::spawn_renewal_task(featureacme) sleeps until the installed cert is withinRENEW_BEFOREof 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.rsbuilds its firstrustls::ServerConfigfromSharedCert::current(cert_pem+key_pem) viatls::build.- The HTTP-01 listener and the issuance flow share one
ChallengeTokensmap:http.rsbinds the listener, spawnsserve_challengeswith the map, then callsAcmeManager::ensure_cert_withwith 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 useensure_cert_with. - After each renewal the manager calls
SharedCert::install, which bumpsCertSnapshot::generation.http.rsdetects rotation by pollingcurrent().generationand reloading the acceptor. This module never touches the acceptor. http.rsspawn order:load_or_create→ bind the challenge listener → spawnserve_challengesfor 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:
AcmeCacheandCertSnapshothave hand-writtenDebugimpls that redact secrets, following theConfigprecedent. - The cache directory is created with
0700and the cache file with0600on unix. The cache holds a private key: the operator must mount it read-write forUSER nobody(or whatever the process user is). --acme-directory-urlmust behttps://, excepthttp://loopback hosts (Pebble / local test servers).
Structs§
- Acme
Cache - On-disk ACME state: opaque account credentials plus the last chain.
- Acme
Config - Strict ACME settings derived from
crate::config::Config. - Acme
Manager - Owns the ACME settings, the shared cert handle, and the renewal lifecycle.
- Cert
Snapshot - A certificate + key installed for the TLS acceptor to serve.
- Challenge
Tokens - Token → key-authorization map backing the HTTP-01 challenge listener.
- Shared
Cert - 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-dirholding account credentials + cert chain. - CACHE_
VERSION - Current schema of
AcmeCache; bump on any incompatible change. - LETSENCRYPT_
PROD_ URL - Default
--acme-directory-urlvalues, 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
Nonewhen no cache file exists yet. - mailto_
contacts - Build the ACME
contactURIs from the optional email flag. - renewal_
delay_ with_ jitter baseplus a deterministic jitter in[0, RENEW_JITTER_MAX).- renewal_
due - True when
expiryis withinRENEW_BEFOREofnow(or past it). - serve_
challenges - Serve challenge responses until
shutdownresolves. - store_
cache - Persist the cache, creating the directory with
0700and the file with0600on 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 loopbackhttp://for Pebble. - validate_
domains - Reject domains the CA cannot issue for over HTTP-01.
- validate_
email - Check an
--acme-emailvalue loosely: present, one@, dot in domain.