You may have seen it used by your colleagues. You may have seen it used by your friends working for big companies with tight security. Neat little black USB devices with a small “y” in a golden circle (or an inverted Half Life looking lambda) attached to their laptops, sometimes hanging on a keychain. But what is it?

Before we move onto what this little device is used for let’s talk about two-factor authentication and why you should have it on all your online accounts.

Two-Factor Authentication (2FA)

Once upon a time the only thing keeping unauthorized individuals from accessing your online accounts was a password. The problem with a password is that it’s usually very simple. How simple? Well, see for yourself. And even if you do use a strong and complex password there is more than one way to get that password from you. Then there is nothing standing between an attacker and your precious data. That is why the 2FA that we recognize today was first made commercially available by the RSA company as a key device in 1986. The device had a small LCD screen that displayed a short numerical code which you would append to your passwords. Many large corporations and government entities used this type of extra protection for their internal system. Some schools here in Sweden have similar devices (of course, modern versions) handed out to their teachers even today so that they can securely access student data. Yet, it was not until 10 or so years ago that the concept became wide spread on the Internet.

Google was one of the first major corporations to roll out this feature to their public service due to Chinese government targeting them and other US based companies with a sophisticated persistent attack. It didn’t take long before other companies started introducing 2FA onto their platforms.

Now, you may wonder why is it called two factor (or multifactor) authentication in the first place? That is because there can be multiple different ways for you to authenticate yourself:

• Something you know: A password, passphrase, PIN, or a security question.
• Something you have: A one time token you received by SMS, a keycard, an RSA token, or a smartcard that you possess.
• Something you are: Your fingerprint, retina scan, or other biometric properties.
• Something you do: How you type, breathe, walk, look and other patterns unique to you.

I an ideal scenario you would use at least 2 of these which makes it extremely hard for an attacker to breach your account. Even if they were able to know your password, which is not hard if your password is 123456, they would need something only you have to complete the authentication.

All 2FA are equal, but some 2FA are more equal than others

This text will largely focus on the second item on that list above, something that you have. For you see, not all the things that you have are equally secure. One of the most common 2FA solutions in the beginning was an SMS. Remember, convenience is the biggest enemy of staying secure and what is more convenient than an SMS? By the time 2FA was rolling out the majority of humankind possessed a mobile phone, and they all could get an SMS. So, a lot of companies started using SMS to send a one time token to their users that they, in turn, used to complete authentication on the service. The problem is, SMS was never made to be secure. It is a plain text system for sending short messages and nothing more. I could now spend the rest of this text explaining why SMS is not to be used as 2FA, but I will not do that. I will let other people, who have done a proper research, do that for me.

It wasn’t long before companies started dropping SMS as 2FA and keeping it as a backup option. Some even completely removing it from their system (well done!). This brings us to various 2FA applications that you can install on your phone. The most known is Google Authenticator. It is a simple tool that will generate one time codes that you use to access your services, not just Google. I need to stress this here, Google Authenticator can be used on any service that uses OTP, not just Google. [digression] You may find this statement funny, but you will be surprised to know that there aare a lot of people who have multiple authenticator apps on their phone - one for Google, one for Microsoft etc. Why? Because when they created 2FA each service suggested their own brand of authentication apps. They didn’t make it clear (for obvious reasons) that you can use just about any application for the job.[/digression]

These applications are pretty convenient, and they do a good job. The problem is that most of them are only on your one phone. They do not offer a possibility of synchronisation with other devices making it easy to have a backup option in case your phone gets lost or stops working. There are options like Authy that are cloud based. However, for a lot of companies using such a service will not be an option. For those using Apple devices I can warmly recommend an app called OTP Auth that uses your iCloud to sync/backup your OTP codes.

Then there are password managers. I will not go into why using a password manager is important. However, I will point out that a lot of them, from online services such as 1Password or Bitwarden, to offline tools such as KeepassXC or MacPass, offer to keep your 2FA codes as part of your account data. Depending on your threat model this may not be the best option as keeping all the eggs in one basket may blow up in your face.

