resolver.h 12.8 KB
Newer Older
Bob Halley's avatar
Bob Halley committed
1
/*
Mark Andrews's avatar
Mark Andrews committed
2
 * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
Mark Andrews's avatar
Mark Andrews committed
3
 * Copyright (C) 1999-2001, 2003  Internet Software Consortium.
4
 *
Bob Halley's avatar
Bob Halley committed
5 6 7
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
8
 *
Mark Andrews's avatar
Mark Andrews committed
9 10 11 12 13 14 15
 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
Bob Halley's avatar
Bob Halley committed
16 17
 */

Mark Andrews's avatar
Mark Andrews committed
18
/* $Id: resolver.h,v 1.55 2007/02/06 00:01:23 marka Exp $ */
David Lawrence's avatar
David Lawrence committed
19

Bob Halley's avatar
Bob Halley committed
20 21 22 23 24 25 26
#ifndef DNS_RESOLVER_H
#define DNS_RESOLVER_H 1

/*****
 ***** Module Info
 *****/

27
/*! \file dns/resolver.h
Bob Halley's avatar
Bob Halley committed
28
 *
29
 * \brief
Andreas Gustafsson's avatar
Andreas Gustafsson committed
30 31 32 33 34 35
 * This is the BIND 9 resolver, the module responsible for resolving DNS
 * requests by iteratively querying authoritative servers and following
 * referrals.  This is a "full resolver", not to be confused with
 * the stub resolvers most people associate with the word "resolver".
 * The full resolver is part of the caching name server or resolver
 * daemon the stub resolver talks to.
Bob Halley's avatar
Bob Halley committed
36 37
 *
 * MP:
38
 *\li	The module ensures appropriate synchronization of data structures it
Bob Halley's avatar
Bob Halley committed
39 40 41
 *	creates and manipulates.
 *
 * Reliability:
42
 *\li	No anticipated impact.
Bob Halley's avatar
Bob Halley committed
43 44
 *
 * Resources:
45
 *\li	TBS
Bob Halley's avatar
Bob Halley committed
46 47
 *
 * Security:
48
 *\li	No anticipated impact.
Bob Halley's avatar
Bob Halley committed
49 50
 *
 * Standards:
51 52
 *\li	RFCs:	1034, 1035, 2181, TBS
 *\li	Drafts:	TBS
Bob Halley's avatar
Bob Halley committed
53 54 55
 */

#include <isc/lang.h>
Bob Halley's avatar
Bob Halley committed
56
#include <isc/socket.h>
Bob Halley's avatar
Bob Halley committed
57 58

#include <dns/types.h>
Bob Halley's avatar
Bob Halley committed
59
#include <dns/fixedname.h>
Bob Halley's avatar
Bob Halley committed
60 61 62

ISC_LANG_BEGINDECLS

63
/*%
Bob Halley's avatar
Bob Halley committed
64 65 66
 * A dns_fetchevent_t is sent when a 'fetch' completes.  Any of 'db',
 * 'node', 'rdataset', and 'sigrdataset' may be bound.  It is the
 * receiver's responsibility to detach before freeing the event.
67
 * \brief
68 69 70
 * 'rdataset', 'sigrdataset', 'client' and 'id' are the values that were
 * supplied when dns_resolver_createfetch() was called.  They are returned
 *  to the caller so that they may be freed.
Bob Halley's avatar
Bob Halley committed
71
 */
Bob Halley's avatar
Bob Halley committed
72 73
typedef struct dns_fetchevent {
	ISC_EVENT_COMMON(struct dns_fetchevent);
Bob Halley's avatar
Bob Halley committed
74
	dns_fetch_t *			fetch;
75
	isc_result_t			result;
Bob Halley's avatar
Bob Halley committed
76 77 78 79 80 81
	dns_rdatatype_t			qtype;
	dns_db_t *			db;
	dns_dbnode_t *			node;
	dns_rdataset_t *		rdataset;
	dns_rdataset_t *		sigrdataset;
	dns_fixedname_t			foundname;
82 83
	isc_sockaddr_t *		client;
	dns_messageid_t			id;
Bob Halley's avatar
Bob Halley committed
84
} dns_fetchevent_t;
Bob Halley's avatar
Bob Halley committed
85

