home | help 
SQ(1)				  User Commands 			   SQ(1)

NAME
     sq-key - Manage keys

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

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	certifi-
     cate. 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 rotate
     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., argu-
     ments.   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  us-
     ing the `--expiration` argument.

     The new certificate will have the same self-signed user IDs as the old cer-
     tificate.	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` argu-
     ment.

     The new certificate will certify the same certificates as the old	certifi-
     cate.  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 de-
     fault, it will go into effect in 182 days.  This can  be  changed	or  sup-
     pressed using the `--retire-in` argument.

     When  using `--output`, the new certificate as well as all of the other up-
     dated certificates are written to the specified file.

     Stable since 1.2.0.

   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  pass-
     word.  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 ex-
     piration  time of an individual subkey, use the `sq key subkey expire` sub-
     command.

   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 cer-
     tificate 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	certifi-
     cate'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  uncon-
     trolled distribution of third-party certifications on certificates.  To al-
     low  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 --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 identi-
     fied 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 speci-
     fied 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
     sq(1),	 sq-key-list(1),      sq-key-generate(1),      sq-key-rotate(1),
     sq-key-import(1),	sq-key-export(1),  sq-key-delete(1), sq-key-password(1),
     sq-key-expire(1),	sq-key-revoke(1),  sq-key-userid(1),   sq-key-subkey(1),
     sq-key-approvals(1).

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

VERSION
     1.3.1

Sequoia PGP			      1.3.1				   SQ(1)
home | help