Sequoia PGP

Related articles
Data-at-rest encryption
List of applications/Security#Encryption, signing, steganography
OpenPGP
Sequoia PGP
is a complete implementation of OpenPGP as defined by the (deprecated)
RFC 4880
and the new
RFC 9580
, and various related standards.
Sequoia consists also of several crates, providing both a low-level and a higher-level API for dealing with OpenPGP data. Moreover, Sequoia provides a
detailed implementation of its Web of Trust
which may be different (but largely compatible) from the one implemented by other tools like
GnuPG
, because OpenPGP does not specify how a web of trust implementation should work.
Installation
You should install the
sequoia-sq
package, and optionally
sequoia-sop
for the
Stateless OpenPGP
implementation of Sequoia.
Configuration
Configuration file is a TOML formatted file placed at one of the following locations:
$SEQUOIA_HOME/config.toml
if
SEQUOIA_HOME
environment variable is set;
$HOME/.config/sequoia/sq/config.toml
if
SEQUOIA_HOME
is not set or it is set to
default
.
You can query, inspect, and create the configuration file through the
sq config
subcommand. The
sq config template
command for example generates on stdout a configuration template with all the keys, which you can customize to fit your needs.
Web of Trust
In order to efficiently use Sequoia it is important to understand its trust model. In order to communicate securely with someone you need to know his OpenPGP certificate in order to both encrypt messages for him and verify his signatures. Since you can not start a secure channel without certificates, the best way to get them is to meet him in person and exchange your respective certificates. However, it is not always possible to meet someone in person. Moreover, a key/certificate may change in future (it could be leaked, lost or just as the computation power increases he needs to generate a new one with more bits in order to avoid decreasing its security). Therefore, it is important to both send and receive certificate modifications as soon as possible and to as many people as possible.
The biggest problem of sending certificates through an insecure channel to start and end-to-end encrypted channel is that a malicious actor can replace both certificate and perform a
main-in-the-middle attack
without the other parties could notice it. A possible countermeasure to this kind of attack is to associate a certificate with an
identity
(which in OpenPGP corresponds to a UserID) which no malicious actor can modify without breaking the cryptographic algorithms.
The act of binding a certificate to an UserID is called in OpenPGP a
certification
, and can be performed by either the certificate owner (in which case is called
self certification
) or a third-part actor called in Sequoia
trust introducer
. Instead, the verification performed by an end-user about a certificate-UserID binding is called
authentication
.
There are several way to organize a authentication scheme, some of them are:
Trust on First Use
(TOFU): the first time a certificate-UserID binding appears they are both printed and shown to the end user, which should decide to accept it or not. This scheme is very simple and widely adopted in several systems;
Centralized authentication
: there are a certain number of trust introducers, called
certification authorities
(CAs), which are known to everyone and everyone must fully trust their certifications. TLS/HTTPS uses this scheme with the X.509 protocol for example;
Decentralized authentication
: everyone can be a trust introducer and certify any certificate-UserID binding, however the end user is free to choose which trust introducer to trust and decide how much trust put on each introducer. Therefore, trust is no more a zero/one choice, and intermediate amounts are possible. Sequoia, GnuPG and several other OpenPGP implementations use this scheme.
In Sequoia each certification of a certificate-UserID binding also specifies the following quantities:
the
trust amount
(how much trust is put on that certification) is a number between 1 and 120 which states "how much trust" we put in this association, with 1 the least trust and 120 full trust. Usually, you can express partial trust by setting the trust amount to 60;
the
trust depth
(how far is that certification) instead can be used to certificate trust introducers: a 0 trust depth only certificate the target binding, instead a 1 trust depth in addition states that the target is also a trust introducer and can certificate other bindings with depth at most 0, a 2 trust depth additionally allows the target to issue certifications with depth at most 1, and so on.
A certificate-UserID binding is said to be (locally for an end-user)
authenticated
if and only if there is one or more valid chains of third-part certifications from your local trust authority key (which is automatically generated the first time you execute
sq
) to the target. For these chains of certifications to be valid it is needed that:
all the trust depths limitations are honored;
the
maximum flow value
of the trust amount graph is at least 120 (if there is a single path then the flow value is exactly the minimum of all the trust amounts of each certification).
Additional information about Sequoia Web of Trust can be found  in the
RFC specification
and in the
Sequoia book
.
Usage
Sequoia's command-line utility
sq
uses subcommands to separate all its functionalities and provide a more user-friendly interface. The generic invocation format is
sq
SUBCOMMAND_1
SUBCOMMAND_2
...
SUBCOMMAND_N
[OPTIONS]
, and some options are global and shared between all subcommands:
--cert-store
PATH
,
--key-store
PATH
uses the provided certifications/keys store instead of the default ones;
--cli-version
VERSION
uses the provided command-line-interface version of
sq
(which is different from the underlying Sequoia library version);
--keyring
PATH
looks up certificates also in the provided keyring without importing them in the certificate store;
--trust-root
FINGERPRINT
use the provided certificate as the "local trust root" for authentication purposes in the Web of Trust;
--quiet
/
--verbose
be more quiet or verbose respectively.
Some options in
sq
(sub)commands requires a certification identifier. We use the notation
--
opt
-*
...
to denote that option
opt
needs a certificate and must be used in one of the following forms:
--
opt
FINGERPRINT
;
--
opt
-email
EMAIL
;
--
opt
-userid
USERID
;
--
opt
-file
FILE
.
Note
When using
--
opt
-email
or
--
opt
-userid
options the corresponding certificate-UserID must be
authenticated
in order for Sequoia to associate the right certificate.
Keys and certificates
Sequoia uses the term
key
to refer private keys and in general all the private material that you should keep secret to anyone. Instead, it uses the terms
certificate
and
cert
to refer both public keys and key certificates in general.
Create a key pair
Warning
By default
sq
generates keys according to the old RFC4880 in order to maintain compatibility with GnuPG and other old OpenPGP implementations. If you do not need interoperability with RFC 4880-only tools then you are encouraged to generate keys in the newer format RFC 9580 with the option
--profile rfc9580
, for example
$ sq key generate --profile rfc9580 --own-key --name "Alice Example" --email alice@example.com
You can also set in in your configuration file:
[encrypt]
profile = "rfc9580"

