=pod

=head1 NAME


I<val_getdaneinfo()> - Perform synchronous validation of TLSA records

I<val_dane_submit()> - Perform asynchronous validation of TLSA records

I<val_dane_match()> - Validate TLSA information against provided data. 

I<val_dane_check()> - Validate TLSA information for SSL connection
(OpenSSL only)

I<val_free_dane()> - Release memory associated with DANE result 
structure.

I<p_dane_error()> - Return error string for given DANE error code.

=head1 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);


=head1 DESCRIPTION

I<val_getdaneinfo()> performs a synchronous lookup of the TLSA record
associated with a given I<name> and returns a linked list of all such
B<validated> records.  I<val_dane_submit()> performs the same lookup in 
an asynchronous manner and invokes the I<callback> function with the
I<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 I<status> argument provides a handle to the asynchronous request to
enable future operators (such as canceling the
request). For more information on the I<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>. I<val_getdaneinfo()>
will construct the above prefix automatically; so the value of I<name>
suppplied by the user should not contain this prefix. The

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

  struct val_daneparams {
    int port;
    int proto;
  };

The I<port> and I<proto> fields are used in constructing the TLSA name
prefix described above.

The results of the TLSA lookup are returned in the I<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 I<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 I<usage>, I<selector> and I<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 I<data> field and has
a length of I<datalen> bytes. There can be more than one TLSA record
associated with a given name, and the I<next> field points to the next
record in this list. 

Given a linked list of TLSA structures in I<dres>, the
I<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 I<databytes> of the length I<databyteslen>. 

The I<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 I<dres> and
compares the certificate association data against the SSL/TLS
certificates associated with the SSL connection I<con>. The DANE
protocol enables certain use cases that allows new trust anchors to be
introduced via DNSSEC. The value of I<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 I<val_free_dane()> function frees the memory associated with 
with the linked list pointed to by I<dres>.

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

=head1 RETURN VALUES

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

The I<retval> value returned as an argument to I<val_dane_callback()>
can contain one of B<VAL_DANE_NOERROR> (for success),
B<VAL_DANE_INTERNAL_ERROR> (for error conditions) or
B<VAL_DANE_CANCELLED> (when the asynchronous request is canceled). 

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

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

=head1 COPYRIGHT

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

=head1 AUTHORS

Suresh Krishnaswamy

=head1 SEE ALSO

I<libval(3)>

RFC 6698 (DANE)

draft-hayatnagarkar-dnsext-validator-api

http://www.dnssec-tools.org

=cut
