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.
vbr_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.
vbr_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.
vbr_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.
vbr_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.
vbr_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 vbr_dns_init() forces (re-)initialization of the resolver. This essentially causes the library
to call any initialization function defined by vbr_dns_set_init().
When the library handle is no longer needed, it should be passed to vbr_close().
Install Now
PNG Icons
Emojis