[key.generate]
profile = "rfc9580"
Generate a key pair with
$ sq key generate --own-key --name "Alice Example" --email alice@example.com
The
--own-key
tells sq to promote the new key as an "unconstrained trust introducer" allowing it to be used to authenticate any certificate-UserID binding.
The default cipher suite that sq uses when generating a key is
cv25519
. To select a specific suite, use
--cipher-suite
;
the default expiration time is set to 3 years, you can change it with the
--expiration
option;
it also automatically generate a revocation certificate, which is your only way to revoke a certificate if you lose access to corresponding private material, by default it is saved at
$HOME/.local/share/sequoia/revocation-certificates
.
The command also prompts you to choose a password for securing private material, take a look at
Security#Choosing secure passwords
for tips about passwords.
Note
If you do not want to use a password then use the
--without-password
option.
Subkeys
Just like GnuPG, you can generate subkeys with SequoiaPGP. By default
sq key generates
generates the following subkeys:
a signing capable subkey, unless the
--cannot-sign
option is passed;
an authentication capable subkey, unless the
--cannot-authenticate
option is passed;
an universal encryption capable subkey, unless
--cannot-encrypt
option is passed or you explicitly set
--can-encrypt
PURPOSE
where
PURPOSE
is one the the followings:
storage
(suitable for encrypt data-at-rest);
transport
(suitable for transport encryption);
universal
(all the previous, default).
You can always add new subkeys later with
sq key subkey add
.
Change expiration date
You can change the expiration date of a certificate with the command
sq key expire --cert-*
..
--expiration
NEW_DATE
Key rotation
Rotate a key means replace an old certificate and (sub)keys with a new one with the same capabilities. Additionally, a revocation certificate for the old certificate is issued indicating that the retirement of the old certificate will occur in, by default, 182 days. This period can be changed with the
--retire-in
option.
Key rotation is performed with the
sq key rotate
command.
Revoking a certificate
Warning
Deleting a key make impossible to decrypt any encrypted message. If possible is better to just revoke a key rather than deleting it, since it only affects the public certificate but you can still use the relative private key for decrypt old data.
If you really really needs to delete a key then use
$ sq key delete --cert
FINGERPRINT
Revocation is done by creating a revocation certificate, that warns to not use this certificate anymore, and publishing it. Since an expired cert is automatically revoked, you need to issue a revocation certificate only if you want to revoke it before expiration date.
There are two kinds of revocations:
soft revocations
are issued just when you want to notice that the key has been superseded, and the private key material is still in the sole control of the owner and has not been leaked. Therefore, other people can still trust older signatures and encrypted data sent by the certificate owner.
hard revocations
notice instead a critical situation where the private material has been leaked. Other users should immediately stop use and trust the old certificate and every already checked signature and encrypted data should be audited (attackers with private keys can always backdate encryptions and signatures).
The difference between a soft and an hard revocation is given by the
--reason=
REASON
option with
REASON
one of the followings:
compromised
,
superseded
,
retired
,
unspecified
.
Note
A revocation certificate by default is generated when you generate a new key and saved in
$HOME/.local/share/sequoia/revocation-certificates
. Save it in a secure and offline location separated by your private keys since it is your only possible way to revoke them if you lose access to your keys.
To generate a new revocation certificate and store it in
FILE
use the following command:
$ sq key revoke --cert-*
...
--reason
REASON
--message
MESSAGE
--output
FILE
Warning
If you forget to add the
--output
FILE
option the generated revocation certificate is automatically imported in your store, revoking immediately your stored certificate!!
Use the following command
$ sq key revoke --cert-*
...
--reason
REASON
--message
MESSAGE
(without
--output
) only if you want to immediately revoke one of your certificates.
On the converse, you can revoke a certificate by just importing the corresponding revocation certificate just like a key:
$ sq cert import
FILE
You can make the revocation public by either publishing the already-revoked certification
$ sq network keyserver publish --cert
REVOKED_CERT_FINGERPRINT
or by publishing the revocation certification file generated by
sq key revoke --output
$ sq network keyserver publish
REVOCATION_FILE
List certificates and keys
To list certificates that matches the provided
FINGERPRINT
,
KEYID
or
PATTERN
:
$ sq cert list
[FINGERPRINT or KEYID or PATTERN]
if you don't provide an argument then all stored certificates are printed.
Tip
By default only authenticated certificates are shown by the previous command, if you want to also show unauthenticated certs then you should also provide the
--gossip
option. Moreover, the
--show-paths
shows the all the certification paths used to prove (or disprove) certificate-UserID bindings according to the
Sequoia/OpenPGP Web of Trust model
.
You can use additional filtering rules with the
--amount
,
--cert
,
--cert-domain
,
--cert-email
,
--cert-grep
,
--cert-userid
options.
To list (private) keys use instead:
$ sq key list
[FINGERPRINT or KEYID or PATTERN]
Export and import certificates
You can export multiple certificates on stdout (or a designated file is you provide the
--output
FILE
option) with the command
$ sq cert export $QUERY
where
$QUERY
filter exported certificate(s) and can consist of:
--cert FPR
for only the certificate designated by its fingerprint
FPR
;
--cert-userid USERID
for all certificates containing a user id;
--cert-email EMAIL
for user id matching
EMAIL
;
--cert-domain DOMAIN
for user id with an email address from domain
DOAMIN
;
--cert-grep PATTERN
for user id matching a pattern (case insensitive).
Note
UserIDs in OpenPGP follows this syntax:
Name
<
email address
>
.
To import certificates from a file use instead the following command:
$ sq cert import FILE
By default Sequoia does not authenticate certificate-UserID bindings on imported certificates unless it founds a valid certification path from the "local trust authority" to the imported certificates with a trust amount of at least 120.
Certification and authentication
You can issue local-only binding certification (with your local trust authority) by either using
sq pki link add
(which only allows you to set the trust amount) or
sq pki link authorize
(which in addition sets the trust depth). Instead, if you want to export your binding certification then you should instead use
sq pki vouch add
or
sq pki vouch authorize
and provide a certificator with the
--certifier
option.
Third-part local certifications of bindings can be revoked with the
sq pki link retract
command.
Warning
It is not possible to retract a certification issued with
sq pki vouch
.
Note
Spammer can issue a large number of bogus third-part certification on a target certificate and floods the keyserver to make the certificate unusable. In order to avoid malicious actor to add an enormous number of third-part certifications some keyholders needs to "approve" third-part certifications by signing them with their private key. You can approve a third-part certification with the following command:
$ sq key approvals update --cert
FINGERPRINT
CERTIFICATORS_QUERY
Additional information can be found on manpages of
sq-key-approvals
,
sq-key-approvals-update
and
sq-key-approvals-list
You can test if a binding is authenticated through the
sq pki authenticate
command.
Certification replaying
After rotating one or more keys with
sq key rotate
, you would like to (re)create all the certifications made by the old key using the new one. This operation to take all certifications made by
A
and re-certify them with
B
is called
certification replay
and can be done with the following command(s):
$ sq pki vouch replay --source-*
A
--target-*
B
Keyservers
Sending keys
You can register your key with a public PGP key server with the command
$ sq network keyserver publish --cert FINGERPRINT
Receiving keys
To import certificates from a keyserver use:
$ sq network keyserver search
FINGERPRING or EMAIL
Tip
Sequoia keeps track of the origin of keys imported through a keyserver through a local server-specific key.  That proxy certificate is in turn certified with a minimal trusted CA (1 of 120). How much a proxy key server CA is trusted can be tuned using
sq pki link add
or
sq pki link retract
.
Web Key Directory (WKD)
Web Key Directory (WKD) is a way of distributing certificates through domain names and webservers.
Sequoia can create the required directory structure with the command
$ sq network wkd publish --create --domain
DOMAIN.NAME
/webserver/root
Once the WKD file directory is created you can publish your certificates with the command
$ sq network wkd publish --cert-*
...
--domain
DOMAIN.NAME
/webserver/root
You can also publish all stored fully authenticated certificates with UserID matching
DOMAIN.NAME
with the command
$ sq network wkd publish --all --domain
DOMAIN.NAME
/webserver/root
Tip
You can use
rsync
program with both the previous commands with the
--rsync
option. With this option, you can use any valid
rsync
destination in place of
/webserver/root
, even remote ones.
Certificates via DNSSEC (DANE)
Sequoia support publishing certificates through DNSSEC according to the
DANE specification
.
The following command generate a
TXT
record you should put in yous DNS configuration:
$ sq network dane generate --cert-*
...
--domain
DOMAIN.NAME
You can also use the
--all
option as in the previous section.
Tip
You can use the
--size-limit
bytes
to give Sequoia an hint about the record's size.
Encrypt and decrypt
Subcommands
sq encrypt
and
sq decrypt
can be used to encrypt and decrypt data respectively. The encrypted output is automatically ASCII-armored (unless you use the
--binary
option) and both commands print the result to stdout (unless you specify a destination file with
--output
)
Note
By default
sq encrypt
also signs encrypted messages. You can use the
--signer-*
options to specify the key used to sign, or
--without-signature
if you do not want to add a signature.
When decrypting with
sq decrypt
Sequoia will automatically check the signature with only
authenticated
stored certificate and prints a warning if it was not able to verify the signature. If you pass any
--signer-*
option to
sq decrypt
then only the provided signatures are checked.
Symmetric ciphers and passwords
The
--with-password
option can be used to prompt a password, which is used to securely generate a symmetric cypher key which is then used to encrypt/decrypt the passed file. To encrypt:
$ sq encrypt --profile
PROFILE
--with-password
FILE
where
PROFILE
is either
rfc4880
(older but compatible with every OpenPGP implementation) or
rfc9580
(newer but only compatible with newest OpenPGP implementations).
To decrypt:
$ sq decrypt
FILE
which automatically detect if the file has been encrypted with a password and asks you to provide it if needed.
you can also use
--with-password-file
PWD_FILE
instead of
--with-password
to use an entire file instead a password to generate a file
Warning
The
--with-password-file
uses the entire file content to generate a password, including leading and trailing whitespaces, newlines and other non-printable characters. Be sure to use the same exact file when decrypting it.
Asymmetric ciphers
You can encrypt a file with an asymmetric key in the following way:
$ sq encrypt --for-*
...
FILE
Note
when using
--for-email
or
--for-userid
Sequoia automatically checks if the target certificate-UserID binding is authenticated, and refuse to proceed if they are not.
You can use
sq decrypt
to decrypt just like asymmetric encrypted files.
Signatures
Sign a file
To sign a file you can use the
sq sign [--message
or
--signature-file
SIGFILE
]
command with any
--signer-*
option to sign a file. Use
--signature-file
SIGFILE
instead of
--message
to create a detached signature instead of an in-lined one.
Verify a signature
A signature can be verified with
sq verify [--message
or
--signature-file
SIGFILE
]
FILE
. By default any stored authenticated certificate is used to verify a signature, but you can use
--signer-*
options to restrict verification to the selected certificates.
You can add the
--signatures
N
to require at least
N
valid signatures to consider the file verified.
Inspect OpenPGP packages
May happen that you want to inspect OpenPGP data stored in a file for debugging reasons. The
sq inspect
subcommand prints a human-readable description of an OpenPGP file:
$ sq inspect
[OPTIONS]
FILE
If you want to get a description of each OpenPGP packet stored in an OpenPGP file then use
$ sq packet dump
[OPTIONS]
FILE
Look at the manpages of
sq-inspect
and
sq-packet-dump
for a comprehensive list of options.
Tips and tricks
Troubleshooting
See also
Sequoia PGP webpage
;
Sequoia book
;
Sequoia proposal to implement decentralized Git access control with OpenPGP
;
Sequoia's drop-in replacement for GnuPG
.