Last updated: July 27, 2017 | See all Documentation
CAA is a type of DNS record that allows site owners to specify which Certificate Authorities (CAs) are allowed to issue certificates containing their domain names. It was standardized in 2013 by RFC 6844 to allow a CA “reduce the risk of unintended certificate mis-issue.” By default, every public CA is allowed to issue certificates for any domain name in the public DNS, provided they validate control of that domain name. That means that if there’s a bug in any one of the many public CAs’ validation processes, every domain name is potentially affected. CAA provides a way for domain holders to reduce that risk.
Note (September 2017): See this update in our API Announcements area for a recent, temporary change to our CAA processing behavior.
If you don’t care about CAA, you generally don’t have to do anything (but see CAA errors below). If you would like to use CAA to restrict which Certificate Authorities are allowed to issue certificates for your domain, you will need to use a DNS provider that supports setting CAA records. Check SSLMate’s CAA page for a list of such providers. If your provider is listed, you can use SSLMate’s CAA Record Generator to generate a set of CAA records listing the CAs that you would like to allow.
Let’s Encrypt’s identifying domain name for CAA is
letsencrypt.org. This is
officially documented in our Certification Practice Statement
(CPS), section 4.2.1.
Where to put the record
You can set CAA records on your main domain, or at any depth of subdomain.
For instance, if you had
www.community.example.com, you could set CAA records
for the full name, or for
community.example.com, or for
will check each version, from left to right, and stop as soon as they see any
CAA record. So for instance, a CAA record at
community.example.com would take
precedence over one at
example.com. Most people who add CAA records will want
to add them to their registered domain (
example.com) so that they apply to all
subdomains. Also note that CAA records for subdomains take precedence over their
parent domains regardless of whether they are more permissive or more
restrictive. So a subdomain can loosen a restriction put in place by a parent
CAA validation follows CNAMEs, like all other DNS requests. If
www.community.example.com is a CNAME to
web1.example.net, the CA will first
request CAA records for
www.community.example.com, then seeing that there is a
CNAME for that domain name instead of CAA records, will request CAA records for
web1.example.net instead. Note that if a domain name has a CNAME record, it is
not allowed to have any other records according to the DNS standards.
The CAA RFC specifies an additional behavior called “tree-climbing” that requires CAs to also check the parent domains of the result of CNAME resolution. Let’s Encrypt does not implement tree climbing because it makes expressing certain CAA policies impossible. After discussion on the IETF mailing list, we achieved consensus that tree-climbing in CAA is not ideal, and there’s an erratum for the CAA RFC removing it. That erratum still needs to be voted in by the CA/Browser Forum by September 8 for it to to take effect for publicly trusted CAs.
Since Let’s Encrypt checks CAA records before every certificate we issue, sometimes we get errors even for domains that haven’t set any CAA records. When we get an error, there’s no way to tell whether we are allowed to issue for the affected domain, since there could be CAA records present that forbid issuance, but are not visible because of the error.
If you receive CAA-related errors, try a few more times against our staging environment to see if they are temporary or permanent. If they are permanent, you will need to file a support issue with your DNS provider, or switch providers. If you’re not sure who your DNS provider is, ask your hosting provider.
Some DNS providers that are unfamiliar with CAA initially reply to problem reports with “We do not support CAA records.” Your DNS provider does not need to specifically support CAA records; it only needs to reply with a NOERROR response for unknown query types (including CAA). Returning other opcodes, including NOTIMP, for unrecognized qtypes is a violation of RFC 1035, and needs to be fixed.
One of the most common errors that people encounter is SERVFAIL. Most often this indicates a failure of DNSSEC validation. If you get a SERVFAIL error, your first step should be to use a DNSSEC debugger like dnsviz.net. If that doesn’t work, it’s possible that your nameservers generate incorrect signatures only when the response is empty. And CAA responses are most commonly empty. For instance, PowerDNS had this bug in version 4.0.3 and below.
If you don’t have DNSSEC enabled and get a SERVFAIL, the second most likely reason is that your authoritative nameserver returned NOTIMP, which as described above is an RFC 1035 violation; it should instead return NOERROR with an empty response. If this is the case, file a bug or a support ticket with your DNS provider.
Lastly, SERVFAILs may be caused by outages at your authoritative nameservers. Check the NS records for your nameservers and ensure that each server is available.
Sometimes CAA queries time out. That is, the authoritative name server never replies with an answer at all, even after multiple retries. Most commonly this happens when your nameserver has a misconfigured firewall in front of it that drops DNS queries with unknown qtypes. File a support ticket with your DNS provider and ask them if they have such a firewall configured.