Overview
--------

duo_unix - Duo two-factor authentication for Unix systems

Duo provides simple two-factor authentication as a service via:

    1.  Phone callback
    2.  SMS-delivered one-time passcodes
    3.  Duo mobile app to generate one-time passcodes
    4.  Duo mobile app for smartphone push authentication
    5.  Duo hardware token to generate one-time passcodes

This package allows an admin (or ordinary user) to quickly add Duo
authentication to any Unix login without setting up secondary user
accounts, directory synchronization, servers, or hardware.

What's here:

lib
	Simple C API for the Duo two-factor authentication service.

login_duo
	Login utility to add secondary Duo authentication to any login
	(e.g. via sshd ForceCommand or ~/.ssh/authorized_keys command)
	to augment password, pubkey, or other primary auth method.

pam_duo
	Optional Pluggable Authentication Module for Linux, FreeBSD,
	NetBSD, MacOS X, Solaris, AIX, HP-UX to add Duo authentication
	system-wide (e.g. sshd, sudo, su, samba, etc.)

Build
-----

Build dependencies for libduo (install these first!):

OpenSSL
	OpenSSL (http://openssl.org) development headers and libraries
	are installed by default on *BSD and MacOS X.

	Solaris, HP-UX, AIX:	3rd party packages or source build
	Redhat/Fedora/CentOS:	yum install openssl-devel
	Debian/Ubuntu: 		apt-get install libssl-dev

libcurl
	The curl (http://curl.haxx.se) development headers and library
	are installed by default on MacOS X, and require OpenSSL.

	FreeBSD/NetBSD:		www/curl port or package
	Solaris, HP-UX, AIX	3rd party packages or source build
	Redhat/Fedora/CentOS:	yum install curl-devel
	Debian/Ubuntu:		apt-get install libcurl-dev 
				(use the openssl version)

Build dependencies for pam_duo:

libpam
	System PAM development headers and libraries are installed by
	default on FreeBSD, NetBSD, MacOS X, Solaris, HP-UX, and AIX.

	RedHat/Fedora/CentOS:	yum install pam-devel
	Debian/Ubuntu:		apt-get install libpam-dev

Options to ./configure:

--with-libcurl=DIR
	Specify location of libcurl build or install directory
	(e.g. "/usr/local", "/opt/csw"), if not installed in a system
	location (e.g. /usr/lib).

--with-pam[=DIR]
	Build PAM module, and optionally override the default install
	directory (determined automatically by platform) if necessary.

--with-privsep-user=USER
	Specify a different user for privilege separation (e.g. "_duo")
	in login_duo - by default, "sshd" (or "_sshd" on MacOS X).

The default path for local configuration files will be set to /etc/duo
(which can be changed by specifying --sysconfdir=DIR).

NOTE: If you're missing ./configure you accidentally downloaded the
git source tree tarball. Get a versioned package tarball instead:

	https://github.com/duosecurity/duo_unix/downloads

Then just run "make".

Install
-------

"make install" as root should do it.

login_duo will be installed setuid root by default in order to keep
the Duo integration and secret keys in your configuration files
secret. It may also be installed non-setuid manually for a user
installation with individual (vs. system-wide) configuration files.

The pam_duo module will be installed in the system PAM module location
by default (/lib/security, /usr/lib/security, /usr/lib/pam, /usr/lib
depending on platform).

Setup
-----

If you don't have a Duo account, sign up at http://www.duosecurity.com
and log into your admin account at https://admin-eval.duosecurity.com

From your admin account, add a new Unix integration (Integrations >
New integration) and use the integration key (ikey), secret key 
(skey), and API hostname in your Duo configuration files (by default
in /etc/duo).

You do not need to create any user accounts manually - new Duo users
will be created as each user logs in and enrolls their own device.

Test
----

To test your Duo configuration, run login_duo from the command line as
your target user - for the default setuid-root install:

	$ login_duo echo YOU ROCK

For a non-setuid install:

	$ ./login_duo -c login_duo.conf echo YOU ROCK

If your Duo integration and secret keys are valid, you will be able to
enroll and authenticate successfully, and congratulate yourself. :-)

Usage
-----

See README.pam, README.ssh, and the login_duo.8 and pam_duo.8 manpages
for additional options.

To build C applications with libduo, use "pkg-config libduo" with
--cflags and --libs arguments to locate the development headers and
library. See the duo.3 manpage for API documentation.

Support
-------

Additional duo_unix documentation is available here:

	http://www.duosecurity.com/docs/duounix

Join our mailing list for technical discussion of duo_unix:

	http://groups.google.com/group/duo_unix

Report any bugs, feature requests, etc. to us directly:

	https://github.com/duosecurity/duo_unix/issues

Have fun!

---
http://www.duosecurity.com