SQ(1)

💅 SQ(1) — the manual page for sq-key-generate

okay so bestie, you've landed in the SQ(1) manual, User Commands section, and this specific page is all about sq-key-generate. It's giving "first step of your whole cryptographic glow-up" energy. Let's go 🫶

---

✨ NAME ✨

sq-key-generate — generate a new key 🔑

---

🌸 SYNOPSIS 🌸

sq key generate [OPTIONS]

---

🦋 DESCRIPTION 🦋

Generate a new key. That's it, that's the whole vibe. 💫

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 like, you can customize, but you don't have to. Chill.

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. 🚨 (it's giving "break glass in case of emergency", and honestly, respect)

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, it syncs everything to that clock ⏰

---

💖 OPTIONS 💖

🎀 Subcommand options

• --allow-non-canonical-userids — Don't reject user IDs that are not in canonical form

Canonical user IDs are of the form Name (Comment) <localpart@example.org>. So if your user ID is, like, not that shape? This flag says "whatever, I'll allow it." 🙈

• --can-authenticate — Add an authentication-capable subkey (default)
• --can-encrypt=PURPOSE — Add an encryption-capable subkey [default: universal]

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 (default)
• --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
• --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]

• --email=ADDRESS — Add an email address as user ID to the key 📧
• --encryption-algorithm=ALGORITHM — Select the cryptographic algorithm for encryption keys

When set, the algorithm is used for encryption-capable keys. This parameter overrides the cipher suite parameter. (yes bestie, it outranks --cipher-suite, main character energy fr 👑)

[possible values: rsa2k, rsa3k, rsa4k, elgamal2k, elgamal3k, cv25519, x25519, x448, nistp256, nistp384, nistp521, brainpoolp256, brainpoolp384, brainpoolp512, mlkem768-x25519, mlkem1024-x448]

• --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]

• --name=NAME — Add a name as user ID to the key 🏷️
• --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. Like, the whole file, whitespace and all. Don't come for me, that's literally what it does. 😭

• --no-userids — Create a key without any user IDs
• --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 two profiles: RFC9580 and RFC4880. Currently, the default is RFC4880. However, once support for RFC9580 is rolled out further, the default will change in a future version of sq. (so heads up: the default is gonna move someday 👀)

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

[default: rfc4880]

[possible values: rfc9580, rfc4880]

• --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 -. ⚠️ No double dashes, bestie, that's the rule.

• --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. 📬

• --signing-algorithm=ALGORITHM — Select the cryptographic algorithm for signing keys ✍️

When set, the algorithm is used for keys used for signing. This includes keys with the signing, authentication, and the certification capability. This parameter overrides the cipher suite parameter.

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

[possible values: rsa2k, rsa3k, rsa4k, dsa2k, dsa3k, cv25519, ed25519, ed448, nistp256, nistp384, nistp521, brainpoolp256, brainpoolp384, brainpoolp512, mldsa65-ed25519, mldsa87-ed448, slhdsa128s, slhdsa128f, slhdsa256s]

• --userid=USERID — Add a user ID to the key

This user ID can combine name and email address, can optionally contain a comment, or even be free-form if --allow-non-canonical-userids is given. However, user IDs that include different information such as name and email address are more difficult to reason about, so using distinct user IDs for name and email address is preferred nowadays.

In doubt, prefer --name and --email. 💡

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

🌈 Global options

See sq(1) for a description of the global options.

---

⭐ EXAMPLES ⭐

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

---

👑 SEE ALSO 👑

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

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

---

🧚 VERSION 🧚

1.5.0

---

aaaand that's the page, bestie!! 🎀 this gorgeous piece of documentation is brought to you by Sequoia PGP, version 1.5.0 — so when you see 1.5.0 floating around, that's the glow-up era we're in. go forth and generate your key, you absolute icon 💜✨