Pluggable Authentication Module (PAM) Universal 2nd Factor (U2F)
================================================================

image:https://travis-ci.org/Yubico/pam-u2f.svg?branch=master["Build Status", link="https://travis-ci.org/Yubico/pam-u2f"]
image:https://scan.coverity.com/projects/5711/badge.svg["Coverity Status", link=https://scan.coverity.com/projects/5711]

This module implements PAM over U2F, providing an easy way to integrate the
YubiKey (or other U2F compliant authenticators) into your existing
infrastructure.

[[building]]
Building
--------

This project uses 'autoconf', 'automake', 'pkg-config' and 'libtool'
to achieve portability and ease of use. 

In addition, both the Yubico U2F https://developers.yubico.com/libu2f-host['libu2f-host-dev'] and
https://developers.yubico.com/libu2f-server['libu2f-server-dev'] libaries are needed.

  Debian:   apt-get install autoconf automake libtool pkg-config libu2f-host-dev libu2f-server-dev --no-install-recommends

If you downloaded a tarball, build it as follows.

-----------
  $ ./configure
  $ make
-----------

Building from Git
-----------------

You may check out the sources using Git with the following command:

-----------
  $ git clone git://github.com/Yubico/pam-u2f.git
-----------

This will create a directory 'pam-u2f'. Enter the directory:

-----------
  $ cd pam-u2f
-----------

'Autoconf', 'automake', 'libtool', and 'libpam' must be installed. 'AsciiDoc' and 'xsltproc' are used to
generate the manpages.

  Debian:   apt-get install autoconf automake libtool libpam-dev libu2f-host-dev libu2f-server-dev asciidoc xsltproc libxml2-utils docbook-xml --no-install-recommends

Generate the build system using:

-----------
  $ autoreconf --install
-----------

Then build as usual, see above under <<building,Building>>.

Installation
------------

Once the module is built copy the file +pam_u2f.so+ to the correct
directory for your system. Typically +/lib/security/+ or
+/lib/x86_64-linux-gnu/security/+. This is automated by +make install+
assuming that the pam directory chosen by +configure+ is correct.
If that is not the case it can be specified with +./configure --with-pam-dir=+.

Create a file for a new service in +/etc/pam.d/+ or edit an already
existing one by adding a line similar to this:

----
auth sufficient pam_u2f.so debug
----

Supported parameters for the module are:

[horizontal]
debug::
Enables debug output

debug_file::
Filename to write debug to, file must exist and be a regular file, or may be one of "stderr", "stdout", or "syslog". STDERR is the default.

origin=origin::
Set the origin for the U2F authentication procedure.
If no value is specified, the origin "pam://$HOSTNAME" is used.

appid=appid::
Set the https://developers.yubico.com/U2F/App_ID.html[application ID] for the U2F authentication procedure.
If no value is specified, the same value used for origin is taken
("pam://$HOSTNAME" if also origin is not specified).

authfile=file::
Set the location of the file that holds the mappings of user names
to keyHandles and user keys.  The format is
+username:first_keyHandle,first_public_key:
second_keyHandle,second_public_key:...+ the default location of the
file is $XDG_CONFIG_HOME/Yubico/u2f_keys. If the environment variable
is not set, $HOME/.config/Yubico/u2f_keys is used.
(more on <<files,Authorization Mapping Files>>).

authpending_file=file::
Set the location of the file that is used for touch request notifications.
This file will be opened when pam-u2f starts waiting for a user to touch the device,
and will be closed when it no longer waits for a touch.
Use inotify to listen on these events, or a more high-level tool like https://github.com/maximbaz/yubikey-touch-detector[yubikey-touch-detector].
Set an empty value in order to disable this functionality, like so: `authpending_file=`.
Default value: /var/run/user/$UID/pam-u2f-authpending

nouserok::
Set to enable authentication attempts to succeed even if the user trying to
authenticate is not found inside authfile or if authfile is missing/malformed.

openasuser::
Setuid to the authenticating user when opening the authfile. Useful when the
user's home is stored on an NFS volume mounted with the root_squash option
(which maps root to nobody which will not be able to read the file).
Note that after release 1.0.8 this is done by default when no global
authfile or XDG_CONFIG_HOME environment variable has been set.

alwaysok::
Set to enable all authentication attempts to succeed (aka presentation mode).

max_devices=n_devices::
Maximum number of devices allowed per user (default is 24). Devices specified
in the authentication file that exceed this value will be ignored.

