pam_u2f(8)

1PAM_U2F(8)                   PAM U2F Module Manual                  PAM_U2F(8)
2
3
4

NAME

6       pam_u2f - Module for U2F authentication
7

SYNOPSIS

9       pam_u2f [...]
10

DESCRIPTION

12       The module provides U2F authentication against Yubikeys and other
13       compliant authenticators.
14

OPTIONS

16       debug
17           Enables debug output
18
19       debug_file
20           Filename to write debugging messages to.  If this file is missing,
21           nothing will be logged. This regular file has to be created by the
22           user or must exist and be a regular file for anything getting
23           logged to it. It is not created by pam-u2f on purpose (for security
24           considerations). This filename may be alternatively set to "stderr"
25           (default), "stdout", or "syslog".
26
27       origin=origin
28           Set the relying party ID for the FIDO authentication procedure. If
29           no value is specified, the identifier "pam://$HOSTNAME" is used.
30
31       appid=appid
32           Set the application ID for the U2F authentication procedure. If no
33           value is specified, the same value used for origin is taken
34           ("pam://$HOSTNAME" if also origin is not specified). This setting
35           is only applicable for U2F credentials created with pamu2fcfg
36           versions v1.0.8 or earlier. Note that on v1.1.0 and v1.1.1 of
37           pam-u2f, handling of this setting was temporarily broken if the
38           value was not the same as the value of origin.
39
40       authfile=file
41           Set the location of the file that holds the mappings of user names
42           to keyHandles and user keys. An individual (per user) file may be
43           configured relative to the users' home dirs, e.g. ".ssh/u2f_keys".
44           If not specified, the location defaults to
45           $XDG_CONFIG_HOME/Yubico/u2f_keys. If $XDG_CONFIG_HOME is not set,
46           $HOME/.config/Yubico/u2f_keys is used. The authfile format is
47           <username>:<KeyHandle1>,<UserKey1>,<CoseType1>,<Options1>:<KeyHandle2>,<UserKey2>,<CoseType2>,<Options2>:...
48
49       authpending_file=file
50           Set the location of the file that is used for touch request
51           notifications. This file will be opened when pam-u2f starts waiting
52           for a user to touch the device, and will be closed when it no
53           longer waits for a touch. Use inotify to listen on these events, or
54           a more high-level tool like yubikey-touch-detector. Default value:
55           /var/run/user/$UID/pam-u2f-authpending. Set an empty value in order
56           to disable this functionality, like so: "authpending_file=".
57
58       nouserok
59           Set to enable authentication attempts to succeed even if the user
60           trying to authenticate is not found inside authfile or if authfile
61           is missing/malformed.
62
63       openasuser
64           Setuid to the authenticating user when opening the authfile. Useful
65           when the user’s home is stored on an NFS volume mounted with the
66           root_squash option (which maps root to nobody which will not be
67           able to read the file). Note that after release 1.0.8 this is done
68           by default when no global authfile or XDG_CONFIG_HOME environment
69           variable has been set.
70
71       alwaysok
72           Set to enable all authentication attempts to succeed (aka
73           presentation mode).
74
75       max_devices=n_devices
76           Maximum number of devices allowed per user (default is 24). Devices
77           specified in the authentication file that exceed this value will be
78           ignored.
79
80       interactive
81           Set to prompt a message and wait before testing the presence of a
82           U2F device. Recommended if your device doesn’t have tactile
83           trigger.
84
85       [prompt=your prompt here]
86           Set individual prompt message for interactive mode. Watch the
87           square brackets around this parameter to get spaces correctly
88           recognized by PAM.
89
90       manual
91           Set to drop to a manual console where challenges are printed on
92           screen and response read from standard input. Useful for debugging
93           and SSH sessions without U2F-support from the SSH client/server. If
94           enabled, interactive mode becomes redundant and has no effect.
95
96       cue
97           Set to prompt a message to remind to touch the device.
98
99       [cue_prompt=your prompt here]
100           Set individual prompt message for the cue option. Watch the square
101           brackets around this parameter to get spaces correctly recognized
102           by PAM.
103
104       nodetect
105           Skip detecting if a suitable key is inserted before performing a
106           full authentication. See NOTES below.
107
108       userpresence=int
109           If 1, require user presence during authentication. If 0, do not
110           request user presence during authentication. If omitted, fallback
111           to the authenticator’s default behaviour.
112
113       userverification=int
114           If 1, require user verification during authentication (e.g.
115           biometrics). If 0, do not request user verification during
116           authentication. If omitted, fallback to the authenticator’s default
117           behaviour. If enabled, an authenticator with support for FIDO2 user
118           verification is required.
119
120       pinverification=int
121           If 1, require PIN verification during authentication. If 0, do not
122           request PIN verification during authentication. If omitted,
123           fallback to the authenticator’s default behaviour. If enabled, an
124           authenticator with support for a FIDO2 PIN is required.
125
126       sshformat
127           Use credentials produced by versions of OpenSSH that have support
128           for FIDO devices. It is not possible to mix native credentials and
129           SSH credentials. Once this option is enabled all credentials will
130           be parsed as SSH.
131

