Hardware keys/ Smart cards

Hardware keys or smart cards are small computers. They come as USB sticks, in credit card format or as a SIM card (and probably other form factors). Their main purpose is to protect secret key material. Secret key material can be written to and stored on these devices, but never read. Instead, these devices can be requested to sign or decrypt data, usually after supplying some kind of authentication (like a PIN). That way secret key material can be used without disclosure.

Sequoia PGP (and therefore sq) uses key- and cert stores to manage the respected objects. These stores delegate requests to backends, one of these backends is gpg-agent. As long as gpg-agent can use your openpgp hardware token, sq can do so as well.

Please note that if you point the environment variable SEQUOIA_HOME to a different location than default, gpg-agent support is disabled.

Overview

For the whole picture - besides sq, gpg-agent and the hardware token - there are two further components relevant: scdaemon and pcscd. Both components implement the access to the hardware token.

scdaemon is part of the GnuPG ecosystem and gpg-agent is hardwired to use it. pcscd is a more generic solution and is used by practically any other software stack than GnuPG.

If scdaemon and pcscd are used simultaneously, there has to be a coordination between them, as they access the same shared hardware resource. For that, scdaemon has to be configured to use pcscd for hardware access, instead of connecting to it directly. The picture looks like this:

sq <-> gpg-agent <-> scdaemon <-> pcscd <-> hardware
         ^
         |
         v
       pin-entry

The pin-entry is used by gpg-agent to get a passphrase or PIN from the user.

This construction is brittle, as scdaemon expects exclusive control of the hardware. With pcscd in the middle, this exclusiveness is not given and any intervening access endangers scdaemons expectations of the state of a connection.

You can disable pcscd and let scdaemon talk directly to the hardware, but then you might lose access to additional capabilities the hardware might offer (like two-factor authentication).

Configuration

To configure scdaemon to use pcscd for hardware access, make sure that the following two lines are in ~/.gnupg/scdaemon.conf:

disable-ccid
pcsc-shared

In case you want to have scdaemon talk directly to the hardware, disable pcscd and make sure that the two lines above are removed (or commented out).