DNS-01 Challenge Explained: The Best Way to Get Wildcard SSL Certificates

If you're managing multiple subdomains or need HTTPS for internal services behind a firewall, the DNS-01 challenge is your best path to free SSL certificates.

Unlike HTTP-01 validation, DNS-01 works with any server configuration, supports wildcard certificates, and doesn't require a public-facing web server. It's the preferred method for DevOps engineers, system administrators, and anyone running a modern infrastructure.

In this guide, we'll cover everything: how DNS-01 works under the hood, how it compares to other ACME challenge types, step-by-step setup with major DNS providers, and how to automate the entire process so you never think about certificate renewal again.

What Is the DNS-01 Challenge?

The DNS-01 challenge is one of three ACME validation methods defined in RFC 8555. When you request a certificate from Let's Encrypt, the CA needs to verify that you control the domain. DNS-01 proves ownership by asking you to place a specific DNS TXT record in your domain's zone configuration.

How It Works

Here's the technical flow:

1. Your ACME client (like CertPilot or Certbot) generates a key authorization — a cryptographic token signed by your ACME account private key.
2. Let's Encrypt provides a validation string and expects to find it at _acme-challenge.yourdomain.com as a TXT record.
3. You (or your ACME client) add this TXT record to your DNS provider's zone file.
4. Let's Encrypt queries the DNS for _acme-challenge.yourdomain.com and checks if the TXT value matches the expected validation string.
5. If matched, the CA confirms you control the domain and issues the certificate.

The critical insight: DNS-01 validates domain ownership at the DNS level, not the web server level. This is what makes it fundamentally different from HTTP-01.

DNS-01 vs HTTP-01 vs TLS-ALPN-01

Feature	DNS-01	HTTP-01	TLS-ALPN-01
Wildcard support	✅ Yes	❌ No	❌ No
Public port required	❌ No (DNS only)	✅ Port 80	✅ Port 443
Works behind firewall	✅ Yes	❌ No	❌ No
Internal/private domains	✅ Yes	❌ No	❌ No
Setup complexity	Moderate	Simple	Simple
Automation ease	Requires DNS API	Easy (cron)	Easy (cron)
Propagation delay	⏱ Minutes	Instant	Instant

Why HTTP-01 Can't Do Wildcards

This is a common point of confusion. HTTP-01 validates by placing a file at http://domain.com/.well-known/acme-challenge/.... But for a wildcard certificate (*.example.com), which subdomain would Let's Encrypt check?

• http://anything.example.com/.well-known/... — there's no way to know which subdomain to check
• http://example.com/.well-known/... — this validates example.com, not *.example.com

The ACME specification explicitly forbids wildcard HTTP-01 validation for this reason. DNS-01 is the only standard method for wildcard certificates.

Setting Up DNS-01 Step by Step

Before You Start

You'll need:

• A domain where you control the DNS settings
• Access to your DNS provider's API (for automation) or web console (for manual setup)
• An ACME client (we'll use CertPilot as the primary example, but Certbot and acme.sh work similarly)

Manual DNS-01 Setup

1. Request a certificate with DNS-01 challenge type:

   # Using CertPilot CLI (conceptual)
   certpilot request --domain example.com --challenge dns-01 --wildcard
   

2. Receive the TXT record details:

   Record type: TXT
   Name: _acme-challenge.example.com
   Value: gfj9Hq1Jk_X9Z7dQ8yT3Lp5Rv2Bm4Nc6Wx0Es3At
   TTL: 60 (or as low as your provider allows)
   

3. Add the record in your DNS provider's console. Navigate to your DNS zone settings and add a new TXT record with the name and value provided.

4. Wait for propagation — typically 1-5 minutes, but can be longer depending on TTL settings.

5. Verify and complete — the ACME client checks for the record and completes the certificate issuance.

Automated DNS-01 Setup with Major Providers

For production use, manual DNS updates are impractical at scale. Here's how automation works with the most common DNS providers.

Cloudflare

# Cloudflare API — add TXT record concept
curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "TXT",
    "name": "_acme-challenge",
    "content": "gfj9Hq1Jk_X9Z7dQ8yT3Lp5Rv2Bm4Nc6Wx0Es3At",
    "ttl": 120
  }'

