Yubikey + GPG + Github + Keybase
The following guide are steps that can be used to generate GPG keys on a YubiKey, use the gpg keys to sign github commits, and publish the public gpg key to Keybase.
Why is this a good idea?
- Generating and storing GPG keys on a YubiKey allows the private key to be protected and ported between physical machines.
- Signing git commits adds an extra layer of verification that code changes originated from an trusted source.
- Using a YubiKey + touch-to-sign requires a physical presence to use the GPG signing key.
- GitHub supports restricting commits to a repo to only those that are signed.
- Putting a physical stamp on your code commits invokes a feeling of pride.
Install required programs to generate GPG keys
- Install gpg tools
$ brew install gpg
- Install pinentry for mac
$ brew install pinentry-mac
- Set pinentry in gpg config
$ echo "pinentry-program /usr/local/bin/pinentry-mac" >> ~/.gnupg/gpg-agent.conf
- Kill the current gpg agent to pick up the change.
$ killall gpg-agent
Edit GPG settings on the YubiKey
- Connect Yubikey to laptop.
- Disregard keyboard setup wizard if one tries to recognize the YubiKey.
- Use gpg to connect to the opengpg app on the Yubikey.
$ gpg --edit-card
- Switch to admin mode of the Yubikey.
- Change the Yubikey to generate gpg keys of 4096 bits instead of 2048.
- For Signature key, Encryption key, and Authentication key do the following. Select 1 to use RSA keys.
- At the prompt for the admin pin enter:
- Set the admin pin for the card.
- Select 3 to set the admin pin.
- Enter the default admin pin.
- Enter a new admin pin twice. Be sure to save this pin in a secure place
- Next, change the user pin.
- Enter the default user pin.
- Enter a new user pin twice. Be sure to save this pin in a secure place
- Next, set the Reset pin.
- Enter your admin pin.
- Enter a new Reset pin. Be sure to save this pin in a secure place
Qto quit the pin menu.
- (Optional) Set your name and email on the card.
Create GPG keys on the YubiKey
- From the
gpg>prompt, generate GPG keys.
- Do not make an off-card backup of encryption key
- Set the expiration date for the keys to 16 years
- Enter your name and e-mail address.
- Generating the keys may take several minutes. The YubiKey will blink while keys are generated. During this time, move your mouse and type on the keyboard. This will help with generating random bytes. Without enough random activity, the key generation will fail.
- After some time (5-10 minutes) you should see
public and secret key created and signed.
- If you log back into the card
gpg --edit-card, you should see the details of the new keys displayed. You can also display the info using the
Configure Pin retries and touch to sign on the Yubikey
- Install the yubikey manager app
brew install ykman
- Use ykman to turn on touch to sign functionality.
ykman openpgp set-touch SIG ON
- Enter the admin PIN to allow modifying the touch setting.
- Answer yes (y) to
Set touch policy of signature key to on?
- Use ykman to set pin retries (5 tries for user pin, reset pin, admin pin)
ykman openpgp set-pin-retries 5 5 5
- Enter the admin PIN to allow modifying the retries setting.
- Answer yes (y) to
Set PIN retry counters to: 5 5 5?
Test your new signing key
- Test by signing a string on the cli. You should be prompted in a pop-up
window to enter your YubiKey User PIN. Remember to touch the yubikey with your finger when blinking to sign the message
echo "foobar" | gpg --sign --armor | gpg --decrypt
Add your public GPG key to Github
- Import your public gpg key to github.
gpg -k # get fingerprint of key to export. This will be a string of characters one line below the line that starts with pub, and one line above the line that starts with uid. gpg --armor --export $FINGERPRINT | pbcopy
Reference: Adding a new GPG key to your GitHub account
- Update your gitconfig to use the new gpg key to sign.
git config --global commit.gpgsign true git config --global user.signingkey $FINGERPRINT
When you make a git commit, you may be propmted to enter the user pin of the yubikey to unlock it.
Each time you make a git commit, the commit will require access to your private gpg key to sign. You will need to physically touch the yubikey to grant access. Otherwise your commit will timeout and fail.
To see the signature of your commit, use the following command:
git log --show-signature
Import and trust GitHub's Public GPG key
- Import Github's public key into local gpg keychain
curl https://github.com/web-flow.gpg | gpg --import
- Show Github's key
- Edit Github's key to change the level of trust
gpg --edit-key $GITHUB_PGP_KEY_FINGERPRINT
- Change the trust level
- Enter the level of trust you have for the key (1-5)
Your decision? 3
- Sign Github's key with your gpg public key
gpg> 1 # select the key to sign (* should appear next to the key name) gpg> sign ... Really sign? (y/N) y
- Save and quit
- Show keys to confirm GitHub's key is signed and has full trust
(Optional) Setup Keybase with new GPG Public key and prove identity with
- Install Keybase
brew install keybase
- Signup for a keybase account but do not import keys.
- Add your public gpg key to keybase
keybase pgp select
- Set the keybase account passphrase.
keybase passphrase set
- Add your keybase identity proof to github
keybase prove github