Bob Halley's avatar
Bob Halley committed
86 87 88
/*
 * Options that modify how a 'fetch' is done.
 */
89 90 91 92 93 94
#define DNS_FETCHOPT_TCP		0x01	     /*%< Use TCP. */
#define DNS_FETCHOPT_UNSHARED		0x02	     /*%< See below. */
#define DNS_FETCHOPT_RECURSIVE		0x04	     /*%< Set RD? */
#define DNS_FETCHOPT_NOEDNS0		0x08	     /*%< Do not use EDNS. */
#define DNS_FETCHOPT_FORWARDONLY	0x10	     /*%< Only use forwarders. */
#define DNS_FETCHOPT_NOVALIDATE		0x20	     /*%< Disable validation. */
95 96
#define DNS_FETCHOPT_EDNS512		0x40	     /*%< Advertise a 512 byte
						          UDP buffer. */
Bob Halley's avatar
Bob Halley committed
97

98 99 100 101
#define	DNS_FETCHOPT_EDNSVERSIONSET	0x00800000
#define	DNS_FETCHOPT_EDNSVERSIONMASK	0xff000000
#define	DNS_FETCHOPT_EDNSVERSIONSHIFT	24

Bob Halley's avatar
Bob Halley committed
102 103 104 105
/*
 * XXXRTH  Should this API be made semi-private?  (I.e.
 * _dns_resolver_create()).
 */
Bob Halley's avatar
Bob Halley committed
106

107 108
#define DNS_RESOLVER_CHECKNAMES		0x01
#define DNS_RESOLVER_CHECKNAMESFAIL	0x02
109 110
#define DNS_RESOLVER_USEDISPATCHPOOL4	0x04
#define DNS_RESOLVER_USEDISPATCHPOOL6	0x08
111

112
isc_result_t
Bob Halley's avatar
Bob Halley committed
113
dns_resolver_create(dns_view_t *view,
Bob Halley's avatar
Bob Halley committed
114
		    isc_taskmgr_t *taskmgr, unsigned int ntasks,
Bob Halley's avatar
Bob Halley committed
115 116
		    isc_socketmgr_t *socketmgr,
		    isc_timermgr_t *timermgr,
117
		    unsigned int options,
118
		    dns_dispatchmgr_t *dispatchmgr,
119 120 121
		    dns_dispatch_t *dispatchv4,
		    dns_dispatch_t *dispatchv6,
		    dns_resolver_t **resp);
122

123
/*%<
Bob Halley's avatar
Bob Halley committed
124 125 126 127
 * Create a resolver.
 *
 * Notes:
 *
128
 *\li	Generally, applications should not create a resolver directly, but
Bob Halley's avatar
Bob Halley committed
129 130 131 132
 *	should instead call dns_view_createresolver().
 *
 * Requires:
 *
133
 *\li	'view' is a valid view.
Bob Halley's avatar
Bob Halley committed
134
 *
135
 *\li	'taskmgr' is a valid task manager.
Bob Halley's avatar
Bob Halley committed
136
 *
137
 *\li	'ntasks' > 0.
Bob Halley's avatar
Bob Halley committed
138
 *
139
 *\li	'socketmgr' is a valid socket manager.
Bob Halley's avatar
Bob Halley committed
140
 *
141
 *\li	'timermgr' is a valid timer manager.
Bob Halley's avatar
Bob Halley committed
142
 *
143
 *\li	'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL.
144
 *
145
 *\li	'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.
Bob Halley's avatar
Bob Halley committed
146
 *
Mark Andrews's avatar
Mark Andrews committed
147
 *\li	resp != NULL && *resp == NULL.
Bob Halley's avatar
Bob Halley committed
148 149 150
 *
 * Returns:
 *
151
 *\li	#ISC_R_SUCCESS				On success.
Bob Halley's avatar
Bob Halley committed
152
 *
153
 *\li	Anything else				Failure.
Bob Halley's avatar
Bob Halley committed
154
 */
