libvbr(3) Library Functions Manual libvbr(3)
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_geth-
eader() to generate VBR information header fields to attach to outgoing messages or when calling vbr_query() to check for a vouching refer-
ence. 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 previ-
ously 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 inter-
esting 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 certi-
fiers 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)
libvbr(3)