Part 2/2: Email Encryption with the Yubikey-NEO, GPG and Linux

20150816_161020

Part 2/2: Yubikey Configuration and Integration with GPG, Thunderbird and Enigmail

In Part 1 of this write-up I explained the importance of end-to-end encryption and how to generate your own signing and encryption keys with GnuPG. In Part 2 (the final installment), I’ll run through:

  • installing prerequisite packages (Fedora, Ubuntu) to enable smart card functionality in Linux with GPG (v2)
  • configuring your Yubikey to act as a smart card device
  • moving your subkeys onto the Yubikey using the keytocard operation

Step 2-1: Install Prerequisite Packages

(dependencies that are automatically installed are not listed):

Ubuntu: add the yubico stable PPA (ppa:yubico/stable) to your repository list and install the following packages:

pcscd, scdaemon, gnupg2, gpgsm, pcsc-tools, 
yubikey-personalization-gui, yubikey-neo-manager,
yubikey-personalization, scdaemon

Fedora: install the following packages:

yubikey-personalization-gui, pyside-tools, libykneomgr, 
pcsc-lite, gnupg2, gnupg2-smime, pcsc-tools, pcsc-lite-ccid

If your installation is running the gnome-keyring daemon, further configuration is required before gpg2 card status/card reading commands work properly. This write-up has an excellent work-around of getting the keyring daemon working; in addition to MATE, I’ve noticed that the gnome keyring daemons running with XFCE/LXDE also fail to provide support without this work around.

We now have all of the pre-requisite packages installed. Smart-card functionality is disabled on the Yubikey NEO by default (as of 2015-Aug) so we need further configuration before testing gpg2’s functionality with it.


Step 2-2: Configure the Yubikey-NEO to Support Smartcard functionality

There are many tutorials that will walk through setting up one-time password/U2F functionality, but operational flags need to be set on the device in order for it to support smart-card (CCID) functionality. The ykpersonalize tool allows us to configure the yubikey with the following flags (these can be found in the man-page or help dialog of the ykpersonalize command line tool)

ykpersonalize -mX
X = 0, OTP device only
X = 1, CCID device only
X = 2, OTP + CCID
X = 3, U2F device only
X = 4, OTP + U2F
X = 5, U2F + CCID
X = 6, OTP + U2F + CCID
+80 to enable MODE_FLAG_EJECT

Adding 80 to the flag number (e.x. for OTP + CCID, -m82) will enable the MODE_FLAG_EJECT functionality, in which tapping on the capacitative button on the device will trigger eject/insert of the device (more details here). In my case, I wanted the Yubikey to work with one-time password, U2F and CCID functionality and I did NOT want any eject/insert functionality with the tap button, so the following configuration setting should be sufficient in most settings

sudo ykpersonalize -m6

Note that the -m6 flag is supported for newer yubikeys (with newer firmware) … the -m82 flag has been reported to work well with older hardware but you will lose U2F functionality. After this command we will have enabled the smart-card functionality of our yubikey! We can check to see if the system is reading it by first removing and re-inserting the yubikey and running the following commands:

gpg2 --card-status
pcsc_scan n

Since we haven’t moved anything to the card, the output of gpg2 –card-status should be something like:

gpg2 --card-status:
Application ID ...: (redacted)
Version ..........: 2.0
Manufacturer .....: Yubico
Serial number ....: (redacted)
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 ...: rsa2048 rsa2048 rsa2048
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]

Before we get into moving our subkeys from Part 1 on to the yubikey, we need to configure and add information to some of the fields listed above. Of note, the admin-PIN and PIN (which you will use with your certificates) need to be configured.  We can do all these via the gpg2 –card-edit command.

The default admin-PIN is usually 12345678, while the default regular PIN is 123456. 

gpg2 --card-edit:
Application ID ...: (redacted)
Version ..........: 2.0
Manufacturer .....: Yubico
Serial number ....: (redacted)
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 ...: rsa2048 rsa2048 rsa2048
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>

We have now entered the “gpg/card” prompt in which we configure the Yubikey’s smartcard functionality. Typing in “help” at this prompt will provide a list of all available commands for further configuration. The most important one is the “passwd” command which will allow us to change our PINs. (however, ensure that the “admin” command is entered first so that we can change our admin PIN).

gpg/card> help
quit         quit this menu
admin        show admin commands
help         show this help
list         list all available data
fetch        fetch the key specified in the card URL
passwd       menu to change or unblock the PIN
verify       verify the PIN and list all data
unblock      unblock the PIN using a Reset Code

gpg/card> admin
Admin commands are allowed

gpg/card> passwd
gpg: OpenPGP card no. (redacted) detected
1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit
Your selection?

Follow the prompts to change Admin PIN (3) and change PIN (1). In the –card-edit prompt, it is also worth setting your name and url from which your public key is fetched when you use the yubikey as a smartcard on other devices. Quit or exit out of the –card-edit prompt when done. You can re-check your information using –card-status after you are finished to ensure that these fields are properly set.