Bob Halley's avatar
Bob Halley committed
155

156 157
void
dns_resolver_freeze(dns_resolver_t *res);
158
/*%<
159 160 161 162
 * Freeze resolver.
 *
 * Notes:
 *
163
 *\li	Certain configuration changes cannot be made after the resolver
164
 *	is frozen.  Fetches cannot be created until the resolver is frozen.
165 166 167
 *
 * Requires:
 *
168
 *\li	'res' is a valid, unfrozen resolver.
169 170 171
 *
 * Ensures:
 *
172
 *\li	'res' is frozen.
173 174
 */

Bob Halley's avatar
Bob Halley committed
175 176
void
dns_resolver_prime(dns_resolver_t *res);
177
/*%<
Bob Halley's avatar
Bob Halley committed
178 179 180 181
 * Prime resolver.
 *
 * Notes:
 *
182
 *\li	Resolvers which have a forwarding policy other than dns_fwdpolicy_only
Bob Halley's avatar
Bob Halley committed
183 184 185 186 187 188
 *	need to be primed with the root nameservers, otherwise the root
 *	nameserver hints data may be used indefinitely.  This function requests
 *	that the resolver start a priming fetch, if it isn't already priming.
 *
 * Requires:
 *
189
 *\li	'res' is a valid, frozen resolver.
Bob Halley's avatar
Bob Halley committed
190 191 192
 */


193 194 195
void
dns_resolver_whenshutdown(dns_resolver_t *res, isc_task_t *task,
			  isc_event_t **eventp);
196
/*%<
Bob Halley's avatar
Bob Halley committed
197 198 199 200
 * Send '*eventp' to 'task' when 'res' has completed shutdown.
 *
 * Notes:
 *
201
 *\li	It is not safe to detach the last reference to 'res' until
Bob Halley's avatar
Bob Halley committed
202 203 204 205
 *	shutdown is complete.
 *
 * Requires:
 *
206
 *\li	'res' is a valid resolver.
Bob Halley's avatar
Bob Halley committed
207
 *
208
 *\li	'task' is a valid task.
Bob Halley's avatar
Bob Halley committed
209
 *
210
 *\li	*eventp is a valid event.
Bob Halley's avatar
Bob Halley committed
211 212 213
 *
 * Ensures:
 *
214
 *\li	*eventp == NULL.
Bob Halley's avatar
Bob Halley committed
215
 */
216 217 218

void
dns_resolver_shutdown(dns_resolver_t *res);
219
/*%<
Bob Halley's avatar
Bob Halley committed
220 221 222 223
 * Start the shutdown process for 'res'.
 *
 * Notes:
 *
224
 *\li	This call has no effect if the resolver is already shutting down.
Bob Halley's avatar
Bob Halley committed
225 226 227
 *
 * Requires:
 *
228
 *\li	'res' is a valid resolver.
Bob Halley's avatar
Bob Halley committed
229
 */
230

Bob Halley's avatar
Bob Halley committed
231 232 233 234 235 236
void
dns_resolver_attach(dns_resolver_t *source, dns_resolver_t **targetp);

void
dns_resolver_detach(dns_resolver_t **resp);

237
isc_result_t
Bob Halley's avatar
Bob Halley committed
238 239
dns_resolver_createfetch(dns_resolver_t *res, dns_name_t *name,
			 dns_rdatatype_t type,
Bob Halley's avatar
Bob Halley committed
240
			 dns_name_t *domain, dns_rdataset_t *nameservers,
Bob Halley's avatar
Bob Halley committed
241 242 243
			 dns_forwarders_t *forwarders,
			 unsigned int options, isc_task_t *task,
			 isc_taskaction_t action, void *arg,
Bob Halley's avatar
Bob Halley committed
244
			 dns_rdataset_t *rdataset,
245
			 dns_rdataset_t *sigrdataset,
Bob Halley's avatar
Bob Halley committed
246
			 dns_fetch_t **fetchp);
