Ubuntu Manpage: sq key

NAME

       sq key - Manage keys

SYNOPSIS

       sq key list [OPTIONS] FINGERPRINT|KEYID|PATTERN
       sq key generate [OPTIONS]
       sq key import [OPTIONS] KEY_FILE
       sq key export [OPTIONS]
       sq key delete [OPTIONS]
       sq key password [OPTIONS]
       sq key expire [OPTIONS]
       sq key revoke [OPTIONS]
       sq key userid [OPTIONS]  SUBCOMMAND
       sq key subkey [OPTIONS]  SUBCOMMAND
       sq key approvals [OPTIONS]  SUBCOMMAND

DESCRIPTION

       Manage keys.

       We  use  the term "key" to refer to OpenPGP keys that do contain secrets.  This subcommand
       provides primitives to generate and otherwise manipulate keys.

       Conversely, we use the term "certificate", or "cert" for short, to refer to  OpenPGP  keys
       that do not contain secrets.  See `sq cert` for operations on certificates.

SUBCOMMANDS

sq key list
List keys managed by the key store.

sq key generate
Generate a new key.

Generating a key is the prerequisite to receiving encrypted messages and creating
signatures. There are a few parameters to this process, but we provide reasonable
defaults for most users.

When generating a key, we also generate an emergency revocation certificate. This can be
used in case the key is lost or compromised. It is saved alongside the key. This can be
changed using the `--rev-cert` argument.

By default a key expires after 3 years. This can be changed using the `--expiration`
argument.

`sq key generate` respects the reference time set by the top-level `--time` argument. It
sets the creation time of the primary key, any subkeys, and the binding signatures to the
reference time.

sq key import
Import keys into the key store.

sq key export
Export keys from the key store.

Exports the secret key material associated with a certificate. Note that even if secret
key material is available, it may not be exportable. For instance, secret key material
stored on a hardware security module usually cannot be exported from the device.

Iterate over all of the specified certificates and export any keys (primary key and
subkeys) with secret key material. An error is returned if any specified certificate does
not contain any secret key material.

If you only want to export a particular key and not all keys associate with a certificate,
use `sq key subkey export`.

sq key delete
Delete a certificate's secret key material.

sq key password
Change the password protecting secret key material.

Secret key material can be protected by a password. This subcommand changes or clears the
password.

To strip the password either use `--clear` or supply a zero-length password when prompted
for the new password.

If a key is password protected, and the correct password was not supplied using the
`--password-file` argument, the user is prompted for the password. Likewise, if the new
password isn't provided, the user is prompted.

sq key expire
Change a certificate's expiration time.

This subcommand changes a certificate's expiration time. To change the expiration time of
an individual subkey, use the `sq key subkey expire` subcommand.

sq key revoke
Revoke a certificate.

Creates a revocation certificate for a certificate.

If `--revoker` or `--revoker-file` is provided, then that key is used to create the
revocation certificate. If that key is different from the certificate that is being
revoked, this results in a third-party revocation. This is normally only useful if the
owner of the certificate designated the key to be a designated revoker.

`sq key revoke` respects the reference time set by the top-level `--time` argument. When
set, it uses the specified time instead of the current time when determining what keys are
valid, and it sets the revocation certificate's creation time to the reference time
instead of the current time.

sq key userid
Manage User IDs.

Add User IDs to a key, or revoke them.

sq key subkey
Manage subkeys.

Add new subkeys to an existing certificate, change their expiration, and revoke them.

sq key approvals
Manages certification approvals.

Key holders may approve of third-party certifications associated with their certificate.
This subcommand manages the approvals.

To prevent certificate flooding attacks, modern key servers prevent uncontrolled
distribution of third-party certifications on certificates. To allow the key holder to
control what information is distributed with their certificate, these key servers only
distribute third-party certifications that the key holder has explicitly approved.

EXAMPLES

sq key list
List the keys managed by the keystore server.

sq key list

List the keys managed by the keystore server with a user ID in example.org.

sq key list --cert-domain=example.org

sq key generate
Generate a key, and save it on the key store.

sq key generate --own-key --without-password --name Alice \
--email alice@example.org

Generate a key, and save it in a file instead of in the key store.

sq key generate --own-key --without-password --name Alice \
--email alice@example.org --output alice-priv.pgp \
--rev-cert alice-priv.rev

Strip the secret key material from the new key.

sq key delete --cert-file=alice-priv.pgp --output=alice.pgp

sq key import
Import the keys into the key store.

sq key import alice-secret.pgp

sq key export
Export Alice's certificate with all available secret key material.

sq key export --cert EB28F26E2739A4870ECC47726F0073F60FD0CBF0

Export Alice's certificate with all available secret key material identified by email
address.

sq key export --cert-email alice@example.org

sq key delete
Delete any secret key associated with Alice's certificate.

sq key delete --cert EB28F26E2739A4870ECC47726F0073F60FD0CBF0

Delete any secret key associated with Alice's certificate selected by user ID.

sq key delete --cert-email=alice@example.org

sq key password
Change the password for all of Alice's keys to the password in the specified file.

sq key password --new-password-file password-file.txt --cert \
EB28F26E2739A4870ECC47726F0073F60FD0CBF0

Clear the password protection for all of Alice's keys.

sq key password --password-file password-file.txt \
--clear-password --cert \
EB28F26E2739A4870ECC47726F0073F60FD0CBF0

sq key expire
Change Alice's certificate to expire in a year.

sq key expire --expiration 1y --cert \
EB28F26E2739A4870ECC47726F0073F60FD0CBF0

Change Alice's certificate to never expire.

sq key expire --expiration never --cert \
EB28F26E2739A4870ECC47726F0073F60FD0CBF0

sq key revoke
Revoke Alice's key, indicating that there is a new certificate.

sq key revoke --cert EB28F26E2739A4870ECC47726F0073F60FD0CBF0 \
--reason superseded --message \
"My new cert is C5999E8191BF7B503653BE958B1F7910D01F86E5"

Revoke the key, indicating that the secret key material was compromised.

sq key revoke --cert EB28F26E2739A4870ECC47726F0073F60FD0CBF0 \
--reason compromised --message \
"Computer attacked, secret key material compromised"

VERSION