YubiKey Setup
Intro
There are two flavors of YubiKey to my estimation:
-
Reduced feature "Security Token"
-
Fully featured (FIPS or not)
The "Security Tokens" only support FIDO2, but that is actually the vast majority of what they are needed for: That is, passkeys, webauthn, SSH keys.
If you also want to use your YubiKey for age keys, you need the more fully featured model. This post was tested using the YubiKey 5C NFC, but any fully featured should work.
In this guide, SSH keys are generated on the YubiKey but the Age key is generated locally first, then copied to the YubiKeys and encrypted using that same age key. This allows for backing up as well as the ability to decrypt files using either YubiKey.
This is better, for reasons explained in the "why use hardware security tokens" blog post.
If you only want one copy, the age-plugin-yubikey walks you through it and is very straightforward.
This is one of the "implementation" details of my "Why use hardware security tokens" blog post.
Additional notes
I use Fish, so I have the following code setup as a fish function, and you can find it on Codeberg. But for clarity, it is here as a bash snippet.
Requirements
Software
-
You must install openssl rather than using the bundled openssl from Apple (probably via homebrew.)
-
ykmancommand-line interface (CLI) tool: Follow the instructions from Yubico. -
A *nix OS:
-
MacOS Sequoia or later if on MacOS
-
Basically any Linux environment
-
-
if on Linux, ensure
pcsdis running. (See the section on the yubikey plugin page for directions.) -
ageCLI: github.com/filosottile/age (apt install age, orbrew install age) -
age-plugin-yubikeyplugin: github.com/str4d/age-plugin-yubikeybrew install age-plugin-yubikey, orcargo install age-plugin-yubikey, or just download a release and add to your$PATH.)
Hardware
This is what I used in this setup
-
YubiKey 5c NFC
-
Age and KeePassXC both require the additional security features not available on the cheaper fido2-only "security key". But if all you need is SSH and webauthn, and fido, then the security key is worth the 50% cheaper price. I have tried using an OnlyKey but it simply does not have the broad support and convenience to be at the same tier of YubiKey.
-
Setup
First, set the FIDO PIN, change the PIV PIN, PUK, and management keys then protect and lock the management key.
export LC_CTYPE=C
printf "Random pin: %s\n" "$(cat /dev/urandom | tr -cd '[:digit:]' | head -c 6)"
ykman fido access change-pin
ykman piv access change-pin # it is better to remember the PIN than to have 2 different ones and forget one of them
printf "Random PUK: %s\n" "$(cat /dev/urandom | tr -cd '[:digit:]' | head -c 8)"
ykman piv access change-puk
printf "Random management key: %s\n" "$(cat /dev/urandom | tr -cd '[:digit:]' | head -c 48)"
ykman piv access change-management-key
ykman piv access change-management-key -a TDES --protect
Create SSH keys
SSH keys are generated on the YubiKey itself in the ed25519-sk format.
Other keys algorithms are supported but this is a best practice and has wide support.
I wrote this as a function to make it easy for myself (and because you will likely generate more than one key).
It works like: create_yubikey_key [--no-touch] <key_name>
create_yubikey_key() {
# Parse optional flags and positional arguments (default to requiring touch)
local require_touch=1
while [[ "$#" -gt 0 ]]; do
case "$1" in
--no-touch)
require_touch=0
shift
;;
-*)
echo "Unknown option: $1" >&2
echo "Usage: create_yubikey_key [--no-touch] <key_name>" >&2
return 1
;;
*)
break
;;
esac
done
# Clear out conflicting environment variables, this may not be needed depending on your setup
unset SSH_SK_PROVIDER
if ssh -V 2>&1 | grep -q OpenSSL; then
printf "Using: "
command -v ssh-keygen
else
# Don't use bundled libressl on macOS!
printf "Are you sure this is using the homebrew openssh? That is usually required for full FIDO2 support.\n"
return 1
fi
if [ "$#" -ne 1 ]; then
echo "Usage: create_yubikey_key [--no-touch] <key_name>"
return 1
fi
local key_name="$1"
local key_path="$HOME/.ssh/id_ed25519_sk_rk_$key_name"
local ssh_opts=("-t" "ed25519-sk" "-O" "resident" "-O" "application=ssh:$key_name" "-f" "$key_path")
local ssh_agent_note=0
if [ "$require_touch" -eq 1 ]; then
ssh_agent_note=1
ssh_opts+=("-O" "verify-required")
echo "Creating YubiKey key '$key_name' with Touch ID enforcement..."
else
echo "Creating YubiKey key '$key_name' without touch requirement..."
fi
echo "Generating key at: $key_path"
echo "+ ssh-keygen ${ssh_opts[*]}"
ssh-keygen "${ssh_opts[@]}"
printf "\nRun 'ssh-keygen -K' to download handles to other machines\n"
if [ "$ssh_agent_note" -eq 0 ]; then
printf "Run 'ssh-add -t 7200 ~/.ssh/id_ed25519_sk_%s' to avoid having to repeatedly touch the yubikey\n" "$key_name"
fi
}
create_yubikey_key
Age keys
You can generate these keys directly on the device, which is more secure, but there is no way to export them to your second YubiKey, so you are forever prevented from decrypting files if you:
-
lose a YubiKey
-
upgrade your YubiKey
-
etc
Instead we tightly protect the private key and upload it to the YubiKeys.
I followed from Pablo Ovelleiro Corral’s blog post as well as having LLMs review the source code to figure out the differences between v0.5.0 and v0.5.1 of the plugin. In accordance with the "BrainMade" mark on this blog (and because I believe that it is disrespectful to ask you to read machine generated code) all code was hand-written by myself.
Ideally you would run this on an offline computer with an ephemeral filesystem, but it is probably fine (especially given the threat analysis on the main blog page) if you don’t.
| Note the variables on lines 10-18. This snippet assumes you want to use slot 82 "RETIRED1" (the default first slot for the plugin), session PIN, and always require touch. |
If on linux, swap the rm -P command with shred or equivalent.
|
You can execute this script from your ~/.age directory.
# This script checked on version 0.5.1, but should work on future versions
AGE_PLUGIN_VERSION="$(age-plugin-yubikey --version | cut -d' ' -f 2)"
# Must be OpenSSL, not LibreSSL (macOS bundles LibreSSL as /usr/bin/openssl)
if ! openssl version | grep -q '^OpenSSL'; then
echo "error: expected OpenSSL on PATH, got $(openssl version)" >&2
exit 1
fi
# Policy bytes for cert extension 1.3.6.1.4.1.41482.3.8:
# PIN: 01=Never, 02=Once, 03=Always
# Touch: 01=Never, 02=Always, 03=Cached
PIN_BYTE="02"
TOUCH_BYTE="02"
# Slots range from 1 to 20, this will overwrite anything in that slot
SLOT=1
PIV_SLOT=$((81 + SLOT))
# Generate the key and upload to YubiKey
openssl ecparam -name prime256v1 -genkey -noout -out age.piv.key.pem
openssl ec -in age.piv.key.pem -pubout -out age.piv.pub.pem
ykman piv keys import "$PIV_SLOT" age.piv.key.pem --pin-policy once --touch-policy always
# Generate the self-signed x509 cert and upload to YubiKey
openssl req -new -x509 -key age.piv.key.pem -out age.piv.cert.pem -days 36500 \
-config /dev/null \
-subj "/O=age-plugin-yubikey/OU=$AGE_PLUGIN_VERSION/CN=PIV age key" \
-addext "1.3.6.1.4.1.41482.3.8=DER:$PIN_BYTE:$TOUCH_BYTE"
ykman piv certificates import "$PIV_SLOT" age.piv.cert.pem
# Save the identity file first — this is what decrypts the backup
# (although it can be regenerated anytime with: age-plugin-yubikey --identity --slot $SLOT)
age-plugin-yubikey --identity --slot "$SLOT" >age.piv.identity.txt 2>/dev/null
# Get the pubkey (recipient) from the identity file
printf "Your new pubkey is: "
grep -Eo 'age1yubikey.*$' age.piv.identity.txt | tee age.piv.pub
# Tar, then encrypt the cert and key
tar czf - age.piv.key.pem age.piv.cert.pem age.piv.pub.pem age.piv.pub age.piv.identity.txt | age -r "$(cat age.piv.pub)" -o age.piv.backup.tar.gz.age
printf "Encrypting key and cert files for transfer to another computer/YubiKey and for backing up.\n\n"
printf "NOTE: You cannot decrypt this without at least one working YubiKey!\n\n"
printf "Decrypt later with: age -d -i age.piv.identity.txt -o backup.tar.gz age.piv.backup.tar.gz.age\n"
# Clean up (maintains macOS rm -P flag for secure file overwrites)
rm -P age.piv.cert.pem age.piv.key.pem age.piv.pub.pem
Test it out!
date | age -R age.piv.pub -o test.age
age -d -i age.piv.identity.txt test.age
If you made a mistake or an error occured, you can remove keys off the YubiKey with the following snippet. The # is \(81 + SLOT\).
| Unless you have another backup YubiKey setup, this is irrecoverable! The backup is encrypted with this key. |
ykman piv certificates delete 82
ykman piv keys delete 82
Some more notes
The -config /dev/null stops openssl v3.x from adding basicConstraints=critical,CA:TRUE (plus the SKID/AKID) which the plugin doesn’t like because it validates that the certificate doesn’t contain any critical extensions it doesn’t recognize.
Avoiding requiring the age-plugin-yubikey
Senders will also need to have the age-plugin-yubikey to send things to you. If you want to avoid that you can create an age identity in the more normal way, but use the YubiKey age key to encrypt the "standard" key.
Replace rm -P with shred or similar on linux.
|
# Create "normal" key
age-keygen -o identity.key
cat identity.key | grep -Eo 'age1.*' | tee identity.pub
# Encrypt the identity using the YubiKey
age -r $(cat age.piv.pub) -o identity.age identity.key
# Securely delete the plaintext identity
rm -P identity.key
You can now ask senders to encrypt to this new identity.pub which is broadly compatible and you will have to decrypt their files like:
age -d -i age.piv.identity.txt identity.age | age -d -i - <FILE>
This prevents you from decrypting things from stdout, and the private key momentarily resides in memory (but not on disk), but those are acceptable compromises to allow more people to send you an encrypted file.
You can swap the first command for age-keygen -pq to use post-quantum mlkem768x25519, which requires age v1.3+ or an optional age-plugin for older versions. As stated in my reasoning in the main blog post, I didn’t consider this worth it yet (debian trixie repos only have age 1.2.1, so there will be many senders without that for a while).
|
Now senders can send you files using either recipient address!