247 248 249 250 251 252 253 254 255 256 257 258

isc_result_t
dns_resolver_createfetch2(dns_resolver_t *res, dns_name_t *name,
			  dns_rdatatype_t type,
			  dns_name_t *domain, dns_rdataset_t *nameservers,
			  dns_forwarders_t *forwarders,
			  isc_sockaddr_t *client, isc_uint16_t id,
			  unsigned int options, isc_task_t *task,
			  isc_taskaction_t action, void *arg,
			  dns_rdataset_t *rdataset,
			  dns_rdataset_t *sigrdataset,
			  dns_fetch_t **fetchp);
259
/*%<
Bob Halley's avatar
Bob Halley committed
260 261 262 263
 * Recurse to answer a question.
 *
 * Notes:
 *
264
 *\li	This call starts a query for 'name', type 'type'.
Bob Halley's avatar
Bob Halley committed
265
 *
266
 *\li	The 'domain' is a parent domain of 'name' for which
Andreas Gustafsson's avatar
Andreas Gustafsson committed
267
 *	a set of name servers 'nameservers' is known.  If no
268
 *	such name server information is available, set
Andreas Gustafsson's avatar
Andreas Gustafsson committed
269 270
 * 	'domain' and 'nameservers' to NULL.
 *
271
 *\li	'forwarders' is unimplemented, and subject to change when
Andreas Gustafsson's avatar
Andreas Gustafsson committed
272
 *	we figure out how selective forwarding will work.
Bob Halley's avatar
Bob Halley committed
273
 *
274 275
 *\li	When the fetch completes (successfully or otherwise), a
 *	#DNS_EVENT_FETCHDONE event with action 'action' and arg 'arg' will be
Bob Halley's avatar
Bob Halley committed
276 277
 *	posted to 'task'.
 *
278
 *\li	The values of 'rdataset' and 'sigrdataset' will be returned in
Bob Halley's avatar
Bob Halley committed
279 280
 *	the FETCHDONE event.
 *
281 282 283 284
 *\li	'client' and 'id' are used for duplicate query detection.  '*client'
 *	must remain stable until after 'action' has been called or
 *	dns_resolver_cancelfetch() is called.
 *
Bob Halley's avatar
Bob Halley committed
285 286
 * Requires:
 *
287
 *\li	'res' is a valid resolver that has been frozen.
Bob Halley's avatar
Bob Halley committed
288
 *
289
 *\li	'name' is a valid name.
Bob Halley's avatar
Bob Halley committed
290
 *
291
 *\li	'type' is not a meta type other than ANY.
Bob Halley's avatar
Bob Halley committed
292
 *
293
 *\li	'domain' is a valid name or NULL.
Bob Halley's avatar
Bob Halley committed
294
 *
295
 *\li	'nameservers' is a valid NS rdataset (whose owner name is 'domain')
296
 *	iff. 'domain' is not NULL.
Bob Halley's avatar
Bob Halley committed
297
 *
298
 *\li	'forwarders' is NULL.
Bob Halley's avatar
Bob Halley committed
299
 *
300 301
 *\li	'client' is a valid sockaddr or NULL.
 *
302
 *\li	'options' contains valid options.
Bob Halley's avatar
Bob Halley committed
303
 *
304
 *\li	'rdataset' is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
305
 *
306
 *\li	'sigrdataset' is NULL, or is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
307
 *
308
 *\li	fetchp != NULL && *fetchp == NULL.
Bob Halley's avatar
Bob Halley committed
309 310 311
 *
 * Returns:
 *
312
 *\li	#ISC_R_SUCCESS					Success
313
 *\li	#DNS_R_DUPLICATE
314
 *\li	#DNS_R_DROP
Bob Halley's avatar
Bob Halley committed
315
 *
316
 *\li	Many other values are possible, all of which indicate failure.
Bob Halley's avatar
Bob Halley committed
317
 */
