ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/evdns.h
Revision: 1.2
Committed: Fri Nov 9 19:33:52 2007 UTC (16 years, 7 months ago) by root
Content type: text/plain
Branch: MAIN
CVS Tags: HEAD
Changes since 1.1: +0 -0 lines
State: FILE REMOVED
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.1 /*
2     * Copyright (c) 2006 Niels Provos <provos@citi.umich.edu>
3     * All rights reserved.
4     *
5     * Redistribution and use in source and binary forms, with or without
6     * modification, are permitted provided that the following conditions
7     * are met:
8     * 1. Redistributions of source code must retain the above copyright
9     * notice, this list of conditions and the following disclaimer.
10     * 2. Redistributions in binary form must reproduce the above copyright
11     * notice, this list of conditions and the following disclaimer in the
12     * documentation and/or other materials provided with the distribution.
13     * 3. The name of the author may not be used to endorse or promote products
14     * derived from this software without specific prior written permission.
15     *
16     * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17     * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18     * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19     * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20     * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21     * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22     * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23     * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24     * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25     * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26     */
27    
28     /*
29     * The original DNS code is due to Adam Langley with heavy
30     * modifications by Nick Mathewson. Adam put his DNS software in the
31     * public domain. You can find his original copyright below. Please,
32     * aware that the code as part of libevent is governed by the 3-clause
33     * BSD license above.
34     *
35     * This software is Public Domain. To view a copy of the public domain dedication,
36     * visit http://creativecommons.org/licenses/publicdomain/ or send a letter to
37     * Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
38     *
39     * I ask and expect, but do not require, that all derivative works contain an
40     * attribution similar to:
41     * Parts developed by Adam Langley <agl@imperialviolet.org>
42     *
43     * You may wish to replace the word "Parts" with something else depending on
44     * the amount of original code.
45     *
46     * (Derivative works does not include programs which link against, run or include
47     * the source verbatim in their source distributions)
48     */
49    
50     /*
51     * Welcome, gentle reader
52     *
53     * Async DNS lookups are really a whole lot harder than they should be,
54     * mostly stemming from the fact that the libc resolver has never been
55     * very good at them. Before you use this library you should see if libc
56     * can do the job for you with the modern async call getaddrinfo_a
57     * (see http://www.imperialviolet.org/page25.html#e498). Otherwise,
58     * please continue.
59     *
60     * This code is based on libevent and you must call event_init before
61     * any of the APIs in this file. You must also seed the OpenSSL random
62     * source if you are using OpenSSL for ids (see below).
63     *
64     * This library is designed to be included and shipped with your source
65     * code. You statically link with it. You should also test for the
66     * existence of strtok_r and define HAVE_STRTOK_R if you have it.
67     *
68     * The DNS protocol requires a good source of id numbers and these
69     * numbers should be unpredictable for spoofing reasons. There are
70     * three methods for generating them here and you must define exactly
71     * one of them. In increasing order of preference:
72     *
73     * DNS_USE_GETTIMEOFDAY_FOR_ID:
74     * Using the bottom 16 bits of the usec result from gettimeofday. This
75     * is a pretty poor solution but should work anywhere.
76     * DNS_USE_CPU_CLOCK_FOR_ID:
77     * Using the bottom 16 bits of the nsec result from the CPU's time
78     * counter. This is better, but may not work everywhere. Requires
79     * POSIX realtime support and you'll need to link against -lrt on
80     * glibc systems at least.
81     * DNS_USE_OPENSSL_FOR_ID:
82     * Uses the OpenSSL RAND_bytes call to generate the data. You must
83     * have seeded the pool before making any calls to this library.
84     *
85     * The library keeps track of the state of nameservers and will avoid
86     * them when they go down. Otherwise it will round robin between them.
87     *
88     * Quick start guide:
89     * #include "evdns.h"
90     * void callback(int result, char type, int count, int ttl,
91     * void *addresses, void *arg);
92     * evdns_resolv_conf_parse(DNS_OPTIONS_ALL, "/etc/resolv.conf");
93     * evdns_resolve("www.hostname.com", 0, callback, NULL);
94     *
95     * When the lookup is complete the callback function is called. The
96     * first argument will be one of the DNS_ERR_* defines in evdns.h.
97     * Hopefully it will be DNS_ERR_NONE, in which case type will be
98     * DNS_IPv4_A, count will be the number of IP addresses, ttl is the time
99     * which the data can be cached for (in seconds), addresses will point
100     * to an array of uint32_t's and arg will be whatever you passed to
101     * evdns_resolve.
102     *
103     * Searching:
104     *
105     * In order for this library to be a good replacement for glibc's resolver it
106     * supports searching. This involves setting a list of default domains, in
107     * which names will be queried for. The number of dots in the query name
108     * determines the order in which this list is used.
109     *
110     * Searching appears to be a single lookup from the point of view of the API,
111     * although many DNS queries may be generated from a single call to
112     * evdns_resolve. Searching can also drastically slow down the resolution
113     * of names.
114     *
115     * To disable searching:
116     * 1. Never set it up. If you never call evdns_resolv_conf_parse or
117     * evdns_search_add then no searching will occur.
118     *
119     * 2. If you do call evdns_resolv_conf_parse then don't pass
120     * DNS_OPTION_SEARCH (or DNS_OPTIONS_ALL, which implies it).
121     *
122     * 3. When calling evdns_resolve, pass the DNS_QUERY_NO_SEARCH flag.
123     *
124     * The order of searches depends on the number of dots in the name. If the
125     * number is greater than the ndots setting then the names is first tried
126     * globally. Otherwise each search domain is appended in turn.
127     *
128     * The ndots setting can either be set from a resolv.conf, or by calling
129     * evdns_search_ndots_set.
130     *
131     * For example, with ndots set to 1 (the default) and a search domain list of
132     * ["myhome.net"]:
133     * Query: www
134     * Order: www.myhome.net, www.
135     *
136     * Query: www.abc
137     * Order: www.abc., www.abc.myhome.net
138     *
139     * API reference:
140     *
141     * int evdns_nameserver_add(unsigned long int address)
142     * Add a nameserver. The address should be an IP address in
143     * network byte order. The type of address is chosen so that
144     * it matches in_addr.s_addr.
145     * Returns non-zero on error.
146     *
147     * int evdns_nameserver_ip_add(const char *ip_as_string)
148     * This wraps the above function by parsing a string as an IP
149     * address and adds it as a nameserver.
150     * Returns non-zero on error
151     *
152     * int evdns_resolve(const char *name, int flags,
153     * evdns_callback_type callback,
154     * void *ptr)
155     * Resolve a name. The name parameter should be a DNS name.
156     * The flags parameter should be 0, or DNS_QUERY_NO_SEARCH
157     * which disables searching for this query. (see defn of
158     * searching above).
159     *
160     * The callback argument is a function which is called when
161     * this query completes and ptr is an argument which is passed
162     * to that callback function.
163     *
164     * Returns non-zero on error
165     *
166     * void evdns_search_clear()
167     * Clears the list of search domains
168     *
169     * void evdns_search_add(const char *domain)
170     * Add a domain to the list of search domains
171     *
172     * void evdns_search_ndots_set(int ndots)
173     * Set the number of dots which, when found in a name, causes
174     * the first query to be without any search domain.
175     *
176     * int evdns_count_nameservers(void)
177     * Return the number of configured nameservers (not necessarily the
178     * number of running nameservers). This is useful for double-checking
179     * whether our calls to the various nameserver configuration functions
180     * have been successful.
181     *
182     * int evdns_clear_nameservers_and_suspend(void)
183     * Remove all currently configured nameservers, and suspend all pending
184     * resolves. Resolves will not necessarily be re-attempted until
185     * evdns_resume() is called.
186     *
187     * int evdns_resume(void)
188     * Re-attempt resolves left in limbo after an earlier call to
189     * evdns_clear_nameservers_and_suspend().
190     *
191     * int evdns_config_windows_nameservers(void)
192     * Attempt to configure a set of nameservers based on platform settings on
193     * a win32 host. Preferentially tries to use GetNetworkParams; if that fails,
194     * looks in the registry. Returns 0 on success, nonzero on failure.
195     *
196     * int evdns_resolv_conf_parse(int flags, const char *filename)
197     * Parse a resolv.conf like file from the given filename.
198     *
199     * See the man page for resolv.conf for the format of this file.
200     * The flags argument determines what information is parsed from
201     * this file:
202     * DNS_OPTION_SEARCH - domain, search and ndots options
203     * DNS_OPTION_NAMESERVERS - nameserver lines
204     * DNS_OPTION_MISC - timeout and attempts options
205     * DNS_OPTIONS_ALL - all of the above
206     * The following directives are not parsed from the file:
207     * sortlist, rotate, no-check-names, inet6, debug
208     *
209     * Returns non-zero on error:
210     * 0 no errors
211     * 1 failed to open file
212     * 2 failed to stat file
213     * 3 file too large
214     * 4 out of memory
215     * 5 short read from file
216     * 6 no nameservers in file
217     *
218     * Internals:
219     *
220     * Requests are kept in two queues. The first is the inflight queue. In
221     * this queue requests have an allocated transaction id and nameserver.
222     * They will soon be transmitted if they haven't already been.
223     *
224     * The second is the waiting queue. The size of the inflight ring is
225     * limited and all other requests wait in waiting queue for space. This
226     * bounds the number of concurrent requests so that we don't flood the
227     * nameserver. Several algorithms require a full walk of the inflight
228     * queue and so bounding its size keeps thing going nicely under huge
229     * (many thousands of requests) loads.
230     *
231     * If a nameserver loses too many requests it is considered down and we
232     * try not to use it. After a while we send a probe to that nameserver
233     * (a lookup for google.com) and, if it replies, we consider it working
234     * again. If the nameserver fails a probe we wait longer to try again
235     * with the next probe.
236     */
237    
238     #ifndef EVENTDNS_H
239     #define EVENTDNS_H
240    
241     #ifdef __cplusplus
242     extern "C" {
243     #endif
244    
245     /* Error codes 0-5 are as described in RFC 1035. */
246     #define DNS_ERR_NONE 0
247     /* The name server was unable to interpret the query */
248     #define DNS_ERR_FORMAT 1
249     /* The name server was unable to process this query due to a problem with the
250     * name server */
251     #define DNS_ERR_SERVERFAILED 2
252     /* The domain name does not exist */
253     #define DNS_ERR_NOTEXIST 3
254     /* The name server does not support the requested kind of query */
255     #define DNS_ERR_NOTIMPL 4
256     /* The name server refuses to reform the specified operation for policy
257     * reasons */
258     #define DNS_ERR_REFUSED 5
259     /* The reply was truncated or ill-formated */
260     #define DNS_ERR_TRUNCATED 65
261     /* An unknown error occurred */
262     #define DNS_ERR_UNKNOWN 66
263     /* Communication with the server timed out */
264     #define DNS_ERR_TIMEOUT 67
265     /* The request was canceled because the DNS subsystem was shut down. */
266     #define DNS_ERR_SHUTDOWN 68
267    
268     #define DNS_IPv4_A 1
269     #define DNS_PTR 2
270     #define DNS_IPv6_AAAA 3
271    
272     #define DNS_QUERY_NO_SEARCH 1
273    
274     #define DNS_OPTION_SEARCH 1
275     #define DNS_OPTION_NAMESERVERS 2
276     #define DNS_OPTION_MISC 4
277     #define DNS_OPTIONS_ALL 7
278    
279     /*
280     * The callback that contains the results from a lookup.
281     * - type is either DNS_IPv4_A or DNS_PTR or DNS_IPv6_AAAA
282     * - count contains the number of addresses of form type
283     * - ttl is the number of seconds the resolution may be cached for.
284     * - addresses needs to be cast according to type
285     */
286     typedef void (*evdns_callback_type) (int result, char type, int count, int ttl, void *addresses, void *arg);
287    
288     int evdns_init(void);
289     void evdns_shutdown(int fail_requests);
290     const char *evdns_err_to_string(int err);
291     int evdns_nameserver_add(unsigned long int address);
292     int evdns_count_nameservers(void);
293     int evdns_clear_nameservers_and_suspend(void);
294     int evdns_resume(void);
295     int evdns_nameserver_ip_add(const char *ip_as_string);
296     int evdns_resolve_ipv4(const char *name, int flags, evdns_callback_type callback, void *ptr);
297     int evdns_resolve_ipv6(const char *name, int flags, evdns_callback_type callback, void *ptr);
298     struct in_addr;
299     struct in6_addr;
300     int evdns_resolve_reverse(struct in_addr *in, int flags, evdns_callback_type callback, void *ptr);
301     int evdns_resolve_reverse_ipv6(struct in6_addr *in, int flags, evdns_callback_type callback, void *ptr);
302     int evdns_set_option(const char *option, const char *val, int flags);
303     int evdns_resolv_conf_parse(int flags, const char *);
304     #ifdef MS_WINDOWS
305     int evdns_config_windows_nameservers(void);
306     #endif
307     void evdns_search_clear(void);
308     void evdns_search_add(const char *domain);
309     void evdns_search_ndots_set(const int ndots);
310    
311     typedef void (*evdns_debug_log_fn_type)(int is_warning, const char *msg);
312     void evdns_set_log_fn(evdns_debug_log_fn_type fn);
313    
314     #define DNS_NO_SEARCH 1
315    
316     #ifdef __cplusplus
317     }
318     #endif
319    
320     /*
321     * Structures and functions used to implement a DNS server.
322     */
323    
324     struct evdns_server_request {
325     int flags;
326     int nquestions;
327     struct evdns_server_question **questions;
328     };
329     struct evdns_server_question {
330     int type;
331     int class;
332     char name[1];
333     };
334     typedef void (*evdns_request_callback_fn_type)(struct evdns_server_request *, void *);
335     #define EVDNS_ANSWER_SECTION 0
336     #define EVDNS_AUTHORITY_SECTION 1
337     #define EVDNS_ADDITIONAL_SECTION 2
338    
339     #define EVDNS_TYPE_A 1
340     #define EVDNS_TYPE_NS 2
341     #define EVDNS_TYPE_CNAME 5
342     #define EVDNS_TYPE_SOA 6
343     #define EVDNS_TYPE_PTR 12
344     #define EVDNS_TYPE_MX 15
345     #define EVDNS_TYPE_TXT 16
346     #define EVDNS_TYPE_AAAA 28
347    
348     #define EVDNS_QTYPE_AXFR 252
349     #define EVDNS_QTYPE_ALL 255
350    
351     #define EVDNS_CLASS_INET 1
352    
353     struct evdns_server_port *evdns_add_server_port(int socket, int is_tcp, evdns_request_callback_fn_type callback, void *user_data);
354     void evdns_close_server_port(struct evdns_server_port *port);
355    
356     int evdns_server_request_add_reply(struct evdns_server_request *req, int section, const char *name, int type, int class, int ttl, int datalen, int is_name, const char *data);
357     int evdns_server_request_add_a_reply(struct evdns_server_request *req, const char *name, int n, void *addrs, int ttl);
358     int evdns_server_request_add_aaaa_reply(struct evdns_server_request *req, const char *name, int n, void *addrs, int ttl);
359     int evdns_server_request_add_ptr_reply(struct evdns_server_request *req, struct in_addr *in, const char *inaddr_name, const char *hostname, int ttl);
360     int evdns_server_request_add_cname_reply(struct evdns_server_request *req, const char *name, const char *cname, int ttl);
361    
362     int evdns_server_request_respond(struct evdns_server_request *req, int err);
363     int evdns_server_request_drop(struct evdns_server_request *req);
364     struct sockaddr;
365     int evdns_server_request_get_requesting_addr(struct evdns_server_request *_req, struct sockaddr *sa, int addr_len);
366    
367     #endif /* !EVENTDNS_H */