DragonFly On-Line Manual Pages

Search: Section:  

DUO(3)                DragonFly Library Functions Manual                DUO(3)


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>

DragonFly 6.5-DEVELOPMENT      October 31, 2010      DragonFly 6.5-DEVELOPMENT

Search: Section: