A look at the Sequoia command-line interface

The Sequoia OpenPGP library has been in development for some time. LWN covered the library in 2020. Now the project's command-line interface has been released. The sq tool offers a promising alternative to the venerable GNU Privacy Guard (GPG) tool — albeit one with a different interface, set of terminology, and approach to the web of trust. Several distributions are making increasing use of the tool behind the scenes.

The Sequoia documentation opens with a warning that the tool uses different terminology than existing OpenPGP implementations. This warning is deserved: what other tools call "public keys", Sequoia calls "certificates". It refers to private keys as merely "keys". The documentation justifies the difference by observing that what OpenPGP and related implementations call a "public key" really bundles a lot of unrelated data: user IDs, metadata, preferences, certifications, signatures, and subkeys, as well as the actual key material itself. Sequoia calls OpenPGP public keys "certificates" in order to emphasize that they are really more than just keys.

Despite those differences, Sequoia's basic operations with keys and certificates are fairly straightforward:

    # Import an existing (private) key
    sq key import $KEYFILE
    # Import a (public) certificate
    sq cert import $FILE

The design of Sequoia's command-line interface takes a different approach from that of GPG, which is designed with interactive use in mind, and will prompt the user with different options when appropriate. Instead, Sequoia automatically uses default values as much as possible. Configuring any operations is done with additional command-line flags — thankfully, the tool ships with comprehensive command-line completion support, so it is fairly easy to see what options are available. For example:

    sq key generate --own-key --name 'Test Key'

That command generates a key with the default configuration. The only value the tool prompts for is the key's passphrase. Any other configuration, such as changing the kind of key generated, needs to be specified on the command line.

The default configuration is fairly sensible: it creates a 256-bit EdDSA primary key with an expiration date three years in the future, plus separate subkeys for signing, authentication, and encryption. The signing and authentication subkeys also use EdDSA, but the encryption subkey is a 256-bit ECDH key instead. The cipher suite, expiration time, user ID, email, and so on can all be set with appropriate command-line flags. Sequoia offers fewer cipher suites than GPG does, however: RSA in 2K, 3K, and 4K variants, plus Curve25519 elliptic keys.

One nice touch is that when Sequoia generates a key, it also automatically generates a revocation certificate for it, stored under ~/.local/share/sequoia/revocation-certificates. If the key is later compromised, the user can quickly publish that pre-prepared revocation certificate. Sequoia's interface was clearly designed with that kind of convenience in mind; after running a command, the tool will suggest relevant follow-up commands, which makes it easy to go through common workflows even for users who do not use the tool regularly.

One area of the interface is somewhat unavoidably complex, however: the commands that deal with the web of trust. In its interface Sequoia tries to emphasize the difference between information that can be cryptographically verified and information that has merely been asserted by a human. For example, this is the output from attempting to verify a valid signature on a file, where the signature was made by a certificate that the user has not told Sequoia to trust:

Sequoia calls signatures that are cryptographically valid, but not necessarily from the right person, "unauthenticated". As the command suggests, when the user has determined that a particular certificate does belong to the person that it claims, they can mark the certificate as authenticated with "sq pki link add". The Sequoia documentation is clear that the tool cannot tell the user when a certificate should be authenticated, saying: "Authenticity can only be established by humans."

By default, the tool doesn't mark any certificates as authenticated except those created with the --own-key flag, because, presumably, the user trusts themselves to be who they say they are.

Marking every individual certificate as authenticated would be tedious, however, which is where the web of trust comes in. Once a user has marked a certificate as authenticated, they can then go on to "certify" that certificate — publishing their authentication for other users to rely on. To do this, the user runs "sq pki vouch certify" which generates an exportable signature attesting that the certificate belongs to the person it claims to. Then this signature can be published to a network keyserver with "sq network keyserver publish".

Other users can rely on these attestations by marking a particular key as a "trusted introducer"; using the "sq pki link authorize" command, the user can say that vouches from a particular key should be believed. Like in GPG, this trust can be applied transitively, up to a configurable depth and with configurable weights for each key. Unlike GPG, Sequoia also supports restricting which keys a trusted introducer is allowed to vouch for according to a regular expression. So, for example, if the user trusts someone to identify their coworkers but not to identify arbitrary people, they could restrict that person's key to only vouch for other keys with a matching email domain.

Before being able to authenticate a certificate by hand or through the web of trust, however, one must first obtain a copy of it. Many certificates are distributed via OpenPGP keyservers, Web Key Directories (WKD), or DNS-Based Authentication of Named Entities (DANE); Sequoia has a command ("sq network search") that will try to retrieve a certificate from all of these sources in parallel. At the same time, it also fetches any published attestations to potentially authenticate the certificate with.

Compatibility

Sequoia has been usable as a library for a while, even if the command-line interface has only recently been made ready. In fact, it is already used as the internal OpenPGP implementation for both RPM and DNF, Fedora's package managers and may soon be used in Debian-based distributions by APT. The Fedora project said that the change was motivated by "improved security and standards-compliance". But many programs don't use a PGP library, and instead use GPG as a command-line tool. For example, Git can call out to GPG or SSH in order to make and verify signatures.

This makes the prospect of porting software away from GPG daunting. So Sequoia also provides an implementation of GPG's command line (called the "GPG Chameleon"), which is intended to be a mostly drop-in replacement. There are a few known differences, such as specifically rejecting some weak algorithms that GPG allows, and a lack of translations or localizations (beyond date and time). By and large, these should not be an obstacle for scripts interacting with GPG's command-line interface.

The other main functional difference with Sequoia's reimplementation is that it stores any modified information in an overlay (a separate directory under ~/.gnupg) that is invisible to GnuPG (and uses Sequoia's database internally). On the one hand, this makes moving from Sequoia back to GnuPG somewhat tedious, because any changes need to be translated over. On the other hand, this makes it safe to try the Chameleon without worrying about accidentally breaking an existing GPG installation. Plus, a user can use the native sq front end, while still relying on programs that invoke gpg.

Overall, Sequoia presents a usable alternative to GPG. The first 1.0 release of a project is sometimes a bit rough, but in Sequoia's case that does not appear to be the case. The tool supports all of the basic operations of an OpenPGP implementation, integrates well with existing software, and has a discoverable interface that makes it easy to come up to speed in a short time. It definitely does not support everything that GPG does, but support for additional cryptographic algorithms seems likely to come in time.