PAM_U2F(8)
==========
:doctype:      manpage
:man source:   pam-u2f
:man manual:   PAM U2F Module Manual

== NAME
pam_u2f - Module for U2F authentication

== SYNOPSIS
*pam_u2f* [...]

== DESCRIPTION
The module provides U2F authentication against Yubikeys and other
compliant authenticators.

== OPTIONS
*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 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 FIDO 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 file that holds the mappings of user
names to keyHandles and user keys. An individual (per user)
file 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. The authfile format is
<username>:<KeyHandle1>,<UserKey1>,<CoseType1>,<Options1>:<KeyHandle2>,<UserKey2>,<CoseType2>,<Options2>:...

*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 FIDO
authenticator, 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.
Default value: /var/run/user/$UID/pam-u2f-authpending.
Set an empty value in order to disable this functionality, like so:
"authpending_file=".

*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 FIDO authenticators allowed per user (default is 24).
FIDO authenticators 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
authenticator. Recommended if your authenticator doesn't have 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 FIDO 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 FIDO authenticator.

*[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*::
Skip detecting if a suitable FIDO authenticator is inserted before performing a
full authentication. See *NOTES* below.

*userpresence*=_int_::
If 1, require 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, require 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, require 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 authenticator. It is not possible to mix native credentials and SSH
credentials. Once this option is enabled all credentials will be parsed
as SSH.

*conf*=_path/to/pam_u2f.conf_::
Set an alternative location for the configuration file.
The supplied path must be absolute and must correspond to an existing
regular file.
See *CONFIGURATION FILE*.

== EXAMPLES

Second factor authentication deferring user verification configuration to the
authorization mapping file.

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

Passwordless authentication enforcing PIN verification.

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

Passwordless authentication using built-in UV (e.g. biometrics) with a fallback
to PIN.

  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

== CAVEATS
By default, relative paths to the authfile will be opened as the
target user, whereas absolute paths 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.

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.

== CONFIGURATION FILE

A configuration file can be used to set the default module arguments.

- The file has a `name = value` format, with comments starting with the `#`
  character.

- White spaces at the beginning of line, end of line, and around the `=` sign
  are ignored.

- Any `conf` argument in the configuration file is ignored.

- The maximum size for the configuration file is 4 KiB.

- The default path for the configuration file is +{sconfdir}/pam_u2f.conf+.
  The default file is allowed to not exist. An alternative path may be set in
  the module command line options.

- The options specified on the module command line override the values from the
  configuration file.

== NOTES

*Nodetect*

The "nodetect" option should be used with caution. pam_u2f checks that
a key configured for the user is inserted before performing the full
tactile authentication. This detection is done by sending a
"check-only" authentication request to all inserted tokens to so see
if at least one of them responds affirmatively to one or more of the
keyhandles configured for the user. By doing this, pam_u2f can avoid
emitting the "cue" prompt (if configured), which can cause some
confusing UI issues if the cue is emitted followed by the underlying
library immediately failing the tactile authentication. This option is
also useful to avoid an unintended 1-second delay prior to the tactile
authentication caused by versions of libu2f-host \<= 1.1.5.

If pam_u2f is configured to "cue" and "nodetect", an attacker can
determine that pam_u2f is part of the authentication stack by
inserting any random U2F token and performing an authentication
attempt. In this scenario, the attacker would see the cue message
followed by an immediate failure, whereas with detection enabled, the
authentication will fail silently. Understand that an attacker
could choose an authenticator that alerts him or her in some way to the
"check-only" authentication attempt, so this precaution only pushes
the issue back a step.

In summary, the detection feature was added to avoid confusing UI
issues and to prevent leaking information about the authentication
stack in very specific scenario when "cue" is configured. The
"nodetect" option was added to avoid buggy sleep behavior in older
versions of libu2f-host and for hypothetical tokens that do not
tolerate the double authentication. Detection is performed, and
likewise "nodetect" honored, regardless of whether "cue" is also
specified.

*SELinux*

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/authfile

should be used.

For more information see
https://access.redhat.com/security/cve/CVE-2020-24612.

== BUGS
Report pam-u2f bugs in the issue tracker: https://github.com/Yubico/pam-u2f/issues

== SEE ALSO
*pam*(7)

The pam-u2f home page: https://developers.yubico.com/pam-u2f/

YubiKeys can be obtained from Yubico: http://www.yubico.com/
