DUO(3)

💖 DUO — the Duo authentication service, bestie edition 💖

okay so this is duo(3), a library functions manual, and it's literally the whole Duo two-factor auth API. sit down, grab a strawberry, we're doing this 🍓

---

✨ 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 gives you access to the Duo two-factor authentication service. that's the whole vibe. 💅

🎀 duo_open()

duo_open() is how you get yourself a handle to the Duo service, no cap.

• ikey and skey are the required integration and secret keys, respectively, for a Duo customer account.
• progname is what identifies the program to the Duo service.
• cafile should be NULL, OR the pathname of a PEM-format CA certificate if you want to override the default.

🦋 duo_set_conv_funcs()

duo_set_conv_funcs() is your glow-up for the internal user conversation functions. here's the breakdown:

• conv_prompt gets called to present the user a login menu and prompt, and to gather their response — it returns buf, or NULL on error. you can set it to NULL if automatic login is specified with DUO_FLAG_AUTO. ✨
• conv_status gets called to display status messages to the user, and may be NULL if no status display is needed.
• conv_arg gets passed as the first argument to these conversation functions.

👑 duo_set_host()

duo_set_host() lets you override the default Duo API host. iconic.

🔥 duo_set_ssl_verify()

duo_set_ssl_verify() lets you override SSL certificate verification — which is enabled by default, just so you know.

💜 duo_login()

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 (like voice callback progress, for example). only issue one status message per authentication attempt.

If it's not NULL, the command to be authorized will be displayed during push authentication. 🫶

🧚 duo_geterr()

duo_geterr() returns a description of the last-seen error on the specified Duo API handle.

bestie, listen: the returned constant string should not be modified or freed by the caller. leave it alone, it's fine where it is. 🙈

🌈 duo_close()

duo_close() closes and frees the specified Duo API handle. clean up after yourself, periodt.

---

⭐ 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⟩

---

and that's the whole page, bestie 🎀 this one's from Debian, dated October 31, 2010 — yes, 2010, it's giving vintage and it's still serving. go forth and two-factor, you got this 💅✨