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