---
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
  ----- -------