#openpgp #pgp #encryption #signing

app sequoia-chameleon-gnupg

Sequoia's reimplementation of the GnuPG interface

9 unstable releases (4 breaking)

new 0.5.1 Feb 21, 2024
0.5.0 Feb 20, 2024
0.4.0 Dec 22, 2023
0.3.2 Jul 25, 2023
0.1.1 Dec 22, 2022

#1 in #reimplementation

Download history 6/week @ 2023-10-31 1/week @ 2023-11-07 4/week @ 2023-11-14 14/week @ 2023-11-21 26/week @ 2023-11-28 6/week @ 2023-12-05 6/week @ 2023-12-12 29/week @ 2023-12-19 27/week @ 2023-12-26 16/week @ 2024-01-02 3/week @ 2024-01-09 1/week @ 2024-01-16 2/week @ 2024-01-23 19/week @ 2024-01-30 1/week @ 2024-02-06 57/week @ 2024-02-13

79 downloads per month


18K SLoC

Rust 16K SLoC // 0.1% comments Bitbake 2K SLoC // 0.0% comments

Sequoia's reimplementation of the GnuPG interface

This is a re-implementation and drop-in replacement of gpg and gpgv using the Sequoia OpenPGP implementation.


gpgv-sq is feature-complete. Please report any problems you encounter when replacing gpgv with gpgv-sq.

gpg-sq is not feature-complete. It currently implements a commonly used subset of the signature creation and verification commands, the encryption and decryption commands, the key listing commands, and some miscellaneous commands.

Support for trust models is limited. Currently, the Web-of-Trust ("pgp") and always trust ("always") are implemented.

Try it out, it is safe!

If you are a power user, you can try out the Chameleon today to see if it covers your use cases. The Chameleon does not directly modify any of GnuPG's data structures, so it is safe to try it out with your existing GnuPG installation and keys.

There are two ways the Chameleon will change your $GNUPGHOME:

  • It will create an openpgp-cert-d overlay in $GNUPGHOME/pubring.cert.d. GnuPG will ignore this.

  • If you create or import secret keys, the Chameleon will interact with gpg-agent the same way GnuPG would, and gpg-agent will in turn modify $GNUPGHOME.

A consequence of not modifying GnuPG's state but using an overlay is that changes made using the Chameleon will not be picked up by GnuPG. For example, if you import a certificate using the Chameleon, it will only be inserted into the overlay, and GnuPG will not see it. If you are using the Chameleon and GnuPG side-by-side, it is recommended to either do state changing actions using GnuPG, or explicitly export changes from the Chameleon and import them into GnuPG, by either manually running the following or adding it to a cronjob:

$ gpg-sq --export | gpg --import

How to build and use the Chameleon

First, you need to install Sequoia's build dependencies. Then build the Chameleon from a checkout of this repository:

$ git clone https://gitlab.com/sequoia-pgp/sequoia-chameleon-gnupg.git
$ cd sequoia-chameleon-gnupg
$ cargo build --release

Alternatively, you can change the cryptographic library that is used. Note that this will change the build dependencies. Currently, crypto-openssl and crypto-cng are supported, which select OpenSSL and Windows CNG, respectively. To select a different backend, disable the default features and activate the corresponding feature:

$ git clone https://gitlab.com/sequoia-pgp/sequoia-chameleon-gnupg.git
$ cd sequoia-chameleon-gnupg
$ cargo build --release --no-default-features --features=crypto-openssl

To use the Chameleon, you need to make sure that it is invoked either directly by you or indirectly by programs instead of GnuPG. One way to do that is to put it under the name gpg into your path, but we also need to make sure that gpgconf points to the Chameleon, because many programs invoke gpgconf to find the location of gpg. To that end, we have a shim that can be used from the build directory (if you want to install the Chameleon, or your cargo target directory is different, you need to adapt it accordingly):

$ export PATH=$(pwd)/shim-release:$PATH
$ gpg --version | head -n1
gpg (GnuPG-compatible Sequoia Chameleon) 2.2.39
$ gpgconf | head -n1

How to trace invocations of the Chameleon

If you have a program that uses GnuPG, and you want to see whether it works with the Chameleon, a good way to do that is to run the test suite (or if there is none, just use the program as usual) with a debug build of the Chameleon, and enable the invocation log. The log will log every invocation of the Chameleon with all the arguments given, and whether an error occurred or not.

