xref: /freebsd/contrib/unbound/libunbound/unbound.h (revision 46d2f61818f594174cafe31ee338c6e083fa1876)
1 /*
2  * unbound.h - unbound validating resolver public API
3  *
4  * Copyright (c) 2007, NLnet Labs. All rights reserved.
5  *
6  * This software is open source.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * Redistributions of source code must retain the above copyright notice,
13  * this list of conditions and the following disclaimer.
14  *
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.
18  *
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.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
26  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
27  * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
28  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
29  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
30  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
31  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
32  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
33  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34  */
35 
36 /**
37  * \file
38  *
39  * This file contains functions to resolve DNS queries and
40  * validate the answers. Synchronously and asynchronously.
41  *
42  * Several ways to use this interface from an application wishing
43  * to perform (validated) DNS lookups.
44  *
45  * All start with
46  *	ctx = ub_ctx_create();
47  *	err = ub_ctx_add_ta(ctx, "...");
48  *	err = ub_ctx_add_ta(ctx, "...");
49  *	... some lookups
50  *	... call ub_ctx_delete(ctx); when you want to stop.
51  *
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));
55  *	... use the answer
56  *
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 ...
63  *	ub_process(ctx);
64  *	... if no result is ready, the app resumes processing above,
65  *	... or process() calls my_callback() with results.
66  *
67  *      ... if the application has nothing more to do, wait for answer
68  *      ub_wait(ctx);
69  *
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.
74  *
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)
80  *
81  * Openssl needs to have locking in place, and the application must set
82  * it up, because a mere library cannot do this, use the calls
83  * CRYPTO_set_id_callback and CRYPTO_set_locking_callback.
84  *
85  * If no threading is compiled in, the above async example uses fork(2) to
86  * create a process to perform the work. The forked process exits when the
87  * calling process exits, or ctx_delete() is called.
88  * Otherwise, for asynchronous with threading, a worker thread is created.
89  *
90  * The blocking calls use shared ctx-cache when threaded. Thus
91  * ub_resolve() and ub_resolve_async() && ub_wait() are
92  * not the same. The first makes the current thread do the work, setting
93  * up buffers, etc, to perform the work (but using shared cache data).
94  * The second calls another worker thread (or process) to perform the work.
95  * And no buffers need to be set up, but a context-switch happens.
96  */
97 #ifndef UB_UNBOUND_H
98 #define UB_UNBOUND_H
99 
100 #ifdef __cplusplus
101 extern "C" {
102 #endif
103 
104 /** the version of this header file */
105 #define UNBOUND_VERSION_MAJOR @UNBOUND_VERSION_MAJOR@
106 #define UNBOUND_VERSION_MINOR @UNBOUND_VERSION_MINOR@
107 #define UNBOUND_VERSION_MICRO @UNBOUND_VERSION_MICRO@
108 
109 /**
110  * The validation context is created to hold the resolver status,
111  * validation keys and a small cache (containing messages, rrsets,
112  * roundtrip times, trusted keys, lameness information).
113  *
114  * Its contents are internally defined.
115  */
116 struct ub_ctx;
117 
118 /**
119  * The validation and resolution results.
120  * Allocated by the resolver, and need to be freed by the application
121  * with ub_resolve_free().
122  */
123 struct ub_result {
124 	/** The original question, name text string. */
125 	char* qname;
126 	/** the type asked for */
127 	int qtype;
128 	/** the class asked for */
129 	int qclass;
130 
131 	/**
132 	 * a list of network order DNS rdata items, terminated with a
133 	 * NULL pointer, so that data[0] is the first result entry,
134 	 * data[1] the second, and the last entry is NULL.
135 	 * If there was no data, data[0] is NULL.
136 	 */
137 	char** data;
138 
139 	/** the length in bytes of the data items, len[i] for data[i] */
140 	int* len;
141 
142 	/**
143 	 * canonical name for the result (the final cname).
144 	 * zero terminated string.
145 	 * May be NULL if no canonical name exists.
146 	 */
147 	char* canonname;
148 
149 	/**
150 	 * DNS RCODE for the result. May contain additional error code if
151 	 * there was no data due to an error. 0 (NOERROR) if okay.
152 	 */
153 	int rcode;
154 
155 	/**
156 	 * The DNS answer packet. Network formatted. Can contain DNSSEC types.
157 	 */
158 	void* answer_packet;
159 	/** length of the answer packet in octets. */
160 	int answer_len;
161 
162 	/**
163 	 * If there is any data, this is true.
164 	 * If false, there was no data (nxdomain may be true, rcode can be set).
165 	 */
166 	int havedata;
167 
168 	/**
169 	 * If there was no data, and the domain did not exist, this is true.
170 	 * If it is false, and there was no data, then the domain name
171 	 * is purported to exist, but the requested data type is not available.
172 	 */
173 	int nxdomain;
174 
175 	/**
176 	 * True, if the result is validated securely.
177 	 * False, if validation failed or domain queried has no security info.
178 	 *
179 	 * It is possible to get a result with no data (havedata is false),
180 	 * and secure is true. This means that the non-existence of the data
181 	 * was cryptographically proven (with signatures).
182 	 */
183 	int secure;
184 
185 	/**
186 	 * If the result was not secure (secure==0), and this result is due
187 	 * to a security failure, bogus is true.
188 	 * This means the data has been actively tampered with, signatures
189 	 * failed, expected signatures were not present, timestamps on
190 	 * signatures were out of date and so on.
191 	 *
192 	 * If !secure and !bogus, this can happen if the data is not secure
193 	 * because security is disabled for that domain name.
194 	 * This means the data is from a domain where data is not signed.
195 	 */
196 	int bogus;
197 
198 	/**
199 	 * If the result is bogus this contains a string (zero terminated)
200 	 * that describes the failure.  There may be other errors as well
201 	 * as the one described, the description may not be perfectly accurate.
202 	 * Is NULL if the result is not bogus.
203 	 */
204 	char* why_bogus;
205 
206 	/**
207 	 * If the query or one of its subqueries was ratelimited.  Useful if
208 	 * ratelimiting is enabled and answer to the client is SERVFAIL as a
209 	 * result.
210 	 */
211 	int was_ratelimited;
212 
213 	/**
214 	 * TTL for the result, in seconds.  If the security is bogus, then
215 	 * you also cannot trust this value.
216 	 */
217 	int ttl;
218 };
219 
220 /**
221  * Callback for results of async queries.
222  * The readable function definition looks like:
223  * void my_callback(void* my_arg, int err, struct ub_result* result);
224  * It is called with
225  *	void* my_arg: your pointer to a (struct of) data of your choice,
226  *		or NULL.
227  *	int err: if 0 all is OK, otherwise an error occurred and no results
228  *	     are forthcoming.
229  *	struct result: pointer to more detailed result structure.
230  *		This structure is allocated on the heap and needs to be
231  *		freed with ub_resolve_free(result);
232  */
233 typedef void (*ub_callback_type)(void*, int, struct ub_result*);
234 
235 /**
236  * The error constants
237  */
238 enum ub_ctx_err {
239 	/** no error */
240 	UB_NOERROR = 0,
241 	/** socket operation. Set to -1, so that if an error from _fd() is
242 	 * passed (-1) it gives a socket error. */
243 	UB_SOCKET = -1,
244 	/** alloc failure */
245 	UB_NOMEM = -2,
246 	/** syntax error */
247 	UB_SYNTAX = -3,
248 	/** DNS service failed */
249 	UB_SERVFAIL = -4,
250 	/** fork() failed */
251 	UB_FORKFAIL = -5,
252 	/** cfg change after finalize() */
253 	UB_AFTERFINAL = -6,
254 	/** initialization failed (bad settings) */
255 	UB_INITFAIL = -7,
256 	/** error in pipe communication with async bg worker */
257 	UB_PIPE = -8,
258 	/** error reading from file (resolv.conf) */
259 	UB_READFILE = -9,
260 	/** error async_id does not exist or result already been delivered */
261 	UB_NOID = -10
262 };
263 
264 /**
265  * Create a resolving and validation context.
266  * The information from /etc/resolv.conf and /etc/hosts is not utilised by
267  * default. Use ub_ctx_resolvconf and ub_ctx_hosts to read them.
268  * @return a new context. default initialisation.
269  * 	returns NULL on error.
270  */
271 struct ub_ctx* ub_ctx_create(void);
272 
273 /**
274  * Destroy a validation context and free all its resources.
275  * Outstanding async queries are killed and callbacks are not called for them.
276  * @param ctx: context to delete.
277  */
278 void ub_ctx_delete(struct ub_ctx* ctx);
279 
280 /**
281  * Set an option for the context.
282  * @param ctx: context.
283  * @param opt: option name from the unbound.conf config file format.
284  *	(not all settings applicable). The name includes the trailing ':'
285  *	for example ub_ctx_set_option(ctx, "logfile:", "mylog.txt");
286  * 	This is a power-users interface that lets you specify all sorts
287  * 	of options.
288  * 	For some specific options, such as adding trust anchors, special
289  * 	routines exist.
290  * @param val: value of the option.
291  * @return: 0 if OK, else error.
292  */
293 int ub_ctx_set_option(struct ub_ctx* ctx, const char* opt, const char* val);
294 
295 /**
296  * Get an option from the context.
297  * @param ctx: context.
298  * @param opt: option name from the unbound.conf config file format.
299  *	(not all settings applicable). The name excludes the trailing ':'
300  *	for example ub_ctx_get_option(ctx, "logfile", &result);
301  * 	This is a power-users interface that lets you specify all sorts
302  * 	of options.
303  * @param str: the string is malloced and returned here. NULL on error.
304  * 	The caller must free() the string.  In cases with multiple
305  * 	entries (auto-trust-anchor-file), a newline delimited list is
306  * 	returned in the string.
307  * @return 0 if OK else an error code (malloc failure, syntax error).
308  */
309 int ub_ctx_get_option(struct ub_ctx* ctx, const char* opt, char** str);
310 
311 /**
312  * setup configuration for the given context.
313  * @param ctx: context.
314  * @param fname: unbound config file (not all settings applicable).
315  * 	This is a power-users interface that lets you specify all sorts
316  * 	of options.
317  * 	For some specific options, such as adding trust anchors, special
318  * 	routines exist.
319  * @return: 0 if OK, else error.
320  */
321 int ub_ctx_config(struct ub_ctx* ctx, const char* fname);
322 
323 /**
324  * Set machine to forward DNS queries to, the caching resolver to use.
325  * IP4 or IP6 address. Forwards all DNS requests to that machine, which
326  * is expected to run a recursive resolver. If the proxy is not
327  * DNSSEC-capable, validation may fail. Can be called several times, in
328  * that case the addresses are used as backup servers.
329  *
330  * To read the list of nameservers from /etc/resolv.conf (from DHCP or so),
331  * use the call ub_ctx_resolvconf.
332  *
333  * @param ctx: context.
334  *	At this time it is only possible to set configuration before the
335  *	first resolve is done.
336  * @param addr: address, IP4 or IP6 in string format.
337  * 	If the addr is NULL, forwarding is disabled.
338  * @return 0 if OK, else error.
339  */
340 int ub_ctx_set_fwd(struct ub_ctx* ctx, const char* addr);
341 
342 /**
343  * Use DNS over TLS to send queries to machines set with ub_ctx_set_fwd().
344  *
345  * @param ctx: context.
346  *	At this time it is only possible to set configuration before the
347  *	first resolve is done.
348  * @param tls: enable or disable DNS over TLS
349  * @return 0 if OK, else error.
350  */
351 int ub_ctx_set_tls(struct ub_ctx* ctx, int tls);
352 
353 /**
354  * Add a stub zone, with given address to send to.  This is for custom
355  * root hints or pointing to a local authoritative dns server.
356  * For dns resolvers and the 'DHCP DNS' ip address, use ub_ctx_set_fwd.
357  * This is similar to a stub-zone entry in unbound.conf.
358  *
359  * @param ctx: context.
360  *	It is only possible to set configuration before the
361  *	first resolve is done.
362  * @param zone: name of the zone, string.
363  * @param addr: address, IP4 or IP6 in string format.
364  * 	The addr is added to the list of stub-addresses if the entry exists.
365  * 	If the addr is NULL the stub entry is removed.
366  * @param isprime: set to true to set stub-prime to yes for the stub.
367  * 	For local authoritative servers, people usually set it to false,
368  * 	For root hints it should be set to true.
369  * @return 0 if OK, else error.
370  */
371 int ub_ctx_set_stub(struct ub_ctx* ctx, const char* zone, const char* addr,
372 	int isprime);
373 
374 /**
375  * Read list of nameservers to use from the filename given.
376  * Usually "/etc/resolv.conf". Uses those nameservers as caching proxies.
377  * If they do not support DNSSEC, validation may fail.
378  *
379  * Only nameservers are picked up, the searchdomain, ndots and other
380  * settings from resolv.conf(5) are ignored.
381  *
382  * @param ctx: context.
383  *	At this time it is only possible to set configuration before the
384  *	first resolve is done.
385  * @param fname: file name string. If NULL "/etc/resolv.conf" is used.
386  * @return 0 if OK, else error.
387  */
388 int ub_ctx_resolvconf(struct ub_ctx* ctx, const char* fname);
389 
390 /**
391  * Read list of hosts from the filename given.
392  * Usually "/etc/hosts".
393  * These addresses are not flagged as DNSSEC secure when queried for.
394  *
395  * @param ctx: context.
396  *	At this time it is only possible to set configuration before the
397  *	first resolve is done.
398  * @param fname: file name string. If NULL "/etc/hosts" is used.
399  * @return 0 if OK, else error.
400  */
401 int ub_ctx_hosts(struct ub_ctx* ctx, const char* fname);
402 
403 /**
404  * Add a trust anchor to the given context.
405  * The trust anchor is a string, on one line, that holds a valid DNSKEY or
406  * DS RR.
407  * @param ctx: context.
408  *	At this time it is only possible to add trusted keys before the
409  *	first resolve is done.
410  * @param ta: string, with zone-format RR on one line.
411  * 	[domainname] [TTL optional] [type] [class optional] [rdata contents]
412  * @return 0 if OK, else error.
413  */
414 int ub_ctx_add_ta(struct ub_ctx* ctx, const char* ta);
415 
416 /**
417  * Add trust anchors to the given context.
418  * Pass name of a file with DS and DNSKEY records (like from dig or drill).
419  * @param ctx: context.
420  *	At this time it is only possible to add trusted keys before the
421  *	first resolve is done.
422  * @param fname: filename of file with keyfile with trust anchors.
423  * @return 0 if OK, else error.
424  */
425 int ub_ctx_add_ta_file(struct ub_ctx* ctx, const char* fname);
426 
427 /**
428  * Add trust anchor to the given context that is tracked with RFC5011
429  * automated trust anchor maintenance.  The file is written to when the
430  * trust anchor is changed.
431  * Pass the name of a file that was output from eg. unbound-anchor,
432  * or you can start it by providing a trusted DNSKEY or DS record on one
433  * line in the file.
434  * @param ctx: context.
435  *	At this time it is only possible to add trusted keys before the
436  *	first resolve is done.
437  * @param fname: filename of file with trust anchor.
438  * @return 0 if OK, else error.
439  */
440 int ub_ctx_add_ta_autr(struct ub_ctx* ctx, const char* fname);
441 
442 /**
443  * Add trust anchors to the given context.
444  * Pass the name of a bind-style config file with trusted-keys{}.
445  * @param ctx: context.
446  *	At this time it is only possible to add trusted keys before the
447  *	first resolve is done.
448  * @param fname: filename of file with bind-style config entries with trust
449  * 	anchors.
450  * @return 0 if OK, else error.
451  */
452 int ub_ctx_trustedkeys(struct ub_ctx* ctx, const char* fname);
453 
454 /**
455  * Set debug output (and error output) to the specified stream.
456  * Pass NULL to disable. Default is stderr.
457  * @param ctx: context.
458  * @param out: FILE* out file stream to log to.
459  * 	Type void* to avoid stdio dependency of this header file.
460  * @return 0 if OK, else error.
461  */
462 int ub_ctx_debugout(struct ub_ctx* ctx, void* out);
463 
464 /**
465  * Set debug verbosity for the context
466  * Output is directed to stderr.
467  * @param ctx: context.
468  * @param d: debug level, 0 is off, 1 is very minimal, 2 is detailed,
469  *	and 3 is lots.
470  * @return 0 if OK, else error.
471  */
472 int ub_ctx_debuglevel(struct ub_ctx* ctx, int d);
473 
474 /**
475  * Set a context behaviour for asynchronous action.
476  * @param ctx: context.
477  * @param dothread: if true, enables threading and a call to resolve_async()
478  *	creates a thread to handle work in the background.
479  *	If false, a process is forked to handle work in the background.
480  *	Changes to this setting after async() calls have been made have
481  *	no effect (delete and re-create the context to change).
482  * @return 0 if OK, else error.
483  */
484 int ub_ctx_async(struct ub_ctx* ctx, int dothread);
485 
486 /**
487  * Poll a context to see if it has any new results
488  * Do not poll in a loop, instead extract the fd below to poll for readiness,
489  * and then check, or wait using the wait routine.
490  * @param ctx: context.
491  * @return: 0 if nothing to read, or nonzero if a result is available.
492  * 	If nonzero, call ctx_process() to do callbacks.
493  */
494 int ub_poll(struct ub_ctx* ctx);
495 
496 /**
497  * Wait for a context to finish with results. Calls ub_process() after
498  * the wait for you. After the wait, there are no more outstanding
499  * asynchronous queries.
500  * @param ctx: context.
501  * @return: 0 if OK, else error.
502  */
503 int ub_wait(struct ub_ctx* ctx);
504 
505 /**
506  * Get file descriptor. Wait for it to become readable, at this point
507  * answers are returned from the asynchronous validating resolver.
508  * Then call the ub_process to continue processing.
509  * This routine works immediately after context creation, the fd
510  * does not change.
511  * @param ctx: context.
512  * @return: -1 on error, or file descriptor to use select(2) with.
513  */
514 int ub_fd(struct ub_ctx* ctx);
515 
516 /**
517  * Call this routine to continue processing results from the validating
518  * resolver (when the fd becomes readable).
519  * Will perform necessary callbacks.
520  * @param ctx: context
521  * @return: 0 if OK, else error.
522  */
523 int ub_process(struct ub_ctx* ctx);
524 
525 /**
526  * Perform resolution and validation of the target name.
527  * @param ctx: context.
528  *	The context is finalized, and can no longer accept config changes.
529  * @param name: domain name in text format (a zero terminated text string).
530  * @param rrtype: type of RR in host order, 1 is A (address).
531  * @param rrclass: class of RR in host order, 1 is IN (for internet).
532  * @param result: the result data is returned in a newly allocated result
533  * 	structure. May be NULL on return, return value is set to an error
534  * 	in that case (out of memory).
535  * @return 0 if OK, else error.
536  */
537 int ub_resolve(struct ub_ctx* ctx, const char* name, int rrtype,
538 	int rrclass, struct ub_result** result);
539 
540 /**
541  * Perform resolution and validation of the target name.
542  * Asynchronous, after a while, the callback will be called with your
543  * data and the result.
544  * @param ctx: context.
545  *	If no thread or process has been created yet to perform the
546  *	work in the background, it is created now.
547  *	The context is finalized, and can no longer accept config changes.
548  * @param name: domain name in text format (a string).
549  * @param rrtype: type of RR in host order, 1 is A.
550  * @param rrclass: class of RR in host order, 1 is IN (for internet).
551  * @param mydata: this data is your own data (you can pass NULL),
552  * 	and is passed on to the callback function.
553  * @param callback: this is called on completion of the resolution.
554  * 	It is called as:
555  * 	void callback(void* mydata, int err, struct ub_result* result)
556  * 	with mydata: the same as passed here, you may pass NULL,
557  * 	with err: is 0 when a result has been found.
558  * 	with result: a newly allocated result structure.
559  *		The result may be NULL, in that case err is set.
560  *
561  * 	If an error happens during processing, your callback will be called
562  * 	with error set to a nonzero value (and result==NULL).
563  * @param async_id: if you pass a non-NULL value, an identifier number is
564  *	returned for the query as it is in progress. It can be used to
565  *	cancel the query.
566  * @return 0 if OK, else error.
567  */
568 int ub_resolve_async(struct ub_ctx* ctx, const char* name, int rrtype,
569 	int rrclass, void* mydata, ub_callback_type callback, int* async_id);
570 
571 /**
572  * Cancel an async query in progress.
573  * Its callback will not be called.
574  *
575  * @param ctx: context.
576  * @param async_id: which query to cancel.
577  * @return 0 if OK, else error.
578  * This routine can return an error if the async_id passed does not exist
579  * or has already been delivered. If another thread is processing results
580  * at the same time, the result may be delivered at the same time and the
581  * cancel fails with an error.  Also the cancel can fail due to a system
582  * error, no memory or socket failures.
583  */
584 int ub_cancel(struct ub_ctx* ctx, int async_id);
585 
586 /**
587  * Free storage associated with a result structure.
588  * @param result: to free
589  */
590 void ub_resolve_free(struct ub_result* result);
591 
592 /**
593  * Convert error value to a human readable string.
594  * @param err: error code from one of the libunbound functions.
595  * 	The error codes are from the type enum ub_ctx_err.
596  * @return pointer to constant text string, zero terminated.
597  */
598 const char* ub_strerror(int err);
599 
600 /**
601  * Debug routine.  Print the local zone information to debug output.
602  * @param ctx: context.  Is finalized by the routine.
603  * @return 0 if OK, else error.
604  */
605 int ub_ctx_print_local_zones(struct ub_ctx* ctx);
606 
607 /**
608  * Add a new zone with the zonetype to the local authority info of the
609  * library.
610  * @param ctx: context.  Is finalized by the routine.
611  * @param zone_name: name of the zone in text, "example.com"
612  *	If it already exists, the type is updated.
613  * @param zone_type: type of the zone (like for unbound.conf) in text.
614  * @return 0 if OK, else error.
615  */
616 int ub_ctx_zone_add(struct ub_ctx* ctx, const char *zone_name,
617 	const char *zone_type);
618 
619 /**
620  * Remove zone from local authority info of the library.
621  * @param ctx: context.  Is finalized by the routine.
622  * @param zone_name: name of the zone in text, "example.com"
623  *	If it does not exist, nothing happens.
624  * @return 0 if OK, else error.
625  */
626 int ub_ctx_zone_remove(struct ub_ctx* ctx, const char *zone_name);
627 
628 /**
629  * Add localdata to the library local authority info.
630  * Similar to local-data config statement.
631  * @param ctx: context.  Is finalized by the routine.
632  * @param data: the resource record in text format, for example
633  *	"www.example.com IN A 127.0.0.1"
634  * @return 0 if OK, else error.
635  */
636 int ub_ctx_data_add(struct ub_ctx* ctx, const char *data);
637 
638 /**
639  * Remove localdata from the library local authority info.
640  * @param ctx: context.  Is finalized by the routine.
641  * @param data: the name to delete all data from, like "www.example.com".
642  * @return 0 if OK, else error.
643  */
644 int ub_ctx_data_remove(struct ub_ctx* ctx, const char *data);
645 
646 /**
647  * Get a version string from the libunbound implementation.
648  * @return a static constant string with the version number.
649  */
650 const char* ub_version(void);
651 
652 /**
653  * Some global statistics that are not in struct stats_info,
654  * this struct is shared on a shm segment (shm-key in unbound.conf)
655  */
656 struct ub_shm_stat_info {
657 	int num_threads;
658 
659 	struct {
660 		long long now_sec, now_usec;
661 		long long up_sec, up_usec;
662 		long long elapsed_sec, elapsed_usec;
663 	} time;
664 
665 	struct {
666 		long long msg;
667 		long long rrset;
668 		long long val;
669 		long long iter;
670 		long long subnet;
671 		long long ipsecmod;
672 		long long respip;
673 		long long dnscrypt_shared_secret;
674 		long long dnscrypt_nonce;
675 		long long dynlib;
676 	} mem;
677 };
678 
679 /** number of qtype that is stored for in array */
680 #define UB_STATS_QTYPE_NUM 256
681 /** number of qclass that is stored for in array */
682 #define UB_STATS_QCLASS_NUM 256
683 /** number of rcodes in stats */
684 #define UB_STATS_RCODE_NUM 16
685 /** number of opcodes in stats */
686 #define UB_STATS_OPCODE_NUM 16
687 /** number of histogram buckets */
688 #define UB_STATS_BUCKET_NUM 40
689 /** number of RPZ actions */
690 #define UB_STATS_RPZ_ACTION_NUM 10
691 
692 /** per worker statistics. */
693 struct ub_server_stats {
694 	/** number of queries from clients received. */
695 	long long num_queries;
696 	/** number of queries that have been dropped/ratelimited by ip. */
697 	long long num_queries_ip_ratelimited;
698 	/** number of queries with a valid DNS Cookie. */
699 	long long num_queries_cookie_valid;
700 	/** number of queries with only the client part of the DNS Cookie. */
701 	long long num_queries_cookie_client;
702 	/** number of queries with invalid DNS Cookie. */
703 	long long num_queries_cookie_invalid;
704 	/** number of queries that had a cache-miss. */
705 	long long num_queries_missed_cache;
706 	/** number of prefetch queries - cachehits with prefetch */
707 	long long num_queries_prefetch;
708 	/** number of queries which are too late to process */
709 	long long num_queries_timed_out;
710 	/** the longest wait time in the queue */
711 	long long max_query_time_us;
712 	/**
713 	 * Sum of the querylistsize of the worker for
714 	 * every query that missed cache. To calculate average.
715 	 */
716 	long long sum_query_list_size;
717 	/** max value of query list size reached. */
718 	long long max_query_list_size;
719 
720 	/** Extended stats below (bool) */
721 	int extended;
722 
723 	/** qtype stats */
724 	long long qtype[UB_STATS_QTYPE_NUM];
725 	/** bigger qtype values not in array */
726 	long long qtype_big;
727 	/** qclass stats */
728 	long long qclass[UB_STATS_QCLASS_NUM];
729 	/** bigger qclass values not in array */
730 	long long qclass_big;
731 	/** query opcodes */
732 	long long qopcode[UB_STATS_OPCODE_NUM];
733 	/** number of queries over TCP */
734 	long long qtcp;
735 	/** number of outgoing queries over TCP */
736 	long long qtcp_outgoing;
737 	/** number of outgoing queries over UDP */
738 	long long qudp_outgoing;
739 	/** number of queries over (DNS over) TLS */
740 	long long qtls;
741 	/** number of queries over (DNS over) HTTPS */
742 	long long qhttps;
743 	/** number of queries over IPv6 */
744 	long long qipv6;
745 	/** number of queries with QR bit */
746 	long long qbit_QR;
747 	/** number of queries with AA bit */
748 	long long qbit_AA;
749 	/** number of queries with TC bit */
750 	long long qbit_TC;
751 	/** number of queries with RD bit */
752 	long long qbit_RD;
753 	/** number of queries with RA bit */
754 	long long qbit_RA;
755 	/** number of queries with Z bit */
756 	long long qbit_Z;
757 	/** number of queries with AD bit */
758 	long long qbit_AD;
759 	/** number of queries with CD bit */
760 	long long qbit_CD;
761 	/** number of queries with EDNS OPT record */
762 	long long qEDNS;
763 	/** number of queries with EDNS with DO flag */
764 	long long qEDNS_DO;
765 	/** answer rcodes */
766 	long long ans_rcode[UB_STATS_RCODE_NUM];
767 	/** answers with pseudo rcode 'nodata' */
768 	long long ans_rcode_nodata;
769 	/** answers that were secure (AD) */
770 	long long ans_secure;
771 	/** answers that were bogus (withheld as SERVFAIL) */
772 	long long ans_bogus;
773 	/** rrsets marked bogus by validator */
774 	long long rrset_bogus;
775 	/** number of queries that have been ratelimited by domain recursion. */
776 	long long queries_ratelimited;
777 	/** unwanted traffic received on server-facing ports */
778 	long long unwanted_replies;
779 	/** unwanted traffic received on client-facing ports */
780 	long long unwanted_queries;
781 	/** usage of tcp accept list */
782 	long long tcp_accept_usage;
783 	/** expired answers served from cache */
784 	long long ans_expired;
785 	/** histogram data exported to array
786 	 * if the array is the same size, no data is lost, and
787 	 * if all histograms are same size (is so by default) then
788 	 * adding up works well. */
789 	long long hist[UB_STATS_BUCKET_NUM];
790 
791 	/** number of message cache entries */
792 	long long msg_cache_count;
793 	/** number of rrset cache entries */
794 	long long rrset_cache_count;
795 	/** number of infra cache entries */
796 	long long infra_cache_count;
797 	/** number of key cache entries */
798 	long long key_cache_count;
799 
800 	/** maximum number of collisions in the msg cache */
801 	long long msg_cache_max_collisions;
802 	/** maximum number of collisions in the rrset cache */
803 	long long rrset_cache_max_collisions;
804 
805 	/** number of queries that used dnscrypt */
806 	long long num_query_dnscrypt_crypted;
807 	/** number of queries that queried dnscrypt certificates */
808 	long long num_query_dnscrypt_cert;
809 	/** number of queries in clear text and not asking for the certificates */
810 	long long num_query_dnscrypt_cleartext;
811 	/** number of malformed encrypted queries */
812 	long long num_query_dnscrypt_crypted_malformed;
813 	/** number of queries which did not have a shared secret in cache */
814 	long long num_query_dnscrypt_secret_missed_cache;
815 	/** number of dnscrypt shared secret cache entries */
816 	long long shared_secret_cache_count;
817 	/** number of queries which are replays */
818 	long long num_query_dnscrypt_replay;
819 	/** number of dnscrypt nonces cache entries */
820 	long long nonce_cache_count;
821 	/** number of queries for unbound's auth_zones, upstream query */
822 	long long num_query_authzone_up;
823 	/** number of queries for unbound's auth_zones, downstream answers */
824 	long long num_query_authzone_down;
825 	/** number of times neg cache records were used to generate NOERROR
826 	 * responses. */
827 	long long num_neg_cache_noerror;
828 	/** number of times neg cache records were used to generate NXDOMAIN
829 	 * responses. */
830 	long long num_neg_cache_nxdomain;
831 	/** number of queries answered from edns-subnet specific data */
832 	long long num_query_subnet;
833 	/** number of queries answered from edns-subnet specific data, and
834 	 * the answer was from the edns-subnet cache. */
835 	long long num_query_subnet_cache;
836 	/** number of queries served from cachedb */
837 	long long num_query_cachedb;
838 	/** number of bytes in the stream wait buffers */
839 	long long mem_stream_wait;
840 	/** number of bytes in the HTTP2 query buffers */
841 	long long mem_http2_query_buffer;
842 	/** number of bytes in the HTTP2 response buffers */
843 	long long mem_http2_response_buffer;
844 	/** number of TLS connection resume */
845 	long long qtls_resume;
846 	/** RPZ action stats */
847 	long long rpz_action[UB_STATS_RPZ_ACTION_NUM];
848 	/** number of bytes in QUIC buffers */
849 	long long mem_quic;
850 	/** number of queries over (DNS over) QUIC */
851 	long long qquic;
852 };
853 
854 /**
855  * Statistics to send over the control pipe when asked
856  * This struct is made to be memcopied, sent in binary.
857  * shm mapped with (number+1) at num_threads+1, with first as total
858  */
859 struct ub_stats_info {
860 	/** the thread stats */
861 	struct ub_server_stats svr;
862 
863 	/** mesh stats: current number of states */
864 	long long mesh_num_states;
865 	/** mesh stats: current number of reply (user) states */
866 	long long mesh_num_reply_states;
867 	/** mesh stats: number of reply states overwritten with a new one */
868 	long long mesh_jostled;
869 	/** mesh stats: number of incoming queries dropped */
870 	long long mesh_dropped;
871 	/** mesh stats: replies sent */
872 	long long mesh_replies_sent;
873 	/** mesh stats: sum of waiting times for the replies */
874 	long long mesh_replies_sum_wait_sec, mesh_replies_sum_wait_usec;
875 	/** mesh stats: median of waiting times for replies (in sec) */
876 	double mesh_time_median;
877 };
878 
879 #ifdef __cplusplus
880 }
881 #endif
882 
883 #endif /* UB_UNBOUND_H */
884