NAME¶
rbl_init(), rbl_close(), rbl_geterror(), rbl_setdomain(),
rbl_query_start(), rbl_query_check(), rbl_query_cancel(),
rbl_settimeout(), rbl_setcallbackint(), rbl_setcallbackctx(),
rbl_setdnscallback(), rbl_dns_set_query_service(),
rbl_dns_set_query_start(), rbl_dns_set_query_cancel(),
rbl_dns_set_query_waitreply(), rbl_dns_set_init(), rbl_dns_set_close(),
rbl_dns_set_nslist(), rbl_dns_set_config(), rbl_dns_set_trustanchor(),
rbl_dns_init() - Realtime Blacklist (RBL) service facility
SYNOPSIS¶
#include
<rbl.h>
RBL *
rbl_init (void *(*
mallocf )(void *, size_t), void (*
freef )(void *, void *p), void *
closure );
unsigned char *
rbl_geterror (RBL *
rbl );
void
rbl_setdomain (RBL *
rbl, unsigned char *
qroot );
RBL_STAT
rbl_query_start (RBL *
rbl, unsigned char *
query,
void **
qh );
RBL_STAT
rbl_settimeout (RBL *
rbl, unsigned int
timeout );
RBL_STAT
rbl_setcallbackint (RBL *
rbl, unsigned int
cbint
);
RBL_STAT
rbl_setcallbackctx (RBL *,
rbl, void *
ctx );
RBL_STAT
rbl_setdnscallback (RBL *,
rbl, void (*
func
)(const void *));
void *
rbl_dns_set_query_service (RBL *
rbl, void *
svc );
void
rbl_dns_set_query_cancel (RBL *
rbl, int (*
func
)(void *, void *));
void
rbl_dns_set_query_start (RBL *
rbl, int (*
func )(void
*, int, unsigned char *, unsigned char *, size_t, void **));
void
rbl_dns_set_query_waitreply (RBL *
rbl, int (*
func
)(void *, void *, struct timeval *, size_t *, int *, int *));
void
rbl_dns_set_init (RBL *
rbl, int (*
func )(void **);
void
rbl_dns_set_close (RBL *
rbl, int (*
func )(void *);
void
rbl_dns_set_config (RBL *
rbl, int (*
func )(void *,
const char *);
void
rbl_dns_set_nslist (RBL *
rbl, int (*
func )(void *,
const char *);
void
rbl_dns_set_trustanchor (RBL *
rbl, int (*
func )(void
*, const char *);
RBL_STAT
rbl_dns_init (RBL *
rbl );
void
rbl_close (RBL *
rbl );
DESCRIPTION¶
These functions are an interface to a facility to conduct Realtime Blacklist
(RBL) queries and return their results. RBLs are described in RFC5782.
An application first initializes the package by calling
rbl_init(). The
optional
mallocf parameter is a caller-provided memory allocation
function taking a pointer to a caller-provided opaque data structure (the
closure parameter) and a number of bytes to allocate. If
mallocf
is not provided, the default system memory allocator function
malloc(3)
is used. The optional
freef parameter specifies a matching
caller-provided memory deallocator function, taking a pointer to a
caller-provided opaque data structure (the
closure parameter) and a
pointer to the memory to be released. If
freef is not provided, the
default system memory release function
free(3) is used. A handle for
future use of the initialized library instance is returned, or NULL on error
and
errno will be set to indicate the cause of the failure.
The
rbl_geterror() function can be used to poll the library for an error
string that provides further description for the most recent failed operation.
A call to
rbl_setdomain() sets the RBL's base domain. This specifies the
"root" of all future queries for the provided
rbl handle to
qroot. Future queries passed to this handle will be prepended to the
string provided here.
A query is initialized with a call to
rbl_query_start() which takes an
RBL library handle as
rbl, the string to be queried as
query,
and a pointer to a void pointer that will be updated to contain a reference to
the initiated query as
qh.
A query previously started by
rbl_query_start() can be canceled by
calling
rbl_query_cancel(), passing it an RBL library handle as
rbl and a query handle as
qh as previously returned when the
query was started.
A query previously started by
rbl_query_start() can be polled for its
status or a result using
rbl_query_check(), passing it an RBL library
handle as
rbl, a query handle as
qh, a pointer to a "struct
timeval" ast
timeout (which can be NULL if an infinite wait is
acceptable), and a pointer to a 32-bit integer as
res into which any
result will be returned (or it can be NULL if the caller doesn't actually want
the result). Results are in network byte order. If this function returns
RBL_STAT_FOUND or RBL_STAT_NOTFOUND, the query is automatically canceled and
need not be passed to
rbl_query_cancel().
The
rbl_settimeout() function can be used to change the query timeout.
The default is ten seconds.
If it is useful to have the library periodically call a user-provided function
as an indication that queries are still in progress, such a function can be
registered with the
rbl_setdnscallback() function. The function
provided should take a void context pointer as its sole argument.
rbl_setcallbackctx() is used to tell the library what context pointer
should be used, and
rbl_setcallbackint() is used to tell the library
what frequency, in seconds, should be used to call that callback function.
Each of these takes the corresponding RBL library handle as its first
argument, and the obvious parameter for its second.
By default, the library will use the stock system resolver to conduct DNS
queries. If alternates should be used, these can be specified using the
following functions:
rbl_dns_set_query_service() sets a context pointer to the query service
to be used, if any. This will be passed as-is to the other DNS functions. It
returns its previous value.
rbl_dns_set_query_cancel() sets a pointer to the function that should be
called to cancel an open query, and should take the following parameters: a
void pointer to the DNS query service to be used, and a void pointer to a
query handle as previously returned by a call to
rbl_dns_set_query_start(). The function should return one of the DNS
result codes described below.
rbl_dns_set_query_start() sets a pointer to the function that should be
called to initiate a new query, and should take the following parameters: a
void pointer to the DNS query service to be used, a DNS record type (e.g.
T_TXT), a pointer to a string containing the query to be started, a pointer to
a buffer into which the reply should be written, the number of bytes available
in that buffer, and a pointer to a void pointer that will be updated to
contain a unique handle for that query once started. The function should
return one of the DNS result codes described below.
rbl_dns_set_query_waitreply() sets a pointer to the function that should
be called to wait for a reply to an open query, and should take the following
parameters: a void pointer to the DNS query service to be used, a void pointer
referencing the query of interest as previously returned by a call to
rbl_dns_set_query_start(), a pointer to a "struct timeval"
structure indicating how long the function should wait for a reply (or NULL if
infinite waiting is acceptable), a pointer to a "size_t" that will
be updated to contain the size of the received reply, a pointer to an integer
that will contain an error code if the query fails (can be NULL if that
information is not interesting to the caller), and a pointer to an integer
that will contain a DNSSEC status indication (can be NULL if that information
is not interesting to the caller). The function should return one of the DNS
result codes described below.
rbl_dns_set_init() sets a pointer to the function that should be called
when it is necessary to initialize a resolver. The function should store a
handle to the initialized resolver and return zero, or return non-zero if
initialization could not be completed. The function specified here is called
before the first call to the query start function (see above).
rbl_dns_set_close() sets a pointer to the function that should be called
when it is necessary to terminate a resolver. The function will receive a
handle referencing the resolver to be terminated, and should return zero on
success or non-zero on failure.
rbl_dns_set_nslist() sets a pointer to the function that should be called
when it is necessary to change the set of nameservers that are to be used to
resolve RBL queries. The function will receive a handle referencing the active
resolver and a string containing a comma-separated list of nameservers to use.
It should return zero on success and non-zero on failure.
rbl_dns_set_config() sets a pointer to the function that should be called
when it is necessary to provide arbitrary configuration information to the
resolver. The function will receive a handle referencing the active resolver
and a string containing the configuration. It should return zero on success
and non-zero on failure.
rbl_dns_set_trustanchor() sets a pointer to the function that should be
called when it is necessary to provide trust anchor information (supporting
DNSSEC) to the resolver. The function will receive a handle referencing the
active resolver and a string containing the trust anchor data. It should
return zero on success and non-zero on failure.
Calling
rbl_dns_init() forces (re-)initialization of the resolver. This
essentially causes the library to call any initialization function defined by
rbl_dns_set_init().
When the library handle is no longer needed, it should be passed to
rbl_close().
RETURN VALUES¶
The following return codes, of type RBL_STAT, can be returned:
- RBL_STAT_OK
- successful completion
- RBL_STAT_INVALID
- operation failed because an invalid parameter was provided
- RBL_STAT_DNSERROR
- operation could not be completed because of errors requesting or receiving
a DNS reply; note that this does not include a successful reply that
contains a "no record found" result, which is a successful
answer
- RBL_STAT_NORESOURCE
- a caller-provided buffer was too small to complete the requested
operation, or a memory or file descriptor allocation failed
- RBL_STAT_NOTIMPLEMENT
- an optional library feature was not selected at compilation time
- RBL_STAT_FOUND
- the requested record was found in the RBL
- RBL_STAT_NOTFOUND
- the requested record was not found in the RBL (but the query did
complete)
- RBL_STAT_NOREPLY
- a call to rbl_query_check() timed out before a result could be
returned
- RBL_STAT_EXPIRED
- the underlying resolver reported that the query expired; this is included
to support resolvers that have an overall query timeout as well as a
single wait timeout
DNS RETURN CODES¶
Any registered DNS functions should return one of the following result codes:
- RBL_DNS_ERROR
- An error occurred. The cause of the error can be retrieved using
rbl_geterror().
- RBL_DNS_SUCCESS
- The operation was successful.
- RBL_DNS_REPLY
- A reply is available (returned by the "waitreply"
function).
- RBL_DNS_NOREPLY
- No reply was received by the time the query timeout was reached (returned
by the "waitreply" function).
- RBL_DNS_EXPIRED
- The query expired completely (returned by the "waitreply"
function). Some resolvers set an overall timeout for the query at start
time in addition to one for each single wait request; this code indicates
the former timeout expired.
COPYRIGHT¶
Copyright (c) 2010-2013, The Trusted Domain Project. All rights reserved.
SEE ALSO¶
intro(2)