Understanding the YubiKey: A Distilled Introduction


If you are reading this it is likely that you have already heard of Yubico's YubiKey.

@YubiKey 4 | 0x300

You might have come across it after announcements from Google, Github and others declaring that they now support a stronger second factor authentication option called FIDO Universal 2nd Factor or U2F. Great! You know you want better security, especially better security that is easy to use!

So, you did a little deeper...


The YubiKey is a small, rugged, nearly indestructible keychain sized USB device that is able to securely store secrets and perform a number of cryptographic operations on behalf of the user. These cryptographic operations serve as the foundation of the advertised features of the YubiKey which I would categorize into two general buckets:

Multi-factor authentication (MFA) features

Specifically Universal 2nd Factor (U2F), OATH TOTP and HOTP, and Yubico OTP, and

Smartcard features

Specifically OpenPGP and PIV/X.509 based encryption and signing.

Since these features are implemented in a hardened USB device, the secrets for securing your online identity are much safer from rouge third-parties compared to a computer or mobile phone alone.


In this series of posts I will distill the many things I've learned while trying to grok the YubiKey and it's related security features. In this post I will introduce the YubiKey's features, use-cases, and relevant software just enough to allow a reader to decide if and how they want to use the YubiKey.

If there is interest, in later posts I will go into more technical detail about the security related features and their associated algorithms.

My Journey to YubiKey

If your experience getting started with YubiKey was anything like mine, it went something like this:

(**WARNING** this is a very non-distilled personal anecdote with some griping)

Great, I saw the announcement, I know I want security...I want a YubiKey! So I click to the YubiKey page and... woah! There are 4 devices! Which one do I need? The 4? The 4 Nano? The Neo? or the U2F key? I guess I came here for U2F but the features on the other keys are so enticing! "Strong crypto" and "touch-to-sign" sound like things I want...but the friction of these decisions have exhausted my energy to impulse buy. I file it away as sometime to revisit in the future.


I come across another YubiKey related announcement. Oh yeah, I want a YubiKey! Oh yeah, I don't know which one...too many choices. The 4 looks to be the newest so I'll get that one. Awesome!


I got my YubiKey! Let me set it up! The packaging directs me to this URL: http://yubi.co/4

@YubiKey 4 Landing Page | 0x500

The video gets me excited but this welcome page doesn't really help me start using my YubiKey. :( It directs me to the developer site...but I don't know what I would develop for the YubiKey because I still don't understand what it really is/does! Okay, I'll put it aside for now. I can revisit this in the future...


I have some free time, let me try to use that YubiKey thing again! A lot of the videos mention something called the "personalization tool". Okay, I'll get that! Uh oh! This is the most overwhelming piece of software I've ever seen! This looks like some sort of internal diagnostic utility not an end-user program. I am going to break this thing, I know it.

@YubiKey Personalization Tool

I could go on and on. Perhaps my path is atypical. For me, the YubiKey was something I wanted to integrate into my life as a security best-practice but I kept hitting roadblock after roadblock on a path that was further slowed by headache inducing cognitive friction. In hindsight, I believe everything you need to know to take full advantage of the YubiKey is indeed available on the Yubico site it just wasn't the easiest thing for me to assimilate.

The Device

As mentioned, the YubiKey is a small, lightweight USB device. As of this writing (August 2016), there are currently 3 generations being sold:

  • YubiKey 4
  • YubiKey NEO
  • FIDO U2F Security Key

The YubiKey 4 comes in two form-factors. One form-factor is a keychain fob sized device with dimensions 18mm x 45mm x 3mm (approx 0.7in x 1.8in x 0.1in). It can live on your keychain or in a desk. The other form-factor is smaller at 12mm x 13mm x 3mm (approx 0.5in x 0.5in x 0.1in) and is intended to semi-permanently reside inside of a USB port on your computer. This is useful if you intent to use the YubiKey a lot and would rather not have to plug it in multiple times a day. The downside though is that it monopolizes an entire USB port, which on Macbooks are at a premium. The two form-factors have exactly the same features and capabilities.

The YubiKey 4 feature-wise is a superset of the YubiKey NEO, specifically more encryption and more storage but with two notable exceptions:

(1) the NEO supports communicating via NFC in addition to USB which allows it to communicate with NFC enabled Android phones. This is a very compelling feature if you want to bring your YubiKey MFA protections to services that you use on your Android phone. This is in stark contrast to iOS which the YubiKey is effectively worthless with.*

