DISCLAIMER
U2F should be used when possible because it is significantly safer than any other alternative. The only reason I’m using TOTP rather than U2F, is because Amazon Web Services does not support 2 MFA devices attached to the same user, and their AWS CLI does not support U2F yet.
Basically, you can use U2F to access the web console, but forget about using U2F when running CLI commands in the terminal (and for me, this is not acceptable).
What is a YubiKey
The YubiKey is a small hardware authentication device, created by Yubico, that supports a wide range of authentication protocols.
It’s a USB key (some versions support USB-A, some USB-C and the latest versions even support NFC) with a LED and a button_._
NOTE: Seems like the YubiKey 4 with firmwares between 4.2.6 and 4.3.4 had a security vulnerability that would allow an attacker to reconstruct the private key using the public key. You can read more about this here and here.
USB interfaces
Yubico call these USB interfaces and each one of them supports one or multiple modes/protocols.
- FIDO: This interface only supports the U2F protocol.
- OTP: This interface has 2 slots (short-press and long-press). Each one of them can be configured and used as: OATH-HOTP, Yubico OTP, Challenge-Response or Static password. By default, a Yubico OTP is preconfigured in the first slot.
- CCID: This is the interface allowing the key to act as a Smart Card. It supports up to 32 OATH-TOTP/OATH-HOTP codes, PIV and OpenPGP.
U2F
An open authentication standard enabling strong two-factor authentication to any number of web-based applications, such as Gmail, Salesforce, Amazon Web Services, Twitter and hundreds more services.
U2F is the recommended two factor method. It is phishing resistant unlike TOTP/Google Authenticator and it is much harder to compromise than SMS/Voice call methods.
It doesn’t require any software or drivers. It works in Chrome by default and in Firefox (you would need to change a config flag). Read more about FIDO U2F.
Smart Card (PIV)
Smart cards contain a chip that brokers data exchanges. These same features are contained in the YubiKey 4 and 5 Series, based on the industry standard Personal Identity and Verification Card (PIV) interface over the CCID protocol, which supports PIV on a USB interface.
Yubico OTP
The YubiKey generates an encrypted password for one-time use. Hackers require physical access of your YubiKey to generate the OTP. This is the weird string you will get if you touch your YubiKey when focused on a text input.
OpenPGP
In the physical world, documents and data are often validated with a signature. In the virtual world, OpenPGP is a standards-based public key cryptography for signing, encrypting, and decrypting texts, e-mails, files, etc.
Static password
A basic YubiKey feature, that generates a 38-character static password compatible with any application log-in. It is most often used with legacy systems that cannot be retrofitted to enable other two-factor authentication schemes, such as pre-boot login.
NOTE: This mode is vulnerable to keyloggers, so it should be avoided when possible.
OATH-TOTP/OATH-HOTP
The key generates a 6 or 8 character OTP (or one-time password) for logging into any service that supports either OATH-TOTP or OATH-HOTP.
The difference between OATH-TOTP and OATH-HOTP is the former is time based, meaning a new password is generated at a set time interval, typically every 30 seconds. The latter is event based, meaning a new one-time password is generated for each event.
Challenge-Response
The Challenge-Response method is best suited for offline validations. Use for Windows, Mac, and Linux computer login.
USB Interfaces and the different modes supported
Which interface will be used?
For our purposes, we will use the CCID interface because it allows to store up-to 32 OATH-TOTP/OATH-HOTP entries. If we only care about a single OATH-HOTP provider, we could use the OTP interface. However, both Google Authenticator and Authy are both TOTP based.
Set-up (GNU/Linux)
Ensure the PC/SC Smart Card Daemon is running
PC/SC Smart Key Daemon (or pcscd) is a service designed to interact with Smart Cards.
I’m running Arch Linux (I couldn’t hold it anymore :P) so I will be using systemctl to start/enable the pcscd service.
pcscd status
Start and enable pcscd.service
Install YubiKey Manager CLI tool
On Arch Linux you just need to run sudo pacman -S yubikey-manager. After the installation is finished, you should be able to run ykman info to retrieve details from your key.
We’re only interested in the CCID interface, so we could chose to disable OTP and FIDO with the following command ykman mode "CCID" but it’s not required.
Using your YubiKey 4 with different providers
When you use Google Authenticator or Authy in your phone, you have to scan a QR code using your camera, however as it’s obvious, you cannot do that with your YubiKey.
Instead, you will have to get a Base32 key and pass it to the YubiKey using the ykman tool previously installed. To add 2FA/MFA for a service using this tool, you need to provide both the aforementioned key and an identifier to help you identify your service/account later.
ykman oath add -t <SERVICE_NAME> <YOUR_BASE32_KEY>
The -t flag indicates you will need to touch your key in order to get the 6-digit code later. This is recommended to prevent malware to generate codes without any user intervention.
After running the previous command, you should now be able to generate a 6-digit code running ykman again.
ykman oath code <SERVICE_NAME>
It will ask you to touch your YubiKey, and then display the code in the screen.
GitHub
Go to your user settings > Security and click on “Enable two-factor authentication”.
In the next screen, you need to select “Set up using an App” when prompted.
After this, you will get to a screen where you can download a set of security codes in case you lose or break you MFA device and you cannot log in. As far as I know, this is something not every service has implemented, and in some of them, if you lose the key…that’s the end.
Once you get to the screen with the QR code, you will need to click on the link that says “enter this text code” and a modal with your Base32 key will open. You can configure your key with the following command:
ykman oath add -t github.com <YOUR_BASE_32_KEY>
After this you need to run ykman oath code github.com to get your 6-digit code and complete the 2FA set up.
AWS (IAM Users, not root account)
After login, go to IAM > Users and click in your user name. Then you need to click on the “Security credentials” tab.
Security credentials tab
As you can see, there is no MFA device assigned, so to assign one, just click Manage. In the next screen, select “Virtual MFA device”.
Setting up a MFA device
Here you can choose to show the QR code or to show the secret key. For our purposes, we want the secret key only.
Then you can run ykman to configure AWS MFA:
ykman oath add -t aws-username <YOUR_BASE_32_KEY>
And then runykman oath code aws-username twice, to get a couple 6-digit codes and complete the set up.
MFA has been set up correctly
GitLab
Go to your user settings > Account and select “Enable two-factor authentication.
In the next screen you will see the QR code, and a bit of text at the right. This contains your Base32 key.
NOTE: You will need to remove the spaces before using the key with
ykman.
After getting the key, the process is exactly the same than GitHub. First you need to configure GitLab in your YubiKey, running the following command.
ykman oath add -t gitlab.com <YOUR_BASE_32_KEY>
After this, just run ykman oath code gitlab.com to get your 6-digit code and complete the 2FA set up.
EXTRA STUFF!
Simplify your workflow using fzf
If you are a heavy-CLI user and don’t know fzf you should stop reading this and go here or here.
ykman oath code $(ykman oath list | fzf)
Using ykman oath list we can get a list of the different services configured with the key. The way this command works, is:
- Passes the output of
ykman oath listtofzf. - You select which service you want to authenticate against and press enter.
ykmanwill ask for you to touch the key, and will output the right 6-digit code associated to the previously selected service.
You can see this in action here.
Use Yubico Authenticator instead of ykman to get the 6-digit codes
If you don’t want to use ykman to get your 6-digit codes, you can also choose to use Yubico Authenticator (a GUI based tool).
In my case I had to install [yubico-yubioath-desktop](https://aur.archlinux.org/packages/yubico-yubioath-desktop/) from the Arch User Repository (AUR).
OOOPS! I need to insert the key
List of services using YubiKey
Touch your YubiKey and you will see a 6-digit code for the selected service
DONE!