Yubikey One-Time Password Authentication

How to add one-time passwords to your own system for added security without investing in an expensive authentication infrastructure.

A number of factors inspired me to take a closer look at the Yubikey. For starters, it is such a simple and elegant solution to two of the major problems the security industry is facing these days: authentication and identity management. Furthermore, I really like how Yubico, the manufacturer of Yubikey, is trying to integrate the Open Source movement into its business strategy. In this article, I cover three topics related to this little device. First, I explain what the Yubikey does and how to use it. Second, I examine how it works. Third, I show how to integrate the Yubikey authentication service into your own infrastructure without too much trouble.

What Is It?

A Yubikey is a small plastic rectangle that basically consists of a USB connector and a button. It resembles a tiny USB Flash drive, and as it measures only 18x45x2mm and weighs only 2 grams, it easily can be carried on a keychain or in a wallet (Figures 1 and 2). When you plug it in to your machine's USB port, it identifies itself as a keyboard, implying that the Yubikey is platform-independent as long as the host device supports data entry via the USB Human Interface Device (HID) specifications. It draws power from the host device and, thus, does not have to depend on an internal battery. The whole device is quite compact and can be attached to an actual key ring using the small hole near the top of the device. The gold surface connectors are quite robust and are expected to last the lifetime of the device. According to a Yubico representative, Yubikeys still were usable after running them through a washing machine's cycle.

Figure 1. Yubikey Plugged In

Figure 2. Yubikey Size

Each time you press the button on the device, it generates a one-time password and sends it to the host machine as if you had entered it on a keyboard. This password then can be used by the service to authenticate you as a user.

How Do You Use It?

I use RoundCube to read my e-mail when I don't have access to my own system. RoundCube is an AJAX-centric Web-based e-mail client. You use it via your Web browser just as you might use Gmail or most other major on-line e-mail providers. Fortunately, RoundCube is open source and based on PHP, so it didn't take too much work to add Yubikey authentication.

Normally, RoundCube asks you to enter your e-mail address and password to log in. However, following a few modifications, the login screen now features a third field: Yubikey OTP (one-time password). Now, all you have to do is enter your e-mail and password as usual, position the cursor in the newly added text field, and put your finger on the Yubikey's button. After a second or so, the Yubikey magically spits out a 44-character sequence followed by a newline character. The newline character causes the form to be submitted. And, assuming that your Yubikey is indeed associated with your account, you will be logged in. Take a look at Figure 3, which shows the slightly modified login screen.

Figure 3. Modified RoundCube Login Form UI

For obvious reasons, the Yubikey should not be used as the only method of authentication. If that were the case, someone getting a hold of your Yubikey then would be able to access your Yubikey-enabled accounts provided that person also knows your corresponding login. However, if you use the Yubikey to add another attribute to a multi-attribute authentication scheme, it can increase security significantly. Imagine if you will, people monitoring your network traffic without your consent. They may be able to glean your password by examining captured TCP packets, but the Yubikey password they capture will be of no use to them, because it can be used only once! After you use a Yubikey password to log in somewhere, it becomes useless. In the next section, I explain exactly how this one-time password scheme works.

More Details

Let's take a closer look at the character sequence the Yubikey transmits to the host machine. Here's an example of a sequence generated by my Yubikey:


The above is actually a one-time password that is secured using AES-128 encryption and ModHex encoding. Let's take a look at how the Yubikey constructs this string. For the purpose of this discussion, refer to Figure 4.

Figure 4. Yubikey Token Construction

The device starts by creating a 16-byte sequence (Figure 4) where the individual bytes are allocated as follows:

  • The first six bytes hold the key's secret unique ID, which is assigned when a Yubikey is programmed. This ID is known only to the entity that assigned it and cannot be retrieved from the Yubikey. Six bytes translates into 2(6*8) = 281,474,976,710,656 unique combinations of bits, which is the number of Yubikey IDs that can be issued before Yubico has to think of a new scheme. Considering that this number exceeds the current world population by a factor of more than 42,000, Yubico is not likely to run out of unique IDs for some time, unless its business model is more successful than anyone could anticipate.

  • The next two bytes in our sequence, bytes 7 and 8, are used to store a session counter in nonvolatile memory. The counter starts at zero and is incremented each time the device is plugged in. Two bytes for the session counter allows for 2(2*8) = 65,536 sessions. In other words, you can plug in the Yubikey three times a day for almost 60 years before running out of session counters. Note that you can generate a significant number of OTPs during each session (see below).

  • The following three bytes, bytes 9 through 11, are used as a timestamp, which is stored in volatile memory during each session. That means each time the device is plugged in, the timestamp starts at zero and continuously increases. Because it is incremented by an internal 8Hz clock, timestamp values will be exhausted after about 24 days. At that time, you need to unplug the Yubikey and plug it back in.

  • Byte 12 in the sequence is a session counter that starts at zero and is incremented by one each time a token is generated. When it reaches that maximum value of 255, it wraps back to zero.

  • Bytes 13 and 14 in the sequence are pseudo-random numbers provided by a free-running oscillator. These bytes are used to add additional entropy to the plain text before subjecting it to the cypher.

  • The last two bytes, numbers 15 and 16, contain a checksum using the CRC-16 algorithm over all values of the token with the two checksum bytes set to zero. This checksum is used for data-integrity checking.

Each time the Yubikey is invoked, it generates the 16-byte sequence described above. However, if you look at the sample Yubikey output previously listed in this article, you will notice that it actually consists of 44 characters. That is because we still are missing three crucial steps before the Yubikey is ready to spit out the final token. First, the 16-byte token is encrypted using an AES-128 key that is unique to each Yubikey. Second, the Yubikey prepends the encrypted 16-byte token with a six-byte plain-text public ID. This public ID is completely different from the secret ID used to construct the 16-byte sequence. The public key does not change and can be used to associate a Yubikey token with an account. Finally, the whole 22-byte sequence (16 bytes encrypted plus six bytes public ID) will be encoded using the not-so-well-known ModHex algorithm.

Yubico chose this algorithm simply because it is limited to characters that are common to many different keyboard layouts. Because the Yubikey impersonates a keyboard, it tries to use characters that work with the various keyboard settings it might encounter in the wild. The disadvantage is that ModHex encoding is somewhat inefficient in that it requires two characters for each byte it encodes, which is why a 22-byte sequence turns into a 44-character sequence. However, as the Yubikey does all the typing, this does not translate into an inconvenience for users.



Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

bad link

Christian Peper's picture


the link to supported apps is broken.
http://yubico.com/applications/software/ is the correct one


Swekey's picture

Hi Dirk,

If you are interested in authentication you should also have a look on the swekey.

It is a totally different approach than the Yubikey.

If you want a free sample for evaluation I'll be happy to send you one...



2 step authentication

Anonymous's picture

What is to prevent the attacker from simulating the response to the first step? More than a simple challenge to the user will be too much of a burden to the user, while a simple challenge will likely be easy to work-around.

I would suggest using the Yubikey device with HTTP Digest Authentication. Of course, the Yubikey OTP will have to be entered in the User Name field, not the password.

It is 10 dreams come true!

Jane's picture

Secure, elegant, and innovative!


Keep the good work!

Geek Guide
The DevOps Toolbox

Tools and Technologies for Scale and Reliability
by Linux Journal Editor Bill Childers

Get your free copy today

Sponsored by IBM

Upcoming Webinar
8 Signs You're Beyond Cron

Scheduling Crontabs With an Enterprise Scheduler
11am CDT, April 29th
Moderated by Linux Journal Contributor Mike Diehl

Sign up now

Sponsored by Skybot