https://github.com/Yubico/pam-u2f

Pluggable Authentication Module (PAM) for U2F and FIDO2
https://github.com/Yubico/pam-u2f

fido2 pam-module u2f yubikey

Last synced: 2 months ago
JSON representation

Pluggable Authentication Module (PAM) for U2F and FIDO2

• Host: GitHub
• URL: https://github.com/Yubico/pam-u2f
• Owner: Yubico
• License: bsd-2-clause
• Created: 2014-12-10T17:12:52.000Z (almost 10 years ago)
• Default Branch: main
• Last Pushed: 2024-05-19T21:47:54.000Z (5 months ago)
• Last Synced: 2024-06-15T05:37:08.278Z (4 months ago)
• Topics: fido2, pam-module, u2f, yubikey
• Language: C
• Homepage: https://developers.yubico.com/pam-u2f/
• Size: 649 KB
• Stars: 523
• Watchers: 54
• Forks: 75
• Open Issues: 14
• Metadata Files:
  • Readme: README
  • License: COPYING
  • Security: SECURITY.md
  • Authors: AUTHORS

Awesome Lists containing this project

README

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

image:https://github.com/yubico/pam-u2f/workflows/linux/badge.svg["Linux Build Status (github actions)", link="https://github.com/Yubico/pam-u2f/actions"]

image:https://github.com/yubico/pam-u2f/workflows/macos/badge.svg["macOS Build Status (github actions)", link="https://github.com/Yubico/pam-u2f/actions"]

image:https://github.com/yubico/pam-u2f/workflows/fuzzer/badge.svg["Fuzz Status (github actions)", link="https://github.com/Yubico/pam-u2f/actions"]

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.

[[building]]

== Building

You may get signed release tarballs from Yubico's

https://developers.yubico.com/pam-u2f/Releases[release page].

This project uses 'autoconf', 'automake', 'pkg-config' and 'libtool'

to achieve portability and ease of use.

In addition, https://developers.yubico.com/libfido2['libfido2'] (>=

1.3.0) is needed. Versions of this project up to 1.0.8 used

`libu2f-host` and `libu2f-server`. On Ubuntu, the necessary dependencies can be

installed using

[source, console]

----

# apt install --no-install-recommends autoconf automake libtool pkg-config \

    libfido2-dev libpam-dev libssl-dev

----

If you downloaded a tarball, build it as follows.

[source, console]

----

$ ./configure

$ make

----

== Building from Git

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

[source, console]

----

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

----

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

[source, console]

----

$ cd pam-u2f

----

`autoconf`, `automake`, `libtool`, and `libpam` must be installed.

`AsciiDoc` and `xsltproc` are used to generate the manpages. On Ubuntu,

the necessary dependencies can be installed using

[source, console]

----

# apt install --no-install-recommends autoconf automake libtool \

    pkg-config libfido2-dev libpam-dev libssl-dev asciidoc xsltproc \

    libxml2-utils docbook-xml

----

On Fedora, the necessary dependencies can be installed using

[source, console]

----

# dnf -y install autoconf automake libtool libfido2-devel pam-devel \

    openssl-devel asciidoc

----

Generate the build system using:

[source, console]

----

$ autoreconf --install

----

Then build as usual, see above under <>.

