Getting started

Let's start with a short overview of some terminology, the toplevel structure of sq, and some features to support you when using sq.

Terminology

Keys and certificates

sq uses a different terminology when it comes to certain cryptographic artifacts. What is known as a "public key" in other OpenPGP software (like gpg), is called a "certificate" in sq. "Private keys" are just called "keys". For the rationale behind this renaming, see chapter Background: Keys and certificates.

Stores instead of keyrings

Some popular OpenPGP implementations store their artifacts in keyrings (secring.pgp, pubring.pgp); sq uses stores for that. Keys are stored in the key store, certificates in the cert store. sq has (limited) support for keyrings to help (for instance) with migration.

"Authenticated"

"Authenticated" in the context of sq means "The right thing". Its main usage is in the selection or designation of a certificate. If you designate a certificate by its fingerprint, this designation is distinct, as fingerprints are unique. Designating by User ID is not, as these cannot be deduced from the key material like a fingerprint can. To use the binding between a certificate and a User ID to designate a certificate (for instance to select a certificate by an email address), this binding has to be authenticated; it has to be manually marked as valid or inherit authenticity by being certified by a trust introducer.

Trust introducer

A trust introducer is a person or institution considered sufficiently trustworthy (and competent) that certifications they have done are accepted. Trust introducers can be limited in scope:

  • so that only specific certifications are considered,
  • in spreading trust — can a trust introducer introduce other entities as further introducers?
  • and trustworthiness, affecting the amount of authenticity a certification adds to a specific certificate.

Technically, a trust introducer is represented by a certificate. Each user has to individually promote a certificate to become a trust introducer. There is no limit to the number of trust introducers a user can have.

Public Key Infrastructure (PKI)

sq does not support implicit authentication; it's not enough to just import a certificate (aka public key) to use it. The User IDs must first be authenticated, which declares a "trust relationship" with the imported certificates.

These relationships are managed within the PKI. You can think of this as your local Web of Trust.

Structure of the interface

The functions of sq are split into categories. Related functions are located in the same category, sometimes even in subcategories.

For orientation, these are the top-level categories:

  • encrypt Encryption of messages or data files.
  • decrypt Decryption of messages or data files.
  • sign Signing messages or data files.
  • verify Verify signed messages or detached signatures.
  • download Download and authenticate a file in one go.
  • inspect Inspect data, like file(1). Works on files, but also on objects in the different stores like certificates or keys.
  • cert Manage certificates. Import, export, list and the like.
  • key Manage keys. Generating, revoking, listing, import/export, updating metadata like expiry date and more.
  • pki This is where your "trust management" lives. Authenticating, lookup, trust paths and amounts and more.
  • network Retrieve and publish certificates over the network.
  • keyring Manage collections of keys or certs in files.
  • packet Low-level packet manipulation.
  • config Get configuration options.
  • version Detailed version and output version information.
  • help Print this message or the help of the given subcommand(s).

For example, you can list your keys with:

$ sq key list
Help

sq has help pages for every command. If in doubt, use:

$ sq some command --help

to get a short overview of parameters and functionality of said command. You can also use:

$ sq help some command
Tab completion

sq comes with tab completion. Pressing the tab key will complete partially typed commands; a second press will present a set of alternatives that are available at that point in the command line. For example:

$ sq command <TAB><TAB>

will show you possible continuations of the command, available subcommands, parameters, and other options. Likewise sq com<TAB><TAB> will expand to sq command .

Hints

After completing a command, sq prints some hints for possible follow-up commands:

$ sq key generate --own-key --email 'alice@example.com'
[...]

Hint: Because you supplied the `--own-key` flag, the user IDs on this key have been marked as authenticated, and this key has been marked as a fully
      trusted introducer.  If that was a mistake, you can undo that with:

  $ sq pki link retract --cert=0F761BE91983E9B50F2180CA8747303171399A43 --all

Hint: You can export your certificate as follows:

  $ sq cert export --cert=0F761BE91983E9B50F2180CA8747303171399A43

Hint: Once you are happy you can upload it to public directories using:

  $ sq network keyserver publish --cert=0F761BE91983E9B50F2180CA8747303171399A43

The hints pick up the results of the command and include them appropriately. In this example, the displayed fingerprint is indeed the fingerprint of the key just generated.

Named parameters can be written like --email alice@example.com or --email=alice@example.com, with or without a = between the parameter name and value.