annotate mod_auth_internal_yubikey.wiki @ 167:caa297adfe14

Make a small amendment to the text about how OTPs work.
author MWild1
date Thu, 17 Feb 2011 16:30:00 +0000
parents 7a9c49166d91
children 5523eda6e4e9
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
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
2 #labels Stage-Beta
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
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
20 = Configuration =
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
21
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
22 == Associating keys ==
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
23 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
24
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
25 To associate a Yubikey with a user, run the following prosodyctl command:
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
26 {{{
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
27 prosodyctl mod_auth_internal_yubikey associate user@example.com
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
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
30 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
31
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
32 *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
33
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
34 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 options are:
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 || password || The user's password (may be blank) ||
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
37 || fixed || The public ID that the Yubikey prefixes to the OTP ||
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
38 || uid || The private ID that the Yubikey encrypts in the OTP ||
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
39 || 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
40
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
41 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
42
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
43 == Configuring Prosody ==
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 To use this module for authentication, set in the config:
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 authentication = "internal_yubikey"
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
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
50 Module-specific options:
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
51
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
52 || 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
53 || 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
54
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
55 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
56
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
57 = Compatibility =
7a9c49166d91 Created wiki page through web user interface.
MWild1
parents:
diff changeset
58 ||0.8|| Works ||