The FSFE Fellowship Card is an OpenPGP smartcard to hold GnuPG signature, encryption, and authentication keys. The fundamental idea of OpenPGP smartcards is to store your key material securely on the card, where all cryptographic operations are executed, maybe after entering the card’s PIN. Thus, secret keys never leave the card. [Note that without smartcards (along the “normal” way) keys are stored on disk and protected via passphrases; thus, a Trojan with keylogger will be able to steal everything, secret key and passphrase, leaving you without protection.]

Big Picture

Initially, the process of smartcard setup and usage appeared rather foggy to me; however, it’s actually quite easy to lift that fog. In the following, I’m trying to explain what I learned. I assume that you are familiar with public key cryptography and GnuPG and describe the big picture in high-level terms first. Afterwards, I point to more specific details concerning smartcard setup and use as well as some error messages.

Key Generation

First, generate a new master key. This master key will only be used to sign other keys (including the subkeys that you create subsequently during the setup process), and it will not be stored on the smartcard but in a secure place (preferably offline, e.g., on a USB stick in a vault). For daily use, generate further subkeys, at least one signature key (to sign files and messages, not keys—that is the purpose of the master key) and one encryption key, optionally also an authentication key. Then, make a backup of your public and secret keyrings containing the newly generated keys and store that backup in a secure place.

Key Transfer

Afterwards, transfer the newly generated subkeys to the smartcard. Importantly, after such a transfer the keyring does not contain the secret key any longer; instead, in the keyring the secret key is replaced with a so-called stub. Such a stub is not a real key but only a pointer to the key stored on the smartcard. To finish the initial setup, remove the (secret part of the) master key from your keyring. Now, the master secret key exists only as backup in a secure place, while the secret parts of the subkeys are available for daily use on the smartcard and exist as backup (together with the master key); importantly, none of the secret keys is stored in the keyring on disk any longer.

Smartcard Use

The final piece of the puzzle is how to use the smartcard on different machines. Of course, the keyring on a different machine needs to know what keys are contained on the smartcard. Towards that end, you may first import the master key’s public key (e.g., from a USB stick); afterwards, execute gpg --card-status or gpg --card-edit with inserted smartcard, which—somewhat surprisingly—constructs the stubs for the secret subkeys in the keyring. Alternatively, on a networked machine you may execute gpg --card-edit followed by the command fetch, which downloads the public key from the “URL of public key” stored on the smartcard and updates the keyring accordingly.

Confusing Terms

Next, in various sources you may read about gpg-agent, scdaemon, and udev; maybe also about pcscd, hotplug, and gpgkey2ssh; probably also about gpg and gpg2. Let’s consider those things in turn. gpg-agent manages keys and caches passphrases and PINs. It is started automatically, either by gpg if necessary or when your GUI is initialized, and there is no reason to start it manually. If you choose to transfer an authentication key to your smartcard, gpg-agent replaces ssh-agent and should be started with your GUI (see below). gpgkey2ssh is a tool of historical interest. scdaemon manages your smartcard and is started automatically by gpg-agent; again, you do not start it manually. pcscd also manages smartcards; I do not need it—in fact, it was installed on one of my systems and caused major problems (see below). udev and hotplug are mechanisms to manage all kinds of devices; essentially, udev has replaced hotplug; it may need manual configuration to work with your smartcard (which was not the case for me, neither on a fresh Ubuntu 12.04.2 LTS nor on “aged” Ubuntu 10.04.4 LTS). Finally, gpg represents GnuPG version 1.x while gpg2 stands for GnuPG version 2.x, both of which are actively maintained; they may even be installed in parallel. gpg2 has better smartcard support and uses scdaemon to talk with the smartcard; in contrast gpg has built-in smartcard support so that scdaemon may not be necessary, but it works with scdaemon as well. However, if you want to enter your PIN with the PIN pad of the card reader (instead of your keyboard where a keylogger may be listening) you probably need scdaemon, even with gpg.

In short, make sure that scdaemon and gpg-agent are installed and forget about all the rest. If you compile gpg2 from source, gpg-agent and scdaemon are included; otherwise, on Ubuntu you may find gpg-agent in its own package and scdaemon—quite surprisingly—in the package gpgsm.

Card Setup

The details of the card setup process are described in this HowTo.

Here is what I suggest to follow that HowTo. First, use a fresh system to generate the master key (for example, Ubuntu 12.04.2 LTS), as a fresh system is far less likely to be compromised than one which has been in use for a while. (Actually, I used c’t Bankix, a German project for secure online banking, instead of Ubuntu 12.04.2 LTS.)

