resolver.h

Go to the documentation of this file.

/*
 * Copyright (C) 2004-2014  Internet Systems Consortium, Inc. ("ISC")
 * Copyright (C) 1999-2001, 2003  Internet Software Consortium.
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
 */

/* $Id: resolver.h,v 1.72 2011/12/05 17:10:51 each Exp $ */

#ifndef DNS_RESOLVER_H
#define DNS_RESOLVER_H 1

/*****
 ***** Module Info
 *****/

/*! \file dns/resolver.h
 *
 * \brief
 * This is the BIND 9 resolver, the module responsible for resolving DNS
 * requests by iteratively querying authoritative servers and following
 * referrals.  This is a "full resolver", not to be confused with
 * the stub resolvers most people associate with the word "resolver".
 * The full resolver is part of the caching name server or resolver
 * daemon the stub resolver talks to.
 *
 * MP:
 *\li   The module ensures appropriate synchronization of data structures it
 *      creates and manipulates.
 *
 * Reliability:
 *\li   No anticipated impact.
 *
 * Resources:
 *\li   TBS
 *
 * Security:
 *\li   No anticipated impact.
 *
 * Standards:
 *\li   RFCs:   1034, 1035, 2181, TBS
 *\li   Drafts: TBS
 */

#include <isc/lang.h>
#include <isc/socket.h>

#include <dns/types.h>
#include <dns/fixedname.h>

ISC_LANG_BEGINDECLS

/*%
 * A dns_fetchevent_t is sent when a 'fetch' completes.  Any of 'db',
 * 'node', 'rdataset', and 'sigrdataset' may be bound.  It is the
 * receiver's responsibility to detach before freeing the event.
 * \brief
 * 'rdataset', 'sigrdataset', 'client' and 'id' are the values that were
 * supplied when dns_resolver_createfetch() was called.  They are returned
 *  to the caller so that they may be freed.
 */
typedef struct dns_fetchevent {
        ISC_EVENT_COMMON(struct dns_fetchevent);
        dns_fetch_t *                   fetch;
        isc_result_t                    result;
        dns_rdatatype_t                 qtype;
        dns_db_t *                      db;
        dns_dbnode_t *                  node;
        dns_rdataset_t *                rdataset;
        dns_rdataset_t *                sigrdataset;
        dns_fixedname_t                 foundname;
        isc_sockaddr_t *                client;
        dns_messageid_t                 id;
        isc_result_t                    vresult;
} dns_fetchevent_t;

/*
 * Options that modify how a 'fetch' is done.
 */
#define DNS_FETCHOPT_TCP                0x001        /*%< Use TCP. */
#define DNS_FETCHOPT_UNSHARED           0x002        /*%< See below. */
#define DNS_FETCHOPT_RECURSIVE          0x004        /*%< Set RD? */
#define DNS_FETCHOPT_NOEDNS0            0x008        /*%< Do not use EDNS. */
#define DNS_FETCHOPT_FORWARDONLY        0x010        /*%< Only use forwarders. */
#define DNS_FETCHOPT_NOVALIDATE         0x020        /*%< Disable validation. */
#define DNS_FETCHOPT_EDNS512            0x040        /*%< Advertise a 512 byte
                                                          UDP buffer. */
#define DNS_FETCHOPT_WANTNSID           0x080        /*%< Request NSID */
#define DNS_FETCHOPT_PREFETCH           0x100        /*%< Do prefetch */
#define DNS_FETCHOPT_NOCDFLAG           0x200        /*%< Don't set CD flag. */
#define DNS_FETCHOPT_NONTA              0x400        /*%< Ignore NTA table. */

/* Reserved in use by adb.c             0x00400000 */
#define DNS_FETCHOPT_EDNSVERSIONSET     0x00800000
#define DNS_FETCHOPT_EDNSVERSIONMASK    0xff000000
#define DNS_FETCHOPT_EDNSVERSIONSHIFT   24

/*
 * Upper bounds of class of query RTT (ms).  Corresponds to
 * dns_resstatscounter_queryrttX statistics counters.
 */
