NAME¶
vbr_init(), vbr_options(), vbr_close(), vbr_geterror(), vbr_getheader(),
vbr_setcert(), vbr_settype(), vbr_setdomain(), vbr_trustedcerts(),
vbr_query(), vbr_settimeout(), vbr_setcallbackint(),
vbr_setcallbackctx(), vbr_setdnscallback(),
vbr_dns_set_query_service(), vbr_dns_set_query_start(),
vbr_dns_set_query_cancel(), vbr_dns_set_query_waitreply() - Vouch
By Reference service facility
SYNOPSIS¶
#include
<vbr.h>
VBR *
vbr_init (void *(*
mallocf )(void *, size_t), void (*
freef )(void *, void *p), void *
closure );
void
vbr_options (VBR *
vbr , unsigned int
opts );
unsigned char *
vbr_geterror (VBR *
vbr );
VBR_STAT
vbr_getheader (VBR *
vbr, unsigned char *
hdr,
size_t
len );
void
vbr_setcert (VBR *
vbr, unsigned char *
cert );
void
vbr_settype (VBR *
vbr, unsigned char *
cert );
void
vbr_setdomain (VBR *
vbr, unsigned char *
cert );
void
vbr_trustedcerts (VBR *
vbr, unsigned char **
cert );
VBR_STAT
vbr_query (VBR *
vbr, unsigned char **
res,
unsigned char **
cert );
VBR_STAT
vbr_settimeout (VBR *
vbr, unsigned int
timeout );
VBR_STAT
vbr_setcallbackint (VBR *
vbr, unsigned int
cbint
);
VBR_STAT
vbr_setcallbackctx (VBR *,
vbr, void *
ctx );
VBR_STAT
vbr_setdnscallback (VBR *,
vbr, void (*
func
)(const void *));
void *
vbr_dns_set_query_service (VBR *
vbr, void *
svc );
void
vbr_dns_set_query_cancel (VBR *
vbr, int (*
func
)(void *, void *));
void
vbr_dns_set_query_start (VBR *
vbr, int (*
func )(void
*, int, unsigned char *, unsigned char *, size_t, void **));
void
vbr_dns_set_query_waitreply (VBR *
vbr, int (*
func
)(void *, void *, struct timeval *, size_t *, int *, int *));
void
vbr_close (VBR *);
DESCRIPTION¶
These functions are an interface to a facility to conduct Vouch By Reference
(VBR) queries and return their results. VBR is defined in RFC5518.
An application first initializes the package by calling
vbr_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 caller can use
vbr_options() to set query processing options. See the
OPTIONS section for details.
The
vbr_geterror() function can be used to poll the library for an error
string that provides further description for the most recent failed operation.
Calling
vbr_getheader() can be used to generate an RFC-compliant
VBR-Info: haeder field based on data provided by other accessor functions,
namely
vbr_setcert(), vbr_settype() and
vbr_setdomain()
(below). A library instance is provided as the first parameter, and a pointer
to the destination buffer and its length are provided in the second and third.
Note that only the value of the header field is stored into the buffer, not
its name; the standard name of the header field is available as the
VBR_INFOHEADER macro.
vbr_setcert() takes a VBR library instance as its first argument and a
colon-separated list of claimed vouching domains as its second. Similarly,
vbr_settype() sets the message type, and
vbr_setdomain() sets
the sending domain. These correspond, respectively, to the "mv",
"mc" and "md" values from a received message's VBR-Info
header field. These values are used by the library instance when calling
vbr_getheader() to generate VBR information header fields to attach to
outgoing messages or when calling
vbr_query() to check for a vouching
reference. Note that the library does no validation of the possible values of
the message type (to allow for new message types that may appear outside of
the original RFC), and has no context to validate the domain.
vbr_trustedcerts() takes a VBR library instance as its first argument and
a NULL-terminated array of pointers to certifier names as its second, which is
used by
vbr_query() to select vouching services the caller trusts. The
intersection of these trusted certifiers and those claimed by an arriving
message. The list is initially empty.
vbr_query() polls trusted certifiers to see if any of them agree with the
assertion made by the message sender. The pointer
res will be set to
point to a result string after the query has been resolved. The result will be
"pass" if any trusted certifier concurred with the assertion made by
the sender. If
cert is not NULL, it will be updated to point to the
name of the trusted certifier that concurred with the sender's assertion when
a "pass" result is returned. If any queries were made but none of
them resulted in concurrence, a result of "fail" is returned. If no
query was made because of errors or because the trusted certifier set and the
sender's certifier set included no vouchers in common,
cert will be
unchanged.
The
vbr_settimeout() function can be used to change the query timeout.
The default is ten seconds. Note that this timeout is applied for each voucher
query, so a call to
vbr_query() can take longer than this if multiple
queries need to be made.
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
vbr_setdnscallback() function. The function
provided should take a void context pointer as its sole argument.
vbr_setcallbackctx() is used to tell the library what context pointer
should be used, and
vbr_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 VBR 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:
vbr_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.
vbr_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
vbr_dns_set_query_start(). The function should return one of the DNS
result codes described below.
vbr_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.
vbr_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
vbr_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.
When the library handle is no longer needed, it should be passed to
vbr_close().
OPTIONS¶
Setting options is done using the
vbr_options() function. The
opts
parameter is a bitwise-OR list of the available options requested by the
application. The currently supported option:
- VBR_FLAG_TRUSTEDONLY
- By default, a VBR query will be sent to the intersection of
the trusted certifiers (provided by the vbr_trustedcerts()
function) and the list of certifiers claimed on a message (provided by the
vbr_sercert() function). With this option enabled, the trusted
certifiers will be checked and the provided certifiers will be
ignored.
RETURN VALUES¶
The following return codes, of type VBR_STAT, can be returned:
- VBR_STAT_OK
- successful completion
- VBR_STAT_INVALID
- operation failed because an invalid parameter was
provided
- VBR_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
- VBR_STAT_NORESOURCE
- a caller-provided buffer was too small to complete the
requested operation, or a memory or file descriptor allocation failed
- VBR_STAT_NOTIMPLEMENT
- an optional library feature was not selected at compilation
time
DNS RETURN CODES¶
Any registered DNS functions should return one of the following result codes:
- VBR_DNS_ERROR
- An error occurred. The cause of the error can be retrieved
using vbr_geterror().
- VBR_DNS_SUCCESS
- The operation was successful.
- VBR_DNS_REPLY
- A reply is available (returned by the "waitreply"
function).
- VBR_DNS_NOREPLY
- No reply was received by the time the query timeout was
reached (returned by the "waitreply" function).
- VBR_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, 2012, The OpenDKIM Project. All rights reserved.
SEE ALSO¶
intro(2)