# 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:
1. 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.
2. 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.
3. 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.
4. 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.
```text
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.
```text
┌────────────────────────────┐
│ 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 `AcmeLocalCA` for 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/` and `Local/` 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:
```text
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 `AcmeLocalCA` is trusted only by clients that have installed that CA. It is not a replacement for a publicly trusted certificate.
## Installation
```toml
[dependencies]
rustls-letsencrypt = "0.1"
tokio = { version = "1", features = ["macros", "net", "rt-multi-thread"] }
```
Enable the blocking facade or managed Pebble support when needed:
```toml
[dependencies]
rustls-letsencrypt = { version = "0.1", features = ["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:
```console
# 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.
```rust,no_run
use rustls_letsencrypt::{
register_alpn_handler,
AcmeEndpoint,
AlpnHandlerConfig,
EventOutput,
HostPattern,
LetsEncryptAcmeProfile,
};
use std::{net::IpAddr, path::PathBuf};
use tokio::net::TcpListener;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let listener = TcpListener::bind("0.0.0.0:443").await?;
let config = AlpnHandlerConfig {
allowed_hosts: vec![
HostPattern::exact("broker.example.com")?,
HostPattern::single_label_wildcard("*.services.example.com")?,
],
verify_dns_before_issuance: true,
dns_servers: None, // Use the system resolver.
public_ip_addresses: vec!["203.0.113.10".parse::<IpAddr>()?],
cert_store_directory: PathBuf::from("./certificates"),
acme_endpoint: AcmeEndpoint::LetsEncrypt(
LetsEncryptAcmeProfile::Production,
),
events: EventOutput::Stderr,
..AlpnHandlerConfig::default()
};
let mut incoming = register_alpn_handler(listener, Some(config)).await?;
while let Some(connection) = incoming.accept().await? {
tokio::spawn(async move {
let tls_stream = connection.into_stream();
// Read and write your application protocol through tls_stream.
drop(tls_stream);
});
}
Ok(())
}
```
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:
```rust,no_run
use rustls_letsencrypt::register_handler;
use tokio::net::TcpListener;
# async fn run() -> Result<(), Box<dyn std::error::Error>> {
let kafka_listener = TcpListener::bind("0.0.0.0:9092").await?;
let mut kafka_tls = register_handler(kafka_listener).await?;
while let Some(connection) = kafka_tls.accept().await? {
let server_name = connection.server_name();
let negotiated_alpn = connection.negotiated_alpn();
let stream = connection.into_stream();
println!("accepted TLS for {server_name:?} using {negotiated_alpn:?}");
drop(stream);
}
# Ok(())
# }
```
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`:
```rust,no_run
use rustls_letsencrypt::{AcmeEndpoint, AlpnHandlerConfig, EventOutput,
HostPattern, ManagedPebbleConfig};
# fn configuration() -> Result<AlpnHandlerConfig, Box<dyn std::error::Error>> {
let config = AlpnHandlerConfig {
allowed_hosts: vec![HostPattern::exact("api.test")?],
acme_endpoint: AcmeEndpoint::Pebble(ManagedPebbleConfig {
pebble_bind: "127.0.0.1:14000".parse()?,
pebble_executable: None,
working_directory: None,
state_directory: Some("./dev-certs/pebble-state".into()),
}),
cert_store_directory: "./dev-certs".into(),
verify_dns_before_issuance: false,
local_fallback_enabled: true,
issuance_attempt_timeout_secs: 30,
events: EventOutput::Stderr,
// Set this only when deliberately testing on an unprivileged port.
allow_non_443_listener: false,
..AlpnHandlerConfig::default()
};
# Ok(config)
# }
```
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:
```rust,no_run
use rustls_letsencrypt::{AcmeEndpoint, AlpnHandlerConfig, EventOutput,
HostPattern, LetsEncryptAcmeProfile};
# fn configuration() -> Result<AlpnHandlerConfig, Box<dyn std::error::Error>> {
let config = AlpnHandlerConfig {
allowed_hosts: vec![HostPattern::exact("api.example.com")?],
acme_endpoint: AcmeEndpoint::LetsEncrypt(LetsEncryptAcmeProfile::Staging),
acme_contacts: vec!["mailto:ops@example.com".into()],
public_ip_addresses: vec!["203.0.113.10".parse()?],
verify_dns_before_issuance: true,
cert_store_directory: "/var/lib/my-service/certificates".into(),
local_fallback_enabled: true,
issuance_attempt_timeout_secs: 60,
events: EventOutput::Stderr,
..AlpnHandlerConfig::default()
};
# Ok(config)
# }
```
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:
```rust,no_run
use rustls_letsencrypt::{AcmeEndpoint, AlpnHandlerConfig, DnsServer,
EventOutput, HostPattern, LetsEncryptAcmeProfile};
# fn configuration() -> Result<AlpnHandlerConfig, Box<dyn std::error::Error>> {
let config = AlpnHandlerConfig {
allowed_hosts: vec![
HostPattern::exact("api.example.com")?,
HostPattern::exact("broker.example.com")?,
],
acme_endpoint: AcmeEndpoint::LetsEncrypt(LetsEncryptAcmeProfile::Production),
acme_contacts: vec!["mailto:ops@example.com".into()],
public_ip_addresses: vec!["203.0.113.10".parse()?],
dns_servers: Some(vec!["1.1.1.1:53".parse::<DnsServer>()?]),
verify_dns_before_issuance: true,
cert_store_directory: "/var/lib/my-service/certificates".into(),
renew_days_before_expiry: 15,
renew_check_interval_secs: 3_600,
renew_check_max_interval_secs: 43_200,
issuance_attempt_timeout_secs: 60,
local_fallback_enabled: true,
events: EventOutput::Stderr,
..AlpnHandlerConfig::default()
};
# Ok(config)
# }
```
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:
```rust,no_run
use rustls_letsencrypt::{AcmeEndpoint, AlpnHandlerConfig, EventOutput, HostPattern};
# fn configuration() -> Result<AlpnHandlerConfig, Box<dyn std::error::Error>> {
let config = AlpnHandlerConfig {
allowed_hosts: vec![HostPattern::single_label_wildcard("*.internal.example")?],
acme_endpoint: AcmeEndpoint::LocalOnly,
verify_dns_before_issuance: false,
local_fallback_enabled: true,
local_leaf_validity_days: 30,
cert_store_directory: "/var/lib/my-service/private-certs".into(),
events: EventOutput::Stderr,
..AlpnHandlerConfig::default()
};
# Ok(config)
# }
```
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.
```rust,no_run
use rustls_letsencrypt::{
AcmeEndpoint,
AlpnHandlerConfig,
DnsServer,
EventOutput,
HostPattern,
LetsEncryptAcmeProfile,
};
use std::{net::IpAddr, path::PathBuf};
# fn config() -> Result<AlpnHandlerConfig, Box<dyn std::error::Error>> {
let config = AlpnHandlerConfig {
allowed_hosts: vec![HostPattern::exact("api.example.com")?],
verify_dns_before_issuance: true,
dns_servers: Some(vec![DnsServer::udp_then_tcp("1.1.1.1:53".parse()?)]),
public_ip_addresses: vec!["203.0.113.10".parse::<IpAddr>()?],
cert_store_directory: PathBuf::from("./certificates"),
acme_endpoint: AcmeEndpoint::LetsEncrypt(
LetsEncryptAcmeProfile::Production,
),
renew_days_before_expiry: 15,
renew_check_interval_secs: 3_600,
renew_check_max_interval_secs: 43_200,
client_hello_timeout_secs: 5,
issuance_attempt_timeout_secs: 60,
initial_connection_wait_timeout_secs: 60,
dns_lookup_timeout_secs: 5,
pebble_startup_timeout_secs: 30,
local_fallback_enabled: true,
events: EventOutput::Stderr,
..AlpnHandlerConfig::default()
};
# Ok(config)
# }
```
### 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.
```rust,no_run
# use rustls_letsencrypt::HostPattern;
# fn hosts() -> Result<(), Box<dyn std::error::Error>> {
let exact = HostPattern::exact("api.example.com")?;
let pattern = HostPattern::single_label_wildcard("*.services.example.com")?;
# Ok(())
# }
```
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.com` matches `one.services.example.com`.
- It does not match `services.example.com`.
- It does not match `one.two.services.example.com`.
- `*help.wushilin.net` matches `myhelp.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:
1. verifies the concrete SNI hostname against `allowed_hosts`;
2. resolves its A and AAAA records;
3. requires at least one result to match `public_ip_addresses`;
4. 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:
```rust,no_run
# use rustls_letsencrypt::{AlpnHandlerConfig, DnsServer};
let config = AlpnHandlerConfig {
verify_dns_before_issuance: true,
dns_servers: Some(vec![
"udp://1.1.1.1:53".parse::<DnsServer>()?,
"tcp://8.8.8.8:1053".parse::<DnsServer>()?,
"udp://[2001:4860:4860::8888]:53".parse::<DnsServer>()?,
]),
public_ip_addresses: vec!["203.0.113.10".parse()?],
..AlpnHandlerConfig::default()
};
# Ok::<(), Box<dyn std::error::Error>>(())
```
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:
```rust,no_run
# use rustls_letsencrypt::AlpnHandlerConfig;
let config = AlpnHandlerConfig {
verify_dns_before_issuance: false,
public_ip_addresses: vec![],
..AlpnHandlerConfig::default()
};
```
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
```rust,no_run
# use rustls_letsencrypt::{AcmeEndpoint, LetsEncryptAcmeProfile};
let staging = AcmeEndpoint::LetsEncrypt(LetsEncryptAcmeProfile::Staging);
let production = AcmeEndpoint::LetsEncrypt(LetsEncryptAcmeProfile::Production);
```
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:
```console
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.
```rust,no_run
use rustls_letsencrypt::{AcmeEndpoint, ManagedPebbleConfig};
let endpoint = AcmeEndpoint::Pebble(ManagedPebbleConfig {
pebble_bind: "127.0.0.1:1232".parse()?,
pebble_executable: None, // Resolve `pebble` from PATH.
working_directory: Some("./pebble-runtime".into()),
state_directory: Some("./certificates/pebble-state".into()),
..ManagedPebbleConfig::default()
});
# Ok::<(), Box<dyn std::error::Error>>(())
```
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:
1. resolves `pebble` from `PATH`, or uses `pebble_executable`;
2. generates the required local configuration and trust material;
3. starts Pebble and the scoped local validation adapter;
4. waits for readiness;
5. starts the normal ACME client against it;
6. 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:
```console
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:
```console
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
```rust,no_run
# use rustls_letsencrypt::AcmeEndpoint;
let endpoint = AcmeEndpoint::Custom {
directory_url: "https://ca.internal.example/acme/directory".parse()?,
issuer_id: "internal-ca".into(),
tls_trust_roots: vec![],
};
```
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`:
```text
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.pem` contains exactly one supported CA certificate;
- `CA.key` is a supported private key matching the certificate's public key;
- the certificate has `CA:TRUE` basic 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:
```text
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:
1. the manager validates the complete candidate pair;
2. it atomically installs a new in-memory `LocalCaState`;
3. it clears local ArcSwap slots for leaves not issued by the new CA;
4. it removes those records from the active `Local/` store and moves them to a non-loadable quarantine/audit location;
5. subsequent handshakes issue or select leaves from the new CA;
6. 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:
```rust,no_run
# async fn replace() -> Result<(), Box<dyn std::error::Error>> {
rustls_letsencrypt::install_local_ca(
std::fs::read("new-ca.pem")?,
std::fs::read("new-ca.key")?,
).await?;
# Ok(())
# }
```
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()`:
```text
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:
```rust,no_run
# use rustls_letsencrypt::AlpnHandlerConfig;
let config = AlpnHandlerConfig {
local_fallback_enabled: false,
..AlpnHandlerConfig::default()
};
```
## 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`.
```rust,no_run
use rustls_letsencrypt::subscribe_events;
# async fn observe() -> Result<(), Box<dyn std::error::Error>> {
let mut events = subscribe_events()?;
while let Some(event) = events.recv().await? {
println!("{} {:?}", event.sequence, event.kind);
}
# Ok(())
# }
```
Subscriptions work in every output mode:
```rust
pub enum EventOutput {
Subscribe, // No built-in console output.
Stderr, // Default.
Stdout,
}
```
| Mode | Built-in output | Subscription API |
|---|---|---|
| `Subscribe` | none | available |
| `Stderr` | stderr | available |
| `Stdout` | stdout | available |
Example output:
```text
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:
```rust,no_run
# use rustls_letsencrypt::{AlpnHandlerConfig, Event};
# use std::sync::Arc;
let config = AlpnHandlerConfig::builder()
.event_handler(Arc::new(|event: &Event| {
// Forward quickly to your own logger, metrics system, or queue.
eprintln!("{:?}", event.kind);
}))
.build()?;
# Ok::<(), Box<dyn std::error::Error>>(())
```
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:
```rust,no_run
# async fn read_cert() -> Result<(), Box<dyn std::error::Error>> {
let certificate = rustls_letsencrypt::get_certificate("broker.example.com").await?;
println!("issuer: {}", certificate.issuer_id());
println!("expires: {}", certificate.not_after());
let leaf_pem = certificate.leaf_pem();
let chain_pem = certificate.chain_pem();
let private_key = certificate.private_key_pem();
# Ok(())
# }
```
`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:
```text
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>`:
```rust,no_run
# use std::sync::Arc;
# use rustls_letsencrypt::{AlpnHandlerConfig, FolderCertStore};
let store = Arc::new(FolderCertStore::open("./certificates").await?);
let config = AlpnHandlerConfig::builder()
.cert_store(store)
.build()?;
# Ok::<(), Box<dyn std::error::Error>>(())
```
`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:
```rust,no_run
# use rustls_letsencrypt::CertStore;
# fn inspect(store: &dyn CertStore) {
let acme = store.acme();
let local = store.local();
# }
```
- `AcmeStoreNamespace` contains ACME accounts, ACME-issued certificate variants, issuer-specific retry state, and ACME quarantine records.
- `LocalStoreNamespace` contains `AcmeLocalCA`, 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:
```text
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_before` and `not_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:
```rust,no_run
use rustls_letsencrypt::blocking;
use rustls_letsencrypt::{AlpnHandlerConfig, EventOutput};
use std::net::TcpListener;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let listener_443 = TcpListener::bind("0.0.0.0:443")?;
let config = AlpnHandlerConfig {
events: EventOutput::Stderr,
// allowed hosts, public IPs, store, and ACME endpoint...
..AlpnHandlerConfig::default()
};
let mut tls_443 = blocking::register_alpn_handler(listener_443, Some(config))?;
let listener_9092 = TcpListener::bind("0.0.0.0:9092")?;
let mut tls_9092 = blocking::register_handler(listener_9092)?;
while let Some(connection) = tls_9092.accept()? {
std::thread::spawn(move || {
let mut stream = connection;
// Use std::io::Read and std::io::Write on stream.
let _ = &mut stream;
});
}
drop(tls_443);
Ok(())
}
```
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:
```console
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_handler` fails 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_directory` private. Files contain certificate and CA private keys.
- Install `AcmeLocalCA` only 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.