libunbound.c File Reference

This file contains functions to resolve DNS queries and validate the answers. More...

#include "libunbound/unbound.h"
#include "config.h"
#include "libunbound/context.h"
#include "libunbound/libworker.h"
#include "util/locks.h"
#include "util/config_file.h"
#include "util/alloc.h"
#include "util/module.h"
#include "util/regional.h"
#include "util/log.h"
#include "util/random.h"
#include "util/net_help.h"
#include "services/modstack.h"
#include "services/localzone.h"
#include "services/cache/infra.h"
#include "services/cache/rrset.h"

Functions

struct ub_ctxub_ctx_create ()
 Create a resolving and validation context.
static void delq (rbnode_t *n, void *arg)
 delete q
void ub_ctx_delete (struct ub_ctx *ctx)
 Destroy a validation context and free all its resources.
int ub_ctx_set_option (struct ub_ctx *ctx, char *opt, char *val)
 Set an option for the context.
int ub_ctx_config (struct ub_ctx *ctx, char *fname)
 setup configuration for the given context.
int ub_ctx_add_ta (struct ub_ctx *ctx, char *ta)
 Add a trust anchor to the given context.
int ub_ctx_add_ta_file (struct ub_ctx *ctx, char *fname)
 Add trust anchors to the given context.
int ub_ctx_trustedkeys (struct ub_ctx *ctx, char *fname)
 Add trust anchors to the given context.
int ub_ctx_debuglevel (struct ub_ctx *ctx, int d)
 Set debug verbosity for the context Output is directed to stderr.
int ub_ctx_debugout (struct ub_ctx *ctx, void *out)
 Set debug output (and error output) to the specified stream.
int ub_ctx_async (struct ub_ctx *ctx, int dothread)
 Set a context behaviour for asynchronous action.
static int pollit (struct ub_ctx *ctx, struct timeval *t)
 perform a select() on the result read pipe
int ub_poll (struct ub_ctx *ctx)
 Poll a context to see if it has any new results Do not poll in a loop, instead extract the fd below to poll for readiness, and then check, or wait using the wait routine.
int ub_fd (struct ub_ctx *ctx)
 Get file descriptor.
static int process_answer_detail (struct ub_ctx *ctx, uint8_t *msg, uint32_t len, ub_callback_t *cb, void **cbarg, int *err, struct ub_result **res)
 process answer from bg worker
static int process_answer (struct ub_ctx *ctx, uint8_t *msg, uint32_t len)
 process answer from bg worker
int ub_process (struct ub_ctx *ctx)
 Call this routine to continue processing results from the validating resolver (when the fd becomes readable).
int ub_wait (struct ub_ctx *ctx)
 Wait for a context to finish with results.
int ub_resolve (struct ub_ctx *ctx, char *name, int rrtype, int rrclass, struct ub_result **result)
 Perform resolution and validation of the target name.
int ub_resolve_async (struct ub_ctx *ctx, char *name, int rrtype, int rrclass, void *mydata, ub_callback_t callback, int *async_id)
 Perform resolution and validation of the target name.
int ub_cancel (struct ub_ctx *ctx, int async_id)
 Cancel an async query in progress.
void ub_resolve_free (struct ub_result *result)
 Free storage associated with a result structure.
const char * ub_strerror (int err)
 Convert error value to a human readable string.
int ub_ctx_set_fwd (struct ub_ctx *ctx, char *addr)
 Set machine to forward DNS queries to, the caching resolver to use.
int ub_ctx_resolvconf (struct ub_ctx *ctx, char *fname)
 Read list of nameservers to use from the filename given.
int ub_ctx_hosts (struct ub_ctx *ctx, char *fname)
 Read list of hosts from the filename given.


Detailed Description

This file contains functions to resolve DNS queries and validate the answers.

Synchonously and asynchronously.


Function Documentation

struct ub_ctx* ub_ctx_create ( void   )  [read]

Create a resolving and validation context.

The information from /etc/resolv.conf and /etc/hosts is not utilised by default. Use ub_ctx_resolvconf and ub_ctx_hosts to read them.

Returns:
a new context. default initialisation. returns NULL on error.

References module_env::alloc, alloc_init(), module_env::cfg, ub_ctx::cfglock, config_create_forlib(), context_query_cmp(), ub_ctx::env, fd_set_nonblock(), log_err(), log_ident_set(), log_init(), ub_ctx::mods, modstack_init(), module_env::need_to_validate, ub_ctx::qqpipe, ub_ctx::qqpipe_lock, ub_ctx::queries, rbtree_init(), ub_ctx::rrpipe, ub_ctx::rrpipe_lock, ub_ctx::seed_rnd, ub_ctx::superalloc, ub_initstate(), ub_randfree(), verbosity, and module_env::worker.

