Wildcard certificates with DNS-01 validation
Wildcard certificates need DNS validation, and DNS validation usually means handing out a DNS API key. Here’s how DNS-01 works and three ways to automate it, including two that keep your DNS keys to yourself.
How DNS-01 works
ACME, the protocol behind Let’s Encrypt and other free certificate authorities, lets you prove control of a domain in a few ways. With DNS-01, the CA gives your client a token, the client publishes a value derived from it as a TXT record at _acme-challenge.example.com, and the CA looks it up. If the record is there, you control the domain.
DNS-01 is the only method CAs accept for wildcard certificates (*.example.com). It also works for servers that aren’t reachable from the internet, since nothing has to be served on port 80 or 443.
The catch: the TXT record changes on every order. With certificates now limited to 200 days, soon 100 and then 47, and domain validations reused for less and less time, records have to be created automatically. That means something needs to be able to change your DNS.
Option 1: your DNS provider’s API
The usual approach: give the ACME client an API key for your DNS provider. It creates the TXT record, waits for it to appear, and removes it afterwards. EverTLS supports Cloudflare, Route 53, Azure DNS, Google Cloud DNS, DigitalOcean and 190+ more.
The risk: many providers’ keys can change any record in the account, so a leaked key could redirect your website or email. Limit it where you can: Cloudflare tokens can be scoped to Zone · DNS · Edit on one zone, and AWS IAM policies can be limited to one hosted zone. EverTLS stores keys encrypted with a key held in a hardware security module.
Option 2: keep the key on your own server
If you don’t want a DNS key on anyone else’s systems, keep it on a server you run. With EverTLS, save the key on any server running the agent:
sudo evertls-agent dns add example-dns --provider cloudflare(On Windows, run evertls-agent.exe in PowerShell as Administrator.) Then set the domain’s validation to DNS · key on agent. When a certificate is issued or renewed, EverTLS asks the agent to create the record, and the agent does it with its local key. EverTLS only ever knows the key’s name. The agent has to be online during issuance and renewal.
Option 3: CNAME delegation, no key at all
DNS lets you point _acme-challenge.example.com somewhere else with a CNAME record, and CAs follow it. So you add one CNAME, once, to a name the validation service controls, and it answers every challenge from then on:
_acme-challenge.example.com. CNAME (the unique target shown in your EverTLS dashboard)Nobody needs a key to your DNS, and it works with any DNS host, including ones without an API. Each domain gets its own target, so one customer’s delegation can’t be used for another’s domain. This is the method we recommend when you can add one record by hand.
Which one?
- CNAME delegation: the best default. One record, no keys, any DNS host.
- Key on the agent: when you can’t add CNAMEs (policy, or a DNS host that doesn’t allow them on
_acme-challenge), but don’t want a key stored centrally. - Provider API in EverTLS: the least setup when you already trust the service with a narrowly scoped key, and the only one that keeps working with no agent online.
Common problems
- The CA doesn’t see the record yet: DNS takes time to update every authoritative server. Clients wait and check before asking the CA, but slow providers may need longer.
- CAA records: if your domain has CAA records, they must allow the CA you use (for example
0 issuewild "letsencrypt.org"for wildcards). - Split DNS: the CA looks the record up on the public internet. Internal-only zones need a public delegation for
_acme-challenge.