A CAA RR contains a single Property consisting of a tag-value pair. An FQDN
MAY have multiple CAA RRs associated with it, and a given Property Tag
MAY be specified more than once across those RRs.
The RDATA section for a CAA RR contains one Property. A Property consists of the following:
+0-1-2-3-4-5-6-7-|0-1-2-3-4-5-6-7-|
| Flags | Tag Length = n |
+----------------|----------------+...+---------------+
| Tag char 0 | Tag char 1 |...| Tag char n-1 |
+----------------|----------------+...+---------------+
+----------------|----------------+.....+----------------+
| Value byte 0 | Value byte 1 |.....| Value byte m-1 |
+----------------|----------------+.....+----------------+
Where n is the length specified in the Tag Length field and m is the number of remaining octets in the Value field. They are related by (m = d - n - 2) where d is the length of the RDATA section.
The fields are defined as follows:
-
Flags:
-
One octet containing the following field:
-
Bit 0, Issuer Critical Flag:
-
If the value is set to "1", the Property is critical. A CA MUST NOT issue certificates for any FQDN if the Relevant RRset for that FQDN contains a CAA critical Property for an unknown or unsupported Property Tag.
Note that according to the conventions set out in [
RFC 1035], bit 0 is the Most Significant Bit and bit 7 is the Least Significant Bit. Thus, according to those conventions, the Flags value 1 means that bit 7 is set, while a value of 128 means that bit 0 is set.
All other bit positions are reserved for future use.
To ensure compatibility with future extensions to CAA, DNS records compliant with this version of the CAA specification
MUST clear (set to "0") all reserved flag bits. Applications that interpret CAA records
MUST ignore the value of all reserved flag bits.
-
Tag Length:
-
A single octet containing an unsigned integer specifyingthe tag length in octets. The tag length MUST be at least 1.
-
Tag:
-
The Property identifier -- a sequence of ASCII characters.
Tags
MAY contain ASCII characters "a" through "z", "A" through "Z", and the numbers 0 through 9. Tags
MUST NOT contain any other characters. Matching of tags is case insensitive.
Tags submitted for registration by IANA
MUST NOT contain any characters other than the (lowercase) ASCII characters "a" through "z" and the numbers 0 through 9.
-
Value:
-
A sequence of octets representing the Property Value.Property Values are encoded as binary values and MAY employsub-formats.
The length of the Value field is specified implicitly as the remaining length of the enclosing RDATA section.
The canonical presentation format of the CAA record is:
CAA <flags> <tag> <value>
Where:
-
Flags:
-
An unsigned integer between 0 and 255.
-
Tag:
-
A non-zero-length sequence of ASCII letters and numbers in lowercase.
-
Value:
-
The Value field, expressed as either (1) a contiguous set of characters without interior spaces or (2) a quoted string. See the <character-string> format specified in RFC 1035, Section 5.1, but note that the Value field contains no length byte and is not limited to 255 characters.
If the issue Property Tag is present in the Relevant RRset for an FQDN, it is a request that Issuers:
-
Perform CAA issue restriction processing for the FQDN, and
-
Grant authorization to issue certificates containing that FQDN to the holder of the issuer-domain-name or a party acting under the explicit authority of the holder of the issuer-domain-name.
The CAA issue Property Value has the following sub-syntax (specified in ABNF as per [
RFC 5234]).
issue-value = *WSP [issuer-domain-name *WSP]
[";" *WSP [parameters *WSP]]
issuer-domain-name = label *("." label)
label = (ALPHA / DIGIT) *( *("-") (ALPHA / DIGIT))
parameters = (parameter *WSP ";" *WSP parameters) / parameter
parameter = tag *WSP "=" *WSP value
tag = (ALPHA / DIGIT) *( *("-") (ALPHA / DIGIT))
value = *(%x21-3A / %x3C-7E)
For consistency with other aspects of DNS administration, FQDN values are specified in letter-digit-hyphen Label (LDH-Label) form.
The following CAA RRset requests that no certificates be issued for the FQDN "certs.example.com" by any Issuer other than ca1.example.net or ca2.example.org.
certs.example.com CAA 0 issue "ca1.example.net"
certs.example.com CAA 0 issue "ca2.example.org"
Because the presence of an issue Property Tag in the Relevant RRset for an FQDN restricts issuance, FQDN owners can use an issue Property Tag with no issuer-domain-name to request no issuance.
For example, the following RRset requests that no certificates be issued for the FQDN "nocerts.example.com" by any Issuer.
nocerts.example.com CAA 0 issue ";"
An issue Property Tag where the issue-value does not match the ABNF grammar
MUST be treated the same as one specifying an empty issuer-domain-name. For example, the following malformed CAA RRset forbids issuance:
malformed.example.com CAA 0 issue "%%%%%"
CAA authorizations are additive; thus, the result of specifying both an empty issuer-domain-name and a non-empty issuer-domain-name is the same as specifying just the non-empty issuer-domain-name.
An Issuer
MAY choose to specify parameters that further constrain the issue of certificates by that Issuer -- for example, specifying that certificates are to be subject to specific validation policies, billed to certain accounts, or issued under specific trust anchors.
For example, if ca1.example.net has requested that its customer account.example.com specify their account number "230123" in each of the customer's CAA records using the (CA-defined) "account" parameter, it would look like this:
account.example.com CAA 0 issue "ca1.example.net; account=230123"
The semantics of parameters to the issue Property Tag are determined by the Issuer alone.
The issuewild Property Tag has the same syntax and semantics as the issue Property Tag except that it only grants authorization to issue certificates that specify a Wildcard Domain Name and each issuewild Property takes precedence over each issue Property when specified. Specifically:
Each issuewild Property
MUST be ignored when processing a request for an FQDN that is not a Wildcard Domain Name.
If at least one issuewild Property is specified in the Relevant RRset for a Wildcard Domain Name, each issue Property
MUST be ignored when processing a request for that Wildcard Domain Name.
For example, the following RRset requests that
only ca1.example.net issue certificates for "wild.example.com" or "sub.wild.example.com", and that
only ca2.example.org issue certificates for "*.wild.example.com" or "*.sub.wild.example.com". Note that this presumes that there are no CAA RRs for sub.wild.example.com.
wild.example.com CAA 0 issue "ca1.example.net"
wild.example.com CAA 0 issuewild "ca2.example.org"
The following RRset requests that
only ca1.example.net issue certificates for "wild2.example.com", "*.wild2.example.com", or "*.sub.wild2.example.com".
wild2.example.com CAA 0 issue "ca1.example.net"
The following RRset requests that
only ca2.example.org issue certificates for "*.wild3.example.com" or "*.sub.wild3.example.com". It does not permit any Issuer to issue for "wild3.example.com" or "sub.wild3.example.com".
wild3.example.com CAA 0 issuewild "ca2.example.org"
wild3.example.com CAA 0 issue ";"
The following RRset requests that
only ca2.example.org issue certificates for "*.wild3.example.com" or "*.sub.wild3.example.com". It permits any Issuer to issue for "wild3.example.com" or "sub.wild3.example.com".
wild3.example.com CAA 0 issuewild "ca2.example.org"
The iodef Property specifies a means of reporting certificate issue requests or cases of certificate issue for domains for which the Property appears in the Relevant RRset, when those requests or issuances violate the security policy of the Issuer or the FQDN holder.
The Incident Object Description Exchange Format (IODEF) [
RFC 7970] is used to present the incident report in machine-readable form.
The iodef Property Tag takes a URL as its Property Value. The URL scheme type determines the method used for reporting:
-
mailto:
-
The IODEF report is reported as a MIME email attachment to an SMTP email that is submitted to the mail address specified. The mail message sent SHOULD contain a brief text message to alert the recipient to the nature of the attachment.
-
http or https:
-
The IODEF report is submitted as a web service request to the HTTP address specified using the protocol specified in [RFC 6546].
These are the only supported URL schemes.
The following RRset specifies that reports may be made by means of email with the IODEF data as an attachment, a web service [
RFC 6546], or both:
report.example.com CAA 0 issue "ca1.example.net"
report.example.com CAA 0 iodef "mailto:security@example.com"
report.example.com CAA 0 iodef "https://iodef.example.com/"
The critical flag is intended to permit future versions of CAA to introduce new semantics that
MUST be understood for correct processing of the record, preventing conforming CAs that do not recognize the new semantics from issuing certificates for the indicated FQDNs.
In the following example, the Property with a Property Tag of "tbs" is flagged as critical. Neither the ca1.example.net CA nor any other Issuer is authorized to issue for "new.example.com" (or any other domains for which this is the Relevant RRset) unless the Issuer has implemented the processing rules for the "tbs" Property Tag.
new.example.com CAA 0 issue "ca1.example.net"
new.example.com CAA 128 tbs "Unknown"