Files

TODO: https://gitlab.com/sequoia-pgp/sequoia-sq/-/issues/299

Intended content:

  • Which files/directories are used/created by sq, what is their purpose
  • Backing up and restoring a "known good state"
  • Switching between "states"
    • ENV-Variables

Directories

Sequoia PGP (and therefore sq) stores it's state - mainly keys and certificates - in a directory structure. The default locations are:

  • The certificate store (short cert store): $HOME/.local/share/pgp.cert.d
  • The key store: $HOME/.local/share/sequoia/keystore
  • The revocation certificate store: $HOME/.local/share/sequoia/revocation-certificates

These default locations can be changed by setting the environment variable SEQUOIA_HOME. There are subtle changes in the directory structure when using SEQUOIA_HOME:

  • The certificate store is: $SEQUOIA_HOME/data/pgp.cert.d
  • The key store is: $SEQUOIA_HOME/data/keystore
  • The revocation certificate store is: $SEQUOIA_HOME/data/revocation-certificates

If $SEQUOIA_HOME equals $HOME, then the default directory structure applies, as if SEQUOIA_HOME is not set.

The location of the cert store can be overridden by setting PGP_CERT_D or SQ_CERT_STORE. SQ_CERT_STORE has precedence over PGP_CERT_D. Both override the implied setting from SEQUOIA_HOME.

The location of the key store can be overridden by setting SQ_KEY_STORE, there is no second environment variable in this case.

All these locations can also be specified on the command line, which will override the environment variables.

Keystore

The keystore contains keypairs, public and secret key material, together with user ids and further metadata bundled together in files. These files are located in the subdirectory softkeys - 'hard keys' are keys stored on specialized hardware like smart cards.

The keystore corresponds to the secret keyring known from GnuPG.

Certificate store

The certificate store contains all certificates imported via sq cert import or fetched by sq network search. It also contains the keys for the intermediate CAs, the local trust root and a SQLite database for cert lookup.

The certificate store corresponds (roughly) to the public keyring known from GnuPG.

Revocation certificate store

Revocation certificates are created when keys are created. When a key is generated in the keystore, its revocation certificate gets stored in the revocation certificate store.

This revocation certificate is unspecific on the reason for revocation (which equals to 'compromised'). It's meant as a last resort, if the original key is lost and a more specific revocation cannot be created.