info gnupg

File: gnupg.info, Node: OpenPGP Key Management, Prev: Operational GPG Commands, Up: GPG Commands

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

'--quick-add-adsk FPR ADSKFPR'
Directly add an Additional Decryption Subkey to the key identified
by the fingerprint FPR. ADSKFPR is the fingerprint of another
key's encryption subkey. A subkey is commonly used here because by
default a primary key has no encryption capability. Use the option
'--with-subkey-fingerprint' with a list command to display the
subkey fingerprints. If the string "default" is used for ADSKFPR
all missing ADSKs configured with '--default-new-key-adsk' are
added.

'--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 useful in
distinct communities or groups to implement the concept of a
Trusted Introducer. 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
'gpg --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. Note
that an unattended version of this command is available as
'--quick-update-pref'.

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.

keytotpm
Transfer the selected secret subkey (or the primary key if no
subkey has been selected) to TPM form. The secret key in the
keyring will be replaced by the TPM representation of that
key, which can only be read by the particular TPM that created
it (so the keyfile now becomes locked to the laptop containing
the TPM). Only certain key types may be transferred to the TPM
(all TPM 2.0 systems are mandated to have the rsa2048 and
nistp256 algorithms but newer TPMs may have more). Note that
the key itself is not transferred into the TPM, merely
encrypted by the TPM in-place, so if the keyfile is deleted,
the key will be lost. Once transferred to TPM representation,
the key file can never be converted back to non-TPM form and
the key will die when the TPM does, so you should first have a
backup on secure offline storage of the actual secret key file
before conversion. It is essential to use the physical system
TPM that you have rw permission on the TPM resource manager
device (/dev/tpmrm0). Usually this means you must be a member
of the tss group.

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

addadsk
Add an Additional Decryption Subkey. The user is asked to
enter the fingerprint of another encryption subkey. Note that
the exact fingerprint of another key's encryption subkey needs
to be entered. This is because commonly the primary key has
no encryption capability. Use the option
'--with-subkey-fingerprint' with a list command to display the
subkey fingerprints.

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 keyring and quit.

quit
Quit the program without updating the keyring.

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, *note trust-values::.

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

'--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 these 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. If
you need to update an existing signature, for example to add or
change notation data, you need to use the option
'--force-sign-key'.

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.

'--quick-update-pref USER-ID'
This command updates the preference list of the key to the current
default value (either built-in or set via
'--default-preference-list'). This is the unattended version of
using "setpref" in the '--key-edit' menu without giving a list.
Note that you can show the preferences in a key listing by using
'--list-options show-pref' or '--list-options show-pref-verbose'.
You should also re-distribute updated keys to your peers.

'--quick-set-ownertrust USER-ID VALUE'
This command sets the ownertrust of a key and can also be used to
set the disable flag of a key. This is the unattended version of
using "trust", "disable", or "enable" in the '--key-edit' menu.

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