3.1.3 How to manage your keys

This section explains the main commands for key management

--gen-key

Generate a new key pair. This command is normally only used interactively.

There is an experimental feature which allows you to create keys in batch mode. See the file doc/DETAILS in the source distribution on how to use this.

--gen-revoke name

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

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

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.

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.

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

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

Toggle between public and secret key listing.

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.

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 option is only useful to bring older keys up to date.

save

Save all changes to the key rings and quit.

quit

Quit the program without updating the key rings.

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: the first is the assigned owner trust and the second is the calculated trust value. Letters are used for the values:

-

No ownertrust assigned / not yet calculated.

e

Trust calculation has failed; probably due to an expired key.

q

Not enough information for calculation.

n

Never trust this key.

m

Marginally trusted.

f

Fully trusted.

u

Ultimately trusted.

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

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