How to add one-time passwords to your own system for added security without investing in an expensive authentication infrastructure.
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 key-chain 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.
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.
Figure 2. Yubikey Size
Figure 3. Modified RoundCube Login Form UI
Figure 2. Yubikey Size
Figure 3. Modified RoundCube Login Form UI
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.
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.
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.
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 con tinuously 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.
Let's take a closer look at the encryption step of generating the token. In contrast to asymmetric algorithms used in public-key encryption schemes, such as PGP, AES is a symmetric algorithm. This means both the party encrypting the token and the party decrypting and validating it will need access to the AES-128 key! This sharing of the AES key happens when the device is programmed. Similar to the device's unique ID, the unique AES-128 key is generated and stored on the device by Yubico before it is shipped out. The company maintains a database where the unique public as well as secret IDs are associated with their corresponding AES keys. This way, Yubico is able to offer an authentication Web service.
Using a symmetric algorithm has the advantage that it is typically very fast. Also, you don't need to rely on third parties for key management or to vouch for identities.
If you want to be in charge of your own AES key, you have two options. First, you can request your AES key from Yubico. At the time of this writing,
Yubico will send you a CD containing the AES key, but the company also is working on a more convenient solution of retrieving the key on-line. Second, you can use Yubico's development kit to program the key yourself. This way, you can assign AES-128 keys, as well as public and secret IDs, according to your own naming conventions. If you supplement this approach by running your own authentication Web service, you eliminate any dependence on Yubico as a third party in your authentication procedure.
The Validation Algorithm: Order Matters
It's not surprising that the process of validating an OTP resembles reversing the steps necessary for constructing an OTP. A basic validation routine might look something like this. First, you ModHex decode the string. Next, you split the string into public ID and 16-byte token. Then, you use the public ID to look up the corresponding AES key. After using the AES key to decrypt, you have the original 16-byte token in plain text. Next, you would verify the CRC-16 checksum (the last two bytes). Then, you would compare the secret ID to the one you retrieved from the database using the public ID. Using the session counter and the session token counter, make sure that the current token was generated after the last successfully authenticated token. Although you don't know exactly when any two tokens were generated, you always can tell in which order they were generated. If the token passes all these tests, you can send a response signaling successful validation to the client. Otherwise, the token is rejected.
Optionally, you can harden the validation algorithm further. For example, you can try to calculate how many sessions or tokens have been skipped since the last successful validation and consider that information in your decision to validate or reject the token. You can use the session timestamp in a similar manner.
Yubico's Open-Source Approach
One thing I find really attractive about Yubico's business model is that it tries to provide all software in the form of open source. According to Yubico's statements, it plans to profit from the manufacture and sale of the devices, but intends to keep all software open source. For example, the source code for the aforementioned Web service is freely available as a reference implementation. Furthermore, Yubico offers client libraries needed for implementing Yubikey authentication in various applications and platforms. Currently, there are client libraries available in Java, C, C#/.NET, PAM, PHP, Ruby, Perl and Python. All these libraries and programs are set up as Google Code projects. Additionally, there are projects for libraries to decrypt OTPs in C and Java, as well as an Open ID server and a personalization tool to allow you to program your own Yubikey. Although all these software projects were initiated by Yubico, you already can see others contributing. Moreover, a number of independent open-source projects using the Yubikey technology have surfaced. Yubico's discussion forum is a good place to keep tabs on such projects and get support.
When you order a Yubikey, it comes ready to take advantage of Yubico's authentication Web service. Because Yubico maintains a database of all API keys, as well as public and secret IDs with which the Yubikeys have been programmed before shipment, Yubico has decided to offer an authentication Web service against those credentials. Developers then can use the Yubico authentication Web service to validate OTPs captured from the device. Yubico has a Web page where you can request an API key. Anyone can get an API key. The only requirement is that you
Listing 1. Typo: Blog-Wide Yubikey Settings HTML
Was this article helpful?