Little black key

Note: All these keys offer the same features, they are just for different slots on your computer. I recommend you do the Yubico quiz to determine which one is the best for your needs.

This finally brings us back to the subject of this text - Yubikey. Before I dive into what you can do with this neat little device it is proper to give it an introduction.

Yubikey is an authentication device produced by a US/Swedish company called Yubico. The company was founded by a Swedish couple, Stina Ehrensvärdand Jakob Ehrensvärd, back in 2007. The device was designed with multiple functionalities in mind: One Time Password, public key cryptography, Universal 2nd Factor (U2F) and FIDO2 protocols. According to Wikipedia, Yubico’s explanation of the name “YubiKey” is that it derives from the phrase “your ubiquitous key”, and that “yubi” is the Japanese word for finger.

Yubico offers wide variety of devices, and it may be a little overwhelming when deciding which one to use. They offer a tool that is supposed to help you with the decision. It all comes down to what types of devices you will be using the key on. Just laptops? Then USB-A and USB-C should be enough. Mobile devices too? Then NFC edition is the one to go for. Either way, I highly recommend buying two Yubikeys as a way to have a safe backup in case you lose your main key.

So, what can you do with this device and why would you use this instead of a phone? Those are very good questions. To answer the first one, let me say that there is a lot packed up in this little device. How much will you use in the end depends on your needs and your levels of nerdiness in the blood. The details will come in a few moments.

Why is it better than the phone? For me this comes down to one thing - phones are hackable-always-online devices. I do not trust my phone too much. It does a good job at what I need it to do, but I don’t keep anything confidential or sensitive on it. Even though I tend to update my phone on time and to change it before it stops being supported. Majority of people out there are using phones without updating them or phones that are no longer being updated by the manufacturer. They download all sorts of applications without checking who made them. They visit all sorts of shady websites or click on links that their friends or complete strangers online send them. That means that keeping the 2FA application on a compromised device is like sending them directly to an attacker. Or let’s look at this scenario - your phone dies. All your 2FA codes are gone because there was no backup. There is the security aspect to consider. More than once OTP has been bypassed. And there were(are) even services offering help with that. I would also recommend reading a nice comparison between OTP and FIDO2 protocol, for more details.

With that out of the way let’s see what can we do with this little black key. The first couple of usages will be understandable to non-technical people. However, as we move through the options the instructions will require more technical skills to be performed. If at any point you stop following what I’m saying that’s fine, this text is for all levels of technical knowledge. If you end up using just 1-2 features you will be hardening your security tremendously. I do recommend you try all the options listed here no matter how much or little you think you know. Worse case scenario, you will learn a lot of new things.

This text assumes the following:

• You are using MacOS and Apple Silicon (M1/M2) architecture
• You use MacPorts or Homebrew, though all Yubico tools can be downloaded from their site
• You have 2 Yubikey 5 devices, one that you will use every day and one, backup, that you will keep somewhere safe
• [for advanced user] You have GPG installed

The first few instructions will work on all operating systems. The rest will work pretty much verbatim on GNU/Linux and I honestly have no idea how they would be done on Windows.

Touch the key to access the website

The most common, and probably the first feature Yubikey offers is to be used as 2FA on a website. Let’s assume that you want to protect your Google Mail with 2FA. You can, of course, use Google Authenticator to generate One-Time Passcode. However, Yubikey offers the strength of FIDO2 and WebAuth protocols to strengthen 2FA process. What you want to do is the following:

• Go to https://myaccount.google.com/ and login
• Proceed to Security and then scroll down to Signing in to Google
• Proceed to 2-Step Verification
• You will be presented with various options, including SMS (I would remove SMS).
• Select Security Key and choose Add security key

All the main browsers will at this point show a window asking you to touch your Yubikey. If you do that the key will be added as an authentication method in your Google Mail.

