forked from firnsy/yubipam
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
124 lines (84 loc) · 4.66 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
-------------------------------------------------------------------------------
1. YubiPAM Introduction
-------------------------------------------------------------------------------
The YubiPAM module provides a simple, easy to configure, 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.
-------------------------------------------------------------------------------
2. Status
-------------------------------------------------------------------------------
1. Manual add/delete from database. Using the ykpasswd tool you can add
delete yubikey entries from the database (default: /etc/yubikey).
2. Per user accounting. Supports individual user account authorisation.
Every user may have multiple Yubikey dongles only make sure you are using
different public UID's on every Yubikey dongle.
3. Single and second factor sign in. Next to single factor ie. Yubikey OTP
you can define an additional passcode. The pam module will detect if the
second factor passcode is needed.
4. Static heuristic support. Heuristic support for OTP data deltas is hard
coded. This will be changable in the next release.
-------------------------------------------------------------------------------
3. Build
-------------------------------------------------------------------------------
Build the YubiPAM module by using autotools. First generate the configure file
$ autoreconf -i
You should run the configure file which will generate the Makefile. Run make
to build the YubiPAM module.
$ ./configure
$ make
$ sudo make install
-------------------------------------------------------------------------------
4. Configuration
-------------------------------------------------------------------------------
Install it in your PAM setup by adding a line to an appropriate file in the
director /etc/pam.d/:
auth sufficient pam_yubikey.so
and ensure pam_yubikey.so is located in /lib/security/
Supported PAM module parameters are:
"debug": enable debug.
"verbose_otp": enable echoing of the OTP, after all it's only a one time pad.
"include_users": enable yubikey auth for users in the given file. Eash line
can contain one user.
Ex: include_users=/etc/yubikey.users
"exclude_users": disable yubikey auth for users in the given file. Eash line
can contain one user.
Ex: exclude_users=/etc/yubikey.users
"passcode_only": instead of the OTP, pam authtok will only contain the
passcode. This can be very handy when you are using other
pam modules like pam_ecryptfs.
-------------------------------------------------------------------------------
5. Utilities
-------------------------------------------------------------------------------
ykpasswd
The ykpasswd utility provides administration, insert and removal of entries,
for the YubiPAM database. The required elements that need to be entered into
the database include the public UID (fixed modhex portion of an OTP), the AES
key which can be used to decrypt the token, and the private UID which is found
after successful decryption of a valid OTP.
If you have apriori knowledge of these values for user joesmith you can enter
them straight into the command line, using:
# ykpasswd -a -k AESKEY -f PUBLICKEY -p PRIVATEKEY -u joesmith
Or alteratnively you can just enter the minimum and be prompted to enter the
information using:
# ykpasswd -a -u joesmith
If you don't have the private UID it requires you to decrypt a valid token to
get the value. Fortunately you can provide a valid OTP and the appropriate AES
key and let ykpasswd determine the public and private UIDs for you, using:
# ykpasswd -a -u joesmith -k AESKEY -o OTP
The "-u" option is mandatory and should always be defined.
ykvalidate
Once a Yubikey has been successfully added to the YubiPAM database, it can be
tested using the ykvalidate tool. Simply pass an OTP associated with the
calling user or specify the actual user and it will confirm if it's VALID or
NOT.
# ykvalidate OTP
# ykvalidate -u joesmith OTP
-------------------------------------------------------------------------------
6. Troubleshooting
-------------------------------------------------------------------------------
In the event that the YubiPAM module is not working it may pay to enable debug
mode in order to sort out any issues. To enable debug mode just add the
PAM module parameter "debug" to your PAM entry:
auth sufficient pam_yubikey.so debug
Note: On production systems, debug should NOT be turned on due to its verbosity
and subsequent disclosure of information.