#define DNS_RESOLVER_QRYRTTCLASS0       10
#define DNS_RESOLVER_QRYRTTCLASS0STR    "10"
#define DNS_RESOLVER_QRYRTTCLASS1       100
#define DNS_RESOLVER_QRYRTTCLASS1STR    "100"
#define DNS_RESOLVER_QRYRTTCLASS2       500
#define DNS_RESOLVER_QRYRTTCLASS2STR    "500"
#define DNS_RESOLVER_QRYRTTCLASS3       800
#define DNS_RESOLVER_QRYRTTCLASS3STR    "800"
#define DNS_RESOLVER_QRYRTTCLASS4       1600
#define DNS_RESOLVER_QRYRTTCLASS4STR    "1600"

/*
 * XXXRTH  Should this API be made semi-private?  (I.e.
 * _dns_resolver_create()).
 */

#define DNS_RESOLVER_CHECKNAMES         0x01
#define DNS_RESOLVER_CHECKNAMESFAIL     0x02

isc_result_t
dns_resolver_create(dns_view_t *view,
                    isc_taskmgr_t *taskmgr,
                    unsigned int ntasks, unsigned int ndisp,
                    isc_socketmgr_t *socketmgr,
                    isc_timermgr_t *timermgr,
                    unsigned int options,
                    dns_dispatchmgr_t *dispatchmgr,
                    dns_dispatch_t *dispatchv4,
                    dns_dispatch_t *dispatchv6,
                    dns_resolver_t **resp);

/*%<
 * Create a resolver.
 *
 * Notes:
 *
 *\li   Generally, applications should not create a resolver directly, but
 *      should instead call dns_view_createresolver().
 *
 * Requires:
 *
 *\li   'view' is a valid view.
 *
 *\li   'taskmgr' is a valid task manager.
 *
 *\li   'ntasks' > 0.
 *
 *\li   'socketmgr' is a valid socket manager.
 *
 *\li   'timermgr' is a valid timer manager.
 *
 *\li   'dispatchv4' is a dispatch with an IPv4 UDP socket, or is NULL.
 *      If not NULL, 'ndisp' clones of it will be created by the resolver.
 *
 *\li   'dispatchv6' is a dispatch with an IPv6 UDP socket, or is NULL.
 *      If not NULL, 'ndisp' clones of it will be created by the resolver.
 *
 *\li   resp != NULL && *resp == NULL.
 *
 * Returns:
 *
 *\li   #ISC_R_SUCCESS                          On success.
 *
 *\li   Anything else                           Failure.
 */

void
dns_resolver_freeze(dns_resolver_t *res);
/*%<
 * Freeze resolver.
 *
 * Notes:
 *
 *\li   Certain configuration changes cannot be made after the resolver
 *      is frozen.  Fetches cannot be created until the resolver is frozen.
 *
 * Requires:
 *
 *\li   'res' is a valid resolver.
 *
 * Ensures:
 *
 *\li   'res' is frozen.
 */

void
dns_resolver_prime(dns_resolver_t *res);
/*%<
 * Prime resolver.
 *
 * Notes:
 *
 *\li   Resolvers which have a forwarding policy other than dns_fwdpolicy_only
 *      need to be primed with the root nameservers, otherwise the root
 *      nameserver hints data may be used indefinitely.  This function requests
 *      that the resolver start a priming fetch, if it isn't already priming.
 *
 * Requires:
 *
 *\li   'res' is a valid, frozen resolver.
 */


void
dns_resolver_whenshutdown(dns_resolver_t *res, isc_task_t *task,
                          isc_event_t **eventp);
/*%<
 * Send '*eventp' to 'task' when 'res' has completed shutdown.
 *
 * Notes:
 *
 *\li   It is not safe to detach the last reference to 'res' until
 *      shutdown is complete.
 *
 * Requires:
 *
 *\li   'res' is a valid resolver.
 *
 *\li   'task' is a valid task.
 *
 *\li   *eventp is a valid event.
 *
 * Ensures:
 *
 *\li   *eventp == NULL.
 */

void
dns_resolver_shutdown(dns_resolver_t *res);
/*%<
 * Start the shutdown process for 'res'.
 *
 * Notes:
 *
 *\li   This call has no effect if the resolver is already shutting down.
 *
 * Requires:
 *
 *\li   'res' is a valid resolver.
 */

void
dns_resolver_attach(dns_resolver_t *source, dns_resolver_t **targetp);

void
dns_resolver_detach(dns_resolver_t **resp);

isc_result_t
dns_resolver_createfetch(dns_resolver_t *res, dns_name_t *name,
                         dns_rdatatype_t type,
                         dns_name_t *domain, dns_rdataset_t *nameservers,
                         dns_forwarders_t *forwarders,
                         unsigned int options, isc_task_t *task,
                         isc_taskaction_t action, void *arg,
                         dns_rdataset_t *rdataset,
                         dns_rdataset_t *sigrdataset,
                         dns_fetch_t **fetchp);

