Yubico Forum

WARNING:
since 1st July 2014 the Yubico applets: OpenPGP, YubiOATH(AKA Yubico Authenticator), Yubico PIV - come PRE-INSTALLED. 99% of the users will not need to touch GPShell nor Yubikey NEO Manager. Don't execute commands which you do not understand you may disable your device




Requirements:
A Yubikey Neo, A computer with an internet connection and a Debian installation CD. Oh and a lot of time...

Description:
This guide will take you from a Debian installation CD, through all the dependencies, compiling and installing a new applet for the Neo and finish with preparing and copying GPG subkeys on the Neo (not generating directly on the Neo). I doubt many people will need the whole guide but hope that parts of it will be of use to some.


Initial Linux Setup

The first thing you will need to do is get a Yubikey Neo.

For this guide I started with a fresh install of Debian 7.3.0 64 bit from the netinstall image and then upgraded to testing (from Wheezy to Jessie). I did not install the Desktop or Print Server components during install but if you do this with a desktop installation then it should not make much difference. Any recent Linux distro should work but writing this guide from a fresh install means you can reproduce my steps exactly if required. I had multiple issues with Gnupg 2.0.19 which is the version in Debian Stable which is why I upgraded to Testing which has version 2.0.22 (improved support for card readers).

The first step is therefore to install Debian Stable and check internet access is working. To upgrade to Debian Testing edit /etc/apt/sources.list and change every instance of the word wheezy to jessie. Then start the upgrade - this step will take a while.

After upgrading I always prefer to reboot to ensure there are no unexpected issues that will appear next time I turn the machine on. There are then a few packages that you need to install from the repositories so you might as well get them all now:

To compile the new applet for installing on your Yubikey you will need:


To compile the Yubikey Personalisation Tool you also need:

And to compile gpshell (for installing the new applet on the Neo) you need:

GPG version 2 is required for this:

Finally to actually access the card you need pcsc:

Download the Java Card Classic Development Kit from http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-javame-419430.html#java_card_kit-2.2.2-oth-JPR, then extract some of the files:



Compile the new Applet

Then you will need to download and compile an upgraded applet from https://github.com/Yubico/ykneo-openpgp ... res/jckit3. Download the applet source directly from https://github.com/Yubico/ykneo-openpgp/archive/master.zip, unzip and compile it.


You should now have a cap file in the sub folder applet/bin/openpgpcard/javacard/openpgpcard.cap


Enable CCID mode on Neo

By default the Yubikey Neo does not have CCID smartcard functionality enabled, so that needs to be turned on. http://opensource.yubico.com/yubikey-personalization/


Note: If you want a slightly quicker way to do this then download the Windows version - it comes with a pre-compiled executable so you can jump straight to running the command.


Plug in your Neo now - you are ready to enable the CCID functionality.


Confirm that you want to set mode 0x82 Take the NEO out and plug it back in to restart it in the new mode.


Install updated openPGP Applet on Neo

Download the gpshell, global platform and the gppcscconnectionplugin from http://sourceforge.net/projects/globalplatform/




Unplug the Neo and plug it in again so it is detected correctly. Now you need to go back to the ykneo-openpgp-master folder (from when you compiled the applet) and install the applet on the Yubikey:

You should be rewarded with several screens of text rushing by.


Prepare GPG key and back it up

The Yubikey NEO can support GPG keys up to 2048 bit RSA - bigger keys will not fit. A lot of people store their main key offline and generate encryption and signing subkeys which they import onto a card for day to day use. This has the advantage that if the card is lost they can just generate new encryption and signing subkeys and their main GPG identity will not lose all the signatures which validate their real identity. Another advantage is that the main key can then be 4096 bits in strength (if you are that paranoid) and the subkeys only 2048 bit so they fit on the The certification part of the key is not present however so they will not be able to certify any other persons key is genuine without getting access to their main/full key.

