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