Provided by: libvbr-dev_2.11.0~alpha-11build1_amd64 bug

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(),      vbr_dns_set_query_waitreply(),     vbr_dns_set_init(),
       vbr_dns_set_close(),              vbr_dns_set_nslist(),              vbr_dns_set_config(),
       vbr_dns_set_trustanchor(), vbr_dns_init() - 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_dns_set_init (VBR * vbr, int (* func )(void **);

       void vbr_dns_set_close (VBR * vbr, int (* func )(void *);

       void vbr_dns_set_config (VBR * vbr, int (* func )(void *, const char *);

       void vbr_dns_set_nslist (VBR * vbr, int (* func )(void *, const char *);

       void vbr_dns_set_trustanchor (VBR * vbr, int (* func )(void *, const char *);

       VBR_STAT vbr_dns_init (VBR * vbr );

       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.

       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().

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 Trusted Domain Project.  All rights reserved.

SEE ALSO

       intro(2)

                                                                                        libvbr(3)