(2) The YubiKey NEO is somewhat open source with it's use of freely available Java Card applets hosted on Github while the YubiKey 4 is not open source at all. People are varied with their reaction to this change; some have stopped recommending YubiKey altogether while Yubico argues there is a conflict between providing the most secure YubiKey and being open source. There are a lot of finer details relevant to this discussion so I recommend that anyone who is sensitive to the fact that the YubiKey 4 is closed-source read up on the discussions taking place.

The FIDO U2F Security Key is a simpler and cheaper device that only implements the U2F features described below.

This document focuses on the functionality provided by the YubiKey 4 and YubiKey NEO.

All devices have a single, capacitive touch surface on them. On the keychain form-factor it is the circular golden metallic indentation on the top surface of the device. On the Nano form-factor the touch surface is the curved end that protrudes slightly from the USB port. It is important to note that these touch sensors are not biometric in any way. They don't do fingerprint identification or anything like that. They are used because many of the YubiKey's features are initiated by a touch gesture or the feature requires a user to touch to device to confirm/allow an operation.

Features Overview

I think the YubiKey's features are best understood as falling into one of two categories: Multi-factor authentication (MFA) related features, and Smartcard related features.

Multi-Factor Authentication (MFA) features include:

  • Yubico OTP
  • Universal 2nd Factor (U2F)
  • Challenge / Response

Smartcard features include:

  • OpenPGP
  • PIV/X.509

The YubiKey also supports a feature called Static Password which I won't go into in this post. See the YubiKey Personalization Tool for more information.

Multi-factor Authentication Features

The majority of the press you've seen about the YubiKey probably focuses on features related to multi-factor authentication (MFA), specifically U2F and Yubico OTP. The YubiKey also supports time based one-time passwords (TOTP) and event based one-time password (HOTP). In these MFA use-cases the YubiKey can augment or replace the mobile app or SMS messages that may currently be used.

In the context of web authentication, multi-factor authentication is way to further secure user authentication to a site or service by requiring a personalized and unique code from a user in addition to their traditional static password. While static passwords are relatively easy for bad-actors to acquire (through phishing and/or malware), the secrets that generate these unique MFA codes don't readily leave the device they were generated on and thus are much harder to be duplicated and/or exploited by a third-party.

Different MFA algorithms use different pieces of information to generate their codes. I will briefly explain key aspects of each algorithm that the YubiKey supports.

Universal 2nd Factor (U2F)

Universal 2nd Factor (U2F) is a standard started by Google and Yubico as a modern MFA strategy that is easier for the user to use while providing higher security guarantees that other MFA techniques. The user experience on a U2F enabled site is such that after a user enters their password the user is directed to press the capacitive touch sensor on the YubiKey to finish authenticating. Behind the scenes, the YubiKey is generating a cryptographically secure value to authenticate the presence of the YubiKey.

The user experience of U2F is similar to Yubico OTP described below but with a key difference: U2F requires browser support to facilitate connecting to and using the YubiKey. Currently Google Chrome is the only mainstream browser to support U2F out of the box. Yubico OTP doesn't require browser support.

U2F is currently supported by the following services:

  • Google (Drive, YouTube, Wallet, Google )
  • Github
  • Dropbox
  • and a few others

The YubiKey works out of the box as a U2F device. No user configuration or intervention is required.

The specifics of how U2F works, how it is implemented, and how it is stronger than other MFA strategies is beyond the scope of this post but if you're interested Yubico has a very readable technical introduction to the U2F protocol.

Yubico OTP

Yubico OTP is a MFA strategy that utilizes a long 44 character string as the one-time password (OTP). An example of a Yubico OTP string is below:


The string changes on each press:


Third-party services can accept and validate Yubico OTP string by utilizing Yubico's online OTP Validation API or using one of the available plugins or libraries.

Sites that support Yubico OTP include:

  • Salesforce
  • Lastpass

The YubiKey supports Yubico OTP out of the box without requiring any user configuration. Yubico OTP has an advantage over U2F in that it doesn't require browser support. Yubico OTP's downsides include it being somewhat YubiKey specific while U2F is a standard and Yubico OTP being theoretically less secure than U2F.

Timer Based OTP (OATH-TOTP)

Timer based one-time passwords (OTP), known technically as TOTP, is an algorithm that computes a numeric 6 or 8 digit code based in part on the current time. Because of this, these TOTP values change at some frequency (usually every 30 seconds). If you are currently using MFA on any site, this is likely what you are currently using. It is the algorithm behind apps like Google Authenticator and Authy. On Google, the TOTP input screen looks something like this:

