rustls-acme

To avoid exhausting Let's Encrypt API rate limits, production servers must implement both account and certificate caching.

• DirCache: A provided file-based cache implementation.
• Cache trait: Allows you to implement custom persistence layers for both certificates and accounts.
• CertCache and AccountCache traits: The underlying traits for specific caching needs.
• CompositeCache: A wrapper that combines two different implementors of CertCache and AccountCache into a single Cache.

Tip: Because error type parameters of the cache carry over to AcmeConfig, use AcmeConfig::cache_with_boxed_err if you want to avoid type specialization based on the specific cache type used.

The Cache trait is a convenience trait that combines both CertCache and AccountCache. Any type that implements both traits automatically implements Cache. This is useful when providing a single storage backend (like a filesystem or database) that handles both certificates and account data.

// Any type implementing both is automatically a Cache
pub trait Cache: CertCache + AccountCache {}
impl<T> Cache for T where T: CertCache + AccountCache {}

If you need to interact with rustls or futures_rustls directly, rustls-acme exposes:

1. AcmeState: Manages the underlying certificate lifecycle.
2. ResolvesServerCertAcme: A resolver that implements the rustls::server::ResolvesServerCert trait, allowing you to integrate ACME certificate management into a standard rustls server setup.

A future that resolves an incoming I/O stream into either a standard TLS handshake or an ACME TLS-ALPN challenge.

When polled, it checks if the client hello contains the ACME TLS-ALPN challenge. If it does, it handles the validation internally and returns Ok(None). Otherwise, it returns Ok(Some(StartHandshake)) for standard TLS traffic.

To use rustls-acme in your Rust project, add it to your Cargo.toml. Note that you must enable either the ring or aws-lc-rs feature, as the crate requires a crypto provider to function.

[dependencies]
rustls-acme = "*"

When the ACME order process fails, it returns an OrderError. Common causes include:

• Acme(AcmeError): A low-level error returned by the ACME protocol/directory.
• Rcgen(rcgen::Error): An error during CSR (Certificate Signing Request) generation.
• BadOrder(Order) / BadAuth(Auth): The order or authorization object received from the server was invalid.
• TooManyAttemptsAuth(String): The authorization for a specific domain failed too many times.
• ProcessingTimeout(Order): The order status remained in Processing for too long.

If certificate parsing fails, check for CertParseError:

• X509: The certificate failed X509 validation.
• Pem: The certificate was not in valid PEM format.
• TooFewPem: The PEM data did not contain the required number of blocks (e.g., missing private key or chain).
• InvalidPrivateKey: The private key type is unsupported.

The TestCache is a specialized cache implementation designed for testing. It generates self-signed certificates and dummy account data, making it suitable for environments where a real ACME server is unavailable or undesirable.

When using TestCache:

• It acts as a mock CA (Certificate Authority).
• load_cert generates a new certificate signed by the internal test CA.
• store_cert, load_account, and store_account are no-ops that log a message but do not persist any data.
• You can retrieve the CA's PEM representation using the ca_pem() method, which may be useful for configuring clients to trust the test CA.

# use rustls_acme::{AcmeConfig, caches::{DirCache, TestCache}};
# let test_environment = true;
let mut config = AcmeConfig::new(["example.com"])
    .cache(DirCache::new("./cache"));

if test_environment {
    config = config.cache(TestCache::default());
}

The NoCache struct provides a no-op implementation of both CertCache and AccountCache traits. Use it when you want to disable the persistence of certificates and ACME accounts (e.g., for testing or in-memory only environments).

When using NoCache:

• load_cert and load_account will always return Ok(None).
• store_cert and store_account will always return Ok(()) but will not actually save any data.
• All operations will log an info message stating that no cache is configured.

use rustls_acme::caches::NoCache;

// Initialize a no-op cache with Infallible error types
let no_cache = NoCache::<std::io::Error, std::io::Error>::default();

To handle incoming TLS connections using the certificates managed by AcmeState, use the incoming method. This provides a high-level API for accepting connections and managing the ACME lifecycle automatically.

If you are using Tokio, use tokio_incoming for a compatible integration.

If you are using Axum, use axum_acceptor to create an acceptor compatible with Axum's ecosystem.

// Standard async-io/futures approach
let incoming = state.incoming(tcp_stream, alpn_protocols);

// Tokio approach
let incoming = state.tokio_incoming(tokio_tcp_stream, alpn_protocols);

// Axum approach
let acceptor = state.axum_acceptor(rustls_config);

To wrap a stream of raw Tokio TCP connections into a Stream of tokio_util::compat::Compat<TokioTCP>, use TokioIncomingTcpWrapper. This is useful when you want to bridge raw Tokio TCP streams into a format compatible with futures-based APIs without applying TLS immediately.

// Assuming 'incoming_tcp' is a Stream of Result<TokioTCP, ETCP>
let tcp_wrapper = TokioIncomingTcpWrapper::from(incoming_tcp);