That’s it! From now on when you log in to Google Mail using your password a small window will appear asking you to touch Yubikey in order to authenticate. You should at this point add your second key too.

One-Time Passcode on Yubikey

I’ve mentioned various apps that you can install on your phone that will generate short-lived digital codes that you can use as 2FA for various websites. However, Yubikey can do that too. This process is somewhat more secure in my opinion as you need both an app and Yubikey to get to the codes. Yubico offers their own application for OTP use called Yubico Authenticator. So how does this work? Let me use Google Mail as an example again, but the process will be similar on most services.

• Install Yubico Authenticator for your platform (all major platforms are supported)
• Connect Yubikey to your device and start Yubico Authenticator
• Go to https://myaccount.google.com/ and login
• Proceed to Security and then scroll down to Signing in to Google
• Proceed to 2-Step Verification
• Select Authenticator app this time
• You will be presented with a QR code that you are supposed to scan
• In Yubico Authenticator app click in the upper right corner and select Add account, this will present you with multiple options. You can Scan the QR code on the screen, or you can click on Can’t scan it? and Google will provide you with a Secret key that you can copy/paste into Yubico Authenticator. You can repeat this process for both keys.
• (Optional) Yubico Authenticator can be setup to require a touch before OTP is used. All you need to do to enable this feature is to select it in the lower left corner of Yubico Authenticator window when adding a new OTP.

Remember, Yubico OTP functionality allows you to write your OTP once and then only delete it. You can not edit it. With this in place you now have your OTP stored on the key and all you need to do to see the tokens is connect your Yubikey to a device that has Yubico Authenticator installed. For additional security you may want to set a password in the Yubico Authenticator (upper right drop down menu, option 2) which wil require typing that password before your OTP codes are revealed.

The limitation of this feature is that it has only 32 slots available for OTP. If you have more sites you want here then using a phone app or even password manager might be a better option. My approach to this matter is that Yubikey is used only for services of high importance. I will not keep OTP for some random tech web forum on it.

Passwordless logging into websites (kind of)

This next step is very straight forward. Some websites, not too many yet, have full support for FIDO2 and WebAuth API in your browser allowing you to authenticate just by having your Yubikey. No password needed. Some websites may require you to insert FIDO2 PIN instead of the password.

I will make a short stop here and introduce another tool Yubico provides - YubiKey Manager. This tool allows you to make various modifications to your key. Most importantly, add/change PIN codes that will unlock your key for use. If you install the tool and go to Applications and then FIDO2 in the drop-down menu of the app, you will be presented with an option to set FIDO2 PIN. This is an additional protection so that you need to type a short numerical key, that only you know, before the key is used for passwordless logging in. This is not necessary, but it can be considered a good security practice.

Log into your operating system using the key

Most modern operating systems support logging into the system using smart cards. Smart cards usually look like credit cards with a chip. They contain certificate which is unlocked using a PIN code. Well guess what? Yubikey can work as a smart card too!

Before we set it up for this purpose, let’s use YubiKey Manager once again. This time click on the Applications and then PIV. You will be presented with three options: setting up PIN/PUK for the key, setting up certificate and resetting the whole thing. Let us set up the PIN and PUK first. The key comes with the default values for PIN (123456) and PUK(12345678). PIN is what you will be using to log into your computer. PUK is an administrative code that you can use to unlock the key if you, for some reason, make 3 mistakes when entering PIN code. So, set these codes to something you will remember. Even better, put them in a password manager.

With PIN/PUK set, go to setting up the certificate. All you have to do here is click on Generate. These certificates can, luckily, be backed up, so you may wish to Export them once you are done. Up to you.

With this in place, go back to the main PIV menu and click on Setup for MacOS in the upper right corner. Follow the instructions and you are done.

There is one more thing that those working in terminal a lot can do at this point. You can use the same PIV PIN for sudo commands. For that to work add the following to /etc/pam.d/sudo:

auth       sufficient     pam_smartcard.so

From now on, when you use sudo you will be asked for your PIV PIN instead of having to type the long and strong password that you are using for your MacOS.

