Notes on Yubikey setup & automation on Linux/MacOS

Apr 4, 2023

3 minutes read

I have finally managed to move my MFA to hardware security keys using Yubikeys, thanks to the Cloudflare’s “Good for the Internet” offer where any Cloudflare customer was able to buy Yubikeys for as low as $10 per key. I maxed out on my offer by buying four of Yubikey 5 series (2xYubiKey 5C NFC & YubiKey 5 NFC).

This blog post is my ad hoc notes on setting up and automating Yubikey 5 series on Linux/MacOS

The setup and automation works for my specific scenarios, environment and threat model. Your mileage may vary.

Software required

Once you have the Yubikeys, the following are the quintessential software to work with Yubikeys -

Yubikey Manager - configure FIDO2, OTP and PIV functionality on your YubiKey
YubiKey Manager CLI (ykman) - Because CLI is the way to automate
Yubico Authenticator - To work with TOTPs (Simply put, OTPs for which you use “Authenticator” apps)
yubikey-agent - ssh-agent for YubiKeys

Working with Time based one time passwords (TOTPs)

You are in luck if the application you want to secure with MFA supports Yubikeys natively (FIDO2/FIDO U2F) such as Github etc. A lot of applications (VPNs, SSH MFA etc) do not support FIDO2/FIDO U2F and they support only TOTP that requires an Authenticator app on a secondary device (mobile phone).

Using Yubikeys, you can make your TOTP mechanism relatively more secure and usable by storing the TOTPs on the Yubikey that on the Authenticator app on a mobile or worse, using browser extensions like Autheticator which nullify the security provided by MFA.

Yubikeys + TOTPs are still not the best from usability PoV because you still have to retrieve the OTP from the Yubikey and enter the OTP but in my opinion, storing TOTP on Yubikey is a better storing on an app on mobile device

Install Yubico Authenticator on your mobile device and pair it with your Yubikey (I have a Yubikey with NFC so I do it via NFC)
Scan the QR code of your TOTP using Yubico Authenticator, this will store the TOTP on the Yubikey
Alternatively, you can use ykman to add a TOTP to your Yubikey (https://docs.yubico.com/software/yubikey/tools/ykman/OATH_Commands.html)

ykman oath access change # set password for OATH codes access 
ykman oath accounts add <NAME> --touch` # Add an OATH TOTP to Yubikey

You can not read the code on the Yubikey using ykman oath accounts code <NAME>
You can automate the above process by using bash functions (or alias) added to your shell config (.zshrc for ZSH)

my-vpn-otp () {
    echo "Generating OTP for VPN"
    ykman oath accounts code <NAME> | cut -d " " -f 3 | pbcopy
    echo "Code copied to clipboard!"
}

Hardware-backed (yubikey) SSH authentication

You can secure your SSH autnetication by using Yubikeys for hardware based authentication. You can secure SSH private keys with the YubiKey by importing them or generating the private key directly on the YubiKey. Private keys cannot be exported or extracted from the YubiKey.

https://developers.yubico.com/SSH/

OpenSSH version 8.2p1 added support for FIDO hardware authenticators. FIDO devices are supported by the public key types “ecdsa-sk” and “ed25519-sk”, along with corresponding certificate types.

ssh-keygen -t ecdsa-sk -O resident

The easiest way of setting up SSH key based authentication is using yubikey-agent.

Just install yubikey-agent and run yubikey-agent -setup, you are good to go!

Other tips

You can remember the OATH TOTP password for Yubikey for a given session using ykman oath access remember

Better blogs on the same topic

Back to posts