Skip to content

Instantly share code, notes, and snippets.

@rdnt

rdnt/README.md

Last active February 9, 2021 08:13
Show Gist options
  • Save rdnt/962e90b5a07c32ff2778de71b2e1cef2 to your computer and use it in GitHub Desktop.
Save rdnt/962e90b5a07c32ff2778de71b2e1cef2 to your computer and use it in GitHub Desktop.
Download ZIP
GPG master & subKeys generation and usage on Git & Github (for GnuPG v2.1 or later)
Raw
README.md

This guide covers creating a master keypair (private and public key, along with an automatically generated encryption subKey), creation of subKeys from that master key to use for signing, and using said keys on Git and Github.
Passphrases are optional but strongly encouraged.

1. Create a master keypair:

  • Type gpg --full-generate-key and enter following settings:
  • Algorithm: RSA and RSA
  • Key size: 4096 bits
  • Duration: 0 (infinite; does not expire)
  • Fill in your personal info (Comment is username)
  • Enter passphrase if applicable

2. Backup your $HOME/.gnupg folder

  • Just in case you mess something up, you can always restore this backup. This folder holds all the public/secret keypairs, subKeys, revocation certificates and the trust database.

3. Create a new subKey (this can be repeated for each of the devices you want to provide subKeys for):

  • List all your keys with gpg -k
  • Edit your master key by typing gpg --edit-key PUBKEYFINGERPRINT, where PUBKEYFINGERPRINT is the fingerprint (a 40-character hex sequence) of your public key
  • On the gpg> prompt, type addkey
  • Choose RSA (sign only) as key type and enter following settings:
  • Key size: 4096 bits
  • Duration: 0 (infinite; does not expire)
  • Enter your passphrase if applicable
  • Type save to save your changes and exit back to the terminal

4. Store your $HOME/.gnupg folder on secure removable media:

  • Make another backup of your $HOME/.gnupg folder, just in case.
  • Copy your $HOME/.gnupg folder to a USB drive (or more).
  • Find the "keygrip" of your master key by using gpg -k --with-keygrip (should be the keygrip of the pub key)
  • Proceed deleting the KEYGRIP.key from the $HOME/.gnupg/private-keys-v1.d folder, where KEYGRIP is the keygrip of your master key. Do not delete this file from the USB drive(s)
  • If you do gpg -K your private key should display as sec#, indicating that it's not really there
  • Mount a USB drive with the backed up .gnupg folder
  • If you now do gpg --homedir="/GNUPGHOME/.gnupg/" -K, where GNUPGHOME is the path where the .gnupg folder resides on your USB drive, the private key should display as sec, indicating it is present on the drive.
  • You have successfully removed the private key from your $HOME/.gnupg folder.
  • Keep the USB drives somewhere safe, you will need them if you want to create a new subKey or revoke a compromised one.

5. Now copy your $HOME/.gnupg to a USB (or more) drives. These drives should be encrypted (e.g. by using BitLocker on Windows) and kept safe. When you need to use your master private/public keys (for example, to create a new subKey) you will have to mount the USB drive(s), decrypt, and set the GNUPGHOME environment variable to the drive's location. (e.g. by using export GNUPGHOME=/media/usbDriveMountName). If you type gpg -K the master key should show up as sec, indicating the private key exists.

6. Copy your $HOME/.gnupg folder to any devices you want.

7. Delete master private key from other devices:

  • Type gpg --with-keygrip --list-key YOURMASTERKEYID to find the "keygrip" of your master key
  • Proceed deleting the KEYGRIP.key from the $HOME/.gnupg/private-keys-v1.d folder, where KEYGRIP is the keygrip of your master key.
  • If you type gpg -K the master private key should show as sec#, indicating that the key is not really there.
  • If using a passphrase, make sure to gpg --edit-key YOURMASTERKEYID passwd and change the passphrase on the $HOME/.gnupg folder where your private key still exists. This will make sure that, if your passphrase on actual devices is compromised, the attacker will have to guess your new passphrase to gain access to your private master key.

8. Import the public key on Github:

  • Important: The public key needs to be re-uploaded whenever a new subKey is created or revoked.
  • Use gpg -k to list available keys.
  • Export the public key by gpg --armor --export PUBKEYFINGERPRINT, where PUBKEYFINGERPRINT is the fingerprint of the pub key (a 40-character long hex hash).
  • Copy the exported public key to clipboard.
  • Go to Github > Settings > SSH and GPS keys > New GPG Key and paste the public key and then click Add GPG Key to save it.

9. Use a subKey when signing commits and tags on Git:

  • gpg --list-secret-keys --keyid-format LONG
  • Copy your subKey ID
  • git config --global user.signingkey YOURSUBKEYID
  • To enable signing by default on all commits, type git config --global commit.gpgsign true
  • You might want to close any console windows before testing autosigning

References

https://help.github.com/en/github/authenticating-to-github/generating-a-new-gpg-key

https://help.github.com/en/github/authenticating-to-github/adding-a-new-gpg-key-to-your-github-account

https://help.github.com/en/github/authenticating-to-github/telling-git-about-your-signing-key

https://wiki.debian.org/Subkeys?action=show&redirect=subkeys

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment