1val_getdaneinfo(3)            Programmer's Manual           val_getdaneinfo(3)
2
3
4

NAME

6       val_getdaneinfo() - Perform synchronous validation of TLSA records
7
8       val_dane_submit() - Perform asynchronous validation of TLSA records
9
10       val_dane_match() - Validate TLSA information against provided data.
11
12       val_dane_check() - Validate TLSA information for SSL connection
13       (OpenSSL only)
14
15       val_free_dane() - Release memory associated with DANE result structure.
16
17       p_dane_error() - Return error string for given DANE error code.
18

SYNOPSIS

20         #include <validator/validator.h>
21         #include <validator/val_dane.h>
22
23         int val_getdaneinfo(val_context_t *ctx,
24                           const char *name,
25                           struct val_daneparams *params,
26                           struct val_danestatus **dres);
27
28         int val_dane_submit(val_context_t *ctx,
29                           const char *name,
30                           struct val_daneparams *params,
31                           val_dane_callback callback,
32                           void *callback_data,
33                           val_async_status **status);
34
35         int val_dane_match(val_context_t *ctx,
36                          struct val_danestatus *dane_cur,
37                          const unsigned char *databytes,
38                          int databyteslen);
39
40         #include <openssl/ssl.h>
41         int val_dane_check(val_context_t *ctx,
42                          SSL *con,
43                          struct val_danestatus *danestatus,
44                          int *do_pathval);
45
46         void val_free_dane(struct val_danestatus *dres);
47
48         const char *p_dane_error(int rc);
49

DESCRIPTION

51       val_getdaneinfo() performs a synchronous lookup of the TLSA record
52       associated with a given name and returns a linked list of all such
53       validated records.  val_dane_submit() performs the same lookup in an
54       asynchronous manner and invokes the callback function with the
55       callback_data arguments on lookup completion. The callback function has
56       the following type definition:
57
58         typedef int (*val_dane_callback)(void *callback_data,
59                                        int retval,
60                                        struct val_danestatus **dres);
61
62       The status argument provides a handle to the asynchronous request to
63       enable future operators (such as canceling the request). For more
64       information on the val_async_status object see draft-hayatnagarkar-
65       dnsext-validator-api.
66
67       The actual DNS name that owns the TLSA record in the DNS has a prefix
68       of the form _<port>._<proto>. val_getdaneinfo() will construct the
69       above prefix automatically; so the value of name suppplied by the user
70       should not contain this prefix. The
71
72       The parameters for the TLSA lookup must be supplied in the params
73       argument, which is a pointer to the following structure:
74
75         struct val_daneparams {
76           int port;
77           int proto;
78         };
79
80       The port and proto fields are used in constructing the TLSA name prefix
81       described above.
82
83       The results of the TLSA lookup are returned in the dres argument, which
84       is a pointer to a linked list of structures of the form below:
85
86         struct val_danestatus {
87           long ttl;
88           int usage;
89           int selector;
90           int type;
91           size_t datalen;
92           unsigned char *data;
93           struct val_danestatus *next;
94         };
95
96       The ttl field is the time-to-live associated with the TLSA record. An
97       application must not cache (and use) this TLSA record beyond its TTL.
98       The usage, selector and type fields correspond to the first three
99       fields of the TLSA RDATA as described in rfc6698. The TLSA certificate
100       association data is returned in the data field and has a length of
101       datalen bytes. There can be more than one TLSA record associated with a
102       given name, and the next field points to the next record in this list.
103
104       Given a linked list of TLSA structures in dres, the val_dane_match()
105       can be used to check if the certificate association data for a given
106       element in this list matches the DER encoded data provided in databytes
107       of the length databyteslen.
108
109       The val_dane_check() function simplifies the match operation when
110       OpenSSL is used to provide SSL/TLS support within the application.
111       This function automatically iterates over all elements in dres and
112       compares the certificate association data against the SSL/TLS
113       certificates associated with the SSL connection con. The DANE protocol
114       enables certain use cases that allows new trust anchors to be
115       introduced via DNSSEC. The value of do_pathval indicates whether the
116       application must proceed with X509 path validation for this connection
117       in accordance with the usage that was encoded in the TLSA record.
118
119       The val_free_dane() function frees the memory associated with with the
120       linked list pointed to by dres.
121
122       The ctx parameter in all the above functions specifies the validation
123       context, which can be set to NULL for default values (see libval(3) and
124       dnsval.conf for more details on validation contexts and validation
125       policy).
126

RETURN VALUES

128       val_getdaneinfo() and val_dane_submit() return VAL_DANE_NOERROR on
129       success, and VAL_DANE_MALFORMED_TLSA or VAL_DANE_INTERNAL_ERROR for
130       error conditions. A value of VAL_DANE_NOTVALIDATED is returned if the
131       TLSA record cannot be validated via DNSSEC. A value of
132       VAL_DANE_IGNORE_TLSA is returned if the TLSA record for the given name
133       is provably absent.
134
135       The retval value returned as an argument to val_dane_callback() can
136       contain one of VAL_DANE_NOERROR (for success), VAL_DANE_INTERNAL_ERROR
137       (for error conditions) or VAL_DANE_CANCELLED (when the asynchronous
138       request is canceled).
139
140       val_dane_match() and val_dane_check() return VAL_DANE_NOERROR on
141       success, VAL_DANE_INTERNAL_ERROR for general error conditions, and
142       VAL_DANE_CHECK_FAILED if the TLSA record cannot be successfully matched
143       against the certificate association data provided.
144
145       The p_dane_error() function can be used to convert the DANE-related
146       error codes to an error string value.
147
149       Copyright 2004-2013 SPARTA, Inc.  All rights reserved.  See the COPYING
150       file included with the DNSSEC-Tools package for details.
151

AUTHORS

153       Suresh Krishnaswamy
154

SEE ALSO

156       libval(3)
157
158       RFC 6698 (DANE)
159
160       draft-hayatnagarkar-dnsext-validator-api
161
162       http://www.dnssec-tools.org
163
164
165
166perl v5.26.2                      2016-12-16                val_getdaneinfo(3)
Impressum