SQ(1)

SQ(1) 💖 — or as I like to call her, sq-key-rotate

Hey bestie 🫶 you've landed on the manual page for sq key rotate, which lives in the User Commands corner of the Sequoia PGP universe. Let's get into it ✨

---

NAME 🎀

sq-key-rotate — Rotate a certificate 💅

---

SYNOPSIS 🌸

sq key rotate [OPTIONS]

That's it, that's the whole vibe. Options go brrr 🦋

---

DESCRIPTION 👑

Rotation. Of a certificate. Iconic behaviour, honestly.

It generates a brand new certificate to replace an existing one. Out with the old, in with the new, no cap 💖

The new certificate will have the same capabilities as the old certificate. You can override that with the --can-sign, --cannot-sign, etc., arguments. But heads up bestie: 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. So it's giving glow-up, not clone 💅

By default the certificate expires after 3 years. Change that with the --expiration argument.

The new certificate will have the same self-signed user IDs as the old certificate. Revoked user IDs are ignored. (Sorry to the revoked ones, you're not invited 🚫)

The new certificate and the old certificate will cross certify each other as unconstrained trusted introducers. Mutual hype, mutual trust, we love to see it 🫶

The new certificate will be linked in the same way as the old certificate. Override with --own-key or --shared-key if you want.

The new certificate will certify the same certificates as the old certificate. Basically the old cert's certifications get replayed. Peep sq pki vouch replay for more on that.

A revocation certificate will be issued, saying the old certificate is retired and the new certificate should be used instead. By default it goes into effect in 182 days. Change it or suppress it entirely with --retire-in.

When you use --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 around, she's reliable, she's a queen.

---

✨ OPTIONS ✨

🌈 Subcommand options

• --can-authenticate — Add an authentication-capable subkey 🔐
• --can-encrypt=PURPOSE — Add an encryption-capable subkey

Encryption-capable subkeys can be marked as suitable for transport encryption, storage encryption, or both, i.e., universal.

[possible values: transport, storage, universal]

• --can-sign — Add a signing-capable subkey ✍️
• --cannot-authenticate — Don't add an authentication-capable subkey 🙅
• --cannot-encrypt — Don't add an encryption-capable subkey 🚫
• --cannot-sign — Don't add a signing-capable subkey 🙈
• --cert=FINGERPRINT|KEYID — Use certificates with the specified fingerprint or key ID 🔎
• --cert-email=EMAIL — Use certificates where a user ID includes the specified email address 📧
• --cert-file=PATH — Read certificates from PATH 📂
• --cert-userid=USERID — Use certificates with the specified user ID 🪪
• --cipher-suite=CIPHER-SUITE — Select the cryptographic algorithms for the key 🔐

The default can be changed in the configuration file using the setting key.generate.cipher-suite.

[default: cv25519]

[possible values: rsa2k, rsa3k, rsa4k, cv25519, cv448, mldsa65-ed25519, mldsa87-ed448]

• --expiration=EXPIRATION — Sets the expiration time ⏳

EXPIRATION is either an ISO 8601 formatted date with an optional time or a custom duration. A duration takes the form N[ymwds], where the letters stand for years, months, weeks, days, and seconds, respectively. Alternatively, the keyword never does not set an expiration time.

[default: 3y]

• --new-password-file=PASSWORD_FILE — File containing password to encrypt the secret key material 🔑

Note that the entire key file will be used as the password including any surrounding whitespace like a trailing newline. Yes bestie, that trailing newline counts. Every byte of it. 😭

• --output=FILE — Write the key to the specified file 💾

When not specified, the key is saved on the key store.

• --own-key — Mark the key as one's own key 👑

The newly generated key with all of its user IDs will be marked as authenticated and as a fully trusted introducer.

• --profile=PROFILE — Select the OpenPGP standard for the key 📜

As OpenPGP evolves, new versions will become available. This option selects the version of OpenPGP to use for the newly generated key.

Currently, sq supports only one version: RFC4880. Consequently, this is the default. However, there is already a newer version of the standard: RFC9580. And, the default will change in a future version of sq.

The default can be changed in the configuration file using the setting key.generate.profile.

[default: rfc4880]

[possible values: rfc9580, rfc4880]

• --retire-in=TIME — Sets the time at which the certificate should be retired ⏰

TIME is either an ISO 8601 formatted date with an optional time or a custom duration. A duration takes the form N[ymwds], where the letters stand for years, months, weeks, days, and seconds, respectively. Alternatively, the keyword never skips the certification of a revocation certificate.

[default: 26w]

• --rev-cert=FILE — Write the emergency revocation certificate to FILE 🚨

When the key is stored on the key store, the revocation certificate is stored in $HOME/.local/share/sequoia/revocation-certificates by default.

When --output is specified, the revocation certificate is written to the file specified by --rev-cert.

If --output is -, then this option must not also be -. fr fr, don't do it.

• --shared-key — Mark the key as a shared key 👯

The newly generated key with all of its user IDs will be marked as authenticated, but not as a trusted introducer. Further, the key metadata will indicate that this is a shared key.

Use this option if you plan to share this key with other people. Normally, you shouldn't share keys material. An example of where you might want to do this is a shared mailbox.

• --without-password — Don't protect the secret key material with a password 🫣

🌟 Global options

See sq(1) for a description of the global options. She's the main character, go read her page 💅

---

💫 EXAMPLES 💫

Rotates Alice's certificate. Slay, Alice 🎀

sq key rotate --cert EB28F26E2739A4870ECC47726F0073F60FD0CBF0

---

🔗 SEE ALSO 🔗

sq(1), sq-key(1).

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

---

🏷️ VERSION 🏷️

1.5.0 ✨

---

Okay that's the whole page bestie, you ate that 🫶 This lil' beauty is brought to you by Sequoia PGP, version 1.5.0 — mwah 💋 go rotate something iconic 👑💖