Import bind 9.5.2 vendor sources.
[dragonfly.git] / contrib / bind-9.5.2 / lib / dns / include / dns / resolver.h
1 /*
2  * Copyright (C) 2004-2009  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: resolver.h,v 1.56.128.7 2009/01/29 22:41:45 jinmei Exp $ */
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
61 ISC_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  */
72 typedef 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 } dns_fetchevent_t;
85
86 /*
87  * Options that modify how a 'fetch' is done.
88  */
89 #define DNS_FETCHOPT_TCP                0x01         /*%< Use TCP. */
90 #define DNS_FETCHOPT_UNSHARED           0x02         /*%< See below. */
91 #define DNS_FETCHOPT_RECURSIVE          0x04         /*%< Set RD? */
92 #define DNS_FETCHOPT_NOEDNS0            0x08         /*%< Do not use EDNS. */
93 #define DNS_FETCHOPT_FORWARDONLY        0x10         /*%< Only use forwarders. */
94 #define DNS_FETCHOPT_NOVALIDATE         0x20         /*%< Disable validation. */
95 #define DNS_FETCHOPT_EDNS512            0x40         /*%< Advertise a 512 byte
96                                                           UDP buffer. */
97 #define DNS_FETCHOPT_WANTNSID           0x80         /*%< Request NSID */
98
99 #define DNS_FETCHOPT_EDNSVERSIONSET     0x00800000
100 #define DNS_FETCHOPT_EDNSVERSIONMASK    0xff000000
101 #define DNS_FETCHOPT_EDNSVERSIONSHIFT   24
102
103 /*
104  * Upper bounds of class of query RTT (ms).  Corresponds to
105  * dns_resstatscounter_queryrttX statistics counters.
106  */
107 #define DNS_RESOLVER_QRYRTTCLASS0       10
108 #define DNS_RESOLVER_QRYRTTCLASS0STR    "10"
109 #define DNS_RESOLVER_QRYRTTCLASS1       100
110 #define DNS_RESOLVER_QRYRTTCLASS1STR    "100"
111 #define DNS_RESOLVER_QRYRTTCLASS2       500
112 #define DNS_RESOLVER_QRYRTTCLASS2STR    "500"
113 #define DNS_RESOLVER_QRYRTTCLASS3       800
114 #define DNS_RESOLVER_QRYRTTCLASS3STR    "800"
115 #define DNS_RESOLVER_QRYRTTCLASS4       1600
116 #define DNS_RESOLVER_QRYRTTCLASS4STR    "1600"
117
118 /*
119  * XXXRTH  Should this API be made semi-private?  (I.e.
120  * _dns_resolver_create()).
121  */
122
123 #define DNS_RESOLVER_CHECKNAMES         0x01
124 #define DNS_RESOLVER_CHECKNAMESFAIL     0x02
125
126 isc_result_t
127 dns_resolver_create(dns_view_t *view,
128                     isc_taskmgr_t *taskmgr, unsigned int ntasks,
129                     isc_socketmgr_t *socketmgr,
130                     isc_timermgr_t *timermgr,
131                     unsigned int options,
132                     dns_dispatchmgr_t *dispatchmgr,
133                     dns_dispatch_t *dispatchv4,
134                     dns_dispatch_t *dispatchv6,
135                     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
170 void
171 dns_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
189 void
190 dns_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
207 void
208 dns_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
231 void
232 dns_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
245 void
246 dns_resolver_attach(dns_resolver_t *source, dns_resolver_t **targetp);
247
248 void
249 dns_resolver_detach(dns_resolver_t **resp);
250
251 isc_result_t
252 dns_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
262 isc_result_t
263 dns_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
333 void
334 dns_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
348 void
349 dns_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
365 void
366 dns_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
382 dns_dispatchmgr_t *
383 dns_resolver_dispatchmgr(dns_resolver_t *resolver);
384
385 dns_dispatch_t *
386 dns_resolver_dispatchv4(dns_resolver_t *resolver);
387
388 dns_dispatch_t *
389 dns_resolver_dispatchv6(dns_resolver_t *resolver);
390
391 isc_socketmgr_t *
392 dns_resolver_socketmgr(dns_resolver_t *resolver);
393
394 isc_taskmgr_t *
395 dns_resolver_taskmgr(dns_resolver_t *resolver);
396
397 isc_uint32_t
398 dns_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
406 void
407 dns_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
415 unsigned int
416 dns_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
425 isc_result_t
426 dns_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
437 void
438 dns_resolver_setudpsize(dns_resolver_t *resolver, isc_uint16_t udpsize);
439 /*%<
440  * Set the EDNS UDP buffer size advertised by the server.
441  */
442
443 isc_uint16_t
444 dns_resolver_getudpsize(dns_resolver_t *resolver);
445 /*%<
446  * Get the current EDNS UDP buffer size.
447  */
448
449 void
450 dns_resolver_reset_algorithms(dns_resolver_t *resolver);
451 /*%<
452  * Clear the disabled DNSSEC algorithms.
453  */
454
455 isc_result_t
456 dns_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
468 isc_boolean_t
469 dns_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
478 isc_boolean_t
479 dns_resolver_digest_supported(dns_resolver_t *resolver, unsigned int digest_type);
480 /*%<
481  * Is this digest type supported.
482  */
483
484 void
485 dns_resolver_resetmustbesecure(dns_resolver_t *resolver);
486
487 isc_result_t
488 dns_resolver_setmustbesecure(dns_resolver_t *resolver, dns_name_t *name,
489                              isc_boolean_t value);
490
491 isc_boolean_t
492 dns_resolver_getmustbesecure(dns_resolver_t *resolver, dns_name_t *name);
493
494 void
495 dns_resolver_setclientsperquery(dns_resolver_t *resolver,
496                                 isc_uint32_t min, isc_uint32_t max);
497
498 void
499 dns_resolver_getclientsperquery(dns_resolver_t *resolver, isc_uint32_t *cur,
500                                 isc_uint32_t *min, isc_uint32_t *max);
501
502 isc_boolean_t
503 dns_resolver_getzeronosoattl(dns_resolver_t *resolver);
504
505 void
506 dns_resolver_setzeronosoattl(dns_resolver_t *resolver, isc_boolean_t state);
507
508 unsigned int
509 dns_resolver_getoptions(dns_resolver_t *resolver);
510
511 ISC_LANG_ENDDECLS
512
513 #endif /* DNS_RESOLVER_H */