Mercurial > prosody-modules
comparison mod_auth_internal_yubikey/README.markdown @ 1803:4d73a1a6ba68
Convert all wiki pages to Markdown
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Fri, 28 Aug 2015 18:03:58 +0200 |
parents | mod_auth_internal_yubikey/README.wiki@29f3d6b7ad16 |
children |
comparison
equal
deleted
inserted
replaced
1802:0ab737feada6 | 1803:4d73a1a6ba68 |
---|---|
1 --- | |
2 labels: | |
3 - 'Stage-Beta' | |
4 - 'Type-Auth' | |
5 summary: 'Two-factor authentication using Yubikeys' | |
6 ... | |
7 | |
8 Introduction | |
9 ============ | |
10 | |
11 A [YubiKey](http://www.yubico.com/yubikey) is a small USB | |
12 one-time-password (OTP) generator. | |
13 | |
14 The idea behind one-time-passwords is that they can, well, only be used | |
15 once. After authenticating with an OTP the only way to log in again is | |
16 to calculate another one and use that. The only (practical) way to | |
17 generate this is by inserting the (correct) Yubikey and pressing its | |
18 button. Acting as a USB keyboard it then "types" the OTP into the | |
19 password prompt of your XMPP client. | |
20 | |
21 Details | |
22 ======= | |
23 | |
24 This self-contained module handles all the authentication of Yubikeys, | |
25 it does not for example depend on the Yubico authentication service, or | |
26 on any external system service such as PAM. | |
27 | |
28 When this module is enabled, only PLAIN authentication is enabled on the | |
29 server (because Prosody needs to receive the full password from the | |
30 client to decode it, not a hash), so connection encryption will | |
31 automatically be enforced by Prosody. | |
32 | |
33 Even if the password is intercepted it is of little use to the attacker | |
34 as it expires as soon as it is used. Additionally the data stored in | |
35 Prosody's DB is not enough to authenticate as the user if stolen by the | |
36 attacker. | |
37 | |
38 When this module is in use each user can either use normal password | |
39 authentication, or instead have their account associated with a | |
40 Yubikey - at which point only the key will work. | |
41 | |
42 Installation | |
43 ============ | |
44 | |
45 Requires bitlib for Lua, and yubikey-lua from | |
46 http://code.matthewwild.co.uk/yubikey-lua . When properly installed, the | |
47 command `lua -lbit -lyubikey` should give you a Lua prompt with no | |
48 errors. | |
49 | |
50 Configuration | |
51 ============= | |
52 | |
53 Associating keys | |
54 ---------------- | |
55 | |
56 Each Yubikey is configured with several pieces of information that | |
57 Prosody needs to know. This information is shown in the Yubikey | |
58 personalization tool (the *yubikey-personalization* package in | |
59 Debian/Ubuntu). | |
60 | |
61 To associate a Yubikey with a user, run the following prosodyctl | |
62 command: | |
63 | |
64 prosodyctl mod_auth_internal_yubikey associate user@example.com | |
65 | |
66 This will run you through a series of questions about the information | |
67 Prosody requires about the key configuration. | |
68 | |
69 **NOTE:** All keys used with the server (rather, with a given host) must | |
70 all have a "public ID" (uid) of the same length. This length must be set | |
71 in the Prosody config with the 'yubikey\_prefix\_length' option. | |
72 | |
73 Instead of entering the information interactively it is also possible to | |
74 specify each option on the command-line (useful for automation) | |
75 via --option="value". The valid options are: | |
76 | |
77 password The user's password (may be blank) | |
78 ---------- -------------------------------------------------------------------------------------------- | |
79 fixed The public ID that the Yubikey prefixes to the OTP | |
80 uid The private ID that the Yubikey encrypts in the OTP | |
81 key The AES key that the Yubikey uses (may be blank if a global shared key is used, see below) | |
82 | |
83 If a password is configured for the user (recommended) they must enter | |
84 this into the password box immediately before the OTP. This password | |
85 doesn't have to be incredibly long or secure, but it prevents the | |
86 Yubikey being used for authentication if it is stolen and the password | |
87 isn't known. | |
88 | |
89 Configuring Prosody | |
90 ------------------- | |
91 | |
92 To use this module for authentication, set in the config: | |
93 | |
94 authentication = "internal_yubikey" | |
95 | |
96 Module-specific options: | |
97 | |
98 yubikey\_prefix\_length (**REQUIRED**) The length of the public ID prefixed to the OTPs | |
99 ------------------------- ------------------------------------------------------------------------------------------------------------------- | |
100 yubikey\_global\_key If all Yubikeys use the same AES key, you can specify it here. Pass --key="" to prosodyctl when associating keys. | |
101 | |
102 If switching from a plaintext storage auth module then users without | |
103 Yubikeys associated with their account can continue to use their | |
104 existing passwords as normal, otherwise password resets are required. | |
105 | |
106 Compatibility | |
107 ============= | |
108 | |
109 ----- ------- | |
110 0.8 Works | |
111 ----- ------- |