--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_auth_internal_yubikey/README.markdown	Fri Aug 28 18:03:58 2015 +0200
@@ -0,0 +1,111 @@
+---
+labels:
+- 'Stage-Beta'
+- 'Type-Auth'
+summary: 'Two-factor authentication using Yubikeys'
+...
+
+Introduction
+============
+
+A [YubiKey](http://www.yubico.com/yubikey) is a small USB
+one-time-password (OTP) generator.
+
+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.
+
+Details
+=======
+
+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.
+
+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.
+
+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.
+
+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.
+
+Installation
+============
+
+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.
+
+Configuration
+=============
+
+Associating keys
+----------------
+
+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).
+
+To associate a Yubikey with a user, run the following prosodyctl
+command:
+
+        prosodyctl mod_auth_internal_yubikey associate user@example.com
+
+This will run you through a series of questions about the information
+Prosody requires about the key configuration.
+
+**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.
+
+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:
+
+  password   The user's password (may be blank)
+  ---------- --------------------------------------------------------------------------------------------
+  fixed      The public ID that the Yubikey prefixes to the OTP
+  uid        The private ID that the Yubikey encrypts in the OTP
+  key        The AES key that the Yubikey uses (may be blank if a global shared key is used, see below)
+
+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.
+
+Configuring Prosody
+-------------------
+
+To use this module for authentication, set in the config:
+
+        authentication = "internal_yubikey"
+
+Module-specific options:
+
+  yubikey\_prefix\_length   (**REQUIRED**) The length of the public ID prefixed to the OTPs
+  ------------------------- -------------------------------------------------------------------------------------------------------------------
+  yubikey\_global\_key      If all Yubikeys use the same AES key, you can specify it here. Pass --key="" to prosodyctl when associating keys.
+
+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.
+
+Compatibility
+=============
+
+  ----- -------
+  0.8   Works
+  ----- -------