contrib/libevent/evdns.h

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