SQ(1)

📦
version 1.5.0 · 7 versions
, in fedora 43, fedora 44, nixpkgs unstable, opensuse-leap 16.0

SQ(1) — the sq-key glow-up 💅

okay bestie, welcome to sq-key, the little corner of the sq universe where we manage keys. it lives in the User Commands section of the manual, and yes, this is the whole vibe. grab a snack. 🍓

✨ SYNOPSIS ✨

sq key list [OPTIONS] FINGERPRINT|KEYID|PATTERN
sq key generate [OPTIONS]
sq key rotate [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

look at that lineup. every single one is a bop. 🎀

💖 DESCRIPTION 💖

Manage keys. fr fr, that's the whole job.

okay so terminology check, because words matter: we use the term "key" to refer to OpenPGP keys that do contain secrets. this subcommand hands you the primitives to generate keys and otherwise manipulate them. 🔑

conversely — and this is the part people mix up — we use the term "certificate", or "cert" for short, to refer to OpenPGP keys that do not contain secrets. want operations on certificates? that's sq cert, different page, different era. 💅

🌸 SUBCOMMANDS 🌸

sq key list

List keys managed by the key store. the little inventory moment. 🦋

sq key generate

Generate a new key. the main character origin story. 👑

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, so you don't have to think too hard. 💖

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. no cap. 🕰️

sq key rotate

Rotate a certificate. glow-up time, but for crypto. 🦋✨

generates a new certificate to replace an existing one.

the new certificate will have the same capabilities as the old certificate. this can be overridden using the --can-sign, --cannot-sign, etc., arguments. Note: the new certificate may have a different shape from the old certificate. for instance, if the old certificate's primary key is marked as both certification and signing capable, the new certificate's primary key will be certification capable, and it will have a signing subkey. she's evolving, okay? 🧚

by default the certificate expires after 3 years. this can be changed using the --expiration argument.

the new certificate will have the same self-signed user IDs as the old certificate. revoked user IDs are ignored. 🙈

the new certificate and the old certificate will cross certify each other as unconstrained trusted introducers.

the new certificate will be linked in the same way as the old certificate. this can be overridden using the --own-key, or the --shared-key argument.

the new certificate will certify the same certificates as the old certificate. that is, the old certificate's certifications will be replayed. see sq pki vouch replay for more information.

a revocation certificate indicating that the old certificate is retired, and that the new certificate should be instead used will be issued. by default, it will go into effect in 182 days. this can be changed or suppressed using the --retire-in argument.

when using --output, the new certificate as well as all of the other updated certificates are written to the specified file.

Stable since 1.2.0. she's been iconic for a minute. 💅

sq key import

Import keys into the key store. come on in, bestie, the door's open. 🫶

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. 😭 the HSM said no and meant it.

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. no thoughts, just deletion. 💀

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-password 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. so interactive of her. ✨

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. important distinction, don't get it twisted. 💅

sq key revoke

Revoke a certificate. the dramatic exit. 🎭

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. iykyk. 🔥

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. the whole subkey lifecycle, babes. 🦋

sq key approvals

Manages certification approvals. very gatekeeping-on-purpose of her, and honestly? correct. 👑

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. see, it's not rudeness, it's security. 💖

🌈 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 --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 --name Alice --email \
       alice@example.org --output alice-priv.pgp --rev-cert \
       alice-priv.rev

sq key rotate

rotates Alice's certificate.

sq key rotate --cert EB28F26E2739A4870ECC47726F0073F60FD0CBF0

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"

🫶 SEE ALSO 🫶

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

⭐ VERSION ⭐

1.5.0

ok that's the whole page bestie, go forth and manage your keys responsibly 💖🔑

that's it, that's the manual — brought to you by Sequoia PGP, version 1.5.0, page SQ(1). mwah. 💅🎀✨

📦 where this page comes from