PGP Walk-Through

We are going to walk through Yubico’s PGP support for signing and encryption, and explain how the PGP interaction works, step by step. Server and client registration and authentication ceremonies are incorporated through the backend in the key handling processes.

Tip
This walk-through is designed for people who prefer to learn by doing. If you prefer learning concepts from the ground up, check out our PGP developers guide. You might find this walk-through and the guide are complementary to each other.

The walk-through is divided into several sections:

  • Overview teaches you the fundamentals of PGP

  • Setup provides a starting point for you to follow the walk-through

  • Configure YubiKey explains the OpenPGP requirements and parameters

  • Loading Keys explains the steps to generate or import encryption master keys and subkeys

  • Upload your Public Key to a Key server explains the steps to ensure your email recipients can decrypt your encrypted email.

Overview

Configure the YubiKey with PGP (Pretty Good Privacy) to encrypt and sign your data and communications. PGP is based on the open standard OpenPGP. PGP is used in Gnu and Linux environments for email encryption. It also provides a toolbox to handle many common cryptographic operations.

For OpenPGP reference, see OpenPGP and for the download site, see GnuPG.

Gnu Privacy Guard (GPG) is the tool to use with OpenPGP standard. It is designed and used for personal data privacy, not necessarily for building into a larger framework. Use the set-up here to load your personal PGP keys (public and private key pair) onto YubiKeys.

In this context, the YubiKey is acting similar to a smart card. It holds the PGP authentication, signing, and encryption keys. It provides a framework for loading the YubiKey.

YubiKey features

  • It is a USB device that is both a smart card and a smart card reader; there is no extra hardware needed beyond the YubiKey.

  • It stores the private and public key.

  • All the encryption and decryption occur on the YubiKey, not on the computer.

YubiKey with PGP

  • Can be configured and used with any application that supports OpenPGP smart cards.

  • Does not support the OpenPGP elliptic-curve cryptography (ECC) keys option.

  • Cannot be used for web authentication.

The focus of this walk-through is to load your PGP keys onto your YubiKey. With the configuration steps you complete here, your users can use a YubiKey to load your personal PGP key. You and your users can then share your personal authentication, using peer to peer authentication. With this, you and your users can send, receive, encrypt, and decrypt email content. Also, you can have your application refer to these PGP keys for authentication and access.

Prerequisites

Download required packages.

  • YubiKeys using OpenPGP are typically configured using GnuPG (GPG). Select from the download tab.

  • For some MacOS software, such as OpenSC, use GPGTools. This is typically preinstalled in the Mac.

  • For Windows, select Gpg4win (includes Kleopatra)

  • YubiKey Manager, to ensure that the operating system recognizes the YubiKey as a smart card.

YubiKey Manager is available for Windows, OSX, and Linux. Installers for the different operating systems can be downloaded from the Yubico website using the links listed at: YubiKey Manager

Setup

This walk-through does not describe how to use OpenPGP; for that see the OpenPGP community. This walk-through also does not describe PGP with YubiKey client/server configuration. The tools all handle that.

This walk-through is about loading your RSA keys onto YubiKeys. When you complete this walk-through, you have:

  • A PGP-enabled RSA public-key cryptosystem.

  • A YubiKey smart card that holds a private key.

  • A device with a common interface that meets Public Key Cryptography Standards (PKCS), for example PKCS#11.

Configure YubiKey

YubiKey Manager handles all these tasks.

Task Prerequisites

  • GnuPG version 2.0.2 or later. Understand how GnuPG works. See GnuPG documentation, usage and setting PIN and reset codes.

  • Importing key, must be an RSA 2048 bit key.

  • YuibiKey admin PIN. An OpenPGP admin password.

  • YubiKey OpenPGP module version 1.0.5 or later.

Verify and GPG and PGP Prerequisites

Step 1. Open a command terminal, with GPG installed.

Step 2. Check the version of the OpenPGP firmware:

If you are using a YubiKey 4 or later, skip this step.

a) Insert your YubiKey in the computer.

b) Run the command:

$ gpg-connect-agent --hex "scd apdu 00 f1 00 00" /bye

D[0000] 01 00 05 90 00 .....

OK

In this example 01 00 05 means version 1.0.5

Step 3. Ensure that CCID (chip card interface device) mode is enabled.

From the YubiKey Manager, select Devices > your_device > Settings > Connection mode.

Alternatively, from the command line, with the YubiKey personalization tool, ykpersonalize Installed.

a) Verify the YubiKey firmware version is 3.1.8 or later.

