Previous: Commands to select the type of operation, Up: Commands [Contents][Index]

#### 4.1.3 How to manage your keys

This section explains the main commands for key management.

`--quick-generate-key user-id [algo [usage [expire]]]` ¶
`--quick-gen-key`

  This is a simple command to generate a standard key with one user id. In contrast to `--generate-key` the key is generated directly without the need to answer a bunch of prompts. Unless the option `--yes` is given, the key creation will be canceled if the given user id already exists in the keyring.

  If invoked directly on the console without any special options an answer to a “Continue?” style confirmation prompt is required. In case the user id already exists in the keyring a second prompt to force the creation of the key will show up.

  If algo or usage are given, only the primary key is created and no prompts are shown. To specify an expiration date but still create a primary and subkey use “default” or “future-default” for algo and “default” for usage. For a description of these optional arguments see the command `--quick-add-key`. The usage accepts also the value “cert” which can be used to create a certification only primary key; the default is to a create certification and signing key.

  The expire argument can be used to specify an expiration date for the key. Several formats are supported; commonly the ISO formats “YYYY-MM-DD” or “YYYYMMDDThhmmss” are used. To make the key expire in N seconds, N days, N weeks, N months, or N years use “seconds=N”, “Nd”, “Nw”, “Nm”, or “Ny” respectively. Not specifying a value, or using “-” results in a key expiring in a reasonable default interval. The values “never”, “none” can be used for no expiration date.

  If this command is used with `--batch`, `--pinentry-mode` has been set to `loopback`, and one of the passphrase options (`--passphrase`, `--passphrase-fd`, or `passphrase-file`) is used, the supplied passphrase is used for the new key and the agent does not ask for it. To create a key without any protection `--passphrase ''` may be used.

  To create an OpenPGP key from the keys available on the currently inserted smartcard, the special string “card” can be used for algo. If the card features an encryption and a signing key, gpg will figure them out and creates an OpenPGP key consisting of the usual primary key and one subkey. This works only with certain smartcards. Note that the interactive `--full-gen-key` command allows to do the same but with greater flexibility in the selection of the smartcard keys.

  Note that it is possible to create a primary key and a subkey using non-default algorithms by using “default” and changing the default parameters using the option `--default-new-key-algo`.

`--quick-set-expire fpr expire [*|subfprs]` ¶

  With two arguments given, directly set the expiration time of the primary key identified by fpr to expire. To remove the expiration time `0` can be used. With three arguments and the third given as an asterisk, the expiration time of all non-revoked and not yet expired subkeys are set to expire. With more than two arguments and a list of fingerprints given for subfprs, all non-revoked subkeys matching these fingerprints are set to expire.

`--quick-add-key fpr [algo [usage [expire]]]` ¶

  Directly add a subkey to the key identified by the fingerprint fpr. Without the optional arguments an encryption subkey is added. If any of the arguments are given a more specific subkey is added.

  algo may be any of the supported algorithms or curve names given in the format as used by key listings. To use the default algorithm the string “default” or “-” can be used. Supported algorithms are “rsa”, “dsa”, “elg”, “ed25519”, “cv25519”, and other ECC curves. For example the string “rsa” adds an RSA key with the default key length; a string “rsa4096” requests that the key length is 4096 bits. The string “future-default” is an alias for the algorithm which will likely be used as default algorithm in future versions of gpg. To list the supported ECC curves the command `gpg --with-colons --list-config curve` can be used.

  Depending on the given algo the subkey may either be an encryption subkey or a signing subkey. If an algorithm is capable of signing and encryption and such a subkey is desired, a usage string must be given. This string is either “default” or “-” to keep the default or a comma delimited list (or space delimited list) of keywords: “sign” for a signing subkey, “auth” for an authentication subkey, and “encr” for an encryption subkey (“encrypt” can be used as alias for “encr”). The valid combinations depend on the algorithm.

  The expire argument can be used to specify an expiration date for the key. Several formats are supported; commonly the ISO formats “YYYY-MM-DD” or “YYYYMMDDThhmmss” are used. To make the key expire in N seconds, N days, N weeks, N months, or N years use “seconds=N”, “Nd”, “Nw”, “Nm”, or “Ny” respectively. Not specifying a value, or using “-” results in a key expiring in a reasonable default interval. The values “never”, “none” can be used for no expiration date.

