rustls-letsencrypt
Automatic TLS certificate issuance, selection, storage, and renewal for Rust servers.
rustls-letsencrypt puts certificate management directly in front of your TLS connections. It reads the ClientHello, selects the best certificate for its SNI hostname, obtains a certificate when one is missing, answers ACME tls-alpn-01 challenges on port 443, and hands the completed TLS stream back to your application.
The manager is process-scoped. Register the port-443 ALPN handler once, then add managed TLS handlers on any other port without repeating configuration.
How it works
The listener on port 443 serves two kinds of TLS connection through the same socket:
- For ordinary clients, it reads SNI from ClientHello, selects the valid ACME certificate or local fallback, completes TLS, and returns the encrypted stream to the application.
- For an ACME validation connection offering only
acme-tls/1, it verifies that this process initiated the matching order, serves the temporary RFC 8737 challenge certificate, completes validation internally, and does not expose that connection to the application. - When an allowed hostname has no certificate, the manager starts ACME issuance and, when enabled, local fallback issuance. The resulting records are stored separately and published to the in-memory certificate cache.
- Other managed listeners—such as Kafka on 9092—share that cache. They can trigger issuance, while the CA's separate validation connection arrives at the already-running port-443 listener.
ordinary client ─┐
├─ TCP 443 ─ ClientHello/SNI/ALPN ─┬─ acme-tls/1 → challenge
ACME validator ──┘ └─ normal TLS → application
Kafka client ───── TCP 9092 ─ shared manager/cache ── normal TLS → Kafka
│
└─ missing cert starts issuance
Why TLS-ALPN-01 on port 443 instead of HTTP-01 on port 80?
- A TLS-only service does not need to open or maintain a plaintext HTTP listener on port 80.
- Networks that intentionally expose only HTTPS can keep that policy.
- Validation follows the same TCP ingress and SNI routing path as production TLS traffic.
- The temporary challenge certificate is scoped to the requested hostname and
acme-tls/1; it is never used for application traffic. - Non-HTTP services such as Kafka can obtain certificates without pretending to be an HTTP server.
TLS-ALPN-01 is not universally better. The CA must reach this manager on TCP 443, and any load balancer or reverse proxy in front must pass the challenge ClientHello through rather than terminating it with an unrelated certificate. When an existing HTTP proxy owns validation routing, HTTP-01 may be simpler.
The interception is transparent to the application protocol. The manager
special-cases only a matching, locally initiated acme-tls/1 validation
connection. Ordinary HTTPS continues through the normal TLS handshake and the
accepted stream contains the original HTTP bytes unchanged. The same is true
for Kafka or any other protocol carried over TLS: after certificate selection,
the crate does not parse, proxy, rewrite, or otherwise participate in the
application protocol. Configure application_alpn_protocols when the
application needs protocols such as h2 or http/1.1 advertised by the TLS
server.
┌────────────────────────────┐
│ process certificate manager│
│ ACME + Local + renewal │
└─────────────┬──────────────┘
│
┌────────────────────────┼───────────────────────┐
│ │ │
port 443 handler port 9092 handler port 8443 handler
TLS + acme-tls/1 normal TLS normal TLS
Features
- Automatic ACME issuance through the TLS-ALPN-01 challenge.
- Let's Encrypt production and staging profiles.
- Managed local Pebble support for development without public DNS or Internet ingress.
- Custom RFC 8555-compatible ACME directory support.
- A process-wide certificate cache shared by TLS listeners on every port.
- Exact hostname and label-glob allowlists (
*never crosses a dot). - Optional DNS-to-public-IP ownership checks before public ACME issuance.
- A persisted local CA named
AcmeLocalCAfor immediate fallback certificates. - Concurrent local and ACME issuance for a previously unseen hostname.
- Deterministic certificate preference: valid ACME, then valid local certificate.
- Lock-free certificate resolution through per-domain ArcSwap snapshots.
- JSON folder storage with separate
ACME/andLocal/namespaces. - Automatic renewal before expiry with bounded retries.
- A configurable absolute deadline for every issuance and renewal attempt, defaulting to 60 seconds.
- Structured lifecycle events, subscriptions, callbacks, and built-in stderr/stdout output.
- Native Tokio API and an optional blocking adapter.
- Certificate retrieval for application integrations such as Kafka.
How it behaves
For every ordinary TLS ClientHello with SNI, the acceptor uses this resolution order:
1. Valid certificate from the configured ACME provider
2. Valid certificate issued by AcmeLocalCA
3. Start or join both issuance tasks and wait for an in-flight result
ACME and local certificates coexist. A local certificate never overwrites an ACME certificate. If local issuance finishes first, the current connection can use it immediately. When ACME issuance succeeds, the next connection automatically uses the ACME certificate.
Existing connections keep the certificate snapshot selected for their handshake. Certificate replacement does not interrupt established connections.
A certificate issued by
AcmeLocalCAis trusted only by clients that have installed that CA. It is not a replacement for a publicly trusted certificate.
Installation
[]
= "0.1"
= { = "1", = ["macros", "net", "rt-multi-thread"] }
Enable the blocking facade or managed Pebble support when needed:
[]
= { = "0.1", = ["blocking", "managed-pebble"] }
Quick start
The port-443 handler must be registered first. It initializes the process manager and makes ACME TLS-ALPN validation available.
Ready-to-run examples
The repository includes practical configurations in examples/, all using
./certs for JSON certificate storage:
# Public production (edit the literal host/IP in the example first)
cargo run --example letsencrypt_prod
# Public staging with application-subscribed events (edit the literal host/IP first)
cargo run --example letsencrypt_staging
# Local Pebble, no public DNS/IP verification, unprivileged port 8443
cargo run --features managed-pebble --example pebble_local
The production and staging examples use explicit public DNS resolvers, verify that the hostname resolves to the configured public IP, and keep local fallback enabled. Production logs to stderr; staging subscribes to structured events. The Pebble example uses stderr logging, private loopback binding, and disables the public DNS ownership gate.
use ;
use ;
use TcpListener;
async
The returned handler accepts ordinary application TLS on port 443 and internally consumes matching acme-tls/1 validation connections. ACME validation streams are never handed to application code.
Passing None uses defaults, but issuance remains disabled until at least one allowed host is configured or valid certificates are already present in the store.
TLS on another port
After the port-443 handler is ready, register ordinary handlers without any additional configuration:
use register_handler;
use TcpListener;
# async
Calling register_handler before register_alpn_handler returns AlpnHandlerNotRegistered. Calling it while port-443 initialization is incomplete returns AlpnHandlerNotReady.
All handlers share:
- allowed-host policy;
- certificate cache;
- ACME account and challenge registry;
- local CA;
- issuance single-flights;
- folder store;
- renewal scheduler;
- event bus.
If a connection on port 9092 requests an allowed hostname with no certificate, it can trigger issuance. The CA's separate validation connection is answered on port 443. If the original client disconnects, issuance continues and the result is stored for its next attempt.
Deployment recipes
These configurations are intended as practical starting points. Pass the chosen
configuration to register_alpn_handler on the listener that receives ACME
TLS-ALPN validation traffic.
Local development with managed Pebble
Enable the managed-pebble feature and ensure pebble is in PATH:
use ;
#
Pebble certificates are test certificates. Clients must trust Pebble's generated test CA; never add that CA to a production or system-wide trust store.
Let's Encrypt staging
Use staging while validating public DNS, firewall rules, port 443 routing, and renewal behavior:
use ;
#
Staging certificates are not publicly trusted. A local fallback is useful only
for clients that already trust Local/CA.pem.
Let's Encrypt production
Move to production only after the staging journey succeeds:
use ;
#
The service must be reachable by the CA on TCP port 443 and the configured DNS
names must resolve to one of public_ip_addresses.
Private services using only AcmeLocalCA
For an internal service that must never contact an ACME server:
use ;
#
Install Local/CA.pem only in the intended private clients. Protect
Local/CA.key as a CA signing key. LocalOnly never initializes an ACME order.
Configuration
Use AlpnHandlerConfig only with register_alpn_handler. Other handlers intentionally accept no certificate-manager configuration.
use ;
use ;
#
Defaults
| Setting | Default | Meaning |
|---|---|---|
renew_days_before_expiry |
15 days | A certificate becomes due for renewal |
renew_check_interval_secs |
3,600 | Scheduled scan and first retry interval |
renew_check_max_interval_secs |
43,200 | Maximum per-domain/issuer retry backoff |
client_hello_timeout_secs |
5 | Absolute seconds allowed to receive ClientHello |
issuance_attempt_timeout_secs |
60 | Absolute seconds allowed for each issuance or renewal attempt |
initial_connection_wait_timeout_secs |
60 | Seconds a triggering handshake waits |
dns_lookup_timeout_secs |
5 | Absolute seconds allowed for one DNS ownership lookup |
pebble_startup_timeout_secs |
30 | Seconds allowed for managed Pebble readiness |
local_fallback_enabled |
enabled | Issue an immediate locally trusted fallback |
verify_dns_before_issuance |
true |
Verify public DNS before ACME issuance/renewal |
dns_servers |
None |
Use the operating system's configured resolver |
events |
Stderr |
Built-in event presentation |
Timeout values are interpreted as seconds and converted to internal Duration values after configuration validation. issuance_attempt_timeout_secs is not capped at 60; the configured value is honored. The default is 60 seconds.
Allowed hosts
Only configured hostnames may trigger issuance or receive a managed certificate.
# use HostPattern;
#
The wildcard is an allowlist pattern, not a wildcard certificate request. The
convenience AlpnHandlerConfig::for_host and for_hosts helpers detect these
patterns automatically:
*.services.example.commatchesone.services.example.com.- It does not match
services.example.com. - It does not match
one.two.services.example.com. *help.wushilin.netmatchesmyhelp.wushilin.net.*.*.*matches any hostname with exactly three labels.*matches any one-label hostname, but is usually too broad for a public service.*matches only characters within one label; it never matches a dot.- Every ACME order uses the concrete SNI hostname.
TLS-ALPN-01 cannot issue wildcard certificates.
Hostnames are normalized to lowercase ASCII form before policy, cache, storage, and ACME lookup. SNI is required for on-demand issuance.
Public IP ownership gate
verify_dns_before_issuance explicitly controls this additional pre-issuance safety gate and defaults to true.
When enabled, before public ACME issuance or renewal the manager:
- verifies the concrete SNI hostname against
allowed_hosts; - resolves its A and AAAA records;
- requires at least one result to match
public_ip_addresses; - starts or joins the ACME order only after those checks pass.
This check happens during issuance and ACME renewal, not on every TLS handshake. A mismatch produces DnsOwnershipMismatch and an event without contacting the ACME server.
Multiple IPv4 and IPv6 addresses are supported for dual-stack and migration scenarios.
By default, lookup uses the operating system's resolver configuration. Supply one or more DNS servers when the application needs deterministic or independent resolution:
# use ;
let config = AlpnHandlerConfig ;
# Ok::
Use udp:// for UDP-only resolution and tcp:// for TCP-only resolution. A bare address such as 1.1.1.1:53 means UDP with TCP retry/failover, which is the normal choice when truncated UDP responses must be retried. Brackets are required around IPv6 literals. DNS servers are tried according to the resolver's failover policy under one bounded lookup deadline. An empty Some(vec![]) is rejected; use None for the system resolver. Unsupported schemes fail configuration parsing explicitly; DNS-over-TLS and DNS-over-HTTPS are not currently enabled by these values.
To rely only on allowed_hosts, disable DNS verification explicitly:
# use AlpnHandlerConfig;
let config = AlpnHandlerConfig ;
When verification is disabled, public_ip_addresses and dns_servers are not used for issuance policy. The manager emits a startup warning event so this weaker policy is visible. The hostname allowlist remains mandatory and ACME still performs its own external domain validation.
Managed Pebble does not use public DNS verification. Its validation environment uses the scoped local hostname mapping described below.
ACME providers
Let's Encrypt
# use ;
let staging = LetsEncrypt;
let production = LetsEncrypt;
Use staging until DNS, firewall, challenge routing, and renewal behavior are verified. Staging certificates are not publicly trusted.
Managed Pebble
Managed Pebble provides a complete local ACME journey when public DNS or inbound Internet access is unavailable.
To build Pebble with Go and install the executable where the managed integration test finds it:
go install github.com/letsencrypt/pebble/v2/cmd/pebble@latest
sudo install -m 0755 "$(go env GOPATH)/bin/pebble" /usr/local/bin/pebble
pebble -version
Alternatively, place a trusted Pebble release binary at
/usr/local/bin/pebble. ManagedPebbleConfig::pebble_executable can select a
different absolute path. The crate never downloads or installs Pebble itself.
use ;
let endpoint = Pebble;
# Ok::
When Pebble is selected, pebble_bind is required and must be loopback. working_directory is optional and sets only the spawned Pebble process's current directory; registration fails if it is not an existing directory. Generated configuration, keys, and certificates use resolved paths and remain independent of that working directory.
At registration, the manager:
- resolves
pebblefromPATH, or usespebble_executable; - generates the required local configuration and trust material;
- starts Pebble and the scoped local validation adapter;
- waits for readiness;
- starts the normal ACME client against it;
- supervises and stops its child processes on shutdown.
If the executable is unavailable, registration returns PebbleExecutableNotFound. The crate never downloads Pebble, installs packages, or silently starts Docker.
Managed validation maps concrete allowed hostnames only inside the Pebble test environment. It does not modify /etc/hosts, system DNS, or the public-IP policy used by Let's Encrypt.
Run the real managed-Pebble integration test with:
cargo test --all-features managed_pebble_issues_and_serves_acme_certificate -- --ignored --nocapture
The test requires the pebble executable in PATH. It starts an isolated
Pebble process and DNS server, completes a real TLS-ALPN-01 order, verifies the
certificate was persisted in the ACME namespace, and uses it for an application
TLS handshake. All listeners use ephemeral loopback ports, so root privileges
and public DNS are unnecessary.
The automated lifecycle suite also covers local fallback when ACME is unreachable, ACME-before-local selection, expired-certificate removal from both memory and storage, aggressive renewal thresholds, forced local renewal, per-domain/per-issuer exponential retry with a configured cap, failed-renewal events, event replay, callback delivery and panic isolation, CA/key validation, namespace coexistence, ClientHello TLS handling, and DNS transport parsing. Renewal tests call the scheduler logic directly, so they verify hour-scale policies deterministically without making the test suite sleep for hours.
Optional live DNS compatibility tests verify explicit resolvers over both transports:
cargo test --all-features explicit_cloudflare_udp_dns_resolves -- --ignored
cargo test --all-features explicit_google_tcp_dns_resolves -- --ignored
With dns_servers: None, ownership checks use the operating system resolver.
Pebble-issued certificates are stored under ACME/ and selected before AcmeLocalCA certificates. Clients must trust Pebble's test root. Pebble certificates are test certificates and are never treated as Let's Encrypt production certificates.
To connect to a Pebble instance managed outside this process, configure it as a custom ACME endpoint with its directory URL, stable issuer ID, and TLS trust root.
Custom ACME server
# use AcmeEndpoint;
let endpoint = Custom ;
Accounts and certificates are scoped to the resolved directory and issuer ID. Changing endpoints does not reuse credentials from another ACME server.
Local fallback certificates
When local fallback is enabled, the store contains one persisted local CA named AcmeLocalCA:
certificates/Local/CA.pem
certificates/Local/CA.key
If both files are absent, the manager generates them. If both exist, they are loaded as the local issuer, allowing an application or operator to supply its own local CA. If only one exists, or the pair is invalid, initialization fails rather than silently generating or replacing key material.
The manager validates that:
CA.pemcontains exactly one supported CA certificate;CA.keyis a supported private key matching the certificate's public key;- the certificate has
CA:TRUEbasic constraints; - key usage permits certificate signing;
- the CA is currently within its validity period;
- its algorithm and key size satisfy configured policy.
The manager can issue a short-lived leaf locally while the configured ACME order is still running.
For a new hostname, local and ACME issuance run concurrently:
first ClientHello
│
├── LocalCaIssuer ── usually completes first ── handshake may continue
│
└── ACME issuer ─── completes later ─────────── preferred thereafter
The first connection subscribes to the shared issuance results before either task starts, so it cannot miss a fast local completion. Other simultaneous connections join the same per-domain/issuer task instead of creating duplicate certificates or ACME orders.
Install the AcmeLocalCA certificate in the trust store of clients that are allowed to accept local fallback. A client without this trust anchor will correctly reject the local certificate.
Replacing the local CA
Local certificate records include the SHA-256 fingerprint of the CA that issued them. At startup, every record under Local/ is cryptographically validated against the current CA.pem, including signature, issuer relationship, SAN, key match, validity, and recorded CA fingerprint.
When CA.pem and CA.key are replaced with a new valid matching pair:
- the manager validates the complete candidate pair;
- it atomically installs a new in-memory
LocalCaState; - it clears local ArcSwap slots for leaves not issued by the new CA;
- it removes those records from the active
Local/store and moves them to a non-loadable quarantine/audit location; - subsequent handshakes issue or select leaves from the new CA;
- ACME certificates under
ACME/are unaffected.
Existing TLS connections keep their already selected certificate snapshot. New connections never receive a leaf known to belong to the previous local CA after the replacement is committed.
Use the transactional API when replacing the CA from inside the application:
# async
This validates first, writes temporary files with restrictive permissions, commits the pair, and invalidates old local leaves as one manager operation.
Direct filesystem replacement is also detected by a watched/reconciled local-CA generation check. Because two separate files cannot be replaced atomically as a pair, the watcher debounces changes and adopts a replacement only after CA.pem and CA.key form a valid matching pair. A partial or invalid replacement emits LocalCaReloadFailed and leaves the last valid in-memory CA and its certificates active; it does not erase working certificates. reload_local_ca() is available when deterministic reload timing is required.
TLS handshakes do not parse CA files. They read the current in-memory CA generation and local certificate slots. This keeps the hot path lock-free while ensuring that a committed mid-process CA replacement invalidates stale leaves before subsequent selection.
All local-CA actions are observable through both the configured console output and subscribe_events():
INFO local CA loaded: fingerprint sha256:...
INFO local CA replacement detected
INFO local CA replaced: sha256:old... -> sha256:new...
WARN local certificate quarantined: api.example.com was issued by sha256:old...
ERROR local CA reload failed: CA.key does not match CA.pem; retaining current CA
Corresponding structured events include LocalCaGenerated, LocalCaLoaded, LocalCaReloadStarted, LocalCaReplaced, LocalCaReloadFailed, and LocalCertificateQuarantined. They carry redacted fingerprints and safe validation details, never CA or leaf private-key bytes.
Disable fallback when every client requires a publicly trusted certificate:
# use AlpnHandlerConfig;
let config = AlpnHandlerConfig ;
Renewal
Every stored ACME and local certificate is renewed through its own issuer.
- A certificate becomes due 15 days before expiry by default.
- The scheduler checks every hour by default.
- Missing or expired certificates trigger issuance immediately; they do not wait for the next scan.
- Due variants are submitted concurrently across domains and issuers.
- Each attempt has an independent absolute deadline from
issuance_attempt_timeout_secs, defaulting to 60 seconds. - Failed attempts back off per domain and issuer: 1h, 2h, 4h, 8h, 12h, then 12h.
- A successful issuer attempt resets only that issuer's backoff.
- A still-valid old certificate remains available during a failed renewal.
- An expired certificate is removed and is never served.
- Local issuance may restore service while ACME retries continue.
The ACME/ and Local/ variants renew independently and continue to coexist.
Retry suppression and counters are process-local in this release. The store traits reserve issuer-specific retry metadata for a durable scheduler, but the manager does not yet restore backoff counters after process restart; certificate expiry timestamps remain authoritative and the first post-restart scan may retry a due certificate immediately.
Events and logging
Certificate management should not be a black box. Every material lifecycle transition is emitted as a structured Event.
use subscribe_events;
# async
Subscriptions work in every output mode:
| Mode | Built-in output | Subscription API |
|---|---|---|
Subscribe |
none | available |
Stderr |
stderr | available |
Stdout |
stdout | available |
Example output:
2026-07-25T10:00:00Z INFO renewal scan started: 6 certificate variants
2026-07-25T10:00:00Z INFO checked asd.com [lets-encrypt-production]: 152 days remaining (expires 2028-12-01)
2026-07-25T10:00:00Z INFO renewal due for pppp.com [lets-encrypt-production]: 14 days remaining
2026-07-25T10:00:00Z INFO renewing pppp.com [lets-encrypt-production], attempt 1
2026-07-25T10:00:08Z INFO renewal succeeded for pppp.com; new expiry 2028-12-01; elapsed 8.2s
An optional callback can observe startup events that occur before a subscriber is created:
# use ;
# use Arc;
let config = builder
.event_handler
.build?;
# Ok::
The event bus is bounded and producers never wait on consumers. Slow subscribers receive a lag indication and can reconcile through list_certificates() or the manager status snapshot. Callback and console presentation run outside handshake, issuer, scheduler, and store-lock paths.
The bus is created before store and local-CA initialization and keeps a bounded startup history. A subscriber opened immediately after register_alpn_handler receives retained initialization events before live events, including local CA generation/load validation and stale-leaf quarantine. Each event's sequence number preserves the boundary between replayed and live delivery.
Events never contain private keys, account keys, challenge tokens, JWS bodies, or unrestricted ACME responses.
The optional tracing integration emits structured fields without installing a tracing subscriber or selecting a formatter.
Reading certificates
Applications may retrieve certificate material through the process-scoped API:
# async
get_certificate follows the same valid-ACME-then-valid-local selection order as TLS. Issuer-specific retrieval is also available when an integration needs both variants.
Prefer the parsed rustls certified-key API when the consumer is in process; it avoids exposing private-key text. Private-key wrapper types do not implement Debug and are zeroized where possible.
The static API is process-local. Another process can open a compatible store read-only or consume an explicitly configured authenticated management service. This crate does not force Kafka or another external service to reload its TLS configuration.
Kafka-style deployment
A Kafka integration can keep Kafka on 9092 while the certificate manager owns port 443:
Internet/CA ── port 443 ── rustls-letsencrypt challenge handler
Kafka clients ── port 9092 ── managed TLS handler ── Kafka protocol
Alternatively, Kafka may read the atomically stored certificate files and use its own reload mechanism. The manager cannot share one TCP address with a separate process unless a fronting TCP router directs SNI and acme-tls/1 traffic correctly.
Certificate stores
Certificate management is independent of the storage backend. The process manager accepts an Arc<dyn CertStore>:
# use Arc;
# use ;
let store = new;
let config = builder
.cert_store
.build?;
# Ok::
CertStore covers:
- issuer-scoped certificate variants;
- ACME accounts;
- the local CA certificate and private key;
- renewal/backoff metadata;
- atomic certificate commits;
- compare-and-swap local CA replacement;
- removal and quarantine;
- optional change notifications and revision tracking.
Every store exposes two typed namespaces:
# use CertStore;
#
AcmeStoreNamespacecontains ACME accounts, ACME-issued certificate variants, issuer-specific retry state, and ACME quarantine records.LocalStoreNamespacecontainsAcmeLocalCA, locally issued leaves, local retry state, and local quarantine records.
This split is enforced by the API rather than inferred from filenames. ACME account operations do not exist on the local namespace, and local CA replacement does not exist on the ACME namespace. The ACME namespace may still contain several issuer IDs—for example Let's Encrypt production, staging, Pebble, or a custom CA—without mixing them with local certificates.
The manager never depends on JSON paths or filesystem behavior. This allows later backends such as:
SqliteCertStore, using transactions and explicit ACME/Local tables;RocksDbCertStore, using atomic write batches and explicit ACME/Local column families or key prefixes;- a remote or application-owned store;
- an in-memory test store.
All backends must provide atomic visibility: readers see either the previous complete record or the new complete record, never a partial certificate or CA. The ACME and Local namespaces remain separate regardless of physical representation.
Certificate records are loaded from the backend at manager startup. Local CA changes can be applied explicitly through reload_local_ca; arbitrary out-of-process certificate edits are not periodically imported in this release. Store reads do not occur on every TLS handshake; validated values are loaded into the same ArcSwap cache.
Folder store
FolderCertStore is the default backend. The cert_store_directory convenience setting constructs it automatically:
certificates/
├── accounts/
│ └── <directory-hash>.json
├── ACME/
│ └── <stable-domain-key>.json
├── Local/
│ ├── CA.pem
│ ├── CA.key
│ └── <stable-domain-key>.json
└── metadata.json
Each certificate record contains:
- schema version;
- normalized hostname and SANs;
- private key PEM;
- leaf certificate PEM;
- ordered intermediate/CA chain;
not_beforeandnot_after;- issuer, endpoint, and provenance metadata;
- storage timestamp and SHA-256 fingerprint.
Writes use a same-directory temporary file, restrictive permissions, flush, and atomic rename. ACME and local variants never overwrite one another.
In-process mutation uses per-domain/issuer async guards and a short-lived folder writer mutex. TLS resolution never takes the storage mutex. The store mutex is not held during ACME requests or certificate generation.
One process owns the writable store. Read-only cross-process access is safe through atomic replacement; multiple independent writer processes are not supported unless cross-process locking is explicitly enabled.
The store contains private keys, including the powerful Local/CA.key. Protect and back it up accordingly. Newly created secret files use mode 0600 on Unix. Operators should also enforce restrictive parent-directory permissions and verify permissions on externally supplied CA files.
ClientHello handling
The acceptor reads ClientHello under one absolute timeout using rustls's lazy acceptor. Rustls retains and replays the consumed ClientHello bytes into the eventual handshake and applies its parser limits.
Connections are rejected when ClientHello is malformed, incomplete, oversized, or too slow. SNI and the complete offered ALPN list are inspected before choosing the TLS configuration.
For a matching active ACME validation request, the server advertises only acme-tls/1 and uses the temporary RFC 8737 challenge certificate. Unsolicited challenge connections are rejected and never create orders.
Blocking API
Enable the blocking feature for synchronous applications:
use blocking;
use ;
use TcpListener;
The blocking facade uses one long-lived private Tokio runtime. It does not create a runtime per connection. Calling a blocking adapter from inside an async runtime returns InvalidConfig with a blocking-inside-async-runtime explanation.
The blocking end-to-end test uses the process-global manager and therefore runs as an isolated ignored test:
cargo test --all-features blocking_acceptor_completes_tls_and_supports_read_write -- --ignored --nocapture
Blocking event subscriptions provide recv and try_recv.
Failure behavior
- Unknown hosts never trigger issuance.
- Missing SNI never triggers issuance.
- A DNS ownership mismatch never contacts the public ACME server.
register_handlerfails until the port-443 handler is ready.- Issuance fails fast when no challenge handler is available.
- Disconnecting a waiting client does not cancel issuance.
- Concurrent requests join one task per domain and issuer.
- Failed renewal keeps the previous certificate until it expires.
- Expired certificates are removed and never served.
- Local fallback does not reset ACME retry state.
- Slow event consumers never delay certificate management.
- A failed managed Pebble startup leaves no partial global manager or child process.
Security notes
- Use Let's Encrypt staging before production.
- Restrict
allowed_hosts; never treat it as untrusted free-form regex. - Keep
cert_store_directoryprivate. Files contain certificate and CA private keys. - Install
AcmeLocalCAonly in clients intended to trust local fallback. - Never install Pebble's test roots in a production or general-purpose trust store.
- Do not expose managed Pebble on a non-loopback address.
- Do not log certificate records, account keys, challenge tokens, or private keys.
- Public DNS must resolve to a configured public IP, and the CA must be able to reach public port 443.
- A reverse proxy or NAT may map to another local port, but the public ACME validation endpoint remains port 443.
Feature flags
| Feature | Default | Purpose |
|---|---|---|
tokio-runtime |
yes | Async listener and stream integration |
folder-store |
yes | JSON folder-backed storage |
tracing |
optional | Structured tracing adapter |
blocking |
no | Synchronous facade |
pebble |
no | Pebble client/test configuration |
managed-pebble |
no | Supervise a system Pebble executable |
License
Licensed under either Apache-2.0 or MIT, at your option.