How to create a DANE TLSA record with OpenSSL

DANE allows for augmentation of TLS certificates by using TLSA DNS records. With DANE, the chain of trust in a traditional PKI is shifted away from the CA, giving more control to the domain administrator.

In this guide we will explain how to use OpenSSL to create a DANE TLSA record from a certificate or key (private or public, RSA or ECC).

If you are new to DANE, we recommend reading our main article about DANE first.

In this article we'll focus on using DANE as an augmentation of the existing PKI for SMTP services. However, the techniques described in this article also apply to other TLS enabled services, such as HTTPS.

TLSA record format

Unlike for example DKIM, which uses TXT type DNS records, a TLSA DNS record has its own DNS record type TLSA. The TLSA record type is defined in rfc6698.

The TLSA record type is a binary record format, it is often displayed in the following format:

(int)[usage] (int)[selector] (int)[matching type] (hex)[certificate association data]

For example:

3 0 1 370c66fd4a0673ce1b62e76b819835dabb20702e4497cb10affe46e8135381e7

Most DNS service providers will offer some input form to create a TLSA record. If the DNS service provider allows text input for a TLSA record, it is most likely expected in the format above

DANE TLSA record location

When using DANE, a TLSA record must be placed at the following location:

_[port]._[protocol].[domain]

For example:

_25._tcp.mx.mailhardener.com
_443._tcp.mailhardener.com

The examples show the use of DANE augmentation of an SMTP (port 25/tcp) service at mx.mailhardener.com, and an HTTPS (port 443/tcp) service at mailhardener.com respectively.

Multiple TLSA records may exist at the same location. At least of the TLSA records has to match a certificate, the rest will be ignored.

Step 1: Choose a 'usage' value

The first value in the TLSA record is the 'usage' field. It describes the kind of certificate the TLSA record should match with.

For e-mail (SMTP) applications, this must be either 2 (DANE-TA) or 3 (DANE-EE). Values usage=0 and usage=1 should not be used for SMTP (see rfc7672 section 3.1.3).

Because Certificate Authorities may use multiple trust anchors, or may rotate their keys, it is most common to use usage=3 (DANE-EE) for DANE with SMTP.

Step 2: Choose a 'selector' value

The second value in the TLSA record is the 'selector' field, it determines if the data contained in the TLSA record is based on the certificate public key, or the entire certificate.

When using option 0, the TLSA record must be replaced every time the certificate is renewed or replaced.

When using option 1, the TLSA record only has to be replaced when the key is rotated. If the certificate is renewed without key rotation, the TLSA record does not need to be replaced.

Step 3: Choose a 'matching' value

The third value in the TLSA record is the 'matching' field, it determines how the value in 'certificate association data' should be matched to the 'selector'.

The matching field specifies how the certificate should be matched to the Certificate Association Data field. This applies to the content specified in the Selector field.

Option 0 (exact match) is impractical with common x.509 certificates, as they are often larger than a DNS record practically allows for. Option 2 (SHA2-512) is not recommended, as it may not be supported by the validator, and also results in much larger TLSA records.

Option 1 (SHA2-256) is the most common, and therefore recommended value to use for the 'matching' field.

Step 4: Creating the 'certificate association data' field

Now it is time to create the 'certificate association data' field using OpenSSL.

Note that all examples here use matching=1 (SHA2-256). All examples below will output the value in hexadecimal form.

How the value is created depends on the choice of the 'selector' value.

Selector=0 (full certificate)

When selector=0, then the 'certificate association data' field will be the hash digest of the entire certificate.

We'll use OpenSSL to convert the entire certificate to DER format, and create a SHA2-256 hash digest from that value. The input certificate.pem depends on the 'usage' value.

• When usage=2, the input certificate should be the CA root certificate.
• when usage=3, the input certificate should be the domain certificate.

openssl x509 -in certificate.pem -outform DER | sha256sum

Selector=1 (subject public key)

When using selector=1, the public key of the certificate is hashed.

OpenSSL can automatically extract the public key from a certificate. Be sure to use the correct certificate (CA root certificate when usage=2, or domain certificate when usage=3). Be aware that if the input is a certificate chain, then OpenSSL will use the first certificate in the file.

openssl x509 -in certificate.pem -pubkey -noout | openssl ec -pubin -outform der | sha256sum 

Alternatively, the public or the private key (used to create the CSR) can also be used as input.

# When using public key as input:
openssl ec -pubin public.pem -outform DER | sha256sum

# When using private key as input:
openssl ec -in private.pem -pubout -outform DER | sha256sum

Note that we use openssl ec here, and not openssl rsa. The ec command should accept both ECC and RSA keys, whereas the rsa command doesn't. If your OpenSSL client does not support elliptic curve cryptography, then replace ec with rsa. Many thanks to Wolfgang Kraft for this tip!

Step 5: Test the record before placing

We can use the OpenSSL s_client to verify the correctness of a DANE TLSA record, before it is deployed.

openssl s_client -brief -dane_tlsa_domain [host_name] -dane_tlsa_rrdata "[tlsa_record]" -connect [host_name]:[port] <<< "Q"

For example, when testing a TLSA record for SMTP service at mx3.mailhardener.com:

openssl s_client -brief -starttls smtp -dane_tlsa_domain mx3.mailhardener.com -dane_tlsa_rrdata "3 1 1 666792F7857D333D59655A19CA59CD88B7C535CD699DCEAA290B943DEB8E23FD" -connect mx3.mailhardener.com:25 <<< "Q"

The expected output should contain the following line:

DANE TLSA 3 1 1 ...699dceaa290b943deb8e23fd matched EE certificate at depth 0

Here we can see that the TLSA record that was passed in the command line matches the certificate which is served by the SMTP service.

If you made a mistake and the new TLSA record does not match the certificate, the following error is expected in the output:

Verification error: no matching DANE TLSA records

Unfortunately, at the time of writing this article, it does not appear that OpenSSL has support to fetch the TLSA record directly from the DNS (tested with OpenSSL 3.0.2).

Step 6: Placing the record in your DNS zone

Now that you have generated the digest, and verified that it matches the certificate of the service you are deploying DANE for, it is time to publish the TLSA record in your DNS zone.

The TLSA record must be placed at _[port]._[protocol].[domain].

Because the TLSA type record is a binary format record, most DNS service providers offer a form to set the 'usage', 'selector', 'matching' and 'certificate association data' fields separately. Most DNS service providers will expect the data to be in hexadecimal format, as outputted by the command line example above.

It may also be possible that your DNS service provider, or DNS server software, accepts the TLSA record via text input, in that case it is usually expected to be in the format as described in the section above.

TLSA records are not meant to ever change (only added or revoked), so you can use a long time-to-live (TTL) value for the record. A TTL of 1 day (86400 seconds) or more is not uncommon for TLSA DNS records.

Step 7: Use SMTP TLS reporting for continuous monitoring

SMTP TLS reporting (RFC8460) a.k.a. 'TLSRPT' is a reporting standard for SMTP TLS related information. TLSRPT capable senders will periodically send aggregate reports containing information on the number of successful and unsuccessful TLS sessions, and details on the TLS failures if they occurred.

TLSRPT also reports details on DANE failures, so it is recommended to adopt SMTP TLS reporting for each domain where DANE is deployed for SMTP use.

Mailhardener has full support for SMTP TLS report aggregation:

Read more about SMTP TLS reporting.

When replacing a certificate

If a certificate is replaced, it may be required to create new TLSA records.

This table immediately highlights the benefit of usage=3 and selector=1, if a certificate is renewed (private key is unchanged), then no changes to TLSA records are required.

If you are updating TLSA records, it is considered good practice to add (rather than replace) a new TLSA record, and remove the old TLSA record some time later (for example: 24 hours). This allows cached properties (DNS records, but also certificates) to expire gracefully. Note that a DNS query on _[port]._[proto].[domain] may return multiple TLSA records.

If you are planning on rotating a key (used for the CSR), then it is recommended to generate the key in advance of replacing the certificate. First publish a TLSA record corresponding to the new key (using selector=1), and deploy the new certificate some time after that. Optionally, once the certificate is received from the CA, a TLSA record corresponding to the certificate (with selector=0) may be deployed.

Revoking a TLSA record

If a certificate or key is no longer in use, it is recommended to remove the corresponding TLSA record from the DNS zone.

Revoking a TLSA record is done by removing the TLSA DNS record. Unlike for example with DKIM, DANE/TLSA does not specify a 'positive denial' record format.

Conclusion

OpenSSL is a useful tool for creating TLSA records for certificates and keys. Using the s_client feature in OpenSSL we can also verify a TLSA record before it is deployed.

When adopting DANE with SMTP, it is recommended to use SMTP TLS reporting to monitor for any TLS/DANE related problems with your SMTP service.

Mailhardener fully supports DANE, TLSA and SMTP TLS reporting. Try Mailhardener now for free.

Further reading

• DANE/TLSA knowledge base
• SMTP TLS reporting knowledge base
• Microsoft releases DANE support

See also

• TLSA record validator