val_getdaneinfo






val_getdaneinfo() − Perform synchronous validation of TLSA
records

     val_dane_submit() − Perform asynchronous validation of
TLSA records

     val_dane_match() − Validate TLSA information against
provided data.

     val_dane_check() − Validate TLSA information for SSL
connection (OpenSSL only)

     val_free_dane() − Release memory associated with DANE
result structure.

     p_dane_error() − Return error string for given DANE
error code.


  #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);

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









                             ‐2‐


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.









                             ‐3‐


     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).

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.

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











                             ‐4‐


Suresh Krishnaswamy

libval(3)

     RFC 6698 (DANE)

     draft‐hayatnagarkar‐dnsext‐validator‐api

     http://www.dnssec−tools.org