306 lines
9.2 KiB
Markdown
306 lines
9.2 KiB
Markdown
# 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 | ✅ | ✅ |
|
|
| iCloud | ✅ | ✅ |
|
|
| M4-Mac-Mini | ✅ | ✅ |
|
|
| Macbook-Pro | ✅ | ✅ |
|
|
| Microcenter | ✅ | ✅ |
|
|
| 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.
|
|
|
|
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.
|
|
|
|
[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.
|
|
|
|
```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.
|
|
|
|
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)
|
|
|
|
1. User: 123456
|
|
1. 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.
|
|
|
|
```bash
|
|
mkdir /tmp/gpg
|
|
```
|
|
|
|
List the keys.
|
|
|
|
```bash
|
|
gpg --fingerprint --fingerprint
|
|
```
|
|
|
|
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
|
|
|
|
```
|
|
|
|
#### Import keys to yubikey.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
gpg> key 4
|
|
```
|
|
|
|
Transfer the key to the card.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
gpg --list-secret-keys
|
|
```
|
|
|
|
#### Edit the card details
|
|
|
|
Here we will edit the card details.
|
|
|
|
```bash
|
|
gpg --card-edit
|
|
```
|
|
|
|
Enter admin mode.
|
|
|
|
```bash
|
|
gpg/card> admin
|
|
```
|
|
|
|
Show the actions you can take
|
|
|
|
```bash
|
|
gpg/card> help
|
|
```
|
|
|
|
Change the admin password
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
echo "Test test..." >> /tmp/test.txt
|
|
```
|
|
|
|
Sign the test file.
|
|
|
|
```bash
|
|
gpg --encrypt /tmp/test.txt
|
|
```
|
|
|
|
Check that it worked.
|
|
|
|
```bash
|
|
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).
|
|
|
|
```bash
|
|
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](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.
|
|
|
|
## 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.
|
|
|
|
[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.
|
|
|
|
### Adding SSH key to another computer, using the yubikey
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|