== 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=`.

== Service Configuration

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

----

For more information about the syntax of PAM configuration files, please

see the manual page for pam.conf(5). Additional <> can be found below.

IMPORTANT: An erroneous PAM configuration may lock some or all users

out of the system or prevent you from gaining root privileges. It is

recommended that you start a separate shell with root privileges while

configuring PAM to be able to revert changes if something goes wrong.

Test your configuration thoroughly before closing the root shell.

=== Module Arguments

[horizontal]

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 relying party ID for the FIDO authentication procedure. If no

value is specified, the identifier "pam://$HOSTNAME" is used.

appid=appid::

Set the https://developers.yubico.com/U2F/App_ID.html[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). This setting is only applicable for U2F credentials

created with pamu2fcfg versions v1.0.8 or earlier. Note that on v1.1.0

and v1.1.1 of pam-u2f, handling of this setting was temporarily broken

if the value was not the same as the value of origin.

authfile=file::

Set the location of the <>. An <> may be configured relative to the users' home dirs, e.g.

".ssh/u2f_keys". If not specified, the location defaults to

$XDG_CONFIG_HOME/Yubico/u2f_keys. If $XDG_CONFIG_HOME is not set,

$HOME/.config/Yubico/u2f_keys is used.

expand::

Enables variable expansion within the authfile path: `%u` is expanded to the

local user name (`PAM_USER`) and `%%` is expanded to `%`. Unknown expansion

sequences result in an authentication error. See also `openasuser`.

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].

Note that yubikey-touch-detector v1.5.1 and later no longer rely on the

authpending file for its detection mechanism. 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 (path is absolute) 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 (credentials) allowed per user (default is 24).

Devices specified in the authorization mapping 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 `libu2f-host` 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.

userpresence=int::

If 1, request user presence during authentication. If 0, do not

request user presence during authentication. If omitted, fallback to

the authenticator's default behaviour.

userverification=int::

If 1, request user verification during authentication (e.g. biometrics).

If 0, do not request user verification during authentication. If omitted,

fallback to the authenticator's default behaviour. If enabled, an

authenticator with support for FIDO2 user verification is required.

pinverification=int::

If 1, request PIN verification during authentication. If 0, do not

request PIN verification during authentication. If omitted, fallback to

the authenticator's default behaviour. If enabled, an authenticator

with support for a FIDO2 PIN is required.

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.

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.

[[examples]]

=== Example Service Configurations

==== Second Factor Authentication

Configure pam-u2f as a `required` module after your primary authentication

module(s) for use as a second factor. Make sure that the primary authentication

method is not `sufficient` or uses other control values that may preempt

execution of pam-u2f.

----

# Primary authentication method(s) above this line.

auth required pam_u2f.so authfile=/etc/u2f_mappings cue

----

==== Passwordless Authentication

For a passwordless experience, where the authenticator PIN can be used in place

of the user password, you can insert the below line towards the top of your

service configuration. You may need to change the control value to something

else if you'd like to execute additional authentication modules after pam-u2f.

----

auth sufficient pam_u2f.so authfile=/etc/u2f_mappings cue pinverification=1

# Fallback modules go below this line (e.g. password authentication).

----

==== Passwordless Authentication using Biometrics

Similar to the previous configuration but capable of built-in user

verification, e.g. fingerprint matching using the YubiKey Bio. This example

falls back to using PIN verification if the fingerprint does not match or is

otherwise blocked.

----

auth sufficient pam_u2f.so authfile=/etc/u2f_mappings cue pinverification=0 userverification=1

auth sufficient pam_u2f.so authfile=/etc/u2f_mappings cue pinverification=1 userverification=0

# More fallback modules go below this line (e.g. password authentication).

----

[[authMappingFiles]]

== Authorization Mapping Files

A mapping must be made between the YubiKey token and the user name,

see <> 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, and the information obtained during the registration procedure.

The mappings should look like this, one per line:

 :,,,:,,,:...

 :,,,:,,,:...

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.

[[individualAuth]]

=== Individual Authorization Mapping by User

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:

 :,,,:,,,:...

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:

[source, console]

----

$ 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`. 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`).

For authenticator management (e.g. setting a PIN, enrolling fingerprints, and

more), please refer to

https://developers.yubico.com/libfido2/Manuals/fido2-token.html[`fido2-token`],

https://developers.yubico.com/yubikey-manager[`yubikey-manager`], or some other

suitable tool.

=== SSH Credentials

To generate SSH credentials OpenSSH version 8.2 or later is required.

It is then possible to generate a credential file with:

[source, console]

----

$ ssh-keygen -t ecdsa-sk -f ./credential.ssh

----

Supported key types are ecdsa-sk and ed25519-sk. Note 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` and the `sshformat` option should also be set. If the

`authfile` parameter is not set, it defaults to `~/.ssh/id_ecdsa_sk`.

=== Multiple Devices

Multiple devices (credentials) are supported. If more than one credential is

specified, authentication against them is attempted sequentially as they are

defined in the authorization mapping file. 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.

== SELinux Note

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

[source, console]

----

# chcon -R -t auth_home_t /path/to/target

----

should be used.

For more information see

https://access.redhat.com/security/cve/CVE-2020-24612[HERE].

== FIDO U2F vs FIDO2

Devices that solely support FIDO U2F and not FIDO2, e.g. the YubiKey 4 series,

can be used only in conjunction with compatible features. Enabling incompatible

features, such as setting the `+pin` or the `+verification` flags in the

`authfile` or the corresponding options in the PAM service configuration causes

the device to be ignored.