resolver.h revision 170222
1135446Strhodes/* 2170222Sdougb * Copyright (C) 2004-2006 Internet Systems Consortium, Inc. ("ISC") 3135446Strhodes * Copyright (C) 1999-2001, 2003 Internet Software Consortium. 4135446Strhodes * 5135446Strhodes * Permission to use, copy, modify, and distribute this software for any 6135446Strhodes * purpose with or without fee is hereby granted, provided that the above 7135446Strhodes * copyright notice and this permission notice appear in all copies. 8135446Strhodes * 9135446Strhodes * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10135446Strhodes * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11135446Strhodes * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12135446Strhodes * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13135446Strhodes * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14135446Strhodes * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15135446Strhodes * PERFORMANCE OF THIS SOFTWARE. 16135446Strhodes */ 17135446Strhodes 18170222Sdougb/* $Id: resolver.h,v 1.40.18.11 2006/02/01 22:39:17 marka Exp $ */ 19135446Strhodes 20135446Strhodes#ifndef DNS_RESOLVER_H 21135446Strhodes#define DNS_RESOLVER_H 1 22135446Strhodes 23135446Strhodes/***** 24135446Strhodes ***** Module Info 25135446Strhodes *****/ 26135446Strhodes 27170222Sdougb/*! \file 28135446Strhodes * 29170222Sdougb * \brief 30135446Strhodes * This is the BIND 9 resolver, the module responsible for resolving DNS 31135446Strhodes * requests by iteratively querying authoritative servers and following 32135446Strhodes * referrals. This is a "full resolver", not to be confused with 33135446Strhodes * the stub resolvers most people associate with the word "resolver". 34135446Strhodes * The full resolver is part of the caching name server or resolver 35135446Strhodes * daemon the stub resolver talks to. 36135446Strhodes * 37135446Strhodes * MP: 38170222Sdougb *\li The module ensures appropriate synchronization of data structures it 39135446Strhodes * creates and manipulates. 40135446Strhodes * 41135446Strhodes * Reliability: 42170222Sdougb *\li No anticipated impact. 43135446Strhodes * 44135446Strhodes * Resources: 45170222Sdougb *\li TBS 46135446Strhodes * 47135446Strhodes * Security: 48170222Sdougb *\li No anticipated impact. 49135446Strhodes * 50135446Strhodes * Standards: 51170222Sdougb *\li RFCs: 1034, 1035, 2181, TBS 52170222Sdougb *\li Drafts: TBS 53135446Strhodes */ 54135446Strhodes 55135446Strhodes#include <isc/lang.h> 56135446Strhodes#include <isc/socket.h> 57135446Strhodes 58135446Strhodes#include <dns/types.h> 59135446Strhodes#include <dns/fixedname.h> 60135446Strhodes 61135446StrhodesISC_LANG_BEGINDECLS 62135446Strhodes 63170222Sdougb/*% 64135446Strhodes * A dns_fetchevent_t is sent when a 'fetch' completes. Any of 'db', 65135446Strhodes * 'node', 'rdataset', and 'sigrdataset' may be bound. It is the 66135446Strhodes * receiver's responsibility to detach before freeing the event. 67170222Sdougb * \brief 68170222Sdougb * 'rdataset', 'sigrdataset', 'client' and 'id' are the values that were 69170222Sdougb * supplied when dns_resolver_createfetch() was called. They are returned 70170222Sdougb * to the caller so that they may be freed. 71135446Strhodes */ 72135446Strhodestypedef struct dns_fetchevent { 73135446Strhodes ISC_EVENT_COMMON(struct dns_fetchevent); 74135446Strhodes dns_fetch_t * fetch; 75135446Strhodes isc_result_t result; 76135446Strhodes dns_rdatatype_t qtype; 77135446Strhodes dns_db_t * db; 78135446Strhodes dns_dbnode_t * node; 79135446Strhodes dns_rdataset_t * rdataset; 80135446Strhodes dns_rdataset_t * sigrdataset; 81135446Strhodes dns_fixedname_t foundname; 82170222Sdougb isc_sockaddr_t * client; 83170222Sdougb dns_messageid_t id; 84135446Strhodes} dns_fetchevent_t; 85135446Strhodes 86135446Strhodes/* 87135446Strhodes * Options that modify how a 'fetch' is done. 88135446Strhodes */ 89170222Sdougb#define DNS_FETCHOPT_TCP 0x01 /*%< Use TCP. */ 90170222Sdougb#define DNS_FETCHOPT_UNSHARED 0x02 /*%< See below. */ 91170222Sdougb#define DNS_FETCHOPT_RECURSIVE 0x04 /*%< Set RD? */ 92170222Sdougb#define DNS_FETCHOPT_NOEDNS0 0x08 /*%< Do not use EDNS. */ 93170222Sdougb#define DNS_FETCHOPT_FORWARDONLY 0x10 /*%< Only use forwarders. */ 94170222Sdougb#define DNS_FETCHOPT_NOVALIDATE 0x20 /*%< Disable validation. */ 95170222Sdougb#define DNS_FETCHOPT_EDNS512 0x40 /*%< Advertise a 512 byte 96170222Sdougb UDP buffer. */ 97135446Strhodes 98170222Sdougb#define DNS_FETCHOPT_EDNSVERSIONSET 0x00800000 99170222Sdougb#define DNS_FETCHOPT_EDNSVERSIONMASK 0xff000000 100170222Sdougb#define DNS_FETCHOPT_EDNSVERSIONSHIFT 24 101170222Sdougb 102135446Strhodes/* 103135446Strhodes * XXXRTH Should this API be made semi-private? (I.e. 104135446Strhodes * _dns_resolver_create()). 105135446Strhodes */ 106135446Strhodes 107135446Strhodes#define DNS_RESOLVER_CHECKNAMES 0x01 108135446Strhodes#define DNS_RESOLVER_CHECKNAMESFAIL 0x02 109135446Strhodes 110135446Strhodesisc_result_t 111135446Strhodesdns_resolver_create(dns_view_t *view, 112135446Strhodes isc_taskmgr_t *taskmgr, unsigned int ntasks, 113135446Strhodes isc_socketmgr_t *socketmgr, 114135446Strhodes isc_timermgr_t *timermgr, 115135446Strhodes unsigned int options, 116135446Strhodes dns_dispatchmgr_t *dispatchmgr, 117135446Strhodes dns_dispatch_t *dispatchv4, 118135446Strhodes dns_dispatch_t *dispatchv6, 119135446Strhodes dns_resolver_t **resp); 120135446Strhodes 121170222Sdougb/*%< 122135446Strhodes * Create a resolver. 123135446Strhodes * 124135446Strhodes * Notes: 125135446Strhodes * 126170222Sdougb *\li Generally, applications should not create a resolver directly, but 127135446Strhodes * should instead call dns_view_createresolver(). 128135446Strhodes * 129170222Sdougb *\li No options are currently defined. 130135446Strhodes * 131135446Strhodes * Requires: 132135446Strhodes * 133170222Sdougb *\li 'view' is a valid view. 134135446Strhodes * 135170222Sdougb *\li 'taskmgr' is a valid task manager. 136135446Strhodes * 137170222Sdougb *\li 'ntasks' > 0. 138135446Strhodes * 139170222Sdougb *\li 'socketmgr' is a valid socket manager. 140135446Strhodes * 141170222Sdougb *\li 'timermgr' is a valid timer manager. 142135446Strhodes * 143170222Sdougb *\li 'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL. 144135446Strhodes * 145170222Sdougb *\li 'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL. 146135446Strhodes * 147170222Sdougb *\li resp != NULL && *resp == NULL. 148135446Strhodes * 149135446Strhodes * Returns: 150135446Strhodes * 151170222Sdougb *\li #ISC_R_SUCCESS On success. 152135446Strhodes * 153170222Sdougb *\li Anything else Failure. 154135446Strhodes */ 155135446Strhodes 156135446Strhodesvoid 157135446Strhodesdns_resolver_freeze(dns_resolver_t *res); 158170222Sdougb/*%< 159135446Strhodes * Freeze resolver. 160135446Strhodes * 161135446Strhodes * Notes: 162135446Strhodes * 163170222Sdougb *\li Certain configuration changes cannot be made after the resolver 164135446Strhodes * is frozen. Fetches cannot be created until the resolver is frozen. 165135446Strhodes * 166135446Strhodes * Requires: 167135446Strhodes * 168170222Sdougb *\li 'res' is a valid, unfrozen resolver. 169135446Strhodes * 170135446Strhodes * Ensures: 171135446Strhodes * 172170222Sdougb *\li 'res' is frozen. 173135446Strhodes */ 174135446Strhodes 175135446Strhodesvoid 176135446Strhodesdns_resolver_prime(dns_resolver_t *res); 177170222Sdougb/*%< 178135446Strhodes * Prime resolver. 179135446Strhodes * 180135446Strhodes * Notes: 181135446Strhodes * 182170222Sdougb *\li Resolvers which have a forwarding policy other than dns_fwdpolicy_only 183135446Strhodes * need to be primed with the root nameservers, otherwise the root 184135446Strhodes * nameserver hints data may be used indefinitely. This function requests 185135446Strhodes * that the resolver start a priming fetch, if it isn't already priming. 186135446Strhodes * 187135446Strhodes * Requires: 188135446Strhodes * 189170222Sdougb *\li 'res' is a valid, frozen resolver. 190135446Strhodes */ 191135446Strhodes 192135446Strhodes 193135446Strhodesvoid 194135446Strhodesdns_resolver_whenshutdown(dns_resolver_t *res, isc_task_t *task, 195135446Strhodes isc_event_t **eventp); 196170222Sdougb/*%< 197135446Strhodes * Send '*eventp' to 'task' when 'res' has completed shutdown. 198135446Strhodes * 199135446Strhodes * Notes: 200135446Strhodes * 201170222Sdougb *\li It is not safe to detach the last reference to 'res' until 202135446Strhodes * shutdown is complete. 203135446Strhodes * 204135446Strhodes * Requires: 205135446Strhodes * 206170222Sdougb *\li 'res' is a valid resolver. 207135446Strhodes * 208170222Sdougb *\li 'task' is a valid task. 209135446Strhodes * 210170222Sdougb *\li *eventp is a valid event. 211135446Strhodes * 212135446Strhodes * Ensures: 213135446Strhodes * 214170222Sdougb *\li *eventp == NULL. 215135446Strhodes */ 216135446Strhodes 217135446Strhodesvoid 218135446Strhodesdns_resolver_shutdown(dns_resolver_t *res); 219170222Sdougb/*%< 220135446Strhodes * Start the shutdown process for 'res'. 221135446Strhodes * 222135446Strhodes * Notes: 223135446Strhodes * 224170222Sdougb *\li This call has no effect if the resolver is already shutting down. 225135446Strhodes * 226135446Strhodes * Requires: 227135446Strhodes * 228170222Sdougb *\li 'res' is a valid resolver. 229135446Strhodes */ 230135446Strhodes 231135446Strhodesvoid 232135446Strhodesdns_resolver_attach(dns_resolver_t *source, dns_resolver_t **targetp); 233135446Strhodes 234135446Strhodesvoid 235135446Strhodesdns_resolver_detach(dns_resolver_t **resp); 236135446Strhodes 237135446Strhodesisc_result_t 238135446Strhodesdns_resolver_createfetch(dns_resolver_t *res, dns_name_t *name, 239135446Strhodes dns_rdatatype_t type, 240135446Strhodes dns_name_t *domain, dns_rdataset_t *nameservers, 241135446Strhodes dns_forwarders_t *forwarders, 242135446Strhodes unsigned int options, isc_task_t *task, 243135446Strhodes isc_taskaction_t action, void *arg, 244135446Strhodes dns_rdataset_t *rdataset, 245135446Strhodes dns_rdataset_t *sigrdataset, 246135446Strhodes dns_fetch_t **fetchp); 247170222Sdougb 248170222Sdougbisc_result_t 249170222Sdougbdns_resolver_createfetch2(dns_resolver_t *res, dns_name_t *name, 250170222Sdougb dns_rdatatype_t type, 251170222Sdougb dns_name_t *domain, dns_rdataset_t *nameservers, 252170222Sdougb dns_forwarders_t *forwarders, 253170222Sdougb isc_sockaddr_t *client, isc_uint16_t id, 254170222Sdougb unsigned int options, isc_task_t *task, 255170222Sdougb isc_taskaction_t action, void *arg, 256170222Sdougb dns_rdataset_t *rdataset, 257170222Sdougb dns_rdataset_t *sigrdataset, 258170222Sdougb dns_fetch_t **fetchp); 259170222Sdougb/*%< 260135446Strhodes * Recurse to answer a question. 261135446Strhodes * 262135446Strhodes * Notes: 263135446Strhodes * 264170222Sdougb *\li This call starts a query for 'name', type 'type'. 265135446Strhodes * 266170222Sdougb *\li The 'domain' is a parent domain of 'name' for which 267135446Strhodes * a set of name servers 'nameservers' is known. If no 268135446Strhodes * such name server information is available, set 269135446Strhodes * 'domain' and 'nameservers' to NULL. 270135446Strhodes * 271170222Sdougb *\li 'forwarders' is unimplemented, and subject to change when 272135446Strhodes * we figure out how selective forwarding will work. 273135446Strhodes * 274170222Sdougb *\li When the fetch completes (successfully or otherwise), a 275170222Sdougb * #DNS_EVENT_FETCHDONE event with action 'action' and arg 'arg' will be 276135446Strhodes * posted to 'task'. 277135446Strhodes * 278170222Sdougb *\li The values of 'rdataset' and 'sigrdataset' will be returned in 279135446Strhodes * the FETCHDONE event. 280135446Strhodes * 281170222Sdougb *\li 'client' and 'id' are used for duplicate query detection. '*client' 282170222Sdougb * must remain stable until after 'action' has been called or 283170222Sdougb * dns_resolver_cancelfetch() is called. 284170222Sdougb * 285135446Strhodes * Requires: 286135446Strhodes * 287170222Sdougb *\li 'res' is a valid resolver that has been frozen. 288135446Strhodes * 289170222Sdougb *\li 'name' is a valid name. 290135446Strhodes * 291170222Sdougb *\li 'type' is not a meta type other than ANY. 292135446Strhodes * 293170222Sdougb *\li 'domain' is a valid name or NULL. 294135446Strhodes * 295170222Sdougb *\li 'nameservers' is a valid NS rdataset (whose owner name is 'domain') 296135446Strhodes * iff. 'domain' is not NULL. 297135446Strhodes * 298170222Sdougb *\li 'forwarders' is NULL. 299135446Strhodes * 300170222Sdougb *\li 'client' is a valid sockaddr or NULL. 301135446Strhodes * 302170222Sdougb *\li 'options' contains valid options. 303135446Strhodes * 304170222Sdougb *\li 'rdataset' is a valid, disassociated rdataset. 305135446Strhodes * 306170222Sdougb *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset. 307135446Strhodes * 308170222Sdougb *\li fetchp != NULL && *fetchp == NULL. 309170222Sdougb * 310135446Strhodes * Returns: 311135446Strhodes * 312170222Sdougb *\li #ISC_R_SUCCESS Success 313170222Sdougb *\li #DNS_R_DUPLICATE 314170222Sdougb *\li #DNS_R_DROP 315135446Strhodes * 316170222Sdougb *\li Many other values are possible, all of which indicate failure. 317135446Strhodes */ 318135446Strhodes 319135446Strhodesvoid 320135446Strhodesdns_resolver_cancelfetch(dns_fetch_t *fetch); 321170222Sdougb/*%< 322135446Strhodes * Cancel 'fetch'. 323135446Strhodes * 324135446Strhodes * Notes: 325135446Strhodes * 326170222Sdougb *\li If 'fetch' has not completed, post its FETCHDONE event with a 327170222Sdougb * result code of #ISC_R_CANCELED. 328135446Strhodes * 329135446Strhodes * Requires: 330135446Strhodes * 331170222Sdougb *\li 'fetch' is a valid fetch. 332135446Strhodes */ 333135446Strhodes 334135446Strhodesvoid 335135446Strhodesdns_resolver_destroyfetch(dns_fetch_t **fetchp); 336170222Sdougb/*%< 337135446Strhodes * Destroy 'fetch'. 338135446Strhodes * 339135446Strhodes * Requires: 340135446Strhodes * 341170222Sdougb *\li '*fetchp' is a valid fetch. 342135446Strhodes * 343170222Sdougb *\li The caller has received the FETCHDONE event (either because the 344135446Strhodes * fetch completed or because dns_resolver_cancelfetch() was called). 345135446Strhodes * 346135446Strhodes * Ensures: 347135446Strhodes * 348170222Sdougb *\li *fetchp == NULL. 349135446Strhodes */ 350135446Strhodes 351135446Strhodesdns_dispatchmgr_t * 352135446Strhodesdns_resolver_dispatchmgr(dns_resolver_t *resolver); 353135446Strhodes 354135446Strhodesdns_dispatch_t * 355135446Strhodesdns_resolver_dispatchv4(dns_resolver_t *resolver); 356135446Strhodes 357135446Strhodesdns_dispatch_t * 358135446Strhodesdns_resolver_dispatchv6(dns_resolver_t *resolver); 359135446Strhodes 360135446Strhodesisc_socketmgr_t * 361135446Strhodesdns_resolver_socketmgr(dns_resolver_t *resolver); 362135446Strhodes 363135446Strhodesisc_taskmgr_t * 364135446Strhodesdns_resolver_taskmgr(dns_resolver_t *resolver); 365135446Strhodes 366135446Strhodesisc_uint32_t 367135446Strhodesdns_resolver_getlamettl(dns_resolver_t *resolver); 368170222Sdougb/*%< 369135446Strhodes * Get the resolver's lame-ttl. zero => no lame processing. 370135446Strhodes * 371135446Strhodes * Requires: 372170222Sdougb *\li 'resolver' to be valid. 373135446Strhodes */ 374135446Strhodes 375135446Strhodesvoid 376135446Strhodesdns_resolver_setlamettl(dns_resolver_t *resolver, isc_uint32_t lame_ttl); 377170222Sdougb/*%< 378135446Strhodes * Set the resolver's lame-ttl. zero => no lame processing. 379135446Strhodes * 380135446Strhodes * Requires: 381170222Sdougb *\li 'resolver' to be valid. 382135446Strhodes */ 383135446Strhodes 384135446Strhodesunsigned int 385135446Strhodesdns_resolver_nrunning(dns_resolver_t *resolver); 386170222Sdougb/*%< 387135446Strhodes * Return the number of currently running resolutions in this 388135446Strhodes * resolver. This is may be less than the number of outstanding 389135446Strhodes * fetches due to multiple identical fetches, or more than the 390135446Strhodes * number of of outstanding fetches due to the fact that resolution 391135446Strhodes * can continue even though a fetch has been canceled. 392135446Strhodes */ 393135446Strhodes 394135446Strhodesisc_result_t 395135446Strhodesdns_resolver_addalternate(dns_resolver_t *resolver, isc_sockaddr_t *alt, 396135446Strhodes dns_name_t *name, in_port_t port); 397170222Sdougb/*%< 398135446Strhodes * Add alternate addresses to be tried in the event that the nameservers 399135446Strhodes * for a zone are not available in the address families supported by the 400135446Strhodes * operating system. 401135446Strhodes * 402135446Strhodes * Require: 403170222Sdougb * \li only one of 'name' or 'alt' to be valid. 404135446Strhodes */ 405135446Strhodes 406135446Strhodesvoid 407135446Strhodesdns_resolver_setudpsize(dns_resolver_t *resolver, isc_uint16_t udpsize); 408170222Sdougb/*%< 409135446Strhodes * Set the EDNS UDP buffer size advertised by the server. 410135446Strhodes */ 411135446Strhodes 412135446Strhodesisc_uint16_t 413135446Strhodesdns_resolver_getudpsize(dns_resolver_t *resolver); 414170222Sdougb/*%< 415135446Strhodes * Get the current EDNS UDP buffer size. 416135446Strhodes */ 417135446Strhodes 418135446Strhodesvoid 419135446Strhodesdns_resolver_reset_algorithms(dns_resolver_t *resolver); 420170222Sdougb/*%< 421135446Strhodes * Clear the disabled DNSSEC algorithms. 422135446Strhodes */ 423135446Strhodes 424135446Strhodesisc_result_t 425135446Strhodesdns_resolver_disable_algorithm(dns_resolver_t *resolver, dns_name_t *name, 426135446Strhodes unsigned int alg); 427170222Sdougb/*%< 428135446Strhodes * Mark the give DNSSEC algorithm as disabled and below 'name'. 429135446Strhodes * Valid algorithms are less than 256. 430135446Strhodes * 431135446Strhodes * Returns: 432170222Sdougb *\li #ISC_R_SUCCESS 433170222Sdougb *\li #ISC_R_RANGE 434170222Sdougb *\li #ISC_R_NOMEMORY 435135446Strhodes */ 436135446Strhodes 437135446Strhodesisc_boolean_t 438135446Strhodesdns_resolver_algorithm_supported(dns_resolver_t *resolver, dns_name_t *name, 439135446Strhodes unsigned int alg); 440170222Sdougb/*%< 441135446Strhodes * Check if the given algorithm is supported by this resolver. 442135446Strhodes * This checks if the algorithm has been disabled via 443135446Strhodes * dns_resolver_disable_algorithm() then the underlying 444135446Strhodes * crypto libraries if not specifically disabled. 445135446Strhodes */ 446135446Strhodes 447170222Sdougbisc_boolean_t 448170222Sdougbdns_resolver_digest_supported(dns_resolver_t *resolver, unsigned int digest_type); 449170222Sdougb/*%< 450170222Sdougb * Is this digest type supported. 451170222Sdougb */ 452170222Sdougb 453135446Strhodesvoid 454135446Strhodesdns_resolver_resetmustbesecure(dns_resolver_t *resolver); 455135446Strhodes 456135446Strhodesisc_result_t 457135446Strhodesdns_resolver_setmustbesecure(dns_resolver_t *resolver, dns_name_t *name, 458135446Strhodes isc_boolean_t value); 459135446Strhodes 460135446Strhodesisc_boolean_t 461135446Strhodesdns_resolver_getmustbesecure(dns_resolver_t *resolver, dns_name_t *name); 462135446Strhodes 463170222Sdougbvoid 464170222Sdougbdns_resolver_setclientsperquery(dns_resolver_t *resolver, 465170222Sdougb isc_uint32_t min, isc_uint32_t max); 466170222Sdougb 467170222Sdougbvoid 468170222Sdougbdns_resolver_getclientsperquery(dns_resolver_t *resolver, isc_uint32_t *cur, 469170222Sdougb isc_uint32_t *min, isc_uint32_t *max); 470170222Sdougb 471170222Sdougbisc_boolean_t 472170222Sdougbdns_resolver_getzeronosoattl(dns_resolver_t *resolver); 473170222Sdougb 474170222Sdougbvoid 475170222Sdougbdns_resolver_setzeronosoattl(dns_resolver_t *resolver, isc_boolean_t state); 476170222Sdougb 477135446StrhodesISC_LANG_ENDDECLS 478135446Strhodes 479135446Strhodes#endif /* DNS_RESOLVER_H */ 480