Referenced by main().

void ub_ctx_delete ( struct ub_ctx ctx  ) 

int ub_ctx_set_option ( struct ub_ctx ctx,
char *  opt,
char *  val 
)

Set an option for the context.

Parameters:
ctx,: context.
opt,: option name from the unbound.conf config file format. (not all settings applicable). The name includes the trailing ':' for example ub_ctx_set_option("logfile:", "mylog.txt"); This is a power-users interface that lets you specify all sorts of options. For some specific options, such as adding trust anchors, special routines exist.
val,: value of the option.
Returns:
: 0 if OK, else error.

References module_env::cfg, ub_ctx::cfglock, config_set_option(), ub_ctx::env, ub_ctx::finalized, UB_AFTERFINAL, UB_NOERROR, and UB_SYNTAX.

int ub_ctx_config ( struct ub_ctx ctx,
char *  fname 
)

setup configuration for the given context.

Parameters:
ctx,: context.
fname,: unbound config file (not all settings applicable). This is a power-users interface that lets you specify all sorts of options. For some specific options, such as adding trust anchors, special routines exist.
Returns:
: 0 if OK, else error.

References module_env::cfg, ub_ctx::cfglock, config_read(), ub_ctx::env, ub_ctx::finalized, UB_AFTERFINAL, UB_NOERROR, and UB_SYNTAX.

Referenced by main().

int ub_ctx_add_ta ( struct ub_ctx ctx,
char *  ta 
)

Add a trust anchor to the given context.

The trust anchor is a string, on one line, that holds a valid DNSKEY or DS RR.

Parameters:
ctx,: context. At this time it is only possible to add trusted keys before the first resolve is done.
ta,: string, with zone-format RR on one line. [domainname] [TTL optional] [type] [class optional] [rdata contents]
Returns:
0 if OK, else error.

References module_env::cfg, cfg_strlist_insert(), ub_ctx::cfglock, ub_ctx::env, ub_ctx::finalized, config_file::trust_anchor_list, UB_AFTERFINAL, UB_NOERROR, and UB_NOMEM.

Referenced by main().

int ub_ctx_add_ta_file ( struct ub_ctx ctx,
char *  fname 
)

Add trust anchors to the given context.

Pass name of a file with DS and DNSKEY records (like from dig or drill).

Parameters:
ctx,: context. At this time it is only possible to add trusted keys before the first resolve is done.
fname,: filename of file with keyfile with trust anchors.
Returns:
0 if OK, else error.

References module_env::cfg, cfg_strlist_insert(), ub_ctx::cfglock, ub_ctx::env, ub_ctx::finalized, config_file::trust_anchor_file_list, UB_AFTERFINAL, UB_NOERROR, and UB_NOMEM.

Referenced by main().

int ub_ctx_trustedkeys ( struct ub_ctx ctx,
char *  fname 
)

Add trust anchors to the given context.

Pass the name of a bind-style config file with trusted-keys{}.

Parameters:
ctx,: context. At this time it is only possible to add trusted keys before the first resolve is done.
fname,: filename of file with bind-style config entries with trust anchors.
Returns:
0 if OK, else error.

References module_env::cfg, cfg_strlist_insert(), ub_ctx::cfglock, ub_ctx::env, ub_ctx::finalized, config_file::trusted_keys_file_list, UB_AFTERFINAL, UB_NOERROR, and UB_NOMEM.

Referenced by main().

int ub_ctx_debuglevel ( struct ub_ctx ctx,
int  d 
)

Set debug verbosity for the context Output is directed to stderr.

Parameters:
ctx,: context.
d,: debug level, 0 is off, 1 is very minimal, 2 is detailed, and 3 is lots.
Returns:
0 if OK, else error.

References module_env::cfg, ub_ctx::cfglock, ub_ctx::env, UB_NOERROR, config_file::verbosity, and verbosity.

Referenced by main().

int ub_ctx_debugout ( struct ub_ctx ctx,
void *  out 
)

Set debug output (and error output) to the specified stream.

Pass NULL to disable. Default is stderr.

Parameters:
ctx,: context.
out,: FILE* out file stream to log to. Type void* to avoid stdio dependency of this header file.
Returns:
0 if OK, else error.

References ub_ctx::cfglock, log_file(), ub_ctx::log_out, ub_ctx::logfile_override, and UB_NOERROR.

int ub_ctx_async ( struct ub_ctx ctx,
int  dothread 
)

Set a context behaviour for asynchronous action.

