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.
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.
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.
Requires firmware 5.2 and above to support the OpenPGP elliptic-curve cryptography (ECC) keys option.
Ideal for encryption with email or files.
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.
Download required packages.
YubiKeys using OpenPGP are typically configured using GnuPG (GPG). Select from the download tab.
For some MacOS or Linux OS’s use GPGTools. This is typically preinstalled in most MacOS computers.
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
This walk-through does not describe how to use OpenPGP; for that see the OpenPGP community or instructions provided by the service using OpenPGP. 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 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.
YubiKey Manager handles all these tasks.
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. YubiKeys 4 and newer devices meet this requirement.
Step 1. Open a command terminal, with GPG installed.
Step 2. (Optional) 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.
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 day-to-day PIN is: 123456
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!
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’.
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
To test your email encryption using the YubiKey keys you created in this walk-through, use the open source Mozilla email tool, Thunderbird.
Required: Thunderbird email
Required: Enigmail add-on. To donate to Enigmail
Optional: ExQuilla
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.
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.
Congratulations! You’ve completed all the steps to encrypt and authenticate with a PGP credential.
If you get stuck, you can check link: OpenPGP community pages or the GnuPG pages.
If you don’t receive an answer, or remain stuck, please file an issue or open a support ticket and we’ll help you out.