1. Yubico
  2. Business
  3. Guides

Using Your YubiKey with OpenPGP

Avatar
Erin
Created - Updated 

bulb-light-icon.svg Tip: If you haven't set a user PIN or an admin PIN for OpenPGP, the default values are 123456 and 12345678, respectively. If the user PIN and/or admin PIN have been changed and are not known, the OpenPGP application can be reset by following this article.

This article covers how to set up your YubiKey with OpenPGP. Before you begin, decide if you want to generate the private key on the YubiKey directly, or if you want to generate the private key off of the YubiKey and then move the subkeys to the YubiKey. To allow for your PGP keys to be backed up, best practice is to generate them externally, not directly on the YubiKey. Once keys have been moved to/generated on the device, you should then personalize the YubiKey by changing the PIN, setting the admin PIN, and so on. Changing the PINs can be done by running the following command:

gpg --change-pin.

Requirements

  • A compatible YubiKey
  • A current version of the GnuPG software installed
    • Windows: GPG4Win
    • macOS: GPG Suite
    • Linux: Pre-installed on all common distributions

 

Generating keys externally from the YubiKey (recommended)

bulb-light-icon.svg Tip: It is strongly recommended that the keys be generated on an offline system, such as a live Linux distribution like Ubuntu. Note that with live Linux, certain packages (like scdaemon) may need to be installed manually.
  1. Insert your YubiKey into a USB port if it is not already plugged in
  2. Enter the following command:
    gpg --expert --full-gen-key
  3. When prompted to specify the key type, enter 1 [for "RSA and RSA (Default)"] and press Enter
  4. Specify the size of key you want to generate. Do one of the following:
    • For a YubiKey NEO, enter 2048 and press Enter
    • For a YubiKey 5 Series, YubiKey FIPS Series, or YubiKey 4 Series, enter 4096 and press Enter
  5. Specify the expiration date of the key, and press Enter. Verify the expiration date when prompted.
  6. Enter your user information into the prompts
  7. Enter your Email Address and press Enter
  8. If desired, enter a Comment about this key, and press Enter (this can be left blank, if desired)
  9. Review the information you entered is correct, enter O (for okay), and then press Enter
  10. A dialog box is displayed to enter the passphrase for your key. While the key is being generated, move your mouse around and/or type on the keyboard to gain entropy. When the key has been generated, you will see several messages displayed. Make a note of the key ID that is displayed in the message such as gpg: key 1234ABC marked as ultimately trusted. The key ID in this case is 1234ABC, and you will need this key ID to perform other operations.

To add an authentication key

bulb-light-icon.svg Tip: Recent releases of GnuPG may have the default allowed actions to be both sign and encrypt. Please be sure to check the default allowed action before proceeding with adding the authentication key.
  1. Insert your YubiKey into a USB port if it is not already plugged in
  2. Enter the following command:
    gpg --expert --edit-key 1234ABC
    (where 1234ABC is the key ID of your key)
  3. Enter the following command:
    addkey
  4. Enter the passphrase for the key (this is the passphrase, and not the user PIN or admin PIN)
  5. When prompted to specify the type of key, enter 8 for RSA
  6. The default will be Sign and Encrypt. To select an authentication key, toggle S to disable sign, E to disable encrypt, and A to enable authentication
  7. Once you confirm that authentication is the current allowed actions, select Q to finish the selection
  8. Specify the key size
  9. Specify the expiration of the authentication key (this should be the same expiration as the primary key)
  10. When prompted to save your changes, enter Y (yes)

To add a signing key

bulb-light-icon.svg Tip: Recent releases of GnuPG may have the default allowed actions to be both sign and encrypt. Please be sure to check the default allowed action before proceeding with adding the authentication key.
  1. Insert your YubiKey into a USB port if it is not already plugged in
  2. Enter the following command (if you are not in edit mode already):
    gpg --expert --edit-key 1234ABC
    (where 1234ABC is the key ID of your key)
  3. Enter the following command:
    addkey
  4. Enter the passphrase for the key (this is the passphrase, and not the user PIN or admin PIN)
  5. When prompted to specify the type of key, enter 8 for RSA
  6. Initial default will be Sign and Encrypt. To select a signing key, enter A to enable Authentication. Optionally, if you want to disable Encrypt, press E to toggle it to disabled.
  7. Once you confirm that Authentication is the current allowed action, enter Q to finish the selection
  8. Specify the key size
  9. Specify the expiration of the signing key (this should be the same expiration as the primary key)
  10. When prompted to save your changes, enter Y (yes)

To create a backup of your key

  1. Insert your YubiKey into a USB port if it is not already plugged in
  2. Enter the following command:
    gpg --export-secret-key --armor 1234ABC<></>
    where 1234ABC is the key ID of your key
  3. Store the text output from the command in a safe place (e.g. print the text, save the text in password managers, save the text on a USB storage device)

To import the key onto your YubiKey

  1. Insert your YubiKey into a USB port if it is not already plugged in
  2. Enter the following command:
    gpg --edit-key 1234ABC
    where 1234ABC is the key ID of your key
  3. Enter the following command:
    keytocard
  4. When prompted if you really want to move your primary key, enter Y (yes)
  5. When prompted where to store the key, select 1. This will move the Signature subkey to the PGP signature slot of the YubiKey.
  6. Enter the following command:
    key 1
  7. Enter the following command:
    keytocard
  8. When prompted where to store the key, select 2. This will move the Encryption subkey to the YubiKey.
  9. Enter the following command:
    key 1
  10. Enter the following command:
    key 2
  11. Enter the following command:
    keytocard
  12. When prompted where to store the key, select 3. This will move the Authentication subkey to the YubiKey.
  13. Enter the following command:
    quit
  14. When prompted to save your changes, enter N (no). Otherwise, GPG will delete you key from your hard drive, and you won't be able to copy it to another YubiKey/keep it as a backup/etc. See here for a more detailed explanation.

Generating Your PGP Key directly on Your YubiKey (not recommended)

exclamation-triangle-icon.svg Warning: Generating the PGP on the YubiKey ensures that malware can never steal your PGP private key, but it means that the key can not be backed up so if your YubiKey is lost or damaged the PGP key is irrecoverable.
  1. Insert your YubiKey into a USB port if it is not already plugged in
  2. Open Command Prompt (Windows) or Terminal (macOS / Linux)
  3. Enter the following command:
    gpg --card-edit
  4. At the gpg/card> prompt, enter the following command:
    admin
  5. (Optional) If you want to use keys larger than 2048 bits, enter the following command:
    key-attr
  6. Enter the following command:
    generate
  7. When prompted, specify if you want to make an off-card backup of your Encryption key
    exclamation-triangle-icon.svg Warning: This is a shim backup of the private key, not a full backup, and cannot be used to restore to a new YubiKey.
  8. Specify how long the key should be valid for (specify the number in days, weeks, months, or years)
  9. Confirm the expiration date
  10. When prompted, enter your name
  11. Enter your email address
  12. Enter a comment, or leave blank
  13. Review the name and email, and accept or make changes
  14. Enter the default admin PIN again. The green light on the YubiKey will flash while the keys are being written.
  15. Enter a passphrase as the key will not allow you to pass without having a passphrase. If you do not enter a passphrase, generation will fail.

Using your YubiKey's OpenPGP function on multiple computers

In order to use the OpenPGP private keys stored on your YubiKey on computers apart from the one where they were generated, it is necessary to import the corresponding public keys. Refer to this guide for more information.

 

Further reading

For more advanced usage of the YubiKey's OpenPGP application with GPG, please refer to this guide.