Bob Halley's avatar
Bob Halley committed
318

Bob Halley's avatar
Bob Halley committed
319
void
320
dns_resolver_cancelfetch(dns_fetch_t *fetch);
321
/*%<
Bob Halley's avatar
Bob Halley committed
322 323 324 325
 * Cancel 'fetch'.
 *
 * Notes:
 *
326 327
 *\li	If 'fetch' has not completed, post its FETCHDONE event with a
 *	result code of #ISC_R_CANCELED.
328 329 330
 *
 * Requires:
 *
331
 *\li	'fetch' is a valid fetch.
Bob Halley's avatar
Bob Halley committed
332
 */
Bob Halley's avatar
Bob Halley committed
333

Bob Halley's avatar
Bob Halley committed
334
void
335
dns_resolver_destroyfetch(dns_fetch_t **fetchp);
336
/*%<
Bob Halley's avatar
Bob Halley committed
337 338 339 340
 * Destroy 'fetch'.
 *
 * Requires:
 *
341
 *\li	'*fetchp' is a valid fetch.
342
 *
343
 *\li	The caller has received the FETCHDONE event (either because the
Bob Halley's avatar
Bob Halley committed
344 345 346 347
 *	fetch completed or because dns_resolver_cancelfetch() was called).
 *
 * Ensures:
 *
348
 *\li	*fetchp == NULL.
Bob Halley's avatar
Bob Halley committed
349
 */
Mark Andrews's avatar
Mark Andrews committed
350

351 352 353
dns_dispatchmgr_t *
dns_resolver_dispatchmgr(dns_resolver_t *resolver);

354 355 356 357 358 359 360 361 362
dns_dispatch_t *
dns_resolver_dispatchv4(dns_resolver_t *resolver);

dns_dispatch_t *
dns_resolver_dispatchv6(dns_resolver_t *resolver);

isc_socketmgr_t *
dns_resolver_socketmgr(dns_resolver_t *resolver);

363 364 365
isc_taskmgr_t *
dns_resolver_taskmgr(dns_resolver_t *resolver);

Mark Andrews's avatar
Mark Andrews committed
366 367
isc_uint32_t
dns_resolver_getlamettl(dns_resolver_t *resolver);
368
/*%<
Mark Andrews's avatar
Mark Andrews committed
369 370 371
 * Get the resolver's lame-ttl.  zero => no lame processing.
 *
 * Requires:
372
 *\li	'resolver' to be valid.
Mark Andrews's avatar
Mark Andrews committed
373 374 375 376
 */

void
dns_resolver_setlamettl(dns_resolver_t *resolver, isc_uint32_t lame_ttl);
377
/*%<
Mark Andrews's avatar
Mark Andrews committed
378 379 380
 * Set the resolver's lame-ttl.  zero => no lame processing.
 *
 * Requires:
381
 *\li	'resolver' to be valid.
Mark Andrews's avatar
Mark Andrews committed
382 383
 */

384 385
unsigned int
dns_resolver_nrunning(dns_resolver_t *resolver);
386
/*%<
387 388 389 390 391 392 393
 * Return the number of currently running resolutions in this
 * resolver.  This is may be less than the number of outstanding
 * fetches due to multiple identical fetches, or more than the
 * number of of outstanding fetches due to the fact that resolution
 * can continue even though a fetch has been canceled.
 */

394 395 396
isc_result_t
dns_resolver_addalternate(dns_resolver_t *resolver, isc_sockaddr_t *alt,
			  dns_name_t *name, in_port_t port);
