Skip to content

txx/pam-u2f

 
 

Repository files navigation

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

Build Status Coverity Status

The PAM U2F module provides an easy way to integrate the Yubikey (or other U2F-compliant authenticators) into your existing user authentication infrastructure. PAM is used by GNU/Linux, Solaris and Mac OS X for user authentication.

Introduction

This module implements PAM authentication over U2F. Registration should be performed using the included tool. Multiple devices are supported, for details check the Multiple Devices section.

For more information visit the project page pam-u2f project.

License

The project is licensed under a BSD license. See the file COPYING for exact wording. For any copyright year range specified as YYYY-ZZZZ in this package note that the range specifies every single year in that closed interval.

Building

This project uses autoconf, automake, pkg-config and libtool to achieve portability and ease of use. If you downloaded a tarball, build it as follows.

  $ ./configure
  $ make check

Both the Yubico U2F host and server libaries are needed libu2f-host, libu2f-server

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 asciidoc xsltproc libxml2-utils docbook-xml --no-install-recommends

Generate the build system using:

  $ autoreconf --install

Then build as usual, see above under 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:

debug

Turns on debugging to STDOUT

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 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 Authorization Mapping Files).

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.

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.

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.

Authorization Mapping Files

A mapping must be made between the YubiKey token and the user name. 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.

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

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.

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)

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.

Portability

The main development platforms are Debian GNU/Linux and Ubuntu and they should be well supported.

About

Pluggable Authentication Module (PAM) for U2F

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • M4 48.5%
  • C 48.2%
  • Makefile 2.6%
  • Shell 0.7%