Touching the key barfs out a lot of strange characters

I can bet that if you are new to Yubikey you have touched it by accident while writing something and a bunch of random characters got printed on your screen out of nowhere. No worries, this is something you can control. Go back to YubiKey Manager and then to Applications and then OTP. You will be presented with two options, long and short touch. Each can do different things. If you don’t need those simply chose Delete and the key won’t be throwing string when you press it by accident. However, you can set up Static password so that touching the key inserts the whole password. I don’t recommend this, but it’s doable. You can experiment a little with this. Perhaps you want to have part of the password on the key and the rest you type i.e. 1Password can ask you to type in your strong and long password one time too many, and you decide to keep a part of it on the key and then type the rest. Or something like that. You can, of course, turn this completely off and then Yubikey will not print anything when you touch it by accident.

Keeping SSH keys on the key

By this point you will not be surprised to learn that Yubikey supports SSH keys too. I personally don’t use that feature as it is designed, but it can be useful to some of you. Yubico has an official guide for this feature that you can find here.

Yubikey and GPG FTW

I have remarked in the previous paragraph that I don’t use the SSH feature as described in the documentation. I prefer to extract my SSH key from a GPG key. This now brings us to the last and the most complex part of this test. This will require working in the terminal and understanding cryptography. If you have no idea what I’m talking about then you better no do things I’m about to explain. Or, even better, do them and learn something new. Don’t worry, you can always reset your Yubikey to its factory state.

So, let’s go.

If you are an advanced user, and you skipped YubiKey Manager steps I’ve talked about earlier you will want to do the following first.

• Insert your Yubikey into the computer
• Run: gpg --card-edit
• If you get gpg: OpenPGP card not available: General error, check if YubiKey Manager is running. The key is not available for other tools while the Manager is running.
• You will be presented with various information about your card i.e. serial number, version etc.
• Type admin and you will be presented with Admin commands are allowed, this will allow changing various things on your card. Typing help will give you all the options
• Type: passwd You will be asked to insert the existing PIN and Admin PIN (PUK), they are 123456 and 12345678 respectively. Change them to something you will remember, or even better, write it in your password manager. You will be asked for a PIN for various things i.e. signing your Git code with GPG, using SSH key etc. You can make 3 mistakes before the key gets locked down. You will need to use Admin PIN/PUK to unlock it.
• Type key-attr - change this from RSA to ECC. RSA is good, but ECC is better. Elliptic Curve Cryptography (ECC) provides an equivalent level of encryption strength as RSA (Rivest-Shamir-Adleman) algorithm with a shorter key length. As a result, the speed and security offered by an ECC certificate are higher than an RSA certificate for Public Key Infrastructure (PKI).

At this point you have two choices, you can generate your GPG key directly on the device, or you can exit, create the keys on your own and then write them to the device. If you want to have the same GPG key on both Yubikey devices, the second option is better. I will now cover the first option.

• Type generate and follow the instructions. The public key will be saved on your computer at the end.
• Exit the card

[The following steps should be done after finishing the manual import of the keys from the next section]

• Edit ~/.gnupg/gpg-agent.conf and add the following:

  default-cache-ttl 300
  default-cache-ttl-ssh 300
  max-cache-ttl 3600
  max-cache-ttl-ssh 3600
  write-env-file ~/.gnupg/gpg-agent-info
  enable-ssh-support
  use-agent
  personal-cipher-preferences AES256 AES192 AES CAST5
  personal-digest-preferences SHA512 SHA384 SHA256 SHA224
  cert-digest-algo SHA512
  default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
  

We will now need our GPG agent to be able to actually use the data on the Yubikey. If you use Bash or Zsh add the following to your .bashrc/.zshrc files:

export "GPG_TTY=$(tty)"
export "SSH_AUTH_SOCK=${HOME}/.gnupg/S.gpg-agent.ssh"

If you, like me, use fishadd the following to your config.fish:

