Crate certmagic 

certmagic

Automatic TLS certificate acquisition, renewal, and maintenance for Rust servers.

CertMagic manages TLS certificates for you: it obtains certificates from ACME CAs (Let’s Encrypt, ZeroSSL, …), renews them before expiry, staples OCSP responses, coordinates with other instances through shared storage, and can even obtain certificates on-demand during the TLS handshake.

Version 0.2 adds optional Redis/etcd coordination and S3, Vault KV v2 and AWS Secrets Manager certificate stores. Select their Cargo features explicitly; builds with etcd-storage require protoc. See the README upgrade notes before switching a shared FileStorage deployment from 0.1 to 0.2.

High-level API

// Manage certificates with default settings (Let's Encrypt production).
let _server_config = certmagic::manage(&["example.com".into()]).await?;

Advanced API

Create a Cache, then a Config, then manage domains:

use std::sync::Arc;
use certmagic::{Cache, CacheOptions, Config, ConfigOptions};

let cache = Cache::new(CacheOptions::default())?;
let config = Config::new(Arc::clone(&cache), ConfigOptions::default())?;
let ct = tokio_util::sync::CancellationToken::new();
config.manage_sync(&ct, &["example.com".into()]).await?;

// Serve TLS with rustls:
let server_config = config.tls_config()?;

Re-exports

pub use acme::acme_issuer::GOOGLE_TRUST_PRODUCTION_CA;

pub use acme::acme_issuer::GOOGLE_TRUST_STAGING_CA;

pub use acme::acme_issuer::LETS_ENCRYPT_PRODUCTION_CA;

pub use acme::acme_issuer::LETS_ENCRYPT_STAGING_CA;

pub use acme::acme_issuer::ZEROSSL_PRODUCTION_CA;

pub use acme::acme_issuer::LETS_ENCRYPT_PRODUCTION_CA as LETS_ENCRYPT_PRODUCTION;

pub use acme::acme_issuer::LETS_ENCRYPT_STAGING_CA as LETS_ENCRYPT_STAGING;

pub use acme::acme_issuer::ZEROSSL_PRODUCTION_CA as ZEROSSL_PRODUCTION;

pub use acme::order::ari_cert_id;

pub use acme::Account;

pub use acme::AccountKey;

pub use acme::AcmeClient;

pub use acme::AcmeIssuer;

pub use acme::AcmeIssuerBuilder;

pub use acme::Directory;

pub use acme::DirectoryMeta;

pub use acme::EabCredentials;

pub use acme::Jwk;

pub use acme::RenewalInfoResponse;

pub use acme::SignatureAlgorithm;

pub use acme::SuggestedWindow;

pub use acme::prompt_user_agreement;

pub use acme::prompt_user_agreement_with_io;

pub use acme::prompt_user_for_email;

pub use acme::prompt_user_for_email_with_io;

pub use cache::Cache;

pub use cache::CacheEvent;

pub use cache::CacheOptions;

pub use cache::SubjectIssuer;

pub use acme::acme_issuer::ChainPreference;

pub use cert_store::remote::ImmutableBlobStore;

pub use cert_store::remote::RemoteCertStore;

pub use cert_store::s3::S3BlobStore;

pub use cert_store::s3::S3BlobStoreOptions;

pub use cert_store::s3::S3CertStore;

pub use cert_store::secrets_manager::SecretsManagerBlobStore;

pub use cert_store::secrets_manager::SecretsManagerCertStore;

pub use cert_store::secrets_manager::SecretsManagerOptions;

pub use cert_store::vault::VaultCertStore;

pub use cert_store::vault::VaultKv2BlobStore;

pub use cert_store::vault::VaultKv2BlobStoreOptions;

pub use cert_store::CertStore;

pub use cert_store::KeyValueCertStore;

pub use certificate::Certificate;

pub use certificate::RenewalInfo;

pub use certificate::RenewalWindow;

pub use certificate::cert_needs_renewal;

pub use certificate::currently_in_renewal_window;

pub use certificate::make_certificate;

pub use certificate::match_wildcard;

pub use certificate::normalize_sni;

pub use certificate::normalized_name;

pub use certificate::subject_is_internal;

pub use certificate::subject_is_ip;

pub use certificate::subject_qualifies_for_cert;

pub use certificate::subject_qualifies_for_public_cert;