Hooray, now, we are done configuring our smartcard interface of the Yubikey and ready to load our subkeys that we generated in Part 1!

Step 2-3: Load the Subkeys from Part 1/2 onto the Yubikey:

Now, we are ready to move our subkeys we generated from Part 1 over to the yubikey. We will be using the keytocard operation of gpg’s –edit-key prompt to do this. A couple of things to keep in mind, however:

  • you will be moving the encryption and signing subkeys on to the card;
  • this means you cannot move the subkey from the Yubikey back on to your computer. Consequently, it is very important to backup your keys once they are generated and before your invoke the keytocard operation (backup operations were emphasized and outlined at the end of Part 1 of this guide).
  • The yubikey can hold 3 subkeys in their respective slots: signing, authentication, encryption. When using the keytocard operation, place the selected key into the appropriate slot.
  • Remember to use the “toggle” command in the edit-key prompt before invoking keytocard, so you can select the appropriate subkey to move.

See the terminal output below for how I moved my signing subkey to the yubikey:

gpg2 --edit-key ankitrasto@emaildomain.com:

Secret key is available.

sec rsa2048/AB21D6A2
 created: 2015-08-15 expires: never usage: SC 
 trust: ultimate validity: ultimate
ssb rsa2048/17126EAA
 created: 2015-08-15 expires: never usage: E 
ssb rsa2048/2CE36C5C
 created: 2015-08-15 expires: never usage: S 
[ultimate] (1). AnkitRasto <ankitrasto@emaildomain.com>

gpg> toggle

sec rsa2048/AB21D6A2
 created: 2015-08-15 expires: never usage: SC 
 trust: ultimate validity: ultimate
ssb rsa2048/17126EAA
 created: 2015-08-15 expires: never usage: E 
ssb rsa2048/2CE36C5C
 created: 2015-08-15 expires: never usage: S 
[ultimate] (1). AnkitRasto <ankitrasto@emaildomain.com>

gpg> key 2

sec rsa2048/AB21D6A2
 created: 2015-08-15 expires: never usage: SC 
 trust: ultimate validity: ultimate
ssb rsa2048/17126EAA
 created: 2015-08-15 expires: never usage: E 
ssb* rsa2048/2CE36C5C
 created: 2015-08-15 expires: never usage: S 
[ultimate] (1). AnkitRasto <ankitrasto@emaildomain.com>

gpg> keytocard 

...

Do the same as above for the key number appropriate for encryption and follow the prompts that the keytocard operation generates. Depending on your system’s policies, you may be asked for your private key passphrase during the keytocard operations.

Now, verify everything’s working with your gpg2 –card-status command, and the output should look something like:

gpg2 –card-status

Application ID ...: (redacted)
Version ..........: 2.0
Manufacturer .....: Yubico
Serial number ....: (redacted)
Name of cardholder: Ankit Rasto
Language prefs ...: [not set]
Sex ..............: Male
URL of public key : [not set]
Login data .......: [not set]
Signature PIN ....: forced
Key attributes ...: rsa2048 rsa2048 rsa2048
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 3 3
Signature counter : 18
Signature key ....: XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX
 created ....: 2015-08-15 12:00:00
Encryption key....: XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX
 created ....: 2015-08-15 12:00:00
Authentication key: [none]
General key info..: sub rsa2048/2CE36C5C 2015-08-15 Ankit Rasto <ankitrasto@emaildomain.com>
sec rsa2048/AB21D6A2 created: 2015-08-15 expires: never 
ssb> rsa2048/17126EAA created: 2015-08-15 expires: never 
 card-no: (redacted)
ssb> rsa2048/2CE36C5C created: 2015-08-15 expires: never 
 card-no: (redacted)

As you can see, the yubikey now has stored signature and encryption subkeys … these fields are no longer blank!

Conclusion

We should now have a properly operational yubikey that we can use to sign and encrypt across multiple devices. In order to use your yubikey on another system, simply ensure that  the system has smartcard functionality (i.e. for another Linux device, install the appropriate packages as listed in this guide). You also need to have the public key loaded on to the system on which you intend to use the yubikey. This can be accomplished by using the “fetch” command in the gpg2 card-edit prompt (assuming you have an appropriate URL set in the card’s properties) or simply importing it manually via gpg.

Go ahead and try some signing, encryption and decryption operations from the command line … you will notice that without your yubikey inserted into your USB slot, these operations will no longer work with the key you generated in Part 1.

Alongside the commandline, we can now use our Yubikey and keypair with a variety of email clients which support PGP. Some examples are Thunderbird + the Enigmail add-on for desktop OSes, and K9-mail with OpenKeychain for Android (if your phone supports NFC).

References

  1. http://blog.josefsson.org/2014/06/23/offline-gnupg-master-key-and-subkeys-on-yubikey-neo-smartcard/
  2. https://jclement.ca/articles/2015/gpg-smartcard/
  3. https://www.2realities.com/blog/2014/11/04/yubikey-slash-openpgp-smartcards-for-newbies/
  4. https://yubico.github.io/yubikey-personalization/ykpersonalize.1.html
Advertisements