Overview
--------

duo_unix - Duo two-factor authentication for Unix systems

Duo provides simple two-factor authentication as a service.

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 (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
	SUSE/SLES:		zypper install libopenssl-devel

libpam
	Only required if building with PAM support (--with-pam below).

	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
	SUSE/SLES:		zypper install pam-devel

zlib
	When compiling for SLES 11, it is reported that you need the
	zlib package during compilation.

	SUSE/SLES:		zypper install zlib-devel

Options to ./configure:

--with-openssl=DIR
        Specify the OpenSSL directory if not found automatically.

--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 login_duo privilege separation -
        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. Grab the latest tarball instead:

	https://dl.duosecurity.com/duo_unix-latest.tar.gz

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

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 -d echo YOU ROCK

For a non-setuid install:

	$ ./login_duo -d -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. :-)

Setuid
------

The login_duo binary is marked setuid in order to read the protected
login_duo.conf configuration file. However, privileges are dropped
immediately after so the privileged attack surface is minimal.

Proxy Support
------
Both login_duo and pam_duo (since duo_unix version 1.7) have experimental
support for the standard "http_proxy" environment variable (honored by
wget, curl, etc.).

You can have this set by adding the http_proxy variable to your login_duo.conf
file, in the following format:

http_proxy=http://username:password@proxy.example.org:8080


Support
-------

Additional duo_unix documentation is available here:

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

Report any bugs, feature requests, etc. here:

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

Have fun!

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