This module implements PAM over U2F and FIDO2, providing an easy way to integrate the YubiKey (or other U2F/FIDO2 compliant authenticators) into your existing infrastructure.
This project uses autoconf, automake, pkg-config and libtool to achieve portability and ease of use.
In addition, libfido2 (>=
1.2.0) is needed. Versions of this project up to 1.0.8 used
libu2f-host and libu2f-server.
Ubuntu: apt install autoconf automake libtool pkg-config libfido2-dev --no-install-recommends
If you downloaded a tarball, build it as follows.
$ ./configure
$ makeYou may check out the sources using Git with the following command:
$ git clone git://github.com/Yubico/pam-u2f.gitThis will create a directory pam-u2f. Enter the directory:
$ cd pam-u2fautoconf, automake, libtool, and libpam must be installed.
AsciiDoc and xsltproc are used to generate the manpages.
Ubuntu: apt install autoconf automake libtool libpam-dev libfido2-dev asciidoc xsltproc libxml2-utils docbook-xml --no-install-recommends
Generate the build system using:
$ autoreconf --installThen build as usual, see above under Building.
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 |
Enables debug output |
| debug_file |
Filename to write debugging messages to. If this file is missing, nothing will be logged. This regular file has to be created by the user or must exist and be a regular file for anything getting logged to it. It is not created by pam-u2f on purpose (for security considerations). This filename may be alternatively set to "stderr" (default), "stdout", or "syslog". |
| origin=origin |
Set the origin for the FIDO authentication procedure. If no value is specified, the origin "pam://$HOSTNAME" is used. |
| appid=appid |
Set the application ID for the FIDO 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
|
| 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
yubikey-touch-detector.
Set an empty value in order to disable this functionality, like so:
|
| nouserok |
Set to enable authentication attempts to succeed even if the user
trying to authenticate is not found inside |
| 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
|
| 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 FIDO 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. |
| [cue_prompt=your prompt here] |
Set individual prompt message for the cue option. Watch the square brackets around this parameter to get spaces correctly recognized by PAM. |
| nodetect |
Set to skip detecting if a suitable FIDO 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 |
| userpresence=int |
If 1, request user presence during authentication. If 0, do not request user presence during authentication. Otherwise, fallback to the authenticator’s default behaviour. |
| userverification=int |
If 1, request user verification during authentication. If 0, do not request user verification during authentication. Otherwise, fallback to the authenticator’s default behaviour. |
| pinverification=int |
If 1, request PIN verification during authentication. If 0, do not request PIN verification during authentication. Otherwise, fallback to the authenticator’s default behaviour. |
| sshformat |
Use credentials produced by versions of OpenSSH that have support for FIDO devices. It is not possible to mix native credentials and SSH credentials. Once this option is enabled all credentials will be parsed as SSH. |
A mapping must be made between the YubiKey token and the user name, see 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. |
Create a file e.g. /etc/u2f_mappings. The file must contain a user
name, and the information obtained during the registration procedure.
The mappings should look like this, one per line:
<username1>:<KeyHandle1>,<UserKey1>,<Options1>:<KeyHandle2>,<UserKey2>,<Options2>:... <username2>:<KeyHandle1>,<UserKey1>,<Options1>:<KeyHandle2>,<UserKey2>,<Options2>:...
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 dynamic 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. |
Each user creates a .config/Yubico/u2f_keys (default) file inside
their home directory and places the mapping in that file. You may want
to specify a different per-user file (relative to the users' home
directory), i.e. .ssh/u2f_keys. Bear in mind, setting an absolute path
here is possible although very likely a fragile setup, and probably
not exhibiting the intended behaviour.
The file must have only one line:
<username>:<KeyHandle1>,<UserKey1>,<Options1>:<KeyHandle2>,<UserKey2>,<Options2>:...
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.
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://myappidthe tool will register a connected token by using the specified origin
and appid. If neither are specified they will default to
pam://$HOSTNAME. Additionally, it is possible to set other options
to require user presence (touch), PIN verification and resident
credentials. 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).
To generate SSH credentials OpenSSH version 8.2 or later is required. It is then possible to generate a credential file with:
$ ssh-keygen -t ecdsa-sk -f ./credential.sshNote that passphrase protected credentials are currently not supported.
To use this credential the authfile parameter should be set to the
path of the file credential.ssh (or use the default id_ecdsa_sk
name and location) and the sshformat option should be set.
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.
Due to an issue with Fedora Linux, and possibly with other
distributions that use SELinux, a system configured with pam-u2f may
end up in a situation where access to the credentials file is denied.
If the nouserok option is also set, this will result in a successful
authentication within the module, without using the FIDO
authenticator.
In order to correctly update the security context the command
fixfiles onboot should be used on existing installations
Moreover, to allow read access to an authfile or directory placed in a non-standard location, the command
# chcon -R -t auth_home_t /path/to/targetshould be used.
For more information see HERE.