contrib/bind9/lib/dns/include/dns/resolver.h

   1 /*
   2  * Copyright (C) 2004-2012  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2001, 2003  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and/or distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id$ */
  19
  20 #ifndef DNS_RESOLVER_H
  21 #define DNS_RESOLVER_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file dns/resolver.h
  28  *
  29  * \brief
  30  * This is the BIND 9 resolver, the module responsible for resolving DNS
  31  * requests by iteratively querying authoritative servers and following
  32  * referrals.  This is a "full resolver", not to be confused with
  33  * the stub resolvers most people associate with the word "resolver".
  34  * The full resolver is part of the caching name server or resolver
  35  * daemon the stub resolver talks to.
  36  *
  37  * MP:
  38  *\li   The module ensures appropriate synchronization of data structures it
  39  *      creates and manipulates.
  40  *
  41  * Reliability:
  42  *\li   No anticipated impact.
  43  *
  44  * Resources:
  45  *\li   TBS
  46  *
  47  * Security:
  48  *\li   No anticipated impact.
  49  *
  50  * Standards:
  51  *\li   RFCs:   1034, 1035, 2181, TBS
  52  *\li   Drafts: TBS
  53  */
  54
  55 #include <isc/lang.h>
  56 #include <isc/socket.h>
  57
  58 #include <dns/types.h>
  59 #include <dns/fixedname.h>
  60
  61 ISC_LANG_BEGINDECLS
  62
  63 /*%
  64  * A dns_fetchevent_t is sent when a 'fetch' completes.  Any of 'db',
  65  * 'node', 'rdataset', and 'sigrdataset' may be bound.  It is the
  66  * receiver's responsibility to detach before freeing the event.
  67  * \brief
  68  * 'rdataset', 'sigrdataset', 'client' and 'id' are the values that were
  69  * supplied when dns_resolver_createfetch() was called.  They are returned
  70  *  to the caller so that they may be freed.
  71  */
  72 typedef struct dns_fetchevent {
  73         ISC_EVENT_COMMON(struct dns_fetchevent);
  74         dns_fetch_t *                   fetch;
  75         isc_result_t                    result;
  76         dns_rdatatype_t                 qtype;
  77         dns_db_t *                      db;
  78         dns_dbnode_t *                  node;
  79         dns_rdataset_t *                rdataset;
  80         dns_rdataset_t *                sigrdataset;
  81         dns_fixedname_t                 foundname;
  82         isc_sockaddr_t *                client;
  83         dns_messageid_t                 id;
  84         isc_result_t                    vresult;
  85 } dns_fetchevent_t;
  86
  87 /*
  88  * Options that modify how a 'fetch' is done.
  89  */
  90 #define DNS_FETCHOPT_TCP                0x01         /*%< Use TCP. */
  91 #define DNS_FETCHOPT_UNSHARED           0x02         /*%< See below. */
  92 #define DNS_FETCHOPT_RECURSIVE          0x04         /*%< Set RD? */
  93 #define DNS_FETCHOPT_NOEDNS0            0x08         /*%< Do not use EDNS. */
  94 #define DNS_FETCHOPT_FORWARDONLY        0x10         /*%< Only use forwarders. */
  95 #define DNS_FETCHOPT_NOVALIDATE         0x20         /*%< Disable validation. */
  96 #define DNS_FETCHOPT_EDNS512            0x40         /*%< Advertise a 512 byte
  97                                                           UDP buffer. */
  98 #define DNS_FETCHOPT_WANTNSID           0x80         /*%< Request NSID */
  99
 100 #define DNS_FETCHOPT_EDNSVERSIONSET     0x00800000
 101 #define DNS_FETCHOPT_EDNSVERSIONMASK    0xff000000
 102 #define DNS_FETCHOPT_EDNSVERSIONSHIFT   24
 103
 104 /*
 105  * Upper bounds of class of query RTT (ms).  Corresponds to
 106  * dns_resstatscounter_queryrttX statistics counters.
 107  */
 108 #define DNS_RESOLVER_QRYRTTCLASS0       10
 109 #define DNS_RESOLVER_QRYRTTCLASS0STR    "10"
 110 #define DNS_RESOLVER_QRYRTTCLASS1       100
 111 #define DNS_RESOLVER_QRYRTTCLASS1STR    "100"
 112 #define DNS_RESOLVER_QRYRTTCLASS2       500
 113 #define DNS_RESOLVER_QRYRTTCLASS2STR    "500"
 114 #define DNS_RESOLVER_QRYRTTCLASS3       800
 115 #define DNS_RESOLVER_QRYRTTCLASS3STR    "800"
 116 #define DNS_RESOLVER_QRYRTTCLASS4       1600
 117 #define DNS_RESOLVER_QRYRTTCLASS4STR    "1600"
 118
 119 /*
 120  * XXXRTH  Should this API be made semi-private?  (I.e.
 121  * _dns_resolver_create()).
 122  */
 123
 124 #define DNS_RESOLVER_CHECKNAMES         0x01
 125 #define DNS_RESOLVER_CHECKNAMESFAIL     0x02
 126
 127 isc_result_t
 128 dns_resolver_create(dns_view_t *view,
 129                     isc_taskmgr_t *taskmgr, unsigned int ntasks,
 130                     isc_socketmgr_t *socketmgr,
 131                     isc_timermgr_t *timermgr,
 132                     unsigned int options,
 133                     dns_dispatchmgr_t *dispatchmgr,
 134                     dns_dispatch_t *dispatchv4,
 135                     dns_dispatch_t *dispatchv6,
 136                     dns_resolver_t **resp);
 137
 138 /*%<
 139  * Create a resolver.
 140  *
 141  * Notes:
 142  *
 143  *\li   Generally, applications should not create a resolver directly, but
 144  *      should instead call dns_view_createresolver().
 145  *
 146  * Requires:
 147  *
 148  *\li   'view' is a valid view.
 149  *
 150  *\li   'taskmgr' is a valid task manager.
 151  *
 152  *\li   'ntasks' > 0.
 153  *
 154  *\li   'socketmgr' is a valid socket manager.
 155  *
 156  *\li   'timermgr' is a valid timer manager.
 157  *
 158  *\li   'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL.
 159  *
 160  *\li   'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.
 161  *
 162  *\li   resp != NULL && *resp == NULL.
 163  *
 164  * Returns:
 165  *
 166  *\li   #ISC_R_SUCCESS                          On success.
 167  *
 168  *\li   Anything else                           Failure.
 169  */
 170
 171 void
 172 dns_resolver_freeze(dns_resolver_t *res);
 173 /*%<
 174  * Freeze resolver.
 175  *
 176  * Notes:
 177  *
 178  *\li   Certain configuration changes cannot be made after the resolver
 179  *      is frozen.  Fetches cannot be created until the resolver is frozen.
 180  *
 181  * Requires:
 182  *
 183  *\li   'res' is a valid resolver.
 184  *
 185  * Ensures:
 186  *
 187  *\li   'res' is frozen.
 188  */
 189
 190 void
 191 dns_resolver_prime(dns_resolver_t *res);
 192 /*%<
 193  * Prime resolver.
 194  *
 195  * Notes:
 196  *
 197  *\li   Resolvers which have a forwarding policy other than dns_fwdpolicy_only
 198  *      need to be primed with the root nameservers, otherwise the root
 199  *      nameserver hints data may be used indefinitely.  This function requests
 200  *      that the resolver start a priming fetch, if it isn't already priming.
 201  *
 202  * Requires:
 203  *
 204  *\li   'res' is a valid, frozen resolver.
 205  */
 206
 207
 208 void
 209 dns_resolver_whenshutdown(dns_resolver_t *res, isc_task_t *task,
 210                           isc_event_t **eventp);
 211 /*%<
 212  * Send '*eventp' to 'task' when 'res' has completed shutdown.
 213  *
 214  * Notes:
 215  *
 216  *\li   It is not safe to detach the last reference to 'res' until
 217  *      shutdown is complete.
 218  *
 219  * Requires:
 220  *
 221  *\li   'res' is a valid resolver.
 222  *
 223  *\li   'task' is a valid task.
 224  *
 225  *\li   *eventp is a valid event.
 226  *
 227  * Ensures:
 228  *
 229  *\li   *eventp == NULL.
 230  */
 231
 232 void
 233 dns_resolver_shutdown(dns_resolver_t *res);
 234 /*%<
 235  * Start the shutdown process for 'res'.
 236  *
 237  * Notes:
 238  *
 239  *\li   This call has no effect if the resolver is already shutting down.
 240  *
 241  * Requires:
 242  *
 243  *\li   'res' is a valid resolver.
 244  */
 245
 246 void
 247 dns_resolver_attach(dns_resolver_t *source, dns_resolver_t **targetp);
 248
 249 void
 250 dns_resolver_detach(dns_resolver_t **resp);
 251
 252 isc_result_t
 253 dns_resolver_createfetch(dns_resolver_t *res, dns_name_t *name,
 254                          dns_rdatatype_t type,
 255                          dns_name_t *domain, dns_rdataset_t *nameservers,
 256                          dns_forwarders_t *forwarders,
 257                          unsigned int options, isc_task_t *task,
 258                          isc_taskaction_t action, void *arg,
 259                          dns_rdataset_t *rdataset,
 260                          dns_rdataset_t *sigrdataset,
 261                          dns_fetch_t **fetchp);
 262
 263 isc_result_t
 264 dns_resolver_createfetch2(dns_resolver_t *res, dns_name_t *name,
 265                           dns_rdatatype_t type,
 266                           dns_name_t *domain, dns_rdataset_t *nameservers,
 267                           dns_forwarders_t *forwarders,
 268                           isc_sockaddr_t *client, isc_uint16_t id,
 269                           unsigned int options, isc_task_t *task,
 270                           isc_taskaction_t action, void *arg,
 271                           dns_rdataset_t *rdataset,
 272                           dns_rdataset_t *sigrdataset,
 273                           dns_fetch_t **fetchp);
 274 isc_result_t
 275 dns_resolver_createfetch3(dns_resolver_t *res, dns_name_t *name,
 276                           dns_rdatatype_t type,
 277                           dns_name_t *domain, dns_rdataset_t *nameservers,
 278                           dns_forwarders_t *forwarders,
 279                           isc_sockaddr_t *client, isc_uint16_t id,
 280                           unsigned int options, unsigned int depth,
 281                           isc_counter_t *qc, isc_task_t *task,
 282                           isc_taskaction_t action, void *arg,
 283                           dns_rdataset_t *rdataset,
 284                           dns_rdataset_t *sigrdataset,
 285                           dns_fetch_t **fetchp);
 286 /*%<
 287  * Recurse to answer a question.
 288  *
 289  * Notes:
 290  *
 291  *\li   This call starts a query for 'name', type 'type'.
 292  *
 293  *\li   The 'domain' is a parent domain of 'name' for which
 294  *      a set of name servers 'nameservers' is known.  If no
 295  *      such name server information is available, set
 296  *      'domain' and 'nameservers' to NULL.
 297  *
 298  *\li   'forwarders' is unimplemented, and subject to change when
 299  *      we figure out how selective forwarding will work.
 300  *
 301  *\li   When the fetch completes (successfully or otherwise), a
 302  *      #DNS_EVENT_FETCHDONE event with action 'action' and arg 'arg' will be
 303  *      posted to 'task'.
 304  *
 305  *\li   The values of 'rdataset' and 'sigrdataset' will be returned in
 306  *      the FETCHDONE event.
 307  *
 308  *\li   'client' and 'id' are used for duplicate query detection.  '*client'
 309  *      must remain stable until after 'action' has been called or
 310  *      dns_resolver_cancelfetch() is called.
 311  *
 312  * Requires:
 313  *
 314  *\li   'res' is a valid resolver that has been frozen.
 315  *
 316  *\li   'name' is a valid name.
 317  *
 318  *\li   'type' is not a meta type other than ANY.
 319  *
 320  *\li   'domain' is a valid name or NULL.
 321  *
 322  *\li   'nameservers' is a valid NS rdataset (whose owner name is 'domain')
 323  *      iff. 'domain' is not NULL.
 324  *
 325  *\li   'forwarders' is NULL.
 326  *
 327  *\li   'client' is a valid sockaddr or NULL.
 328  *
 329  *\li   'options' contains valid options.
 330  *
 331  *\li   'rdataset' is a valid, disassociated rdataset.
 332  *
 333  *\li   'sigrdataset' is NULL, or is a valid, disassociated rdataset.
 334  *
 335  *\li   fetchp != NULL && *fetchp == NULL.
 336  *
 337  * Returns:
 338  *
 339  *\li   #ISC_R_SUCCESS                                  Success
 340  *\li   #DNS_R_DUPLICATE
 341  *\li   #DNS_R_DROP
 342  *
 343  *\li   Many other values are possible, all of which indicate failure.
 344  */
 345
 346 void
 347 dns_resolver_cancelfetch(dns_fetch_t *fetch);
 348 /*%<
 349  * Cancel 'fetch'.
 350  *
 351  * Notes:
 352  *
 353  *\li   If 'fetch' has not completed, post its FETCHDONE event with a
 354  *      result code of #ISC_R_CANCELED.
 355  *
 356  * Requires:
 357  *
 358  *\li   'fetch' is a valid fetch.
 359  */
 360
 361 void
 362 dns_resolver_destroyfetch(dns_fetch_t **fetchp);
 363 /*%<
 364  * Destroy 'fetch'.
 365  *
 366  * Requires:
 367  *
 368  *\li   '*fetchp' is a valid fetch.
 369  *
 370  *\li   The caller has received the FETCHDONE event (either because the
 371  *      fetch completed or because dns_resolver_cancelfetch() was called).
 372  *
 373  * Ensures:
 374  *
 375  *\li   *fetchp == NULL.
 376  */
 377
 378 void
 379 dns_resolver_logfetch(dns_fetch_t *fetch, isc_log_t *lctx,
 380                       isc_logcategory_t *category, isc_logmodule_t *module,
 381                       int level, isc_boolean_t duplicateok);
 382 /*%<
 383  * Dump a log message on internal state at the completion of given 'fetch'.
 384  * 'lctx', 'category', 'module', and 'level' are used to write the log message.
 385  * By default, only one log message is written even if the corresponding fetch
 386  * context serves multiple clients; if 'duplicateok' is true the suppression
 387  * is disabled and the message can be written every time this function is
 388  * called.
 389  *
 390  * Requires:
 391  *
 392  *\li   'fetch' is a valid fetch, and has completed.
 393  */
 394
 395 dns_dispatchmgr_t *
 396 dns_resolver_dispatchmgr(dns_resolver_t *resolver);
 397
 398 dns_dispatch_t *
 399 dns_resolver_dispatchv4(dns_resolver_t *resolver);
 400
 401 dns_dispatch_t *
 402 dns_resolver_dispatchv6(dns_resolver_t *resolver);
 403
 404 isc_socketmgr_t *
 405 dns_resolver_socketmgr(dns_resolver_t *resolver);
 406
 407 isc_taskmgr_t *
 408 dns_resolver_taskmgr(dns_resolver_t *resolver);
 409
 410 isc_uint32_t
 411 dns_resolver_getlamettl(dns_resolver_t *resolver);
 412 /*%<
 413  * Get the resolver's lame-ttl.  zero => no lame processing.
 414  *
 415  * Requires:
 416  *\li   'resolver' to be valid.
 417  */
 418
 419 void
 420 dns_resolver_setlamettl(dns_resolver_t *resolver, isc_uint32_t lame_ttl);
 421 /*%<
 422  * Set the resolver's lame-ttl.  zero => no lame processing.
 423  *
 424  * Requires:
 425  *\li   'resolver' to be valid.
 426  */
 427
 428 unsigned int
 429 dns_resolver_nrunning(dns_resolver_t *resolver);
 430 /*%<
 431  * Return the number of currently running resolutions in this
 432  * resolver.  This is may be less than the number of outstanding
 433  * fetches due to multiple identical fetches, or more than the
 434  * number of of outstanding fetches due to the fact that resolution
 435  * can continue even though a fetch has been canceled.
 436  */
 437
 438 isc_result_t
 439 dns_resolver_addalternate(dns_resolver_t *resolver, isc_sockaddr_t *alt,
 440                           dns_name_t *name, in_port_t port);
 441 /*%<
 442  * Add alternate addresses to be tried in the event that the nameservers
 443  * for a zone are not available in the address families supported by the
 444  * operating system.
 445  *
 446  * Require:
 447  * \li  only one of 'name' or 'alt' to be valid.
 448  */
 449
 450 void
 451 dns_resolver_setudpsize(dns_resolver_t *resolver, isc_uint16_t udpsize);
 452 /*%<
 453  * Set the EDNS UDP buffer size advertised by the server.
 454  */
 455
 456 isc_uint16_t
 457 dns_resolver_getudpsize(dns_resolver_t *resolver);
 458 /*%<
 459  * Get the current EDNS UDP buffer size.
 460  */
 461
 462 void
 463 dns_resolver_reset_algorithms(dns_resolver_t *resolver);
 464 /*%<
 465  * Clear the disabled DNSSEC algorithms.
 466  */
 467
 468 isc_result_t
 469 dns_resolver_disable_algorithm(dns_resolver_t *resolver, dns_name_t *name,
 470                                unsigned int alg);
 471 /*%<
 472  * Mark the give DNSSEC algorithm as disabled and below 'name'.
 473  * Valid algorithms are less than 256.
 474  *
 475  * Returns:
 476  *\li   #ISC_R_SUCCESS
 477  *\li   #ISC_R_RANGE
 478  *\li   #ISC_R_NOMEMORY
 479  */
 480
 481 isc_boolean_t
 482 dns_resolver_algorithm_supported(dns_resolver_t *resolver, dns_name_t *name,
 483                                  unsigned int alg);
 484 /*%<
 485  * Check if the given algorithm is supported by this resolver.
 486  * This checks if the algorithm has been disabled via
 487  * dns_resolver_disable_algorithm() then the underlying
 488  * crypto libraries if not specifically disabled.
 489  */
 490
 491 isc_boolean_t
 492 dns_resolver_digest_supported(dns_resolver_t *resolver, unsigned int digest_type);
 493 /*%<
 494  * Is this digest type supported.
 495  */
 496
 497 void
 498 dns_resolver_resetmustbesecure(dns_resolver_t *resolver);
 499
 500 isc_result_t
 501 dns_resolver_setmustbesecure(dns_resolver_t *resolver, dns_name_t *name,
 502                              isc_boolean_t value);
 503
 504 isc_boolean_t
 505 dns_resolver_getmustbesecure(dns_resolver_t *resolver, dns_name_t *name);
 506
 507
 508 void
 509 dns_resolver_settimeout(dns_resolver_t *resolver, unsigned int seconds);
 510 /*%<
 511  * Set the length of time the resolver will work on a query, in seconds.
 512  *
 513  * If timeout is 0, the default timeout will be applied.
 514  *
 515  * Requires:
 516  * \li  resolver to be valid.
 517  */
 518
 519 unsigned int
 520 dns_resolver_gettimeout(dns_resolver_t *resolver);
 521 /*%<
 522  * Get the current length of time the resolver will work on a query, in seconds.
 523  *
 524  * Requires:
 525  * \li  resolver to be valid.
 526  */
 527
 528 void
 529 dns_resolver_setclientsperquery(dns_resolver_t *resolver,
 530                                 isc_uint32_t min, isc_uint32_t max);
 531
 532 void
 533 dns_resolver_getclientsperquery(dns_resolver_t *resolver, isc_uint32_t *cur,
 534                                 isc_uint32_t *min, isc_uint32_t *max);
 535
 536 isc_boolean_t
 537 dns_resolver_getzeronosoattl(dns_resolver_t *resolver);
 538
 539 void
 540 dns_resolver_setzeronosoattl(dns_resolver_t *resolver, isc_boolean_t state);
 541
 542 unsigned int
 543 dns_resolver_getoptions(dns_resolver_t *resolver);
 544
 545 void
 546 dns_resolver_addbadcache(dns_resolver_t *resolver, dns_name_t *name,
 547                          dns_rdatatype_t type, isc_time_t *expire);
 548 /*%<
 549  * Add a entry to the bad cache for <name,type> that will expire at 'expire'.
 550  *
 551  * Requires:
 552  * \li  resolver to be valid.
 553  * \li  name to be valid.
 554  */
 555
 556 isc_boolean_t
 557 dns_resolver_getbadcache(dns_resolver_t *resolver, dns_name_t *name,
 558                          dns_rdatatype_t type, isc_time_t *now);
 559 /*%<
 560  * Check to see if there is a unexpired entry in the bad cache for
 561  * <name,type>.
 562  *
 563  * Requires:
 564  * \li  resolver to be valid.
 565  * \li  name to be valid.
 566  */
 567
 568 void
 569 dns_resolver_flushbadcache(dns_resolver_t *resolver, dns_name_t *name);
 570 /*%<
 571  * Flush the bad cache of all entries at 'name' if 'name' is non NULL.
 572  * Flush the entire bad cache if 'name' is NULL.
 573  *
 574  * Requires:
 575  * \li  resolver to be valid.
 576  */
 577
 578 void
 579 dns_resolver_printbadcache(dns_resolver_t *resolver, FILE *fp);
 580 /*%
 581  * Print out the contents of the bad cache to 'fp'.
 582  *
 583  * Requires:
 584  * \li  resolver to be valid.
 585  */
 586
 587 void
 588 dns_resolver_setmaxdepth(dns_resolver_t *resolver, unsigned int maxdepth);
 589 unsigned int
 590 dns_resolver_getmaxdepth(dns_resolver_t *resolver);
 591 /*%
 592  * Get and set how many NS indirections will be followed when looking for
 593  * nameserver addresses.
 594  *
 595  * Requires:
 596  * \li  resolver to be valid.
 597  */
 598
 599 void
 600 dns_resolver_setmaxqueries(dns_resolver_t *resolver, unsigned int queries);
 601 unsigned int
 602 dns_resolver_getmaxqueries(dns_resolver_t *resolver);
 603 /*%
 604  * Get and set how many iterative queries will be allowed before
 605  * terminating a recursive query.
 606  *
 607  * Requires:
 608  * \li  resolver to be valid.
 609  */
 610
 611 ISC_LANG_ENDDECLS
 612
 613 #endif /* DNS_RESOLVER_H */