Yubikey One-Time Password Authentication | Linux Journal (2024)

Security

A number of factors inspired me to take a closer look atthe Yubikey. For starters, it is such a simple and elegant solution totwo of the major problems the security industry is facing these days:authentication and identity management. Furthermore, I really like howYubico, the manufacturer of Yubikey, is trying to integrate the OpenSource 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 theYubikey authentication service into your own infrastructure without toomuch trouble.

What Is It?

A Yubikey is a small plastic rectangle that basically consists of aUSB connector and a button. It resembles a tiny USB Flash drive, andas 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 isplatform-independent as long as the host device supports data entry viathe USB Human Interface Device (HID) specifications. It draws powerfrom the host device and, thus, does not have to depend on an internalbattery. The whole device is quite compact and can be attached toan actual key ring using the small hole near the top of the device. Thegold surface connectors are quite robust and are expected to last thelifetime of the device. According to a Yubico representative, Yubikeysstill were usable after running them through a washing machine's cycle.

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

How Do You Use It?

I use RoundCube to read my e-mail when I don't have accessto 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 othermajor on-line e-mail providers. Fortunately, RoundCube is open sourceand based on PHP, so it didn't take too muchwork to add Yubikey authentication.

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

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

More Details

Let's take a closer look at the character sequence the Yubikey transmitsto the host machine. Here's an example of a sequence generated bymy Yubikey:

tlerefhcvijlngibueiiuhkeibbcbecehvjiklltnbbl

The above is actually a one-time password that is securedusing AES-128 encryption and ModHex encoding. Let's take a look at howthe 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) wherethe individual bytes are allocated as follows:

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

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

More about Encryption

Let's take a closer look at the encryption step of generating the token. Incontrast to asymmetric algorithms used in public-key encryption schemes,such as PGP, AES is a symmetric algorithm. This means both the partyencrypting the token and the party decrypting and validating it willneed access to the AES-128 key! This sharing of the AES key happens whenthe device is programmed. Similar to the device's unique ID, the uniqueAES-128 key is generated and stored on the device by Yubico beforeit is shipped out. The company maintains a database where the uniquepublic as well as secret IDs are associated with their correspondingAES keys. This way, Yubico is able to offer an authentication Web service.

Using a symmetric algorithm has the advantage that it is typically veryfast. Also, you don't need to rely on third parties for key managementor to vouch for identities.

If you want to be in charge of your own AES key, you have twooptions. First, you can request your AES key from Yubico. At the time of thiswriting, Yubico will send you a CD containing the AES key, but the companyalso is working on a more convenient solution of retrieving the keyon-line. Second, you can use Yubico's development kit to program the key yourself. This way, you can assignAES-128 keys, as well as public and secret IDs, according to your ownnaming conventions. If you supplement this approach by running your ownauthentication Web service, you eliminate any dependence on Yubico asa third party in your authentication procedure.

The Validation Algorithm: Order Matters

It's not surprising that the process of validating an OTP resembles reversingthe steps necessary for constructing an OTP. A basic validation routine mightlook something like this. First, you ModHex decode the string. Next, yousplit the string into public ID and 16-byte token. Then, you use the public IDto 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 verifythe CRC-16 checksum (the last two bytes). Then, you would compare the secret IDto the one you retrieved from the database using the public ID. Usingthe session counter and the session token counter, make sure that thecurrent token was generated after the last successfully authenticatedtoken. Although you don't know exactly when any two tokens were generated,you always can tell in which order they were generated. If the tokenpasses all these tests, you can send a response signaling successfulvalidation 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 skippedsince the last successful validation and consider that information inyour decision to validate or reject the token. You can use the sessiontimestamp in a similar manner.

Yubico's Open-Source Approach

One thing I find really attractive about Yubico's business model is thatit tries to provide all software in the form of open source. According toYubico's statements, it plans to profit from the manufacture and sale ofthe devices, but intends to keep all software open source. For example,the source code for the aforementioned Web service is freely availableas a reference implementation. Furthermore, Yubico offers client librariesneeded for implementing Yubikey authentication in various applicationsand platforms. Currently, there are client libraries available in Java,C, C#/.NET, PAM, PHP, Ruby, Perl and Python. All these libraries andprograms are set up as Google Code projects. Additionally, there areprojects for libraries to decrypt OTPs in C and Java, as well asan Open ID server and a personalization tool to allow you to programyour own Yubikey. Although all these software projects were initiatedby Yubico, you already can see others contributing. Moreover, a numberof independent open-source projects using the Yubikey technology havesurfaced. Yubico's discussion forum is a good place to keep tabs onsuch projects and get support.