$ lsusb -v

b) Set your device to OTP/CCID or CCID mode. Use ykpersonalize.

$ ykpersonalize -m6

c) Verify libccid version is 1.4.10 or later.

$ pkg info ccid

d) Verify ``/etc/libccid_Info.plist` contains YubiKey USB PID/VID

$ ls yubikey

e) Check PCSCD setup is working. Review response to PCSC scan for a reference to YubiKey.

$ pscs_scan

f) Verify scdaemon version is 2.0.22 or later.

$ scdaemon --version

Set the OpenPGP parameters.

From the command terminal, enter the listed GPG commands and verify the responses. For a list of gpg-card commands, type gpg -help.

Step 1. Open gpg-card options.

user@debian:~$ gpg --card-edit
Application ID ...: D2760001240102000060000000420000
Version ..........: 2.0
Manufacturer .....: unknown
Serial number ....: 00000042
Name of cardholder: [not set]
Language prefs ...: [not set]
Sex ..............: unspecified
URL of public key : [not set]
Login data .......: [not set]
Signature PIN ....: forced
Key attributes ...: 2048R 2048R 2048R
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 3 3
Signature counter : 0
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
General key info..: [none]

Step 2. Set administrator permission.

gpg/card> admin
Admin commands are allowed

Step 3. Change passwords Open password option.

You are changing two PINs: the admin PIN, and the day-to-day PIN

Have two PINs picked out – minimum 8 digits each (only digits, no symbols or letters). Or use an online random number generator

Safeguard these PINS very, very well and do not lose them.

gpg/card> passwd
gpg: OpenPGP card no. D2760001240102000060000000420000 detected
1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit

Step 4. Change Admin password. Enter the default PIN, to get permission to change.

The default admin PIN is: 12345678

Your selection? 3
12345678
PIN changed.
1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit

Step 5. Change day-to-day password. Enter the default PIN, to get permission to change.

The default admin PIN is: 12345678

Your selection? 1
PIN changed.
1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit
Your selection? q

Step 6. Optionally, set user information.

Use this to distinguish each user that has access to the encryption group.

gpg/card> name
Cardholder's surname: Josefsson
Cardholder's given name: Simon

gpg/card> lang
Language preferences: sv

gpg/card> url
URL to retrieve public key: https://josefsson.org/1c5c4717.txt

gpg/card> sex
Sex ((M)ale, (F)emale or space): m

gpg/card> login
Login data (account name): jas

gpg/card>
Application ID ...: D2760001240102000060000000420000
Version ..........: 2.0
Manufacturer .....: unknown
Serial number ....: 00000042
Name of cardholder: Simon Josefsson
Language prefs ...: sv
Sex ..............: male
URL of public key : https://josefsson.org/1c5c4717.txt
Login data .......: jas
Signature PIN ....: forced
Key attributes ...: 2048R 2048R 2048R
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 3 3
Signature counter : 0
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
General key info..: [none]

gpg/card> quit
user@debian:~$

Step 7. Optionally, activate YubiKey Touch.

Install custom bash script, yubitouch.sh.

$ ./yubitouch.sh sig on

All done!

Loading Keys

NOTE: Ensure your laptop is disconnected from the internet.

Load existing or generate new PGP keys to a YubiKey. Two key types are required: Master key that never changes. Sub keys that can change. There can be multiple Sub-keys per Master key.

  • Master key – used to manage. The master key cannot expire.

  • Sub keys – can be assigned conditions, for example expiration dates. Flash sign-in sub key and make new one. Keep master key.

Step 1 Preparing Keys. Choose to Import or Generate keys.

Import Existing Key.

To get the PGP keys off of a USB drive with the keys and onto the YubiKey:

a) Insert the USB thumb drive into the computer. Using File Explorer or Finder, locate the drive assigned to the USB drive. For example, D: or E: or whatever.

b) From command terminal, change to the location of the USB drive. For example:

$ cd D:

c) Confirm that the public and private keys are on the thumb drive by typing into the command terminal:

$ dir

This command displays a list files on the thumb drive.

d) Confirm that the keys are on your hard drive GPG key ring by typing into the command terminal:

$ gpg --list-secret-keys

e) Run the import command on both the public and the private keys.

This is a two-step process: First we import the keys onto the hard drive GPG key ring. Then transfer the keys from the hard drive onto the YubiKey.

To execute the first step, type the following into the command terminal:

$ gpg --allow-secret-key-import --import [my_private_key.asc]

This command imports both the public and the private key.

Generate a Master Key.

Complete this task only if do not have an RSA key to load. (If you generate a key on device, you do know where the device has been because you cannot export without the device and admin-never share option. If you use the import a key option, you can have a backup.)

If you have keys, skip this step and proceed to Step 2.

First your create Master key. Then your create sub-keys (Step 2).

a) Initiate the command driven wizard.

gpg --gen-key
gpg (GnuPG) 2.0.22; Copyright (C) 2013 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
Your selection?

b) Set size, type limits, and expiration date.

RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048)
Requested keysize is 2048 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0)

c) Associate a real name, email address, and optionally add a comment for this key. Confirm the provided information.

Real name:
Email address:
Comment:
You selected this USER-ID:
    "Foo Bar <foo@example.com>"
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit?

d) Record the ID of the key. In this example the ID is 13AFCE85.

We need to generate a lot of random bytes. It is a good idea to perform some other action (type on the keyboard, move the mouse, utilize the disks) during the prime generation; this gives the random number generator a better chance to gain enough entropy.

gpg: key 13AFCE85 marked as ultimately trusted
public and secret key created and signed.
gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0  valid:  4  signed:  8  trust: 0-, 0q, 0n, 0m, 0f, 4u
gpg: depth: 1  valid:  8  signed:  2  trust: 3-, 0q, 0n, 5m, 0f, 0u
gpg: next trustdb check due at 2014-03-23
pub  2048R/13AFCE85 2014-03-07 [expires: 2014-06-15]
Key fingerprint = 743A 2D58 688A 9E9E B4FC  493F 70D1 D7A8 13AF CE85
uid   Foo Bar <foo@example.com>
sub   2048R/D7421CDF 2014-03-07 [expires: 2014-06-15]

Step 2 Add an Authentication Key (sub-key).

a) Add authentication sub-key.

gpg --expert --edit-key 13AFCE85
gpg (GnuPG) 2.0.22; Copyright (C) 2013 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Secret key is available.
pub 2048R/13AFCE85 created: 2014-03-07 expires: 2014-06-15 usage: SC
                   trust: ultimate      validity: ultimate
sub 2048R/D7421CDF created: 2014-03-07 expires: 2014-06-15 usage: E
[ultimate] (1). Foo Bar foo@example.com

gpg> addkey
2048-bit RSA key, ID 13AFCE85, created 2014-03-07

b) Select 8 to attach another RSA key to our key.

Please select what kind of key you want:
   (3) DSA (sign only)
   (4) RSA (sign only)
   (5) Elgamal (encrypt only)
   (6) RSA (encrypt only)
   (7) DSA (set your own capabilities)
   (8) RSA (set your own capabilities)
Your selection?

c) Get a pure authentication key, select A, then S, then E. When done select Q to continue.

Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Sign Encrypt
   (S) Toggle the sign capability
   (E) Toggle the encrypt capability
   (A) Toggle the authenticate capability
   (Q) Finished
Your selection?

d) Set key size as 2048 bits.

RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048)

e) Select the same expiry you set previously. Confirm by entering y.

Requested keysize is 2048 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0)
Is this correct? (y/N) y
Really create? (y/N) y
We need to generate a lot of random bytes. It is a good idea to perform some other action (type on the keyboard, move the mouse, utilize the disks) during the prime generation; this gives the random number generator a better chance to gain enough entropy.
pub 2048R/13AFCE85 created: 2014-03-07 expires: 2014-06-15 usage: SC
                   trust: ultimate      validity: ultimate
sub 2048R/D7421CDF created: 2014-03-07 expires: 2014-06-15 usage: E
sub 2048R/B4000C55 created: 2014-03-07 expires: 2014-06-15 usage: A
[ultimate] (1). Foo Bar foo@example.com

gpg> Save changes? (y/N) y

Step 3 Backup your Key.

Create your backup and store it in a secure offline location.

gpg --export-secret-key --armor 13AFCE85

Step 4 Import the Key to your YubiKey.

a) Start import key.

gpg --edit-key 13AFCE85
gpg (GnuPG) 2.0.22; Copyright (C) 2013 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Secret key is available.
pub 2048R/13AFCE85 created: 2014-03-07 expires: 2014-06-15 usage: SC
                   trust: ultimate      validity: ultimate
sub 2048R/D7421CDF created: 2014-03-07 expires: 2014-06-15 usage: E
sub 2048R/B4000C55 created: 2014-03-07 expires: 2014-06-15 usage: A
[ultimate] (1). Foo Bar <foo@example.com>

b) Move the primary key to the YubiKey PGP Signature slot.

gpg> toggle
sec  2048R/13AFCE85  created: 2014-03-07  expires: 2014-06-15
ssb  2048R/D7421CDF  created: 2014-03-07  expires: never
ssb  2048R/B4000C55  created: 2014-03-07  expires: never
(1)  Foo Bar <foo@example.com>
gpg> keytocard
Really move the primary key? (y/N) y
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
Please select where to store the key:
   (1) Signature key
   (3) Authentication key
Your selection? 1
gpg> key 1
sec 2048R/13AFCE85 created: 2014-03-07 expires: 2014-06-15
                   card-no: 0000 00000001
ssb* 2048R/D7421CDF created: 2014-03-07 expires: never
ssb  2048R/B4000C55 created: 2014-03-07 expires: never
(1)  Foo Bar <foo@example.com>

c) Move the Encryption key.

gpg> keytocard
Signature key ....: 743A 2D58 688A 9E9E B4FC  493F 70D1 D7A8 13AF CE85
Encryption key....: [none]
Authentication key: [none]
Please select where to store the key:
   (2) Encryption key
Your selection? 2

d) Move the Authentication key to the YubiKey.

gpg> key 1
sec 2048R/13AFCE85 created: 2014-03-07 expires: 2014-06-15
                   card-no: 0000 00000001
ssb 2048R/D7421CDF created: 2014-03-07 expires: never
                   card-no: 0000 00000001
ssb 2048R/B4000C55 created: 2014-03-07 expires: never
(1)  Foo Bar <foo@example.com>
gpg> key 2
sec 2048R/13AFCE85 created: 2014-03-07 expires: 2014-06-15
                   card-no: 0000 00000001
ssb 2048R/D7421CDF created: 2014-03-07 expires: never
                    card-no: 0000 00000001
ssb* 2048R/B4000C55 created: 2014-03-07 expires: never
(1)  Foo Bar <foo@example.com>
gpg> keytocard
Signature key ....:743A 2D58 688A 9E9E B4FC 493F 70D1 D7A8 13AF CE85
Encryption key....:8D17 89A0 5C2F B804 22E5 5C04 8A68 9CC0 D742 1CDF
Authentication key: [none]
Please select where to store the key:
   (3) Authentication key
Your selection? 3

e) Save the keyring.

gpg> quit
Save changes? (y/N) y

The secret key is no longer stored on your computer. A pointer on the computer indicates that the secret key is stored on the YubiKey smart card.

Step 5. Confirm the keys are ‘sharded’ by using Kleopatra.

Open Kleopatra and navigate to the certificates list. A card icon next to each key indicates it is ‘sharded’.

Upload Your Public Key to a Keyserver

Step 1. Reconnect your laptop to the Internet.

Step 2. Open Kleopatra and select File > Export Certificates.

The default keyserver is Kleopata is keys.gnupg.net

To change the keyserver, select Settings > Configure Kleopatra

Demo – Using Thunderbird

To test your email encryption using the YubiKey keys you created in this walk-through, use the open source Mozilla email tool, Thunderbird.

Prerequisites

ExQuilla lets Thunderbird communicate to your Microsoft Exchange server in the EWS protocol.

It won’t make new email notification any better.

But will download email just as fast and will transfer over your existing Outlook folders better than if you configure Thunderbird with IMAP (assuming that your Microsoft Exchange server still supports IMAP).

It costs $10 / annually after a 60-day trial license.

Configure Enigmail

Ensure your encryption keys are ready. Complete the steps in this walk-through.

Step 1. Start the Enigmail setup wizard.

Step 2. The Enigmail Setup Wizard > Key Selection > Create A Key To Sign And Encrypt Email panel, displays the following message:

We have detected that you already have an OpenPGP key. You can either use one of your existing keys to sign, encrypt and decrypt emails, or you can create a new key pair.

Step 3. Click the option, I want to select one of the keys below to signing and encrypting my email.

Step 4. Select the Account/User ID you created.

If your Account/User ID and Key ID are listed, you have successfully implemented the YubiKey PGP encryption configuration.

Wrapping up

Congratulations! You’ve completed all the steps to encrypt and authenticate with a PGP credential.

Help, I’m Stuck!

If you get stuck, you can check link: OpenPGP community pages or the GnuPG pages.

If you don’t receive and answer, or remain stuck, please file an issue or open a support ticket and we’ll help you out.