libpam-yubico for Debian
------------------------


Online validation
-----------------

The default way to use this PAM module is to validate YubiKey OTPs
using the free online validation service, the YubiCloud. If this
PAM module is enabled together with for example pam_unix, you can
get two-factor (2FA) authentication with your YubiKey as one factor
and your UNIX password as the second factor.

To use the YubiCloud securely, you should get an API key and enter
that at the package configuration prompt. To change the configuration
after initial install, use `dpkg-reconfigure libpam-yubico'.

To get an API key, visit https://upgrade.yubico.com/getapikey/

  (don't worry, it's free).

If you want to use some other online validation service than the
YubiCloud, you can. All the software for the YubiCloud is available
as open source. See the Developer section at http://yubico.com/.


Offline validation
------------------

YubiKeys can be programmed for HMAC-SHA-1 Challenge-Response, and
this PAM module can use that to provide offline authentication
requiring a YubiKey. See /usr/share/doc/libpam-yubico/README.gz
for more information about how to configure that (search for
"challenge-response").


Example and debugging
---------------------

While you generally should use `dpkg-reconfigure libpam-yubico' to
change the configuration for this PAM module, this is an example PAM
stack configuration for two-factor authentication using YubiKey and
your UNIX password (note that debugging is enabled with `debug') :

  # here are the per-package modules (the "Primary" block)
  auth   required                    pam_yubico.so   debug id=4711 key=pJMccccc05pJMccccT05=
  auth   [success=1 default=ignore]  pam_unix.so     nullok_secure try_first_pass
  # here's the fallback if no module succeeds
  auth	 requisite    	    pam_deny.so


To see the debug output, do the following :

  $ sudo touch /var/run/pam-debug.log
  $ sudo chmod 666 /var/run/pam-debug.log
  $ sudo tail -F /var/run/pam-debug.log

There is more documentation online in the Yubico-PAM wiki at

  https://github.com/Yubico/yubico-pam/wiki/

but it might be for a more recent version of the Yubico PAM module
than the one you are using.


Other
-----

See the file /usr/share/doc/libpam-yubico/README.gz to learn about
what else can be configured for the Yubico PAM module.


Fredrik Thulin <fredrik@yubico.com>, Tue Dec 13 13:32:59 CET 2011
