forked from Yubico/yubico-pam-dpkg
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
346 lines (238 loc) · 10.6 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
Yubico PAM module
-----------------
The Yubico PAM module provides an easy way to integrate the Yubikey
into your existing user authentication infrastructure. PAM is used by
GNU/Linux, Solaris and Mac OS X for user authentication, and by other
specialized applications such as NCSA !MyProxy.
Status and Roadmap
------------------
The module is working for multi-user systems. The primary mode of
operation is by doing online validation using a YubiKey validation
service (such as the YubiCloud, or a private one configured using
the 'url' parameter).
In version 2.6, offline validation was also made possible through
the use of HMAC-SHA1 Challenge-Response found in YubiKey 2.2 and
later. This has introduced a dependency of libykpers-1 from the
ykpersonalize package. Pass `--without-cr' to `configure' to avoid
this dependency.
The development community is co-ordinated via GitHub :
https://github.com/Yubico/yubico-pam/
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 from Git
-----------------
Skip to the next section if you are using an official packaged
version.
You may check out the sources using Git with the following command:
------
$ git clone git://github.com/Yubico/yubico-pam.git yubico-pam
------
This will create a directory 'yubico-pam'.
Autoconf, automake and libtool must be installed to create a compilable
source tree.
Generate the build system using:
------
$ cd yubico-pam
$ autoreconf --install
------
Building
--------
You will need to have libykclient (ykclient.h, libykclient.so) and
libpam-dev (security/pam_appl.h, libpam.so) installed. Get the
ykclient library from:
http://opensource.yubico.com/yubico-c-client/
It in turn requires Curl, which you need to have installed, and
libyubikey. Get libyubikey from
http://opensource.yubico.com/yubico-c/
The new Challenge-Response offline authentication requires libykpers-1
from the yubikey-personalization project :
http://opensource.yubico.com/yubikey-personalization/
The build system uses Autoconf, to set up the build system run:
------
./configure
------
Use --without-ldap to disable ldap support.
Then build the code, run the self-test and install the binaries:
------
make check install
------
Ubuntu PPA
----------
There is an Ubuntu PPA (Personal Package Archive) for yubico-pam that
can be installed using the following commands on reasonably modern
Ubuntu platforms :
$ sudo add-apt-repository ppa:yubico/stable
$ sudo apt-get update
$ sudo apt-get install libpam-yubico
See the file /usr/share/doc/libpam-yubico/README.Debian after installing.
Configuration
-------------
Install it in your PAM setup by adding a line to an appropriate file
in /etc/pam.d/:
------
auth sufficient pam_yubico.so id=16 debug
------
and move pam_yubico.so into /lib/security/ (or wherever PAM modules
live in your system) :
------
mv /usr/local/lib/security/pam_yubico.so /lib/security/
------
For more information, see the project Wiki page.
Supported PAM module parameters are:
------
"authfile": to indicate the location of the file that holds the
mappings of Yubikey token IDs to user names.
"id": to indicate your client identity.
"key": to indicate your client key in base64 format.
The client key is also known as API key, and provides
integrity in the communication between the client (you)
and the validation server.
If you want to get one for use with the default YubiCloud
service, visit this URL :
https://upgrade.yubico.com/getapikey/
"debug": to enable debug output to stdout.
"alwaysok": to enable all authentication attempts to succeed
(aka presentation mode).
"try_first_pass":
Before prompting the user for their password, the module
first tries the previous stacked module´s password in case
that satisfies this module as well.
"use_first_pass":
The argument use_first_pass forces the module to use a previous
stacked modules password and will never prompt the user - if no
password is available or the password is not appropriate, the user
will be denied access.
"url": specify the URL template to use, this is set by calling
yubikey_client_set_url_template, which defaults to:
http://api.yubico.com/wsapi/verify?id=%d&otp=%s
or
http://api.yubico.com/wsapi/2.0/verify?id=%d&otp=%s
depending on your version of yubico-c-client.
"capath": specify the path where X509 certificates are stored. This is
required if 'https' or 'ldaps' are used in 'url' and 'ldap_uri'
respectively.
"verbose_otp":
This argument is used to show the OTP (One Time Password) when it
is entered, i.e. to enable terminal echo of entered characters.
You are advised to not use this, if you are using two factor
authentication because that will display your password on the
screen.
This requires the service using the PAM module to
display custom fields. For example, OpenSSH requires
you to configure "ChallengeResponseAuthentication no".
"ldap_uri": specify the LDAP server URI (e.g. ldap://localhost).
"ldapserver": specify the LDAP server host (default LDAP port is used).
_Deprecated. Use "ldap_uri" instead._
"ldapdn": specify the dn where the users are stored
(eg: ou=users,dc=domain,dc=com).
"user_attr": specify the LDAP attribute used to store user names (eg:cn).
"yubi_attr": specify the LDAP attribute used to store the Yubikey id.
"yubi_attr_prefix":
specify the prefix of the LDAP attribute's value, in case
of a generic attribute, used to store several types of ids.
"token_id_length":
Length of ID prefixing the OTP (this is 12 if using the
YubiCloud).
"mode":
Mode of operation. Use "client" for online validation with
a YubiKey validation service such as the YubiCloud, or use
"challenge-response" for offline validation using YubiKeys
with HMAC-SHA-1 Challenge-Response configurations. See the
man-page ykpamcfg(1) for further details on how to configure
offline Challenge-Response validation.
------
If you are using "debug" you may find it useful to create a
world-writable log file:
------
touch /var/run/pam-debug.log
chmod go+w /var/run/pam-debug.log
------
Authorization Mapping Files
---------------------------
A mapping must be made between the Yubikey token ID and the user ID it is
attached to. 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.
Central authorization mapping
-----------------------------
Create a /etc/yubikey_mappings, the file must contain a user name and the
Yubikey token ID separated by colons (same format as the passwd file) for
each user you want to allow onto the system using a Yubikey.
The mappings should look like this, one per line:
------
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:….
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:….
------
Now add authfile=/etc/yubikey_mappings to your PAM configuration line, so it
looks like:
------
auth sufficient pam_yubico.so id=16 authfile=/etc/yubikey_mappings
------
Individual authorization mapping by user
----------------------------------------
Each user creates a ~/.yubico/authorized_yubikeys file inside of their home
directory and places the mapping in that file, the file must have only one
line:
------
<user name>:<Yubikey token ID1>:<Yubikey token ID2>
------
This is much the same concept as the SSH authorized_keys file.
Obtaining the Yubikey token ID (a.k.a. public ID)
-------------------------------------------------
You can obtain the Yubikey token ID in two places. One is by removing the
last 32 characters of any OTP (One Time Password) generated with your Yubikey, the other
is by using the modhex calculator located here :
http://radius.yubico.com/demo/Modhex_Calculator.php
Enter your Yubikey OTP and convert it, your Yubikey token ID is 12 characters and listed as:
Modhex encoded: XXXXXXX
Not sure what that last bit meant? Here is how to get a copy of your OTP.
Fast way
--------
* Open a terminal
* Press yubikey button
It will output an OTP into the shell:
------
$ cccccccgklgcvnkcvnnegrnhgrjkhlkfhdkclfncvlgj
bash: cccccccgklgcvnkcvnnegrnhgrjkhlkfhdkclfncvlgj: command not found
------
This can be pasted into the Modhex_Calculator page.
Harder way
----------
This requires you to have the pam module enabled with 'debug' turned on. When
prompted for the yubikey press the button. The pam module will print out debug
information including the OTP and ID of your token to the shell - copy the ID
into your config file and you should be up and going.
------
Yubikey for `youruser':
[pam_yubico.c:pam_sm_authenticate(867)] conv returned 44 bytes
[pam_yubico.c:pam_sm_authenticate(885)] Skipping first 0 bytes. Length is 44, token_id set to 12 and token OTP always 32.
[pam_yubico.c:pam_sm_authenticate(892)] OTP: ccccccclabcabkhbdncicglfltnukadfoifadfhhhhfe ID: cccccclabcab
------
Yubico PAM module and SELinux.
------------------------------
Users with SELinux in enforcing mode (the default on Fedora 17+) may experience
login problems with services including those validated via
polkit-agent-helper-1, sshd and login.
This is documented in the PAM Yubico issue tracker [1] and Red Hat bugzilla
including a work around [2] for ssh (Equivalent files could be created for
other services). Systems in 'permissive' mode will generate AVC warnings but
authentication will succeed.
[1] http://code.google.com/p/yubico-pam/issues/detail?id=43
[2] https://bugzilla.redhat.com/show_bug.cgi?id=841693#c3
To determine if you have SELinux enforcing or not run the 'sestatus' command.
Examples
--------
If you want to use the Yubikey to authenticate you on linux console
logins, add the following to the top of /etc/pam.d/login:
------
auth sufficient pam_yubico.so id=16 debug
------
Feedback
--------
If you want to discuss anything related to the Yubico PAM module,
please e-mail the mailing list yubico-devel@googlegroups.com.