Back to index

tor  0.2.3.19-rc
eventdns.h
Go to the documentation of this file.
00001 
00002 /*
00003  * The original DNS code is due to Adam Langley with heavy
00004  * modifications by Nick Mathewson.  Adam put his DNS software in the
00005  * public domain.  You can find his original copyright below.  Please,
00006  * aware that the code as part of libevent is governed by the 3-clause
00007  * BSD license above.
00008  *
00009  * This software is Public Domain. To view a copy of the public domain dedication,
00010  * visit http://creativecommons.org/licenses/publicdomain/ or send a letter to
00011  * Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
00012  *
00013  * I ask and expect, but do not require, that all derivative works contain an
00014  * attribution similar to:
00015  *     Parts developed by Adam Langley <agl@imperialviolet.org>
00016  *
00017  * You may wish to replace the word "Parts" with something else depending on
00018  * the amount of original code.
00019  *
00020  * (Derivative works does not include programs which link against, run or include
00021  * the source verbatim in their source distributions)
00022  */
00023 
00024 /*
00025  * Welcome, gentle reader
00026  *
00027  * Async DNS lookups are really a whole lot harder than they should be,
00028  * mostly stemming from the fact that the libc resolver has never been
00029  * very good at them. Before you use this library you should see if libc
00030  * can do the job for you with the modern async call getaddrinfo_a
00031  * (see http://www.imperialviolet.org/page25.html#e498). Otherwise,
00032  * please continue.
00033  *
00034  * This code is based on libevent and you must call event_init before
00035  * any of the APIs in this file. You must also seed the OpenSSL random
00036  * source if you are using OpenSSL for ids (see below).
00037  *
00038  * This library is designed to be included and shipped with your source
00039  * code. You statically link with it. You should also test for the
00040  * existence of strtok_r and define HAVE_STRTOK_R if you have it.
00041  *
00042  * The DNS protocol requires a good source of id numbers and these
00043  * numbers should be unpredictable for spoofing reasons. There are
00044  * three methods for generating them here and you must define exactly
00045  * one of them. In increasing order of preference:
00046  *
00047  * DNS_USE_GETTIMEOFDAY_FOR_ID:
00048  *   Using the bottom 16 bits of the usec result from gettimeofday. This
00049  *   is a pretty poor solution but should work anywhere.
00050  * DNS_USE_CPU_CLOCK_FOR_ID:
00051  *  Using the bottom 16 bits of the nsec result from the CPU's time
00052  *  counter. This is better, but may not work everywhere. Requires
00053  *  POSIX realtime support and you'll need to link against -lrt on
00054  *  glibc systems at least.
00055  * DNS_USE_OPENSSL_FOR_ID:
00056  *  Uses the OpenSSL RAND_bytes call to generate the data. You must
00057  *  have seeded the pool before making any calls to this library.
00058  *
00059  * The library keeps track of the state of nameservers and will avoid
00060  * them when they go down. Otherwise it will round robin between them.
00061  *
00062  * Quick start guide:
00063  *      #include "evdns.h"
00064  *      void callback(int result, char type, int count, int ttl,
00065  *     void *addresses, void *arg);
00066  *      evdns_resolv_conf_parse(DNS_OPTIONS_ALL, "/etc/resolv.conf");
00067  *      evdns_resolve("www.hostname.com", 0, callback, NULL);
00068  *
00069  * When the lookup is complete the callback function is called. The
00070  * first argument will be one of the DNS_ERR_* defines in evdns.h.
00071  * Hopefully it will be DNS_ERR_NONE, in which case type will be
00072  * DNS_IPv4_A, count will be the number of IP addresses, ttl is the time
00073  * which the data can be cached for (in seconds), addresses will point
00074  * to an array of uint32_t's and arg will be whatever you passed to
00075  * evdns_resolve.
00076  *
00077  * Searching:
00078  *
00079  * In order for this library to be a good replacement for glibc's resolver it
00080  * supports searching. This involves setting a list of default domains, in
00081  * which names will be queried for. The number of dots in the query name
00082  * determines the order in which this list is used.
00083  *
00084  * Searching appears to be a single lookup from the point of view of the API,
00085  * although many DNS queries may be generated from a single call to
00086  * evdns_resolve. Searching can also drastically slow down the resolution
00087  * of names.
00088  *
00089  * To disable searching:
00090  *      1. Never set it up. If you never call evdns_resolv_conf_parse or
00091  *   evdns_search_add then no searching will occur.
00092  *
00093  *      2. If you do call evdns_resolv_conf_parse then don't pass
00094  *   DNS_OPTION_SEARCH (or DNS_OPTIONS_ALL, which implies it).
00095  *
00096  *      3. When calling evdns_resolve, pass the DNS_QUERY_NO_SEARCH flag.
00097  *
00098  * The order of searches depends on the number of dots in the name. If the
00099  * number is greater than the ndots setting then the names is first tried
00100  * globally. Otherwise each search domain is appended in turn.
00101  *
00102  * The ndots setting can either be set from a resolv.conf, or by calling
00103  * evdns_search_ndots_set.
00104  *
00105  * For example, with ndots set to 1 (the default) and a search domain list of
00106  * ["myhome.net"]:
00107  *     Query: www
00108  *     Order: www.myhome.net, www.
00109  *
00110  *     Query: www.abc
00111  *     Order: www.abc., www.abc.myhome.net
00112  *
00113  * API reference:
00114  *
00115  * int evdns_nameserver_add(uint32_t address)
00116  *      Add a nameserver. The address should be an IP address in
00117  *      network byte order. The type of address is chosen so that
00118  *      it matches in_addr.s_addr.
00119  *      Returns non-zero on error.
00120  *
00121  * int evdns_nameserver_ip_add(const char *ip_as_string)
00122  *      This wraps the above function by parsing a string as an IP
00123  *      address and adds it as a nameserver.
00124  *      Returns non-zero on error
00125  *
00126  * int evdns_resolve(const char *name, int flags,
00127  *           evdns_callback_type callback,
00128  *           void *ptr)
00129  *      Resolve a name. The name parameter should be a DNS name.
00130  *      The flags parameter should be 0, or DNS_QUERY_NO_SEARCH
00131  *      which disables searching for this query. (see defn of
00132  *      searching above).
00133  *
00134  *      The callback argument is a function which is called when
00135  *      this query completes and ptr is an argument which is passed
00136  *      to that callback function.
00137  *
00138  *      Returns non-zero on error
00139  *
00140  * void evdns_search_clear()
00141  *      Clears the list of search domains
00142  *
00143  * void evdns_search_add(const char *domain)
00144  *      Add a domain to the list of search domains
00145  *
00146  * void evdns_search_ndots_set(int ndots)
00147  *      Set the number of dots which, when found in a name, causes
00148  *      the first query to be without any search domain.
00149  *
00150  * int evdns_count_nameservers(void)
00151  *      Return the number of configured nameservers (not necessarily the
00152  *      number of running nameservers).  This is useful for double-checking
00153  *      whether our calls to the various nameserver configuration functions
00154  *      have been successful.
00155  *
00156  * int evdns_clear_nameservers_and_suspend(void)
00157  *      Remove all currently configured nameservers, and suspend all pending
00158  *      resolves.    Resolves will not necessarily be re-attempted until
00159  *      evdns_resume() is called.
00160  *
00161  * int evdns_resume(void)
00162  *      Re-attempt resolves left in limbo after an earlier call to
00163  *      evdns_clear_nameservers_and_suspend().
00164  *
00165  * int evdns_config_windows_nameservers(void)
00166  *      Attempt to configure a set of nameservers based on platform settings on
00167  *      a win32 host.       Preferentially tries to use GetNetworkParams; if that fails,
00168  *      looks in the registry.      Returns 0 on success, nonzero on failure.
00169  *
00170  * int evdns_resolv_conf_parse(int flags, const char *filename)
00171  *      Parse a resolv.conf like file from the given filename.
00172  *
00173  *      See the man page for resolv.conf for the format of this file.
00174  *      The flags argument determines what information is parsed from
00175  *      this file:
00176  *        DNS_OPTION_SEARCH - domain, search and ndots options
00177  *        DNS_OPTION_NAMESERVERS - nameserver lines
00178  *        DNS_OPTION_MISC - timeout and attempts options
00179  *        DNS_OPTIONS_ALL - all of the above
00180  *      The following directives are not parsed from the file:
00181  *        sortlist, rotate, no-check-names, inet6, debug
00182  *
00183  *      Returns non-zero on error:
00184  *       0 no errors
00185  *       1 failed to open file
00186  *       2 failed to stat file
00187  *       3 file too large
00188  *       4 out of memory
00189  *       5 short read from file
00190  *        6 no nameservers in file
00191  *
00192  * Internals:
00193  *
00194  * Requests are kept in two queues. The first is the inflight queue. In
00195  * this queue requests have an allocated transaction id and nameserver.
00196  * They will soon be transmitted if they haven't already been.
00197  *
00198  * The second is the waiting queue. The size of the inflight ring is
00199  * limited and all other requests wait in waiting queue for space. This
00200  * bounds the number of concurrent requests so that we don't flood the
00201  * nameserver. Several algorithms require a full walk of the inflight
00202  * queue and so bounding its size keeps thing going nicely under huge
00203  * (many thousands of requests) loads.
00204  *
00205  * If a nameserver loses too many requests it is considered down and we
00206  * try not to use it. After a while we send a probe to that nameserver
00207  * (a lookup for google.com) and, if it replies, we consider it working
00208  * again. If the nameserver fails a probe we wait longer to try again
00209  * with the next probe.
00210  */
00211 
00212 #ifndef _TOR_EVENTDNS_H
00213 #define _TOR_EVENTDNS_H
00214 
00215 /* Error codes 0-5 are as described in RFC 1035. */
00216 #define DNS_ERR_NONE 0
00217 /* The name server was unable to interpret the query */
00218 #define DNS_ERR_FORMAT 1
00219 /* The name server was unable to process this query due to a problem with the
00220  * name server */
00221 #define DNS_ERR_SERVERFAILED 2
00222 /* The domain name does not exist */
00223 #define DNS_ERR_NOTEXIST 3
00224 /* The name server does not support the requested kind of query */
00225 #define DNS_ERR_NOTIMPL 4
00226 /* The name server refuses to reform the specified operation for policy
00227  * reasons */
00228 #define DNS_ERR_REFUSED 5
00229 /* The reply was truncated or ill-formated */
00230 #define DNS_ERR_TRUNCATED 65
00231 /* An unknown error occurred */
00232 #define DNS_ERR_UNKNOWN 66
00233 /* Communication with the server timed out */
00234 #define DNS_ERR_TIMEOUT 67
00235 /* The request was canceled because the DNS subsystem was shut down. */
00236 #define DNS_ERR_SHUTDOWN 68
00237 
00238 #define DNS_IPv4_A 1
00239 #define DNS_PTR 2
00240 #define DNS_IPv6_AAAA 3
00241 
00242 #define DNS_QUERY_NO_SEARCH 1
00243 
00244 #define DNS_OPTION_SEARCH 1
00245 #define DNS_OPTION_NAMESERVERS 2
00246 #define DNS_OPTION_MISC 4
00247 #define DNS_OPTIONS_ALL 7
00248 
00249 /*
00250  * The callback that contains the results from a lookup.
00251  * - type is either DNS_IPv4_A or DNS_IPv6_AAAA or DNS_PTR
00252  * - count contains the number of addresses of form type
00253  * - ttl is the number of seconds the resolution may be cached for.
00254  * - addresses needs to be cast according to type
00255  */
00256 typedef void (*evdns_callback_type) (int result, char type, int count, int ttl, void *addresses, void *arg);
00257 
00258 int evdns_init(void);
00259 void evdns_shutdown(int fail_requests);
00260 const char *evdns_err_to_string(int err);
00261 int evdns_nameserver_add(uint32_t address);
00262 int evdns_count_nameservers(void);
00263 int evdns_clear_nameservers_and_suspend(void);
00264 int evdns_resume(void);
00265 int evdns_nameserver_ip_add(const char *ip_as_string);
00266 int evdns_nameserver_sockaddr_add(const struct sockaddr *sa, socklen_t len);
00267 void evdns_set_default_outgoing_bind_address(const struct sockaddr *addr, socklen_t addrlen);
00268 int evdns_resolve_ipv4(const char *name, int flags, evdns_callback_type callback, void *ptr);
00269 int evdns_resolve_ipv6(const char *name, int flags, evdns_callback_type callback, void *ptr);
00270 struct in_addr;
00271 struct in6_addr;
00272 int evdns_resolve_reverse(const struct in_addr *in, int flags, evdns_callback_type callback, void *ptr);
00273 int evdns_resolve_reverse_ipv6(const struct in6_addr *in, int flags, evdns_callback_type callback, void *ptr);
00274 int evdns_set_option(const char *option, const char *val, int flags);
00275 int evdns_resolv_conf_parse(int flags, const char *);
00276 #ifdef _WIN32
00277 int evdns_config_windows_nameservers(void);
00278 #endif
00279 void evdns_search_clear(void);
00280 void evdns_search_add(const char *domain);
00281 void evdns_search_ndots_set(const int ndots);
00282 
00283 typedef void (*evdns_debug_log_fn_type)(int is_warning, const char *msg);
00284 void evdns_set_log_fn(evdns_debug_log_fn_type fn);
00285 
00286 void evdns_set_transaction_id_fn(uint16_t (*fn)(void));
00287 void evdns_set_random_bytes_fn(void (*fn)(char *, size_t));
00288 
00289 #define DNS_NO_SEARCH 1
00290 
00291 /* Structures and functions used to implement a DNS server. */
00292 
00293 struct evdns_server_request {
00294        int flags;
00295        int nquestions;
00296        struct evdns_server_question **questions;
00297 };
00298 struct evdns_server_question {
00299        int type;
00300        int dns_question_class;
00301        char name[1];
00302 };
00303 typedef void (*evdns_request_callback_fn_type)(struct evdns_server_request *, void *);
00304 #define EVDNS_ANSWER_SECTION 0
00305 #define EVDNS_AUTHORITY_SECTION 1
00306 #define EVDNS_ADDITIONAL_SECTION 2
00307 
00308 #define EVDNS_TYPE_A    1
00309 #define EVDNS_TYPE_NS          2
00310 #define EVDNS_TYPE_CNAME   5
00311 #define EVDNS_TYPE_SOA         6
00312 #define EVDNS_TYPE_PTR        12
00313 #define EVDNS_TYPE_MX         15
00314 #define EVDNS_TYPE_TXT        16
00315 #define EVDNS_TYPE_AAAA       28
00316 
00317 #define EVDNS_QTYPE_AXFR 252
00318 #define EVDNS_QTYPE_ALL      255
00319 
00320 #define EVDNS_CLASS_INET   1
00321 
00322 struct evdns_server_port *evdns_add_server_port(tor_socket_t socket, int is_tcp, evdns_request_callback_fn_type callback, void *user_data);
00323 void evdns_close_server_port(struct evdns_server_port *port);
00324 
00325 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);
00326 int evdns_server_request_add_a_reply(struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl);
00327 int evdns_server_request_add_aaaa_reply(struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl);
00328 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);
00329 int evdns_server_request_add_cname_reply(struct evdns_server_request *req, const char *name, const char *cname, int ttl);
00330 
00331 struct sockaddr;
00332 int evdns_server_request_get_requesting_addr(struct evdns_server_request *req, struct sockaddr *sa, int addr_len);
00333 
00334 int evdns_server_request_respond(struct evdns_server_request *req, int err);
00335 int evdns_server_request_drop(struct evdns_server_request *req);
00336 
00337 #endif // !EVENTDNS_H