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 debug to, file must exist and be a regular file,
21           or one of "stdout", "stderr", or "syslog". STDERR is the default.
22
23       origin=origin
24           Set the origin for the U2F authentication procedure. If no value is
25           specified, the origin "pam://$HOSTNAME" is used.
26
27       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
32       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
40       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: "authpending_file=".
48
49       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
54       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). Note that after release 1.0.8 this is done
59           by default when no global authfile or XDG_CONFIG_HOME environment
60           variable has been set.
61
62       alwaysok
63           Set to enable all authentication attempts to succeed (aka
64           presentation mode).
65
66       max_devices=n_devices
67           Maximum number of devices allowed per user (default is 24). Devices
68           specified in the authentication file that exceed this value will be
69           ignored.
70
71       interactive
72           Set to prompt a message and wait before testing the presence of a
73           U2F device. Recommended if your device doesn’t have tactile
74           trigger.
75
76       [prompt=your prompt here]
77           Set individual prompt message for interactive mode. Watch the
78           square brackets around this parameter to get spaces correctly
79           recognized by PAM.
80
81       manual
82           Set to drop to a manual console where challenges are printed on
83           screen and response read from standard input. Useful for debugging
84           and SSH sessions without U2F-support from the SSH client/server. If
85           enabled, interactive mode becomes redundant and has no effect.
86
87       cue
88           Set to prompt a message to remind to touch the device.
89
90       nodetect
91           Skip detecting if a suitable key is inserted before performing a
92           full authentication. See NOTES below.
93

EXAMPLES

95       auth sufficient pam_u2f.so debug origin=pam://$HOSTNAME
96       appid=pam://$HOSTNAME
97
98       auth required pam_u2f.so origin=http://example.com
99       appid=http://example.com authfile=/etc/yubikey_mappings
100

CAVEATS

102       By default the mapping file inside a home directory will be opened as
103       the target user, whereas the central file will be opened as root. If
104       the XDG_CONFIG_HOME variable is set, privileges will not be dropped
105       unless the openasuser configuration setting is set.
106
107       Using pam-u2f to secure the login to a computer while storing the
108       mapping file in an encrypted home directory, will result in the
109       impossibility of logging into the system. The partition is decrypted
110       after login and the mapping file can not be accessed.
111

NOTES

113       The "nodetect" option should be used with caution. pam_u2f checks that
114       a key configured for the user is inserted before performing the full
115       tactile authentication. This detection is done by sending a
116       "check-only" authentication request to all inserted tokens to so see if
117       at least one of them responds affirmatively to one or more of the
118       keyhandles configured for the user. By doing this, pam_u2f can avoid
119       emitting the "cue" prompt (if configured), which can cause some
120       confusing UI issues if the cue is emitted followed by the underlying
121       library immediately failing the tactile authentication. This option is
122       also useful to avoid an unintended 1-second delay prior to the tactile
123       authentication caused by versions of libu2f-host <= 1.1.5.
124
125       If pam_u2f is configured to "cue" and "nodetect", an attacker can
126       determine that pam_u2f is part of the authentication stack by inserting
127       any random U2F token and performing an authentication attempt. In this
128       scenario, the attacker would see the cue message followed by an
129       immediate failure, whereas with detection enabled, the U2F
130       authentication will fail silently. Understand that an attacker could
131       choose a U2F token that alerts him or her in some way to the
132       "check-only" authentication attempt, so this precaution only pushes the
133       issue back a step.
134
135       In summary, the detection feature was added to avoid confusing UI
136       issues and to prevent leaking information about the authentication
137       stack in very specific scenario when "cue" is configured. The
138       "nodetect" option was added to avoid buggy sleep behavior in older
139       versions of libu2f-host and for hypothetical tokens that do not
140       tolerate the double authentication. Detection is performed, and
141       likewise "nodetect" honored, regardless of whether "cue" is also
142       specified.
143

BUGS

145       Report pam-u2f bugs in the issue tracker:
146       https://github.com/Yubico/pam-u2f/issues
147

SEE ALSO

149       pam(7)
150
151       The pam-u2f home page: https://developers.yubico.com/pam-u2f/
152
153       YubiKeys can be obtained from Yubico: http://www.yubico.com/
154
155
156
157pam-u2f                          Version 1.0.8                      PAM_U2F(8)
Impressum