1PAM_U2F(8) PAM U2F Module Manual PAM_U2F(8)
2
6 pam_u2f - Module for U2F authentication
7
9 pam_u2f [...]
10
12 The module provides U2F authentication against Yubikeys and other
13 compliant authenticators.
14
16 debug
17 Enables debug output
18 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 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 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 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 expand
50 Enables variable expansion within the authfile path: %u is expanded
51 to the local user name (PAM_USER) and %% is expanded to %. Unknown
52 expansion sequences result in an authentication error. See also
53 openasuser.
54 authpending_file=file
56 Set the location of the file that is used for touch request
57 notifications. This file will be opened when pam-u2f starts waiting
58 for a user to touch the device, and will be closed when it no
59 longer waits for a touch. Use inotify to listen on these events, or
60 a more high-level tool like yubikey-touch-detector. Default value:
61 /var/run/user/$UID/pam-u2f-authpending. Set an empty value in order
62 to disable this functionality, like so: "authpending_file=".
63 nouserok
65 Set to enable authentication attempts to succeed even if the user
66 trying to authenticate is not found inside authfile or if authfile
67 is missing/malformed.
68 openasuser
70 Setuid to the authenticating user when opening the authfile. Useful
71 when the user’s home is stored on an NFS volume mounted with the
72 root_squash option (which maps root to nobody which will not be
73 able to read the file). Note that after release 1.0.8 this is done
74 by default when no global authfile (path is absolute) or
75 XDG_CONFIG_HOME environment variable has been set.
76 alwaysok
78 Set to enable all authentication attempts to succeed (aka
79 presentation mode).
80 max_devices=n_devices
82 Maximum number of devices (credentials) allowed per user (default
83 is 24). Devices specified in the authorization mapping file that
84 exceed this value will be ignored.
85 interactive
87 Set to prompt a message and wait before testing the presence of a
88 U2F device. Recommended if your device doesn’t have tactile
89 trigger.
90 [prompt=your prompt here]
92 Set individual prompt message for interactive mode. Watch the
93 square brackets around this parameter to get spaces correctly
94 recognized by PAM.
95 manual
97 Set to drop to a manual console where challenges are printed on
98 screen and response read from standard input. Useful for debugging
99 and SSH sessions without U2F-support from the SSH client/server. If
100 enabled, interactive mode becomes redundant and has no effect.
101 cue
103 Set to prompt a message to remind to touch the device.
104 [cue_prompt=your prompt here]
106 Set individual prompt message for the cue option. Watch the square
107 brackets around this parameter to get spaces correctly recognized
108 by PAM.
109 nodetect
111 Skip detecting if a suitable key is inserted before performing a
112 full authentication. See NOTES below.
113 userpresence=int
115 If 1, require user presence during authentication. If 0, do not
116 request user presence during authentication. If omitted, fallback
117 to the authenticator’s default behaviour.
118 userverification=int
120 If 1, require user verification during authentication (e.g.
121 biometrics). If 0, do not request user verification during
122 authentication. If omitted, fallback to the authenticator’s default
123 behaviour. If enabled, an authenticator with support for FIDO2 user
124 verification is required.
125 pinverification=int
127 If 1, require PIN verification during authentication. If 0, do not
128 request PIN verification during authentication. If omitted,
129 fallback to the authenticator’s default behaviour. If enabled, an
130 authenticator with support for a FIDO2 PIN is required.
131 sshformat
133 Use credentials produced by versions of OpenSSH that have support
134 for FIDO devices. It is not possible to mix native credentials and
135 SSH credentials. Once this option is enabled all credentials will
136 be parsed as SSH.
137
139 Second factor authentication deferring user verification configuration
140 to the authorization mapping file.
141 auth required pam_u2f.so authfile=/etc/u2f_mappings cue
143 Passwordless authentication enforcing PIN verification.
145 auth sufficient pam_u2f.so authfile=/etc/u2f_mappings cue pinverification=1 userverification=0
147 Passwordless authentication using built-in UV (e.g. biometrics) with a
149 fallback to PIN.
150 auth sufficient pam_u2f.so authfile=/etc/u2f_mappings cue pinverification=0 userverification=1
152 auth sufficient pam_u2f.so authfile=/etc/u2f_mappings cue pinverification=1 userverification=0
153
155 By default, relative paths to the authfile will be opened as the target
156 user, whereas absolute paths will be opened as "root". If the
157 "XDG_CONFIG_HOME" variable is set, privileges will not be dropped
158 unless the "openasuser" configuration setting is set.
159 Using pam-u2f to secure the login to a computer while storing the
161 mapping file in an encrypted home directory, will result in the
162 impossibility of logging into the system. The partition is decrypted
163 after login and the mapping file can not be accessed.
164
166 Nodetect
167 The "nodetect" option should be used with caution. pam_u2f checks that
169 a key configured for the user is inserted before performing the full
170 tactile authentication. This detection is done by sending a
171 "check-only" authentication request to all inserted tokens to so see if
172 at least one of them responds affirmatively to one or more of the
173 keyhandles configured for the user. By doing this, pam_u2f can avoid
174 emitting the "cue" prompt (if configured), which can cause some
175 confusing UI issues if the cue is emitted followed by the underlying
176 library immediately failing the tactile authentication. This option is
177 also useful to avoid an unintended 1-second delay prior to the tactile
178 authentication caused by versions of libu2f-host <= 1.1.5.
179 If pam_u2f is configured to "cue" and "nodetect", an attacker can
181 determine that pam_u2f is part of the authentication stack by inserting
182 any random U2F token and performing an authentication attempt. In this
183 scenario, the attacker would see the cue message followed by an
184 immediate failure, whereas with detection enabled, the U2F
185 authentication will fail silently. Understand that an attacker could
186 choose a U2F token that alerts him or her in some way to the
187 "check-only" authentication attempt, so this precaution only pushes the
188 issue back a step.
189 In summary, the detection feature was added to avoid confusing UI
191 issues and to prevent leaking information about the authentication
192 stack in very specific scenario when "cue" is configured. The
193 "nodetect" option was added to avoid buggy sleep behavior in older
194 versions of libu2f-host and for hypothetical tokens that do not
195 tolerate the double authentication. Detection is performed, and
196 likewise "nodetect" honored, regardless of whether "cue" is also
197 specified.
198 SELinux
200 Due to an issue with Fedora Linux, and possibly with other
202 distributions that use SELinux, a system configured with pam-u2f may
203 end up in a situation where access to the credentials file is denied.
204 If the nouserok option is also set, this will result in a successful
205 authentication within the module, without using the FIDO authenticator.
206 In order to correctly update the security context the command fixfiles
208 onboot should be used on existing installations
209 Moreover, to allow read access to an authfile or directory placed in a
211 non-standard location, the command
212 # chcon -R -t auth_home_t /path/to/authfile
214 should be used.
216 For more information see
218 https://access.redhat.com/security/cve/CVE-2020-24612.
219
221 Report pam-u2f bugs in the issue tracker:
222 https://github.com/Yubico/pam-u2f/issues
223
225 pam(7)
226 The pam-u2f home page: https://developers.yubico.com/pam-u2f/
228 YubiKeys can be obtained from Yubico: http://www.yubico.com/
230pam-u2f Version 1.3.0 PAM_U2F(8)