Note that I must warn you against Ubuntu 12.10 and 13.04 beta. Do not use them!

You only need to burn/install the ISO image to a CD or USB stick (booting from CD may be preferable as that is a read-only medium, although it is slower).

Be sure to verify the checksum of the ISO image!

Then you can immediately boot from that medium to test Ubuntu without installing it to your hard disk, in fact without modifying your hard disk. Before booting, disconnect your computer from the net, maybe disable wireless networking via suitable hotkeys. Once the boot process is completed, you find yourself in a fully functional Ubuntu system that is suitable to generate GnuPG keys and transfer them to the smartcard. Connect your smartcard reader and insert the smartcard. gpg is installed and udev configured correctly. Thus, the following command shows the contents of your card.

$ gpg --card-status

Note that neither gpg-agent nor scdaemon are installed. Thus, smartcard PINs need to be entered on the keyboard. This should not be a problem as (a) you disconnected the machine from the net and (b) nothing is stored on disk. (Be careful with a USB stick, though. Maybe format it in the end.)

However, the system is not ready to follow the HowTo yet. After creation of the master key (gpg --gen-key), access to the card via (gpg --card-status) fails, as the Gnome keyring daemon interferes:

gpg: selecting openpgp failed: unknown command
gpg: OpenPGP card not available: general error

Thus, kill gnome-keyring-daemon:

$ pkill -f gnome-keyring-daemon

Now, gpg --card-status should work again.

Follow the HowTo. When it instructs you to use a search engine for authentication keys, use gpg --edit-key again and type the command addcardkey. Choose “authentication key” when asked what type of key you want. Continue to follow the HowTo.

Afterwards, your new master key and new subkeys are stored on the smartcard, the secret keys are stored in a secret place (except for the authentication key, which was generated directly on the smartcard), and your public key is exported to a file.

System Setup for Card Usage

To get rid of the Gnome keyring problem mentioned above, go to directory /etc/xdg/autostart and delete (or rename) the files gnome-keyring-ssh.desktop and gnome-keyring-gpg.desktop.

Next, make sure that scdaemon and gpg-agent are installed. As noted above, either compile gpg2 from source or install the appropriate packages (gpgsm and gpg-agent). Set up ~/.gnupg/gpg-agent.conf for ssh support, maybe also increase the duration for which PINs will be cached, e.g.:

enable-ssh-support

# Cache for 6h = 6*60*60 seconds, instead of the default of 10 minutes.
# Upon access, default-cache-ttl re-starts.
default-cache-ttl 21600
default-cache-ttl-ssh 21600

# Enter passphrases for keys that are not stored on smartcard:
pinentry-program /usr/bin/pinentry-gtk-2

Then, configure your system not to start ssh-agent any more, but to start gpg-agent upon login instead. The necessary steps are system-specific. For Ubuntu (12.04.2, also 10.04), check the files under directory /etc/X11/Xsession.d. You should see the file 90gpg-agent, where you may need to adjust the path for GPGAGENT if you compiled from source; you also see that you need to include configuration option use-agent in your gpg.conf. Moreover, you should see the file 90x11-common_ssh-agent, which makes use of option use-ssh-agent, which in turn can be removed from the file /etc/X11/Xsession.options. Apply necessary changes and log off and on again.

Finally, add your public authentication key to the file ~/.ssh/authorized_keys on all machines into which you want to ssh by just entering the smartcard’s PIN. The command

$ ssh-add -L

should show all known keys for ssh authentication, including those on the smartcard, which can be recognized by the identifier cardno:<your-card-number>. Append that key (as usual) to ~/.ssh/authorized_keys. (Don’t use gpgkey2ssh.) If you don’t see such a key, make sure that you followed the advice concerning gnome-keyring-ssh.desktop above.

That’s it. Enjoy your smartcard.

Strange Errors

On one of my machines, gpg2 --card-status showed errors like this:

gpg: selecting openpgp failed: Kartenfehler
gpg: OpenPGP Karte ist nicht vorhanden: Kartenfehler

Upon repeated attempts:

gpg: OpenPGP Karte ist nicht vorhanden: Nicht unterstützt

The English messages are:

gpg: selecting openpgp failed: Card error
gpg: OpenPGP card not available: Card error
gpg: OpenPGP card not available: Not supported

Moreover, debug messages for scdaemon (enabled via ~/.gnupg/scdaemon.conf) showed this:

scdaemon[7615] PC/SC OPEN failed: comm error

Ultimately, pcscd was running as root (started from /etc/init.d/pcscd) and interfered with scdaemon. I killed that process and disabled it:

$ sudo update-rc.d -f pcscd remove

Everything was good.