This functionality is currently being tested and is entirely at your own risk. Because the infrastructure used has yet to be migrated to ‘production’, we cannot guarantee that the generated authentication data will continue to work for a long time. Do not use ACME-DNS for production and contact certificaten-beheer@surf.nl if you would like to participate in testing.


ACME-DNS is a solution for DNS challenges within ACME that is independent of DNS hosting. For ACME, HARICA requires that an HTTP or DNS challenge be performed during the certificate request. It is not always desirable or possible to open the necessary ports for the HTTP challenge to the public. In addition, a DNS challenge is always required for wildcard certificates. To perform the DNS challenge automatically, an API is required for the DNS hosting. This is not always available, or it is not desirable to place the necessary credentials on all servers. As a solution, we offer an ACME-DNS server from SURFdomains (based on https://github.com/joohoi/acme-dns). This server can be accessed at https://acme-dns.surfdomeinen.nl, with the API endpoints at https://acme-dns.surfdomeinen.nl/api/. ACME-DNS is supported by various ACME clients, possibly by means of a plugin.

How does ACME-DNS work?

The number of steps below that are performed automatically varies per client, so please check the documentation before performing these steps. Supported clients can be found at https://github.com/joohoi/acme-dns?tab=readme-ov-file#clients. Below, we use acme-dns-client as an example (https://github.com/acme-dns/acme-dns-client), which can be used as manual-auth-hook in certbot.

Create a user

Create a new user via the register endpoint. In the allow field, specify the prefixes from which this user may be used (if this is not specified, there is no restriction). Three pieces of information will then be generated:

Next, a CNAME record must be created under the name or names for which a certificate is being requested. If a certificate is requested for example.nl, a CNAME record must be created for _acme-challenge.example.nl that refers to the random subdomain from the registrar. This step confirms that you actually have control over the domain for which a certificate is being requested.

Example acme-dns-client:

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

Request certificate

With the username and password from the previous step, it is possible to have TXT records included under the generated random subdomain. These TXT records are used within ACME to verify the DNS challenges. These records are set up via the update endpoint, where the last two TXT records are published.

Example 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>

The following steps for the DNS challenge then take place in the background:

  • HARICA generates a challenge.
  • acme-dns-client sends this to the update endpoint on the ACME-DNS server with authentication using the username and password from the registration.
  • ACME-DNS server records this challenge as a TXT record under the random subdomain associated with the account.
  • HARICA requests the TXT record for _acme-challenge.example.nl, following the CNAME to the random subdomain, after which it receives the challenge from the ACME-DNS server.
  • HARICA verifies that the challenge is correct and, if so, the certificate will be issued.
  • No labels