# 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:**
```dns
; 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.