Skip to main content

If you need help or get stuck, post in #engineering-general and tag the last person who edited this document and ask them to give you a hand. If you find this document incomplete or lacking detail, follow the boy scout rule, make a pull request and improve it!

Yubikey Setup

This guide explains how to set up your Yubikey for GPG code signing of Git commits. You'll learn how to:

  • Set your PIN and PUK (Pin Unlock Key)
  • Create a certificate
  • Export your public key
  • Add it to your GitHub profile

Prerequisites​

  1. Install required tools:
brew install gnupg yubikey-personalization pinentry-mac
brew install --cask yubico-yubikey-manager
  1. Verify Yubikey detection:
gpg --card-status

You should see output similar to:

Reader ...........: Yubico YubiKey OTP FIDO CCID
Application ID ...: D2760002250100000006340457570500
Application type .: OpenPGP
Version ..........: 3.4
...

GPG Configuration​

  1. Set up GPG environment:
export GPG_TTY=$(tty)
echo 'export GPG_TTY=$(tty)' >> ~/.zshrc
echo "use-agent" >> ~/.gnupg/gpg.conf
  1. Configure GPG agent:
mkdir -p ~/.gnupg
echo "enable-ssh-support
use-standard-socket
pinentry-program /opt/homebrew/bin/pinentry-mac" > ~/.gnupg/gpg-agent.conf

gpgconf --kill gpg-agent
gpgconf --launch gpg-agent

Yubikey Setup​

1. Reset PIN and PUK​

  1. Open the card editor:
gpg --card-edit
  1. In the prompt, run these commands. The default pin is 123456. The default admin pin is 12345678:
gpg/card> admin
Admin commands are allowed

gpg/card> passwd
gpg: OpenPGP card no. _________ detected

1 - change PIN                                                                       
2 - unblock PIN                                                                      
3 - change Admin PIN                                                                 
4 - set the Reset Code
Q - quit              

Your selection? 1

gpg/card> passwd
gpg: OpenPGP card no. _________ detected

1 - change PIN                                                                       
2 - unblock PIN                                                                      
3 - change Admin PIN                                                                 
4 - set the Reset Code                                                                                                                                                    
Q - quit              

Your selection? 3

Q

Important: Remember both your PIN and PUK, and store them in your password manager.

2. Generate GPG Key​

  1. Open the card editor again:
gpg --card-edit
  1. In the prompt, run:
admin
generate

Enter your details. This will generate your public / private keypair.

3. Test Your GPG Key​

echo "test" | gpg --clearsign

Export and Configure GPG Key​

1. Find Your Key ID​

gpg --list-secret-keys

You should see output like:

[keyboxd]
---------
sec>  rsa2048 2025-04-01 [SC]
      27512BAE400D2B1E35F2C4C2F230125C8130347C
      Card serial no. = 0006 32045787
uid           [ultimate] Will Salt <will.salt@assetreality.com>
ssb>  rsa2048 2025-04-01 [A]
ssb>  rsa2048 2025-04-01 [E]

2. Export Your Public Key​

  1. Edit your key:
gpg --edit-key YOUR_KEY_ID
  1. List the subkeys:
list

You'll see output like:

pub  rsa2048/XXXXXXXXXXXXXXXX  created: ...
     usage: SC
sub  rsa2048/YYYYYYYYYYYYYYYY  created: ...
     usage: E
sub  rsa2048/ZZZZZZZZZZZZZZZZ  created: ...
     usage: A

Note:

  • S = Signing
  • C = Certifying (verifying other keys)
  • E = Encryption
  • A = Authentication (for SSH)
  1. Export the Encryption subkey (replace YYYYYYYYYYYYYYYY with your key ID):
gpg --export --armor YYYYYYYYYYYYYYYY > mykey.asc

3. Add Key to GitHub​

  1. Go to GitHub GPG Keys Settings
  2. Click "New GPG Key"
  3. Paste the contents of mykey.asc

Git Configuration​

  1. Configure Git to use your key:
git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true
  1. Test your signed commit:
git commit -S -m "My first signed commit with YubiKey"
  1. Verify the signature:
git log --show-signature

You should see output like:

commit 1234567890abcdef...
gpg: Signature made Wed Apr  1 10:00:00 2025 UTC
gpg:                using RSA key ABCDEF1234567890
gpg: Good signature from "Your Name <you@example.com>" [ultimate]