2 * unbound.h - unbound validating resolver public API
4 * Copyright (c) 2007, NLnet Labs. All rights reserved.
6 * This software is open source.
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
12 * Redistributions of source code must retain the above copyright notice,
13 * this list of conditions and the following disclaimer.
15 * Redistributions in binary form must reproduce the above copyright notice,
16 * this list of conditions and the following disclaimer in the documentation
17 * and/or other materials provided with the distribution.
19 * Neither the name of the NLNET LABS nor the names of its contributors may
20 * be used to endorse or promote products derived from this software without
21 * specific prior written permission.
23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
25 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
26 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
27 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
32 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33 * POSSIBILITY OF SUCH DAMAGE.
39 * This file contains functions to resolve DNS queries and
40 * validate the answers. Synchonously and asynchronously.
42 * Several ways to use this interface from an application wishing
43 * to perform (validated) DNS lookups.
46 * ctx = ub_ctx_create();
47 * err = ub_ctx_add_ta(ctx, "...");
48 * err = ub_ctx_add_ta(ctx, "...");
50 * ... call ub_ctx_delete(ctx); when you want to stop.
52 * Application not threaded. Blocking.
53 * int err = ub_resolve(ctx, "www.example.com", ...
54 * if(err) fprintf(stderr, "lookup error: %s\n", ub_strerror(err));
57 * Application not threaded. Non-blocking ('asynchronous').
58 * err = ub_resolve_async(ctx, "www.example.com", ... my_callback);
59 * ... application resumes processing ...
60 * ... and when either ub_poll(ctx) is true
61 * ... or when the file descriptor ub_fd(ctx) is readable,
62 * ... or whenever, the app calls ...
64 * ... if no result is ready, the app resumes processing above,
65 * ... or process() calls my_callback() with results.
67 * ... if the application has nothing more to do, wait for answer
70 * Application threaded. Blocking.
71 * Blocking, same as above. The current thread does the work.
72 * Multiple threads can use the *same context*, each does work and uses
73 * shared cache data from the context.
75 * Application threaded. Non-blocking ('asynchronous').
76 * ... setup threaded-asynchronous config option
77 * err = ub_ctx_async(ctx, 1);
78 * ... same as async for non-threaded
79 * ... the callbacks are called in the thread that calls process(ctx)
81 * If no threading is compiled in, the above async example uses fork(2) to
82 * create a process to perform the work. The forked process exits when the
83 * calling process exits, or ctx_delete() is called.
84 * Otherwise, for asynchronous with threading, a worker thread is created.
86 * The blocking calls use shared ctx-cache when threaded. Thus
87 * ub_resolve() and ub_resolve_async() && ub_wait() are
88 * not the same. The first makes the current thread do the work, setting
89 * up buffers, etc, to perform the work (but using shared cache data).
90 * The second calls another worker thread (or process) to perform the work.
91 * And no buffers need to be set up, but a context-switch happens.
101 * The validation context is created to hold the resolver status,
102 * validation keys and a small cache (containing messages, rrsets,
103 * roundtrip times, trusted keys, lameness information).
105 * Its contents are internally defined.
110 * The validation and resolution results.
111 * Allocated by the resolver, and need to be freed by the application
112 * with ub_resolve_free().
115 /** The original question, name text string. */
117 /** the type asked for */
119 /** the class asked for */
123 * a list of network order DNS rdata items, terminated with a
124 * NULL pointer, so that data[0] is the first result entry,
125 * data[1] the second, and the last entry is NULL.
126 * If there was no data, data[0] is NULL.
130 /** the length in bytes of the data items, len[i] for data[i] */
134 * canonical name for the result (the final cname).
135 * zero terminated string.
136 * May be NULL if no canonical name exists.
141 * DNS RCODE for the result. May contain additional error code if
142 * there was no data due to an error. 0 (NOERROR) if okay.
147 * The DNS answer packet. Network formatted. Can contain DNSSEC types.
150 /** length of the answer packet in octets. */
154 * If there is any data, this is true.
155 * If false, there was no data (nxdomain may be true, rcode can be set).
160 * If there was no data, and the domain did not exist, this is true.
161 * If it is false, and there was no data, then the domain name
162 * is purported to exist, but the requested data type is not available.
167 * True, if the result is validated securely.
168 * False, if validation failed or domain queried has no security info.
170 * It is possible to get a result with no data (havedata is false),
171 * and secure is true. This means that the non-existance of the data
172 * was cryptographically proven (with signatures).
177 * If the result was not secure (secure==0), and this result is due
178 * to a security failure, bogus is true.
179 * This means the data has been actively tampered with, signatures
180 * failed, expected signatures were not present, timestamps on
181 * signatures were out of date and so on.
183 * If !secure and !bogus, this can happen if the data is not secure
184 * because security is disabled for that domain name.
185 * This means the data is from a domain where data is not signed.
190 * If the result is bogus this contains a string (zero terminated)
191 * that describes the failure. There may be other errors as well
192 * as the one described, the description may not be perfectly accurate.
193 * Is NULL if the result is not bogus.
198 * TTL for the result, in seconds. If the security is bogus, then
199 * you also cannot trust this value.
205 * Callback for results of async queries.
206 * The readable function definition looks like:
207 * void my_callback(void* my_arg, int err, struct ub_result* result);
209 * void* my_arg: your pointer to a (struct of) data of your choice,
211 * int err: if 0 all is OK, otherwise an error occured and no results
213 * struct result: pointer to more detailed result structure.
214 * This structure is allocated on the heap and needs to be
215 * freed with ub_resolve_free(result);
217 typedef void (*ub_callback_t)(void*, int, struct ub_result*);
220 * Create a resolving and validation context.
221 * The information from /etc/resolv.conf and /etc/hosts is not utilised by
222 * default. Use ub_ctx_resolvconf and ub_ctx_hosts to read them.
223 * @return a new context. default initialisation.
224 * returns NULL on error.
226 struct ub_ctx* ub_ctx_create(void);
229 * Destroy a validation context and free all its resources.
230 * Outstanding async queries are killed and callbacks are not called for them.
231 * @param ctx: context to delete.
233 void ub_ctx_delete(struct ub_ctx* ctx);
236 * Set an option for the context.
237 * @param ctx: context.
238 * @param opt: option name from the unbound.conf config file format.
239 * (not all settings applicable). The name includes the trailing ':'
240 * for example ub_ctx_set_option(ctx, "logfile:", "mylog.txt");
241 * This is a power-users interface that lets you specify all sorts
243 * For some specific options, such as adding trust anchors, special
245 * @param val: value of the option.
246 * @return: 0 if OK, else error.
248 int ub_ctx_set_option(struct ub_ctx* ctx, const char* opt, const char* val);
251 * Get an option from the context.
252 * @param ctx: context.
253 * @param opt: option name from the unbound.conf config file format.
254 * (not all settings applicable). The name excludes the trailing ':'
255 * for example ub_ctx_get_option(ctx, "logfile", &result);
256 * This is a power-users interface that lets you specify all sorts
258 * @param str: the string is malloced and returned here. NULL on error.
259 * The caller must free() the string. In cases with multiple
260 * entries (auto-trust-anchor-file), a newline delimited list is
261 * returned in the string.
262 * @return 0 if OK else an error code (malloc failure, syntax error).
264 int ub_ctx_get_option(struct ub_ctx* ctx, const char* opt, char** str);
267 * setup configuration for the given context.
268 * @param ctx: context.
269 * @param fname: unbound config file (not all settings applicable).
270 * This is a power-users interface that lets you specify all sorts
272 * For some specific options, such as adding trust anchors, special
274 * @return: 0 if OK, else error.
276 int ub_ctx_config(struct ub_ctx* ctx, const char* fname);
279 * Set machine to forward DNS queries to, the caching resolver to use.
280 * IP4 or IP6 address. Forwards all DNS requests to that machine, which
281 * is expected to run a recursive resolver. If the proxy is not
282 * DNSSEC-capable, validation may fail. Can be called several times, in
283 * that case the addresses are used as backup servers.
285 * To read the list of nameservers from /etc/resolv.conf (from DHCP or so),
286 * use the call ub_ctx_resolvconf.
288 * @param ctx: context.
289 * At this time it is only possible to set configuration before the
290 * first resolve is done.
291 * @param addr: address, IP4 or IP6 in string format.
292 * If the addr is NULL, forwarding is disabled.
293 * @return 0 if OK, else error.
295 int ub_ctx_set_fwd(struct ub_ctx* ctx, const char* addr);
298 * Read list of nameservers to use from the filename given.
299 * Usually "/etc/resolv.conf". Uses those nameservers as caching proxies.
300 * If they do not support DNSSEC, validation may fail.
302 * Only nameservers are picked up, the searchdomain, ndots and other
303 * settings from resolv.conf(5) are ignored.
305 * @param ctx: context.
306 * At this time it is only possible to set configuration before the
307 * first resolve is done.
308 * @param fname: file name string. If NULL "/etc/resolv.conf" is used.
309 * @return 0 if OK, else error.
311 int ub_ctx_resolvconf(struct ub_ctx* ctx, const char* fname);
314 * Read list of hosts from the filename given.
315 * Usually "/etc/hosts".
316 * These addresses are not flagged as DNSSEC secure when queried for.
318 * @param ctx: context.
319 * At this time it is only possible to set configuration before the
320 * first resolve is done.
321 * @param fname: file name string. If NULL "/etc/hosts" is used.
322 * @return 0 if OK, else error.
324 int ub_ctx_hosts(struct ub_ctx* ctx, const char* fname);
327 * Add a trust anchor to the given context.
328 * The trust anchor is a string, on one line, that holds a valid DNSKEY or
330 * @param ctx: context.
331 * At this time it is only possible to add trusted keys before the
332 * first resolve is done.
333 * @param ta: string, with zone-format RR on one line.
334 * [domainname] [TTL optional] [type] [class optional] [rdata contents]
335 * @return 0 if OK, else error.
337 int ub_ctx_add_ta(struct ub_ctx* ctx, const char* ta);
340 * Add trust anchors to the given context.
341 * Pass name of a file with DS and DNSKEY records (like from dig or drill).
342 * @param ctx: context.
343 * At this time it is only possible to add trusted keys before the
344 * first resolve is done.
345 * @param fname: filename of file with keyfile with trust anchors.
346 * @return 0 if OK, else error.
348 int ub_ctx_add_ta_file(struct ub_ctx* ctx, const char* fname);
351 * Add trust anchors to the given context.
352 * Pass the name of a bind-style config file with trusted-keys{}.
353 * @param ctx: context.
354 * At this time it is only possible to add trusted keys before the
355 * first resolve is done.
356 * @param fname: filename of file with bind-style config entries with trust
358 * @return 0 if OK, else error.
360 int ub_ctx_trustedkeys(struct ub_ctx* ctx, const char* fname);
363 * Set debug output (and error output) to the specified stream.
364 * Pass NULL to disable. Default is stderr.
365 * @param ctx: context.
366 * @param out: FILE* out file stream to log to.
367 * Type void* to avoid stdio dependency of this header file.
368 * @return 0 if OK, else error.
370 int ub_ctx_debugout(struct ub_ctx* ctx, void* out);
373 * Set debug verbosity for the context
374 * Output is directed to stderr.
375 * @param ctx: context.
376 * @param d: debug level, 0 is off, 1 is very minimal, 2 is detailed,
378 * @return 0 if OK, else error.
380 int ub_ctx_debuglevel(struct ub_ctx* ctx, int d);
383 * Set a context behaviour for asynchronous action.
384 * @param ctx: context.
385 * @param dothread: if true, enables threading and a call to resolve_async()
386 * creates a thread to handle work in the background.
387 * If false, a process is forked to handle work in the background.
388 * Changes to this setting after async() calls have been made have
389 * no effect (delete and re-create the context to change).
390 * @return 0 if OK, else error.
392 int ub_ctx_async(struct ub_ctx* ctx, int dothread);
395 * Poll a context to see if it has any new results
396 * Do not poll in a loop, instead extract the fd below to poll for readiness,
397 * and then check, or wait using the wait routine.
398 * @param ctx: context.
399 * @return: 0 if nothing to read, or nonzero if a result is available.
400 * If nonzero, call ctx_process() to do callbacks.
402 int ub_poll(struct ub_ctx* ctx);
405 * Wait for a context to finish with results. Calls ub_process() after
406 * the wait for you. After the wait, there are no more outstanding
407 * asynchronous queries.
408 * @param ctx: context.
409 * @return: 0 if OK, else error.
411 int ub_wait(struct ub_ctx* ctx);
414 * Get file descriptor. Wait for it to become readable, at this point
415 * answers are returned from the asynchronous validating resolver.
416 * Then call the ub_process to continue processing.
417 * This routine works immediately after context creation, the fd
419 * @param ctx: context.
420 * @return: -1 on error, or file descriptor to use select(2) with.
422 int ub_fd(struct ub_ctx* ctx);
425 * Call this routine to continue processing results from the validating
426 * resolver (when the fd becomes readable).
427 * Will perform necessary callbacks.
428 * @param ctx: context
429 * @return: 0 if OK, else error.
431 int ub_process(struct ub_ctx* ctx);
434 * Perform resolution and validation of the target name.
435 * @param ctx: context.
436 * The context is finalized, and can no longer accept config changes.
437 * @param name: domain name in text format (a zero terminated text string).
438 * @param rrtype: type of RR in host order, 1 is A (address).
439 * @param rrclass: class of RR in host order, 1 is IN (for internet).
440 * @param result: the result data is returned in a newly allocated result
441 * structure. May be NULL on return, return value is set to an error
442 * in that case (out of memory).
443 * @return 0 if OK, else error.
445 int ub_resolve(struct ub_ctx* ctx, const char* name, int rrtype,
446 int rrclass, struct ub_result** result);
449 * Perform resolution and validation of the target name.
450 * Asynchronous, after a while, the callback will be called with your
451 * data and the result.
452 * @param ctx: context.
453 * If no thread or process has been created yet to perform the
454 * work in the background, it is created now.
455 * The context is finalized, and can no longer accept config changes.
456 * @param name: domain name in text format (a string).
457 * @param rrtype: type of RR in host order, 1 is A.
458 * @param rrclass: class of RR in host order, 1 is IN (for internet).
459 * @param mydata: this data is your own data (you can pass NULL),
460 * and is passed on to the callback function.
461 * @param callback: this is called on completion of the resolution.
463 * void callback(void* mydata, int err, struct ub_result* result)
464 * with mydata: the same as passed here, you may pass NULL,
465 * with err: is 0 when a result has been found.
466 * with result: a newly allocated result structure.
467 * The result may be NULL, in that case err is set.
469 * If an error happens during processing, your callback will be called
470 * with error set to a nonzero value (and result==NULL).
471 * @param async_id: if you pass a non-NULL value, an identifier number is
472 * returned for the query as it is in progress. It can be used to
474 * @return 0 if OK, else error.
476 int ub_resolve_async(struct ub_ctx* ctx, const char* name, int rrtype,
477 int rrclass, void* mydata, ub_callback_t callback, int* async_id);
480 * Cancel an async query in progress.
481 * Its callback will not be called.
483 * @param ctx: context.
484 * @param async_id: which query to cancel.
485 * @return 0 if OK, else error.
486 * This routine can return an error if the async_id passed does not exist
487 * or has already been delivered. If another thread is processing results
488 * at the same time, the result may be delivered at the same time and the
489 * cancel fails with an error. Also the cancel can fail due to a system
490 * error, no memory or socket failures.
492 int ub_cancel(struct ub_ctx* ctx, int async_id);
495 * Free storage associated with a result structure.
496 * @param result: to free
498 void ub_resolve_free(struct ub_result* result);
501 * Convert error value to a human readable string.
502 * @param err: error code from one of the ub_val* functions.
503 * @return pointer to constant text string, zero terminated.
505 const char* ub_strerror(int err);
508 * Debug routine. Print the local zone information to debug output.
509 * @param ctx: context. Is finalized by the routine.
510 * @return 0 if OK, else error.
512 int ub_ctx_print_local_zones(struct ub_ctx* ctx);
515 * Add a new zone with the zonetype to the local authority info of the
517 * @param ctx: context. Is finalized by the routine.
518 * @param zone_name: name of the zone in text, "example.com"
519 * If it already exists, the type is updated.
520 * @param zone_type: type of the zone (like for unbound.conf) in text.
521 * @return 0 if OK, else error.
523 int ub_ctx_zone_add(struct ub_ctx* ctx, char *zone_name, char *zone_type);
526 * Remove zone from local authority info of the library.
527 * @param ctx: context. Is finalized by the routine.
528 * @param zone_name: name of the zone in text, "example.com"
529 * If it does not exist, nothing happens.
530 * @return 0 if OK, else error.
532 int ub_ctx_zone_remove(struct ub_ctx* ctx, char *zone_name);
535 * Add localdata to the library local authority info.
536 * Similar to local-data config statement.
537 * @param ctx: context. Is finalized by the routine.
538 * @param data: the resource record in text format, for example
539 * "www.example.com IN A 127.0.0.1"
540 * @return 0 if OK, else error.
542 int ub_ctx_data_add(struct ub_ctx* ctx, char *data);
545 * Remove localdata from the library local authority info.
546 * @param ctx: context. Is finalized by the routine.
547 * @param data: the name to delete all data from, like "www.example.com".
548 * @return 0 if OK, else error.
550 int ub_ctx_data_remove(struct ub_ctx* ctx, char *data);
553 * Get a version string from the libunbound implementation.
554 * @return a static constant string with the version number.
556 const char* ub_version(void);
562 #endif /* _UB_UNBOUND_H */