The Yubico Authentication Service

When you order a Yubikey, it comes ready to take advantage of Yubico'sauthentication Web service. Because Yubico maintains a database of all APIkeys, as well as public and secret IDs with which the Yubikeys have beenprogrammed before shipment, Yubico has decided to offer an authenticationWeb service against those credentials. Developers then can use theYubico authentication Web service to validate OTPs captured from thedevice. Yubico has a Web page where you can request an API key. Anyonecan get an API key. The only requirement is that you have to submita valid Yubikey OTP. This is merely a measure to avoid database bloatfrom too many bogus requests. The API key also comes with an ID number.

The purpose of the API key is to sign/verify requests to/from the Yubicoauthentication Web service using the HMAC-SHA1 hashing algorithm. This isdone because support for SSL is often spurious in the various environmentsin which the Web service client libraries have to function. Note thatit is not strictly necessary to use SSL, because the token alreadyis encrypted! However, as an added precaution, SSL should be used as atransport layer whenever it is available. In the PHP client library,for example, all you have to do is add an s to http where theauthentication server URL is specified.

Adding Yubikey Authentication to Typo

Now that we have a solid understanding of the underlying technology,let's add Yubikey authentication to an existing application. I useTypo to blog. Typo is developed using Ruby on Rails, and you can check out its latest codebase via the project's public Subversionrepository. Whether or not you like the structure RoR imposes on thedeveloper, it works to our advantage in this case, because it makes iteasy to locate the files we need to modify. Take a look at Figure 5for a basic outline of the validation routine we will be implementing.

To start, let's drop the Ruby Web services client library, yubico.rb,into the project's lib directory. After adding the correspondingrequire command to the config/environments.rb file, we can be assuredthat the library will be available throughout the application.

Two groups of settings are necessary to configure Yubikey authentication.First, there are the site-wide settings, namely the APIkey and corresponding ID necessary to submit authentication requests tothe Web service. There also is a switch for enabling or disabling Yubikeyauthentication on a blog-wide level. Typo stores these blog-specificsettings by serializing them and persisting them to the blogs.settingscolumn. Lucky for us, that means we don't have to make any changes tothe database. However, we do need to amend the UI and data model used tostore these settings within the application. Listing 1 shows how to addthese three Yubikey configuration options to the respective HTML templatein the admin user interface. Similarly, Listing 2 shows how to add thosesame settings to the model. That's all it takes for Rails to render a formto input those settings and store them in the database for each blog. Figure 6 shows the final result.

filename: app/model/blog.rb... # Authentication setting :yubikey_required, :boolean, false setting :yubikey_api_id, :string, '' setting :yubikey_api_key, :string, ''...

Second, there are two user-specific settings: Yubikey ID and YubikeyRequired. The former is necessary to associate a Typo account with auser's unique public Yubikey ID; whereas the latter allows users toenable Yubikey authentication selectively for their accounts only. Now,let'smake both options available from the user's preference settings withinthe application's admin interface. To make the new options appear inthe UI, I added a new section to the partial HTML template that rendersthe form for editing user options (Listing 3). Thanks to RoR'sActiveRecord support, we don't need to write any code to save thesenew options to the database; however, we do need to make sure that weadd the correspondingly named fields to the user table to which allvalues on this screen are being persisted. In Rails, this is done byadding a database migration, which is nothing more than an abstract wayof describing an incremental modification to the database. In our case,we are adding the fields yubikey_id and yubikey_required to theuser table by creating the migration shown in Listing 4. Now, all you needto do is run the rake utility from the command line and tell it toupgrade the database: rake db:migrate. The nice thing about Rails'migrations is that they are database-provider independent. The migration wecreated in Listing 4 can be used with any of the underlying databasesthat Typo supports. At the time of this writing, this includes MySQL,PostgreSQL and SQLite. Finally, you can admire the new settings in theaccount-specific options in Figure 7.