Best practice: Create a Cloudflare API token with DNS:Edit permission scoped to the specific zone only — never use the global API key.

AWS Route 53

# Using AWS CLI
aws route53 change-resource-record-sets \
  --hosted-zone-id ZONE_ID \
  --change-batch '{
    "Changes": [{
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "_acme-challenge.example.com.",
        "Type": "TXT",
        "TTL": 60,
        "ResourceRecords": [{"Value": "\"gfj9Hq1Jk_X9Z7dQ8yT3Lp5Rv2Bm4Nc6Wx0Es3At\""}]
      }
    }]
  }'

Note: Route 53 requires the TXT value to be wrapped in escaped quotes \"value\" — a common gotcha.

Google Cloud DNS

gcloud dns record-sets create _acme-challenge.example.com \
  --zone=example-zone \
  --type=TXT \
  --ttl=60 \
  --rrdatas="gfj9Hq1Jk_X9Z7dQ8yT3Lp5Rv2Bm4Nc6Wx0Es3At"

Namecheap

Namecheap supports automated DNS updates through its API with GET/POST requests. Enable Dynamic DNS and use the API endpoint to add or update _acme-challenge TXT records.

Wildcard Certificates Explained

What Wildcard Certificates Cover

A wildcard SSL certificate (*.example.com) secures one level of subdomains:

• ✅ blog.example.com
• ✅ api.example.com
• ✅ app.example.com
• ✅ mail.example.com
• ❌ blog.staging.example.com (two levels deep)
• ❌ example.com (the bare domain — you need a separate SAN entry)

Critical limitation: Wildcard certificates only cover *.example.com, not example.com itself. Most Let's Encrypt configurations add the bare domain as a separate Subject Alternative Name (SAN) entry, like this:

Subject: CN = *.example.com
X509v3 Subject Alternative Name:
    DNS:*.example.com, DNS:example.com

Multi-Level Wildcards Don't Exist

There's no such thing as **.example.com or *.*.example.com in the SSL world. The wildcard character * only matches a single label. If you need to cover blog.staging.example.com, you have three options:

1. Add it as a SAN on your existing certificate (up to 100 domains per cert on Let's Encrypt)
2. Issue a separate certificate specifically for that subdomain
3. Use DNS-01 validation to issue certificates for each level you need

DNS Propagation: The #1 Cause of DNS-01 Failures

DNS propagation is the most common pain point with DNS-01 challenges. Here's how to handle it.

Understanding TTL

TTL (Time To Live) tells DNS resolvers how long to cache a record. When validating, you want the lowest possible TTL so that Let's Encrypt's DNS queries return the new record quickly.

Recommendation: Set TTL to 60 seconds (or the minimum your provider allows) before starting validation. After the certificate is issued, you can increase it back to a normal value like 300 or 3600.

Checking Propagation

Before asking Let's Encrypt to verify, confirm the record is visible globally:

# Check with Cloudflare's DNS resolver (global)
dig TXT _acme-challenge.example.com @1.1.1.1

# Check with Google DNS
dig TXT _acme-challenge.example.com @8.8.8.8

# Check with your current resolver
dig TXT _acme-challenge.example.com +short

If these show the correct TXT value, Let's Encrypt will see it too.

Propagation Timing Chart

Provider	Typical Time	Max Observed
Cloudflare	< 30 seconds	2 minutes
AWS Route 53	< 1 minute	5 minutes
Google Cloud DNS	< 30 seconds	2 minutes
Namecheap	1-5 minutes	15 minutes
GoDaddy	5-15 minutes	60 minutes
Custom nameservers	Varies widely	Up to 24 hours

Security Best Practices for DNS-01

Since DNS-01 requires API access to your DNS provider, you're introducing a potential attack surface. Follow these practices to stay secure:

1. Use Scoped API Tokens

Never use global API keys. Every major DNS provider supports scoped tokens:

• Cloudflare: API tokens with DNS:Edit for specific zones only
• AWS: IAM policies scoped to specific hosted zones with route53:ChangeResourceRecordSets
• Google Cloud: Service accounts with dns.changes.create on specific managed zones

2. Rotate Credentials Regularly

Set up a quarterly rotation schedule for your DNS API credentials. If you're using CertPilot, credential management and rotation alerts are handled automatically.

3. Monitor DNS Changes

Enable audit logging on your DNS provider and set up alerts for unexpected _acme-challenge record creations. Cloudflare Audit Logs and AWS CloudTrail are your friends here.

4. Limit Exposure Window

DNS-01 challenges are short-lived. ACME validation tokens are typically valid for 30 minutes. Once validation is complete, you can remove the TXT record (if you're not using automated renewal). For automated setups, the ACME client handles cleanup.

Automating DNS-01 with CertPilot

If managing DNS API credentials and ACME clients sounds like a lot of overhead, CertPilot handles all of this automatically:

1. Add your domain and select DNS-01 as the validation method
2. Connect your DNS provider (Cloudflare, Route 53, Google Cloud DNS, Namecheap) via OAuth or scoped API tokens
3. CertPilot manages everything — creates the TXT record, waits for propagation, requests the certificate, and cleans up the record afterward
4. Auto-renewal is built in — certificates renew automatically before expiry, with real-time monitoring and alerts

For wildcard certificates, it's a single click. No manual DNS config, no cron jobs, no missed renewals.

Troubleshooting Common DNS-01 Issues

Problem: "No TXT record found" — but I added it!

Likely cause: DNS propagation delay or wrong record name. Fix: Double-check the record name. It should be _acme-challenge.example.com, not just example.com. Use the dig command above to verify.

Problem: "Invalid TXT record value"

Likely cause: Extra quotes, whitespace, or encoding issues. Fix: In most DNS providers, don't manually add quotes around the value — the provider adds them automatically. Route 53 requires double-escaped quotes; check our example above.

Problem: "Certificate issued but browser shows error"

Likely cause: Missing intermediate certificate or incomplete certificate chain. Fix: Ensure your web server serves the full chain: certificate + intermediate (R3) + root (ISRG Root X1). Most ACME clients, including CertPilot, include the full chain by default.

Problem: "Rate limited by Let's Encrypt"

Likely cause: Too many failed validation attempts or duplicate certificate requests. Fix: Let's Encrypt limits are generous but can be hit during testing. The key limit: 5 failed authorizations per domain per hour. Wait an hour or check Let's Encrypt's status page.

Frequently Asked Questions

Can I use DNS-01 without API access?

Yes, you can manually add the TXT record through your DNS provider's web interface. However, you'll need to repeat this every 90 days for renewal. Automation is strongly recommended for any production setup.

Does DNS-01 work with internal domains (not publicly resolvable)?

No. Let's Encrypt's validation servers must be able to query your public DNS. For internal domains, consider using a private CA or an ACME-compatible internal CA server.

Can I use DNS-01 with any domain registrar?

Yes, as long as you control the DNS zone. If your registrar doesn't support API-based DNS updates, you can transfer DNS management to a provider like Cloudflare (free plan works) while keeping the domain registered elsewhere.

How many certificates can I get with wildcard DNS-01?

Let's Encrypt allows 50 certificates per registered domain per week. With wildcard certificates, each certificate can cover unlimited first-level subdomains under that wildcard, plus up to 100 additional SAN entries.

Summary

DNS-01 is the gold standard for SSL certificate validation when you need:

• Wildcard certificates — the only standard ACME method that supports them
• Behind-firewall servers — no public ports required
• Automated renewal at scale — once set up with DNS API integration

The initial setup requires a bit more effort than HTTP-01, but the payoff is substantial: one wildcard certificate can secure your entire infrastructure, and automation makes renewal completely hands-off.

Ready to set up automated wildcard SSL certificates for your domains? Try CertPilot — free automated SSL certificate management with one-click DNS-01 validation and built-in auto-renewal.