Create a GPG key
We use GPG keys to encrypt our secrets. Documentation for using your GPG key can be found here.
Prerequisites
Install gpg
if you don’t already have it.
You can use brew install gpg-suite
to install the graphical GPG Suite. This comes with GPG Mail, which you may not want - you can install a mailless version by running brew install --cask gpg-suite-no-mail
instead.
If you have a YubiKey
If asked for a user and PIN by the YubiKey and you have never set your own, the defaults are: user: 123456 admin: 12345678
Creating a new GPG key
Insert the YubiKey into a USB port.
Enter the following command to the terminal:
gpg --card-edit
If the key has never been used before: at the
gpg/card>
, enterpasswd
then the default PIN. After this, you will be prompted to choose your own PIN for the device.At the
gpg/card>
prompt, enteradmin
, thenkey-attr
.Select the option for
ECC
thenCurve 25519
when asked for the key strength. You will be asked this 3 times (one each for the signature, encryption and authentication keys).Enter the command
generate
.You will be asked if you wish to make a backup of your key. This is not recommended unless the backup is stored securely.
When asked for the expiry, enter
0
to ensure your key never expires.Enter your real name and
digital.cabinet-office.gov.uk
email address.The green light will flash on the key whilst it is being written. This may take a few minutes.
Enter
quit
to exit.
Enabling your existing GPG key from a YubiKey on a new machine
Insert the YubiKey into a USB port.
Enter the following command to the terminal:
gpg --card-edit
At the
gpg/card>
prompt, enterfetch
, thenverify
.Enter
quit
to exit.
If you don’t have a YubiKey
Creating a GPG key (using the GUI)
GPGtools comes with a GUI which can perform most of the operations you need.
Before creating your key, make sure that your keyserver (the public server where your key is stored) is set to hkps://keys.openpgp.org/
(the default). You can do this by going to preferences and setting your keyserver.
To create a new key, click “New”. The Name
field should be your name. For Length
, you should have at least 4096.
The creation process will give you the option to upload to a public server. Say yes. You can check your key has been uploaded using the Lookup Key button in the GUI.
On the main page which lists all of your keys you can double click your key to get the required details (fingerprint and id).
See below for checking your passphrase.
Creating a GPG key (using the command line)
Create a gpg key with gpg --gen-key
using your
digital.cabinet-office.gov.uk email address. Defaults for the questions
should be fine, although you should choose a 4096-bit key.
Note
You should also generate a revocation certificate with
gpg --gen-revoke
and store it in a safe place (not on your laptop, maybe a USB stick in your locker).
Working out your key ID and fingerprint
gpg --fingerprint firstname.lastname@digital.cabinet-office.gov.uk
Should look something like this.
pub rsa2048 2013-02-08 [SC]
37CC 021A C5C2 4E27 C4D9 5735 9B0E 9DD1 90E6 5803
uid [ultimate] Firstname Lastname <firstname.lastname@digital.cabinet-office.gov.uk>
sub rsa2048 2013-02-08 [E]
The fingerprint is 37CC 021A C5C2 4E27 C4D9 5735 9B0E 9DD1 90E6 5803
,
and the key ID is 90E65803
— the last 8 characters of the fingerprint.
Save your public key to govuk-secrets
In the govuk-secrets
repository, dump your public key into the gpg_public_keys
directory then open a PR.
gpg --export -a --output ~/govuk/govuk-secrets/gpg_public_keys/your_name.asc your.email@digital.cabinet-office.gov.uk
Make sure your passphrase works
You can test your passphrase like this:
echo "1234" | gpg -o /dev/null --local-user YOUR_FINGERPRINT_WITHOUT_SPACES -as - && echo "The correct passphrase was entered for this key"
You will be prompted to enter your passphrase upon running this command then if you have entered your passphrase correctly you will see “The correct passphrase was entered for this key”.
Backup a GPG key
Backup and transfer GPG key to another computer (using the GUI)
To backup your key, select the key you want to backup in GPG Keychain and then click on “Export”. This will download your key in the following format:
Name (keyID) – Public.asc
or Name (keyID) – Secret.asc
Then add your key to an encrypted zip file (see below for how to do this) and store it somewhere else, for example your Google Drive.
On your new machine, click on “Import” in GPG Keychain and select the .asc
file your downloaded earlier.
When your key has been imported you should see it listed on the main page.
Instructions taken from GPG Tools FAQ
Creating an encrypted zip file using the terminal
To zip one file, go to the directory containing the file and then do:
zip -e {zipped filename} {original filename}
so to encrypt your GPG key you’ll use:
zip -e "Name (keyID) – Public.asc.zip" "Name (keyID) – Public.asc"
Extend an expired GPG key
If your GPG key has expired, the easiest way to update it is to extend the expiry date.
You may also find that you have sub-keys that are due to expire too. If you are using a Mac, the easiest way to check is to use the GPG Keychain application. In GPG Keychain, double-click on your key to see the details and go the the “Subkeys” tab. If you have a sub-key that is due to expire, you’ll be asked if you want to update it.
After extending (or renewing) your GPG key, you will need to extract the public key and raise a PR to update govuk_secrets
.