Skip to main content

This documentation is intended for internal use by the RE team.


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:
    • signatures
    • encryption
    • authentication
  • 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

(If not using a Mac, don’t try it with pinentry-mac)

Add the following line to your .bash_profile:

export GPG_TTY=$(tty)

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 a new YubiKey

You may be asked for a PIN whilst running through the following instructions. The default PINs are:

  • user: 123456
  • admin: 12345678

Follow these steps to setup the GPG on your YubiKey.

  1. Insert the YubiKey into the USB port.
  2. Open Terminal.
  3. Enter the GPG command: gpg --card-edit
  4. At the gpg/card> prompt, enter the command: admin
  5. Enter the command: key-attr, then select option 1 (RSA) and type 4096 when asked for key strength
  6. Enter the command: generate
  7. 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.
  8. Specify how long the key should be valid for (specify the number in days, weeks, months, or years). We recommend to say 0 to make sure the key never expires.
    • This may prompt you to enter a user PIN.
  9. When prompted, enter your name, email address and comment. We recommend that it is GDS specific.
    • Real Name: Rafal Proszowski
    • Email address:
    • Comment: GDS
  10. Review the name, email, and accept or make changes.
    • This may prompt you to enter an admin PIN.
  11. Enter the default admin PIN again. The green light on the YubiKey will flash while the keys are being written. This might take several minutes.
  12. 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 passwd and follow the steps on the screen. Press Q to quit interactive mode. TIP: although it’s called a “PIN” it can in fact be any alphanumeric passphrase
  13. Enter quit to finish setting up the key.

Use an existing Yubikey’s GPG key on a new laptop

  1. Insert the YubiKey into the USB port.
  2. Open Terminal.
  3. Enter the GPG command: gpg --card-edit
  4. At the gpg/card> prompt, enter the command: fetch
  5. At the gpg/card> prompt, enter the command: verify - this may prompt you for previously set PIN
  6. Enter quit

Publish public key to keyservers

  1. Obtain the Key fingerprint and Key ID by running: gpg -K --keyid-format 0xLONG
    • Key ID is the 18 character string after rsa4096/ on the first line of the output. For example: 0x0000000000000000
    • Key fingerprint (if present) is the 40 character string in the second line of the output. For example: 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000
  2. Publish your public key by running: gpg --keyserver --send-keys <KEY_ID>
    • 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.

  1. Obtain the Key fingerprint and Key ID by following the instructions above (“Publish public key to keyservers”)
  2. Run the following command to obtain your public key:

    gpg --armor --export <KEY_ID>

    TIP: Pipe output of above command into pbcopy to copy the output to your system clipboard ready for pasting.

  3. Go to GitHub settings to add the public key output above to your GitHub account.

  4. Add or update the [User] section in your ~/.gitconfig file similar to the example below to configure git to use the key for signing commits .signingkey should be set to your from above.

        name = Rafal Proszowski
        email =
        signingkey = <KEY_ID>
  5. (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://
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
keyid-format 0xlong
list-options show-uid-validity
verify-options show-uid-validity


pinentry-program /usr/local/bin/pinentry-mac
default-cache-ttl 60
max-cache-ttl 120

(If not using a Mac, drop the pinentry-program line)

After setting up these .conf files for GPG, you should kill the agent:

killall gpg-agent

Use YubiKey for 2FA in Amazon Web Services

Your Yubikey is capable of TOTP and U2F authentication. When configuring it as an MFA device in Amazon Web Services, be careful to NOT use the U2F option, as this will prevent you from using the AWS API. Instead, say it’s a Virtual device (as if it were like a phone or something) and use the TOTP functionality. gds-cli will look for a TOTP code named gds-users, but this can be overridden with the GDS_USERS_YUBIKEY_TARGET environment variable.

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:

  1. 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.

  1. 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 gpg-agent.

  1. You may wish to insert the following into your .bash_profile to invoke the gpg-agent on every terminal run:

    eval $(gpg-agent --daemon)
  2. After that change, restart your terminal, or run the above command yourself. If the gpg-agent is already running, run killall gpg-agent first.

  3. Once you’re running the gpg-agent with SSH enabled, you should be able to run:

    ssh-add -L

    That should display the public key that ends with something like cardno:000000000000.

  4. 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:

gpg --card-status

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:

export GPG_TTY=$(tty)

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.