ACME in depth · 18.4

CAA records

This section is DNS background. TLSPilot does not create or check CAA records, but a CAA record that does not fit makes the CA refuse the certificate, and TLSPilot then shows the error of the CA. With CAA (Certification Authority Authorization, RFC 8659), the owner of a domain defines in DNS which CAs may issue certificates for it. Every public CA checks CAA before it issues. If no CAA record exists, any CA may issue.

A CAA record has the form CAA <flags> <tag> <value>. The flags are usually 0. The value 128 marks the record as critical: a CA that does not understand the tag must not issue. The CA looks for CAA records at the name in the certificate first, then at each parent domain, and uses the first records it finds. A record on example.com therefore also applies to www.example.com, unless the subdomain has CAA records of its own. The CA checks every name in the certificate, so a single restricted name blocks the whole certificate.

CAA tags and ACME parameters
Tag or parameter	Meaning
Tags (RFC 8659)
`issue`	Allows the named CA to issue certificates for the domain and its subdomains. It also applies to wildcard certificates as long as there is no `issuewild` record. `issue ";"` allows no CA.
`issuewild`	Only for wildcard certificates (`*.example.com`). If present, it replaces `issue` for wildcards.
`iodef`	Address for reports about requests that violate the CAA records, as `mailto:` or `https:` URL. Not every CA sends such reports; Google Trust Services, for example, does not act on `iodef`.
ACME parameters (RFC 8657), appended to the CA name with `;`
`accounturi`	Only this ACME account may order certificates. At Let’s Encrypt, the account URL looks like `https://acme-v02.api.letsencrypt.org/acme/acct/1234567890`.
`validationmethods`	Only these challenge types may be used, for example `dns-01`, `http-01` or `tls-alpn-01`.

Example records

In this example, Let’s Encrypt (letsencrypt.org) and Google Trust Services (pki.goog) may issue for example.com and its subdomains. Wildcard certificates may only come from Let’s Encrypt with DNS-01, and reports go to the security team:

example.com.  CAA 0 issue     "letsencrypt.org"
example.com.  CAA 0 issue     "pki.goog"
example.com.  CAA 0 issuewild "letsencrypt.org;validationmethods=dns-01"
example.com.  CAA 0 iodef     "mailto:security@example.com"

To bind Let’s Encrypt to the ACME account of TLSPilot, add the account URL: example.com. CAA 0 issue "letsencrypt.org;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/1234567890".

Note

Several CAs on one name: RFC 8659 has no combined record that lists several CAs. Every CA you use needs its own issue record on the same name, and each record names exactly one CA. The CA always evaluates the whole set of CAA records at that name. As soon as this set contains an issue record, every CA that is not listed must refuse to issue. Records with only iodef do not restrict issuance. Example for Let’s Encrypt and ZeroSSL, which issues with the CAA value of Sectigo:

example.com.  3600  IN  CAA  0 issue "letsencrypt.org"
example.com.  3600  IN  CAA  0 issue "sectigo.com"

Pitfall issuewild: If the set contains an issuewild record, it applies to wildcard names such as *.example.com instead of issue. A CA that is only listed in issue may then not issue wildcard certificates. List every CA that issues wildcards in its own issuewild record as well.
Pitfall subdomains: The CA only climbs the tree as long as it finds no CAA records. If a subdomain such as shop.example.com has CAA records of its own, only these apply, and the records of example.com are not considered. Repeat on the subdomain every CA that may issue for it.

Typical errors

CNAME chain: CAA lookups follow CNAME records like any DNS query. If www.example.com is a CNAME to a name of a CDN or hosting provider, the CAA records at that target apply. If the target has none, the CA continues with the parent domains of your own name, for example example.com.
Wildcard: A certificate for *.example.com fails although issue allows the CA, because an issuewild record does not name it, for example issuewild ";".
ACME parameters: With accounturi, the record must name the current ACME account; after Reset Account, TLSPilot registers a new account. With validationmethods, the challenge type of the certificate must be listed.
DNS errors: If the CAA lookup fails, for example with SERVFAIL or a timeout, the CA cannot tell whether it may issue and usually refuses. Common causes are a broken DNSSEC signature or nameservers that do not answer queries for unknown record types correctly.

Check the records

dig +short CAA example.com
dig @8.8.8.8 CAA www.example.com

An empty answer means that there is no CAA record at exactly this name. Then check the parent domains as well.