NAME¶
pam_u2f - Module for U2F authentication
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
/usr/local/etc/security/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.
