rustls-letsencrypt 0.1.1

Automatic Let's Encrypt, ACME, and local-CA certificate management for rustls listeners
Documentation

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.
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 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:

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

[dependencies]
rustls-letsencrypt = "0.1"
tokio = { version = "1", features = ["macros", "net", "rt-multi-thread"] }

Enable the blocking facade or managed Pebble support when needed:

[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:

# 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 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:

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:

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:

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:

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:

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.

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.

# 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:

# 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:

# 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

# 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:

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 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:

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 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:

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:

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:

# 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():

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 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.

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:

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:

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 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:

# 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:

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 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:

# 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:

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:

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:

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.