glm-5.1
596c89ce24
Rename all crates, CLI commands, constants, type names, doc comments, and documentation from wraith to alknet. Includes wire-protocol changes: ALPN wraith-ssh -> alknet-ssh, reserved destination prefix wraith- -> alknet-, SSH auth username wraith -> alknet.
2.6 KiB
ADR-008: ACME/Let's Encrypt Certificate Provisioning
Status
Accepted
Context
TLS transport mode requires certificates. Manual certificate management is error-prone — users need to obtain, install, and renew certificates. Our production setup uses certbot with Let's Encrypt (documented in /workspace/system/dev1/certbot.md), which automates this via the ACME protocol.
There are two ACME flows:
- Domain-based: Standard flow with DNS-01 or HTTP-01 challenge. Certificate is tied to a domain name, auto-renews via certbot/systemd timer. Requires port 80 or DNS access for challenges.
- IP-based: Short-lived certificates via TLS-ALPN-01 challenge on port 443. No domain needed, but cert is short-lived (days, not months). Simpler for quick setups but requires the ACME client to run continuously.
Both flows are important for alknet's usability. Without ACME, TLS mode requires manual cert setup — a significant barrier for users who want "SSH over port 443" for censorship resistance.
Decision
Support both ACME certificate provisioning paths:
-
Domain-based ACME (
--acme-domain <domain>): Standard certbot-style flow. Certificate is domain-bound, auto-renews. The server runs a challenge responder (HTTP-01 on port 80 or TLS-ALPN-01 on port 443) during certificate issuance/renewal. -
IP-based ACME: Short-lived certs for servers without a domain. Uses TLS-ALPN-01 challenge on port 443. Lower burden but certs expire frequently.
-
Manual certs (
--tls-cert/--tls-key): Always supported for users with existing certificates or specific PKI setups.
The implementation should use the rustls-acme crate (or similar pure-Rust ACME client) to avoid an external certbot dependency. This keeps alknet self-contained as a single binary.
Consequences
- Positive: Users can run
alknet serve --transport tls --acme-domain example.comand get working TLS with zero manual cert management. - Positive: IP-based ACME covers the quick-setup case without requiring a domain.
- Positive: Consistent with our production infrastructure (certbot + Let's Encrypt is already our standard).
- Negative: ACME adds complexity to the server binary (challenge responder, cert store, renewal timer).
- Negative: IP-based short-lived certs require more frequent renewal handling.
- Negative: Binary size increases with ACME support (rustls-acme dependency). Consider making ACME a feature flag (
acme).