forked from Mirrors/freeswitch
60434decf5
mod_enum can be used as a dialplan app, an api call from the console or as a dialplan interface.
Dialplan Interface:
put enum as the dialplan parameter in an endpoint module
i.e. instead of "XML" set it to "enum" or "enum,XML" for fall through.
Dialplan App:
This example will do a lookup and set the a variable that is the proper
dialstring to call all of the possible routes in order of preference according to
the lookup and the order of the routes in the enum.conf section.
<extension name="tollfree">
<condition field="destination_number" expression="^(18(0{2}|8{2}|7{2}|6{2})\d{7})$">
<action application="enum" data="$1"/>
<action application="bridge" data="${enum_auto_route}"/>
</condition>
</extension>
You can also pick an alrernate root:
<action application="enum" data="$1 myroot.org"/>
API command:
at the console you can say:
enum <number> [<root>]
The root always defaults to the one in the enum.conf section.
git-svn-id: http://svn.freeswitch.org/svn/freeswitch/trunk@3494 d0543943-73ff-0310-b7d9-9358b9ac24b2
1285 lines
53 KiB
Groff
1285 lines
53 KiB
Groff
.\" $Id: udns.3,v 1.26 2006/11/28 22:58:04 mjt Exp $
|
|
.\" udns library manpage
|
|
.\"
|
|
.\" Copyright (C) 2005 Michael Tokarev <mjt@corpit.ru>
|
|
.\" This file is part of UDNS library, an async DNS stub resolver.
|
|
.\"
|
|
.\" This library is free software; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU Lesser General Public
|
|
.\" License as published by the Free Software Foundation; either
|
|
.\" version 2.1 of the License, or (at your option) any later version.
|
|
.\"
|
|
.\" This library is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
.\" Lesser General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU Lesser General Public
|
|
.\" License along with this library, in file named COPYING.LGPL; if not,
|
|
.\" write to the Free Software Foundation, Inc., 59 Temple Place,
|
|
.\" Suite 330, Boston, MA 02111-1307 USA
|
|
|
|
.TH udns 3 "Apr 2005" "Library Functions"
|
|
|
|
.SH NAME
|
|
udns \- stub DNS resolver library
|
|
|
|
.SH SYNOPSYS
|
|
.nf
|
|
#include <udns.h>
|
|
struct \fBdns_ctx\fR;
|
|
struct \fBdns_query\fR;
|
|
extern struct dns_ctx \fBdns_defctx\fR;
|
|
struct dns_ctx *\fIctx\fR;
|
|
typedef void \fBdns_query_fn\fR(\fIctx\fR, void *\fIresult\fR, void *\fIdata\fR);
|
|
typedef int
|
|
\fBdns_parse_fn\fR(const unsigned char *\fIqnd\fR,
|
|
const unsigned char *\fIpkt\fR,
|
|
const unsigned char *\fIcur\fR,
|
|
const unsigned char *\fIend\fR,
|
|
void **\fIresultp\fR);
|
|
|
|
\fBcc\fR ... -l\fBudns\fR
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.PP
|
|
The DNS library, \fBudns\fR, implements thread-safe stub DNS resolver
|
|
functionality, which may be used both traditional, syncronous way
|
|
and asyncronously, with application-supplied event loop.
|
|
|
|
.PP
|
|
While DNS works with both TCP and UDP, performing UDP query first and
|
|
if the result does not fit in UDP buffer (512 bytes max for original
|
|
DNS protocol), retrying the query over TCP, the library uses UDP only,
|
|
but uses EDNS0 (RFC2671) extensions which allows larger UDP buffers.
|
|
|
|
.PP
|
|
The library uses single UDP socket to perform all operations even when
|
|
asking multiple nameservers. This way, it is very simple to use the
|
|
library in asyncronous event-loop applications: an application should
|
|
add only single socket to the set of filedescriptors it monitors for I/O.
|
|
|
|
.PP
|
|
The library uses two main objects, \fIresolver context\fR of type
|
|
\fBstruct\ dns_ctx\fR, and \fIquery structure\fR of type
|
|
\fBstruct\ dns_query\fR, both are opaque for an application.
|
|
Resolver context holds global information about the resolver,
|
|
such as list of nameservers to use, list of active requests and the like.
|
|
Query objects holds information about a single DNS query in progress and
|
|
are allocated/processed/freed by the library. Pointer to query structure
|
|
may be treated as an identifier of an in-progress query and may be used
|
|
to cancel the asyncronous query or to wait for it to complete.
|
|
|
|
.PP
|
|
Asyncronous interface works as follows. An application initializes
|
|
resolver context, submits any number of queries for it using one of
|
|
supplied \fBdns_submit_\fIXXX\fR() routines (each return the query
|
|
identifier as pointer to query structure), waits for input on the
|
|
UDP socket used by the library, and gives some control to the library
|
|
by calling \fBdns_ioevent\fR() and \fBdns_timeouts\fR() routines when
|
|
appropriate. The library performs all necessary processing and executes
|
|
application supplied callback routine when a query completes (either
|
|
successefully or not), giving it the result if any, pointer to the
|
|
resolver context (from which completion status may be obtained), and
|
|
the data pointer supplied by an application when the query has been
|
|
submitted. When submitting a query, an application requests how to
|
|
handle the reply -- to either return raw DNS reply packet for its
|
|
own low-level processing, or it may provide an address of \fIparsing
|
|
routine\fR of type \fBdns_parse_fn\fR to perform conversion of on-wire
|
|
format into easy to use data structure (the library provides parsing
|
|
routines for several commonly used resource record types, as well as
|
|
type-safe higher-level inteface that requests parsing automatically).
|
|
The I/O monitoring and timeout handling may be either traditional
|
|
select() or poll() based, or any callback-driven technique may be
|
|
used.
|
|
|
|
.PP
|
|
Additionally, the library provides traditional syncronous interface,
|
|
which may be intermixed with asyncronous calls (during syncronous
|
|
query processing, other asyncronous queries for the same resolver
|
|
context continued to be processed as usual). An application uses
|
|
one of numerous \fBdns_resolve_\fIXXX\fR() routines provided by the
|
|
library to perform a query. As with asyncronous interface, an
|
|
application may either request to return raw DNS packet or type-specific
|
|
data structure by providing the parsing routine to handle the reply.
|
|
Every routine from \fBdns_resolve_\fIXXX\fR() series return pointer
|
|
to result or NULL in case of any error. Query completion status
|
|
(or length of the raw DNS packet) is available from the resolver
|
|
context using \fBdns_status\fR() routine, the same way as for the
|
|
asyncronous interface.
|
|
|
|
.PP
|
|
Internally, library uses on-wire format of domain names, referred
|
|
to as \fIDN format\fR in this manual page. This is a series of domain
|
|
\fIlabels\fR whith preceeding length byte, terminated by zero-length
|
|
label wich is integral part of the DN format. There are several routines
|
|
provided to convert from traditional asciiz string to DN and back.
|
|
Higher-level type-specific query interface hides the DN format from
|
|
an application.
|
|
|
|
.SH "COMMON DEFINITIONS"
|
|
|
|
.PP
|
|
Every DNS Resource Record (RR) has a \fItype\fR and a \fIclass\fR.
|
|
The library defines several integer constants, \fBDNS_C_\fIXXX\fR and
|
|
\fBDNS_T_\fIXXX\fR, to use as symbolic names for RR classes and types,
|
|
such as \fBDNS_C_IN\fR for Internet class, \fBDNS_T_A\fR for IPv4
|
|
address record type and so on. See udns.h header file for complete list
|
|
of all such constants.
|
|
|
|
.PP
|
|
The following constants are defined in dns.h header file:
|
|
.IP "\fBDNS_MAXDN\fR (255 bytes)"
|
|
Maximum length of the domain name in internal (on-wire) DN format.
|
|
.IP "\fBDNS_MAXLABEL\fR (63 bytes)"
|
|
Maximum length of a single label in DN format.
|
|
.IP "\fBDNS_MAXNAME\fR (1024 bytes)"
|
|
Maximum length of asciiz format of a domain name.
|
|
.IP "\fBDNS_HSIZE\fR (12 bytes)"
|
|
Size of header in DNS packet.
|
|
.IP "\fBDNS_PORT\fR (53)"
|
|
Default port to use when contacting a DNS server.
|
|
.IP "\fBDNS_MAXSERV\fR (6 servers)"
|
|
Maximum number of DNS servers to use.
|
|
.IP "\fBDNS_MAXSRCH\fR (5 search list entries)"
|
|
Maximum number of domain search list
|
|
.IP "\fBDNS_MAXPACKET\fR (512 bytes)"
|
|
Maximum length of DNS UDP packet as specified by original DNS protocol
|
|
.IP "\fBDNS_EDNS0PACKET\fR (4096 bytes)"
|
|
Default length of DNS UDP packet (with EDNS0 extensions) the library uses.
|
|
Note that recursive nameservers usually resides near the client asking them
|
|
to resolve names, e.g. on the same LAN segment or even on the same host, so
|
|
UDP packet fragmentation isn't a problem in most cases. Note also that
|
|
the size of actual packets will be as many bytes as actual reply size requires,
|
|
which is smaller than this value in almost all cases.
|
|
|
|
.PP
|
|
Additionally, several constants are defined to simplify work with raw DNS
|
|
packets, such as DNS response codes (\fBDNS_R_\fIXXX\fR), DNS header layout
|
|
(\fBDNS_H_\fIXXX\fR) and others. Again, see udns.h for complete list.
|
|
Library error codes (\fBDNS_E_\fIXXX\fR) are described later in this
|
|
manual page.
|
|
|
|
.SH "RESOLVER CONTEXT"
|
|
|
|
.PP
|
|
Resolver context, of type \fBstruct\ dns_ctx\fR, is an object which is
|
|
opaque to an application. Several routines provided by the library
|
|
to initialize, copy and free resolver contexts. Most other high-level
|
|
routines in this library expects a pointer to resolver context, \fIctx\fR,
|
|
as the first argument. There is a default resolver context available,
|
|
named \fBdns_defctx\fR. When the context pointer \fIctx\fR passed to
|
|
a routine is NULL, \fBdns_defctx\fR is used. Several resolver contexts
|
|
may be active at the same time, for example, when an application is
|
|
multi-threaded and each thread uses resolver.
|
|
.PP
|
|
When initializing resolver context, the library uses information from
|
|
system file /etc/resolv.conf (see \fBresolv.conf\fR(5)), consults
|
|
environment variables \fB$LOCALDOMAIN\fR, \fB$DNSCACHEIP\fR,
|
|
\fB$NAMESERVERS\fR and \fB$RES_OPTIONS\fR, and local host name to obtain
|
|
list of local nameservers, domain name search list and various resolver
|
|
options.
|
|
.PP
|
|
The following routines to initialize resolver context are available:
|
|
.PP
|
|
.nf
|
|
int \fBdns_init\fR(int \fIdo_open\fR)
|
|
struct dns_ctx *\fBdns_new\fR(struct dns_ctx *\fIcopy\fR)
|
|
void \fBdns_free\fR(\fIctx\fR)
|
|
.fi
|
|
.RS
|
|
\fBdns_init\fR() initializes default resolver context, \fBdns_defctx\fR,
|
|
and optionally opens it (if \fIdo_open\fR is true) using \fBdns_open\fR(),
|
|
returning negative value on error.
|
|
\fBdns_new\fR() makes a copy of a given resolver context \fIcopy\fR, or
|
|
default context if \fIcopy\fR is NULL, and returns pointer to it.
|
|
\fBdns_new\fR() may fail if there's no memory available to make a copy
|
|
of \fIcopy\fR, in which case the routine will return NULL pointer.
|
|
\fBdns_free\fR() is used to close assotiated socket and free resolver
|
|
context resources and cancelling (abandoming) all active queries
|
|
assotiated with it. It's ok to free \fBdns_defctx\fR as well as
|
|
dynamically allocated contexts returned by \fBdns_new\fR().
|
|
.RE
|
|
.PP
|
|
.nf
|
|
int \fBdns_add_serv\fR(\fIctx\fR, const char *\fIserv\fR)
|
|
int \fBdns_add_serv_s\fR(\fIctx\fR, const struct sockaddr *\fIsa\fR)
|
|
int \fBdns_add_srch\fR(\fIctx\fR, const char *\fIsrch\fR)
|
|
.fi
|
|
.RS
|
|
Add an element to list of nameservers (\fBdns_add_serv\fR(), as
|
|
asciiz-string \fIserv\fR with an IP address of the nameserver,
|
|
and \fBdns_add_serv_s\fR(), as initialized socket address \fIsa\fR),
|
|
or search list (\fBdns_add_srch\fR(), as a pointer to domain name)
|
|
for the given context \fIctx\fR. If the last argument is a NULL
|
|
pointer, the corresponding list (search or nameserver) is reset
|
|
instead. Upon successeful completion, each routine returns new
|
|
number of elements in the list in question. On error, negative
|
|
value is returned and global variable \fBerrno\fR is set appropriately.
|
|
It is an error to call any of this functions if the context is
|
|
opened (after \fBdns_open\fR() or \fBdns_init\fR() with non-zero argument).
|
|
.RE
|
|
.PP
|
|
.nf
|
|
int \fBdns_set_opts\fR(\fIctx\fR, const char *\fIopts\fR)
|
|
.fi
|
|
.RS
|
|
set resolver context options from \fIopts\fR string, in the same way as
|
|
processing \fBoptions\fR statement in resolv.conf and \fB$RES_OPTIONS\fR
|
|
environment variable.
|
|
.RE
|
|
.PP
|
|
.nf
|
|
void \fBdns_set_opt\fR(\fIctx\fR, int \fIopt\fR, \fIval\fR)
|
|
.fi
|
|
.RS
|
|
.B TODO
|
|
The \fIflags\fR argument is a bitmask with the following bits defined:
|
|
.IP \fBDNS_NOSRCH\fR
|
|
do not perform domain name search in search list.
|
|
.IP \fBDNS_NORD\fR
|
|
do not request recursion when performing queries
|
|
(i.e. don't set RD flag in querues).
|
|
.IP \fBDNS_AAONLY\fR
|
|
request authoritative answers only (i.e. set AA
|
|
flag in queries).
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
int \fBdns_open\fR(\fIctx\fR)
|
|
int \fBdns_sock\fR(const \fIctx\fR)
|
|
void \fBdns_close\fR(\fIctx\fR)
|
|
.fi
|
|
.RS
|
|
\fBdns_open\fR() opens the UDP socket used for queries if not already
|
|
open, and return assotiated filedescriptor (or negative value in case
|
|
of error).
|
|
\fBdns_sock\fR() return the UDP socket if open, or -1 if not.
|
|
\fBdns_close\fR() closes the UDP socket if it was open.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
int \fBdns_active\fR(const \fIctx\fR)
|
|
.fi
|
|
.RS
|
|
return number of active queries queued for the given context
|
|
\fIctx\fR, or zero if none.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
int \fBdns_status\fR(const \fIctx\fR)
|
|
.fi
|
|
.RS
|
|
return status code from last operation. When using syncronous
|
|
interface, this is the query completion status of the last query.
|
|
With asyncronous interface, from within the callback routine,
|
|
this is the query completion status of the query for which the
|
|
callback is being called. When query submission fails, this
|
|
is the error code indicating failure reason. All error codes
|
|
are negative and are represented by \fBDNS_E_\fIXXX\fR constants
|
|
described below.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
void \fBdns_ioevent\fR(\fIctx\fR, time_t \fInow\fR)
|
|
.fi
|
|
.RS
|
|
this routine may be called by an application to process I/O
|
|
events on the UDP socket used by the library, as returned
|
|
by \fBdns_sock\fR(). The routine tries to receive incoming
|
|
UDP datagram from the socket and process it. The socket is
|
|
set up to be non-blocking, so it is safe to call the routine
|
|
even if there's no data to read. The routine will process
|
|
as many datagrams as are queued for the socket, so it is
|
|
safe to use it with either level-triggered or edge-triggered
|
|
I/O monitoring model. The \fInow\fR argument is either a
|
|
current time as returned by \fBtime\fR(), or 0, in which
|
|
case the routine will obtain current time by it's own.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
int \fBdns_timeouts\fR(\fIctx\fR, int \fImaxwait\fR, time_t \fInow\fR)
|
|
.fi
|
|
.RS
|
|
process any pending timeouts and return number of secounds
|
|
from current time (\fInow\fR if it is not 0) to the time when
|
|
the library wants the application to pass it control to process
|
|
more queued requests. In case when there are no requests pending,
|
|
this time is -1. The routine will not request a time larger than
|
|
\fImaxwait\fR secounds if it is greather or equal to zero. If
|
|
\fInow\fR is 0, the routine will obtain current time by it's own;
|
|
when it is not 0, it should contain current time as returned by
|
|
\fBtime\fR().
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
typedef void \fBdns_utm_fn\fR(\fIctx\fR, int \fItimeout\fR, void *\fIdata\fR)
|
|
void \fBdns_set_cbck\fR(\fIctx\fR, dns_utm_fn *\fIutmfn\fR, void *\fIdata\fR)
|
|
.fi
|
|
.RS
|
|
An application may use custom callback-based I/O multiplexing mechanism.
|
|
Usually such a mechanism have concept of a \fItimer\fR, and an ability
|
|
to register a timer event in a form of a callback routine which will
|
|
be executed after certain amount of time. In order to use such an
|
|
event mechanism, udns provides an ability to register and de-register
|
|
timer events necessary for internal processing using whatever event
|
|
mechanism an application uses. For this to work, it is possible to
|
|
assotiate a pointer to a routine that will perform necessary work for
|
|
(de)registering timer events with a given resolver context, and
|
|
udns will call that routine at appropriate times. Prototype of
|
|
such a routine is shown by \fBdns_utm_fn\fR typedef above. Libudns
|
|
assotiates single timer with resolver context. User-supplied \fIutmfn\fR
|
|
routine will be called by the library with the following arguments:
|
|
.IP "\fIctx\fR == NULL"
|
|
delete user timer, at context free time or when an application changes
|
|
user timer request routine using \fBdns_set_cbck\fR();
|
|
.IP "\fIctx\fR != NULL, \fItimeout\fR < 0"
|
|
don't fire timer anymore, when there are no active requests;
|
|
.IP "\fIctx\fR != NULL, \fItimeout\fR == 0"
|
|
fire timer at the next possibility, but not immediately;
|
|
.IP "\fIctx\fR != NULL, \fItimeout\fR > 0"
|
|
fire timer after \fItimeout\fR seconds after now.
|
|
.PP
|
|
The \fIdata\fR argument passed to the routine will be the same
|
|
as passed to \fBdns_set_cbck\fR().
|
|
.PP
|
|
When a timer expires, an application should call \fBdns_tmeouts\fR()
|
|
routine (see below). Non-callback timer usage is provided too.
|
|
.RE
|
|
|
|
.PP
|
|
.B XXXX TODO: some more resolver context routines, like dns_set_dbgfn() etc.
|
|
|
|
.SH "QUERY INTERFACE"
|
|
|
|
.PP
|
|
There are two ways to perform DNS queries: traditional syncronous
|
|
way, when udns performs all the necessary processing and return
|
|
control to the application only when the query completes, and
|
|
asyncronous way, when an application submits one or more queries
|
|
to the library using given resolver context, and waits for completion
|
|
by monitoring filedescriptor used by library and calling library
|
|
routines to process input on that filedescriptor. Asyncronous mode
|
|
works with callback routines: an application supplies an address of
|
|
a routine to execute when the query completes, and a data pointer,
|
|
which is passed to the callback routine.
|
|
|
|
.PP
|
|
Queries are submitted to the library in a form of \fBstruct\ dns_query\fR.
|
|
To perform asyncronous query, an application allocates memory for the
|
|
\fIquery structure\fR and passes it to the library using \fBdns_submit\fR()
|
|
routines, together with all the query parameters. When the query completes,
|
|
library will call application-supplied callback routine, giving it the
|
|
resolver context (wich holds query completion status), dynamically allocated
|
|
result (which will be either raw DNS packet or, if applicatin requested parsing
|
|
the result by specifying non-NULL parse routine, ready-to-use type-specific
|
|
structure), and a data pointer provided by an application when it submitted the
|
|
query. It is the application who's responsible for freeing the result memory.
|
|
.PP
|
|
Generic query callback routine looks like this:
|
|
.nf
|
|
typedef void
|
|
\fBdns_query_fn\fR(\fIctx\fR, void *\fIresult\fR, void *\fIdata\fR)
|
|
.fi
|
|
Type-specific query interface expects similar form of callback
|
|
routine with the only difference in type of \fBresult\fR argument,
|
|
which will be pointer to specific data structure (decoded reply)
|
|
instead of this void pointer to raw DNS packet data.
|
|
|
|
.PP
|
|
Result parsing routine looks like this:
|
|
.nf
|
|
typedef int
|
|
\fBdns_parse_fn\fR(const unsigned char *\fIqdn\fR,
|
|
const unsigned char *\fIpkt\fR,
|
|
const unsigned char *\fIcur\fR,
|
|
const unsigned char *\fIend\fR,
|
|
void **\fIresultp\fR);
|
|
.fi
|
|
When called by the library, the arguments are as follows:
|
|
\fIpkt\fR points to the start of the packet received;
|
|
\fIend\fR points past the end of the packet received;
|
|
\fIcur\fR points past the query DN in the query section of the
|
|
packet;
|
|
\fIqdn\fR points to the original query DN.
|
|
The routine should allocate a single buffer to hold the result,
|
|
parse the reply filling in the buffer, and return the buffer
|
|
using \fIresultp\fR argument. It returns 0 in case of error,
|
|
or udns error code (\fBDNS_E_\fIXXX\fR constants) in case of
|
|
error.
|
|
Note that by the time when the parse routine is called by the
|
|
library, packet is already verified to be a reply to the
|
|
original query, by matching query DN, query class and query type.
|
|
|
|
.PP
|
|
Type-specific query inteface supplies necessary parsing routines
|
|
automatically.
|
|
|
|
.PP
|
|
In case of error, query completion status as returned by
|
|
\fBdns_status\fR(\fIctx\fR), will contain one of the following values:
|
|
.IP "positive value"
|
|
length of raw DNS packet if parsing is not requested.
|
|
.IP 0
|
|
the query was successeful and the \fIreply\fR points to type-specific
|
|
data structure.
|
|
.IP \fBDNS_E_TEMPFAIL\fR
|
|
temporary error, the resolver nameserver was not able to
|
|
process our query or timed out.
|
|
.IP \fBDNS_E_PROTOCOL\fR
|
|
protocol error, a nameserver returned malformed reply.
|
|
.IP \fBDNS_E_NXDOMAIN\fR
|
|
the domain name does not exist.
|
|
.IP \fBDNS_E_NODATA\fR
|
|
there is no data of requested type found.
|
|
.IP \fBDNS_E_NOMEM\fR
|
|
out of memory while processing request.
|
|
.IP \fBDNS_E_BADQUERY\fR
|
|
some aspect of the query (most common is the domain name in question)
|
|
is invalid, and the library can't even start a query.
|
|
|
|
.PP
|
|
Library provides two series of routines which uses similar interface --
|
|
one for asyncronous queries and another for syncronous queries. There
|
|
are two general low-level routines in each series to submit (asyncronous
|
|
interface) and resolve (syncronous interface) queries, as well as several
|
|
type-specific routines with more easy-to-use interfaces. To submit
|
|
an asyncronous query, use one of \fBdns_submit_\fIXXX\fR() routine, each
|
|
of which accepts query parameters, pointers to callback routine and to
|
|
callback data, and optional current time hint. Note type-specific
|
|
\fBdns_submit_\fIXXX\fR() routines expects specific type of the callback
|
|
routine as well, which accepts reply as a pointer to corresponding
|
|
structure, not a void pointer). Every \fBdns_submit_\fIXXX\fR() routine
|
|
return pointer to internal query structure of type struct\ dns_query,
|
|
used as an identifier for the given query.
|
|
|
|
.PP
|
|
To resolve a query syncronously, use one of \fBdns_resolve_\fIXXX\fR()
|
|
routines, which accepts the same query parameters (but not the
|
|
callback pointers) as corresponding \fBdns_submit_\fIXXX\fR(), and
|
|
return the query result, which is the same as passed to the callback
|
|
routine in case of asyncronous interface.
|
|
|
|
.PP
|
|
In either case, the result memory (if the query completed successefully)
|
|
is dynamically allocated and should be freed by an application. If
|
|
the query failed for any reason, the result will be NULL, and error
|
|
status will be available from \fBdns_status\fR(\fIctx\fR) routine
|
|
as shown above.
|
|
|
|
.PP
|
|
.nf
|
|
struct dns_query *
|
|
\fBdns_submit_dn\fR(\fIctx\fR,
|
|
const unsigned char *\fIdn\fR, \fIqcls\fR, \fIqtyp\fR, \fIflags\fR,
|
|
\fIparse\fR, \fIcbck\fR, \fIdata\fR)
|
|
struct dns_query *
|
|
\fBdns_submit_p\fR(\fIctx\fR,
|
|
const char *\fIname\fR, \fIqcls\fR, \fIqtyp\fR, \fIflags\fR,
|
|
\fIparse\fR, \fIcbck\fR, \fIdata\fR)
|
|
enum dns_class \fIqcls\fR;
|
|
enum dns_type \fIqtyp\fR;
|
|
int \fIflags\fR;
|
|
dns_parse_fn *\fIparse\fR;
|
|
dns_query_fn *\fIcbck\fR;
|
|
void *\fIdata\fR;
|
|
.fi
|
|
.RS
|
|
submit a query for processing for the given resolver context \fIctx\fR.
|
|
Two routines differs only in 3rd argument, which is domain name in
|
|
DN format (\fIdn\fR) or asciiz string (\fIname\fR). The query will be
|
|
performed for the given domain name, with type \fIqtyp\fR in class \fIqcls\fR,
|
|
using option bits in \fIflags\fR, using RR parsing routine pointed by
|
|
\fIparse\fR if not-NULL, and upon completion, \fIcbck\fR function will
|
|
be called with the \fIdata\fR argument.
|
|
In case of successeful query submission,
|
|
the routine return pointer to internal query structure which may be treated
|
|
as an identifier of the query as used by the library, and may be used as an
|
|
argument for \fBdns_cancel\fR() routine. In case of error, NULL will be
|
|
returned, and context error status (available using \fIdns_status\fR() routine)
|
|
will be set to corresponding error code, which in this case may be
|
|
DNS_E_BADQUERY if the \fIname\fR of \fIdn\fR is invalid, DNS_E_NOMEM if
|
|
there's no memory available to allocate query structure, or DNS_E_TEMPFAIL
|
|
if an internal error occured.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
void *\fBdns_resolve_dn\fR(\fIctx\fR,
|
|
const unsigned char *\fIdn\fR, \fIqcls\fR, \fIqtyp\fR, \fIflags\fR, \fIparse\fR);
|
|
void *\fBdns_resolve_p\fR(\fIctx\fR,
|
|
const char *\fIname\fR, \fIqcls\fR, \fIqtyp\fR, \fIflags\fR, \fIparse\fR)
|
|
enum dns_class \fIqcls\fR;
|
|
enum dns_type \fIqtyp\fR;
|
|
int \fIflags\fR;
|
|
dns_parse_fn *\fIparse\fR;
|
|
.fi
|
|
.RS
|
|
syncronous interface. The routines perform all the steps necessary to resolve
|
|
the given query and return the result. If there's no positive result for any
|
|
reason, all the routines return NULL, and set context error status (available
|
|
using \fBdns_status\fR() routine) to indicate the error code. If the query
|
|
was successeful, context status code will contain either the length of the
|
|
raw DNS reply packet if \fIparse\fR argument was NULL (in which case the return
|
|
value is pointer to the reply DNS packet), or 0 (in which case the return value
|
|
is the result of \fIparse\fR routine). If the query successeful (return value
|
|
is not NULL), the memory returned was dynamically allocated by the library
|
|
and should be free()d by application after use.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
void *\fBdns_resolve\fR(\fIctx\fR, struct dns_query *\fIq\fR)
|
|
.fi
|
|
.RS
|
|
wait for the given query \fIq\fR, as returned by one of
|
|
\fBdns_submit_\fIXXX\fR() routines, for completion, and
|
|
return the result. The callback routine will not be called
|
|
for this query. After completion, the query identifier \fIq\fI
|
|
is not valid. Both \fBdns_resolve_dn\fR() and \fBdns_resolve_p\fR()
|
|
are just wrappers around corresponding submit routines and this
|
|
\fBdns_resolve\fR() routine.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
void \fBdns_cancel\fR(\fIctx\fR, struct dns_query *\fIq\fR)
|
|
.fi
|
|
.RS
|
|
cancel an active query \fIq\fR, without calling a callback routine.
|
|
After completion, the query identifier \fIq\fR is not valid.
|
|
.RE
|
|
|
|
.SH "TYPE-SPECIFIC QUERIES"
|
|
|
|
.PP
|
|
In addition to the generic low-level query interface, the library provides
|
|
a set of routines to perform specific queries in a type-safe manner, as
|
|
well as parsers for several well-known resource record types. The library
|
|
implements high-level interface for A, AAAA, PTR, MX and TXT records
|
|
and DNSBL and RHSBL functionality. These routines returns specific types
|
|
as result of a query, instead of raw DNS packets. The following types
|
|
and routines are available.
|
|
|
|
.PP
|
|
.nf
|
|
struct \fBdns_rr_null\fR {
|
|
char *\fBdnsn_qname\fR; /* original query name */
|
|
char *\fBdnsn_cname\fR; /* canonical name */
|
|
unsigned \fBdnsn_ttl\fR; /* Time-To-Live (TTL) value */
|
|
int \fBdnsn_nrr\fR; /* number of records in the set */
|
|
};
|
|
.fi
|
|
.PP
|
|
NULL RR set, used as a base for all other RR type structures.
|
|
Every RR structure as used by the library have four standard
|
|
fields as in struct\ \fBdns_rr_null\fR.
|
|
|
|
.SS "IN A Queries"
|
|
.PP
|
|
.nf
|
|
struct \fBdns_rr_a4\fR { /* IN A RRset */
|
|
char *\fBdnsa4_qname\fR; /* original query name */
|
|
char *\fBdnsa4_cname\fR; /* canonical name */
|
|
unsigned \fBdnsa4_ttl\fR; /* Time-To-Live (TTL) value */
|
|
int \fBdnsa4_nrr\fR; /* number of addresses in the set */
|
|
struct in_addr \fBdnsa4_addr\fR[]; /* array of addresses */
|
|
};
|
|
typedef void
|
|
\fBdns_query_a4_fn\fR(\fIctx\fR, struct dns_rr_a4 *\fIresult\fR, \fIdata\fR)
|
|
dns_parse_fn \fBdns_parse_a4\fB;
|
|
struct dns_query *
|
|
\fBdns_submit_a4\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR,
|
|
dns_query_a4_fn *\fIcbck\fR, \fIdata\fR);
|
|
struct dns_rr_a4 *
|
|
\fBdns_resolve_a4\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR);
|
|
.fi
|
|
.PP
|
|
The \fBdns_rr_a4\fR structure holds a result of an \fBIN A\fR query,
|
|
which is an array of IPv4 addresses. Callback routine for IN A queries
|
|
expected to be of type \fBdns_query_a4_fn\fR, which expects pointer to
|
|
\fBdns_rr_a4\fR structure as query result instead of raw DNS packet.
|
|
The \fBdns_parse_a4\fR() is used to convert raw DNS reply packet into
|
|
\fBdns_rr_a4\fR structure (it is used internally and may be used directly too
|
|
with generic query interface). Routines \fBdns_submit_a4\fR() and
|
|
\fBdns_resolve_a4\fR() are used to perform A IN queries in a type-safe
|
|
manner. The \fIname\fR parameter is the domain name in question, and
|
|
\fIflags\fR is query flags bitmask, with one bit, DNS_NOSRCH, of practical
|
|
interest (if the \fIname\fR is absolute, that is, it ends up with a dot,
|
|
DNS_NOSRCH flag will be set automatically).
|
|
|
|
.SS "IN AAAA Queries"
|
|
.PP
|
|
.nf
|
|
struct \fBdns_rr_a6\fR { /* IN AAAA RRset */
|
|
char *\fBdnsa6_qname\fR; /* original query name */
|
|
char *\fBdnsa6_cname\fR; /* canonical name */
|
|
unsigned \fBdnsa6_ttl\fR; /* Time-To-Live (TTL) value */
|
|
int \fBdnsa6_nrr\fR; /* number of addresses in the set */
|
|
struct in6_addr \fBdnsa6_addr\fR[]; /* array of addresses */
|
|
};
|
|
typedef void
|
|
\fBdns_query_a6_fn\fR(\fIctx\fR, struct dns_rr_a6 *\fIresult\fR, \fIdata\fR)
|
|
dns_parse_fn \fBdns_parse_a6\fB;
|
|
struct dns_query *
|
|
\fBdns_submit_a6\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR,
|
|
dns_query_a6_fn *\fIcbck\fR, \fIdata\fR);
|
|
struct dns_rr_a6 *
|
|
\fBdns_resolve_a6\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR);
|
|
.fi
|
|
.PP
|
|
The \fBdns_rr_a6\fR structure holds a result of an \fBIN AAAA\fR query,
|
|
which is an array of IPv6 addresses. Callback routine for IN AAAA queries
|
|
expected to be of type \fBdns_query_a6_fn\fR, which expects pointer to
|
|
\fBdns_rr_a6\fR structure as query result instead of raw DNS packet.
|
|
The \fBdns_parse_a6\fR() is used to convert raw DNS reply packet into
|
|
\fBdns_rr_a6\fR structure (it is used internally and may be used directly too
|
|
with generic query interface). Routines \fBdns_submit_a6\fR() and
|
|
\fBdns_resolve_a6\fR() are used to perform AAAA IN queries in a type-safe
|
|
manner. The \fIname\fR parameter is the domain name in question, and
|
|
\fIflags\fR is query flags bitmask, with one bit, DNS_NOSRCH, of practical
|
|
interest (if the \fIname\fR is absolute, that is, it ends up with a dot,
|
|
DNS_NOSRCH flag will be set automatically).
|
|
|
|
.SS "IN PTR Queries"
|
|
.PP
|
|
.nf
|
|
struct \fBdns_rr_ptr\fR { /* IN PTR RRset */
|
|
char *\fBdnsptr_qname\fR; /* original query name */
|
|
char *\fBdnsptr_cname\fR; /* canonical name */
|
|
unsigned \fBdnsptr_ttl\fR; /* Time-To-Live (TTL) value */
|
|
int \fBdnsptr_nrr\fR; /* number of domain name pointers */
|
|
char *\fBdnsptr_ptr\fR[]; /* array of domain name pointers */
|
|
};
|
|
typedef void
|
|
\fBdns_query_ptr_fn\fR(\fIctx\fR, struct dns_rr_ptr *\fIresult\fR, \fIdata\fR)
|
|
dns_parse_fn \fBdns_parse_ptr\fB;
|
|
struct dns_query *
|
|
\fBdns_submit_a4ptr\fB(\fIctx\fR, const struct in_addr *\fBaddr\fR,
|
|
dns_query_ptr_fn *\fIcbck\fR, \fIdata\fR);
|
|
struct dns_rr_ptr *
|
|
\fBdns_resolve_a4ptr\fB(\fIctx\fR, const struct in_addr *\fBaddr\fR);
|
|
struct dns_query *
|
|
\fBdns_submit_a6ptr\fB(\fIctx\fR, const struct in6_addr *\fBaddr\fR,
|
|
dns_query_ptr_fn *\fIcbck\fR, \fIdata\fR);
|
|
struct dns_rr_ptr *
|
|
\fBdns_resolve_a6ptr\fB(\fIctx\fR, const struct in6_addr *\fBaddr\fR);
|
|
.fi
|
|
.PP
|
|
The \fBdns_rr_ptr\fR structure holds a result of an IN PTR query, which
|
|
is an array of domain name pointers for a given IPv4 or IPv6 address.
|
|
Callback routine for IN PTR queries expected to be of type
|
|
\fBdns_query_ptr_fn\fR, which expects pointer to \fBdns_rr_ptr\fR
|
|
structure as query result instead of raw DNS packet. The \fBdns_parse_ptr\fR()
|
|
is used to convert raw DNS reply packet into \fBdns_rr_ptr\fR structure
|
|
(it is used internally and may be used directly too with generic query
|
|
interface). Routines \fBdns_submit_a4ptr\fR() and \fBdns_resolve_a4ptr\fR()
|
|
are used to perform IN PTR queries for IPv4 addresses in a type-safe
|
|
manner. Routines \fBdns_submit_a6ptr\fR() and \fBdns_resolve_a6ptr\fR()
|
|
are used to perform IN PTR queries for IPv6 addresses.
|
|
|
|
.SS "IN MX Queries"
|
|
.PP
|
|
.nf
|
|
struct \fBdns_mx\fR { /* single MX record */
|
|
int \fBpriority\fR; /* priority value of this MX */
|
|
char *\fBname\fR; /* domain name of this MX */
|
|
};
|
|
struct \fBdns_rr_mx\fR { /* IN MX RRset */
|
|
char *\fBdnsmx_qname\fR; /* original query name */
|
|
char *\fBdnsmx_cname\fR; /* canonical name */
|
|
unsigned \fBdnsmx_ttl\fR; /* Time-To-Live (TTL) value */
|
|
int \fBdnsmx_nrr\fR; /* number of mail exchangers in the set */
|
|
struct dns_mx \fBdnsmx_mx\fR[]; /* array of mail exchangers */
|
|
};
|
|
typedef void
|
|
\fBdns_query_mx_fn\fR(\fIctx\fR, struct dns_rr_mx *\fIresult\fR, \fIdata\fR)
|
|
dns_parse_fn \fBdns_parse_mx\fB;
|
|
struct dns_query *
|
|
\fBdns_submit_mx\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR,
|
|
dns_query_mx_fn *\fIcbck\fR, \fIdata\fR);
|
|
struct dns_rr_mx *
|
|
\fBdns_resolve_mx\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR);
|
|
.fi
|
|
.PP
|
|
The \fBdns_rr_mx\fR structure holds a result of an IN MX query, which
|
|
is an array of mail exchangers for a given domain. Callback routine for IN MX
|
|
queries expected to be of type \fBdns_query_mx_fn\fR, which expects pointer to
|
|
\fBdns_rr_mx\fR structure as query result instead of raw DNS packet.
|
|
The \fBdns_parse_mx\fR() is used to convert raw DNS reply packet into
|
|
\fBdns_rr_mx\fR structure (it is used internally and may be used directly too
|
|
with generic query interface). Routines \fBdns_submit_mx\fR() and
|
|
\fBdns_resolve_mx\fR() are used to perform IN MX queries in a type-safe
|
|
manner. The \fIname\fR parameter is the domain name in question, and
|
|
\fIflags\fR is query flags bitmask, with one bit, DNS_NOSRCH, of practical
|
|
interest (if the \fIname\fR is absolute, that is, it ends up with a dot,
|
|
DNS_NOSRCH flag will be set automatically).
|
|
|
|
.SS "TXT Queries"
|
|
.PP
|
|
.nf
|
|
struct \fBdns_txt\fR { /* single TXT record */
|
|
int \fBlen\fR; /* length of the text */
|
|
unsigned char *\fBtxt\fR; /* pointer to the text */
|
|
};
|
|
struct \fBdns_rr_txt\fR { /* TXT RRset */
|
|
char *\fBdnstxt_qname\fR; /* original query name */
|
|
char *\fBdnstxt_cname\fR; /* canonical name */
|
|
unsigned \fBdnstxt_ttl\fR; /* Time-To-Live (TTL) value */
|
|
int \fBdnstxt_nrr\fR; /* number of text records in the set */
|
|
struct dns_txt \fBdnstxt_txt\fR[]; /* array of TXT records */
|
|
};
|
|
typedef void
|
|
\fBdns_query_txt_fn\fR(\fIctx\fR, struct dns_rr_txt *\fIresult\fR, \fIdata\fR)
|
|
dns_parse_fn \fBdns_parse_txt\fB;
|
|
struct dns_query *
|
|
\fBdns_submit_txt\fB(\fIctx\fR, const char *\fIname\fR, enum dns_class \fIqcls\fR,
|
|
int \fIflags\fR, dns_query_txt_fn *\fIcbck\fR, \fIdata\fR);
|
|
struct dns_rr_txt *
|
|
\fBdns_resolve_txt\fB(\fIctx\fR, const char *\fIname\fR,
|
|
enum dns_class \fIqcls\fR, int \fIflags\fR);
|
|
.fi
|
|
.PP
|
|
The \fBdns_rr_txt\fR structure holds a result of a TXT query, which is an
|
|
array of text records for a given domain name. Callback routine for TXT
|
|
queries expected to be of type \fBdns_query_txt_fn\fR, which expects pointer
|
|
to \fBdns_rr_txt\fR structure as query result instead of raw DNS packet.
|
|
The \fBdns_parse_txt\fR() is used to convert raw DNS reply packet into
|
|
\fBdns_rr_txt\fR structure (it is used internally and may be used directly too
|
|
with generic query interface). Routines \fBdns_submit_txt\fR() and
|
|
\fBdns_resolve_txt\fR() are used to perform IN MX queries in a type-safe
|
|
manner. The \fIname\fR parameter is the domain name in question, and
|
|
\fIflags\fR is query flags bitmask, with one bit, DNS_NOSRCH, of practical
|
|
interest (if the \fIname\fR is absolute, that is, it ends up with a dot,
|
|
DNS_NOSRCH flag will be set automatically). Note that each TXT string
|
|
is represented by \fBstruct\ dns_txt\fR, while zero-terminated (and the
|
|
len field of the structure does not include the terminator), may contain
|
|
embedded null characters -- content of TXT records is not interpreted
|
|
by the library in any way.
|
|
|
|
.SS "SRV Queries"
|
|
.PP
|
|
.nf
|
|
struct \fBdns_srv\fR { /* single SRV record */
|
|
int \fBpriority\fR; /* priority of the record */
|
|
int \fBweight\fR; /* weight of the record */
|
|
int \fBport\fR; /* the port number to connect to */
|
|
char *\fBname\fR; /* target host name */
|
|
};
|
|
struct \fBdns_rr_srv\fR { /* SRV RRset */
|
|
char *\fBdnssrv_qname\fR; /* original query name */
|
|
char *\fBdnssrv_cname\fR; /* canonical name */
|
|
unsigned \fBdnssrv_ttl\fR; /* Time-To-Live (TTL) value */
|
|
int \fBdnssrv_nrr\fR; /* number of text records in the set */
|
|
struct dns_srv \fBdnssrv_srv\fR[]; /* array of SRV records */
|
|
};
|
|
typedef void
|
|
\fBdns_query_srv_fn\fR(\fIctx\fR, struct dns_rr_srv *\fIresult\fR, \fIdata\fR)
|
|
dns_parse_fn \fBdns_parse_srv\fB;
|
|
struct dns_query *
|
|
\fBdns_submit_srv\fB(\fIctx\fR, const char *\fIname\fR, const char *\fIservice\fR, const char *\fIprotocol\fR,
|
|
int \fIflags\fR, dns_query_txt_fn *\fIcbck\fR, \fIdata\fR);
|
|
struct dns_rr_srv *
|
|
\fBdns_resolve_srv\fB(\fIctx\fR, const char *\fIname\fR, const char *\fIservice\fR, const char *\fIprotocol\fR,
|
|
int \fIflags\fR);
|
|
.fi
|
|
.PP
|
|
The \fBdns_rr_srv\fR structure holds a result of an IN SRV (rfc2782) query,
|
|
which is an array of servers (together with port numbers) which are performing
|
|
operations for a given \fIservice\fR using given \fIprotocol\fR on a target
|
|
domain \fIname\fR. Callback routine for IN SRV queries expected to be of type
|
|
\fBdns_query_srv_fn\fR, which expects pointer to \fBdns_rr_srv\fR structure as
|
|
query result instead of raw DNS packet. The \fBdns_parse_srv\fR() is used to
|
|
convert raw DNS reply packet into \fBdns_rr_srv\fR structure (it is used
|
|
internally and may be used directly too with generic query interface).
|
|
Routines \fBdns_submit_srv\fR() and \fBdns_resolve_srv\fR() are used to
|
|
perform IN SRV queries in a type-safe manner. The \fIname\fR parameter
|
|
is the domain name in question, \fIservice\fR and \fRprotocl\fR specifies the
|
|
service and the protocol in question (the library will construct query DN
|
|
according to rfc2782 rules) and may be NULL (in this case the library
|
|
assumes \fIname\fR parameter holds the complete SRV query), and
|
|
\fIflags\fR is query flags bitmask, with one bit, DNS_NOSRCH, of practical
|
|
interest (if the \fIname\fR is absolute, that is, it ends up with a dot,
|
|
DNS_NOSRCH flag will be set automatically).
|
|
|
|
.SS "NAPTR Queries"
|
|
.PP
|
|
.nf
|
|
struct \fBdns_naptr\fR { /* single NAPTR record */
|
|
int \fBorder\fR; /* record order */
|
|
int \fBpreference\fR; /* preference of this record */
|
|
char *\fBflags\fR; /* application-specific flags */
|
|
char *\fBservices\fR; /* service parameters */
|
|
char *\fBregexp\fR; /* substitutional regular expression */
|
|
char *\fBreplacement\fR; /* replacement string */
|
|
};
|
|
struct \fBdns_rr_naptr\fR { /* NAPTR RRset */
|
|
char *\fBdnsnaptr_qname\fR; /* original query name */
|
|
char *\fBdnsnaptr_cname\fR; /* canonical name */
|
|
unsigned \fBdnsnaptr_ttl\fR; /* Time-To-Live (TTL) value */
|
|
int \fBdnsnaptr_nrr\fR; /* number of text records in the set */
|
|
struct dns_naptr \fBdnsnaptr_naptr\fR[]; /* array of NAPTR records */
|
|
};
|
|
typedef void
|
|
\fBdns_query_naptr_fn\fR(\fIctx\fR, struct dns_rr_naptr *\fIresult\fR, \fIdata\fR)
|
|
dns_parse_fn \fBdns_parse_naptr\fB;
|
|
struct dns_query *
|
|
\fBdns_submit_naptr\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR,
|
|
dns_query_txt_fn *\fIcbck\fR, \fIdata\fR);
|
|
struct dns_rr_naptr *
|
|
\fBdns_resolve_naptr\fB(\fIctx\fR, const char *\fIname\fR, int \fIflags\fR);
|
|
.fi
|
|
.PP
|
|
The \fBdns_rr_naptr\fR structure holds a result of an IN NAPTR (rfc3403) query.
|
|
Callback routine for IN NAPTR queries expected to be of type
|
|
\fBdns_query_naptr_fn\fR, expects pointer to \fBdns_rr_naptr\fR
|
|
structure as query result instead of raw DNS packet.
|
|
The \fBdns_parse_naptr\fR() is used to convert raw DNS reply packet into
|
|
\fBdns_rr_naptr\fR structure (it is used
|
|
internally and may be used directly too with generic query interface).
|
|
Routines \fBdns_submit_naptr\fR() and \fBdns_resolve_naptr\fR() are used to
|
|
perform IN NAPTR queries in a type-safe manner. The \fIname\fR parameter
|
|
is the domain name in question, and \fIflags\fR is query flags bitmask,
|
|
with one bit, DNS_NOSRCH, of practical interest (if the \fIname\fR is
|
|
absolute, that is, it ends up with a dot, DNS_NOSRCH flag will be set
|
|
automatically).
|
|
|
|
.SS "DNSBL Interface"
|
|
.PP
|
|
A DNS-based blocklists, or a DNSBLs, are in wide use nowadays, especially
|
|
to protect mailservers from spammers. The library provides DNSBL interface,
|
|
a set of routines to perform queries against DNSBLs. Routines accepts an
|
|
IP address (IPv4 and IPv6 are both supported) and a base DNSBL zone as
|
|
query parameters, and returns either \fBdns_rr_a4\fR or \fBdns_rr_txt\fR
|
|
structure. Note that IPv6 interface return IPv4 RRset.
|
|
.PP
|
|
.nf
|
|
struct dns_query *
|
|
\fBdns_submit_a4dnsbl\fR(\fIctx\fR,
|
|
const struct in_addr *\fIaddr\fR, const char *\fIdnsbl\fR,
|
|
dns_query_a4_fn *\fIcbck\fR, void *\fIdata\fR);
|
|
struct dns_query *
|
|
\fBdns_submit_a4dnsbl_txt\fR(\fIctx\fR,
|
|
const struct in_addr *\fIaddr\fR, const char *\fIdnsbl\fR,
|
|
dns_query_txt_fn *\fIcbck\fR, void *\fIdata\fR);
|
|
struct dns_query *
|
|
\fBdns_submit_a6dnsbl\fR(\fIctx\fR,
|
|
const struct in6_addr *\fIaddr\fR, const char *\fIdnsbl\fR,
|
|
dns_query_a4_fn *\fIcbck\fR, void *\fIdata\fR);
|
|
struct dns_query *
|
|
\fBdns_submit_a6dnsbl_txt\fR(\fIctx\fR,
|
|
const struct in6_addr *\fIaddr\fR, const char *\fIdnsbl\fR,
|
|
dns_query_txt_fn *\fIcbck\fR, void *\fIdata\fR);
|
|
struct dns_rr_a4 *\fBdns_resolve_a4dnsbl\fR(\fIctx\fR,
|
|
const struct in_addr *\fIaddr\fR, const char *\fIdnsbl\fR)
|
|
struct dns_rr_txt *\fBdns_resolve_a4dnsbl_txt\fR(\fIctx\fR,
|
|
const struct in_addr *\fIaddr\fR, const char *\fIdnsbl\fR)
|
|
struct dns_rr_a4 *\fBdns_resolve_a6dnsbl\fR(\fIctx\fR,
|
|
const struct in6_addr *\fIaddr\fR, const char *\fIdnsbl\fR)
|
|
struct dns_rr_txt *\fBdns_resolve_a6dnsbl_txt\fR(\fIctx\fR,
|
|
const struct in6_addr *\fIaddr\fR, const char *\fIdnsbl\fR)
|
|
.fi
|
|
Perform (submit or resolve) a DNSBL query for the given \fIdnsbl\fR
|
|
domain and an IP \fIaddr\fR in question, requesting either A or TXT
|
|
records.
|
|
|
|
.SS "RHSBL Interface"
|
|
.PP
|
|
RHSBL is similar to DNSBL, but instead of an IP address, the
|
|
parameter is a domain name.
|
|
.PP
|
|
.nf
|
|
struct dns_query *
|
|
\fBdns_submit_rhsbl\fR(\fIctx\fR, const char *\fIname\fR, const char *\fIrhsbl\fR,
|
|
dns_query_a4_fn *\fIcbck\fR, void *\fIdata\fR);
|
|
struct dns_query *
|
|
\fBdns_submit_rhsbl_txt\fR(\fIctx\fR, const char *\fIname\fR, const char *\fIrhsbl\fR,
|
|
dns_query_txt_fn *\fIcbck\fR, void *\fIdata\fR);
|
|
struct dns_rr_a4 *
|
|
\fBdns_resolve_rhsbl\fR(\fIctx\fR, const char *\fIname\fR, const char *\fIrhsbl\fR);
|
|
struct dns_rr_txt *
|
|
\fBdns_resolve_rhsbl_txt\fR(\fIctx\fR, const char *\fIname\fR, const char *\fIrhsbl\fR);
|
|
.fi
|
|
Perform (submit or resolve) a RHSBL query for the given \fIrhsbl\fR
|
|
domain and \fIname\fR in question, requesting either A or TXT records.
|
|
|
|
|
|
.SH "LOW-LEVEL INTERFACE"
|
|
|
|
.SS "Domain Names (DNs)"
|
|
|
|
.PP
|
|
A DN is a series of domain name labels each starts with length byte,
|
|
followed by empty label (label with zero length). The following
|
|
routines to work with DNs are provided.
|
|
|
|
.PP
|
|
.nf
|
|
unsigned \fBdns_dnlen\fR(const unsigned char *\fIdn\fR)
|
|
.fi
|
|
.RS
|
|
return length of the domain name \fIdn\fR, including the terminating label.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
unsigned \fBdns_dnlabels\fR(const unsigned char *\fIdn\fR)
|
|
.fi
|
|
.RS
|
|
return number of non-zero labels in domain name \fIdn\fR.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
unsigned \fBdns_dnequal\fR(\fIdn1\fR, \fIdn2\fR)
|
|
const unsigned char *\fIdn1\fR, *\fIdn2\fR;
|
|
.fi
|
|
.RS
|
|
test whenever the two domain names, \fIdn1\fR and \fIdn2\fR, are
|
|
equal (case-insensitive). Return domain name length if equal
|
|
or 0 if not.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
unsigned \fBdns_dntodn\fR(\fIsdn\fR, \fIddn\fR, \fIdnsiz\fR)
|
|
const unsigned char *\fIsdn\fR;
|
|
unsigned char *\fIddn\fR;
|
|
unsigned \fIdnsiz\fR;
|
|
.fi
|
|
.RS
|
|
copies the source domain name \fIsdn\fR to destination buffer \fIddn\fR
|
|
of size \fIdnsiz\fR. Return domain name length or 0 if \fIddn\fR is
|
|
too small.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
int \fBdns_ptodn\fR(\fIname\fR, \fInamelen\fR, \fIdn\fR, \fIdnsiz\fR, \fIisabs\fR)
|
|
int \fBdns_sptodn\fR(\fIname\fR, \fIdn\fR, \fIdnsiz\fR)
|
|
const char *\fIname\fR; unsigned \fInamelen\fR;
|
|
unsigned char *\fIdn\fR; unsigned \fIdnsiz\fR;
|
|
int *\fIisabs\fR;
|
|
.fi
|
|
.RS
|
|
convert asciiz name \fIname\fR of length \fInamelen\fR to DN format,
|
|
placing result into buffer \fIdn\fR of size \fIdnsiz\fR. Return
|
|
length of the DN if successeful, 0 if the \fIdn\fR buffer supplied is
|
|
too small, or negative value if \fIname\fR is invalid. If \fIisabs\fR
|
|
is non-NULL and conversion was successeful, *\fIisabs\fR will be set to
|
|
either 1 or 0 depending whenever \fIname\fR was absolute (i.e. ending with
|
|
a dot) or not. Name length, \fInamelength\fR, may be zero, in which case
|
|
strlen(\fIname\fR) will be used. Second form, \fBdns_sptodn\fR(), is a
|
|
simplified form of \fBdns_ptodn\fR(), equivalent to
|
|
.br
|
|
.nf
|
|
\fBdns_ptodn\fR(\fIname\fR, 0, \fIdn\fR, \fIdnlen\fR, 0).
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
extern const unsigned char \fBdns_inaddr_arpa_dn\fR[]
|
|
int \fBdns_a4todn\fR(const struct in_addr *\fIaddr\fR, const unsigned char *\fItdn\fR,
|
|
unsigned char *\fIdn\fR, unsigned \fIdnsiz\fR)
|
|
int \fBdns_a4ptodn\fR(const struct in_addr *\fIaddr\fR, const char *\fItname\fR,
|
|
unsigned char *\fIdn\fR, unsigned \fIdnsiz\fR)
|
|
extern const unsigned char \fBdns_ip6_arpa_dn\fR[]
|
|
int \fBdns_a6todn\fR(const struct in6_addr *\fIaddr\fR, const unsigned char *\fItdn\fR,
|
|
unsigned char *\fIdn\fR, unsigned \fIdnsiz\fR)
|
|
int \fBdns_a6ptodn\fR(const struct in6_addr *\fIaddr\fR, const char *\fItname\fR,
|
|
unsigned char *\fIdn\fR, unsigned \fIdnsiz\fR)
|
|
.fi
|
|
.RS
|
|
several variants of routines to convert IPv4 and IPv6 address \fIaddr\fR
|
|
into reverseDNS-like domain name in DN format, storing result in \fIdn\fR
|
|
of size \fIdnsiz\fR. \fItdn\fR (or \fItname\fR) is the base zone name,
|
|
like in-addr.arpa for IPv4 or in6.arpa for IPv6. If \fItdn\fR (or \fItname\fR)
|
|
is NULL, \fBdns_inaddr_arpa_dn\fR (or \fBdns_ip6_arpa_dn\fR) will be used.
|
|
The routines may be used to construct a DN for a DNSBL lookup for example.
|
|
All routines return length of the resulting DN on success, -1 if resulting
|
|
DN is invalid, or 0 if the \fIdn\fR buffer (\fIdnsiz\fR) is too small.
|
|
To hold standard rDNS DN, a buffer of size \fBDNS_A4RSIZE\fR (30 bytes) for
|
|
IPv4 address, or \fBDNS_A6RSIZE\fR (74 bytes) for IPv6 address, is sufficient.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
int \fBdns_dntop\fR(\fIdn\fR, \fIname\fR, \fInamesiz\fR)
|
|
const unsigned char *\fIdn\fR;
|
|
const char *\fIname\fR; unsigned \fInamesiz\fR;
|
|
.fi
|
|
.RS
|
|
convert domain name \fIdn\fR in DN format to asciiz string, placing result
|
|
into \fIname\fR buffer of size \fInamesiz\fR. Maximum length of asciiz
|
|
representation of domain name is \fBDNS_MAXNAME\fR (1024) bytes. Root
|
|
domain is represented as empty string. Return length of the resulting name
|
|
(including terminating character, i.e. strlen(name)+1) on success, 0 if the
|
|
\fIname\fR buffer is too small, or negative value if \fIdn\fR is invalid
|
|
(last case should never happen since all routines in this library which
|
|
produce domain names ensure the DNs generated are valid).
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
const char *\fBdns_dntosp\fR(const unsigned char *\fIdn\fR)
|
|
.fi
|
|
.RS
|
|
convert domain name \fIdn\fR in DN format to asciiz string using static
|
|
buffer. Return the resulting asciiz string on success or NULL on failure.
|
|
Note since this routine uses static buffer, it is not thread-safe.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
unsigned \fBdns_dntop_size\fR(const unsigned char *\fIdn\fR)
|
|
.fi
|
|
.RS
|
|
return the buffer size needed to convert the \fIdn\fR domain name
|
|
in DN format to asciiz string, for \fBdns_dntop\fR(). The routine
|
|
return either the size of buffer required, including the trailing
|
|
zero byte, or 0 if \fIdn\fR is invalid.
|
|
.RE
|
|
|
|
.SS "Working with DNS Packets"
|
|
|
|
.PP
|
|
The following routines are provided to encode and decode DNS on-wire
|
|
packets. This is low-level interface.
|
|
|
|
.PP
|
|
DNS response codes (returned by \fBdns_rcode\fR() routine) are
|
|
defined as constants prefixed with \fBDNS_R_\fR. See dns.h
|
|
header file for the complete list. In particular, constants
|
|
\fBDNS_R_NOERROR\fR (0), \fBDNS_R_SERVFAIL\fR, \fBDNS_R_NXDOMAIN\fR
|
|
may be of interest to an application.
|
|
|
|
.PP
|
|
.nf
|
|
unsigned \fBdns_get16\fR(const unsigned char *\fIp\fR)
|
|
unsigned \fBdns_get32\fR(const unsigned char *\fIp\fR)
|
|
.fi
|
|
.RS
|
|
helper routines, convert 16-bit or 32-bit integer in on-wire
|
|
format pointed to by \fIp\fR to unsigned.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
unsigned char *\fBdns_put16\fR(unsigned char *\fId\fR, unsigned \fIn\fR)
|
|
unsigned char *\fBdns_put32\fR(unsigned char *\fId\fR, unsigned \fIn\fR)
|
|
.fi
|
|
.RS
|
|
helper routine, convert unsigned 16-bit or 32-bit integer \fIn\fR to
|
|
on-wire format to buffer pointed to by \fId\fR, return \fId\fR+2 or
|
|
\fId\fR+4.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
\fBDNS_HSIZE\fR (12)
|
|
.fi
|
|
.RS
|
|
defines size of DNS header. Data section
|
|
in the DNS packet immediately follows the header. In the header,
|
|
there are query identifier (id), various flags and codes,
|
|
and number of resource records in various data sections.
|
|
See dns.h header file for complete list of DNS header definitions.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
unsigned \fBdns_qid\fR(const unsigned char *\fIpkt\fR)
|
|
int \fBdns_rd\fR(const unsigned char *\fIpkt\fR)
|
|
int \fBdns_tc\fR(const unsigned char *\fIpkt\fR)
|
|
int \fBdns_aa\fR(const unsigned char *\fIpkt\fR)
|
|
int \fBdns_qr\fR(const unsigned char *\fIpkt\fR)
|
|
int \fBdns_ra\fR(const unsigned char *\fIpkt\fR)
|
|
unsigned \fBdns_opcode\fR(const unsigned char *\fIpkt\fR)
|
|
unsigned \fBdns_rcode\fR(const unsigned char *\fIpkt\fR)
|
|
unsigned \fBdns_numqd\fR(const unsigned char *\fIpkt\fR)
|
|
unsigned \fBdns_numan\fR(const unsigned char *\fIpkt\fR)
|
|
unsigned \fBdns_numns\fR(const unsigned char *\fIpkt\fR)
|
|
unsigned \fBdns_numar\fR(const unsigned char *\fIpkt\fR)
|
|
const unsigned char *\fBdns_payload\fR(const unsigned char *\fIpkt\fR)
|
|
.fi
|
|
.RS
|
|
return various parts from the DNS packet header \fIpkt\fR:
|
|
query identifier (qid),
|
|
recursion desired (rd) flag,
|
|
truncation occured (tc) flag,
|
|
authoritative answer (aa) flag,
|
|
query response (qr) flag,
|
|
recursion available (ra) flag,
|
|
operation code (opcode),
|
|
result code (rcode),
|
|
number of entries in question section (numqd),
|
|
number of answers (numan),
|
|
number of authority records (numns),
|
|
number of additional records (numar),
|
|
and the pointer to the packet data (payload).
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
int \fBdns_getdn\fR(\fIpkt\fR, \fIcurp\fR, \fIpkte\fR, \fIdn\fR, \fIdnsiz\fR)
|
|
const unsigned char *\fBdns_skipdn\fR(\fIcur\fR, \fIpkte\fR)
|
|
const unsigned char *\fIpkt\fR, *\fIpkte\fR, **\fIcurp\fR, *\fIcur\fR;
|
|
unsigned char *\fIdn\fR; unsigned \fIdnsiz\fR;
|
|
.fi
|
|
.RS
|
|
\fBdns_getdn\fR() extract DN from DNS packet \fIpkt\fR which ends before
|
|
\fIpkte\fR starting at position *\fIcurp\fR into buffer pointed to by
|
|
\fIdn\fR of size \fIdnsiz\fR. Upon successeful completion, *\fIcurp\fR
|
|
will point to the next byte in the packet after the extracted domain name.
|
|
It return positive number (length of the DN if \fIdn\fR) upon successeful
|
|
completion, negative value on error (when the packet contains invalid data),
|
|
or zero if the \fIdnsiz\fR is too small (maximum length of a domain name is
|
|
\fBDNS_MAXDN\fR). \fBdns_skipdn\fR() return pointer to the next byte in
|
|
DNS packet which ends up before \fIpkte\fR after a domain name which starts
|
|
at the \fIcur\fP byte, or NULL if the packet is invalid. \fBdns_skipdn\fR()
|
|
is more or less equivalent to what \fBdns_getdn\fR() does, except it does not
|
|
actually extract the domain name in question, and uses simpler interface.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
struct \fBdns_rr\fR {
|
|
unsigned char \fBdnsrr_dn\fR[DNS_MAXDN]; /* the RR DN name */
|
|
enum dns_class \fBdnsrr_cls\fR; /* class of the RR */
|
|
enum dns_type \fBdnsrr_typ\fR; /* type of the RR */
|
|
unsigned \fBdnsrr_ttl\fR; /* TTL value */
|
|
unsigned \fBdnsrr_dsz\fR; /* size of data in bytes */
|
|
const unsigned char *\fBdnsrr_dptr\fR; /* pointer to the first data byte */
|
|
const unsigned char *\fBdnsrr_dend\fR; /* next byte after RR */
|
|
};
|
|
.fi
|
|
.RS
|
|
The \fBdns_rr\fR structure is used to hold information about
|
|
single DNS Resource Record (RR) in an easy to use form.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
struct \fBdns_parse\fR {
|
|
const unsigned char *\fBdnsp_pkt\fR; /* pointer to the packet being parsed */
|
|
const unsigned char *\fBdnsp_end\fR; /* end of the packet pointer */
|
|
const unsigned char *\fBdnsp_cur\fR; /* current packet positionn */
|
|
const unsigned char *\fBdnsp_ans\fR; /* pointer to the answer section */
|
|
int \fBdnsp_rrl\fR; /* number of RRs left */
|
|
int \fBdnsp_nrr\fR; /* number of relevant RRs seen so far */
|
|
unsigned \fBdnsp_ttl\fR; /* TTL value so far */
|
|
const unsigned char *\fBdnsp_qdn\fR; /* the domain of interest or NULL */
|
|
enum dns_class \fBdnsp_qcls\fR; /* class of interest or 0 for any */
|
|
enum dns_type \fBdnsp_qtyp\fR; /* type of interest or 0 for any */
|
|
unsigned char \fBdnsp_dnbuf\fR[DNS_MAXDN]; /* domain name buffer */
|
|
};
|
|
.fi
|
|
.RS
|
|
The \fBdns_parse\fR structure is used to parse DNS reply packet.
|
|
It holds information about the packet being parsed (dnsp_pkt, dnsp_end and
|
|
dnsp_cur fields), number of RRs in the current section left to do, and
|
|
the information about specific RR which we're looking for (dnsp_qdn,
|
|
dnsp_qcls and dnsp_qtyp fields).
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
int \fBdns_initparse\fR(struct dns_parse *\fIp\fR,
|
|
const unsigned char *\fIqdn\fR,
|
|
const unsigned char *\fIpkt\fR,
|
|
const unsigned char *\fIcur\fR,
|
|
const unsigned char *\fIend\fR)
|
|
.fi
|
|
.RS
|
|
initializes the RR parsing structure \fIp\fR. Arguments \fIpkt\fR, \fIcur\fR
|
|
and \fIend\fR should describe the received packet: \fIpkt\fR is the start of
|
|
the packet, \fIend\fR points to the next byte after the end of the packet,
|
|
and \fIcur\fR points past the query DN in query section (to query class+type
|
|
information). And \fIqdn\fR points to the query DN. This is the arguments
|
|
passed to \fBdns_parse_fn\fR() routine. \fBdns_initparse\fR() initializes
|
|
\fBdnsp_pkt\fR, \fBdnsp_end\fR and \fBdnsp_qdn\fR fields to the corresponding
|
|
arguments, extracts and initializes \fBdnsp_qcls\fR and \fBdnsp_qtyp\fR
|
|
fields to the values found at \fIcur\fR pointer, initializes
|
|
\fBdnsp_cur\fR and \fBdnsp_ans\fR fields to be \fIcur\fR+4 (to the start of
|
|
answer section), and initializes \fBdnsp_rrl\fR field to be number of entries
|
|
in answer section. \fBdnsp_ttl\fR will be set to max TTL value, 0xffffffff,
|
|
and \fBdnsp_nrr\fR to 0.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
int \fBdns_nextrr\fR(struct dns_parse *\fIp\fR, struct dns_rr *\fIrr\fR);
|
|
.fi
|
|
.RS
|
|
searches for next RR in the packet based on the criteria provided in
|
|
the \fIp\fR structure, filling in the \fIrr\fR structure and
|
|
advancing \fIp\fR->\fBdnsp_cur\fR to the next RR in the packet.
|
|
RR selection is based on dnsp_qdn, dnsp_qcls and dnsp_qtyp fields in
|
|
the dns_parse structure. Any (or all) of the 3 fields may be 0,
|
|
which means any actual value from the packet is acceptable. In case
|
|
the field isn't 0 (or NULL for dnsp_qdn), only RRs with corresponding
|
|
characteristics are acceptable. Additionally, when dnsp_qdn is non-NULL,
|
|
\fBdns_nextrr\fR() performs automatic CNAME expansion.
|
|
Routine will return positive value on success, 0 in case it reached the end
|
|
of current section in the packet (\fIp\fR->\fBdnsp_rrl\fR is zero), or
|
|
negative value if next RR can not be decoded (packet format is invalid).
|
|
The routine updates \fIp\fR->\fBdnsp_qdn\fR automatically when this
|
|
field is non-NULL and it encounters appropriate CNAME RRs (saving CNAME
|
|
target in \fIp\fR->\fBdnsp_dnbuf\fR), so after end of the process,
|
|
\fIp\fR->\fBdnsp_qdn\fR will point to canonical name of the domain
|
|
in question. The routine updates \fIp\fR->\fBdnsp_ttl\fR value to
|
|
be the minimum TTL of all RRs found.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
void \fBdns_rewind\fR(struct dns_parse *\fIp\fR, const unsigned char *\fIqdn\fR)
|
|
.fi
|
|
.RS
|
|
this routine "rewinds" the packet parse state structure to be at the
|
|
same state as after a call to \fBdns_initparse\fR(), i.e. reposition
|
|
the parse structure \fIp\fR to the start of answer section and
|
|
initialize \fIp\fR->\fBdnsp_rrl\fR to the number of entries in
|
|
answer section.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
int \fBdns_stdrr_size\fR(const struct dns_parse *\fIp\fR);
|
|
.fi
|
|
.RS
|
|
return size to hold standard RRset structure information, as shown
|
|
in \fBdns_rr_null\fR structure (for the query and canonical
|
|
names). Used to calculate amount of memory to allocate for common
|
|
part of type-specific RR structures in parsing routines.
|
|
.RE
|
|
|
|
.PP
|
|
.nf
|
|
void *\fBdns_stdrr_finish\fR(struct dns_rr_null *\fIret\fR, char *\fIcp\fR,
|
|
const struct dns_parse *\fIp\fR);
|
|
.fi
|
|
.RS
|
|
initializes standard RRset fields in \fIret\fR structure using buffer
|
|
pointed to by \fIcp\fR, which should have at least as many bytes
|
|
as \fBdns_stdrr_size\fR(\fIp\fR) returned. Used to finalize common
|
|
part of type-specific RR structures in parsing routines.
|
|
.RE
|
|
|
|
.PP
|
|
See library source for usage examples of all the above low-level routines,
|
|
especially source of the parsing routines.
|
|
|
|
.SH AUTHOR
|
|
.PP
|
|
The \fBudns\fR library has been written by Michael Tokarev, mjt@corpit.ru.
|