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