GPG Keys - alphagov/notifications-manuals GitHub Wiki

We currently use GPG keys for encrypting and decrypting credentials in the notifications-credentials repo.

Using a Yubikey makes it easier to migrate to a new machine, without copying files over.

Getting started

Install GPG tools

# make sure you have v2.0 or greater!
gpg --version

# if not, try reinstalling it
brew uninstall gpg --ignore-dependencies
brew install gnupg

Configure GPG tools

Add the following to your ~/.zshrc:

# reload your terminal after adding
export GPG_TTY=$(tty)

Edit ~/.gnupg/dirmngr.conf like this:

keyserver hkps://keys.openpgp.org
standard-resolver

Edit ~/.gnupg/gpg-agent.conf` like this:

# not needed if using a yubikey
default-cache-ttl 600

Then run gpgconf --reload.

Setup a GPG key pair

Two options for new keys:

👉 Use your Yubikey (recommend)

👉 Create a key pair on your Mac

You may also want to:

👉 Switch to using a Yubikey (migrate both the master and encryption keys)

👉 Use your Yubikey on a new Mac

Check it works OK

Check encryption / decryption works with:

echo 'message' | gpg --encrypt --armor --recipient <your email> | gpg --decrypt

Upload public key

After you create your keys, make sure you upload the public key to a remote key server, so that others can verify your commits and encrypt stuff for you to see. To do this, run the following:

# get your key fingerprint
gpg -K

# upload your public key
gpg --keyserver keyserver.ubuntu.com --send-keys <fingerprint>

## Check your key is uploaded correctly.
Go to https://keyserver.ubuntu.com/
Enter your KEY id and hit "search Key"
It should show your newly uploaded key
Overview of gpg -K A typical GPG setup looks like this (`gpg -K`): 
sec   rsa4096 2021-02-10 [SC]
      0C199BFCBA89508A36751A199600E79E7F2F66ED
uid           [ultimate] Ben Test <[email protected]>
ssb   rsa4096 2021-02-10 [E]
ssb   rsa4096 2021-02-10 [S]

It's worth understanding what this output means:

  • sec refers to the "master" key, which can be used for signing (S) and certifying subkeys (C).
  • 0C199BFCBA89508A36751A199600E79E7F2F66ED is the public key fingerprint, for sharing with others.
  • ssb ... [E] means an encryption subkey is present, for encrypting/decrypting credentials.
  • ssb ... [S] means a signing subkey is present, for signing git commits.

GPG will automatically use the right key, depending on the task (signing, encrypting, etc.).

Setup commit signing

Follow the instructions here.

You'll then want to add your gpg public key to github here. You can get your public key by running:

gpg -a --export "<my name>"

You may want to sign commits globally, for all repos:

git config --global commit.gpgsign true

If you store your GPG key on a Yubikey, you will only need to enter your PIN once to sign a commit, unless: you remove the card, or the card receives another command (e.g. from an authenticator app).

Create a new key pair

Use your Yubikey (recommended)

First you should change the default PIN for the OpenPGP applet on the Yubikey:

gpg --edit-card

gpg/card> admin # expose admin commands / admin mode
gpg/card> passwd # change the PIN (default is 123456) and the admin PIN (default is 12345678)

If the applet is set to generate keys of 2048 bits (check the key attributes field when you run gpg --edit-card), change it to 4096:

gpg --edit-card

# follow the instructions for each key
# set kind to RSA
# set keysize to 4096
gpg/card> key-attr

Now generate a new key pair on on the Yubikey:

gpg --edit-card

gpg/card> admin # expose admin commands

# follow the instructions
# set keysize to 4096
# set expiry to 0 (never)
gpg/card> generate

When prompted, get the revocation key and store this somewhere safe (not on your Mac).

👉 Back to getting started

Setup a GPG key pair

Run the following:

gpg --full-gen-key
1. Choose (9) ECC (sign and encrypt) *default*
2. Choose (1) Curve 25519 *default*
3. Choose 0 = key does not expire
4. Enter your full Name
5. Enter your email address
6. Hit 'O' for OK
7. Enter a password of your choice twice (must contain a number)

This will only generate a master key (SC) and an encryption subkey (E). If you like, you can generate a separate signing subkey (S) using the gpg --edit-key command. However, there's little point in doing this, because:

  • You can't move it to your Yubikey, as we need to use the "Signature" slot for the master key (see below). This is one reason why it's better to use a Yubikey in the first instance, since the master key can then be stored separately.

  • All the GPG keys are stored together anyway (on your Mac or Yubikey), and it's easy to change them if we need to. (In more security-conscious setups, you would typically store your master key offline in a safe, or something like that.)

👉 Back to getting started

Use your Yubikey on a new Mac

This may not work straight away:

error: gpg failed to sign the data
fatal: failed to write commit object

# returns nothing (no keys in your keychain)
gpg -K

Make GPG aware of the key pair:

# quit straightaway, or...
gpg --edit-card

# try to decrypt something
notify-pass ...

Created the gpg keypair but do not yet have an yubikey ?

gds-cli config ask-for-mfa

Obs: See other options by running:

gds-cli config help

👉 Back to getting started

⚠️ **GitHub.com Fallback** ⚠️