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