val_getdaneinfo(3)

📦 version 2.2.3, in arch rolling, fedora 43, fedora 44

💖 NAME 💖

Okay bestie, gather round, because this whole page is about DANE validation — specifically TLSA records, and the little squad of functions that go get them and check them. Here's the lineup, no cap:

  • val_getdaneinfo() — does a synchronous validation of TLSA records
  • val_dane_submit() — does an asynchronous validation of TLSA records
  • val_dane_match() — validates TLSA info against data you hand it
  • val_dane_check() — validates TLSA info for an SSL connection (OpenSSL only, iykyk)
  • val_free_dane() — releases the memory associated with a DANE result structure
  • p_dane_error() — returns the error string for a given DANE error code

✨ SYNOPSIS ✨

#include <validator/validator.h>
#include <validator/val_dane.h>

int val_getdaneinfo(val_context_t *ctx,
                  const char *name,
                  struct val_daneparams *params,
                  struct val_danestatus **dres);

int val_dane_submit(val_context_t *ctx,
                  const char *name,
                  struct val_daneparams *params,
                  val_dane_callback callback,
                  void *callback_data,
                  val_async_status **status);

int val_dane_match(val_context_t *ctx,
                 struct val_danestatus *dane_cur,
                 const unsigned char *databytes,
                 int databyteslen);

#include <openssl/ssl.h>
int val_dane_check(val_context_t *ctx,
                 SSL *con,
                 struct val_danestatus *danestatus,
                 int *do_pathval);

void val_free_dane(struct val_danestatus *dres);

const char *p_dane_error(int rc);

🌸 DESCRIPTION 🌸

So val_getdaneinfo() does a synchronous lookup of the TLSA record associated with a given name, and hands you back a linked list of all such validated records. Slay.

val_dane_submit() does the exact same lookup but asynchronously, and it invokes the callback function with the callback_data arguments once the lookup is done. That callback function has this type definition, literally:

typedef int (*val_dane_callback)(void *callback_data,
                               int retval,
                               struct val_danestatus **dres);

The status argument gives you a handle to the asynchronous request so you can do future operators on it (like canceling the request, oop). For more info on the val_async_status object, go read draft-hayatnagarkar-dnsext-validator-api.

Now, the actual DNS name that owns the TLSA record in the DNS has a prefix of the form _<port>._<proto>. val_getdaneinfo() constructs that prefix for you automatically, so the value of name supplied by you should not contain this prefix. The

Not me ending a sentence there — that's genuinely how the original page trails off. The vibe check says the thought left the group chat mid-typing. 😭

The parameters for the TLSA lookup must be supplied in the params argument, which is a pointer to this structure:

struct val_daneparams {
  int port;
  int proto;
};

The port and proto fields get used in constructing that TLSA name prefix we were just talking about.

The results of the TLSA lookup come back in the dres argument, which is a pointer to a linked list of structures shaped like this:

struct val_danestatus {
  long ttl;
  int usage;
  int selector;
  int type;
  size_t datalen;
  unsigned char *data;
  struct val_danestatus *next;
};

Let's break it down, bestie:

  • ttl — the time-to-live associated with the TLSA record. ⚠️ An application must not cache (and use) this TLSA record beyond its TTL. That's not a suggestion, that's the rule.
  • usage, selector, type — these correspond to the first three fields of the TLSA RDATA as described in rfc6698.
  • data — the TLSA certificate association data, and it has a length of datalen bytes.
  • next — there can be more than one TLSA record associated with a given name, and this points to the next record in the list.

Given a linked list of TLSA structures in dres, val_dane_match() can be used to check whether the certificate association data for a given element in this list matches the DER encoded data provided in databytes, of the length databyteslen.

The val_dane_check() function simplifies the match operation when OpenSSL is used to provide SSL/TLS support inside your application. This function automatically iterates over all elements in dres and compares the certificate association data against the SSL/TLS certificates associated with the SSL connection con. The DANE protocol enables certain use cases that allow new trust anchors to be introduced via DNSSEC. The value of do_pathval indicates whether the application must proceed with X509 path validation for this connection, in accordance with the usage that was encoded in the TLSA record.

The val_free_dane() function frees the memory associated with the linked list pointed to by dres. Give it back to the void, periodt. 🦋

The ctx parameter in all the above functions specifies the validation context, and it can be set to NULL for default values (peep libval(3) and dnsval.conf for more details on validation contexts and validation policy).

👑 RETURN VALUES 👑

val_getdaneinfo() and val_dane_submit() return VAL_DANE_NOERROR on success, and VAL_DANE_MALFORMED_TLSA or VAL_DANE_INTERNAL_ERROR for error conditions. A value of VAL_DANE_NOTVALIDATED is returned if the TLSA record cannot be validated via DNSSEC. And a value of VAL_DANE_IGNORE_TLSA is returned if the TLSA record for the given name is provably absent.

The retval value returned as an argument to val_dane_callback() can contain one of:

  • VAL_DANE_NOERROR — for success ✨
  • VAL_DANE_INTERNAL_ERROR — for error conditions 💀
  • VAL_DANE_CANCELLED — when the asynchronous request is canceled 🙈

val_dane_match() and val_dane_check() return VAL_DANE_NOERROR on success, VAL_DANE_INTERNAL_ERROR for general error conditions, and VAL_DANE_CHECK_FAILED if the TLSA record cannot be successfully matched against the certificate association data provided.

The p_dane_error() function can be used to convert the DANE-related error codes to an error string value.

Copyright 2004-2013 SPARTA, Inc. All rights reserved. See the COPYING file included with the DNSSEC-Tools package for details.

🌈 AUTHORS 🌈

Suresh Krishnaswamy

🫶 SEE ALSO 🫶

And that's the whole page, bestie — go validate some TLSA records and be iconic about it. 💅✨

This lil doc was brought to you by perl v5.26.2, dated 2016-12-16, and it's the val_getdaneinfo(3) page from the Programmer's Manual. Stay caffeinated, stay validated. 🦋💖

📦 where this page comes from