sentinel_proxy/acme/
mod.rs

1//! ACME automatic certificate management
2//!
3//! Provides zero-config TLS via Let's Encrypt and compatible CAs.
4//!
5//! # Features
6//!
7//! - Automatic certificate issuance and renewal
8//! - HTTP-01 challenge handling
9//! - DNS-01 challenge support for wildcard certificates
10//! - Modular DNS provider system (Hetzner, webhook)
11//! - Persistent storage for certificates and account credentials
12//! - Background renewal scheduler
13//!
14//! # Architecture
15//!
16//! The ACME module consists of five main components:
17//!
18//! - [`AcmeClient`] - Wrapper around `instant-acme` for ACME protocol operations
19//! - [`CertificateStorage`] - Persistent storage for certificates and account keys
20//! - [`ChallengeManager`] - Manages pending HTTP-01 challenges for serving
21//! - [`dns`] - DNS-01 challenge support with pluggable providers
22//! - [`RenewalScheduler`] - Background task for checking and renewing certificates
23//!
24//! # Example (HTTP-01)
25//!
26//! ```kdl
27//! listener "https" {
28//!     address "0.0.0.0:443"
29//!     protocol "https"
30//!
31//!     tls {
32//!         acme {
33//!             email "admin@example.com"
34//!             domains "example.com" "www.example.com"
35//!             staging false
36//!             storage "/var/lib/sentinel/acme"
37//!             renew-before-days 30
38//!         }
39//!     }
40//! }
41//! ```
42//!
43//! # Example (DNS-01 for Wildcards)
44//!
45//! ```kdl
46//! listener "https" {
47//!     address "0.0.0.0:443"
48//!     protocol "https"
49//!
50//!     tls {
51//!         acme {
52//!             email "admin@example.com"
53//!             domains "example.com" "*.example.com"
54//!             challenge-type "dns-01"
55//!
56//!             dns-provider {
57//!                 type "hetzner"
58//!                 credentials-file "/etc/sentinel/secrets/hetzner-dns.json"
59//!                 api-timeout-secs 30
60//!
61//!                 propagation {
62//!                     initial-delay-secs 10
63//!                     check-interval-secs 5
64//!                     timeout-secs 120
65//!                 }
66//!             }
67//!         }
68//!     }
69//! }
70//! ```
71//!
72//! # Challenge Flow (HTTP-01)
73//!
74//! When a certificate needs to be obtained or renewed:
75//!
76//! 1. [`AcmeClient`] creates a new order with the ACME server
77//! 2. For each domain, the ACME server provides a challenge token
78//! 3. [`ChallengeManager`] registers the token and key authorization
79//! 4. The ACME server validates by requesting `/.well-known/acme-challenge/<token>`
80//! 5. Sentinel's request filter intercepts and returns the key authorization
81//! 6. Once validated, [`AcmeClient`] finalizes the order and receives the certificate
82//! 7. [`CertificateStorage`] persists the certificate and triggers TLS reload
83//!
84//! # Challenge Flow (DNS-01)
85//!
86//! For wildcard certificates or when HTTP-01 is not feasible:
87//!
88//! 1. [`AcmeClient`] creates a new order with DNS-01 challenges
89//! 2. For each domain, [`dns::Dns01ChallengeManager`] creates TXT records via the DNS provider
90//! 3. [`dns::PropagationChecker`] waits for DNS propagation
91//! 4. The ACME server validates by querying `_acme-challenge.{domain}` TXT records
92//! 5. Once validated, [`AcmeClient`] finalizes the order and receives the certificate
93//! 6. DNS records are cleaned up, certificate is persisted
94
95mod challenge;
96mod client;
97pub mod dns;
98mod error;
99mod scheduler;
100mod storage;
101
102pub use challenge::ChallengeManager;
103pub use client::AcmeClient;
104pub use error::AcmeError;
105pub use scheduler::RenewalScheduler;
106pub use storage::CertificateStorage;
sentinel_proxy/acme/mod.rs

sentinel_proxy/acme/
mod.rs
