DUO(3) BSD Library Functions Manual DUO(3)NAMEduo — Duo authentication service
SYNOPSIS
#include <duo.h>
duo_t *
duo_open(const char *ikey, const char *skey, const char *progname,
const char *cafile);
void
duo_set_conv_funcs(duo_t *d,
char *(*conv_prompt)(void *conv_arg, const char *, char *, size_t),
void (*conv_status)(void *conv_arg, const char *msg),
void *conv_arg);
void
duo_set_host(duo_t *d, const char *hostname);
void
duo_set_ssl_verify(duo_t *d, int bool);
duo_code_t
duo_login(duo_t *d, const char *username, const char *client_ip,
int flags, const char *command);
const char *
duo_geterr(duo_t *d);
void
duo_close(duo_t *d);
DESCRIPTION
The duo API provides access to the Duo two-factor authentication service.
duo_open() is used to obtain a handle to the Duo service. ikey and skey
are the required integration and secret keys, respectively, for a Duo
customer account. progname identifies the program to the Duo service.
cafile should be NULL or the pathname of a PEM-format CA certificate to
override the default.
duo_set_conv_funcs() may be used to override the internal user conversa‐
tion functions. conv_prompt is called to present the user a login menu
and prompt, and gather their response, returning buf or NULL on error. It
may be set to NULL if automatic login is specified with DUO_FLAG_AUTO.
conv_status is called to display status messages to the user, and may be
NULL if no status display is needed. conv_arg is passed as the first
argument to these conversation functions.
duo_set_host() may be used to override the default Duo API host.
duo_set_ssl_verify() may be used to override SSL certificate verification
(enabled by default).
duo_login() performs secondary authentication via the Duo service for the
specified username. client_ip is the source IP address of the connection
to be authenticated, or NULL to specify the local host. The following
bitmask values are defined for flags:
DUO_FLAG_AUTO Attempt authentication without prompting the
user, using their default out-of-band authentica‐
tion factor.
DUO_FLAG_SYNC Do not report incremental status during authenti‐
cation (e.g. voice callback progress) - only
issue one status message per authentication
attempt.
If not NULL, the command to be authorized will be displayed during push
authentication.
duo_geterr() returns a description of the last-seen error on the speci‐
fied Duo API handle. The returned constant string should not be modified
or freed by the caller.
duo_close() closes and frees the specified Duo API handle.
RETURN VALUESduo_open() returns a pointer to the configured Duo API handle, or NULL on
failure.
duo_login() returns status codes of type duo_code_t, which may have the
following values:
DUO_OK User authenticated
DUO_FAIL User failed to authenticate
DUO_ABORT User denied by policy
DUO_LIB_ERROR Unexpected library error
DUO_CONN_ERROR Duo service unreachable
DUO_CLIENT_ERROR Invalid client parameters to API call
DUO_SERVER_ERROR Duo service error
In the event of a DUO_*_ERROR return, duo_geterr may be called to recover
a human-readable error message.
duo_geterr() returns a constant string which should not be modified or
freed by the caller.
SEE ALSOpam_duo(8), login_duo(1)AUTHORS
Duo Security ⟨support@duosecurity.com⟩
BSD October 31, 2010 BSD
