Setting up a Yubikey login

FastMail supports using a Yubikey to login to your account via the web interface. This can either be used as a one factor (yubikey only) or two factor (yubikey and password) login method.

To setup a Yubikey login, just click on Advanced in the top left menu, and then click on 'Alternative Logins', and create a new one factor or two factor Yubikey alternative login.

Currently we authenticate against the Yubico online web service rather than our own validation server. This means that by default your Yubikey should work "out of the box" with the AES key that was in it when it was shipped.

Using a Yubikey for login

You can click the "More" link on the login page to show the yubikey entry field. After entering your username, and a password (if using two-factor authentication), focus the cursor in the yubikey field. Then insert your yubikey into a USB slot and press the button on the yubikey to enter a yubikey one-time value into the field.

Alternatively, you can just insert the yubikey value directly into the password field (one-factor) or onto the end of the password (two-factor). This means you don't have to click More link to show the yubikey field.

Getting a Yubikey

You can order Yubikeys from the Yubico website order page.

One-factor vs Two-factor authentication

With one factor authentication, you need one item to authenticate that you are who you say you are. Normally that's a password (something you know), or with a yubikey one-factor login, that's just the value generated by the yubikey when you touch it (something you have).

With two factor authentication, you need two items to authenticate you. With yubikey two-factor, that's both a password (something you know) and the value generated by the yubikey when you touch it (something you have).

The advantage of the two-factor approach is that if you login on a machine with a keylogger/malware/root kit that captures your username + password + yubikey one time password, it doesn't matter, because the yubikey one time password can't be reused. If someone steals your physical Yubikey, then it doesn't matter, because they don't know your fixed static password. This is why it's called "two factor" authentication. (Of course it doesn't protect against the case of both the static password and physical key being stolen, but that's a lot less likely)

More about Yubikey

The Yubikey is a small USB authentication device that you can use to login to your FastMail account instead of your regular password. The Yubikey doesn't need any client software. You just plug it into a USB port and it acts like a USB keyboard that most OS's automatically support. It has one button on it, that when you press it, it generates a new one-time 44 character password.

The main advantage of a Yubikey login over a regular static password login is that to login, you must have the physical Yubikey token plugged into your machine, and you must press the button on it to generate a new one-time password. You can't re-enter an already used one-time password, or copy and paste an existing one-time password. This prevents replay attacks if someone captures any of your logins (eg keylogger, tcp dump, malware root kit, etc).

Here's the way it works:

  • Each device has a unique id, that's the first 12 chars
  • Each device has an internal "shared secret" AES encryption key
  • Each time you press the button, it generates a new one-time value that encrypted with that key, that's the other 32 characters

The way it generates the one-time value is like this:

  • It takes some internal values and joins them together
  • It then encrypts that data using a symmetric cipher with the shared AES key that's stored in the Yubikey, and also on the Yubico server so the server can decrypt it

The internal values that are joined and encrypted include:

  • A private internal value
  • A number of counter fields (each time you plug the key into a machine, or generate a new key, internal non-volatile counters are incremented)
  • Timer field (an internal 8hz counter value)
  • A random number
  • A CRC checksum

So at the receiving side, you get the 44 char value. The first 12 chars normally let you work out who's key it is (we still need to ask for your login name, because we allow you to associate your Yubikey with multiple different accounts if you want). With the other 32 bytes, they are decrypted using the shared AES key, and then all the values are checked to make sure they are valid (eg counters are all higher than their previous values, checksum is valid, etc). There's more details at the Yubico website (PDF manual).

So with this approach, you can validate a login, and be sure that if someone captures your keystrokes/one-time password value, it's useless, because it can't be used again.

We don't actually store the AES key or do the decryption. That's done with the Yubico web API service. So the shared key is stored in the Yubikey itself, and on the Yubico web service API server.