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
val_getdaneinfo() performs a synchronous lookup of the TLSA record associated with a given name and returns a linked list of all such validated records. val_dane_submit() performs the same lookup in an asynchronous manner and invokes the callback function with the callback_data arguments on lookup completion. The callback function has the following type definition:
typedef int (*val_dane_callback)(void *callback_data,
int retval,
struct val_danestatus **dres);
The status argument provides a handle to the asynchronous request to enable future operators (such as canceling the request). For more information on the val_async_status object see draft-hayatnagarkar-dnsext-validator-api.
The actual DNS name that owns the TLSA record in the DNS has a prefix of the form _<port>._<proto>. val_getdaneinfo() will construct the above prefix automatically; so the value of name suppplied by the user should not contain this prefix. The
The parameters for the TLSA lookup must be supplied in the params argument, which is a pointer to the following structure:
struct val_daneparams {
int port;
int proto;
};
The port and proto fields are used in constructing the TLSA name prefix described above.
The results of the TLSA lookup are returned in the dres argument, which is a pointer to a linked list of structures of the form below:
struct val_danestatus {
long ttl;
int usage;
int selector;
int type;
size_t datalen;
unsigned char *data;
struct val_danestatus *next;
};
The ttl field is the time-to-live associated with the TLSA record. An application must not cache (and use) this TLSA record beyond its TTL. The usage, selector and type fields correspond to the first three fields of the TLSA RDATA as described in rfc6698. The TLSA certificate association data is returned in the data field and has a length of datalen bytes. There can be more than one TLSA record associated with a given name, and the next field points to the next record in this list.
Given a linked list of TLSA structures in dres, the val_dane_match() can be used to check if 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 within the 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 allows 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 with the linked list pointed to by dres.
The ctx parameter in all the above functions specifies the validation context, which can be set to NULL for default values (see 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. 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) or 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.