Configuration

The behavior of sq is configurable using configuration files. There are two separate sources of configuration values: the configuration for the cryptographic policy, and the configuration for sq. The configuration for the cryptographic policy is used by the underlying Sequoia PGP and thus determines the behavior of sq concerning cipher algorithms, hashes and the like (for details see below).

The sq configuration file is in TOML format, and sets the selection of default keyservers, default expiration times for newly generated keys, default ciphers, etc. This configuration takes priority, and thus allows overriding settings from the cryptographic policy.

The cryptographic policy configuration is located in /etc/crypto-policies/back-ends/sequoia.config. The configuration for sq in ~/.config/sequoia/sq/config.toml.

Accessing configuration settings

sq has a subcommand config to access configuration settings.

$ sq config get

Will read out the complete configuration of sq, or specify a key to selectively retrieve the corresponding value:

$ sq config get key.generate.cipher-suite
key.generate.cipher-suite = "cv25519"

If you are interested in more than the plain value, and want some information on what a specific setting is used for, you can use sq config inspect.

  • $ sq config inspect paths

This gives you paths to the different files or directories sq uses: key and cert store, as well as configuration files.

  • $ sq config inspect network

    Tells you which services sq will use if it's performing a network search.

  • $ sq config inspect policy

    Gives hints about the currently active cryptographic policy.

To create a new config file as a starting point for your setup, you can generate one based on your current settings using

$ sq config template

The generated configuration will be printed to STDOUT or into a file if you specify --output $FILE or redirect the output. Move this output to ~/.config/sequoia/sq/config.toml, so that sq can pick it up. This configuration also allows you to modify settings inherited from the cryptographic policy.

Cryptographic policy configuration

Sequoia PGP has a standard policy that defines which algorithms (ciphers, hash functions, etc.) are valid and available. This policy can be adjusted to cater for specific needs.

The adjustments are configured in a file (command line switches are not available), located by default in /etc/crypto-policies/back-ends/sequoia.config. This location can be changed by setting the environment variable SEQUOIA_CRYPTO_POLICY. A missing configuration file simply means "no adjustments" and the default policy applies.

These are global adjustments, effective for every user on the system. Per-user adjustments can be made in each user's respective configuration file.

Sequoia PGP comes with a sensible default cryptographic policy. There is no safety net when you modify its settings! You could introduce unsafe behavior or stop Sequoia PGP from working at all.

Format

The configuration file uses the TOML format, consisting of the following sections:

  • hash_algorithms
  • asymmetric_algorithms
  • symmetric_algorithms
  • aead_algorithms
  • packets

Missing or empty sections again mean "no adjustments".

A simple adjustment might look like this:

[hash_algorithms]
sha1 = "never"

This advises Sequoia PGP to never use or accept SHA-1 hashes. Signatures based on SHA-1 would be considered "invalid". Since signatures play a central role, this might also invalidate some certificates and keys.

Besides never and always, adjustments can have a date value. This specifies a cutoff time after which the adjustment would switch from always to never:

[hash_algorithms]
sha1 = 2010-01-01

The format of the configuration file allows using keys which are not (yet) defined. This way adjustment can be made for algorithms which will be included in the foreseeable future. To avoid parsing errors, these future keys have to be declared by using ignore_invalid.

This example configures the nonexisting hash function "SHA-4" as "always valid" while declaring it as a future key, so that versions of Sequoia PGP which do not know about SHA-4 can still parse the configuration:

[hash_algorithms]
sha4 = "always"
ignore_invalid = ["sha4"]

Please note that ignore_invalid has no influence on the crypto policy itself; it's only meant to support the parser.

If, for some reason, only a fixed set of algorithms should be considered valid, there is a way to prevent algorithms introduced by upgrades to the software to take effect. The "catch all" key is default_disposition. The following example allows SHA256 and forbids everything else:

[hash_algorithms]
sha256 = "always"
default_disposition = "never"

Hash algorithms have properties which can be configured individually. second_preimage_resistance and collision_resistance address attacks on hash functions:

[hash_algorithms]
sha1.second_preimage_resistance = 2030-01-01
sha1.collision_resistance = 2022-01-01

The packets section allows configurations for different versions of a packet type. The following example sets (different) cutoff times for signature packets in version 3 and 4, while unrestrictedly allows version 5 - since version 5 signatures are not yet available, ignore_invalid is set for this key:

signature.v3 = 2017-01-01
signature.v4 = 2030-01-01
signature.v5 = "always"
signature.ignore_invalid = "v5"

Complete list of sections and keys

[hash_algorithms]
md5 = ...
sha1 = ...
ripemd160 = ...
sha256 = ...
sha384 = ...
sha512 = ...
sha224 = ...

[asymmetric_algorithms]
rsa1024 = ...
rsa2048 = ...
rsa3072 = ...
rsa4096 = ...
elgamal1024 = ...
elgamal2048 = ...
elgamal3072 = ...
elgamal4096 = ...
dsa1024 = ...
dsa2048 = ...
dsa3072 = ...
dsa4096 = ...
nistp256 = ...
nistp384 = ...
nistp521 = ...
brainpoolp256 = ...
brainpoolp512 = ...
cv25519 = ...

[symmetric_algorithms]
idea = ...
tripledes = ...
cast5 = ...
blowfish = ...
aes128 = ...
aes192 = ...
aes256 = ...
twofish = ...
camellia128 = ...
camellia192 = ...
camellia256 = ...

[aead_algorithms]
eax = ...
ocb = ...

[packets]
pkesk = ...
signature = ...
skesk = ...
onepasssig = ...
secretkey = ...
publickey = ...
secretsubkey = ...
compresseddata = ...
sed = ...
marker = ...
literal = ...
trust = ...
userid = ...
publicsubkey = ...
userattribute = ...
seip = ...
mdc = ...
aed = ...