1DUO(3)                   BSD Library Functions Manual                   DUO(3)
2

NAME

4     duo — Duo authentication service
5

SYNOPSIS

7     #include <duo.h>
8
9     duo_t *
10     duo_open(const char *ikey, const char *skey, const char *progname,
11         const char *cafile);
12
13     void
14     duo_set_conv_funcs(duo_t *d,
15         char *(*conv_prompt)(void *conv_arg, const char *, char *, size_t),
16         void (*conv_status)(void *conv_arg, const char *msg),
17         void *conv_arg);
18
19     void
20     duo_set_host(duo_t *d, const char *hostname);
21
22     void
23     duo_set_ssl_verify(duo_t *d, int bool);
24
25     duo_code_t
26     duo_login(duo_t *d, const char *username, const char *client_ip,
27         int flags, const char *command);
28
29     const char *
30     duo_geterr(duo_t *d);
31
32     void
33     duo_close(duo_t *d);
34

DESCRIPTION

36     The duo API provides access to the Duo two-factor authentication service.
37
38     duo_open() is used to obtain a handle to the Duo service.  ikey and skey
39     are the required integration and secret keys, respectively, for a Duo
40     customer account.  progname identifies the program to the Duo service.
41     cafile should be NULL or the pathname of a PEM-format CA certificate to
42     override the default.
43
44     duo_set_conv_funcs() may be used to override the internal user conversa‐
45     tion functions.  conv_prompt is called to present the user a login menu
46     and prompt, and gather their response, returning buf or NULL on error. It
47     may be set to NULL if automatic login is specified with DUO_FLAG_AUTO.
48     conv_status is called to display status messages to the user, and may be
49     NULL if no status display is needed.  conv_arg is passed as the first ar‐
50     gument to these conversation functions.
51
52     duo_set_host() may be used to override the default Duo API host.
53
54     duo_set_ssl_verify() may be used to override SSL certificate verification
55     (enabled by default).
56
57     duo_login() performs secondary authentication via the Duo service for the
58     specified username.  client_ip is the source IP address of the connection
59     to be authenticated, or NULL to specify the local host. The following
60     bitmask values are defined for flags:
61
62           DUO_FLAG_AUTO     Attempt authentication without prompting the
63                             user, using their default out-of-band authentica‐
64                             tion factor.
65           DUO_FLAG_SYNC     Do not report incremental status during authenti‐
66                             cation (e.g. voice callback progress) - only is‐
67                             sue one status message per authentication at‐
68                             tempt.
69
70     If not NULL, the command to be authorized will be displayed during push
71     authentication.
72
73     duo_geterr() returns a description of the last-seen error on the speci‐
74     fied Duo API handle. The returned constant string should not be modified
75     or freed by the caller.
76
77     duo_close() closes and frees the specified Duo API handle.
78

RETURN VALUES

80     duo_open() returns a pointer to the configured Duo API handle, or NULL on
81     failure.
82
83     duo_login() returns status codes of type duo_code_t, which may have the
84     following values:
85
86           DUO_OK            User authenticated
87           DUO_FAIL          User failed to authenticate
88           DUO_ABORT         User denied by policy
89           DUO_LIB_ERROR     Unexpected library error
90           DUO_CONN_ERROR    Duo service unreachable
91           DUO_CLIENT_ERROR  Invalid client parameters to API call
92           DUO_SERVER_ERROR  Duo service error
93
94     In the event of a DUO_*_ERROR return, duo_geterr may be called to recover
95     a human-readable error message.
96
97     duo_geterr() returns a constant string which should not be modified or
98     freed by the caller.
99

SEE ALSO

101     pam_duo(8), login_duo(1)
102

AUTHORS

104     Duo Security ⟨support@duosecurity.com⟩
105
106BSD                            October 31, 2010                            BSD
Impressum