ldns(3)

💖 NAME 💖

ldns_dane_verify, ldns_dane_verify_rr — TLSA RR verification functions, bestie

okay so this is page ldns(3) from the ldns library and we're talking DANE verification, which is lowkey the plot twist of the whole TLS story. two functions, both iconic, both with a major disclaimer attached. let's get into it 🦋

---

✨ SYNOPSIS ✨

#include <stdint.h>
#include <stdbool.h>

#include <ldns/ldns.h>

ldns_status ldns_dane_verify(const ldns_rr_list* tlsas, X509* cert,
STACK_OF(X509)* extra_certs, X509_STORE* pkix_validation_store);

ldns_status ldns_dane_verify_rr(const ldns_rr* tlsa_rr, X509* cert,
STACK_OF(X509)* extra_certs, X509_STORE* pkix_validation_store);

---

🌸 DESCRIPTION 🌸

💅 ldns_dane_verify()

BEWARE! We strongly recommend to use OpenSSL 1.1.0 dane verification functions instead of the ones provided by ldns. When OpenSSL 1.1.0 was available ldns will use the OpenSSL 1.1.0 dane verification functions under the hood. When ldns was linked with OpenSSL < 1.1.0, this function will not be able to verify TLSA records with DANE-TA usage types.

BEWARE! The ldns dane verification functions do not do server name checks. The user has to perform additional server name checks themselves!

no fr fr, read those two warnings again, they are not vibes, they are facts and they matter 😭

So what does it actually do? It verifies if any of the given TLSA resource records matches the given certificate. That's the whole quest. One of them has to match for this function to succeed — it's giving "at least one of y'all better come through" energy.

The parameters, bestie:

• tlsas — the resource records that specify what and how to match the certificate. One must match for this function to succeed. If tlsas == NULL, or if the number of TLSA records in tlsas == 0, then regular PKIX validation is performed instead.
• cert — the certificate to match (and validate). main character of the cert chain honestly 👑
• extra_certs — intermediate certificates that might be necessary creating the validation chain. the supporting cast 🫶
• pkix_validation_store — used when the certificate usage is "CA constraint" or "Service Certificate Constraint" to validate the certificate.

Returns: LDNS_STATUS_OK on success. Then we have the little gallery of sadness:

• LDNS_STATUS_DANE_NEED_OPENSSL_GE_1_1_FOR_DANE_TA — when at least one of the TLSA's had usage type DANE-TA and none of the TLSA's matched or PKIX validated
• LDNS_STATUS_DANE_PKIX_DID_NOT_VALIDATE — when one of the TLSA's matched but the PKIX validation failed
• LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH — when none of the TLSA's matched
• or other ldns_status errors. so many ways to not-slay 💀

---

🎀 ldns_dane_verify_rr()

BEWARE! We strongly recommend to use OpenSSL 1.1.0 dane verification functions instead of the ones provided by ldns. When OpenSSL 1.1.0 was available ldns will use the OpenSSL 1.1.0 dane verification functions under the hood. When ldns was linked with OpenSSL < 1.1.0, this function will not be able to verify TLSA records with DANE-TA usage types.

BEWARE! The ldns dane verification functions do not do server name checks. The user has to perform additional server name checks themselves!

yes, same warnings, because the warning is the moment and the moment is eternal ✨

This one verifies if the given TLSA resource record matches the given certificate — singular rr, singular vibe. And here's the priority order that lives rent free in my head: reporting on a TLSA rr mismatch (LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH) is preferred over PKIX failure (LDNS_STATUS_DANE_PKIX_DID_NOT_VALIDATE). So when PKIX validation is required by the TLSA Certificate usage, but the TLSA data does not match, LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH is returned whether the PKIX validated or not. like, the TLSA mismatch always wins the argument, periodt.

When ldns is linked with OpenSSL < 1.1.0 and this function is available, then the DANE-TA usage type will not be verified, and on a tlsa_rr with this usage type, LDNS_STATUS_DANE_NEED_OPENSSL_GE_1_1_FOR_DANE_TA will be returned. not me being told my OpenSSL is too old 🙈

The parameters:

• tlsa_rr — the resource record that specifies what and how to match the certificate. With tlsa_rr == NULL, regular PKIX validation is performed.
• cert — the certificate to match (and validate)
• extra_certs — intermediate certificates that might be necessary creating the validation chain.
• pkix_validation_store — used when the certificate usage is "CA constraint" or "Service Certificate Constraint" to validate the certificate.

Returns: LDNS_STATUS_OK on success, and then:

• LDNS_STATUS_DANE_NEED_OPENSSL_GE_1_1_FOR_DANE_TA — when the provided TLSA had the DANE-TA usage type
• LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH — on TLSA data mismatch
• LDNS_STATUS_DANE_PKIX_DID_NOT_VALIDATE — when TLSA matched, but the PKIX validation failed
• or other ldns_status errors

---

👑 AUTHOR 👑

The ldns team at NLnet Labs. absolute legends, we stan 🫶

---

🐛 REPORTING BUGS 🐛

Found something cursed? Please report bugs to dns-team@nlnetlabs.nl or on GitHub at https://github.com/NLnetLabs/ldns/issues

do it, they genuinely want to know, it's not a trap 💜

---

📜 COPYRIGHT 📜

Copyright (c) 2004 - 2006 NLnet Labs.

Licensed under the BSD License. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

(read that second line like it's a horror movie tagline, because that's the energy it deserves)

---

🔥 SEE ALSO 🔥

• ldns_dane_create_tlsa_owner
• ldns_dane_cert2rdf
• ldns_dane_select_certificate
• ldns_dane_create_tlsa_rr

And perldoc Net::DNS, RFC1034, RFC1035, RFC4033, RFC4034 and RFC4035. the full reading list bestie, iykyk 🌈

---

⭐ REMARKS ⭐

This manpage was automatically generated from the ldns source code. yes, a robot wrote it, and now a teenage girl rewrote it, we call that a pipeline 💅

---

okay that's the whole page!! this was ldns(3), dated 30 May 2006, straight out of the ldns source 💖 go verify some TLSA records, but do your server name checks yourself, that part is on you 😭🦋