isc_result_t
dns_resolver_createfetch2(dns_resolver_t *res, dns_name_t *name,
                          dns_rdatatype_t type,
                          dns_name_t *domain, dns_rdataset_t *nameservers,
                          dns_forwarders_t *forwarders,
                          isc_sockaddr_t *client, isc_uint16_t id,
                          unsigned int options, isc_task_t *task,
                          isc_taskaction_t action, void *arg,
                          dns_rdataset_t *rdataset,
                          dns_rdataset_t *sigrdataset,
                          dns_fetch_t **fetchp);
isc_result_t
dns_resolver_createfetch3(dns_resolver_t *res, dns_name_t *name,
                          dns_rdatatype_t type,
                          dns_name_t *domain, dns_rdataset_t *nameservers,
                          dns_forwarders_t *forwarders,
                          isc_sockaddr_t *client, isc_uint16_t id,
                          unsigned int options, unsigned int depth,
                          isc_counter_t *qc, isc_task_t *task,
                          isc_taskaction_t action, void *arg,
                          dns_rdataset_t *rdataset,
                          dns_rdataset_t *sigrdataset,
                          dns_fetch_t **fetchp);
/*%<
 * Recurse to answer a question.
 *
 * Notes:
 *
 *\li   This call starts a query for 'name', type 'type'.
 *
 *\li   The 'domain' is a parent domain of 'name' for which
 *      a set of name servers 'nameservers' is known.  If no
 *      such name server information is available, set
 *      'domain' and 'nameservers' to NULL.
 *
 *\li   'forwarders' is unimplemented, and subject to change when
 *      we figure out how selective forwarding will work.
 *
 *\li   When the fetch completes (successfully or otherwise), a
 *      #DNS_EVENT_FETCHDONE event with action 'action' and arg 'arg' will be
 *      posted to 'task'.
 *
 *\li   The values of 'rdataset' and 'sigrdataset' will be returned in
 *      the FETCHDONE event.
 *
 *\li   'client' and 'id' are used for duplicate query detection.  '*client'
 *      must remain stable until after 'action' has been called or
 *      dns_resolver_cancelfetch() is called.
 *
 * Requires:
 *
 *\li   'res' is a valid resolver that has been frozen.
 *
 *\li   'name' is a valid name.
 *
 *\li   'type' is not a meta type other than ANY.
 *
 *\li   'domain' is a valid name or NULL.
 *
 *\li   'nameservers' is a valid NS rdataset (whose owner name is 'domain')
 *      iff. 'domain' is not NULL.
 *
 *\li   'forwarders' is NULL.
 *
 *\li   'client' is a valid sockaddr or NULL.
 *
 *\li   'options' contains valid options.
 *
 *\li   'rdataset' is a valid, disassociated rdataset.
 *
 *\li   'sigrdataset' is NULL, or is a valid, disassociated rdataset.
 *
 *\li   fetchp != NULL && *fetchp == NULL.
 *
 * Returns:
 *
 *\li   #ISC_R_SUCCESS                                  Success
 *\li   #DNS_R_DUPLICATE
 *\li   #DNS_R_DROP
 *
 *\li   Many other values are possible, all of which indicate failure.
 */

void
dns_resolver_cancelfetch(dns_fetch_t *fetch);
/*%<
 * Cancel 'fetch'.
 *
 * Notes:
 *
 *\li   If 'fetch' has not completed, post its FETCHDONE event with a
 *      result code of #ISC_R_CANCELED.
 *
 * Requires:
 *
 *\li   'fetch' is a valid fetch.
 */

void
dns_resolver_destroyfetch(dns_fetch_t **fetchp);
/*%<
 * Destroy 'fetch'.
 *
 * Requires:
 *
 *\li   '*fetchp' is a valid fetch.
 *
 *\li   The caller has received the FETCHDONE event (either because the
 *      fetch completed or because dns_resolver_cancelfetch() was called).
 *
 * Ensures:
 *
 *\li   *fetchp == NULL.
 */

void
dns_resolver_logfetch(dns_fetch_t *fetch, isc_log_t *lctx,
                      isc_logcategory_t *category, isc_logmodule_t *module,
                      int level, isc_boolean_t duplicateok);