By default GPG will create 2 keys - the first is used for signing (files) and certifying (other GPG keys). The second is used for Encryption. I'm going to create a new subkey for signing so only this goes onto the Yubikey. Gpg outputs a lot of text and this post feels big enough already so I'm going to skip most of the output - you will get far more on your screen than is shown here.

First to add a new signing key of 2048 bit size. My main key ID in this example is 3edda8ae - change this for your ID:

You should now be able to see the extra line ending in "usage: S" to denote the signing only key. If you are using an existing key and the Encryption key is not shown as "sub 2048R" then you will need to create a new encryption subkey as above but choosing "RSA (encrypt only) as the type.

Final step before you move the keys to the Neo is to back them all up. If you do not want to trap your only copy of the private key on a Neo then back it up first! Once more because this step is important: BACK UP YOUR KEYS!



Move these backup files somewhere safe - you do not want to accidentally overwrite or delete them. Next lets put the encryption subkey onto the Yubikey (you need to pulg the Yubikey in now if it is not already):


Move the keys to the Neo


"key 1" selects the first subkey (it is shown with an asterisk). "keytocard" MOVES the selected subkey to the card after you have confirmed both the gpg pass-phrase as well as the card administrator pin. There is only one slot to store this kind of key so you need to choose option 2. Finally the keys are shown but with the encryption key having a card number underneath it to show it is no longer present on the computer.

Next we need to move the signing key to the NEO:

"key 1" deselects the first (encryption) subkey, then "key 2" selects the second (signing) subkey. "keytocard" is used to MOVE the signing subkey to the NEO. Finally quit saving changes.

As a quick test remove the Neo. Encrypt a random file to this new key and then try to decrypt it - you will get an error:

Now plug the NEO in again and run exactly the same command:


The output at the end will be the secret message you added to test.txt. This would only be possible to decrypt with the NEO plugged in, as only a stub of the private encryption key is stored on the local hard drive.

You can now backup the private key from your computer (which only contains a stub of the full private key). This stub and the public key you saved earlier can be manually imported on any other computer without risking loss of control of your keys as you also need the Yubikey connected to use it.

From your working computer:

Copy those 2 files to another computer and import them with:

You can make life a bit easier in 2 ways. Firstly if you upload your key to a keyserver then you can automatically pull down the required files with this command (after plugging in the NEO):



