1val_getdaneinfo(3) Programmer's Manual val_getdaneinfo(3)
2
6 val_getdaneinfo() - Perform synchronous validation of TLSA records
7 val_dane_submit() - Perform asynchronous validation of TLSA records
9 val_dane_match() - Validate TLSA information against provided data.
11 val_dane_check() - Validate TLSA information for SSL connection
13 (OpenSSL only)
14 val_free_dane() - Release memory associated with DANE result structure.
16 p_dane_error() - Return error string for given DANE error code.
18
20 #include <validator/validator.h>
21 #include <validator/val_dane.h>
22 int val_getdaneinfo(val_context_t *ctx,
24 const char *name,
25 struct val_daneparams *params,
26 struct val_danestatus **dres);
27 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 int val_dane_match(val_context_t *ctx,
36 struct val_danestatus *dane_cur,
37 const unsigned char *databytes,
38 int databyteslen);
39 #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 void val_free_dane(struct val_danestatus *dres);
47 const char *p_dane_error(int rc);
49
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 typedef int (*val_dane_callback)(void *callback_data,
59 int retval,
60 struct val_danestatus **dres);
61 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 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 The parameters for the TLSA lookup must be supplied in the params
73 argument, which is a pointer to the following structure:
74 struct val_daneparams {
76 int port;
77 int proto;
78 };
79 The port and proto fields are used in constructing the TLSA name prefix
81 described above.
82 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 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 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 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 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 The val_free_dane() function frees the memory associated with with the
120 linked list pointed to by dres.
121 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
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 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 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 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
153 Suresh Krishnaswamy
154
156 libval(3)
157 RFC 6698 (DANE)
159 draft-hayatnagarkar-dnsext-validator-api
161 http://www.dnssec-tools.org
163perl v5.26.2 2016-12-16 val_getdaneinfo(3)