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.
```
gpg> admin
```
Change the Yubikey to generate gpg keys of 4096 bits instead of 2048.
```
gpg> key-attr
```
For Signature key, Encryption key, and Authentication key do the following. Select 1 to use RSA keys.
```
(1) RSA
```
Enter:
```
4096
```
At the prompt for the admin pin enter:
```
12345678
```
Set the admin pin for the card.
```
passwd
```
Select 3 to set the admin pin.
```
3
```
Enter the default admin pin.
```
12345678
```
Enter a new admin pin twice. Be sure to save this pin in a secure place
Next, change the user pin.
```
1
```
Enter the default user pin.
```
1234567
```
Enter a new user pin twice. Be sure to save this pin in a secure place
Next, set the Reset pin.
```
4
```
Enter your admin pin.
Enter a new Reset pin. Be sure to save this pin in a secure place
Select Q to quit the pin menu.
(Optional) Set your name and email on the card.
```
gpg> name
```

Create GPG keys on the YubiKey

From the gpg> prompt, generate GPG keys.
```
gpg> generate
```
Do not make an off-card backup of encryption key
```
n
```
Set the expiration date for the keys to 16 years
```
16y
```
Enter your name and e-mail address.
Enter O for Okay
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.
quit
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 list command.

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
```
gpg -k
```
Edit Github's key to change the level of trust
```
gpg --edit-key $GITHUB_PGP_KEY_FINGERPRINT
```
Change the trust level
```
gpg> trust
```
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
```
save
```
Show keys to confirm GitHub's key is signed and has full trust
```
gpg -k
```

(Optional) Setup Keybase with new GPG Public key and prove identity with

Github

Install Keybase
```
brew install keybase
```
Signup for a keybase account but do not import keys.
```
keybase signup
```
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
```

bhouse/setup.md