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 RSA key (private or public).
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.
Unlike for example DKIM, which uses
TXT type DNS records, a TLSA DNS record has its own DNS record type
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]
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
When using DANE, a TLSA record must be placed at the following location:
The examples show the use of DANE augmentation of an SMTP (port 25/tcp) service at
mx.mailhardener.com, and a HTTPS (port 443/tcp) service at
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.
The first value in the TLSA record is the 'usage' field. It describes the kind of certificate the TLSA record should match with.
||PKI trust anchor certificate (the PKI CA certificate in the chain). Do not use with SMTP.|
||PKI 'end-entity' certificate (the PKI certificate for the domain). Do not use with SMTP.|
||trust anchor certificate (the CA certificate in the chain)|
||'end-entity' certificate (the certificate for the domain)|
For e-mail (SMTP) applications, this must be either 2 (
DANE-TA) or 3 (
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.
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.
|0 (full certificate)||Allows for effective revocation of a certificate||TLSA must be renewed with each certificate renewal|
|1 (subject public key)||TLSA record requires no renewal on certificate renewal (unless key is changed)||TLSA record renewal may be forgotten on eventual key rotation|
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.
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.
|1||SHA2-256 hash digest|
|2||SHA2-512 hash digest|
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.
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.
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.
openssl x509 -in certificate.pem -outform DER | sha256sum
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 rsa -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 rsa -pubin public.pem -outform DER | sha256sum # When using private key as input: openssl rsa -in private.pem -pubout -outform DER | sha256sum
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
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).
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
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.
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.
If a certificate is replaced, it may be required to create new TLSA records.
|0 or 2 (trust anchor)||0 (full certificate)||CA replaces root certificate|
|0 or 2 (trust anchor)||1 (public key)||CA rotates private key|
|1 or 3 (end entity)||0 (full certificate)||Certificate is renewed|
|1 or 3 (end entity)||1 (public key)||Only if private key is rotated|
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.
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.
OpenSSL is a useful tool for creating TLSA records for certificates and keys.
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.
On last thing: If you have questions, comments or thoughts on this article, don't hesitate to shoot us an email.
You can also follow and reach us on Twitter @Mailhardener.