---
name: "duo"
section: "3"
platform: "linux"
package: "libduo3t64"
version: "1.11.3-1.2+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/duo"
---

# duo(3)

Duo authentication service

## 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)](/pam_duo/8.md), login\_duo(1)

## AUTHORS

Duo Security ⟨support@duosecurity.com⟩