resolver.h revision 205292
10SN/A/* 27755SN/A * Copyright (C) 2004-2010 Internet Systems Consortium, Inc. ("ISC") 30SN/A * Copyright (C) 1999-2001, 2003 Internet Software Consortium. 40SN/A * 50SN/A * Permission to use, copy, modify, and/or distribute this software for any 60SN/A * purpose with or without fee is hereby granted, provided that the above 72362SN/A * copyright notice and this permission notice appear in all copies. 80SN/A * 92362SN/A * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 100SN/A * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 110SN/A * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 120SN/A * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 130SN/A * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 140SN/A * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 150SN/A * PERFORMANCE OF THIS SOFTWARE. 160SN/A */ 170SN/A 180SN/A/* $Id: resolver.h,v 1.60.56.3.22.2 2010/02/25 10:57:12 tbox Exp $ */ 190SN/A 200SN/A#ifndef DNS_RESOLVER_H 212362SN/A#define DNS_RESOLVER_H 1 222362SN/A 232362SN/A/***** 240SN/A ***** Module Info 250SN/A *****/ 260SN/A 270SN/A/*! \file dns/resolver.h 280SN/A * 290SN/A * \brief 300SN/A * This is the BIND 9 resolver, the module responsible for resolving DNS 310SN/A * requests by iteratively querying authoritative servers and following 320SN/A * referrals. This is a "full resolver", not to be confused with 330SN/A * the stub resolvers most people associate with the word "resolver". 340SN/A * The full resolver is part of the caching name server or resolver 350SN/A * daemon the stub resolver talks to. 360SN/A * 370SN/A * MP: 380SN/A *\li The module ensures appropriate synchronization of data structures it 390SN/A * creates and manipulates. 400SN/A * 41658SN/A * Reliability: 42658SN/A *\li No anticipated impact. 430SN/A * 440SN/A * Resources: 450SN/A *\li TBS 460SN/A * 470SN/A * Security: 480SN/A *\li No anticipated impact. 490SN/A * 500SN/A * Standards: 510SN/A *\li RFCs: 1034, 1035, 2181, TBS 520SN/A *\li Drafts: TBS 537755SN/A */ 540SN/A 550SN/A#include <isc/lang.h> 567755SN/A#include <isc/socket.h> 570SN/A 580SN/A#include <dns/types.h> 597755SN/A#include <dns/fixedname.h> 600SN/A 610SN/AISC_LANG_BEGINDECLS 620SN/A 630SN/A/*% 640SN/A * A dns_fetchevent_t is sent when a 'fetch' completes. Any of 'db', 650SN/A * 'node', 'rdataset', and 'sigrdataset' may be bound. It is the 660SN/A * receiver's responsibility to detach before freeing the event. 670SN/A * \brief 680SN/A * 'rdataset', 'sigrdataset', 'client' and 'id' are the values that were 690SN/A * supplied when dns_resolver_createfetch() was called. They are returned 700SN/A * to the caller so that they may be freed. 710SN/A */ 720SN/Atypedef struct dns_fetchevent { 737755SN/A ISC_EVENT_COMMON(struct dns_fetchevent); 740SN/A dns_fetch_t * fetch; 750SN/A isc_result_t result; 760SN/A dns_rdatatype_t qtype; 770SN/A dns_db_t * db; 780SN/A dns_dbnode_t * node; 797755SN/A dns_rdataset_t * rdataset; 800SN/A dns_rdataset_t * sigrdataset; 810SN/A dns_fixedname_t foundname; 820SN/A isc_sockaddr_t * client; 830SN/A dns_messageid_t id; 840SN/A} dns_fetchevent_t; 850SN/A 860SN/A/* 870SN/A * Options that modify how a 'fetch' is done. 880SN/A */ 890SN/A#define DNS_FETCHOPT_TCP 0x01 /*%< Use TCP. */ 900SN/A#define DNS_FETCHOPT_UNSHARED 0x02 /*%< See below. */ 910SN/A#define DNS_FETCHOPT_RECURSIVE 0x04 /*%< Set RD? */ 920SN/A#define DNS_FETCHOPT_NOEDNS0 0x08 /*%< Do not use EDNS. */ 930SN/A#define DNS_FETCHOPT_FORWARDONLY 0x10 /*%< Only use forwarders. */ 940SN/A#define DNS_FETCHOPT_NOVALIDATE 0x20 /*%< Disable validation. */ 950SN/A#define DNS_FETCHOPT_EDNS512 0x40 /*%< Advertise a 512 byte 960SN/A UDP buffer. */ 970SN/A#define DNS_FETCHOPT_WANTNSID 0x80 /*%< Request NSID */ 980SN/A 990SN/A#define DNS_FETCHOPT_EDNSVERSIONSET 0x00800000 1000SN/A#define DNS_FETCHOPT_EDNSVERSIONMASK 0xff000000 1010SN/A#define DNS_FETCHOPT_EDNSVERSIONSHIFT 24 1020SN/A 1030SN/A/* 1040SN/A * Upper bounds of class of query RTT (ms). Corresponds to 1057755SN/A * dns_resstatscounter_queryrttX statistics counters. 1060SN/A */ 1070SN/A#define DNS_RESOLVER_QRYRTTCLASS0 10 1080SN/A#define DNS_RESOLVER_QRYRTTCLASS0STR "10" 1090SN/A#define DNS_RESOLVER_QRYRTTCLASS1 100 1100SN/A#define DNS_RESOLVER_QRYRTTCLASS1STR "100" 1110SN/A#define DNS_RESOLVER_QRYRTTCLASS2 500 1120SN/A#define DNS_RESOLVER_QRYRTTCLASS2STR "500" 1130SN/A#define DNS_RESOLVER_QRYRTTCLASS3 800 1140SN/A#define DNS_RESOLVER_QRYRTTCLASS3STR "800" 1150SN/A#define DNS_RESOLVER_QRYRTTCLASS4 1600 1167755SN/A#define DNS_RESOLVER_QRYRTTCLASS4STR "1600" 1177755SN/A 1180SN/A/* 1190SN/A * XXXRTH Should this API be made semi-private? (I.e. 1200SN/A * _dns_resolver_create()). 1210SN/A */ 1220SN/A 1230SN/A#define DNS_RESOLVER_CHECKNAMES 0x01 12410089SN/A#define DNS_RESOLVER_CHECKNAMESFAIL 0x02 1250SN/A 1260SN/Aisc_result_t 1270SN/Adns_resolver_create(dns_view_t *view, 1280SN/A isc_taskmgr_t *taskmgr, unsigned int ntasks, 1290SN/A isc_socketmgr_t *socketmgr, 1300SN/A isc_timermgr_t *timermgr, 1310SN/A unsigned int options, 1320SN/A dns_dispatchmgr_t *dispatchmgr, 1330SN/A dns_dispatch_t *dispatchv4, 1340SN/A dns_dispatch_t *dispatchv6, 1350SN/A dns_resolver_t **resp); 136 137/*%< 138 * Create a resolver. 139 * 140 * Notes: 141 * 142 *\li Generally, applications should not create a resolver directly, but 143 * should instead call dns_view_createresolver(). 144 * 145 * Requires: 146 * 147 *\li 'view' is a valid view. 148 * 149 *\li 'taskmgr' is a valid task manager. 150 * 151 *\li 'ntasks' > 0. 152 * 153 *\li 'socketmgr' is a valid socket manager. 154 * 155 *\li 'timermgr' is a valid timer manager. 156 * 157 *\li 'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL. 158 * 159 *\li 'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL. 160 * 161 *\li resp != NULL && *resp == NULL. 162 * 163 * Returns: 164 * 165 *\li #ISC_R_SUCCESS On success. 166 * 167 *\li Anything else Failure. 168 */ 169 170void 171dns_resolver_freeze(dns_resolver_t *res); 172/*%< 173 * Freeze resolver. 174 * 175 * Notes: 176 * 177 *\li Certain configuration changes cannot be made after the resolver 178 * is frozen. Fetches cannot be created until the resolver is frozen. 179 * 180 * Requires: 181 * 182 *\li 'res' is a valid, unfrozen resolver. 183 * 184 * Ensures: 185 * 186 *\li 'res' is frozen. 187 */ 188 189void 190dns_resolver_prime(dns_resolver_t *res); 191/*%< 192 * Prime resolver. 193 * 194 * Notes: 195 * 196 *\li Resolvers which have a forwarding policy other than dns_fwdpolicy_only 197 * need to be primed with the root nameservers, otherwise the root 198 * nameserver hints data may be used indefinitely. This function requests 199 * that the resolver start a priming fetch, if it isn't already priming. 200 * 201 * Requires: 202 * 203 *\li 'res' is a valid, frozen resolver. 204 */ 205 206 207void 208dns_resolver_whenshutdown(dns_resolver_t *res, isc_task_t *task, 209 isc_event_t **eventp); 210/*%< 211 * Send '*eventp' to 'task' when 'res' has completed shutdown. 212 * 213 * Notes: 214 * 215 *\li It is not safe to detach the last reference to 'res' until 216 * shutdown is complete. 217 * 218 * Requires: 219 * 220 *\li 'res' is a valid resolver. 221 * 222 *\li 'task' is a valid task. 223 * 224 *\li *eventp is a valid event. 225 * 226 * Ensures: 227 * 228 *\li *eventp == NULL. 229 */ 230 231void 232dns_resolver_shutdown(dns_resolver_t *res); 233/*%< 234 * Start the shutdown process for 'res'. 235 * 236 * Notes: 237 * 238 *\li This call has no effect if the resolver is already shutting down. 239 * 240 * Requires: 241 * 242 *\li 'res' is a valid resolver. 243 */ 244 245void 246dns_resolver_attach(dns_resolver_t *source, dns_resolver_t **targetp); 247 248void 249dns_resolver_detach(dns_resolver_t **resp); 250 251isc_result_t 252dns_resolver_createfetch(dns_resolver_t *res, dns_name_t *name, 253 dns_rdatatype_t type, 254 dns_name_t *domain, dns_rdataset_t *nameservers, 255 dns_forwarders_t *forwarders, 256 unsigned int options, isc_task_t *task, 257 isc_taskaction_t action, void *arg, 258 dns_rdataset_t *rdataset, 259 dns_rdataset_t *sigrdataset, 260 dns_fetch_t **fetchp); 261 262isc_result_t 263dns_resolver_createfetch2(dns_resolver_t *res, dns_name_t *name, 264 dns_rdatatype_t type, 265 dns_name_t *domain, dns_rdataset_t *nameservers, 266 dns_forwarders_t *forwarders, 267 isc_sockaddr_t *client, isc_uint16_t id, 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 * Recurse to answer a question. 275 * 276 * Notes: 277 * 278 *\li This call starts a query for 'name', type 'type'. 279 * 280 *\li The 'domain' is a parent domain of 'name' for which 281 * a set of name servers 'nameservers' is known. If no 282 * such name server information is available, set 283 * 'domain' and 'nameservers' to NULL. 284 * 285 *\li 'forwarders' is unimplemented, and subject to change when 286 * we figure out how selective forwarding will work. 287 * 288 *\li When the fetch completes (successfully or otherwise), a 289 * #DNS_EVENT_FETCHDONE event with action 'action' and arg 'arg' will be 290 * posted to 'task'. 291 * 292 *\li The values of 'rdataset' and 'sigrdataset' will be returned in 293 * the FETCHDONE event. 294 * 295 *\li 'client' and 'id' are used for duplicate query detection. '*client' 296 * must remain stable until after 'action' has been called or 297 * dns_resolver_cancelfetch() is called. 298 * 299 * Requires: 300 * 301 *\li 'res' is a valid resolver that has been frozen. 302 * 303 *\li 'name' is a valid name. 304 * 305 *\li 'type' is not a meta type other than ANY. 306 * 307 *\li 'domain' is a valid name or NULL. 308 * 309 *\li 'nameservers' is a valid NS rdataset (whose owner name is 'domain') 310 * iff. 'domain' is not NULL. 311 * 312 *\li 'forwarders' is NULL. 313 * 314 *\li 'client' is a valid sockaddr or NULL. 315 * 316 *\li 'options' contains valid options. 317 * 318 *\li 'rdataset' is a valid, disassociated rdataset. 319 * 320 *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset. 321 * 322 *\li fetchp != NULL && *fetchp == NULL. 323 * 324 * Returns: 325 * 326 *\li #ISC_R_SUCCESS Success 327 *\li #DNS_R_DUPLICATE 328 *\li #DNS_R_DROP 329 * 330 *\li Many other values are possible, all of which indicate failure. 331 */ 332 333void 334dns_resolver_cancelfetch(dns_fetch_t *fetch); 335/*%< 336 * Cancel 'fetch'. 337 * 338 * Notes: 339 * 340 *\li If 'fetch' has not completed, post its FETCHDONE event with a 341 * result code of #ISC_R_CANCELED. 342 * 343 * Requires: 344 * 345 *\li 'fetch' is a valid fetch. 346 */ 347 348void 349dns_resolver_destroyfetch(dns_fetch_t **fetchp); 350/*%< 351 * Destroy 'fetch'. 352 * 353 * Requires: 354 * 355 *\li '*fetchp' is a valid fetch. 356 * 357 *\li The caller has received the FETCHDONE event (either because the 358 * fetch completed or because dns_resolver_cancelfetch() was called). 359 * 360 * Ensures: 361 * 362 *\li *fetchp == NULL. 363 */ 364 365void 366dns_resolver_logfetch(dns_fetch_t *fetch, isc_log_t *lctx, 367 isc_logcategory_t *category, isc_logmodule_t *module, 368 int level, isc_boolean_t duplicateok); 369/*%< 370 * Dump a log message on internal state at the completion of given 'fetch'. 371 * 'lctx', 'category', 'module', and 'level' are used to write the log message. 372 * By default, only one log message is written even if the corresponding fetch 373 * context serves multiple clients; if 'duplicateok' is true the suppression 374 * is disabled and the message can be written every time this function is 375 * called. 376 * 377 * Requires: 378 * 379 *\li 'fetch' is a valid fetch, and has completed. 380 */ 381 382dns_dispatchmgr_t * 383dns_resolver_dispatchmgr(dns_resolver_t *resolver); 384 385dns_dispatch_t * 386dns_resolver_dispatchv4(dns_resolver_t *resolver); 387 388dns_dispatch_t * 389dns_resolver_dispatchv6(dns_resolver_t *resolver); 390 391isc_socketmgr_t * 392dns_resolver_socketmgr(dns_resolver_t *resolver); 393 394isc_taskmgr_t * 395dns_resolver_taskmgr(dns_resolver_t *resolver); 396 397isc_uint32_t 398dns_resolver_getlamettl(dns_resolver_t *resolver); 399/*%< 400 * Get the resolver's lame-ttl. zero => no lame processing. 401 * 402 * Requires: 403 *\li 'resolver' to be valid. 404 */ 405 406void 407dns_resolver_setlamettl(dns_resolver_t *resolver, isc_uint32_t lame_ttl); 408/*%< 409 * Set the resolver's lame-ttl. zero => no lame processing. 410 * 411 * Requires: 412 *\li 'resolver' to be valid. 413 */ 414 415unsigned int 416dns_resolver_nrunning(dns_resolver_t *resolver); 417/*%< 418 * Return the number of currently running resolutions in this 419 * resolver. This is may be less than the number of outstanding 420 * fetches due to multiple identical fetches, or more than the 421 * number of of outstanding fetches due to the fact that resolution 422 * can continue even though a fetch has been canceled. 423 */ 424 425isc_result_t 426dns_resolver_addalternate(dns_resolver_t *resolver, isc_sockaddr_t *alt, 427 dns_name_t *name, in_port_t port); 428/*%< 429 * Add alternate addresses to be tried in the event that the nameservers 430 * for a zone are not available in the address families supported by the 431 * operating system. 432 * 433 * Require: 434 * \li only one of 'name' or 'alt' to be valid. 435 */ 436 437void 438dns_resolver_setudpsize(dns_resolver_t *resolver, isc_uint16_t udpsize); 439/*%< 440 * Set the EDNS UDP buffer size advertised by the server. 441 */ 442 443isc_uint16_t 444dns_resolver_getudpsize(dns_resolver_t *resolver); 445/*%< 446 * Get the current EDNS UDP buffer size. 447 */ 448 449void 450dns_resolver_reset_algorithms(dns_resolver_t *resolver); 451/*%< 452 * Clear the disabled DNSSEC algorithms. 453 */ 454 455isc_result_t 456dns_resolver_disable_algorithm(dns_resolver_t *resolver, dns_name_t *name, 457 unsigned int alg); 458/*%< 459 * Mark the give DNSSEC algorithm as disabled and below 'name'. 460 * Valid algorithms are less than 256. 461 * 462 * Returns: 463 *\li #ISC_R_SUCCESS 464 *\li #ISC_R_RANGE 465 *\li #ISC_R_NOMEMORY 466 */ 467 468isc_boolean_t 469dns_resolver_algorithm_supported(dns_resolver_t *resolver, dns_name_t *name, 470 unsigned int alg); 471/*%< 472 * Check if the given algorithm is supported by this resolver. 473 * This checks if the algorithm has been disabled via 474 * dns_resolver_disable_algorithm() then the underlying 475 * crypto libraries if not specifically disabled. 476 */ 477 478isc_boolean_t 479dns_resolver_digest_supported(dns_resolver_t *resolver, unsigned int digest_type); 480/*%< 481 * Is this digest type supported. 482 */ 483 484void 485dns_resolver_resetmustbesecure(dns_resolver_t *resolver); 486 487isc_result_t 488dns_resolver_setmustbesecure(dns_resolver_t *resolver, dns_name_t *name, 489 isc_boolean_t value); 490 491isc_boolean_t 492dns_resolver_getmustbesecure(dns_resolver_t *resolver, dns_name_t *name); 493 494void 495dns_resolver_setclientsperquery(dns_resolver_t *resolver, 496 isc_uint32_t min, isc_uint32_t max); 497 498void 499dns_resolver_getclientsperquery(dns_resolver_t *resolver, isc_uint32_t *cur, 500 isc_uint32_t *min, isc_uint32_t *max); 501 502isc_boolean_t 503dns_resolver_getzeronosoattl(dns_resolver_t *resolver); 504 505void 506dns_resolver_setzeronosoattl(dns_resolver_t *resolver, isc_boolean_t state); 507 508unsigned int 509dns_resolver_getoptions(dns_resolver_t *resolver); 510 511void 512dns_resolver_addbadcache(dns_resolver_t *resolver, dns_name_t *name, 513 dns_rdatatype_t type, isc_time_t *expire); 514/*%< 515 * Add a entry to the bad cache for <name,type> that will expire at 'expire'. 516 * 517 * Requires: 518 * \li resolver to be valid. 519 * \li name to be valid. 520 */ 521 522isc_boolean_t 523dns_resolver_getbadcache(dns_resolver_t *resolver, dns_name_t *name, 524 dns_rdatatype_t type, isc_time_t *now); 525/*%< 526 * Check to see if there is a unexpired entry in the bad cache for 527 * <name,type>. 528 * 529 * Requires: 530 * \li resolver to be valid. 531 * \li name to be valid. 532 */ 533 534void 535dns_resolver_flushbadcache(dns_resolver_t *resolver, dns_name_t *name); 536/*%< 537 * Flush the bad cache of all entries at 'name' if 'name' is non NULL. 538 * Flush the entire bad cache if 'name' is NULL. 539 * 540 * Requires: 541 * \li resolver to be valid. 542 */ 543 544void 545dns_resolver_printbadcache(dns_resolver_t *resolver, FILE *fp); 546/*% 547 * Print out the contents of the bad cache to 'fp'. 548 * 549 * Requires: 550 * \li resolver to be valid. 551 */ 552 553ISC_LANG_ENDDECLS 554 555#endif /* DNS_RESOLVER_H */ 556