EXAMPLES

133       auth sufficient pam_u2f.so debug origin=pam://$HOSTNAME
134       appid=pam://$HOSTNAME
135
136       auth required pam_u2f.so origin=http://example.com
137       appid=http://example.com authfile=/etc/yubikey_mappings
138

CAVEATS

140       By default the mapping file inside a home directory will be opened as
141       the target user, whereas the central file will be opened as "root". If
142       the "XDG_CONFIG_HOME" variable is set, privileges will not be dropped
143       unless the "openasuser" configuration setting is set.
144
145       Using pam-u2f to secure the login to a computer while storing the
146       mapping file in an encrypted home directory, will result in the
147       impossibility of logging into the system. The partition is decrypted
148       after login and the mapping file can not be accessed.
149

NOTES

151       Nodetect
152
153       The "nodetect" option should be used with caution. pam_u2f checks that
154       a key configured for the user is inserted before performing the full
155       tactile authentication. This detection is done by sending a
156       "check-only" authentication request to all inserted tokens to so see if
157       at least one of them responds affirmatively to one or more of the
158       keyhandles configured for the user. By doing this, pam_u2f can avoid
159       emitting the "cue" prompt (if configured), which can cause some
160       confusing UI issues if the cue is emitted followed by the underlying
161       library immediately failing the tactile authentication. This option is
162       also useful to avoid an unintended 1-second delay prior to the tactile
163       authentication caused by versions of libu2f-host <= 1.1.5.
164
165       If pam_u2f is configured to "cue" and "nodetect", an attacker can
166       determine that pam_u2f is part of the authentication stack by inserting
167       any random U2F token and performing an authentication attempt. In this
168       scenario, the attacker would see the cue message followed by an
169       immediate failure, whereas with detection enabled, the U2F
170       authentication will fail silently. Understand that an attacker could
171       choose a U2F token that alerts him or her in some way to the
172       "check-only" authentication attempt, so this precaution only pushes the
173       issue back a step.
174
175       In summary, the detection feature was added to avoid confusing UI
176       issues and to prevent leaking information about the authentication
177       stack in very specific scenario when "cue" is configured. The
178       "nodetect" option was added to avoid buggy sleep behavior in older
179       versions of libu2f-host and for hypothetical tokens that do not
180       tolerate the double authentication. Detection is performed, and
181       likewise "nodetect" honored, regardless of whether "cue" is also
182       specified.
183
184       SELinux
185
186       Due to an issue with Fedora Linux, and possibly with other
187       distributions that use SELinux, a system configured with pam-u2f may
188       end up in a situation where access to the credentials file is denied.
189       If the nouserok option is also set, this will result in a successful
190       authentication within the module, without using the FIDO authenticator.
191
192       In order to correctly update the security context the command fixfiles
193       onboot should be used on existing installations
194
195       Moreover, to allow read access to an authfile or directory placed in a
196       non-standard location, the command
197
198           # chcon -R -t auth_home_t /path/to/authfile
199
200       should be used.
201
202       For more information see
203       https://access.redhat.com/security/cve/CVE-2020-24612.
204

BUGS

206       Report pam-u2f bugs in the issue tracker:
207       https://github.com/Yubico/pam-u2f/issues
208