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 debug to, file must exist and be a regular file,
21 or one of "stdout", "stderr", or "syslog". STDERR is the default.
22 origin=origin
24 Set the origin for the U2F authentication procedure. If no value is
25 specified, the origin "pam://$HOSTNAME" is used.
26 appid=appid
28 Set the application ID for the U2F authentication procedure. If no
29 value is specified, the same value used for origin is taken
30 ("pam://$HOSTNAME" if also origin is not specified).
31 authfile=file
33 Set the location of the file that holds the mappings of user names
34 to keyHandles and user keys. The format is
35 username:keyHandle1,public_key1:keyHandle2,public_key2:... the
36 default location of the file is $XDG_CONFIG_HOME/Yubico/u2f_keys.
37 If the environment variable is not set,
38 $HOME/.config/Yubico/u2f_keys is used.
39 authpending_file=file
41 Set the location of the file that is used for touch request
42 notifications. This file will be opened when pam-u2f starts waiting
43 for a user to touch the device, and will be closed when it no
44 longer waits for a touch. Use inotify to listen on these events, or
45 a more high-level tool like yubikey-touch-detector. Default value:
46 /var/run/user/$UID/pam-u2f-authpending. Set an empty value in order
47 to disable this functionality, like so: lockfile=
48 nouserok
50 Set to enable authentication attempts to succeed even if the user
51 trying to authenticate is not found inside authfile or if authfile
52 is missing/malformed.
53 openasuser
55 Setuid to the authenticating user when opening the authfile. Useful
56 when the user’s home is stored on an NFS volume mounted with the
57 root_squash option (which maps root to nobody which will not be
58 able to read the file).
59 alwaysok
61 Set to enable all authentication attempts to succeed (aka
62 presentation mode).
63 max_devices=n_devices
65 Maximum number of devices allowed per user (default is 24). Devices
66 specified in the authentication file that exceed this value will be
67 ignored.
68 interactive
70 Set to prompt a message and wait before testing the presence of a
71 U2F device. Recommended if your device doesn’t have tactile
72 trigger.
73 [prompt=your prompt here]
75 Set individual prompt message for interactive mode. Watch the
76 square brackets around this parameter to get spaces correctly
77 recognized by PAM.
78 manual
80 Set to drop to a manual console where challenges are printed on
81 screen and response read from standard input. Useful for debugging
82 and SSH sessions without U2F-support from the SSH client/server. If
83 enabled, interactive mode becomes redundant and has no effect.
84 cue
86 Set to prompt a message to remind to touch the device.
87 nodetect
89 Skip detecting if a suitable key is inserted before performing a
90 full authentication. See NOTES below.
91
93 auth sufficient pam_u2f.so debug origin=pam://$HOSTNAME
94 appid=pam://$HOSTNAME
95 auth required pam_u2f.so origin=http://example.com
97 appid=http://example.com authfile=/etc/yubikey_mappings
98
100 Using pam-u2f to secure the login to a computer while storing the
101 mapping file in an encrypted home directory, will result in the
102 impossibility of logging into the system. The partition is decrypted
103 after login and the mapping file can not be accessed.
104
106 The "nodetect" option should be used with caution. pam_u2f checks that
107 a key configured for the user is inserted before performing the full
108 tactile authentication. This detection is done by sending a
109 "check-only" authentication request to all inserted tokens to so see if
110 at least one of them responds affirmatively to one or more of the
111 keyhandles configured for the user. By doing this, pam_u2f can avoid
112 emitting the "cue" prompt (if configured), which can cause some
113 confusing UI issues if the cue is emitted followed by the underlying
114 library immediately failing the tactile authentication. This option is
115 also useful to avoid an unintended 1-second delay prior to the tactile
116 authentication caused by versions of libu2f-host <= 1.1.5.
117 If pam_u2f is configured to "cue" and "nodetect", an attacker can
119 determine that pam_u2f is part of the authentication stack by inserting
120 any random U2F token and performing an authentication attempt. In this
121 scenario, the attacker would see the cue message followed by an
122 immediate failure, whereas with detection enabled, the U2F
123 authentication will fail silently. Understand that an attacker could
124 choose a U2F token that alerts him or her in some way to the
125 "check-only" authentication attempt, so this precaution only pushes the
126 issue back a step.
127 In summary, the detection feature was added to avoid confusing UI
129 issues and to prevent leaking information about the authentication
130 stack in very specific scenario when "cue" is configured. The
131 "nodetect" option was added to avoid buggy sleep behavior in older
132 versions of libu2f-host and for hypothetical tokens that do not
133 tolerate the double authentication. Detection is performed, and
134 likewise "nodetect" honored, regardless of whether "cue" is also
135 specified.
136
138 Report pam-u2f bugs in the issue tracker:
139 https://github.com/Yubico/pam-u2f/issues
140
142 pam(7)
143 The pam-u2f home page: https://developers.yubico.com/pam-u2f/
145 YubiKeys can be obtained from Yubico: http://www.yubico.com/
147pam-u2f Version 1.0.6 PAM_U2F(8)