SQ(1)

NAME
sq keyring - Manages collections of keys or certs

SYNOPSIS
sq keyring list [OPTIONS] FILE
sq keyring split [OPTIONS] FILE
sq keyring merge [OPTIONS] FILE
sq keyring filter [OPTIONS] FILE
sq keyring lint [OPTIONS] FILE

DESCRIPTION
Manages collections of keys or certs.

Collections of keys or certificates (also known as "keyrings" when they contain secret key material, and "certrings" when they don't) are any number of concatenated certificates. This subcommand provides tools to list, split, merge, and filter keyrings.

Note: In the documentation of this subcommand, we sometimes use the terms keys and certs interchangeably.

SUBCOMMANDS

  sq keyring list
Lists keys in a keyring.

Prints the fingerprint as well as the primary userid for every certificate encountered in the keyring.

  sq keyring split
Splits a keyring into individual keys.

Splitting up a keyring into individual keys helps with curating a keyring.

The converse operation is `sq keyring merge`.

  sq keyring merge
Merges keys or keyrings into a single keyring.

Multiple versions of the same certificate are merged together. Where data is replaced (e.g., secret key material), data from the later certificate is preferred.

  sq keyring filter
Joins keys into a keyring applying a filter.

This can be used to filter keys based on given predicates, e.g. whether they have a user id containing an email address with a certain domain. Additionally, the keys can be pruned to only include components matching the predicates.

If no filters are supplied, everything matches.

If multiple predicates are given, they are or'ed, i.e. a key matches if any of the predicates match. To require all predicates to match, chain multiple invocations of this command. See EXAMPLES for inspiration.

  sq keyring lint
Checks certificates for issues.

`sq keyring lint` checks the supplied certificates for the following SHA-1-related issues:

  - Whether a certificate revocation uses SHA-1.

  - Whether the current self signature for a non-revoked User ID uses
    SHA-1.

  - Whether the current subkey binding signature for a non-revoked,
    live subkey uses SHA-1.

  - Whether a primary key binding signature ("backsig") for a
    non-revoked, live subkey uses SHA-1.

Diagnostics are printed to stderr. At the end, some statistics are shown. This is useful when examining a keyring. If `--fix` is specified and at least one issue could be fixed, the fixed certificates are printed to stdout.

This tool does not currently support smart cards. But, if only the subkeys are on a smart card, this tool may still be able to partially repair the certificate. In particular, it will be able to fix any issues with User ID self signatures and subkey binding signatures for encryption-capable subkeys, but it will not be able to generate new primary key binding signatures for any signing-capable subkeys.

EXAMPLES

  sq keyring list

List all certs

    sq keyring list certs.pgp

List all certs with a userid on example.org

    sq keyring filter --domain example.org certs.pgp \
        | sq keyring list

  sq keyring split

Split all certs

    sq keyring split certs.pgp

Split all certs, merging them first to avoid duplicates

    sq keyring merge certs.pgp | sq keyring split

  sq keyring merge

Merge certificate updates

    sq keyring merge certs.pgp romeo-updates.pgp

  sq keyring filter

Converts a key to a cert (i.e., remove any secret key material)

    sq keyring filter --to-cert cat juliet.pgp

Gets the keys with a user id on example.org

    sq keyring filter --domain example.org keys.pgp

Gets the keys with a user id on example.org or example.net

    sq keyring filter --domain example.org --domain example.net \
        keys.pgp

Gets the keys with a user id with the name Juliet

    sq keyring filter --name Juliet keys.pgp

Gets the keys with a user id with the name Juliet on example.org

    sq keyring filter --domain example.org keys.pgp | \
        sq keyring filter --name Juliet

Gets the keys with a user id on example.org, pruning other userids

    sq keyring filter --domain example.org --prune-certs certs.pgp

  sq keyring lint

To gather statistics, simply run:

    sq keyring lint keyring.pgp

To fix a key:

    gpg --export-secret-keys FPR \
        | sq keyring lint --fix -p passw0rd -p password123 \
        | gpg --import

To get a list of keys with issues:

    sq keyring lint --list-keys keyring.pgp \
        | while read FPR; do something; done

SEE ALSO
sq(1), sq-keyring-list(1), sq-keyring-split(1), sq-keyring-merge(1), sq-keyring-filter(1), sq-keyring-lint(1).

For the full documentation see <https://book.sequoia-pgp.org>.

VERSION
0.33.0 (sequoia-openpgp 1.17.0)