pub use config::CertificateSelector;

pub use config::Config;

pub use config::ConfigBuilder;

pub use config::ConfigOptions;

pub use config::DefaultCertificateSelector;

pub use config::IssuerPolicy;

pub use config::Manager;

pub use config::OcspConfig;

pub use config::OnDemandConfig;

pub use config::Policy;

pub use crypto::KeyGenerator;

pub use crypto::KeyType;

pub use crypto::StandardKeyGenerator;

pub use error::Error;

pub use error::Result;

pub use https::HttpsRedirectHandler;

pub use https::HttpsRequest;

pub use https::HttpsResponse;

pub use https::https;

pub use https::https_on;

pub use https::start_https_redirect;

pub use https::start_https_redirect_to_host;

pub use https::start_https_redirect_with_port;

pub use issuer::CertificateResource;

pub use issuer::Csr;

pub use issuer::IssuedCertificate;

pub use issuer::Issuer;

pub use issuer::PreChecker;

pub use issuer::RevocationReason;

pub use issuer::Revoker;

pub use issuer::as_acme_issuer;

pub use maintain::MaintenanceConfig;

pub use maintain::start_maintenance;

pub use maintain::stop_maintenance;

pub use config::Manager as CertificateManager;

pub use issuer::Issuer as CertIssuer;

pub use solvers::Solver;

pub use solvers::distributed::DistributedSolver;

pub use solvers::dns::Dns01Solver;

pub use solvers::dns::DnsProvider;

pub use solvers::dns::DnsResolver;

pub use solvers::http::Http01Solver;

pub use solvers::tls_alpn::ChallengeCert;

pub use solvers::tls_alpn::TlsAlpnSolver;

pub use ratelimiter::RingBufferRateLimiter;

pub use solvers::http::HttpChallengeHandler;

pub use solvers::http::HttpChallengeMap;

pub use solvers::http::extract_http_challenge_token;

pub use solvers::http::handle_http_challenge;

pub use solvers::http::handle_http_challenge_request;

pub use solvers::http::handle_http_challenge_request_async;

pub use solvers::http::handle_http_challenge_request_blindly;

pub use solvers::http::is_valid_http_challenge_token;

pub use solvers::http::looks_like_http_challenge;

pub use solvers::http::solve_http_challenge_blindly;

pub use storage::FileStorage;

pub use storage::CERTS_PREFIX;

pub use storage::CleanStorageOptions;

pub use storage::KeyBuilder;

pub use storage::KeyInfo;

pub use storage::KeyValue;

pub use storage::LockGuard;

pub use storage::LockHandle;

pub use storage::Locker;

pub use storage::OCSP_PREFIX;

pub use storage::STORAGE_KEYS;

pub use storage::Storage;

pub use storage::StorageKeys;

pub use storage::account_key_prefix;

pub use storage::account_private_key;

pub use storage::account_registration;

pub use storage::acme_ca_prefix;

pub use storage::acme_hosts_prefix;

pub use storage::acquire;

pub use storage::acquire_lock;

pub use storage::acquire_with_timeout;

pub use storage::certs_prefix;

pub use storage::certs_site_prefix;

pub use storage::clean_up_own_locks;

pub use storage::cleanup_own_locks;

pub use storage::issuer_key;

pub use storage::legacy_account_key_prefix;

pub use storage::load_certificate;

pub use storage::locks_key;

pub use storage::ocsp_key;

pub use storage::ocsp_staple_key;

pub use storage::safe_key;

pub use storage::site_cert_key;

pub use storage::site_meta_key;

pub use storage::site_private_key;

pub use storage::store_certificate;

pub use storage::store_tx;

pub use storage::track_lock;

pub use storage::try_acquire;

pub use storage::try_acquire_lock;

pub use storage::untrack_lock;

pub use storage::EtcdStorage;

pub use storage::EtcdStorageOptions;

pub use storage::EtcdTlsOptions;

pub use storage::RedisStorage;

pub use storage::RedisStorageOptions;

pub use tls_integration::install_default_provider;

pub use tls_integration::install_default_provider as install_default_crypto_provider;

pub use tls_integration::CertmagicAcceptor;

pub use tls_integration::CertmagicResolver;

pub use tls_integration::ResolverSource;