397
/*%<
398 399 400 401 402
 * Add alternate addresses to be tried in the event that the nameservers
 * for a zone are not available in the address families supported by the
 * operating system.
 *
 * Require:
403
 * \li	only one of 'name' or 'alt' to be valid.
404 405
 */

406 407
void
dns_resolver_setudpsize(dns_resolver_t *resolver, isc_uint16_t udpsize);
408
/*%<
409 410 411 412 413
 * Set the EDNS UDP buffer size advertised by the server.
 */

isc_uint16_t
dns_resolver_getudpsize(dns_resolver_t *resolver);
414
/*%<
415 416 417
 * Get the current EDNS UDP buffer size.
 */

418 419
void
dns_resolver_reset_algorithms(dns_resolver_t *resolver);
420
/*%<
421 422 423 424 425 426
 * Clear the disabled DNSSEC algorithms.
 */

isc_result_t
dns_resolver_disable_algorithm(dns_resolver_t *resolver, dns_name_t *name,
			       unsigned int alg);
427
/*%<
428 429 430 431
 * Mark the give DNSSEC algorithm as disabled and below 'name'.
 * Valid algorithms are less than 256.
 *
 * Returns:
432 433 434
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_RANGE
 *\li	#ISC_R_NOMEMORY
435 436 437 438 439
 */

isc_boolean_t
dns_resolver_algorithm_supported(dns_resolver_t *resolver, dns_name_t *name,
				 unsigned int alg);
440
/*%<
441 442 443 444 445 446
 * Check if the given algorithm is supported by this resolver.
 * This checks if the algorithm has been disabled via
 * dns_resolver_disable_algorithm() then the underlying
 * crypto libraries if not specifically disabled.
 */

447 448
isc_boolean_t
dns_resolver_digest_supported(dns_resolver_t *resolver, unsigned int digest_type);
Mark Andrews's avatar
Mark Andrews committed
449
/*%<
450 451 452
 * Is this digest type supported.
 */

453 454 455 456 457 458 459 460 461 462
void
dns_resolver_resetmustbesecure(dns_resolver_t *resolver);

isc_result_t
dns_resolver_setmustbesecure(dns_resolver_t *resolver, dns_name_t *name,
			     isc_boolean_t value);

isc_boolean_t
dns_resolver_getmustbesecure(dns_resolver_t *resolver, dns_name_t *name);

463 464 465 466 467 468 469
void
dns_resolver_setclientsperquery(dns_resolver_t *resolver,
				isc_uint32_t min, isc_uint32_t max);

void
dns_resolver_getclientsperquery(dns_resolver_t *resolver, isc_uint32_t *cur,
				isc_uint32_t *min, isc_uint32_t *max);
470 471 472 473 474 475 476

isc_boolean_t
dns_resolver_getzeronosoattl(dns_resolver_t *resolver);
 
void
dns_resolver_setzeronosoattl(dns_resolver_t *resolver, isc_boolean_t state);

477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506
unsigned int
dns_resolver_getoptions(dns_resolver_t *resolver);

isc_result_t
dns_resolver_createdispatchpool(dns_resolver_t *res, unsigned int ndisps,
				unsigned int interval);
/*%<
 * Create a pool of dispatches
 *
 * Notes:
 *
 *\li	Generally, applications should not create a resolver directly, but
 *	should instead call dns_view_createresolver().
 *
 * Requires:
 *
 *\li	'res' is a valid resolver that has not been frozen.  Also it must have
 *	either the _USEDISPATCHPOOL4 or _USEDISPATCHPOOL6 option. 
 *
 *\li	'taskmgr' is a valid task manager.
 *
 *\li	'ndisps' > 0.
 *
 * Returns:
 *
 *\li	#ISC_R_SUCCESS				On success.
 *
 *\li	Anything else				Failure.
 */

Bob Halley's avatar
Bob Halley committed
507 508 509
ISC_LANG_ENDDECLS

#endif /* DNS_RESOLVER_H */