notes/Yubikey.md

Yubikey

A list of sites that my yubikey's are registerd with.

Site	Primary Key Registered	Backup Key Registered
Cloudflare	✅
Facebook	✅
first-financial-bank	✅
github	✅
gitea	✅
go-daddy	✅
M4-Mac-Mini	✅
Macbook-Pro	✅
Proton	✅

Initial Setup

Yubikey-Instructions

I followed the above instructions to setup certificates that allows the yubikey to be used for the login screen. I opted not to require it at login as there are warnings about if a key is lost (and you use FileVault) then you will not be able to unlock the file system. This does allow the computer to be unlocked with a simple passcode though.

There are several PIN / passwords that need setup beyond the above instructions. This seemed easier on my iPhone. On the iPhone tap the menu at top right and choose configuration. There you can setup the OATH password and FIDO pin (take note to read the First Financial notes)

Moving GPG keys onto Yubikey

Helpful Guide

Note: The above guide is what was really followed / worked the best for me, the below guide was also helpful, but the above one covers more items, trouble shooting, and SSH setup using GPG keys.

helpful-youtube-video

The GPG-Suite application needs to be installed on macOS in order to interact with the yubikey.

brew install gpg-suite-no-mail

This then gives you access to use the gpg --card-edit command that allows you to add gpg-keys to the yubikey itself.

The yubikey only stores the private parts of the sub-keys, so the public portions need to still be on the machine or downloaded from a key server.

URL of public key

Default PIN's for yubikey (need changed below).

1. User: 123456
2. Admin: 12345678

Sequence

Export and store the secret keys before starting.

Note: This is around 8m in the video linked above.

Create a directory to store the exported keys.

mkdir /tmp/gpg

List the keys.

gpg --fingerprint --fingerprint

Export the secret keys, individually (this is for convenience, if you export the master key then the sub-keys are included).

gpg --export-secret-subkeys --armor <LAST-8-DIGITS-OF-FINGERPRINT> >
/tmp/gpg/michael-<LAST-8-DIGITS-OF-FINGERPRINT>.private-<Key Type>-subkey.txt

Import keys to yubikey.

gpg --edit-key B86F487BF0A715D016DB140A37F1B52C60D8C24B

Then you need to select the sub-keys one at a time and move them to the appropriate slog on the yubikey. The sub-keys should all have an expiration date associated with them, where as the master keys are generally set to never expire, you only want to move the sub-keys.

Look for the key that the line begins with sub (sub-key) and usage is S (signing). And select it by typing key <num>, a star should appear next to the selected key.

gpg> key 4

Transfer the key to the card.

gpg> keytocard

Then select the number option for the type of key that you've selected, here you will be asked for the password for the GPG key first, then the Admin GPG PIN for the yubikey in order to move the private key onto the yubikey.

When the key has been moved you will have to type the key and the number to deselect the key before choosing the next one (i.e. key 4 then key 5 to choose the next key).

Repeat this process for key types S (sign), A (authenticate), and E (encrypt), choosing the appropriate slot for each.

Once the keys are moved you type quit, it will prompt to save changes and you choose n (no), then it will prompt to quit without saving and you select y. Otherwise you secret keys will be deleted upon saving, which you will want to make a backup first.

Save secret keys

Next we will save the secret keys we exported in the beginning, these should typically be stored in a safe location disconnected from the internet (such as a usb thumb drive).

I like to wrap them up in a disk image that is password protected.

hdutil create -encryption AES-256 -srcfolder /tmp/gpg /tmp/gpg.dmg

Delete the secret keys

You do not want secret keys to be on your machine, they should only be stored in a safe location and on the yubikey.

gpg --delete-secret-keys <KEY ID>

This will prompt / warn you several times just click yes or OK for all of it.

You can check that they were deleted by using this command, which shouldn't output anything.

gpg --list-secret-keys

Edit the card details

Here we will edit the card details.

gpg --card-edit

Enter admin mode.

gpg/card> admin

Show the actions you can take

gpg/card> help

Change the admin password

gpg/card> passwd

Select option 3 to change the admin password. It will prompt for the current password 12345678, then ask for a new password.

Then we need to change the user password, which is option 1. It will prompt for the current password 123456, then ask for a new password. This password will be needed whenever you need to do an operation using the private keys stored in the yubikey.

When done type Q, then you can change other items about the card if you'd like, such as name, url, etc.

Test it.

Create a test file that you can sign.

echo "Test test..." >> /tmp/test.txt

Sign the test file.

gpg --encrypt /tmp/test.txt

Check that it worked.

cat /tmp/test.txt.asc

Decrypt the file, here it will ask for password of the private key (not the GPG User or Admin PIN).

gpg --decrypt /tmp/test.txt.asc

Remove the yubikey and try again, it shouldn't be possible without the yubikey being inserted.

Note: I was having trouble afterwards on Gitea that was saying signatures were suspicious, I had to update my git config file to include signingkey = 14A20BF5!, which is my signing key, the ! being the important part stack-overflow-link.

Signing Commits

When signing commits it will ask for a PIN to unlock the card, here you need to use the GPG User PIN to unlock and sign the commit, not the pin for the private key.

SSH setup

Setup Instructions

Note: My dotfiles should already have the appropriate environment variables and gpg configuration, they just need to be linked properly.

Extra Setup Steps

The above includes links to extra LaunchAgent files needed to be setup on macOS for ssh using GPG keys to work properly.

Adding SSH key to another computer, using the yubikey.

Move into SSH directory and generate key (yubikey needs to be plugged into the computer).

cd ~/.ssh && ssh-keygen -K

Note: This makes syncing passwords using gopass a PITA the way I currently have it setup with different password stores, I may have to consolidate them into a single store to make the friction less.

TOTP setup

Move TOTP tokens from current password manager and into the Yubico-Authenticator application, so that they are more secure / require the hardware yubikey. Saved the secrets inside current password manager so that they can be setup on the backup yubikey when it arrives.

Setting Up at First Financial Bank

When setting up I could only use my phone it wouldn't allow me on my computer. Once you tap the device to the phone it prompts for a PIN, this is referring to the FIDO PIN that needs setup prior. This took me a while to figure out and had to factory reset the FIDO application on the yubikey after too many failed attempts where I used the primary PIN to try and unlock the yubikey.