/*%<
 * Dump a log message on internal state at the completion of given 'fetch'.
 * 'lctx', 'category', 'module', and 'level' are used to write the log message.
 * By default, only one log message is written even if the corresponding fetch
 * context serves multiple clients; if 'duplicateok' is true the suppression
 * is disabled and the message can be written every time this function is
 * called.
 *
 * Requires:
 *
 *\li   'fetch' is a valid fetch, and has completed.
 */

dns_dispatchmgr_t *
dns_resolver_dispatchmgr(dns_resolver_t *resolver);

dns_dispatch_t *
dns_resolver_dispatchv4(dns_resolver_t *resolver);

dns_dispatch_t *
dns_resolver_dispatchv6(dns_resolver_t *resolver);

isc_socketmgr_t *
dns_resolver_socketmgr(dns_resolver_t *resolver);

isc_taskmgr_t *
dns_resolver_taskmgr(dns_resolver_t *resolver);

isc_uint32_t
dns_resolver_getlamettl(dns_resolver_t *resolver);
/*%<
 * Get the resolver's lame-ttl.  zero => no lame processing.
 *
 * Requires:
 *\li   'resolver' to be valid.
 */

void
dns_resolver_setlamettl(dns_resolver_t *resolver, isc_uint32_t lame_ttl);
/*%<
 * Set the resolver's lame-ttl.  zero => no lame processing.
 *
 * Requires:
 *\li   'resolver' to be valid.
 */

unsigned int
dns_resolver_nrunning(dns_resolver_t *resolver);
/*%<
 * Return the number of currently running resolutions in this
 * resolver.  This is may be less than the number of outstanding
 * fetches due to multiple identical fetches, or more than the
 * number of of outstanding fetches due to the fact that resolution
 * can continue even though a fetch has been canceled.
 */

isc_result_t
dns_resolver_addalternate(dns_resolver_t *resolver, isc_sockaddr_t *alt,
                          dns_name_t *name, in_port_t port);
/*%<
 * Add alternate addresses to be tried in the event that the nameservers
 * for a zone are not available in the address families supported by the
 * operating system.
 *
 * Require:
 * \li  only one of 'name' or 'alt' to be valid.
 */

void
dns_resolver_setudpsize(dns_resolver_t *resolver, isc_uint16_t udpsize);
/*%<
 * Set the EDNS UDP buffer size advertised by the server.
 */

isc_uint16_t
dns_resolver_getudpsize(dns_resolver_t *resolver);
/*%<
 * Get the current EDNS UDP buffer size.
 */

void
dns_resolver_reset_algorithms(dns_resolver_t *resolver);
/*%<
 * Clear the disabled DNSSEC algorithms.
 */

void
dns_resolver_reset_ds_digests(dns_resolver_t *resolver);
/*%<
 * Clear the disabled DS/DLV digest types.
 */

isc_result_t
dns_resolver_disable_algorithm(dns_resolver_t *resolver, dns_name_t *name,
                               unsigned int alg);
/*%<
 * Mark the given DNSSEC algorithm as disabled and below 'name'.
 * Valid algorithms are less than 256.
 *
 * Returns:
 *\li   #ISC_R_SUCCESS
 *\li   #ISC_R_RANGE
 *\li   #ISC_R_NOMEMORY
 */

isc_result_t
dns_resolver_disable_ds_digest(dns_resolver_t *resolver, dns_name_t *name,
                               unsigned int digest_type);
/*%<
 * Mark the given DS/DLV digest type as disabled and below 'name'.
 * Valid types are less than 256.
 *
 * Returns:
 *\li   #ISC_R_SUCCESS
 *\li   #ISC_R_RANGE
 *\li   #ISC_R_NOMEMORY
 */

isc_boolean_t
dns_resolver_algorithm_supported(dns_resolver_t *resolver, dns_name_t *name,
                                 unsigned int alg);
/*%<
 * Check if the given algorithm is supported by this resolver.
 * This checks whether the algorithm has been disabled via
 * dns_resolver_disable_algorithm(), then checks the underlying
 * crypto libraries if it was not specifically disabled.
 */

isc_boolean_t
dns_resolver_ds_digest_supported(dns_resolver_t *resolver, dns_name_t *name,
                                 unsigned int digest_type);
/*%<
 * Check if the given digest type is supported by this resolver.
 * This checks whether the digest type has been disabled via
 * dns_resolver_disable_ds_digest(), then checks the underlying
 * crypto libraries if it was not specifically disabled.
 */

