CAA records explained: which CAs may issue

Any of the publicly trusted certificate authorities (CAs) can issue a certificate for any domain, as long as the requester passes domain validation. A Certification Authority Authorization (CAA) record lets the domain owner name the CAs that are allowed to do so. CAs are required to check CAA before issuing. The record is defined in RFC 8659, which replaced RFC 6844.

The record

A CAA record has three fields: a flags byte, a property tag and a value.

example.com.  CAA  0 issue "letsencrypt.org"
example.com.  CAA  0 issuewild ";"
example.com.  CAA  0 iodef "mailto:[email protected]"

RFC 8659 defines three tags:

• issue names a CA that may issue certificates for the name. Several issue records allow several CAs.
• issuewild does the same for wildcard certificates such as *.example.com.
• iodef gives a URL where a CA can report a request that violates the policy.

The value of issue and issuewild is the CA's domain name, optionally followed by parameters after a semicolon. RFC 8657 defines two such parameters: accounturi limits issuance to one account at the CA, and validationmethods limits the methods the CA may use to validate the domain. The CA decides which domain name identifies it; it is listed in its documentation.

A value that cannot be parsed is reported as CAA_INVALID_VALUE. CAs treat a broken record carefully, and some refuse to issue.

Forbidding issuance

An issue record with an empty issuer, written 0 issue ";", means that no CA may issue certificates for the name. It is useful for domains that never need a certificate, or as issuewild ";" to forbid wildcard certificates while normal ones are still allowed through issue. The check reports it as CAA_NO_ISSUANCE so you can confirm it is intended.

Wildcards

For a wildcard name, the CA looks at issuewild first. If the set contains any issuewild records, only those count for the wildcard certificate and the issue records are ignored for it. If there are none, the issue records apply to wildcards too. The check lists the allowed issuers for normal and for wildcard certificates separately in its result.

Where the CA looks: climbing the tree

RFC 8659 section 3 describes how a CA finds the relevant set of records. It queries CAA for the exact name in the certificate. If that gives no records, it queries the parent name, and so on towards the root. The first non-empty set it finds is the one that applies. Records at a subdomain therefore replace those of the parent completely; they are not merged.

For example, for shop.eu.example.com the CA tries shop.eu.example.com, then eu.example.com, then example.com. If only example.com has CAA records, they apply.

The ProbeKit check follows the same steps, from the name you give up to the registrable domain just below the public suffix (such as example.com or example.co.uk), and shows which name the records were found at. Records published on the public suffix itself are not considered, and the check stops after ten names.

The critical flag

The flags byte has one defined bit: the issuer critical flag, the value 128. A record with the flag set and a tag the CA does not understand means the CA must not issue at all. This lets a domain add new kinds of restrictions that older CAs cannot ignore by mistake. It also means that a typo in a tag combined with flag 128 blocks all issuance. The check reports a critical record with a tag it does not know as CAA_UNKNOWN_CRITICAL_TAG. Tags without the flag that the CA does not know are ignored.

iodef

The iodef value is a URL. RFC 8659 mentions mailto:, http: and https: URLs. The check accepts mailto: and https: and warns about anything else, including plain http:, as CAA_INVALID_IODEF. Few CAs send such reports, so iodef is useful but should not be your only way to notice unexpected certificates. Certificate Transparency logs are a more reliable source.

No CAA records

If the name and all its parents up to the registrable domain have no CAA records, any CA may issue. The check reports this as CAA_NOT_FOUND for information. Adding CAA does not change anything for a CA you already use, as long as you list it. It does stop an attacker who can pass domain validation, for example through a hijacked web server, from getting a certificate from a CA you never use.

A typical policy

A domain that gets its certificates from one CA, wants reports, and never uses wildcards could publish:

example.com.  CAA  0 issue "letsencrypt.org"
example.com.  CAA  0 issuewild ";"
example.com.  CAA  0 iodef "mailto:[email protected]"

Before you publish, list every place that requests certificates for the domain and its subdomains: your own servers, load balancers, CDNs, mail and hosting services. Each of their CAs needs an issue record, or the next renewal fails.

Common mistakes

• Listing a CA under the wrong domain name, so it refuses to renew your certificates.
• Forgetting the CA of a service that issues certificates on your behalf, such as a CDN or hosting platform.
• A subdomain with its own CAA records that do not include the CA used for that subdomain.
• Setting flag 128 on a record by accident.
• Forgetting that a mark certificate for BIMI is also issued by a CA, and that the issuevmc property, not issue, governs it.

Use the CAA record check to see the records that apply to a name and where they come from, or the domain health check for CAA together with DNSSEC and the mail checks. The raw records are also available through the DNS lookup.