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