/contrib/bind9/lib/dns/include/dns/resolver.h
https://bitbucket.org/freebsd/freebsd-head/ · C Header · 577 lines · 164 code · 59 blank · 354 comment · 0 complexity · d3d75e867adef74da0fdf113abc36358 MD5 · raw file
- /*
- * Copyright (C) 2004-2012 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$ */
- #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 0x01 /*%< Use TCP. */
- #define DNS_FETCHOPT_UNSHARED 0x02 /*%< See below. */
- #define DNS_FETCHOPT_RECURSIVE 0x04 /*%< Set RD? */
- #define DNS_FETCHOPT_NOEDNS0 0x08 /*%< Do not use EDNS. */
- #define DNS_FETCHOPT_FORWARDONLY 0x10 /*%< Only use forwarders. */
- #define DNS_FETCHOPT_NOVALIDATE 0x20 /*%< Disable validation. */
- #define DNS_FETCHOPT_EDNS512 0x40 /*%< Advertise a 512 byte
- UDP buffer. */
- #define DNS_FETCHOPT_WANTNSID 0x80 /*%< Request NSID */
- #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,
- 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 valid dispatcher with an IPv4 UDP socket, or is NULL.
- *
- *\li 'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.
- *
- *\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);
- /*%<
- * 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.
- */
- isc_result_t
- dns_resolver_disable_algorithm(dns_resolver_t *resolver, dns_name_t *name,
- unsigned int alg);
- /*%<
- * Mark the give 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_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 if the algorithm has been disabled via
- * dns_resolver_disable_algorithm() then the underlying
- * crypto libraries if not specifically disabled.
- */
- isc_boolean_t
- dns_resolver_digest_supported(dns_resolver_t *resolver, unsigned int digest_type);
- /*%<
- * Is this digest type supported.
- */
- 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_printbadcache(dns_resolver_t *resolver, FILE *fp);
- /*%
- * Print out the contents of the bad cache to 'fp'.
- *
- * Requires:
- * \li resolver to be valid.
- */
- ISC_LANG_ENDDECLS
- #endif /* DNS_RESOLVER_H */