michael/notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: More yubikey notes.

Browse Source
This commit is contained in:
Michael Housh
2025-03-31 13:10:47 -04:00
parent b84b5cd5b3
commit abf61c1235
1 changed files with 125 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

206
Yubikey.md
View File

@@ -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 <LAST-8-DIGITS-OF-FINGERPRINT> >
/tmp/gpg/michael-<LAST-8-DIGITS-OF-FINGERPRINT>.private-<Key Type>-subkey.txt
gpg --export-secret-subkeys --armor <LAST-8-DIGITS-OF-FINGERPRINT> > /tmp/gpg/michael-<LAST-8-DIGITS-OF-FINGERPRINT>.private-<Key Type>-subkey.txt
```
@@ -89,12 +92,14 @@ gpg --export-secret-subkeys --armor <LAST-8-DIGITS-OF-FINGERPRINT> >
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 <num>`, 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 <num>`, 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 <KEY ID>
@@ -142,7 +150,8 @@ 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.
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.