forked from Yubico/pam-u2f
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
392 lines (306 loc) · 14.5 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
Pluggable Authentication Module (PAM) Universal 2nd Factor (U2F)
================================================================
image:https://github.com/yubico/pam-u2f/workflows/linux/badge.svg["Linux Build Status (github actions)", link="https://github.com/Yubico/pam-u2f/actions"]
image:https://github.com/yubico/pam-u2f/workflows/macos/badge.svg["macOS Build Status (github actions)", link="https://github.com/Yubico/pam-u2f/actions"]
image:https://github.com/yubico/pam-u2f/workflows/fuzzer/badge.svg["Fuzz Status (github actions)", link="https://github.com/Yubico/pam-u2f/actions"]
This module implements PAM over U2F and FIDO2, providing an easy way to integrate the
YubiKey (or other U2F/FIDO2 compliant authenticators) into your existing
infrastructure.
[[building]]
Building
--------
This project uses 'autoconf', 'automake', 'pkg-config' and 'libtool'
to achieve portability and ease of use.
In addition, https://developers.yubico.com/libfido2['libfido2'] (>=
1.3.0) is needed. Versions of this project up to 1.0.8 used
`libu2f-host` and `libu2f-server`. On Ubuntu, the necessary dependencies can be
installed using
[source, console]
----
# apt install --no-install-recommends autoconf automake libtool pkg-config \
libfido2-dev libpam-dev libssl-dev
----
If you downloaded a tarball, build it as follows.
[source, console]
----
$ ./configure
$ make
----
Building from Git
-----------------
You may check out the sources using Git with the following command:
[source, console]
----
$ git clone https://github.com/Yubico/pam-u2f.git
----
This will create a directory 'pam-u2f'. Enter the directory:
[source, console]
----
$ cd pam-u2f
----
`autoconf`, `automake`, `libtool`, and `libpam` must be installed.
`AsciiDoc` and `xsltproc` are used to generate the manpages. On Ubuntu,
the necessary dependencies can be installed using
[source, console]
----
# apt install --no-install-recommends autoconf automake libtool \
pkg-config libfido2-dev libpam-dev libssl-dev asciidoc xsltproc \
libxml2-utils docbook-xml
----
On Fedora, the necessary dependencies can be installed using
[source, console]
----
# dnf -y install autoconf automake libtool libfido2-devel pam-devel \
openssl-devel asciidoc
----
Generate the build system using:
[source, console]
----
$ autoreconf --install
----
Then build as usual, see above under <<building,Building>>.
Installation
------------
Once the module is built, copy the file `pam_u2f.so` to the correct
directory for your system. Typically `/lib/security/` or
`/lib/x86_64-linux-gnu/security/`. This is automated by `make install`
assuming that the pam directory chosen by `configure` is correct. If
that is not the case it can be specified with `./configure
--with-pam-dir=`.
Create a file for a new service in `/etc/pam.d/` or edit an already
existing one by adding a line similar to this:
----
auth sufficient pam_u2f.so debug
----
For more information about the syntax of PAM configuration files, please
see the manual page for pam.conf(5).
IMPORTANT: An erroneous PAM configuration may lock some or all users
out of the system or prevent you from gaining root privileges. It is
recommended that you start a separate shell with root privileges while
configuring PAM to be able to revert changes if something goes wrong.
Test your configuration thoroughly before closing the root shell.
Supported parameters for the module are:
[horizontal]
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 https://developers.yubico.com/U2F/App_ID.html[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 U2F 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 <<authMappingFiles,file that holds the mappings of user
names to keyHandles and user keys>>. An <<individualAuth,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.
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 device, 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
https://github.com/maximbaz/yubikey-touch-detector[yubikey-touch-detector].
Set an empty value in order to disable this functionality, like so:
`authpending_file=`. Default value:
/var/run/user/$UID/pam-u2f-authpending
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 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 devices allowed per user (default is 24). Devices
specified in the authentication file that exceed this value will be
ignored.
interactive::
Set to prompt a message and wait before testing the presence of a FIDO
device. Recommended if your device doesn't have a 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 U2F-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 device.
[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::
Set to skip detecting if a suitable FIDO token is inserted before
performing the full tactile authentication. This detection was created
to avoid emitting the "cue" message if no suitable token exists,
because doing so leaks information about the authentication stack if a
token is inserted but not configured for the authenticating user.
However, it was found that versions of `libu2f-host` 1.1.5 or less has
buggy iteration/sleep behavior which causes a 1-second delay to occur
for this initial detection. For this reason, as well as the
possibility of hypothetical tokens that do not tolerate this double
authentication, the "nodetect" option was added.
userpresence=int::
If 1, request 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, request 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, request 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 devices. It is not possible to mix native credentials and SSH
credentials. Once this option is enabled all credentials will be parsed
as SSH.
[[authMappingFiles]]
Authorization Mapping Files
---------------------------
A mapping must be made between the YubiKey token and the user name,
see <<registration, here>> for details on how to perform the
registration using the bundled tool.
There are two ways to do this, either centrally in one file, or
individually, where users can create the mapping in their home
directories. If the central authorization mapping file is being used,
user home directory mappings will not be used and the opposite applies
if user home directory mappings are being used, the central
authorization mappings file will not be used.
By default the mapping file inside a home directory will be opened as
the target user, whereas the central file 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.
IMPORTANT: 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.
Central Authorization Mapping
-----------------------------
Create a file e.g. `/etc/u2f_mappings`. The file must contain a user
name, and the information obtained during the registration procedure.
The mappings should look like this, one per line:
<username1>:<KeyHandle1>,<UserKey1>,<CoseType1>,<Options1>:<KeyHandle2>,<UserKey2>,<CoseType2>,<Options2>:...
<username2>:<KeyHandle1>,<UserKey1>,<CoseType1>,<Options1>:<KeyHandle2>,<UserKey2>,<CoseType2>,<Options2>:...
Now add `authfile=/etc/u2f_mappings` to your PAM configuration line,
so it looks like:
auth sufficient pam_u2f.so authfile=/etc/u2f_mappings
If you do not set the `openasuser` setting, the authfile will be
opened and parsed as `root` so make sure it has the correct owner and
permissions set.
IMPORTANT: On dynamic networks (e.g. where hostnames are set by DHCP),
users should not rely on the default origin and appid
("pam://$HOSTNAME") but set those parameters explicitly to the same
value.
[[individualAuth]]
Individual Authorization Mapping by User
----------------------------------------
Each user creates a `.config/Yubico/u2f_keys` (default) file inside
their home directory and places the mapping in that file. You may want
to specify a different per-user file (relative to the users' home
directory), i.e. `.ssh/u2f_keys`. Bear in mind, setting an absolute path
here is possible although very likely a fragile setup, and probably
not exhibiting the intended behaviour.
The file must have only one line:
<username>:<KeyHandle1>,<UserKey1>,<CoseType1>,<Options1>:<KeyHandle2>,<UserKey2>,<CoseType2>,<Options2>:...
This is much the same concept as the SSH authorized_keys file.
In this case, pam-u2f will drop privileges and read the mapping file
as that user. This happens regardless of the `openasuser` option being
set.
Note that if you set the `XDG_CONFIG_HOME` variable, privileges will not
be dropped by default. Consider also setting `openasuser` in that
case.
[[registration]]
Obtaining key-handles and Public Keys
-------------------------------------
In order to obtain the required information for the authentication procedure,
a token should be first registered. This can be done by using the command line
configuration tool provided with the module:
[source, console]
----
$ pamu2fcfg -uusername -opam://myorigin -ipam://myappid
----
the tool will register a connected token by using the specified origin
and appid. If neither are specified they will default to
`pam://$HOSTNAME`. Additionally, it is possible to set other options
to require user presence (touch), PIN verification and resident
credentials. On success the tool prints to standard output a
configuration line that can be directly used with the module. For
additional information on the tool read the relative manpage (`man
pamu2fcfg`).
SSH Credentials
---------------
To generate SSH credentials OpenSSH version 8.2 or later is required.
It is then possible to generate a credential file with:
[source, console]
----
$ ssh-keygen -t ecdsa-sk -f ./credential.ssh
----
Supported key types are ecdsa-sk and ed25519-sk. Note that passphrase protected
credentials are currently not supported.
To use this credential the `authfile` parameter should be set to the path of
the file `credential.ssh` and the `sshformat` option should also be set. If the
`authfile` parameter is not set, it defaults to `~/.ssh/id_ecdsa_sk`.
[[devices]]
Multiple Devices
----------------
Multiple devices are supported. If more than one device is specified,
authentication against them is attempted sequentially as they are defined
in the configuration file of the module. If during an authentication
attempt a connected device is removed or a new device is plugged in,
the authentication restarts from the top of the list.
SELinux Note
------------
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
[source, console]
----
# chcon -R -t auth_home_t /path/to/target
----
should be used.
For more information see
https://access.redhat.com/security/cve/CVE-2020-24612[HERE].
FIDO U2F vs FIDO2
-----------------
Devices that solely support FIDO U2F and not FIDO2, e.g. the YubiKey 4 series,
can be used only in conjunction with compatible features. Enabling incompatible
features, such as setting the `+pin` or the `+verification` flags in the
`authfile` or the corresponding options in the PAM service configuration causes
the device to be ignored.