NAME

       duo — 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 conversation 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 authentication factor.
             DUO_FLAG_SYNC     Do not report incremental  status  during  authentication  (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 specified 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 VALUES

       duo_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 ALSO

       pam_duo(8), login_duo(1)

AUTHORS

       Duo Security ⟨support@duosecurity.com⟩

Debian                                          October 31, 2010                                          DUO(3)