Google TOTP Input Screen

Because time is an input to the TOTP algorithm and the fact the YubiKey doesn't have an internal clock, TOTP codes can only be generated by the YubiKey with the help of a supporting application. The Yubico Authenticator software is a companion app that uses the computer's time along with secrets stored on the YubiKey to generate the current TOTP value for a particular site. The application is available on Windows, Mac, Linux and on Android.

Alt text

YubiKey 4 can store up to 32 TOTP or HOTP credentials while the YubiKey Neo can store up to 28.

Event Based OTP (OATH-HOTP)

Event based one-time passwords (OTP), known technically as HOTP, are very similar to the TOTP algorithm described above as they both produce numeric 6 to 8 digit codes except that instead of using time as an input to the algorithm, HOTP uses an incrementing counter. For this reason, HOTP values change on every request for an HOTP code.

There are two ways to configure an YubiKey to generate HOTP codes. First, you can use the same Yubico Authenticator app described above for TOTP. When adding the credentials, select the HOTP type instead of TOTP.

Alt text

Alternatively, HOTP codes can be emitted with just a finger press by using the YubiKey Personalization Tool.

In my opinion it is very unlikely you'll encounter a HOTP protected service.

Challenge / Response

The challenge / response feature of the YubiKey is a variant of both the Yubico OTP and HOTP features described above. I think it's usefulness is limited for a general internet user so I will avoid describing it in any detail. I recommend people read the YubiKey user manual for more information.

A YubiKey is not configured to handle challenge / response from the factory. The challenge / response feature is enabled and configured with the YubiKey Personalization Tool and initiated with a touch gesture.

Smartcard Features

The rest of the main YubiKey features revolve around a technology called a smartcard. A smartcard is a computing platform that traditionally lived in a credit card shaped form-factor and looked something like this:

Contact Smartcard

Smartcards commonly have a processor, memory and it's own operating system on the card. Smartcards traditionally interfaced with a computer via an external reader peripheral. There are standardized hardware protocols (CCID) and software interfaces (PC/SC) for programming and interfacing with these smartcards over USB.

Today, many vendors produce smartcards that are a single USB device instead of a smartcard and a separate USB reader. The YubiKey is one such device.

Both of the smartcard features described below, OpenPGP and PIV/X.509, enable workflows for establishing trust and privacy between semi-anonymous internet users. Through two cryptographic primitives, signing and encrypting, the OpenPGP and PIV/X.509 features help guarantee the following online:

  1. Something sent was actually sent by the stated person and not by an impersonator (*signing*)
  2. Something sent was actually sent by the stated person and not altered in transit (*signing*)
  3. Something sent to another will only be readable by the intended recipient and not a third-party (*encrypting*)

OpenPGP and PIV/X.509 features accomplishes this (in part) with the use of secret values (private keys) that should only ever be seen by their owner. The guarantees of these systems are only valid if these private keys remain secret.


OpenPGP is an open standard that specifies algorithms for the signing and encrypting data and establishing trust between semi-anonymous internet users. OpenPGP builds trust between internet users in a peer-to-peer fashion. Collectively, with the help of the network of OpenPGP users, a person can trust a larger group of people than they would be able to alone. This OpenPGP trust model contrasts with the X.509 model which is more hierarchical.

OpenPGP is generally used for:

  • Encrypting emails so as to be viewable only by the intended recipient
  • Signing emails to verify who authored the email
  • Signing software downloads to ensure they've not been tampered with

Instructions on using the YubiKey as an OpenPGP smartcard is beyond the scope of this article. Generally, you will be using the GnuPG command line tool. I found this blog post particularly helpful when setting up my personal YubiKey for OpenPGP.

Personally, the OpenPGP feature was the main motivation for me to purchase a YubiKey.


The United States federal government standard FIPS 201 specifies "Personal Identity Verification" (PIV) requirements for Federal employees and contractors. The YubiKey supports the FIPS 201 and PIV standards which may be used in government or large enterprise settings, but more generally, the YubiKey's PIV support allows the device to be used as a store for up to 24 (on the YubiKey 4) X.509 certificates and their associated private keys. This is useful for various X.509 use-cases not related specifically to PIV.

As mentioned, OpenPGP and X.509 both provide infrastructure for signing and encrypting digital content. While OpenPGP builds trust peer-to-peer, X.509 builds trust hierarchically. Specifically a user trusts a certificate authority and implicitly trusts any certificate the certificate authority trusts. The X.509 trust model is most commonly used for protecting websites (HTTPS/TLS/SSL).