interactive::
Set to prompt a message and wait before testing the presence of a U2F device.
Recommended if your device doesn't have a tactile trigger.

[prompt=your prompt here]::
Set individual prompt message for interactive mode. Watch the square brackets
around this parameter to get spaces correctly recognized by PAM.

manual::
Set to drop to a manual console where challenges are printed on screen
and response read from standard input. Useful for debugging and SSH sessions
without U2F-support from the SSH client/server.
If enabled, interactive mode becomes redundant and has no effect.

cue::
Set to prompt a message to remind to touch the device.

nodetect::
Set to skip detecting if a suitable U2F token is inserted before performing
the full tactile authentication. This detection was created to avoid
emitting the "cue" message if no suitable token exists, because doing so
leaks information about the authentication stack if a token is inserted but
not configured for the authenticating user. However, it was found that
versions of libu2f-user 1.1.5 or less has buggy iteration/sleep behavior
which causes a 1-second delay to occur for this initial detection. For this
reason, as well as the possibility of hypothetical tokens that do not
tolerate this double authentication, the "nodetect" option was added.

[[files]]
Authorization Mapping Files
---------------------------
A mapping must be made between the YubiKey token and the user name,
see <<registration, here>> for details on how to perform the registration
using the bundled tool.

There are two ways to do this, either centrally in one file, or
individually, where users can create the mapping in their home directories.
If the central authorization mapping file is being used, user home directory
mappings will not be used and the opposite applies if user home directory
mappings are being used, the central authorization mappings file will not
be used.

By default the mapping file inside a home directory will be opened as
the target user, whereas the central file will be opened as `root`. If
the `XDG_CONFIG_HOME` variable is set, privileges will not be dropped
unless the `openasuser` configuration setting is set.

IMPORTANT: Using pam-u2f to secure the login to a computer while
storing the mapping file in an encrypted home directory, will result
in the impossibility of logging into the system. The partition is
decrypted after login and the mapping file can not be accessed.

== Central authorization mapping
Create a file e.g. `/etc/u2f_mappings`., The file must contain
a user name, the number of registered Yubikeys and the information
obtained during the registration procedure.

The mappings should look like this, one per line:

 <username1>:<KeyHandle1>,<UserKey1>:<KeyHandle2>,<UserKey2>:...
 <username2>:<KeyHandle1>,<UserKey1>:<KeyHandle2>,<UserKey2>:...

Now add `authfile=/etc/u2f_mappings` to your PAM configuration line, so it
looks like:

 auth sufficient pam_u2f.so authfile=/etc/u2f_mappings

If you do not set the `openasuser` setting, the authfile will be opened
and parsed as `root` so make sure it has the correct owner and
permissions set.

IMPORTANT: On dynamics networks (e.g. where hostnames are set by DHCP),
users should not rely on the default origin and appid ("pam://$HOSTNAME")
but set those parameters explicitly to the same value.

== Individual authorization mapping by user
Each user creates a `~/.config/Yubico/u2f_keys` file inside of their home
directory and places the mapping in that file, the file must have only one
line:

 <username>:<KeyHandle1>,<UserKey1>:<KeyHandle2>,<UserKey2>:...

This is much the same concept as the SSH authorized_keys file.

In this case, pam-u2f will drop privileges and read the mapping file
as that user. This happens regardless of the `openasuser` option being
set.

Note that if you set the XDG_CONFIG_HOME variable, privileges will not
be dropped by default. Consider also setting `openasuser` in that case.

[[registration]]
Obtaining key-handles and public keys
-------------------------------------

In order to obtain the required information for the authentication procedure,
a token should be first registered. This can be done by using the command line
configuration tool provided with the module:

----
$ pamu2fcfg -uusername -opam://myorigin -ipam://myappid
----

the tool will register a connected token by using the specified origin and
appid. If neither are specified they will default to +pam://$HOSTNAME+.
During the U2F registration, the user is required to touch the token.
On success the tool prints to standard output a configuration line that
can be directly used with the module. For additional information on the
tool read the relative manpage (+man pamu2fcfg+)

[[devices]]
Multiple Devices
----------------

Multiple devices are supported. If more than one device is specified,
authentication against them is attempted sequentially as they are defined
in the configuration file of the module. If during an authentication
attempt a connected device is removed or a new device is plugged in,
the authentication restarts from the top of the list.
