Sequoia PGP

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 certificate any certificate-UserID bingind, 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 uses this scheme.

In Sequoia each certification of a certificate-UserID binding also specifies the following quantities:

the trust amout (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 approce 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 recertify them with B is called certification replay and can be done with the following command(s):

$ sq pki vouch replay --source-* A --target-* B

Kerservers

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

ou can also use --with-password-file PSW_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 inlined 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.