Skip to content

Instantly share code, notes, and snippets.

@MIchaelMainer

MIchaelMainer/yubikeycommitsign.md

Last active March 31, 2022 22:03
Show Gist options
  • Save MIchaelMainer/6f390c7faec81c720ad81e4a95735d59 to your computer and use it in GitHub Desktop.
Save MIchaelMainer/6f390c7faec81c720ad81e4a95735d59 to your computer and use it in GitHub Desktop.
Download ZIP
How to sign commits
Raw
yubikeycommitsign.md

Commit signing with YubiKey 4 on Windows

Disclaimer

Please note that this is not a complete guide, these are only notes I took for myself from the following resources, use it at your own risk. I have tested these instructions with YubiKey 4 on Windows 11.

  1. https://www.youtube.com/watch?v=fEftwheNMm8
  2. https://www.youtube.com/watch?v=Y3mLBTCiccs
  3. https://www.yubico.com/blog/github-now-supports-ssh-security-keys/
  4. https://github.com/drduh/YubiKey-Guide
  5. https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits

Set up on a new machine

  1. Install GPG4Win
winget install GnuPG.Gpg4win

You may need to restart your terminal to get GPG into your PATH.

  1. Install YubiKey Manager https://www.yubico.com/support/download/yubikey-manager/

  2. Insert your YubiKey to a USB port

  3. Enter card edit mode in GPG:

gpg --card-edit
  1. Switch to admin mode:
admin
  1. (Optional) Factory reset the key if you need to:
factory-reset
  1. (Optional) Change the key's PINs:
passwd

Follow the instructions within the command to change default PINs from 123456 (non-admin) and 12345678 (admin) to your own PINs.

  1. Generate a GPG key:
generate

To increase randomness, move your mouse or type on your keyboard (gpg normally shows this message but not in the card edit mode).

Enter your name and email as they appear in GitHub.

  1. Reconnect your YubiKey by the following commands. You will need to step out of card edit mode by hitting Ctrl+C to run these commands.
gpg-connect-agent  killagent /bye
gpg-connect-agent  /bye
  1. Get public key ID:
gpg --card-status
  1. Copy <id> from the output line:
General key info..: pub  rsa2048/<id>
  1. Export your public key (replace <id> with the ID copied in step 11)
gpg -o gpg.key --armor --export <id>

gpg.key is now the file that contains your public key.

  1. Upload the contents of gpg.key file to GitHub:
GitHub -> Settings -> SSH and GPG keys -> New PGP key
  1. Set local git config (replace <id> with the ID copied in step 11)

This step assumes that your Gpg4Win installation location is standard (i.e. C:\Program Files (x86)\GnuPG\bin\gpg.exe), change that command to point to the installation location on your machine if it is not.

git config --global user.signingKey <id>
git config --global commit.gpgsign true
git config --global gpg.program 'C:\Program Files (x86)\GnuPG\bin\gpg.exe'
  1. Allow touch on YubiKey for signing:
& 'C:\Program Files\Yubico\YubiKey Manager\ykman.exe' openpgp keys set-touch SIG ON

  1. Create a git commit in any repository. You will be asked your PIN (non-admin PIN from step 7) and then you will need to touch the YubiKey to sign the commit. Any subsequent commits will need only the touch.

  2. Confirm that the commit is signed:

git log --show-signature
  1. Push your commit to GitHub and check if Verified badge appears.

Using same YubiKey on multiple machines

  1. Import the public key (gpg.key file is from step 11)
gpg --import gpg.key
  1. Follow step 14.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment