SQ(1)

NAME
sq-key-rotate - Rotate a certificate

SYNOPSIS
sq key rotate [OPTIONS]

DESCRIPTION
Rotate a certificate.

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.

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.

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.

--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 `-`.

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

EXAMPLES

Rotates Alice's certificate.

    sq key rotate --cert EB28F26E2739A4870ECC47726F0073F60FD0CBF0

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

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

VERSION
1.4.0