From abf61c1235f988f86884206f68f697470ccfba5f Mon Sep 17 00:00:00 2001 From: Michael Housh Date: Mon, 31 Mar 2025 13:10:47 -0400 Subject: [PATCH] feat: More yubikey notes. --- Yubikey.md | 206 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 125 insertions(+), 81 deletions(-) diff --git a/Yubikey.md b/Yubikey.md index e32c755..336490a 100644 --- a/Yubikey.md +++ b/Yubikey.md @@ -4,61 +4,65 @@ 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 | ✅ | | +| Cloudflare | ✅ | ✅ | +| Facebook | ✅ | ✅ | +| first-financial-bank | ✅ | ✅ | +| github | ✅ | ✅ | +| gitea | ✅ | ✅ | +| go-daddy | ✅ | ✅ | +| iCloud | ✅ | ✅ | +| M4-Mac-Mini | ✅ | ✅ | +| Macbook-Pro | ✅ | ✅ | +| Proton | ✅ | ✅ | ## Initial Setup [Yubikey-Instructions](https://support.yubico.com/hc/en-us/articles/360016649059-Using-your-YubiKey-as-a-smart-card-in-macOS) -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. +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](#first-financial-bank) -notes) +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](#first-financial-bank) notes) ## Moving GPG keys onto Yubikey [Helpful Guide](https://github.com/drduh/YubiKey-Guide?tab=readme-ov-files) -> 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. +> 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](https://www.youtube.com/watch?v=xGsixSh6sC4) -The `GPG-Suite` application needs to be installed on macOS in order to interact with the yubikey. +The `GPG-Suite` application needs to be installed on macOS in order to interact +with the yubikey. ```bash 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. +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. +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](https://keys.openpgp.org/vks/v1/by-fingerprint/B86F487BF0A715D016DB140A37F1B52C60D8C24B) -### Default PIN's for yubikey (need changed below). +### Default PIN's for yubikey (need changed below) 1. User: 123456 1. Admin: 12345678 ### Sequence -#### Export and store the secret keys before starting. +#### Export and store the secret keys before starting > Note: This is around 8m in the video linked above. @@ -74,12 +78,11 @@ 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). +Export the secret keys, individually (this is for convenience, if you export the +master key then the sub-keys are included). ```bash -gpg --export-secret-subkeys --armor > -/tmp/gpg/michael-.private--subkey.txt +gpg --export-secret-subkeys --armor > /tmp/gpg/michael-.private--subkey.txt ``` @@ -89,12 +92,14 @@ gpg --export-secret-subkeys --armor > 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**. +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 `, a star should appear next to the selected key. +Look for the key that the line begins with `sub` (sub-key) and usage is `S` +(signing). And select it by typing `key `, a star should appear next to the +selected key. ```bash gpg> key 4 @@ -106,24 +111,27 @@ 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. +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). +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. +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. +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). +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. @@ -133,8 +141,8 @@ 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. +You do not want secret keys to be on your machine, they should only be stored in +a safe location and on the yubikey. ```bash gpg --delete-secret-keys @@ -142,7 +150,8 @@ gpg --delete-secret-keys 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. +You can check that they were deleted by using this command, which shouldn't +output anything. ```bash gpg --list-secret-keys @@ -174,17 +183,18 @@ 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. +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. +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. +When done type `Q`, then you can change other items about the card if you'd +like, such as name, url, etc. -## Test it. +## Test it Create a test file that you can sign. @@ -204,57 +214,91 @@ 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). +Decrypt the file, here it will ask for password of the private key (not the GPG +User or Admin PIN). ```bash gpg --decrypt /tmp/test.txt.asc ``` -Remove the yubikey and try again, it shouldn't be possible without the yubikey being inserted. +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 +> 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](https://stackoverflow.com/questions/78554135/unverified-github-commits-using-gpg-keys-on-yubikey). ## 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. +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](https://github.com/drduh/YubiKey-Guide?tab=readme-ov-file#ssh) -> Note: My dotfiles should already have the appropriate environment variables and gpg configuration, -> they just need to be linked properly. +> Note: My dotfiles should already have the appropriate environment variables +> and gpg configuration, they just need to be linked properly. [Extra Setup Steps](https://jms1.net/yubikey/make-ssh-use-gpg-agent.md) -The above includes links to extra LaunchAgent files needed to be setup on macOS for ssh using GPG -keys to work properly. +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. +### Adding SSH key to another computer, using the yubikey -Move into SSH directory and generate key (yubikey needs to be plugged into the computer). +Move into SSH directory and generate key (yubikey needs to be plugged into the +computer). ```bash 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. +> 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. + +## Ykman command + +You can use the `ykman` utility to help manage openpgp options with the yubikey. + +```bash +brew install ykman +``` + +### Example (Increase pin attempts) + +```bash +ykman openpgp access set-retries 5 3 3 +``` + +### Reset / unblock after too many failed login attempts + +```bash +ykman openpgp access unblock-pin +``` ## 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. +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 {#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. +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. + +## iCloud + +[Setup instructions](https://support.yubico.com/hc/en-us/articles/7449189070620-Protecting-Apple-iCloud-with-YubiKeys) + +This requires 2 yubikey's in order to setup, and was pretty straight forward +based on instructions.