Anyone with production access, which includes most (if not all) of Reliability Engineering, should be using a GDS issued YubiKey for:
- storage of GPG keys:
- ssh keys (e.g. for GitHub or SSH access)
In addition, it is advisable to use the YubiKey for:
- Time-based One Time Passwords (TOTPs)
- Universal 2nd Factor (U2F) authentication
How to setup YubiKey for GPG
We will generate the GPG key directly on the YubiKey you have received. This means that the private key cannot be exported at any point from now on, and will not be generated (or left behind) on your machine.
Generating the PGP on the YubiKey ensures that malware can never steal your PGP private key. However, this means that the key can not be backed up so if your YubiKey is lost or damaged the PGP key is irrecoverable.
You will need to install certain applications on your system.
If you have homebrew installed on your Mac, run the following:
brew install ykman gnupg coreutils pinentry-mac
Add the following line to your
This will ensure your GPG sessions happen in the terminal instead of relying on the GUI.
(Optional) YubiKey preparation
If you have set up GPG on your YubiKey before, you may need to reset the Key. Make sure your YubiKey is connected to your laptop.
Run the following command to clear all GPG data currently residing on your key.
ykman openpgp reset
This command will also print out your PINs. Make a note of them.
Setup GPG on YubiKey
You may be asked for a PIN whilst running through the following instructions. The default PINs are:
Follow these steps to setup the GPG on your YubiKey.
- Insert the YubiKey into the USB port.
- Open Terminal.
- Enter the GPG command:
- At the
gpg/card>prompt, enter the command:
- Enter the command:
- When prompted, specify if you want to make an off-card backup of your
encryption key. We recommend that you say
no. It brings no value.
- Specify how long the key should be valid for (specify the number in days,
weeks, months, or years). We recommend to say
0to make sure the key never expires.
- This may prompt you to enter a user PIN.
- When prompted, enter your name, email address and comment. We recommend that
it is GDS specific.
- Real Name:
- Email address:
- Real Name:
- Review the name, email, and accept or make changes.
- This may prompt you to enter an admin PIN.
- Enter the default admin PIN again. The green light on the YubiKey will flash while the keys are being written.
- You should change the two PINs on the key, to make sure a lost key doesn’t
allow new owner to sign in or decrypt data with your key. Type in
passwdand follow the steps on the screen. Press
Qto quit interactive mode. TIP: although it’s called a “PIN” it can in fact be any alphanumeric passphrase
quitto finish setting up the key.
Publish public key to keyservers
- Obtain the Key fingerprint and Key ID by running:
gpg -K --keyid-format 0xLONG
Key IDis the 18 character string after
rsa2048/on the first line of the output.
Key fingerprint(if present) is the 40 character string in the second line of the output.
- Publish your public key by running:
gpg --keyserver keys.gnupg.net --send-keys <KEY_ID>
- These servers can be unreliable. If it fails, try again or try with
different server, for instance
- These servers can be unreliable. If it fails, try again or try with different server, for instance
Publish public key to GitHub and configure git
You should add the public key to GitHub to identify your commits with GPG signatures.
- Obtain the Key fingerprint and Key ID by running
gpg -K --keyid-format 0xLONG
KEY_IDis the 18 character string after
rsa2048/on the first line of the output. For example:
Key fingerprint(if present) is the 40 character string For example:
0000 0000 0000 0000 0000 0000 0000 0000 0000 0000
Run the following command to obtain your public key:
gpg --armor --export <KEY_ID>
TIP: Pipe output of above command into
pbcopyto copy the output to your system clipboard ready for pasting.
Go to GitHub settings to add the public key output above to your GitHub account.
Add or update the
[User]section in your
~/.gitconfigfile similar to the example below to configure git to use the key for signing commits .
signingkeyshould be set to your
[user] name = Rafal Proszowski email = email@example.com signingkey = <KEY_ID>
(Optional) Set git to always sign commits:
git config --global commit.gpgsign true
(Optional) Tuning GPG agent
You should create any files that do not exist yet.
These will provide a better user experience and some security.
auto-key-locate keyserver keyserver hkps://hkps.pool.sks-keyservers.net keyserver-options no-honor-keyserver-url personal-cipher-preferences AES256 AES192 AES CAST5 personal-digest-preferences SHA512 SHA384 SHA256 SHA224 default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed cert-digest-algo SHA512 s2k-cipher-algo AES256 s2k-digest-algo SHA512 charset utf-8 fixed-list-mode no-comments no-emit-version keyid-format 0xlong list-options show-uid-validity verify-options show-uid-validity with-fingerprint use-agent require-cross-certification
enable-ssh-support pinentry-program /usr/local/bin/pinentry-mac default-cache-ttl 60 max-cache-ttl 120
After setting up these
.conf files for GPG, you should kill the agent:
Use YubiKey for 2FA in GitHub account
You can use your YubiKey as your 2FA device for GitHub. This is more convenient (insert key and press the gold disk when prompted) and more secure than an authenticator app on your phone:
- Visit your GitHub account settings to add your YubiKey as a U2F device.
Use YubiKey for 2FA in Google account
You can use your YubiKey as your 2FA device for Google Account.
- Visit your google account settings to add your YubiKey as a Security Key
(Optional) Use YubiKey for SSH
Assuming you have modified your
~/.gnupg/gpg-agent.conf as per Tuning GPG agent section, you should be enabling the support for SSH already.
What you will end up doing, is replacing the
ssh-agent with the
You may wish to insert the following into your
.bash_profileto invoke the
gpg-agenton every terminal run:
eval $(gpg-agent --daemon)
After that change, restart your terminal, or run the above command yourself. If the
gpg-agentis already running, run
Once you’re running the
gpg-agentwith SSH enabled, you should be able to run:
That should display the public key that ends with something like
Use the public key where SSH access is required. GitHub for instance.
If the YubiKey is inserted but you still get errors like this:
error: gpg failed to sign the data fatal: failed to write commit object
When trying to
git commit, there are a couple of things you should check.
First, check that GnuPG can read the right private key off your YubiKey, with:
Look for a line starting with
sec> and make sure it shows the key ID that
you’ve specified in your Git configuration.
Next, in case the GnuPG agent is attempting to use the wrong TTY, try:
Now to test that everything’s working you can try signing some text:
echo "test" | gpg --clearsign
If you’re trying to change the Admin PIN and getting an error like “Conditions of use not satisfied”, this means your new PIN is less than 8 characters.