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.]
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.
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.
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.
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.
Next, in various sources you may read about
udev; maybe also about
gpgkey2ssh; probably also about
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,
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).
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
In short, make sure that
gpg-agent are installed and forget about all the rest. If you compile
gpg2 from source,
scdaemon are included; otherwise, on Ubuntu you may find
gpg-agent in its own package and
scdaemon—quite surprisingly—in the package
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
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
$ pkill -f gnome-keyring-daemon
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
Next, make sure that
gpg-agent are installed. As noted above, either compile
gpg2 from source or install the appropriate packages (
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
That’s it. Enjoy your smartcard.
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 PC/SC OPEN failed: comm error
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.