#summary Two-factor authentication using Yubikeys
#labels Stage-Beta,Type-Auth

= Introduction =

A [http://www.yubico.com/yubikey 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 ||