filename: db/migrate/071_add_yubikey_columns_to_user.rb:class AddYubikeyColumnsToUser < ActiveRecord::Migration def self.up add_column :users, :yubikey_id, :string, :null => false, :default => '' add_column :users, :yubikey_required, :boolean, :null => false, :default => false end def self.down remove_column :users, :yubikey_id remove_column :users, :yubikey_required endend

Now that we have the setup all taken care of, we can focus on the actualauthentication during login. First, let's add a Yubikey OTP input fieldto the login screen provided that Yubikey authentication is enabled forthe whole blog. I have done this by modifying the partial template thatrenders the login form in Listing 5. Notice that we always have to showthe Yubikey OTP field during login, because until users supply theiruser names, we don't know whether Yubikey authentication is required fora particular user. Figure 8 shows the modified login screen.

Whenthe login form is submitted, Rails routes it to the login method ofthe AccountsController class (Listing 6). This is where we add thelogic to check whether we need to handle Yubikey authentication. Afterthe existing code has verified the regular login and password, wenow have an instantiated user object that can tell us whether Yubikeyauthentication is required for this user. If so, we invoke the staticmethod authenticate_yubikey of the user object. Looking at Listing7, we check that neither the Yubikey OTP from the login form nor theuser's public Yubikey ID are blank. Moreover, by definition, the first12 characters of the OTP have to match the public ID associated withthe account. If everything is in order, we instantiate a Yubico object,which will handle the Web service authentication request for us. Themethod simply returns a boolean. True means the user was authenticatedsuccessfully. Conversely, false implies an invalid OTP or an attempt byan unauthorized user—possibly an attempt to hack into the account.

filename: app/model/user.rb... # Authenticate a user's Yubikey ID. # # Example: # @user.authenticate_yubikey(this_blog, 'thcrefhcvijl', # 'thcrefhcvijldvlfugbhrghkibjigdbunhjlfnbtvfbc') # def authenticate_yubikey(this_blog, yubikey_id = '', yubikey_otp = '') if (yubikey_id.empty? || yubikey_otp.empty? || !yubikey_otp[0, 12].eql?(yubikey_id)) return false else begin yk = Yubico.new(this_blog.yubikey_api_id, this_blog.yubikey_api_key) return yk.verify(yubikey_otp).eql?('OK') rescue return false end end end...

That's it! My Typo blog is now Yubikey-enabled. I will be submitting apatch to make these changes permanent by integrating them into theTypo codebase.

Implementation Variations

You might want to consider a few variations whenimplementing Yubikey authentication. First, you can choose to omit theuser name, because the Yubikey token already includes a public ID thatcan be used to link to the user's account. This scheme works as long asyou are not allowing users to associate a single Yubikey with multipleaccounts.

Second, you can minimize modifications required to the UI of existingsystems by including the Yubikey token in the password field. Becausethe OTP is of fixed length, it stands to reason that the remainingcharacters belong to the password. Also, as the Yubikey appends anewline character to the token, users would have to type their passwordfirst, followed by the OTP—rather than the other way around.

Third, you might want to consider making login a two-step process. First,prompt the user for the OTP and validate it. If the validation requestis approved, prompt the user for the regular login and password. To seethe advantage of this approach, consider the scenario in which username, password and OTP are submitted simultaneously. If maliciousparties are able to intercept the submission and prevent the OTP from beingsubmitted to the validation server, they effectively have all three piecesof information they need to penetrate the system to which you are tryingto authenticate. However, if you submit the OTP only during the first stopof the login process, malicious parties can intercept the token withoutgaining access to the system because they do not have the correspondinguser name and password. To make you supply the user name and password,they need to let the OTP pass through and be validated, which also makesthe OTP useless for subsequent uses. Thus, the attackers' task will becomplicated significantly.

Yubikey in the Wild

On its Web site, Yubico maintains a growing list of applications andservices that take advantage of the Yubikey. There is a plugin forWordPress, SSH integration, phpBB forum access and Windows login(commercial beta). As the above example of integrating the Yubikey intothe Typo blog software's authentication routine shows, the process isfairly straightforward. Hopefully, this article inspires you to use thisas a starting point to make your favorite piece of open-source softwaremore secure by adding Yubikey authentication.