gpgconf --launch gpg-agent
set -e SSH_AUTH_SOCK
set -U -x SSH_AUTH_SOCK ~/.gnupg/S.gpg-agent.ssh

Restart your terminal and then restart GPG agent using the following commands:

gpg-connect-agent killagent /bye
gpg-connect-agent /bye

That is it. You can now put your public GPG key into GitHub/GitLab and sign your commits using Yubikey or when pulling down code from private repositories. You will be prompted for the PIN each time. At this point you can extract the public SSH key by inserting the key into the computer and running:

ssh-add -L

This command will give you ssh-ed25519 that you can use to access remote servers using SSH for example.

And at this point we could call it a day, but we are adventurous, and we want more from life, right? Right. I will refer you the previous section and the step of typing key-attr. Once you do that, stop and exit.

The following can be done in multiple ways. I will give a general step-by-step guide, and you can adjust it to your needs and levels of paranoia. You can find different tutorials online for this step. I like to keep things simple.

• Run: gpg2 --expert --full-gen-key
• Choose: ECC (sign only)
• Once done export key ID: export KEYID=XXXX(bash/zsh) or set -x KEYID XXXX(fish)
• Create revocation cert: gpg --gen-revoke $KEYID > ecc_revoke.txt
• Backup master key: gpg --armor --export-secret-keys $KEYID > ecc_master.key
• Create subkeys - gpg --expert --edit-key $KEYID:
  • Type: addkey –> ECC (sign only)
  • Type: addkey –> ECC (encrypt only)
  • Type: addkey –> ECC (set your own capabilities) and choose just Sign
• Save and list the keys: gpg --list-secret-keys
• Export subkeys:
  • gpg --armor --export-secret-keys $KEYID > ecc_mastersub.key
  • gpg --armor --export-secret-subkeys $KEYID > ecc_sub.key
• Be mindful that keytocard doesn’t copy the keys to the card, but it actually moves them. That means that once you type save you will not be able to “copy” the same keys to another key. If you want to create a backup key. Either backup .gnupg directory or export both public and private keys as ASC file through the UI.
• Transfer keys to device:
  • gpg --edit-key $KEYID
  • toggle
  • key 1
  • keytocard - option 1
  • key 1 (detach key)
  • key 2
  • keytocard - option 2
  • key 2 (detach key)
  • key 3
  • keytocard - option 3
  • save
• Export public key: gpg --armor --export $KEYID > pubkey.txt
• Remove the key from GPG - delete .gnupg completely or just remove the key using the UI
• Import public key to your GPG tool
• Extract SSH key: ssh-add -L

If for whatever reason you mess things up (it can happen) you can reset the whole key either by using YubiKey Manager or, even better, by using CLI tool called ykman which you can install with both MacPorts and Brew.

To completely reset your Yubikey run:

ykman openpgp reset

Some troubleshooting tips

1. If for whatever reason GPG agent doesn’t see your card (you may remove it from the device and put it in again), run the following:

gpg --card-status

This will initialize the key and display its content. However, if this too fails then just restart the GPG agent by using:

gpg-connect-agent killagent /bye
gpg-connect-agent /bye

2. If you see the following error when trying to access SSH servers: "sign_and_send_pubkey: signing failed: agent refused operation" run the following:

gpgconf --kill all
gpg --card-status
gpg-connect-agent updatestartuptty /bye

3. If you really mess it up

If things really get messed up, which can happen, you can always completely reset your Yubikey by running the following commands:

gpg --card-edit
admin
factory-reset

You can also use YubiKey Manager or UI tools to reset your key or just some of the features of your key.

Final thoughts

I really hope that this was as fun for you to read as it was for me to write. I have tried to address all levels of experience and needs with this text. Yubikey has been my great companion for many years, and it has helped me learn a lot about security and encryption while enjoying a slick Scandinavian design. I don’t know what future holds for us, but it seems to be passwordless. I am quite sure that Yubikey will be on the forefront of that passwordless future.