`--generate-key` ¶
`--gen-key`

  Generate a new key pair using the current default parameters. This is the standard command to create a new key. In addition to the key a revocation certificate is created and stored in the `openpgp-revocs.d` directory below the GnuPG home directory.

`--full-generate-key` ¶
`--full-gen-key`

  Generate a new key pair with dialogs for all options. This is an extended version of `--generate-key`.

  There is also a feature which allows you to create keys in batch mode. See the manual section “Unattended key generation” on how to use this.

`--generate-revocation name` ¶
`--gen-revoke name`

  Generate a revocation certificate for the complete key. To only revoke a subkey or a key signature, use the `--edit` command.

  This command merely creates the revocation certificate so that it can be used to revoke the key if that is ever needed. To actually revoke a key the created revocation certificate needs to be merged with the key to revoke. This is done by importing the revocation certificate using the `--import` command. Then the revoked key needs to be published, which is best done by sending the key to a keyserver (command `--send-key`) and by exporting (`--export`) it to a file which is then send to frequent communication partners.

`--generate-designated-revocation name` ¶
`--desig-revoke name`

  Generate a designated revocation certificate for a key. This allows a user (with the permission of the keyholder) to revoke someone else’s key.

`--edit-key` ¶

  Present a menu which enables you to do most of the key management related tasks. It expects the specification of a key on the command line.

  uid n

    Toggle selection of user ID or photographic user ID with index n. Use `*` to select all and `0` to deselect all.

  key n

    Toggle selection of subkey with index n or key ID n. Use `*` to select all and `0` to deselect all.

  sign

    Make a signature on key of user `name`. If the key is not yet signed by the default user (or the users given with `-u`), the program displays the information of the key again, together with its fingerprint and asks whether it should be signed. This question is repeated for all users specified with `-u`.

  lsign

    Same as "sign" but the signature is marked as non-exportable and will therefore never be used by others. This may be used to make keys valid only in the local environment.

  nrsign

    Same as "sign" but the signature is marked as non-revocable and can therefore never be revoked.

  tsign

    Make a trust signature. This is a signature that combines the notions of certification (like a regular signature), and trust (like the "trust" command). It is generally only useful in distinct communities or groups. For more information please read the sections “Trust Signature” and “Regular Expression” in RFC-4880.

  Note that "l" (for local / non-exportable), "nr" (for non-revocable, and "t" (for trust) may be freely mixed and prefixed to "sign" to create a signature of any type desired.

  If the option `--only-sign-text-ids` is specified, then any non-text based user ids (e.g., photo IDs) will not be selected for signing.

  delsig

    Delete a signature. Note that it is not possible to retract a signature, once it has been send to the public (i.e. to a keyserver). In that case you better use `revsig`.

  revsig

    Revoke a signature. For every signature which has been generated by one of the secret keys, GnuPG asks whether a revocation certificate should be generated.

  check

    Check the signatures on all selected user IDs. With the extra option `selfsig` only self-signatures are shown.

  adduid

    Create an additional user ID.

  addphoto

    Create a photographic user ID. This will prompt for a JPEG file that will be embedded into the user ID. Note that a very large JPEG will make for a very large key. Also note that some programs will display your JPEG unchanged (GnuPG), and some programs will scale it to fit in a dialog box (PGP).

  showphoto

    Display the selected photographic user ID.

  deluid

    Delete a user ID or photographic user ID. Note that it is not possible to retract a user id, once it has been send to the public (i.e. to a keyserver). In that case you better use `revuid`.

  revuid

    Revoke a user ID or photographic user ID.

  primary

    Flag the current user id as the primary one, removes the primary user id flag from all other user ids and sets the timestamp of all affected self-signatures one second ahead. Note that setting a photo user ID as primary makes it primary over other photo user IDs, and setting a regular user ID as primary makes it primary over other regular user IDs.

  keyserver

    Set a preferred keyserver for the specified user ID(s). This allows other users to know where you prefer they get your key from. See `--keyserver-options honor-keyserver-url` for more on how this works. Setting a value of "none" removes an existing preferred keyserver.

  notation

    Set a name=value notation for the specified user ID(s). See `--cert-notation` for more on how this works. Setting a value of "none" removes all notations, setting a notation prefixed with a minus sign (-) removes that notation, and setting a notation name (without the =value) prefixed with a minus sign removes all notations with that name.

  pref

    List preferences from the selected user ID. This shows the actual preferences, without including any implied preferences.

  showpref

    More verbose preferences listing for the selected user ID. This shows the preferences in effect by including the implied preferences of 3DES (cipher), SHA-1 (digest), and Uncompressed (compression) if they are not already included in the preference list. In addition, the preferred keyserver and signature notations (if any) are shown.

  setpref string

    Set the list of user ID preferences to string for all (or just the selected) user IDs. Calling setpref with no arguments sets the preference list to the default (either built-in or set via `--default-preference-list`), and calling setpref with "none" as the argument sets an empty preference list. Use `gpg2 --version` to get a list of available algorithms. Note that while you can change the preferences on an attribute user ID (aka "photo ID"), GnuPG does not select keys via attribute user IDs so these preferences will not be used by GnuPG.

    When setting preferences, you should list the algorithms in the order which you’d like to see them used by someone else when encrypting a message to your key. If you don’t include 3DES, it will be automatically added at the end. Note that there are many factors that go into choosing an algorithm (for example, your key may not be the only recipient), and so the remote OpenPGP application being used to send to you may or may not follow your exact chosen order for a given message. It will, however, only choose an algorithm that is present on the preference list of every recipient key. See also the INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below.

  addkey

    Add a subkey to this key.

  addcardkey

    Generate a subkey on a card and add it to this key.

  keytocard

    Transfer the selected secret subkey (or the primary key if no subkey has been selected) to a smartcard. The secret key in the keyring will be replaced by a stub if the key could be stored successfully on the card and you use the save command later. Only certain key types may be transferred to the card. A sub menu allows you to select on what card to store the key. Note that it is not possible to get that key back from the card - if the card gets broken your secret key will be lost unless you have a backup somewhere.

  bkuptocard file

    Restore the given file to a card. This command may be used to restore a backup key (as generated during card initialization) to a new card. In almost all cases this will be the encryption key. You should use this command only with the corresponding public key and make sure that the file given as argument is indeed the backup to restore. You should then select 2 to restore as encryption key. You will first be asked to enter the passphrase of the backup key and then for the Admin PIN of the card.

  delkey

    Remove a subkey (secondary key). Note that it is not possible to retract a subkey, once it has been send to the public (i.e. to a keyserver). In that case you better use `revkey`. Also note that this only deletes the public part of a key.

  revkey

    Revoke a subkey.

  expire

    Change the key or subkey expiration time. If a subkey is selected, the expiration time of this subkey will be changed. With no selection, the key expiration of the primary key is changed.

  trust

    Change the owner trust value for the key. This updates the trust-db immediately and no save is required.

  disable
  enable

    Disable or enable an entire key. A disabled key can not normally be used for encryption.

  addrevoker

    Add a designated revoker to the key. This takes one optional argument: "sensitive". If a designated revoker is marked as sensitive, it will not be exported by default (see export-options).

  passwd

    Change the passphrase of the secret key.

  toggle

    This is dummy command which exists only for backward compatibility.

  clean

    Compact (by removing all signatures except the selfsig) any user ID that is no longer usable (e.g. revoked, or expired). Then, remove any signatures that are not usable by the trust calculations. Specifically, this removes any signature that does not validate, any signature that is superseded by a later signature, revoked signatures, and signatures issued by keys that are not present on the keyring.

  minimize

    Make the key as small as possible. This removes all signatures from each user ID except for the most recent self-signature.

  change-usage

    Change the usage flags (capabilities) of the primary key or of subkeys. These usage flags (e.g. Certify, Sign, Authenticate, Encrypt) are set during key creation. Sometimes it is useful to have the opportunity to change them (for example to add Authenticate) after they have been created. Please take care when doing this; the allowed usage flags depend on the key algorithm.

  cross-certify

    Add cross-certification signatures to signing subkeys that may not currently have them. Cross-certification signatures protect against a subtle attack against signing subkeys. See `--require-cross-certification`. All new keys generated have this signature by default, so this command is only useful to bring older keys up to date.

  save

    Save all changes to the keyrings and quit.

  quit

    Quit the program without updating the keyrings.

  The listing shows you the key with its secondary keys and all user IDs. The primary user ID is indicated by a dot, and selected keys or user IDs are indicated by an asterisk. The trust value is displayed with the primary key: "trust" is the assigned owner trust and "validity" is the calculated validity of the key. Validity values are also displayed for all user IDs. For possible values of trust, see trust-values.

`--sign-key name` ¶

  Signs a public key with your secret key. This is a shortcut version of the subcommand "sign" from `--edit`.

`--lsign-key name` ¶

  Signs a public key with your secret key but marks it as non-exportable. This is a shortcut version of the subcommand "lsign" from `--edit-key`.

`--quick-sign-key fpr [names]` ¶
`--quick-lsign-key fpr [names]`

  Directly sign a key from the passphrase without any further user interaction. The fpr must be the verified primary fingerprint of a key in the local keyring. If no names are given, all useful user ids are signed; with given [names] only useful user ids matching one of theses names are signed. By default, or if a name is prefixed with a ’*’, a case insensitive substring match is used. If a name is prefixed with a ’=’ a case sensitive exact match is done.

  The command `--quick-lsign-key` marks the signatures as non-exportable. If such a non-exportable signature already exists the `--quick-sign-key` turns it into a exportable signature.

  This command uses reasonable defaults and thus does not provide the full flexibility of the "sign" subcommand from `--edit-key`. Its intended use is to help unattended key signing by utilizing a list of verified fingerprints.

`--quick-add-uid user-id new-user-id` ¶

  This command adds a new user id to an existing key. In contrast to the interactive sub-command `adduid` of `--edit-key` the new-user-id is added verbatim with only leading and trailing white space removed, it is expected to be UTF-8 encoded, and no checks on its form are applied.

`--quick-revoke-uid user-id user-id-to-revoke` ¶

  This command revokes a user ID on an existing key. It cannot be used to revoke the last user ID on key (some non-revoked user ID must remain), with revocation reason “User ID is no longer valid”. If you want to specify a different revocation reason, or to supply supplementary revocation text, you should use the interactive sub-command `revuid` of `--edit-key`.

`--quick-revoke-sig fpr signing-fpr [names]` ¶

  This command revokes the key signatures made by signing-fpr from the key specified by the fingerprint fpr. With names given only the signatures on user ids of the key matching any of the given names are affected (see `--quick-sign-key`). If a revocation already exists a notice is printed instead of creating a new revocation; no error is returned in this case. Note that key signature revocations may be superseded by a newer key signature and in turn again revoked.

`--quick-set-primary-uid user-id primary-user-id` ¶

  This command sets or updates the primary user ID flag on an existing key. user-id specifies the key and primary-user-id the user ID which shall be flagged as the primary user ID. The primary user ID flag is removed from all other user ids and the timestamp of all affected self-signatures is set one second ahead.

`--change-passphrase user-id` ¶
`--passwd user-id`

  Change the passphrase of the secret key belonging to the certificate specified as user-id. This is a shortcut for the sub-command `passwd` of the edit key menu. When using together with the option `--dry-run` this will not actually change the passphrase but check that the current passphrase is correct.

Previous: Commands to select the type of operation, Up: Commands [Contents][Index]