ACME DNS-01 certificates with PrimeDNS

The DNS-01 challenge lets you issue Let's Encrypt certificates, including wildcards (*.domain.tld), without exposing port 80/443. Your ACME client asks PrimeDNS to create a _acme-challenge TXT record, Let's Encrypt verifies it over DNS, and the client removes it again.

Choose your client

  • acme.sh: a shell ACME client, with a PrimeDNS DNS API plugin.
  • certbot: with two small hook scripts.
  • lego and Traefik: with the PrimeDNS provider built into lego.
  • cert-manager on Kubernetes: with the PrimeDNS webhook.

Any other client that can call an HTTP API or run a hook can use the same endpoint, see Calling the API directly. Every client needs the same thing first: an API key.

Create an API key

Go to Account → API Keys and create a key for ACME. Choose Certificate key and list in the hostnames field each hostname you will issue a certificate for (one per line, for example domain.tld and api.domain.tld) and untick the other scopes. Such a key gets one acme:name:_acme-challenge.<hostname> scope per name and can only create and remove the _acme-challenge TXT record for exactly those names, so a key that leaks from a server cannot change any of your records or validate any other name. domain.tld also covers *.domain.tld (both validate at the same name), but not api.domain.tld. (Keys with dns:write also work.)

Create new API key form

Wildcard certificates

A wildcard certificate (*.domain.tld) can only be issued with the DNS-01 challenge: Let's Encrypt states that "wildcard issuance must use the DNS-01 challenge". HTTP-01 cannot validate a wildcard, so this is the one case where DNS-01 is not just a convenience.

  • One level. *.domain.tld matches www.domain.tld, but not a.b.domain.tld and not domain.tld itself (RFC 6125, section 6.4.3).
  • Ask for both names when you need the bare domain too: -d domain.tld -d '*.domain.tld', as in the examples on the client pages.
  • Two TXT values, one name. Each of the two names is validated separately, so the CA expects two different values at _acme-challenge.domain.tld at the same time. PrimeDNS accepts several values under one name.

CNAME delegation: certificates for a domain hosted elsewhere

The simplest setup is the one above: the domain's DNS is on PrimeDNS, and the API key above is all you need. If a domain's DNS stays with another provider, for example one without an API, PrimeDNS can still answer the challenge for it. One record at the other provider forwards the challenge to a zone you host with us, and your ACME client writes the validation record there.

A workaround, not the long-term setup. It lets you automate certificates for a domain we do not serve. Hosting the domain on PrimeDNS is simpler and better: no forwarding record to maintain, one key for everything, and the domain gets all the other PrimeDNS features. When you can, move the domain to PrimeDNS.

An example

You want a certificate for shop.example.com, whose DNS is at another provider. In your PrimeDNS account you have the zone example.net, which will receive the validation records.

WhereRecordWho creates itHow long
At the other provider
(zone example.com)
_acme-challenge.shop.example.com CNAME validation.example.net. You, once, by hand Stays; used for every renewal
PrimeDNS
(zone example.net)
validation.example.net TXT "<token from the CA>" The PrimeDNS API, when your ACME client asks for it Seconds to minutes: removed right after validation

validation.example.net does not have to exist beforehand; the TXT record creates it. The two domains do not have to be related, and the CNAME is the only thing you add by hand.

Set it up

  1. Pick the target zone. Any zone of your PrimeDNS account will do (here example.net), and its nameservers must point to PrimeDNS. A name in somebody else's zone, or in a zone hosted at another provider, cannot be used.
  2. Create a key. In Account → API Keys choose Certificate key and leave hostnames empty. Under CNAME delegation targets enter validation.example.net. The key gets the scope acme:name:validation.example.net: it can add and remove TXT records at exactly that name and nowhere else.
  3. Add the CNAME at the other provider: _acme-challenge.shop.example.com pointing to validation.example.net.
  4. Run your ACME client with that key as PRIMEDNS_API_KEY, asking for a certificate for shop.example.com. The client has to know where the CNAME leads, so it can call the PrimeDNS API with the name validation.example.net. How you tell it depends on the client, see the table below.

What happens when the certificate is issued

  1. Your client asks the CA (Let's Encrypt or another) for a certificate for shop.example.com. The CA answers with a token to publish in DNS.
  2. The client calls the PrimeDNS API. PrimeDNS creates the TXT record at validation.example.net.
  3. The client waits a moment for the record to be served.
  4. The CA looks up _acme-challenge.shop.example.com. The other provider answers with the CNAME, the CA follows it to validation.example.net and gets the TXT record from the PrimeDNS nameservers. The token matches, so the domain is verified.
  5. The client calls the API again and the TXT record is removed. The CNAME stays for the next renewal.

If you ask for both shop.example.com and *.shop.example.com, both are checked at the same name, so two TXT records sit at validation.example.net at once. PrimeDNS accepts that, and each one is removed separately.

The target and your client

You can point the CNAME at the validation name in two forms. Both work; pick the one your client expects.

CNAME points toKey scope (from the key form)acme.shcert-manager
validation.example.net acme:name:validation.example.net, from the CNAME delegation targets field --domain-alias validation.example.net cnameStrategy: Follow
_acme-challenge.validation.example.net acme:name:_acme-challenge.validation.example.net, list validation.example.net under hostnames --challenge-alias validation.example.net cnameStrategy: Follow

acme.sh needs the alias option on the command line, see acme.sh. cert-manager follows the CNAME when the solver has cnameStrategy: Follow, see cert-manager. The certbot hook scripts write the record for the domain you pass to certbot, so use acme.sh or cert-manager for a domain whose DNS is elsewhere.

Calling the API directly

An ACME client or a script sends the full name of the TXT record to the API (that is what the plugins, hooks and the cert-manager webhook do). By hand it looks like this:

curl -X POST https://api.primedns.net/v1/dns/acme-challenge \
  -H "X-API-Key: $PRIMEDNS_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "_acme-challenge.shop.example.com", "value": "<token from the CA>"}'

curl -X DELETE https://api.primedns.net/v1/dns/acme-challenge \
  -H "X-API-Key: $PRIMEDNS_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "_acme-challenge.shop.example.com", "value": "<token from the CA>"}'

name is always the exact name of the TXT record: _acme-challenge.<hostname> for a certificate for <hostname> (also for its wildcard), or the CNAME target (for example validation.example.net) with a delegation. Removing a record needs its value, so other TXT records at the same name are never touched.

Troubleshooting

  • DOMAIN_NOT_FOUND: the domain is not in your PrimeDNS account, or the API key belongs to a different account or team.
  • 403: INSUFFICIENT_SCOPE means the key has no acme:name:<fqdn> scope (or dns:write). NAME_NOT_ALLOWED means the key is limited to other names; create a key that lists this one.
  • The CA reports NXDOMAIN looking up TXT for _acme-challenge... although the record was added: a resolver that looked that name up just before (a propagation check of your client, a manual dig or an earlier attempt) is still holding the "does not exist" answer. Our name servers drop it when the record is created, but a resolver you use may keep it for up to a minute (the SOA minimum of your zone). Wait a little and retry, and avoid querying the name yourself before the run.
  • 422: name or value is missing from the request, or domain was sent instead of name. Check that your client or hook passes the full record name and the token.