(NL) ACME-DNS via SURFdomeinen

ACME-DNS is een oplossing voor DNS challenges binnen ACME die onafhankelijk is van de DNS hosting. Voor ACME vereist HARICA dat een HTTP of DNS challenge wordt uitgevoerd tijdens de aanvraag van een certificaat. Het is niet altijd gewenst of mogelijk om de benodigde poorten voor de HTTP challenge publiek open te zetten. Daarnaast is voor wildcard certificaten altijd een DNS challenge vereist. Om de DNS challenge automatisch uit te voeren is een API nodig bij de DNS hosting. Dit is niet altijd beschikbaar, of het is niet gewenst om de benodigde credentials op alle servers te plaatsen. Als oplossing hiervoor bieden we vanuit SURFdomeinen een ACME-DNS server aan (op basis van https://github.com/joohoi/acme-dns). Deze server is bereikbaar op https://acme-dns.surfdomeinen.nl, met de API endpoints onder https://acme-dns.surfdomeinen.nl/api/. ACME-DNS wordt door verschillende ACME clients ondersteund, eventueel door middel van een plugin.

Hoe werkt ACME-DNS?

Het verschilt per client hoeveel van onderstaande stappen automatisch worden uitgevoerd, dus ga dit eerst na in de documentatie voordat je deze stappen uitvoert. Ondersteunde clients zijn te vinden op https://github.com/joohoi/acme-dns?tab=readme-ov-file#clients. Hieronder gebruiken we acme-dns-client als voorbeeld (https://github.com/acme-dns/acme-dns-client), welke als manual-auth-hook in certbot kan worden gebruikt.

Maak een gebruiker aan

Via het register endpoint een nieuwe gebruiker aan. Hierbij geef je in het veld allow op vanaf welke prefixes deze gebruiker mag worden gebruikt (als dit niet wordt ingevuld is er geen beperking). Er worden dan drie gegevens gegenereerd:

• Gebruikersnaam
• Wachtwoord
• Random subdomein (xyz.acme-dns.surfdomeinen.nl)

Vervolgens moet een CNAME record worden aangemaakt onder de naam of namen waarvoor een certificaat wordt aangevraagd. Als een certificaat wordt aangevraagd voor example.nl, moet een CNAME records worden aangemaakt voor _acme-challenge.example.nl die verwijst naar het random subdomein uit de registraite. Deze stap is de bevestiging dat je daadwerkelijk controle hebt over het domein waarvoor een certificaat wordt aangevraagd.

Voorbeeld acme-dns-client:

acme-dns-client register -d example.nl -s https://acme-dns.surfdomeinen.nl/api --allow <ipv4prefix>,<ipv6prefix>

Vraag certificaat aan

Met de gebruikersnaam en het wachtwoord uit de vorige stap is het mogelijk om TXT records op te laten nemen onder het gegenereerde random subdomein. Deze TXT records worden binnen ACME gebruikt om de DNS challanges te verifieren.  Het instellen van deze records gaat via het update endpoint, waarbij de laatste twee TXT records worden gepubliceerd.

Voorbeeld acme-dns-client:

certbot certonly --manual --preferred-challenges dns --manual-auth-hook 'acme-dns-client' -d example.nl --server https://acme.harica.gr/TCS-DV/directory --eab-kid <eabkey> --eab-hmac-key <hmac-key>

Op de achtergrond vinden dan de volgende stappen plaats voor de DNS challenge:

• HARICA genereert een challenge.
• acme-dns-client stuurt deze naar het update endpoint op de ACME-DNS server met authenticatie door middel van de gebruikersnaam en wachtwoord uit de registratie.
• De ACME-DNS server neemt deze challenge op als TXT record onder het random subdomein dat bij de account hoort.
• HARICA vraagt het TXT record op voor _acme-challenge.example.nl en volgt daarbij de CNAME naar het random subdomein, waarna het de challenge ontvangt van de ACME-DNS server.
• HARICA en verifieert of de challenge correct is en als dit het geval is zal het certificaat worden uitgegeven.