Skip to content

ADR-0004 — HTTP-01 over DNS-01 for ACME certificate issuance

  • Status: accepted
  • Date: 2026-06-30
  • Domain: TLS · secrets exposure

Context

TLS certificates are issued automatically by Let's Encrypt via Traefik (ADR-0002). The ACME protocol offers two challenge types to prove control of a hostname: HTTP-01, which serves a token over port 80 on the host being certified, and DNS-01, which creates a TXT record via the DNS provider's API and supports wildcard certificates but requires storing DNS-API credentials on the host. Each service gets its own per-host certificate; there is no requirement for a single wildcard certificate. Port 80 is reachable because the origin is exposed directly (ADR-0003).

Decision

HTTP-01. With the origin already exposed and port 80 reachable, HTTP-01 is the simplest path to a valid certificate, and it keeps a DNS-provider API token off the box entirely — which meaningfully shrinks the blast radius of a host compromise, since that token would otherwise grant control over the whole domain's DNS. Wildcard certificates, the main reason to prefer DNS-01, are not needed: per-host certs are perfectly adequate for the flat <project>.tarik-lab.dev scheme.

Consequences

  • No DNS-API secret stored on the host — a host compromise cannot be escalated into DNS takeover via this path. The issuance flow is the simplest possible: nothing to configure beyond pointing Traefik at the ACME endpoint.
  • Cannot issue wildcard certificates; every hostname gets its own cert. Requires port 80 to remain open and inbound-reachable for issuance and renewal — many small certs rather than one broad one, a minor operational detail at this scale.
  • Switching to DNS-01 later is a configuration change, not a redesign, should a wildcard cert or a setup without inbound port 80 become necessary. Revisit if a wildcard certificate becomes necessary (many short-lived subdomains, or hiding individual hostnames from certificate transparency logs), or if port 80 can no longer be exposed for validation.

Alternatives considered

  • DNS-01 — rejected for now: gains wildcard-cert support, but requires storing a DNS-provider API token on the host — a credential whose compromise would grant control over the whole domain's DNS, which is a worse trade than per-host certs for this flat subdomain scheme.