.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "val_getdaneinfo 3"
.TH val_getdaneinfo 3 "2016-12-16" "perl v5.26.2" "Programmer's Manual"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
val_getdaneinfo() \- Perform synchronous validation of TLSA records
.PP
val_dane_submit() \- Perform asynchronous validation of TLSA records
.PP
val_dane_match() \- Validate TLSA information against provided data.
.PP
val_dane_check() \- Validate TLSA information for SSL connection
(OpenSSL only)
.PP
val_free_dane() \- Release memory associated with DANE result 
structure.
.PP
p_dane_error() \- Return error string for given DANE error code.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fI\fIval_getdaneinfo()\fI\fR performs a synchronous lookup of the \s-1TLSA\s0 record
associated with a given \fIname\fR and returns a linked list of all such
\&\fBvalidated\fR records.  \fI\fIval_dane_submit()\fI\fR performs the same lookup in 
an asynchronous manner and invokes the \fIcallback\fR function with the
\&\fIcallback_data\fR arguments on lookup completion. The callback function
has the following type definition:
.PP
.Vb 3
\&  typedef int (*val_dane_callback)(void *callback_data,
\&                                 int retval,
\&                                 struct val_danestatus **dres);
.Ve
.PP
The \fIstatus\fR argument provides a handle to the asynchronous request to
enable future operators (such as canceling the
request). For more information on the \fIval_async_status\fR object see 
draft-hayatnagarkar-dnsext-validator-api.
.PP
The actual \s-1DNS\s0 name that owns the \s-1TLSA\s0 record in the
\&\s-1DNS\s0 has a prefix of the form _<port>._<proto>. \fI\fIval_getdaneinfo()\fI\fR
will construct the above prefix automatically; so the value of \fIname\fR
suppplied by the user should not contain this prefix. The
.PP
The parameters for the \s-1TLSA\s0 lookup must be supplied in the \fIparams\fR
argument, which is a pointer to the following structure:
.PP
.Vb 4
\&  struct val_daneparams {
\&    int port;
\&    int proto;
\&  };
.Ve
.PP
The \fIport\fR and \fIproto\fR fields are used in constructing the \s-1TLSA\s0 name
prefix described above.
.PP
The results of the \s-1TLSA\s0 lookup are returned in the \fIdres\fR argument,
which is a pointer to a linked list of structures of the 
form below:
.PP
.Vb 9
\&  struct val_danestatus {
\&    long ttl;
\&    int usage;
\&    int selector;
\&    int type;
\&    size_t datalen;
\&    unsigned char *data;
\&    struct val_danestatus *next;
\&  };
.Ve
.PP
The \fIttl\fR field is the time-to-live associated with the \s-1TLSA\s0 record. An
application must not cache (and use) this \s-1TLSA\s0 record beyond its \s-1TTL.\s0
The \fIusage\fR, \fIselector\fR and \fItype\fR fields correspond to the first
three fields of the \s-1TLSA RDATA\s0 as described in rfc6698. The \s-1TLSA\s0
certificate association data is returned in the \fIdata\fR field and has
a length of \fIdatalen\fR bytes. There can be more than one \s-1TLSA\s0 record
associated with a given name, and the \fInext\fR field points to the next
record in this list.
.PP
Given a linked list of \s-1TLSA\s0 structures in \fIdres\fR, the
\&\fI\fIval_dane_match()\fI\fR can be used to check if the certificate association
data for a given element in this list matches the \s-1DER\s0 encoded data
provided in \fIdatabytes\fR of the length \fIdatabyteslen\fR.
.PP
The \fI\fIval_dane_check()\fI\fR function simplifies the match operation when
OpenSSL is used to provide \s-1SSL/TLS\s0 support within the application.
This function automatically iterates over all elements in \fIdres\fR and
compares the certificate association data against the \s-1SSL/TLS\s0
certificates associated with the \s-1SSL\s0 connection \fIcon\fR. The \s-1DANE\s0
protocol enables certain use cases that allows new trust anchors to be
introduced via \s-1DNSSEC.\s0 The value of \fIdo_pathval\fR indicates whether
the application must proceed with X509 path validation for this
connection in accordance with the usage that was encoded in the \s-1TLSA\s0
record.
.PP
The \fI\fIval_free_dane()\fI\fR function frees the memory associated with 
with the linked list pointed to by \fIdres\fR.
.PP
The \fIctx\fR parameter in all the above functions specifies the validation
context, which can be set to \s-1NULL\s0 for default values (see \fI\fIlibval\fI\|(3)\fR
and \fIdnsval.conf\fR for more details on validation contexts and
validation policy).
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fI\fIval_getdaneinfo()\fI\fR and \fI\fIval_dane_submit()\fI\fR return \fB\s-1VAL_DANE_NOERROR\s0\fR
on success, and \fB\s-1VAL_DANE_MALFORMED_TLSA\s0\fR or \fB\s-1VAL_DANE_INTERNAL_ERROR\s0\fR
for error conditions. A value of \fB\s-1VAL_DANE_NOTVALIDATED\s0\fR is returned if
the \s-1TLSA\s0 record cannot be validated via \s-1DNSSEC. A\s0 value of
\&\fB\s-1VAL_DANE_IGNORE_TLSA\s0\fR is returned if the \s-1TLSA\s0 record for the given name
is provably absent.
.PP
The \fIretval\fR value returned as an argument to \fI\fIval_dane_callback()\fI\fR
can contain one of \fB\s-1VAL_DANE_NOERROR\s0\fR (for success),
\&\fB\s-1VAL_DANE_INTERNAL_ERROR\s0\fR (for error conditions) or
\&\fB\s-1VAL_DANE_CANCELLED\s0\fR (when the asynchronous request is canceled).
.PP
\&\fI\fIval_dane_match()\fI\fR and \fI\fIval_dane_check()\fI\fR return \fB\s-1VAL_DANE_NOERROR\s0\fR on
success, \fB\s-1VAL_DANE_INTERNAL_ERROR\s0\fR for general error conditions, and
\&\fB\s-1VAL_DANE_CHECK_FAILED\s0\fR if the \s-1TLSA\s0 record cannot be successfully matched
against the certificate association data provided.
.PP
The \fI\fIp_dane_error()\fI\fR function can be used to convert the DANE-related
error codes to an error string value.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2004\-2013 \s-1SPARTA,\s0 Inc.  All rights reserved.
See the \s-1COPYING\s0 file included with the DNSSEC-Tools package for details.
.SH "AUTHORS"
.IX Header "AUTHORS"
Suresh Krishnaswamy
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fI\fIlibval\fI\|(3)\fR
.PP
\&\s-1RFC 6698\s0 (\s-1DANE\s0)
.PP
draft-hayatnagarkar-dnsext-validator-api
.PP
http://www.dnssec\-tools.org