Some use-cases that the YubiKey PIV/X.509 feature supports:

  • Setting up a certificate authority
  • Application signing for Apple (iOS, macOS)
  • Application signing for Android (jarsigner)
  • SSH authentication
  • Docker Content Trust

The PIV command line tool yubico-piv-tool page is probably the best resource for understanding the the usage of the PIV/X.509 features.


YubiKey Personalization Tool

Alt text

The YubiKey Personalization Tool is mainly intended to configure the touch initiated features of the YubiKey, specifically:

  • Yubico OTP
  • Static Password
  • Challenge-Response

Features like U2F, OpenPGP and OATH-TOTP aren't mentioned in this tool because as they are configured via other tools.

A YubiKey can be configured to support two of these touch initiated operations at a time. To uniquely select which of the two configured touch features a user intends when pressing the device the YubiKey supports two distinct touch gestures: a short press (0.3 - 1.5 seconds) and a long press (2.5 - 5 seconds). In various places, the personalization tool UI mentions programming "configuration slot 1" and "configuration slot 2", these correspond to programming the short and long press gestures respectively. Yubico programmed configuration slot 1 at the factory to emit Yubico OTP values.

The text along the top of the app "Yubico OTP", "OATH-HOTP", etc. are effectively UI tabs, with the first four tabs corresponding to the features mentioned above.

In general, it should be safe to experiment with programming configuration slot 2. If you see a section called "Configuration Protection" be sure to keep it unprotected OR use a value you can remember. Once a configuration slot is protected it cannot be modified or reset without the access code.

Yubico Authenticator

Alt text

The Yubico Authenticator is the helper application for adding and retrieving TOTP and HOTP codes from a YubiKey. Operation is pretty self explanatory. Generally one would use the "Scan a QR code" to populate the "Secret key" field.

NOTE: If you use a YubiKey to store TOTP or HOTP secrets, I recommend saving a copy of the "Secret key" value in a safe place just in case you lose access to your YubiKey. Additionally, you can also program multiple YubiKey's with the same secret key.

YubiKey Neo Manager

Alt text

Despite it's name, the YubiKey Neo Manager can be used with the YubiKey 4 in addition to the YubiKey NEO. This tool is used to alter the way the YubiKey presents itself to the USB bus. There are three connection modes possible:

  • OTP
  • U2F
  • CCID

All three modes are enabled by default since November 2015. It is unlikely you'll need to use this tool unless your YubiKey is older, in which case you'll likely want to enable CCID mode which allows the OpenPGP, PIV/X.509, and TOTP features.

YubiKey PIV Manager

Alt text

The YubiKey PIV manager allows a user to initialize the PIV device's PIN, PUK, and management keys as well as generate and/or import the PIV specification's 4 main certificate slots (Authentication, Digital Signature, Key Management, and Card Authentication). While the graphical interface is useful to managing PIV specific workflows, the yubico-piv-tool command line tool is what is used for more advanced X.509 workflows including Android and OS X code signing.


While the YubiKey can add a lot of value, there are a couple negatives that are worth mentioning.

First, the YubiKey is pretty much worthless for iOS (iPhone and iPad) use-cases. One isn't able to use U2F or TOTP codes with iOS. It may be possible to use Yubico OTP, HOTP, and static password features with iOS according to Yubico but I think that isn't a very realistic mobile workflow. Android fares a lot better, especially with the YubiKey NEO and it's NFC support. Either way, it is important to think about how securing services with a YubiKey might work if you want/need to access those services on your mobile devices.

Second, by design, a YubiKey's secrets, once stored on or generated by the YubiKey, cannot be extracted from the device. One will need to have a recovery plan should the YubiKey become lost or inaccessible for any reason. In the case of U2F, it is recommended that you enroll two separate YubiKeys. In the case of TOTP and HOTP, it is recommended that you store a copy of the secret value string somewhere safe and ideally offline. Similar precautions should be made when using the OpenPGP and PIV/X.509 features. The specifics of the recovery plan differ depending on the specific YubiKey feature and the online service it's being used with.


I hope this distilled (though admittedly still long) introduction to the YubiKey helps give you a metal model to understand and give shape to how a YubiKey can fit into your online security solutions.

Please feel free to leave comments below on any errors or omissions or about anything you'd like more information about. I will write follow-up posts based on interest.


2016-08-24 - Corrected statements about CCID being disabled; it is now enabled by default since November 2015 (Thanks Ronnie Manning from Yubico)