Skip to main content

2. The TLSA Resource Record

The TLSA DNS resource record (RR) is used to associate a TLS server certificate or public key with the domain name where the record is found, thus forming a "TLSA certificate association". The semantics of how the TLSA RR is interpreted are given later in this document.

The type value for the TLSA RR type is defined in Section 7.1.

The TLSA RR is class independent.

The TLSA RR has no special Time to Live (TTL) requirements.

2.1. TLSA RDATA Wire Format​

The RDATA for a TLSA RR consists of a one-octet certificate usage field, a one-octet selector field, a one-octet matching type field, and the certificate association data field.

                     1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  Cert. Usage  |   Selector    | Matching Type |               /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+               /
/                                                               /
/                 Certificate Association Data                  /
/                                                               /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

2.1.1. The Certificate Usage Field​

A one-octet value, called "certificate usage", specifies the provided association that will be used to match the certificate presented in the TLS handshake. This value is defined in a new IANA registry (see Section 7.2) in order to make it easier to add additional certificate usages in the future. The certificate usages defined in this document are:

0 -- CA constraint: Certificate usage 0 is used to specify a CA certificate, or the public key of such a certificate, that MUST be found in any of the PKIX certification paths for the end entity certificate given by the server in TLS. This certificate usage is sometimes referred to as "CA constraint" because it limits which CA can be used to issue certificates for a given service on a host. The presented certificate MUST pass PKIX certification path validation, and a CA certificate that matches the TLSA record MUST be included as part of a valid certification path. Because this certificate usage allows both trust anchors and CA certificates, the certificate might or might not have the basicConstraints extension present.

1 -- Service certificate constraint: Certificate usage 1 is used to specify an end entity certificate, or the public key of such a certificate, that MUST be matched with the end entity certificate given by the server in TLS. This certificate usage is sometimes referred to as "service certificate constraint" because it limits which end entity certificate can be used by a given service on a host. The target certificate MUST pass PKIX certification path validation and MUST match the TLSA record.

2 -- Trust anchor assertion: Certificate usage 2 is used to specify a certificate, or the public key of such a certificate, that MUST be used as the trust anchor when validating the end entity certificate given by the server in TLS. This certificate usage is sometimes referred to as "trust anchor assertion" and allows a domain name administrator to specify a new trust anchor -- for example, if the domain issues its own certificates under its own CA that is not expected to be in the end users' collection of trust anchors. The target certificate MUST pass PKIX certification path validation, with any certificate matching the TLSA record considered to be a trust anchor for this certification path validation.

3 -- Domain-issued certificate: Certificate usage 3 is used to specify a certificate, or the public key of such a certificate, that MUST match the end entity certificate given by the server in TLS. This certificate usage is sometimes referred to as "domain-issued certificate" because it allows for a domain name administrator to issue certificates for a domain without involving a third-party CA. The target certificate MUST match the TLSA record. The difference between certificate usage 1 and certificate usage 3 is that certificate usage 1 requires that the certificate pass PKIX validation, but PKIX validation is not tested for certificate usage 3.

The certificate usages defined in this document explicitly only apply to PKIX-formatted certificates in DER encoding [X.690]. If TLS allows other formats later, or if extensions to this RRtype are made that accept other formats for certificates, those certificates will need their own certificate usage values.

2.1.2. The Selector Field​

A one-octet value, called "selector", specifies which part of the TLS certificate presented by the server will be matched against the association data. This value is defined in a new IANA registry (see Section 7.3). The selectors defined in this document are:

0 -- Full certificate: the Certificate binary structure as defined in [RFC5280]

1 -- SubjectPublicKeyInfo: DER-encoded binary structure as defined in [RFC5280]

(Note that the use of "selector" in this document is completely unrelated to the use of "selector" in DomainKeys Identified Mail (DKIM) [RFC6376].)

2.1.3. The Matching Type Field​

A one-octet value, called "matching type", specifies how the certificate association is presented. This value is defined in a new IANA registry (see Section 7.4). The types defined in this document are:

0 -- Exact match on selected content

1 -- SHA-256 hash of selected content [RFC6234]

2 -- SHA-512 hash of selected content [RFC6234]

If the TLSA record's matching type is a hash, having the record use the same hash algorithm that was used in the signature in the certificate (if possible) will assist clients that support a small number of hash algorithms.

2.1.4. The Certificate Association Data Field​

This field specifies the "certificate association data" to be matched. These bytes are either raw data (that is, the full certificate or its SubjectPublicKeyInfo, depending on the selector) for matching type 0, or the hash of the raw data for matching types 1 and 2. The data refers to the certificate in the association, not to the TLS ASN.1 Certificate object.

2.2. TLSA RR Presentation Format​

The presentation format of the RDATA portion (as defined in [RFC1035]) is as follows:

  • The certificate usage field MUST be represented as an 8-bit unsigned integer.
  • The selector field MUST be represented as an 8-bit unsigned integer.
  • The matching type field MUST be represented as an 8-bit unsigned integer.
  • The certificate association data field MUST be represented as a string of hexadecimal characters. Whitespace is allowed within the string of hexadecimal characters, as described in [RFC1035].

2.3. TLSA RR Examples​

In the following examples, the domain name is formed using the rules in Section 3.

An example of a hashed (SHA-256) association of a PKIX CA certificate:

_443._tcp.www.example.com. IN TLSA (
   0 0 1 d2abde240d7cd3ee6b4b28c54df034b9
         7983a1d16e8a410e4561cb106618e971 )

An example of a hashed (SHA-512) subject public key association of a PKIX end entity certificate:

_443._tcp.www.example.com. IN TLSA (
   1 1 2 92003ba34942dc74152e2f2c408d29ec
         a5a520e7f2e06bb944f4dca346baf63c
         1b177615d466f6c4b71c216a50292bd5
         8c9ebdd2f74e38fe51ffd48c43326cbc )

An example of a full certificate association of a PKIX end entity certificate:

_443._tcp.www.example.com. IN TLSA (
   3 0 0 30820307308201efa003020102020... )
Last updated on