Automated Certificate Management Environment, or ACME, is a protocol that lets a certificate authority verify control of identifiers and issue certificates without a manual approval exchange. Before a CA issues for a DNS name, it asks the client to complete a challenge. DNS-01 is one of those challenge types.
The DNS-01 validation transaction
For a requested name such as app.example.com, the ACME server provides a random token. The client combines that token with the ACME account key authorization, hashes the result, and publishes it as a TXT value beneath:
_acme-challenge.app.example.comThe CA resolves that record from its own validation infrastructure. If the expected value is visible and the authorization remains valid, control is proven. After validation, the client removes the temporary record. The certificate private key never needs to enter DNS; only the challenge proof is published.
Production clients should let an ACME library or established client such as lego implement token construction and protocol state. Reimplementing the protocol around a few API calls creates subtle account, nonce, authorization, retry, and cleanup risks.
Why wildcard certificates require DNS-01
A wildcard such as *.example.com can represent hosts that do not exist when the certificate is issued. An HTTP request to one particular server cannot prove authority over every possible first-level name. DNS control can. Public ACME certificate authorities therefore require DNS-01 for wildcard identifiers.
The wildcard and apex are separate identifiers. A certificate containing both example.com and *.example.com may require multiple challenge values at the same TXT owner name. Your DNS provider and client must preserve simultaneous values until all related authorizations finish.
Propagation is more than waiting for a TTL
DNS updates pass through a provider API, authoritative name servers, recursive resolvers, and caches. The visible time depends on provider commit behavior, authoritative consistency, negative caching, resolver paths, and the CA's perspective. Setting a low TTL cannot make an update visible before the authoritative service applies it.
A reliable client checks authoritative DNS and then the recursive view it expects the CA to use. Fixed delays can be useful for a provider with predictable behavior, but a blind sleep is neither proof of visibility nor proof of failure. Keep propagation timeouts bounded and provider-specific.
Treat DNS API credentials as certificate authority
A credential able to change arbitrary records can redirect web traffic, email, identity verification, and future certificate challenges. It may be more powerful than the certificate private key it helps create. Use the narrowest credential your provider supports:
- Limit access to the exact hosted zone.
- Allow TXT changes only when provider conditions can enforce record type.
- Restrict record names to required
_acme-challengeowners when possible. - Separate read and write tokens if the provider supports it cleanly.
- Avoid account-wide administrator keys and interactive user credentials.
- Store credentials in restrictive files owned by the certificate service identity.
Do not place provider secrets in command history, process arguments, container image layers, source repositories, browser storage, or general application logs. Rotate a credential at its native source and verify the automation still sees the intended identity before the next order.
Challenge delegation can reduce the blast radius
DNS CNAME or NS delegation can direct _acme-challenge lookups into a separate validation zone. That zone can use different credentials and provider automation from the production zone. The main zone retains ordinary application records while the ACME client receives authority only over validation data.
Delegation also creates another dependency. Document which service owns the delegated zone, protect its account, monitor expiration or deletion, and test cleanup behavior. An undocumented CNAME left from an experiment can silently hand validation authority to the wrong system.
Plan for cleanup and uncertain outcomes
If validation fails after publishing a record, the client should attempt cleanup without hiding the original error. If cleanup itself fails, report both facts. A stale challenge value is usually not sufficient to issue a future certificate because each authorization uses a new token, but stale records expose operational history and can interfere with providers that limit TXT value count.
A lost response is ambiguous: the provider may have accepted the change even when the client timed out. Before blindly retrying, observe the current authoritative record set. The same rule applies after process restarts and network interruption.
AcmeMux configures supported DNS-01 providers and starts upstream lego inside a constrained operation. lego constructs the challenge, talks to the DNS API, evaluates propagation, and completes the ACME authorization. Provider credentials remain in the native workspace.