annotate mod_auth_internal_yubikey.wiki @ 476:6aa13786ce90

Created wiki page through web user interface.
author MWild1@gmail.com
date Tue, 19 Aug 2014 14:45:06 +0000
parents 80f117f99f23
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
166
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
1 #summary Two-factor authentication using Yubikeys
180
80f117f99f23 Add Type-Auth tag
MWild1
parents: 168
diff changeset
2 #labels Stage-Beta,Type-Auth
166
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
3
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
4 = Introduction =
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
5
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
6 A [http://www.yubico.com/yubikey YubiKey] is a small USB one-time-password (OTP) generator.
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
7
167
caa297adfe14 Make a small amendment to the text about how OTPs work.
MWild1
parents: 166
diff changeset
8 The idea behind one-time-passwords is that they can, well, only be used once. After authenticating with an OTP the only way to log in again is to calculate another one and use that. The only (practical) way to generate this is by inserting the (correct) Yubikey and pressing its button. Acting as a USB keyboard it then "types" the OTP into the password prompt of your XMPP client.
166
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
9
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
10 = Details =
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
11
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
12 This self-contained module handles all the authentication of Yubikeys, it does not for example depend on the Yubico authentication service, or on any external system service such as PAM.
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
13
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
14 When this module is enabled, only PLAIN authentication is enabled on the server (because Prosody needs to receive the full password from the client to decode it, not a hash), so connection encryption will automatically be enforced by Prosody.
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
15
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
16 Even if the password is intercepted it is of little use to the attacker as it expires as soon as it is used. Additionally the data stored in Prosody's DB is not enough to authenticate as the user if stolen by the attacker.
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
17
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
18 When this module is in use each user can either use normal password authentication, or instead have their account associated with a Yubikey - at which point only the key will work.
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
19
168
5523eda6e4e9 Documented dependencies.
MWild1
parents: 167
diff changeset
20 = Installation =
5523eda6e4e9 Documented dependencies.
MWild1
parents: 167
diff changeset
21
5523eda6e4e9 Documented dependencies.
MWild1
parents: 167
diff changeset
22 Requires bitlib for Lua, and yubikey-lua from http://code.matthewwild.co.uk/yubikey-lua . When properly installed, the command `lua -lbit -lyubikey` should give you a Lua prompt with no errors.
5523eda6e4e9 Documented dependencies.
MWild1
parents: 167
diff changeset
23
166
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
24 = Configuration =
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
25
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
26 == Associating keys ==
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
27 Each Yubikey is configured with several pieces of information that Prosody needs to know. This information is shown in the Yubikey personalization tool (the _yubikey-personalization_ package in Debian/Ubuntu).
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
28
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
29 To associate a Yubikey with a user, run the following prosodyctl command:
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
30 {{{
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
31 prosodyctl mod_auth_internal_yubikey associate user@example.com
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
32 }}}
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
33
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
34 This will run you through a series of questions about the information Prosody requires about the key configuration.
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
35
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
36 *NOTE:* All keys used with the server (rather, with a given host) must all have a "public ID" (uid) of the same length. This length must be set in the Prosody config with the 'yubikey_prefix_length' option.
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
37
168
5523eda6e4e9 Documented dependencies.
MWild1
parents: 167
diff changeset
38 Instead of entering the information interactively it is also possible to specify each option on the command-line (useful for automation) via --option="value". The valid options are:
166
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
39
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
40 || password || The user's password (may be blank) ||
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
41 || fixed || The public ID that the Yubikey prefixes to the OTP ||
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
42 || uid || The private ID that the Yubikey encrypts in the OTP ||
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
43 || key || The AES key that the Yubikey uses (may be blank if a global shared key is used, see below) ||
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
44
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
45 If a password is configured for the user (recommended) they must enter this into the password box immediately before the OTP. This password doesn't have to be incredibly long or secure, but it prevents the Yubikey being used for authentication if it is stolen and the password isn't known.
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
46
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
47 == Configuring Prosody ==
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
48
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
49 To use this module for authentication, set in the config:
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
50 {{{
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
51 authentication = "internal_yubikey"
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
52 }}}
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
53
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
54 Module-specific options:
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
55
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
56 || yubikey_prefix_length || (*REQUIRED*) The length of the public ID prefixed to the OTPs ||
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
57 || yubikey_global_key || If all Yubikeys use the same AES key, you can specify it here. Pass --key="" to prosodyctl when associating keys. ||
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
58
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
59 If switching from a plaintext storage auth module then users without Yubikeys associated with their account can continue to use their existing passwords as normal, otherwise password resets are required.
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
60
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
61 = Compatibility =
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
62 ||0.8|| Works ||