If you follow this guide you will end up with an offline and online Yubikey. Use your online Yubikey for everyday life, signing/encryption etc. Offline key for signing keys for web-of-trust and replace lost online keys.
Awesome tools with PGP keys:
- mozilla/sops dead-simple local encryption of sensitive files
- popass.pw password manager for you and your team stored in git
Offline Yubikey for signature key, this should exclusively be used for creating/revoking online keys and signing others peoples keys for web-of-trust. This key should be kept secured and not actively used, stashed somewhere at home. For the paranoid I recommend storing the offline Yubikey in a tamper-evident bag, keep the serial of the bag in a gist (signed commits ofc). Recommended key is Yubikey 5c for future proof and to make it easy to use.
Online Yubikey for daily life. Choose a Yubikey that fits your lifestyle.
Yubikey for your keychain:
- Yubikey 5c for smaller footprint
- Yubikey 5C NFC for use with Android/iPhone
Yubikey permanent in your laptop:
- Yubikey 5 Nano for USB-A, less that extends out of chassi than USB-C
- Yubikey 5C Nano for USB-C
# Install gpg-suite
$ brew cask install gpg-suite
Infineon Technologies, one of Yubico’s secure element vendors, informed us of a security issue in their firmware cryptographic libraries. The issue affects TPMs in millions of computers, and multiple smart card and security token vendors.
Make sure your key is not vulnerable on Yubico keycheck site. If it's affected then you should either buy a new Yubikey or follow a different guide how to generate the keys off the YubiKey.
# Enter gpg command
$ gpg --card-edit
# Enter admin mode
gpg> admin
# Set keysize to 4096
# Choose RSA and 4096 for all options
gpg> key-attr
## Run guide to generate keypair
# Please note that the factory settings of the PINs are
# PIN = '123456' Admin PIN = '12345678'
# Questions with answers:
# Make off-card backup of encryption key? (Y/n): n
# Key is valid for?: 3y
gpg> generate
gpg> Q
TODO https://debian-administration.org/article/450/Generating_a_revocation_certificate_with_gpg
Add the email addresses you want to use with your GPG identity.
When git signing it is required that committer and email address in the certificate are the same (GitHub requires this for showing verified flag). Thus you might want to have several email addresses registered in the certificate.
# We start by listing keys in your email address
$ gpg --list-keys <your email>
pub rsa4096 2018-02-05 [SC] [expires: 2022-02-12]
EA85C6564606A899966AB7F175745A53C9673583
uid [ultimate] Carl Loa Odin <loa@nonetype.se>
sub rsa4096 2018-02-05 [A] [expires: 2022-02-12]
sub rsa4096 2018-02-05 [E] [expires: 2022-02-12]
# copy the key id from previous listing (in example EA85C6564606A899966AB7F175745A53C9673583)
$ gpg --expert --edit-key <longid>
# for every email you want to add run
gpg> adduid
# now select the uid you want as your primary, probably your private email address
gpg> uid 2
gpg> primary
gpg> save
# Enter gpg command
$ gpg --card-edit
# Step into admin mode
gpg> admin
# Config Yubikey with your name
gpg> name
# Require pin for all signatures
gpg> forcesig
# Enter password menu to set personal PIN and admin PIN
gpg> passwd
# Update personal PIN
gpg> 1
# Update Admin Pin
gpg> 3
gpg> quit
We will now setup a secondary yubikey with subkeys. This one will be for everyday usage.
IMPORTANT: Make sure only your offline Yubikey is plugged in which contains your main key.
# We start by listing keys in your email address
$ gpg --list-keys <your email>
pub rsa4096 2018-02-05 [SC] [expires: 2022-02-12]
EA85C6564606A899966AB7F175745A53C9673583
uid [ultimate] Carl Loa Odin <loa@nonetype.se>
sub rsa4096 2018-02-05 [A] [expires: 2022-02-12]
sub rsa4096 2018-02-05 [E] [expires: 2022-02-12]
# copy the key id from previous listing (in example EA85C6564606A899966AB7F175745A53C9673583)
$ gpg --expert --edit-key <longid>
# Generate new subkey for signatures
# Questions with answers:
# Please select what kind of key you want (4) RSA (sign only): 4
# RSA keys may be between 1024 and 4096 bits long: 4096
# Please specify how long the key should be valid: 3y
gpg> addkey
# Generate new subkey for encryption
# Questions with answers:
# Please select what kind of key you want (6) RSA (encrypt only): 6
# RSA keys may be between 1024 and 4096 bits long: 4096
# Please specify how long the key should be valid: 3y
gpg> addkey
# Generate new subkey for authentication
# Questions with answers:
# Please select what kind of key you want (8) RSA (set your own capabilities): 8
# Toggle capabilities until only Authentication is choosen: _Current allowed actions: Authenticate_
# RSA keys may be between 1024 and 4096 bits long: 4096
# Please specify how long the key should be valid: 3y
gpg> addkey
gpg> save
IMPORTANT: Make sure only your Online Yubikey is plugged in which is currently empty.
# Enter gpg command
$ gpg --card-edit
# Step into admin mode
gpg> admin
# Config Yubikey with your name
gpg> name
# Require pin for all signatures
gpg> forcesig
# Enter password menu to set personal PIN and admin PIN
gpg> passwd
# Update personal PIN
gpg> 1
# Update Admin Pin
gpg> 3
gpg> quit
IMPORTANT: Make sure only your new Online Yubikey is plugged in.
# We start by listing keys in your email address (notice the extra subkeys generated in previous steps)
$ gpg --list-keys <your email>
pub rsa4096 2018-02-05 [SC] [expires: 2022-02-12]
EA85C6564606A899966AB7F175745A53C9673583
uid [ultimate] Carl Loa Odin <loa@nonetype.se>
sub rsa4096 2018-02-05 [A] [expires: 2022-02-12]
sub rsa4096 2018-02-05 [E] [expires: 2022-02-12]
sub rsa4096 2018-12-18 [S] [expires: 2022-12-17]
sub rsa4096 2018-12-18 [E] [expires: 2022-12-17]
sub rsa4096 2018-12-18 [A] [expires: 2022-12-17]
# copy the key id from previous listing (in example EA85C6564606A899966AB7F175745A53C9673583)
$ gpg --expert --edit-key <longid>
# make it possible to select individual keys
gpg> toggle
# Select the last key with usage S, probably key 3.
# The key should be marked with a `ssb*`
gpg> key 3
sec rsa4096/75745A53C9673583
created: 2018-02-05 expires: 2022-02-12 usage: SC
card-no: 0006 07431439
trust: unknown validity: ultimate
ssb rsa4096/4CD49BFD4E4F10D3
created: 2018-02-05 expires: 2022-02-12 usage: A
card-no: 0006 07431439
ssb rsa4096/AF20A2CB05BEC84E
created: 2018-02-05 expires: 2022-02-12 usage: E
card-no: 0006 07431439
ssb* rsa4096/ABBF2E2607AC076B
created: 2018-12-18 expires: 2022-12-17 usage: S
ssb rsa4096/A6D37B9DF8529809
created: 2018-12-18 expires: 2022-12-17 usage: E
ssb rsa4096/A49F7D3A02291CA3
created: 2018-12-18 expires: 2022-12-17 usage: A
[ultimate] (1). Carl Loa Odin <loa@nonetype.se>
# Move signature subkey to yubikey
# Questions with answers:
# Please select where to store the key (1) Signature key: 1
gpg> keytocard
# Deselect signature key
gpg> key 3
# Select the last key with usage E, probably key 4.
# The key should be marked with a `ssb*`
gpg> key 4
# Move encryption subkey to yubikey
# Questions with answers:
# Please select where to store the key (2) Encryption key: 2
gpg> keytocard
# Deselect encryption key
gpg> key 4
# Select the last key with usage A, probably key 5.
# The key should be marked with a `ssb*`
gpg> key 5
# Move authentication subkey to yubikey
# Questions with answers:
# Please select where to store the key (3) Authentication key: 3
gpg> keytocard
gpg> save
# We start by listing keys in your email address (notice the extra subkeys generated in previous steps)
$ gpg --list-keys <your email>
pub rsa4096 2018-02-05 [SC] [expires: 2022-02-12]
EA85C6564606A899966AB7F175745A53C9673583
uid [ultimate] Carl Loa Odin <loa@nonetype.se>
sub rsa4096 2018-02-05 [A] [expires: 2022-02-12]
sub rsa4096 2018-02-05 [E] [expires: 2022-02-12]
sub rsa4096 2018-12-18 [S] [expires: 2022-12-17]
sub rsa4096 2018-12-18 [E] [expires: 2022-12-17]
sub rsa4096 2018-12-18 [A] [expires: 2022-12-17]
# copy the key id from previous listing (in example EA85C6564606A899966AB7F175745A53C9673583)
$ gpg --expert --edit-key <longid>
$ quit
Verify following from the output given from the commands above:
- All keys are assigned to a card:
card-no: 0006 07431439
- First keys SC, A, E are assigned to one card
card-no: 0006 07431439
- Last keys S, E, A are assigned to another card
card-no: 0006 08626967
gpg (GnuPG/MacGPG2) 2.2.10; Copyright (C) 2018 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Secret key is available.
sec rsa4096/75745A53C9673583
created: 2018-02-05 expires: 2022-02-12 usage: SC
card-no: 0006 07431439
trust: unknown validity: ultimate
ssb rsa4096/4CD49BFD4E4F10D3
created: 2018-02-05 expires: 2022-02-12 usage: A
card-no: 0006 07431439
ssb rsa4096/AF20A2CB05BEC84E
created: 2018-02-05 expires: 2022-02-12 usage: E
card-no: 0006 07431439
ssb rsa4096/ABBF2E2607AC076B
created: 2018-12-18 expires: 2022-12-17 usage: S
card-no: 0006 08626967
ssb rsa4096/A6D37B9DF8529809
created: 2018-12-18 expires: 2022-12-17 usage: E
card-no: 0006 08626967
ssb rsa4096/A49F7D3A02291CA3
created: 2018-12-18 expires: 2022-12-17 usage: A
card-no: 0006 08626967
[ultimate] (1). Carl Loa Odin <loa@nonetype.se>
- Lock/hide away your offline yubikey with your primary signature key at home or bank safe
- Keep your online everyday yubikey with you and enjoy life with GPG
- Publish your public key to the world
- Go to key-signing parties
This will setup gpg-agent as your ssh-agent so the key on the Yubikey is exposed for ssh authentication.
# Create config dir for gpg
$ mkdir ~/.gnupg
# Create config for gpg-agent
$ cat > ~/.gnupg/gpg-agent.conf <<EOF
enable-ssh-support
EOF
Add following to your .bashrc
or .zshrc
:
export SSH_AUTH_SOCK="/run/user/$(id -u)/gnupg/S.gpg-agent.ssh"
Restart shell and run following to verify:
$ ssh-add -L
ssh-rsa AAAAB...== cardno:000000000000
You can setup git to sign commits and tags with the keys on your Yubikey.
# Identify your key id, 866BB649D084C1BA0E877C1A3C3AD83C0E508BDD in this example
$ gpg --list-keys <your email>
pub rsa4096 2018-02-05 [SC] [expires: 2022-02-12]
EA85C6564606A899966AB7F175745A53C9673583
uid [ultimate] Carl Loa Odin <loa@nonetype.se>
sub rsa4096 2018-02-05 [A] [expires: 2022-02-12]
sub rsa4096 2018-02-05 [E] [expires: 2022-02-12]
# Set git signing key globally
$ git config --global user.signingkey EA85C6564606A899966AB7F175745A53C9673583
## GitHub show Verified on keys
# You can add your public key to your GitHub profile so your commits shows up as verified
# Export the public key in ascii format and add as a new GPG key https://github.com/settings/keys
$ gpg --armor --export EA85C6564606A899966AB7F175745A53C9673583
# Add -S to sign commits
$ git commit -S -m "Test commit"
# Use -s instead of -a to sign git tags
$ git tag -s v1.5 -m 'my signed 1.5 tag'
# Add --show-signature to view signature on commits
$ git show --show-signature
# Run following to always sign commits
$ git config --global commit.gpgsign true
If you have a Yubikey and want to reset the current keys on that Yubikey, use this script https://gist.github.com/pkirkovsky/c3d703633effbdfcb48c#file-yubikey-reset-sh