Parameters:
ctx,: context.
dothread,: if true, enables threading and a call to resolve_async() creates a thread to handle work in the background. If false, a process is forked to handle work in the background. Changes to this setting after async() calls have been made have no effect (delete and re-create the context to change).
Returns:
0 if OK, else error.

References ub_ctx::cfglock, ub_ctx::dothread, ub_ctx::finalized, UB_AFTERFINAL, and UB_NOERROR.

Referenced by main().

int ub_poll ( struct ub_ctx ctx  ) 

Poll a context to see if it has any new results Do not poll in a loop, instead extract the fd below to poll for readiness, and then check, or wait using the wait routine.

Parameters:
ctx,: context.
Returns:
: 0 if nothing to read, or nonzero if a result is available. If nonzero, call ctx_process() to do callbacks.

References pollit().

int ub_fd ( struct ub_ctx ctx  ) 

Get file descriptor.

Wait for it to become readable, at this point answers are returned from the asynchronous validating resolver. Then call the ub_process to continue processing. This routine works immediately after context creation, the fd does not change.

Parameters:
ctx,: context.
Returns:
: -1 on error, or file descriptor to use select(2) with.

References ub_ctx::rrpipe.

int ub_process ( struct ub_ctx ctx  ) 

Call this routine to continue processing results from the validating resolver (when the fd becomes readable).

Will perform necessary callbacks.

Parameters:
ctx,: context
Returns:
: 0 if OK, else error.

References ub_result::len, libworker_read_msg(), process_answer(), ub_ctx::rrpipe, ub_ctx::rrpipe_lock, UB_NOERROR, and UB_PIPE.

Referenced by main().

int ub_wait ( struct ub_ctx ctx  ) 

Wait for a context to finish with results.

Calls ub_process() after the wait for you. After the wait, there are no more outstanding asynchronous queries.

Parameters:
ctx,: context.
Returns:
: 0 if OK, else error.

References ub_ctx::cfglock, ub_result::len, libworker_read_msg(), ub_ctx::num_async, pollit(), process_answer_detail(), ub_ctx::rrpipe, ub_ctx::rrpipe_lock, UB_NOERROR, and UB_PIPE.

Referenced by ext_thread().

int ub_resolve ( struct ub_ctx ctx,
char *  name,
int  rrtype,
int  rrclass,
struct ub_result **  result 
)

Perform resolution and validation of the target name.

Parameters:
ctx,: context. The context is finalized, and can no longer accept config changes.
name,: domain name in text format (a zero terminated text string).
rrtype,: type of RR in host order, 1 is A (address).
rrclass,: class of RR in host order, 1 is IN (for internet).
result,: the result data is returned in a newly allocated result structure. May be NULL on return, return value is set to an error in that case (out of memory).
Returns:
0 if OK, else error.

References ub_result::answer_len, ub_result::answer_packet, ub_ctx::cfglock, context_finalize(), context_new(), context_query_delete(), ub_ctx::finalized, rbnode_t::key, libworker_fg(), ctx_query::msg, ctx_query::msg_len, ctx_query::node, ub_ctx::queries, rbtree_delete(), ctx_query::res, UB_NOERROR, and UB_NOMEM.

Referenced by dnslook(), ext_thread(), main(), and process().

int ub_resolve_async ( struct ub_ctx ctx,
char *  name,
int  rrtype,
int  rrclass,
void *  mydata,
ub_callback_t  callback,
int *  async_id 
)

Perform resolution and validation of the target name.

Asynchronous, after a while, the callback will be called with your data and the result.

Parameters:
ctx,: context. If no thread or process has been created yet to perform the work in the background, it is created now. The context is finalized, and can no longer accept config changes.
name,: domain name in text format (a string).
rrtype,: type of RR in host order, 1 is A.
rrclass,: class of RR in host order, 1 is IN (for internet).
mydata,: this data is your own data (you can pass NULL), and is passed on to the callback function.
callback,: this is called on completion of the resolution. It is called as: void callback(void* mydata, int err, struct ub_result* result) with mydata: the same as passed here, you may pass NULL, with err: is 0 when a result has been found. with result: a newly allocated result structure. The result may be NULL, in that case err is set.
If an error happens during processing, your callback will be called with error set to a nonzero value (and result==NULL).
Parameters:
async_id,: if you pass a non-NULL value, an identifier number is returned for the query as it is in progress. It can be used to cancel the query.
Returns:
0 if OK, else error.

