docs/infrastructure/acme.md

ACME DNS Challenges

Summary

We agreed to use ACME DNS-01 challenges for issuing certificates for both public-facing and internal services. A key benefit is that DNS-01 enables internal certificate issuance in the first place, since the CA only needs to verify TXT records in DNS (no inbound HTTP/ALPN access to the service). To keep our primary DNS zones clean, we will create a separate, dedicated zone for ACME challenges and delegate challenge records to it via CNAME.

Decisions

• Use ACME DNS-01 as the challenge type for both external/public and internal certificate issuance.
• Create a dedicated DNS zone for ACME challenges (e.g., _acme.example.com).
• For each certificate FQDN, publish a CNAME at _acme-challenge.<fqdn> that points into the dedicated challenge zone.
• Store the TXT token(s) only in the dedicated challenge zone to avoid cluttering primary zones.
• Keep low TTLs (e.g., 60-120s) on both CNAME and TXT records to speed up renewals.
• Restrict write access to the challenge zone to the ACME automation only.

Meetings

• 05.08.2025: Bert-Jan Fikse, Tobias Schaller, Tobias Wüst, Tom Jampen (inital version)

Background

The following article explains how DNS-01 challenges can be effectively used to issue Let's Encrypt certificates for servers with internal IP addresses:

• https://lists.bfh.science/pipermail/bfh-linux-announce/2021-September/000134.html

The following manpage explains important implementation details for correctly handling DNS-01 challenges:

• https://sources.debian.org/src/open-infrastructure-service-tools/20250626-2/dehydrated/share/man/dehydrated-nsupdate.1.rst#L20

Reference Design

Dedicated zone: _acme.digitalboard.ch

Dedicated zone for each managed school: gymkirchenfeld._acme.digitalboard.ch

For a service FQDN: Target certificate: app1.gymkirchenfeld.ch, app2.kinet.ch

Publish in the primary zone:

; Delegate the challenge to the dedicated zone
_acme-challenge.app1.gymkirchenfeld.ch.  IN  CNAME
app1.gymkirchenfeld.ch.gymkirchenfeld._acme.digitalboard.ch.

_acme-challenge.app2.kinet.ch.           IN  CNAME
app2.kinet.ch.gymkirchenfeld._acme.digitalboard.ch.

_acme-challenge.app.example.com.        IN  CNAME
app.example.com.school-a._acme.digitalboard.ch.

During validation, the CA will follow the CNAME from the primary zone to the dedicated zone and read the TXT record there.