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

   1 /*
   2  * Copyright (C) 2004-2006  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2001, 2003  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and 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: resolver.h,v 1.40.18.11 2006/02/01 22:39:17 marka Exp $ */
  19
  20 #ifndef DNS_RESOLVER_H
  21 #define DNS_RESOLVER_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file
  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 } dns_fetchevent_t;
  85
  86 /*
  87  * Options that modify how a 'fetch' is done.
  88  */
  89 #define DNS_FETCHOPT_TCP                0x01         /*%< Use TCP. */
  90 #define DNS_FETCHOPT_UNSHARED           0x02         /*%< See below. */
  91 #define DNS_FETCHOPT_RECURSIVE          0x04         /*%< Set RD? */
  92 #define DNS_FETCHOPT_NOEDNS0            0x08         /*%< Do not use EDNS. */
  93 #define DNS_FETCHOPT_FORWARDONLY        0x10         /*%< Only use forwarders. */
  94 #define DNS_FETCHOPT_NOVALIDATE         0x20         /*%< Disable validation. */
  95 #define DNS_FETCHOPT_EDNS512            0x40         /*%< Advertise a 512 byte
  96                                                           UDP buffer. */
  97
  98 #define DNS_FETCHOPT_EDNSVERSIONSET     0x00800000
  99 #define DNS_FETCHOPT_EDNSVERSIONMASK    0xff000000
 100 #define DNS_FETCHOPT_EDNSVERSIONSHIFT   24
 101
 102 /*
 103  * XXXRTH  Should this API be made semi-private?  (I.e.
 104  * _dns_resolver_create()).
 105  */
 106
 107 #define DNS_RESOLVER_CHECKNAMES         0x01
 108 #define DNS_RESOLVER_CHECKNAMESFAIL     0x02
 109
 110 isc_result_t
 111 dns_resolver_create(dns_view_t *view,
 112                     isc_taskmgr_t *taskmgr, unsigned int ntasks,
 113                     isc_socketmgr_t *socketmgr,
 114                     isc_timermgr_t *timermgr,
 115                     unsigned int options,
 116                     dns_dispatchmgr_t *dispatchmgr,
 117                     dns_dispatch_t *dispatchv4,
 118                     dns_dispatch_t *dispatchv6,
 119                     dns_resolver_t **resp);
 120
 121 /*%<
 122  * Create a resolver.
 123  *
 124  * Notes:
 125  *
 126  *\li   Generally, applications should not create a resolver directly, but
 127  *      should instead call dns_view_createresolver().
 128  *
 129  *\li   No options are currently defined.
 130  *
 131  * Requires:
 132  *
 133  *\li   'view' is a valid view.
 134  *
 135  *\li   'taskmgr' is a valid task manager.
 136  *
 137  *\li   'ntasks' > 0.
 138  *
 139  *\li   'socketmgr' is a valid socket manager.
 140  *
 141  *\li   'timermgr' is a valid timer manager.
 142  *
 143  *\li   'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL.
 144  *
 145  *\li   'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.
 146  *
 147  *\li   resp != NULL && *resp == NULL.
 148  *
 149  * Returns:
 150  *
 151  *\li   #ISC_R_SUCCESS                          On success.
 152  *
 153  *\li   Anything else                           Failure.
 154  */
 155
 156 void
 157 dns_resolver_freeze(dns_resolver_t *res);
 158 /*%<
 159  * Freeze resolver.
 160  *
 161  * Notes:
 162  *
 163  *\li   Certain configuration changes cannot be made after the resolver
 164  *      is frozen.  Fetches cannot be created until the resolver is frozen.
 165  *
 166  * Requires:
 167  *
 168  *\li   'res' is a valid, unfrozen resolver.
 169  *
 170  * Ensures:
 171  *
 172  *\li   'res' is frozen.
 173  */
 174
 175 void
 176 dns_resolver_prime(dns_resolver_t *res);
 177 /*%<
 178  * Prime resolver.
 179  *
 180  * Notes:
 181  *
 182  *\li   Resolvers which have a forwarding policy other than dns_fwdpolicy_only
 183  *      need to be primed with the root nameservers, otherwise the root
 184  *      nameserver hints data may be used indefinitely.  This function requests
 185  *      that the resolver start a priming fetch, if it isn't already priming.
 186  *
 187  * Requires:
 188  *
 189  *\li   'res' is a valid, frozen resolver.
 190  */
 191
 192
 193 void
 194 dns_resolver_whenshutdown(dns_resolver_t *res, isc_task_t *task,
 195                           isc_event_t **eventp);
 196 /*%<
 197  * Send '*eventp' to 'task' when 'res' has completed shutdown.
 198  *
 199  * Notes:
 200  *
 201  *\li   It is not safe to detach the last reference to 'res' until
 202  *      shutdown is complete.
 203  *
 204  * Requires:
 205  *
 206  *\li   'res' is a valid resolver.
 207  *
 208  *\li   'task' is a valid task.
 209  *
 210  *\li   *eventp is a valid event.
 211  *
 212  * Ensures:
 213  *
 214  *\li   *eventp == NULL.
 215  */
 216
 217 void
 218 dns_resolver_shutdown(dns_resolver_t *res);
 219 /*%<
 220  * Start the shutdown process for 'res'.
 221  *
 222  * Notes:
 223  *
 224  *\li   This call has no effect if the resolver is already shutting down.
 225  *
 226  * Requires:
 227  *
 228  *\li   'res' is a valid resolver.
 229  */
 230
 231 void
 232 dns_resolver_attach(dns_resolver_t *source, dns_resolver_t **targetp);
 233
 234 void
 235 dns_resolver_detach(dns_resolver_t **resp);
 236
 237 isc_result_t
 238 dns_resolver_createfetch(dns_resolver_t *res, dns_name_t *name,
 239                          dns_rdatatype_t type,
 240                          dns_name_t *domain, dns_rdataset_t *nameservers,
 241                          dns_forwarders_t *forwarders,
 242                          unsigned int options, isc_task_t *task,
 243                          isc_taskaction_t action, void *arg,
 244                          dns_rdataset_t *rdataset,
 245                          dns_rdataset_t *sigrdataset,
 246                          dns_fetch_t **fetchp);
 247
 248 isc_result_t
 249 dns_resolver_createfetch2(dns_resolver_t *res, dns_name_t *name,
 250                           dns_rdatatype_t type,
 251                           dns_name_t *domain, dns_rdataset_t *nameservers,
 252                           dns_forwarders_t *forwarders,
 253                           isc_sockaddr_t *client, isc_uint16_t id,
 254                           unsigned int options, isc_task_t *task,
 255                           isc_taskaction_t action, void *arg,
 256                           dns_rdataset_t *rdataset,
 257                           dns_rdataset_t *sigrdataset,
 258                           dns_fetch_t **fetchp);
 259 /*%<
 260  * Recurse to answer a question.
 261  *
 262  * Notes:
 263  *
 264  *\li   This call starts a query for 'name', type 'type'.
 265  *
 266  *\li   The 'domain' is a parent domain of 'name' for which
 267  *      a set of name servers 'nameservers' is known.  If no
 268  *      such name server information is available, set
 269  *      'domain' and 'nameservers' to NULL.
 270  *
 271  *\li   'forwarders' is unimplemented, and subject to change when
 272  *      we figure out how selective forwarding will work.
 273  *
 274  *\li   When the fetch completes (successfully or otherwise), a
 275  *      #DNS_EVENT_FETCHDONE event with action 'action' and arg 'arg' will be
 276  *      posted to 'task'.
 277  *
 278  *\li   The values of 'rdataset' and 'sigrdataset' will be returned in
 279  *      the FETCHDONE event.
 280  *
 281  *\li   'client' and 'id' are used for duplicate query detection.  '*client'
 282  *      must remain stable until after 'action' has been called or
 283  *      dns_resolver_cancelfetch() is called.
 284  *
 285  * Requires:
 286  *
 287  *\li   'res' is a valid resolver that has been frozen.
 288  *
 289  *\li   'name' is a valid name.
 290  *
 291  *\li   'type' is not a meta type other than ANY.
 292  *
 293  *\li   'domain' is a valid name or NULL.
 294  *
 295  *\li   'nameservers' is a valid NS rdataset (whose owner name is 'domain')
 296  *      iff. 'domain' is not NULL.
 297  *
 298  *\li   'forwarders' is NULL.
 299  *
 300  *\li   'client' is a valid sockaddr or NULL.
 301  *
 302  *\li   'options' contains valid options.
 303  *
 304  *\li   'rdataset' is a valid, disassociated rdataset.
 305  *
 306  *\li   'sigrdataset' is NULL, or is a valid, disassociated rdataset.
 307  *
 308  *\li   fetchp != NULL && *fetchp == NULL.
 309  *
 310  * Returns:
 311  *
 312  *\li   #ISC_R_SUCCESS                                  Success
 313  *\li   #DNS_R_DUPLICATE
 314  *\li   #DNS_R_DROP
 315  *
 316  *\li   Many other values are possible, all of which indicate failure.
 317  */
 318
 319 void
 320 dns_resolver_cancelfetch(dns_fetch_t *fetch);
 321 /*%<
 322  * Cancel 'fetch'.
 323  *
 324  * Notes:
 325  *
 326  *\li   If 'fetch' has not completed, post its FETCHDONE event with a
 327  *      result code of #ISC_R_CANCELED.
 328  *
 329  * Requires:
 330  *
 331  *\li   'fetch' is a valid fetch.
 332  */
 333
 334 void
 335 dns_resolver_destroyfetch(dns_fetch_t **fetchp);
 336 /*%<
 337  * Destroy 'fetch'.
 338  *
 339  * Requires:
 340  *
 341  *\li   '*fetchp' is a valid fetch.
 342  *
 343  *\li   The caller has received the FETCHDONE event (either because the
 344  *      fetch completed or because dns_resolver_cancelfetch() was called).
 345  *
 346  * Ensures:
 347  *
 348  *\li   *fetchp == NULL.
 349  */
 350
 351 dns_dispatchmgr_t *
 352 dns_resolver_dispatchmgr(dns_resolver_t *resolver);
 353
 354 dns_dispatch_t *
 355 dns_resolver_dispatchv4(dns_resolver_t *resolver);
 356
 357 dns_dispatch_t *
 358 dns_resolver_dispatchv6(dns_resolver_t *resolver);
 359
 360 isc_socketmgr_t *
 361 dns_resolver_socketmgr(dns_resolver_t *resolver);
 362
 363 isc_taskmgr_t *
 364 dns_resolver_taskmgr(dns_resolver_t *resolver);
 365
 366 isc_uint32_t
 367 dns_resolver_getlamettl(dns_resolver_t *resolver);
 368 /*%<
 369  * Get the resolver's lame-ttl.  zero => no lame processing.
 370  *
 371  * Requires:
 372  *\li   'resolver' to be valid.
 373  */
 374
 375 void
 376 dns_resolver_setlamettl(dns_resolver_t *resolver, isc_uint32_t lame_ttl);
 377 /*%<
 378  * Set the resolver's lame-ttl.  zero => no lame processing.
 379  *
 380  * Requires:
 381  *\li   'resolver' to be valid.
 382  */
 383
 384 unsigned int
 385 dns_resolver_nrunning(dns_resolver_t *resolver);
 386 /*%<
 387  * Return the number of currently running resolutions in this
 388  * resolver.  This is may be less than the number of outstanding
 389  * fetches due to multiple identical fetches, or more than the
 390  * number of of outstanding fetches due to the fact that resolution
 391  * can continue even though a fetch has been canceled.
 392  */
 393
 394 isc_result_t
 395 dns_resolver_addalternate(dns_resolver_t *resolver, isc_sockaddr_t *alt,
 396                           dns_name_t *name, in_port_t port);
 397 /*%<
 398  * Add alternate addresses to be tried in the event that the nameservers
 399  * for a zone are not available in the address families supported by the
 400  * operating system.
 401  *
 402  * Require:
 403  * \li  only one of 'name' or 'alt' to be valid.
 404  */
 405
 406 void
 407 dns_resolver_setudpsize(dns_resolver_t *resolver, isc_uint16_t udpsize);
 408 /*%<
 409  * Set the EDNS UDP buffer size advertised by the server.
 410  */
 411
 412 isc_uint16_t
 413 dns_resolver_getudpsize(dns_resolver_t *resolver);
 414 /*%<
 415  * Get the current EDNS UDP buffer size.
 416  */
 417
 418 void
 419 dns_resolver_reset_algorithms(dns_resolver_t *resolver);
 420 /*%<
 421  * Clear the disabled DNSSEC algorithms.
 422  */
 423
 424 isc_result_t
 425 dns_resolver_disable_algorithm(dns_resolver_t *resolver, dns_name_t *name,
 426                                unsigned int alg);
 427 /*%<
 428  * Mark the give DNSSEC algorithm as disabled and below 'name'.
 429  * Valid algorithms are less than 256.
 430  *
 431  * Returns:
 432  *\li   #ISC_R_SUCCESS
 433  *\li   #ISC_R_RANGE
 434  *\li   #ISC_R_NOMEMORY
 435  */
 436
 437 isc_boolean_t
 438 dns_resolver_algorithm_supported(dns_resolver_t *resolver, dns_name_t *name,
 439                                  unsigned int alg);
 440 /*%<
 441  * Check if the given algorithm is supported by this resolver.
 442  * This checks if the algorithm has been disabled via
 443  * dns_resolver_disable_algorithm() then the underlying
 444  * crypto libraries if not specifically disabled.
 445  */
 446
 447 isc_boolean_t
 448 dns_resolver_digest_supported(dns_resolver_t *resolver, unsigned int digest_type);
 449 /*%<
 450  * Is this digest type supported.
 451  */
 452
 453 void
 454 dns_resolver_resetmustbesecure(dns_resolver_t *resolver);
 455
 456 isc_result_t
 457 dns_resolver_setmustbesecure(dns_resolver_t *resolver, dns_name_t *name,
 458                              isc_boolean_t value);
 459
 460 isc_boolean_t
 461 dns_resolver_getmustbesecure(dns_resolver_t *resolver, dns_name_t *name);
 462
 463 void
 464 dns_resolver_setclientsperquery(dns_resolver_t *resolver,
 465                                 isc_uint32_t min, isc_uint32_t max);
 466
 467 void
 468 dns_resolver_getclientsperquery(dns_resolver_t *resolver, isc_uint32_t *cur,
 469                                 isc_uint32_t *min, isc_uint32_t *max);
 470
 471 isc_boolean_t
 472 dns_resolver_getzeronosoattl(dns_resolver_t *resolver);
 473
 474 void
 475 dns_resolver_setzeronosoattl(dns_resolver_t *resolver, isc_boolean_t state);
 476
 477 ISC_LANG_ENDDECLS
 478
 479 #endif /* DNS_RESOLVER_H */