Yubikey for WordPress, Roundcube and Linux

Background information using YubiCloud

What is the Yubikey?

The Yubikey is a cheap hardware security token which looks like a small USB stick.  It provides a one-time password (OTP) to use as two-factor authentication next to username and password.  Yubikey is a product of the Yubico company.  The Yubikey represents itself like a USB keyboard, so no drivers are required and it works on any platform which supports USB keyboards.  It works even with an iPad.  When pressing the touch-button it generates a keystroke which represents the one-time password.  The Yubikey is durable and doesn’t contain a battery or moving parts.  The Yubikey has four different operating modes.

1. YubiCloud (Yubico OTP) – Used for one-time password authentication against the Yubico authentication servers, also called the ‘YubiCloud’.
2. OATH OTP – Used for one-time password authentication using ‘Open Authentication’ which is an open standard.  You need a third party or corporate server to take care of the authentication.
3. Static password – The Yubikey returns a pre-defined static password when pressing the touch-button.
4. Challenge-response – Can be used with client software developed for the Yubikey.  For use in specific applications only.

Two of these modes can be configured at the same time.  The Yubikey has two slots.  By default, the first slot is for YubiCloud mode, the second is empty.  Both slots can be configured to contain any of the four modes.  Pressing the touch-button for a short or a long time will decide which slot is accessed.

This article discusses only the YubiCloud mode.

Extend your application to support the Yubikey

To handle YubiCloud authentication, the application needs Yubikey support.  There are many plugins to add Yubikey support to web-applications.  Yubico develops some plugins by itself, other are developed by the community.  Also, look for plugins for the YubiCloud (or Yubico OTP) service as some other plugins are developed for ‘OATH OTP’ mode and requires a third party authentication server.  When your application is ready to support Yubikey authentication it needs to be registered by Yubico to allow authentication by their servers.  During the registration process an ID and API Key are generated which needs to be included in the application configuration.

I discuss only plugins for WordPress CMS, Roundcube webmail and a module for Linux authentication.

All about the Yubikey OTP code

The Yubikey represents itself like an USB keyboard.  When pressing the Yubikey touch-button it generates a 44 character keystroke (the OTP code).  But what does these characters mean?  If you take a further look on the characters you will find out that some characters that exist on your keyboard will never occur in the Yubikey OTP code.  Remember that the Yubikey behaves like a keyboard.  But there are many keyboards and keyboard layout’s in the world, depending on your language.  The USA QWERTY keyboard starts with a ‘Q’, but a French AZERTY keyboard starts with an ‘A’.  It is not the keyboard device itself which send the letter to the computer, it depends on a software setting which defines the keyboard layout according your physical keyboard.  The Yubikey must co-operate with all existing keyboard layouts on the world, so it uses only the keys which are always on the same position, whether it’s a Swedish or a Spanish keyboard.

Next, you need to know is that each two characters represent one byte in hex code.  The algorithm to convert OTP code to hex is called ‘modhex’.  Details can be found here, a modhex converter can be found here.  So those 44 characters represent 22 bytes.  The modhex code ‘fjhk’ stands for ‘4869’ in hex which is ‘Hi’ in plain text.

The 22 bytes are split up in a static part and dynamic part.  The first 6 bytes (or 12 characters from the OTP code) represent a unique public ID for the Yubikey.  The next 16 characters represents a unique secret ID, a session counter, a timecode, a token counter, a pseudo-random value and a CRC-16 checksum.  These last 16 bytes are AES encrypted with a 128 bit key unique to each Yubikey.  The 128 bit AES key is assigned to your key during the manufacturing process by Yubico.  You cannot see the value of your AES-key, however, it is possible to create a new one and upload it to Yubico.

OTP Code (44 characters):

 ccccc*******vkiigurjtnhcrrgvhghniirrgvhghnii

• Unique public ID – This is the serial number of the Yubikey.  Use this to assign a key to a person.
• Unique secret ID (encrypted) – This is a unique secret ID only known by Yubico.
• Session counter (encrypted) – This is a counter which increments every time the Yubikey is plugged in.  Because it has two bytes the maximum amount of plugin’s is 65,536.  After that you are not able to generate OTP codes anymore and your Yubikey get worthless.  Anyway, it should be enough for anyone.
• Timecode (encrypted) – When the Yubikey connects to a system a 8 Hertz counter starts to count from 0.  The three bytes enables counting to 16,777,216.  After that you cannot create OTP codes until you unplug and plug it back in.  It takes about 24 days before this value is reached.
• Token counter (encrypted) – This counts the amount of generated OTP codes since the Yubikey is plugged in.  After 256 it will start to count from the beginning again and the generating of OTP codes can continue.
• Pseudo-random values (encrypted) – Random data to add to the plaintext data.  This makes it harder to guess the content of the other fields when all are encrypted.
• CRC-16 checksum (encrypted) – Checksum for error detection.

How does the YubiCloud work?

When logging in to a (web)application, your authentication data like username, password and Yubikey OTP code will be transferred to the application.  The application takes care of the username and password, but will send the OTP code along with some other information to the YubiCloud.  The YubiCloud will respond with information about the validity of the OTP code on which the (web)application allows or disallows access.

Based on the Yubico validation protocol v2.0 I created the authentication scheme below.

Authentication scheme for applications using the YubiCloud

1. The client application sends an authentication request to the application server.  Username, password and the Yubikey OTP code are transferred.
2. The application server handles the username/password locally.  To prepare transmission to the YubiCloud a random nonce is generated.  Next, a signature based on the client ID, OTP and nonce is generated using the HMAC-SHA-1 algorithm using the API-Key as the key.
3. Send the Client ID, OTP, nonce and signature to the YubiCloud.
4. The YubiCloud returns the OTP, nonce, timestamp, status and signature to the application.
5. If the signature and status are OK, authentication is successful, otherwise, authentication has failed.
6. Access is given or forbidden.

I captured the traffic between the application server and the YubiCloud with Wireshark.  The http session gives the following output.

Request from application server: (The info under the asterisks is hidden)

GET /wsapi/2.0/verify?id=8**3&nonce=splownaueiytkixwtkckyjpvqjovotnh&otp=ccccc********bukulkevkjffkngdendlufchlrtljdt&h=MJaY43HgmK983i0dO6LrwSfYyqQ= HTTP/1.1
User-Agent: ykclient/2.7
Host: api.yubico.com
Accept: */*

Reply from YubiCloud: (The info under the asterisks is hidden)

HTTP/1.1 200 OK
Date: Wed, 25 Jul 2012 19:19:15 GMT
Server: Apache/2.2.22 (Ubuntu)
X-Powered-By: PHP/5.3.10-1ubuntu3.2
Vary: Accept-Encoding
Content-Length: 170
Content-Type: text/plain

h=9oq/3sKgPyFvyTc1QEHZNv/dkVs=
t=2012-07-25T19:19:16Z0021
otp=ccccc********bukulkevkjffkngdendlufchlrtljdt
nonce=splownaueiytkixwtkckyjpvqjovotnh
sl=20
status=OK

← Back Next →