/contrib/bind9/lib/dns/include/dns/resolver.h

  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 */