resolver.h revision 275672
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: resolver.h,v 1.72 2011/12/05 17:10:51 each Exp $ */ 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 61ISC_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 */ 72typedef 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 isc_uint32_t qtotal; 86} dns_fetchevent_t; 87 88/* 89 * Options that modify how a 'fetch' is done. 90 */ 91#define DNS_FETCHOPT_TCP 0x01 /*%< Use TCP. */ 92#define DNS_FETCHOPT_UNSHARED 0x02 /*%< See below. */ 93#define DNS_FETCHOPT_RECURSIVE 0x04 /*%< Set RD? */ 94#define DNS_FETCHOPT_NOEDNS0 0x08 /*%< Do not use EDNS. */ 95#define DNS_FETCHOPT_FORWARDONLY 0x10 /*%< Only use forwarders. */ 96#define DNS_FETCHOPT_NOVALIDATE 0x20 /*%< Disable validation. */ 97#define DNS_FETCHOPT_EDNS512 0x40 /*%< Advertise a 512 byte 98 UDP buffer. */ 99#define DNS_FETCHOPT_WANTNSID 0x80 /*%< Request NSID */ 100 101#define DNS_FETCHOPT_EDNSVERSIONSET 0x00800000 102#define DNS_FETCHOPT_EDNSVERSIONMASK 0xff000000 103#define DNS_FETCHOPT_EDNSVERSIONSHIFT 24 104 105/* 106 * Upper bounds of class of query RTT (ms). Corresponds to 107 * dns_resstatscounter_queryrttX statistics counters. 108 */ 109#define DNS_RESOLVER_QRYRTTCLASS0 10 110#define DNS_RESOLVER_QRYRTTCLASS0STR "10" 111#define DNS_RESOLVER_QRYRTTCLASS1 100 112#define DNS_RESOLVER_QRYRTTCLASS1STR "100" 113#define DNS_RESOLVER_QRYRTTCLASS2 500 114#define DNS_RESOLVER_QRYRTTCLASS2STR "500" 115#define DNS_RESOLVER_QRYRTTCLASS3 800 116#define DNS_RESOLVER_QRYRTTCLASS3STR "800" 117#define DNS_RESOLVER_QRYRTTCLASS4 1600 118#define DNS_RESOLVER_QRYRTTCLASS4STR "1600" 119 120/* 121 * XXXRTH Should this API be made semi-private? (I.e. 122 * _dns_resolver_create()). 123 */ 124 125#define DNS_RESOLVER_CHECKNAMES 0x01 126#define DNS_RESOLVER_CHECKNAMESFAIL 0x02 127 128isc_result_t 129dns_resolver_create(dns_view_t *view, 130 isc_taskmgr_t *taskmgr, 131 unsigned int ntasks, unsigned int ndisp, 132 isc_socketmgr_t *socketmgr, 133 isc_timermgr_t *timermgr, 134 unsigned int options, 135 dns_dispatchmgr_t *dispatchmgr, 136 dns_dispatch_t *dispatchv4, 137 dns_dispatch_t *dispatchv6, 138 dns_resolver_t **resp); 139 140/*%< 141 * Create a resolver. 142 * 143 * Notes: 144 * 145 *\li Generally, applications should not create a resolver directly, but 146 * should instead call dns_view_createresolver(). 147 * 148 * Requires: 149 * 150 *\li 'view' is a valid view. 151 * 152 *\li 'taskmgr' is a valid task manager. 153 * 154 *\li 'ntasks' > 0. 155 * 156 *\li 'socketmgr' is a valid socket manager. 157 * 158 *\li 'timermgr' is a valid timer manager. 159 * 160 *\li 'dispatchv4' is a dispatch with an IPv4 UDP socket, or is NULL. 161 * If not NULL, 'ndisp' clones of it will be created by the resolver. 162 * 163 *\li 'dispatchv6' is a dispatch with an IPv6 UDP socket, or is NULL. 164 * If not NULL, 'ndisp' clones of it will be created by the resolver. 165 * 166 *\li resp != NULL && *resp == NULL. 167 * 168 * Returns: 169 * 170 *\li #ISC_R_SUCCESS On success. 171 * 172 *\li Anything else Failure. 173 */ 174 175void 176dns_resolver_freeze(dns_resolver_t *res); 177/*%< 178 * Freeze resolver. 179 * 180 * Notes: 181 * 182 *\li Certain configuration changes cannot be made after the resolver 183 * is frozen. Fetches cannot be created until the resolver is frozen. 184 * 185 * Requires: 186 * 187 *\li 'res' is a valid resolver. 188 * 189 * Ensures: 190 * 191 *\li 'res' is frozen. 192 */ 193 194void 195dns_resolver_prime(dns_resolver_t *res); 196/*%< 197 * Prime resolver. 198 * 199 * Notes: 200 * 201 *\li Resolvers which have a forwarding policy other than dns_fwdpolicy_only 202 * need to be primed with the root nameservers, otherwise the root 203 * nameserver hints data may be used indefinitely. This function requests 204 * that the resolver start a priming fetch, if it isn't already priming. 205 * 206 * Requires: 207 * 208 *\li 'res' is a valid, frozen resolver. 209 */ 210 211 212void 213dns_resolver_whenshutdown(dns_resolver_t *res, isc_task_t *task, 214 isc_event_t **eventp); 215/*%< 216 * Send '*eventp' to 'task' when 'res' has completed shutdown. 217 * 218 * Notes: 219 * 220 *\li It is not safe to detach the last reference to 'res' until 221 * shutdown is complete. 222 * 223 * Requires: 224 * 225 *\li 'res' is a valid resolver. 226 * 227 *\li 'task' is a valid task. 228 * 229 *\li *eventp is a valid event. 230 * 231 * Ensures: 232 * 233 *\li *eventp == NULL. 234 */ 235 236void 237dns_resolver_shutdown(dns_resolver_t *res); 238/*%< 239 * Start the shutdown process for 'res'. 240 * 241 * Notes: 242 * 243 *\li This call has no effect if the resolver is already shutting down. 244 * 245 * Requires: 246 * 247 *\li 'res' is a valid resolver. 248 */ 249 250void 251dns_resolver_attach(dns_resolver_t *source, dns_resolver_t **targetp); 252 253void 254dns_resolver_detach(dns_resolver_t **resp); 255 256isc_result_t 257dns_resolver_createfetch(dns_resolver_t *res, dns_name_t *name, 258 dns_rdatatype_t type, 259 dns_name_t *domain, dns_rdataset_t *nameservers, 260 dns_forwarders_t *forwarders, 261 unsigned int options, isc_task_t *task, 262 isc_taskaction_t action, void *arg, 263 dns_rdataset_t *rdataset, 264 dns_rdataset_t *sigrdataset, 265 dns_fetch_t **fetchp); 266 267isc_result_t 268dns_resolver_createfetch2(dns_resolver_t *res, dns_name_t *name, 269 dns_rdatatype_t type, 270 dns_name_t *domain, dns_rdataset_t *nameservers, 271 dns_forwarders_t *forwarders, 272 isc_sockaddr_t *client, isc_uint16_t id, 273 unsigned int options, isc_task_t *task, 274 isc_taskaction_t action, void *arg, 275 dns_rdataset_t *rdataset, 276 dns_rdataset_t *sigrdataset, 277 dns_fetch_t **fetchp); 278isc_result_t 279dns_resolver_createfetch3(dns_resolver_t *res, dns_name_t *name, 280 dns_rdatatype_t type, 281 dns_name_t *domain, dns_rdataset_t *nameservers, 282 dns_forwarders_t *forwarders, 283 isc_sockaddr_t *client, isc_uint16_t id, 284 unsigned int options, unsigned int depth, 285 isc_task_t *task, 286 isc_taskaction_t action, void *arg, 287 dns_rdataset_t *rdataset, 288 dns_rdataset_t *sigrdataset, 289 dns_fetch_t **fetchp); 290/*%< 291 * Recurse to answer a question. 292 * 293 * Notes: 294 * 295 *\li This call starts a query for 'name', type 'type'. 296 * 297 *\li The 'domain' is a parent domain of 'name' for which 298 * a set of name servers 'nameservers' is known. If no 299 * such name server information is available, set 300 * 'domain' and 'nameservers' to NULL. 301 * 302 *\li 'forwarders' is unimplemented, and subject to change when 303 * we figure out how selective forwarding will work. 304 * 305 *\li When the fetch completes (successfully or otherwise), a 306 * #DNS_EVENT_FETCHDONE event with action 'action' and arg 'arg' will be 307 * posted to 'task'. 308 * 309 *\li The values of 'rdataset' and 'sigrdataset' will be returned in 310 * the FETCHDONE event. 311 * 312 *\li 'client' and 'id' are used for duplicate query detection. '*client' 313 * must remain stable until after 'action' has been called or 314 * dns_resolver_cancelfetch() is called. 315 * 316 * Requires: 317 * 318 *\li 'res' is a valid resolver that has been frozen. 319 * 320 *\li 'name' is a valid name. 321 * 322 *\li 'type' is not a meta type other than ANY. 323 * 324 *\li 'domain' is a valid name or NULL. 325 * 326 *\li 'nameservers' is a valid NS rdataset (whose owner name is 'domain') 327 * iff. 'domain' is not NULL. 328 * 329 *\li 'forwarders' is NULL. 330 * 331 *\li 'client' is a valid sockaddr or NULL. 332 * 333 *\li 'options' contains valid options. 334 * 335 *\li 'rdataset' is a valid, disassociated rdataset. 336 * 337 *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset. 338 * 339 *\li fetchp != NULL && *fetchp == NULL. 340 * 341 * Returns: 342 * 343 *\li #ISC_R_SUCCESS Success 344 *\li #DNS_R_DUPLICATE 345 *\li #DNS_R_DROP 346 * 347 *\li Many other values are possible, all of which indicate failure. 348 */ 349 350void 351dns_resolver_cancelfetch(dns_fetch_t *fetch); 352/*%< 353 * Cancel 'fetch'. 354 * 355 * Notes: 356 * 357 *\li If 'fetch' has not completed, post its FETCHDONE event with a 358 * result code of #ISC_R_CANCELED. 359 * 360 * Requires: 361 * 362 *\li 'fetch' is a valid fetch. 363 */ 364 365void 366dns_resolver_destroyfetch(dns_fetch_t **fetchp); 367/*%< 368 * Destroy 'fetch'. 369 * 370 * Requires: 371 * 372 *\li '*fetchp' is a valid fetch. 373 * 374 *\li The caller has received the FETCHDONE event (either because the 375 * fetch completed or because dns_resolver_cancelfetch() was called). 376 * 377 * Ensures: 378 * 379 *\li *fetchp == NULL. 380 */ 381 382void 383dns_resolver_logfetch(dns_fetch_t *fetch, isc_log_t *lctx, 384 isc_logcategory_t *category, isc_logmodule_t *module, 385 int level, isc_boolean_t duplicateok); 386/*%< 387 * Dump a log message on internal state at the completion of given 'fetch'. 388 * 'lctx', 'category', 'module', and 'level' are used to write the log message. 389 * By default, only one log message is written even if the corresponding fetch 390 * context serves multiple clients; if 'duplicateok' is true the suppression 391 * is disabled and the message can be written every time this function is 392 * called. 393 * 394 * Requires: 395 * 396 *\li 'fetch' is a valid fetch, and has completed. 397 */ 398 399dns_dispatchmgr_t * 400dns_resolver_dispatchmgr(dns_resolver_t *resolver); 401 402dns_dispatch_t * 403dns_resolver_dispatchv4(dns_resolver_t *resolver); 404 405dns_dispatch_t * 406dns_resolver_dispatchv6(dns_resolver_t *resolver); 407 408isc_socketmgr_t * 409dns_resolver_socketmgr(dns_resolver_t *resolver); 410 411isc_taskmgr_t * 412dns_resolver_taskmgr(dns_resolver_t *resolver); 413 414isc_uint32_t 415dns_resolver_getlamettl(dns_resolver_t *resolver); 416/*%< 417 * Get the resolver's lame-ttl. zero => no lame processing. 418 * 419 * Requires: 420 *\li 'resolver' to be valid. 421 */ 422 423void 424dns_resolver_setlamettl(dns_resolver_t *resolver, isc_uint32_t lame_ttl); 425/*%< 426 * Set the resolver's lame-ttl. zero => no lame processing. 427 * 428 * Requires: 429 *\li 'resolver' to be valid. 430 */ 431 432unsigned int 433dns_resolver_nrunning(dns_resolver_t *resolver); 434/*%< 435 * Return the number of currently running resolutions in this 436 * resolver. This is may be less than the number of outstanding 437 * fetches due to multiple identical fetches, or more than the 438 * number of of outstanding fetches due to the fact that resolution 439 * can continue even though a fetch has been canceled. 440 */ 441 442isc_result_t 443dns_resolver_addalternate(dns_resolver_t *resolver, isc_sockaddr_t *alt, 444 dns_name_t *name, in_port_t port); 445/*%< 446 * Add alternate addresses to be tried in the event that the nameservers 447 * for a zone are not available in the address families supported by the 448 * operating system. 449 * 450 * Require: 451 * \li only one of 'name' or 'alt' to be valid. 452 */ 453 454void 455dns_resolver_setudpsize(dns_resolver_t *resolver, isc_uint16_t udpsize); 456/*%< 457 * Set the EDNS UDP buffer size advertised by the server. 458 */ 459 460isc_uint16_t 461dns_resolver_getudpsize(dns_resolver_t *resolver); 462/*%< 463 * Get the current EDNS UDP buffer size. 464 */ 465 466void 467dns_resolver_reset_algorithms(dns_resolver_t *resolver); 468/*%< 469 * Clear the disabled DNSSEC algorithms. 470 */ 471 472isc_result_t 473dns_resolver_disable_algorithm(dns_resolver_t *resolver, dns_name_t *name, 474 unsigned int alg); 475/*%< 476 * Mark the give DNSSEC algorithm as disabled and below 'name'. 477 * Valid algorithms are less than 256. 478 * 479 * Returns: 480 *\li #ISC_R_SUCCESS 481 *\li #ISC_R_RANGE 482 *\li #ISC_R_NOMEMORY 483 */ 484 485isc_boolean_t 486dns_resolver_algorithm_supported(dns_resolver_t *resolver, dns_name_t *name, 487 unsigned int alg); 488/*%< 489 * Check if the given algorithm is supported by this resolver. 490 * This checks if the algorithm has been disabled via 491 * dns_resolver_disable_algorithm() then the underlying 492 * crypto libraries if not specifically disabled. 493 */ 494 495isc_boolean_t 496dns_resolver_digest_supported(dns_resolver_t *resolver, unsigned int digest_type); 497/*%< 498 * Is this digest type supported. 499 */ 500 501void 502dns_resolver_resetmustbesecure(dns_resolver_t *resolver); 503 504isc_result_t 505dns_resolver_setmustbesecure(dns_resolver_t *resolver, dns_name_t *name, 506 isc_boolean_t value); 507 508isc_boolean_t 509dns_resolver_getmustbesecure(dns_resolver_t *resolver, dns_name_t *name); 510 511 512void 513dns_resolver_settimeout(dns_resolver_t *resolver, unsigned int seconds); 514/*%< 515 * Set the length of time the resolver will work on a query, in seconds. 516 * 517 * If timeout is 0, the default timeout will be applied. 518 * 519 * Requires: 520 * \li resolver to be valid. 521 */ 522 523unsigned int 524dns_resolver_gettimeout(dns_resolver_t *resolver); 525/*%< 526 * Get the current length of time the resolver will work on a query, in seconds. 527 * 528 * Requires: 529 * \li resolver to be valid. 530 */ 531 532void 533dns_resolver_setclientsperquery(dns_resolver_t *resolver, 534 isc_uint32_t min, isc_uint32_t max); 535 536void 537dns_resolver_getclientsperquery(dns_resolver_t *resolver, isc_uint32_t *cur, 538 isc_uint32_t *min, isc_uint32_t *max); 539 540isc_boolean_t 541dns_resolver_getzeronosoattl(dns_resolver_t *resolver); 542 543void 544dns_resolver_setzeronosoattl(dns_resolver_t *resolver, isc_boolean_t state); 545 546unsigned int 547dns_resolver_getoptions(dns_resolver_t *resolver); 548 549void 550dns_resolver_addbadcache(dns_resolver_t *resolver, dns_name_t *name, 551 dns_rdatatype_t type, isc_time_t *expire); 552/*%< 553 * Add a entry to the bad cache for <name,type> that will expire at 'expire'. 554 * 555 * Requires: 556 * \li resolver to be valid. 557 * \li name to be valid. 558 */ 559 560isc_boolean_t 561dns_resolver_getbadcache(dns_resolver_t *resolver, dns_name_t *name, 562 dns_rdatatype_t type, isc_time_t *now); 563/*%< 564 * Check to see if there is a unexpired entry in the bad cache for 565 * <name,type>. 566 * 567 * Requires: 568 * \li resolver to be valid. 569 * \li name to be valid. 570 */ 571 572void 573dns_resolver_flushbadcache(dns_resolver_t *resolver, dns_name_t *name); 574/*%< 575 * Flush the bad cache of all entries at 'name' if 'name' is non NULL. 576 * Flush the entire bad cache if 'name' is NULL. 577 * 578 * Requires: 579 * \li resolver to be valid. 580 */ 581 582void 583dns_resolver_printbadcache(dns_resolver_t *resolver, FILE *fp); 584/*% 585 * Print out the contents of the bad cache to 'fp'. 586 * 587 * Requires: 588 * \li resolver to be valid. 589 */ 590 591void 592dns_resolver_setmaxdepth(dns_resolver_t *resolver, unsigned int maxdepth); 593unsigned int 594dns_resolver_getmaxdepth(dns_resolver_t *resolver); 595/*% 596 * Get and set how many NS indirections will be followed when looking for 597 * nameserver addresses. 598 * 599 * Requires: 600 * \li resolver to be valid. 601 */ 602 603ISC_LANG_ENDDECLS 604 605#endif /* DNS_RESOLVER_H */ 606