If however you do not want to upload this key to the public keyservers you can upload it to a specific url and program the NEO to look there. The --armor switch below instructs gpg to only use a character set that is safe to use in emails (mail programs have a habit of treating some obscure characters inconsistently which is not good if those characters are in the middle of your key!

# gpg2 --armor --export 3edda8ae > public_key_armor.key

Upload this file to anywhere you control and make a note of the direct link to the file. I uploaded to my Dropbox account so for me the file was accessible at https://dl.dropboxusercontent.com/u/120 ... _armor.key. We need to add this link to the URL field of the NEO:

You can check this worked as expected by running gpg2 --card-status and checking the output now contains your URL. To make this a decent test I am going to delete the entire local public and private keyring files, then import the keys using the NEO and online public file before repeating the encryption test I performed earlier to prove decryption only works with the NEO installed. First to delete the local files:


Trying to list keys will now just show GPG creating new keyring files:
:~/.gnupg# gpg2 --list-keys
gpg: keyring `/root/.gnupg/pubring.gpg' created
gpg: /root/.gnupg/trustdb.gpg: trustdb created

Time to fetch the public key. Plug in the NEO and run the following commands:


You can now try encrypting a message to your private key and it will only decrypt if the NEO is plugged in:

Congratulations! Firstly for reading through everything above (assuming you didn't cheat and skip all the way down here!) You should now have a GPG key which you can use relatively easily on any computer with GPG but you do not need to place the private key on that computer. For me this means I can freely use my personal GPG key on work computers without any chance of losing control of a copy, but it could just as easily be that you want to protect your work GPG key when visiting client sites.

I have not tested this thoroughly on different distributions but as far as I know any distro with gnupg 2.0.22 available should also meet the other requirements. If you know of any distros that this will or will not work on then please let me know and I'll update this guide. Any questions please ask - I'll help if I can.


Changing the user and admin pin on the NEO
Use of the gpg key stored on the NEO requires you to enter a pin code (default is normally 123456). Getting the pin code wrong 3 times locks the user pin. The default admin pin is normally 12345678. Getting the admin pin code wrong 3 times will lock the card and cannot be reset. Make sure you remember these pin codes!

use the "gpg --change-pin" command and change both the user and admin pin to something you will remember:



Other things to do
There are several other things you should do to if you have not already:

• Generate revocation certificates
• Upload to public keyservers
• Store your key backups somewhere secure and offsite
• Use the Neo to authenticate SSH connections (good guide at http://www.bradfordembedded.com/2013/12/yubikey-smartcard/)

Problems...
There are a few problems that are worth bearing in mind when following this guide depending on how secure you want your end result to be.

Randomness matters. A computer builds up a pool of entropy from various sources during use. This entropy is then used by /dev/random when anything needs random numbers - however on a clean install with no extra software running that has probably only just booted up there is not much entropy to go around. This could lead to weak keys being generated. A program like haveged may well eliminate this problem if you can not use a genuine hardware random number generator like the Entropykey (I know nothing about this project beyond the fact is looks cool and is reasonably cheap).

By using Debian Testing I am also using a system with less immediate security patching. Stable Debian receives security patches very quickly and Unstable Debian also receives them quickly (but then it receives everything quickly, including patches, new software and new bugs/security problems - that is why it is called "Unstable" Testing Debian tends to receive updates after they have been tested a for a while and have no known serious bugs so sometimes a security problem might be unpatched on Testing after both Stable has been patched and Unstable has received a newer version that also fixes the problem. Alternatives if you are concerned - gnupg 2.0.22 is not in Debian Backports so you could either manually install packages from the Debian Jessie repository or use a different distro with a later version of gnupg. Or compile gnupg from source if you were feeling adventurous.

I did all this as the root user. Normally bad but in my defense: A lot of this had to be done as root anyway, you need to trust the system you are generating the keys on completely (eg don't use if for browsing facebook!) and you have to trust the software you are installing completely. Since I'm using a fresh minimal install and not connecting to random internet sites the risks are minimized.


Troubleshooting


Yubikey Neo not recognised as a CCID device.
If you are using an older distro that does not fully recognise the Yubikey Neo as a ccid device then you need to take a few more steps:

A Debian Wheezy install I have been using does not know that the Yubikey can be a smart card. Not too hard to fix though: edit /etc/libccid_Info.plist. You need to add two lines at the top of 3 sections.
Find array ifdVendorID and add the following two lines at the top:

Find array ifdProductID and add the following two lines at the top:

Find array ifdFriendlyName and add the following two lines at the top:


Restart the service:


Unplug and replug the neo and the output of dmesg should now include "Yubikey NEO OTP+CCID"


Guides used to create this guide:

Far too many web pages to list fully, but the main sources of information I used were:
https://github.com/Yubico/ykneo-openpgp

Yubico Forums eg: Adding the Yubikey Neo to known hardware (not required in the end as I switched to Debian Testing) viewtopic.php?f=26&t=982&start=10#p3767
Creating subkeys and seperating out from the main key for security reasons: http://www.void.gr/kargig/blog/2013/12/ ... h-subkeys/
How to add GPG keys to cards: http://www.gnupg.org/howtos/card-howto/en/ch05.html

If you have any comments or suggestions then please let me know.

questions around the subkeys are explained here:
http://www.gnupg.org/gph/en/manual.html#AEN526

Do I understand correctly that the NEO can only have 1 keypair onboard? So there is no place for an active encryption key and a number of expired keys for the sake of reading old communication??

As I understand it the NEO can't even store one complete key pair - it only stores the private key and the public key is fetched from a keyserver when you first use the key. The NEO has 3 slots - one for encryption subkey, one for signing subkey and one for authentication subkey (eg ssh logins). So you are correct that if you lost your NEO and decided to create a new subkey for a new NEO then you would no longer be able to use the NEO for decrypting messages encrypted to the previous subkey. You would still have these older private subkeys stored elsewhere (unless they were generated on the NEO itself) so could decrypt those messages there. The only possible (but clunky, expensive and unrealistic) work around I can think of would be to buy a separate NEO for every new encryption subkey that you *might* need to decrypt messages with.

Not ideal but I'm not aware of any smartcards that can store multiple keys (I could be wrong here - if so please let me know - but I have only ever seen details of cards that can take a single private encryption subkey).

Regards,
Neal.

unfortunately it doesn't work for me.
I'm doing this on a fresh updated KALI linux on an USB stick (so I can destroy it afterwards)

the card is working:

second command is with card ejected


also looks fine

I'll dd a debian and install that to the USB drive and rerun the howto.

I suspect that the "Broadcom" bit is another smartcard reader and the applet is trying to install to a card in that reader (just a guess though). Can you disable/remove the broadcom Corp 5880 card reader or try with a different computer if it is built in? Failing that you could edit the /etc/libccid_Info.plist file discussed in my post and try to manually remove the lines related to this Broadcom device so KALI no longer recognizes it as a smartcard reader.

On a related note I've just noticed how messed up that bit in the guide is - obviously something went wrong when I converted it. I'll go fix that now...

Cheers,
Neal.

Probably not related to your current issue but I also had many problems with gpg from debian stable - which is why I upgraded to testing to get version 2.0.22 which has better support for smartcards. If you get stuck actually adding the keys to the NEO then check your GPG version as that gave me errors along the lines of "card not found" or "card not supported". If "gpg" is not actually calling version 2 of GPG then use eg: "gpg2 --card-status".

I'm already up and running with debian testing, applet is on the key now. Now only the key-gen. Will do that tomorrow with a clear head
I've noted all the commands in a .sh file which I'll post here afterwards. (commands from the start post but in workable cut'n paste format)

After walking trough it all I've decided on 2 changes.

1. give the master key a long lifetime but not 'forever' some clients/persons might whine about this because they aren't aware of the rotating yearly keys on the yubi
2. also generate a 3rd authentication key (as far as I'm aware this is a singing key in slot 3.....) just in case you decide you want to play with gpg-agent for ssh authentication (as I did 2 hours after I had my yubi ready and the master keys stored away)

Note: I've installed debian on a usb stick (full disk encryption), upgraded to testing, ran all the downloads and compiled everything.
Disconnected the internet (never to be connected again to this OS) and then generate keys. After all is done and keys are stored on a 2nd (and 3rd) usb stick I'll wipe the bootable USB key a few times.

Each year in order to re-generate additional keys I'll go trough this procedure. (when I get sick of it I might up to 2 year lifetimes)

for future reference:
http://budts.be/weblog/2012/08/ssh-auth ... ur-pgp-key
a howto on creating an authentication sub-key in expert mode.

another interesting reading for making good keypairs:
https://alexcabal.com/creating-the-perfect-gpg-keypair/

(NOTE: i hope this post stays editable, i will clean this mess up one day!)

I run in to an error at the key import stage. The keys are show correctly as in screenshots and until this point all is well:

gpg> keytocard
gpg: can't connect to the agent - trying fall back
The card does not support the import of keys


gpg> scdaemon[6631]: updating slot 0 status: 0x0000->0x0007 (0->1)


I found one other thread on here referring to this and the cure was to ensure that that pcscd was running, but in my case it definitely is (pcscd -v correctly gives the version)

Any suggestions appreciated

Dear hqarrse,

What is the serial number on your Yubikey NEO, you may have a very old version of the OpenPGP back in a time when the import was not supported yet.

_________________
-Tom

hi Tom,

it's a shiny new one (3000052)