contrib/unbound/libunbound/unbound.h

   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 };
 849
 850 /**
 851  * Statistics to send over the control pipe when asked
 852  * This struct is made to be memcopied, sent in binary.
 853  * shm mapped with (number+1) at num_threads+1, with first as total
 854  */
 855 struct ub_stats_info {
 856         /** the thread stats */
 857         struct ub_server_stats svr;
 858
 859         /** mesh stats: current number of states */
 860         long long mesh_num_states;
 861         /** mesh stats: current number of reply (user) states */
 862         long long mesh_num_reply_states;
 863         /** mesh stats: number of reply states overwritten with a new one */
 864         long long mesh_jostled;
 865         /** mesh stats: number of incoming queries dropped */
 866         long long mesh_dropped;
 867         /** mesh stats: replies sent */
 868         long long mesh_replies_sent;
 869         /** mesh stats: sum of waiting times for the replies */
 870         long long mesh_replies_sum_wait_sec, mesh_replies_sum_wait_usec;
 871         /** mesh stats: median of waiting times for replies (in sec) */
 872         double mesh_time_median;
 873 };
 874
 875 #ifdef __cplusplus
 876 }
 877 #endif
 878
 879 #endif /* UB_UNBOUND_H */