Mercurial > prosody-modules

comparison mod_auth_internal_yubikey/README.markdown @ 1803:4d73a1a6ba68

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 ----- -------