p_dane_error

val_getdaneinfo(3)            Programmer's Manual           val_getdaneinfo(3)



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

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.

COPYRIGHT
       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
       libval(3)

       RFC 6698 (DANE)

       draft-hayatnagarkar-dnsext-validator-api

       http://www.dnssec-tools.org




perl v5.26.2                      2016-12-16                val_getdaneinfo(3)