pub use zerossl::ZEROSSL_HTTP_VALIDATION_PREFIX;

pub use zerossl::ZeroSslApiIssuer;

pub use zerossl::handle_zerossl_http_validation;

pub use zerossl::looks_like_zerossl_http_validation;

pub use zerossl::ZeroSslIssuer;

pub use zerossl::ZeroSslIssuerBuilder;

Modules

acme

ACME support: account keys and JWS primitives, directory discovery, nonce management, accounts with EAB, the order state machine, ARI, and a transport abstraction that keeps the protocol unit-testable.

cache

In-memory certificate cache.

cert_store

Certificate-resource storage independent from account, lock and challenge storage.

certificate

The Certificate type, parsing, name matching, subject qualification, and renewal-window math.

clock

Injectable clock for time-sensitive logic (renewal windows, OCSP freshness, retry pacing). Production code uses SystemClock; tests use MockClock.

config

Configuration.

crypto

Key generation, PEM codecs, CSRs, and certificate-chain hashing .

dnsutil

DNS utilities for DNS-01 propagation checks.

error

Error types for the certmagic crate.

events

Typed event system.

handshake

TLS handshake integration.

http

Shared outbound HTTP client compatibility surface.

http_handler

Standalone HTTP-01 challenge handler module.

https

Framework-neutral HTTPS serving wrapper.

issuer

Issuer abstraction: certificate sources.

localcache

Node-local read-through cache over another Storage .

maintain

Background certificate maintenance.

ocsp

OCSP stapling.

pem

Minimal PEM (RFC 7468) encoding/decoding.

ratelimiter

Sliding-window rate limiter.

runtime

Runtime infrastructure: background job management and retry-with-backoff.

singleflight

In-process single-flight coordination.

solvers

Challenge solvers.

storage

Storage abstraction.

tls_integration

rustls integration glue.

zerossl

ZeroSSL issuer.

Structs

CertManager

High-level certificate lifecycle manager.

CertManagerBuilder

Builder for CertManager.

Statics

HTTPS_PORT

Public HTTPS listener port used by listen.

HTTP_CHALLENGE_PORT

Port used for HTTP-01 validation (normally HTTP_PORT).

HTTP_PORT

Public HTTP listener port used by the built-in HTTP-01 solver.

TLS_ALPN_CHALLENGE_PORT

Port used for TLS-ALPN-01 validation (normally HTTPS_PORT).

USER_AGENT

Process-wide ACME User-Agent. Initialized to certmagic-rs/<version> on first read; applications may override it via set_user_agent before the first ACME request.

Functions

default_acme_issuer

Return a fresh Let’s Encrypt issuer with terms pre-agreed for the convenience entrypoints.

default_config

Return a fresh default configuration options value.

listen

Manage certificates and bind a TLS listener on the configured HTTPS port . The default HTTP-01 challenge listener is used during management and is released before the returned listener is bound. Configure a DNS provider if binding the challenge port is not appropriate. The returned acceptor resolves certificates asynchronously before each handshake.

listen_acceptor

Obtain or load certificates, probe-bind addr, and return a standard tokio_rustls::TlsAcceptor backed by the resulting rustls configuration.

listen_on

Variant of listen for applications that choose the bind address.

listen_with_addr

Alias for listen_acceptor.

manage

Manage domain_names with the default configuration and return a ready to use rustls rustls::ServerConfig.

manage_async

Like manage_sync but per-domain management runs in background jobs with retry.

manage_sync

Manage domain_names with the default configuration: obtain missing certificates and keep them renewed.

obtain

Obtain one certificate immediately using the default configuration.

obtain_cert_sync

Obtain one certificate immediately with the default configuration.

obtain_in_background

Request one certificate in the background using the default configuration.

server_config

Alias for tls.

set_user_agent

Override the ACME User-Agent. Unlike a mutable package variable, only the first call wins — Rust statics are not mutable after initialization. Returns false if something was already set.

tls

Manage domain_names with the default configuration and return a rustls rustls::ServerConfig serving the cached certificates.

user_agent

The effective ACME User-Agent string.

Type Aliases

CertCache

Alias for Cache.

CertResolver

Alias for tls_integration::CertmagicResolver.

RateLimiter

Alias for the sliding-window rate limiter.

TlsAlpn01Solver

Alias for the TLS-ALPN-01 solver.