void
dns_resolver_resetmustbesecure(dns_resolver_t *resolver);

isc_result_t
dns_resolver_setmustbesecure(dns_resolver_t *resolver, dns_name_t *name,
                             isc_boolean_t value);

isc_boolean_t
dns_resolver_getmustbesecure(dns_resolver_t *resolver, dns_name_t *name);


void
dns_resolver_settimeout(dns_resolver_t *resolver, unsigned int seconds);
/*%<
 * Set the length of time the resolver will work on a query, in seconds.
 *
 * If timeout is 0, the default timeout will be applied.
 *
 * Requires:
 * \li  resolver to be valid.
 */

unsigned int
dns_resolver_gettimeout(dns_resolver_t *resolver);
/*%<
 * Get the current length of time the resolver will work on a query, in seconds.
 *
 * Requires:
 * \li  resolver to be valid.
 */

void
dns_resolver_setclientsperquery(dns_resolver_t *resolver,
                                isc_uint32_t min, isc_uint32_t max);

void
dns_resolver_getclientsperquery(dns_resolver_t *resolver, isc_uint32_t *cur,
                                isc_uint32_t *min, isc_uint32_t *max);

isc_boolean_t
dns_resolver_getzeronosoattl(dns_resolver_t *resolver);

void
dns_resolver_setzeronosoattl(dns_resolver_t *resolver, isc_boolean_t state);

unsigned int
dns_resolver_getoptions(dns_resolver_t *resolver);

void
dns_resolver_addbadcache(dns_resolver_t *resolver, dns_name_t *name,
                         dns_rdatatype_t type, isc_time_t *expire);
/*%<
 * Add a entry to the bad cache for <name,type> that will expire at 'expire'.
 *
 * Requires:
 * \li  resolver to be valid.
 * \li  name to be valid.
 */

isc_boolean_t
dns_resolver_getbadcache(dns_resolver_t *resolver, dns_name_t *name,
                         dns_rdatatype_t type, isc_time_t *now);
/*%<
 * Check to see if there is a unexpired entry in the bad cache for
 * <name,type>.
 *
 * Requires:
 * \li  resolver to be valid.
 * \li  name to be valid.
 */

void
dns_resolver_flushbadcache(dns_resolver_t *resolver, dns_name_t *name);
/*%<
 * Flush the bad cache of all entries at 'name' if 'name' is non NULL.
 * Flush the entire bad cache if 'name' is NULL.
 *
 * Requires:
 * \li  resolver to be valid.
 */

void
dns_resolver_flushbadnames(dns_resolver_t *resolver, dns_name_t *name);
/*%<
 * Flush the bad cache of all entries at or below 'name'.
 *
 * Requires:
 * \li  resolver to be valid.
 * \li  name != NULL
 */

void
dns_resolver_printbadcache(dns_resolver_t *resolver, FILE *fp);
/*%
 * Print out the contents of the bad cache to 'fp'.
 *
 * Requires:
 * \li  resolver to be valid.
 */

void
dns_resolver_setquerydscp4(dns_resolver_t *resolver, isc_dscp_t dscp);
isc_dscp_t
dns_resolver_getquerydscp4(dns_resolver_t *resolver);

void
dns_resolver_setquerydscp6(dns_resolver_t *resolver, isc_dscp_t dscp);
isc_dscp_t
dns_resolver_getquerydscp6(dns_resolver_t *resolver);
/*%
 * Get and set the DSCP values for the resolver's IPv4 and IPV6 query
 * sources.
 *
 * Requires:
 * \li  resolver to be valid.
 */

void
dns_resolver_setmaxdepth(dns_resolver_t *resolver, unsigned int maxdepth);
unsigned int
dns_resolver_getmaxdepth(dns_resolver_t *resolver);
/*%
 * Get and set how many NS indirections will be followed when looking for
 * nameserver addresses.
 *
 * Requires:
 * \li  resolver to be valid.
 */

void
dns_resolver_setmaxqueries(dns_resolver_t *resolver, unsigned int queries);
unsigned int
dns_resolver_getmaxqueries(dns_resolver_t *resolver);
/*%
 * Get and set how many iterative queries will be allowed before
 * terminating a recursive query.
 *
 * Requires:
 * \li  resolver to be valid.
 */

ISC_LANG_ENDDECLS

#endif /* DNS_RESOLVER_H */

---