Scroll to navigation

DUO(3) Library Functions Manual DUO(3)

NAME

duoDuo 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.

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

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

() may be used to override the default Duo API host.

() may be used to override SSL certificate verification (enabled by default).

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

Attempt authentication without prompting the user, using their default out-of-band authentication factor.
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.

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

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

User authenticated
User failed to authenticate
User denied by policy
Unexpected library error
Duo service unreachable
Invalid client parameters to API call
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⟩

October 31, 2010 Debian