File: README

package info (click to toggle)
pam-u2f 1.0.4-2
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 1,668 kB
  • ctags: 287
  • sloc: sh: 11,547; ansic: 1,353; makefile: 82
file content (212 lines) | stat: -rw-r--r-- 7,460 bytes parent folder | download | duplicates (2)
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
Pluggable Authentication Module (PAM) Universal 2nd Factor (U2F)
================================================================

image:https://travis-ci.org/Yubico/pam-u2f.svg?branch=master["Build Status", link="https://travis-ci.org/Yubico/pam-u2f"]
image:https://scan.coverity.com/projects/5711/badge.svg["Coverity Status", link=https://scan.coverity.com/projects/5711]

The PAM U2F module provides an easy way to integrate the Yubikey (or
other U2F-compliant authenticators) into your existing user
authentication infrastructure. PAM is used by GNU/Linux, Solaris and
Mac OS X for user authentication.

Introduction
------------

This module implements PAM authentication over U2F. Registration should
be performed using the included tool. Multiple devices are supported, for
details check the <<devices, Multiple Devices>> section.

For more information visit the project page
https://developers.yubico.com/pam-u2f/[pam-u2f project].

License
-------

The project is licensed under a BSD license. See the file COPYING for
exact wording. For any copyright year range specified as YYYY-ZZZZ in
this package note that the range specifies every single year in that
closed interval.

[[building]]
Building
--------

This project uses 'autoconf', 'automake' and 'libtool' to achieve
portability and ease of use.  If you downloaded a tarball, build it as
follows.

-----------
  $ ./configure
  $ make check
-----------

Both the Yubico U2F host and server libaries are needed
https://developers.yubico.com/libu2f-host[libu2f-host],
https://developers.yubico.com/libu2f-server[libu2f-server]

Building from Git
-----------------

You may check out the sources using Git with the following command:

-----------
  $ git clone git://github.com/Yubico/pam-u2f.git
-----------

This will create a directory 'pam-u2f'. Enter the directory:

-----------
  $ cd pam-u2f
-----------

Autoconf, automake, libtool, and libpam must be installed. AsciiDoc and xsltproc are used to
generate the manpages.

  Debian:   apt-get install autoconf automake libtool libpam-dev asciidoc xsltproc libxml2-utils docbook-xml --no-install-recommends

Generate the build system using:

-----------
  $ 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
----

Supported parameters for the module are:

[horizontal]
debug::
Turns on debugging to STDOUT

origin=origin::
Set the origin for the U2F authentication procedure.
If no value is specified, the origin "pam://$HOSTNAME" is used.

appid=appid::
Set the https://developers.yubico.com/U2F/App_ID.html[application ID] for the U2F authentication procedure.
If no value is specified, the same value used for origin is taken
("pam://$HOSTNAME" if also origin is not specified).

authfile=file::
Set the location of the file that holds the mappings of user names
to keyHandles and user keys.  The format is
+username:first_keyHandle,first_public_key:
second_keyHandle,second_public_key:...+ the default location of the
file is $XDG_CONFIG_HOME/Yubico/u2f_keys. If the environment variable
is not set, $HOME/.config/Yubico/u2f_keys is used.
(more on <<files,Authorization Mapping Files>>).

nouserok::
Set to enable authentication attempts to succeed even if the user trying to
authenticate is not found inside authfile.

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 U2F device.
Recommended if your device doesn't have a tactile trigger.

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.

[[files]]
Authorization Mapping Files
---------------------------
A mapping must be made between the YubiKey token and the user name.
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.

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, the number of registered Yubikeys and the information
obtained during the registration procedure.

The mappings should look like this, one per line:

 <username1>:<KeyHandle1>,<UserKey1>:<KeyHandle2>,<UserKey2>:...
 <username2>:<KeyHandle1>,<UserKey1>:<KeyHandle2>,<UserKey2>:...

Now add `authfile=/etc/u2f_mappings` to your PAM configuration line, so it
looks like:

 auth sufficient pam_u2f.so authfile=/etc/u2f_mappings

== Individual authorization mapping by user
Each user creates a `~/.config/Yubico/u2f_keys` file inside of their home
directory and places the mapping in that file, the file must have only one
line:

 <username>:<KeyHandle1>,<UserKey1>:<KeyHandle2>,<UserKey2>:...

This is much the same concept as the SSH authorized_keys file.

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:

----
$ 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+.
During the U2F registration, the user is required to touch the token.
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+)

[[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.

Portability
-----------

The main development platforms are Debian GNU/Linux and Ubuntu and they
should be well supported.