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 used to sign or decrypt data, usually after supplying some kind of authentication (like a PIN). That way, secret key material can be used without disclosing it.

Sequoia PGP (and therefore sq) uses key and cert stores to manage their respective 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.

If you point the environment variable SEQUOIA_HOME to a location other than default, gpg-agent support is disabled.

Overview

For the whole picture—aside from sq, gpg-agent and the hardware token—there are two further relevant components: scdaemon and pcscd. Both components implement 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 every software stack other than GnuPG.

If scdaemon and pcscd are used simultaneously, there has to be 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 service is used by gpg-agent to ask for 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 exclusivity 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

If 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.