$ cargo build
$ export PATH=$(pwd)/shim-debug:$PATH
$ # WARNING: this only works with a debug build!
$ export SEQUOIA_GPG_CHAMELEON_LOG_INVOCATIONS=/tmp/invocation.log
$ # Run your test suite here.  This is an example:
$ (gpg --version ; gpg --lsign-key) >/dev/null 2>&1
814360: "gpg" "--version"
814360: success
814359: "gpg" "--lsign-key"
814359:            Command aLSignKey is not implemented.

Non-Functional Advantages

The Chameleon has a number of non-functional advantages relative to GnuPG.

Automatic discovery of certificate updates

The Chameleon includes a component called Parcimonie (after the venerable Parcimonie) that will keep your certificates up-to-date, trying to do so in a privacy preserving fashion.

It will periodically use any enabled auto-key-locate methods to search for updates in the local certificate store using randomized delays trying to de-correlate them. It will use Tor if available.

To enable the Parcimonie component, run gpg-sq --x-sequoia-parcimonie, either manually or using a service manager (a systemd unit file with the name gpg-sq-parcimonie.service is included in this repository). Alternatively, you can use the x-sequoia-autostart-parcimonie option in your configuration file to start it on-demand if gpg-sq is invoked.

OpenPGP Conformance

Sequoia implements nearly all of the OpenPGP RFC4880. The missing bits are either obsolete or insecure. Furthermore, we engage with the IETF OpenPGP working group, and wrote an extensive OpenPGP Interoperability Test Suite to improve interoperability between various implementations. In short, if you use Sequoia to encrypt your data, you can be sure that you can decrypt it with any other OpenPGP implementation.

No more waiting for Trust Database checks

The Chameleon uses a very fast implementation of the Web-of-Trust, and we calculate the trust on the fly without relying on a cache like GnuPG. That means that gpg --check-trustdb is a no-operation for the Chameleon, whereas GnuPG is known to take a long time.

SHA-1 Mitigations

SHA-1 is broken. Unfortunately, SHA-1 is still widely used. To deal with this Sequoia implements a number of countermeasures:

  • Sequoia uses SHA1-CD, a variant of SHA-1 that detects and mitigates collision attacks. This protection is also used by GitHub, among others.

  • Sequoia rejects all signatures using SHA-1 by default.

On the other hand, GnuPG accepts SHA-1 everywhere without any additional protections.

Collision Protection

Sequoia includes a salt in signatures and self-signatures to defend against collision attacks, among others. OpenSSH does the same thing. Should the collision resistance of another hash be broken, this will frustrate attackers trying to perform a Shambles-style attack.


Thanks to Rust's safer concurrency paradigms, it is less dangerous and less complicated for the Chameleon to use threads than implementations written in other languages. The Chameleon uses this, for instance, to parse keyrings faster.

Testing methodology

There are two ways we test the Chameleon: we run the Chameleon and GnuPG side-by-side and compare the results, and we use test suites of programs that use GnuPG.

Using GnuPG as Test Oracle

We run experiments that invoke the Chameleon and record human-readable and machine-readable output and side-effects, and compare that to what GnuPG emits. These tests are run when you invoke cargo test, and hence need GnuPG to be installed.

Downstream Test Suites

We use test suites of programs that directly or indirectly use GnuPG to verify that we support the required functionality.

A reoccurring problem when running these test suites is that they may include cryptographic artifacts such as OpenPGP certificates, keys, signatures, and messages. Those are rarely updated, and hence are stuck in time using old packet formats or insecure algorithms.

If you are maintaining a software package that includes cryptographic artifacts in the test suite, please help by regularly updating the artifacts. Further, try to reduce the amount of checked-in artifacts in the first place. Where possible, try to generate the required artifacts in the test.

Bugs discovered in the process


Sequoia GnuPG Chameleon is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See LICENSE.txt.

Sequoia GnuPG Chameleon is a derived work of GnuPG. It is not a clean-room reimplementation, and it does include parts of GnuPG either literally, or transcribed to Rust. Therefore, parties who claim copyright to GnuPG also have a claim on parts of the Chameleon. See AUTHORS.GnuPG for a list.


~1M SLoC