References ub_ctx::cfglock, context_finalize(), context_new(), context_query_delete(), context_serialize_new_query(), ub_ctx::created_bg, ub_ctx::finalized, rbnode_t::key, libworker_bg(), libworker_write_msg(), ctx_query::msg, ctx_query::node, ub_ctx::num_async, ub_ctx::qqpipe, ub_ctx::qqpipe_lock, ub_ctx::queries, ctx_query::querynum, rbtree_delete(), UB_NOERROR, UB_NOMEM, and UB_PIPE.

Referenced by ext_thread(), and main().

int ub_cancel ( struct ub_ctx ctx,
int  async_id 
)

Cancel an async query in progress.

Its callback will not be called.

Parameters:
ctx,: context.
async_id,: which query to cancel.
Returns:
0 if OK, else error.

References ctx_query::async, ctx_query::cancelled, ub_ctx::cfglock, context_query_delete(), context_serialize_cancel(), ub_ctx::dothread, rbnode_t::key, libworker_write_msg(), log_assert, ctx_query::msg, ctx_query::node, ub_ctx::num_async, ub_ctx::qqpipe, ub_ctx::qqpipe_lock, ub_ctx::queries, rbtree_delete(), rbtree_search(), UB_NOERROR, UB_NOMEM, and UB_PIPE.

Referenced by ext_thread(), and main().

void ub_resolve_free ( struct ub_result result  ) 

Free storage associated with a result structure.

Parameters:
result,: to free

References ub_result::answer_packet, ub_result::canonname, ub_result::data, ub_result::len, and ub_result::qname.

Referenced by context_query_delete(), dnslook(), ext_callback(), ext_thread(), main(), process(), and process_answer_detail().

const char* ub_strerror ( int  err  ) 

Convert error value to a human readable string.

Parameters:
err,: error code from one of the ub_val* functions.
Returns:
pointer to constant text string, zero terminated.

References UB_AFTERFINAL, UB_FORKFAIL, UB_INITFAIL, UB_NOERROR, UB_NOMEM, UB_PIPE, UB_READFILE, UB_SERVFAIL, UB_SOCKET, and UB_SYNTAX.

Referenced by check_ub_res(), checkerr(), dnslook(), main(), print_result(), and process().

int ub_ctx_set_fwd ( struct ub_ctx ctx,
char *  addr 
)

Set machine to forward DNS queries to, the caching resolver to use.

IP4 or IP6 address. Forwards all DNS requests to that machine, which is expected to run a recursive resolver. If the proxy is not DNSSEC-capable, validation may fail. Can be called several times, in that case the addresses are used as backup servers.

To read the list of nameservers from /etc/resolv.conf (from DHCP or so), use the call ub_ctx_resolvconf.

Parameters:
ctx,: context. At this time it is only possible to set configuration before the first resolve is done.
addr,: address, IP4 or IP6 in string format. If the addr is NULL, forwarding is disabled.
Returns:
0 if OK, else error.

References config_stub::addrs, module_env::cfg, cfg_strlist_insert(), ub_ctx::cfglock, config_delstubs(), ub_ctx::env, extstrtoaddr(), ub_ctx::finalized, config_file::forwards, log_assert, config_stub::name, config_stub::next, UB_AFTERFINAL, UB_NOERROR, UB_NOMEM, and UB_SYNTAX.

Referenced by main(), and ub_ctx_resolvconf().

int ub_ctx_resolvconf ( struct ub_ctx ctx,
char *  fname 
)

Read list of nameservers to use from the filename given.

Usually "/etc/resolv.conf". Uses those nameservers as caching proxies. If they do not support DNSSEC, validation may fail.

Only nameservers are picked up, the searchdomain, ndots and other settings from resolv.conf(5) are ignored.

Parameters:
ctx,: context. At this time it is only possible to set configuration before the first resolve is done.
fname,: file name string. If NULL "/etc/resolv.conf" is used.
Returns:
0 if OK, else error.

References ub_ctx_set_fwd(), UB_NOERROR, and UB_READFILE.

Referenced by main().

int ub_ctx_hosts ( struct ub_ctx ctx,
char *  fname 
)

Read list of hosts from the filename given.

Usually "/etc/hosts". These addresses are not flagged as DNSSEC secure when queried for.

Parameters:
ctx,: context. At this time it is only possible to set configuration before the first resolve is done.
fname,: file name string. If NULL "/etc/hosts" is used.
Returns:
0 if OK, else error.

References module_env::cfg, cfg_strlist_insert(), ub_ctx::cfglock, ub_ctx::env, ub_ctx::finalized, config_file::local_data, config_stub::name, str_is_ip6(), UB_AFTERFINAL, UB_NOERROR, UB_NOMEM, UB_READFILE, and UB_SYNTAX.

Referenced by main().


Generated on Sun Sep 21 16:23:29 2008 for unbound by  doxygen 1.5.6