5.1.3 How to manage the certificates and keys

--generate-key

--gen-key

This command allows the creation of a certificate signing request or a self-signed certificate. It is commonly used along with the --output option to save the created CSR or certificate into a file. If used with the --batch a parameter file is used to create the CSR or certificate and it is further possible to create non-self-signed certificates.

--list-keys

-k

List all available certificates stored in the local key database. Note that the displayed data might be reformatted for better human readability and illegal characters are replaced by safe substitutes.

--list-secret-keys

-K

List all available certificates for which a corresponding a secret key is available.

--list-external-keys pattern

List certificates matching pattern using an external server. This utilizes the dirmngr service.

--list-chain

Same as --list-keys but also prints all keys making up the chain.

--dump-cert

--dump-keys

List all available certificates stored in the local key database using a format useful mainly for debugging.

--dump-chain

Same as --dump-keys but also prints all keys making up the chain.

--dump-secret-keys

List all available certificates for which a corresponding a secret key is available using a format useful mainly for debugging.

--dump-external-keys pattern

List certificates matching pattern using an external server. This utilizes the dirmngr service. It uses a format useful mainly for debugging.

--show-certs [files]

This command takes certificate files as input and prints information about them in the same format as --dump-cert does. Each file may either contain a single binary certificate or several PEM encoded certificates. If no files are given, the input is taken from stdin.

Please note that the listing format may be changed in future releases and that the option --with-colons has currently no effect.

--keydb-clear-some-cert-flags

This is a debugging aid to reset certain flags in the key database which are used to cache certain certificate statuses. It is especially useful if a bad CRL or a weird running OCSP responder did accidentally revoke certificate. There is no security issue with this command because gpgsm always make sure that the validity of a certificate is checked right before it is used.

--delete-keys pattern

Delete the keys matching pattern. Note that there is no command to delete the secret part of the key directly. In case you need to do this, you should run the command gpgsm --dump-secret-keys KEYID before you delete the key, copy the string of hex-digits in the “keygrip” line and delete the file consisting of these hex-digits and the suffix .key from the private-keys-v1.d directory below our GnuPG home directory (usually ~/.gnupg).

--export [pattern]

Export all certificates stored in the Keybox or those specified by the optional pattern. Those pattern consist of a list of user ids (see how-to-specify-a-user-id). When used along with the --armor option a few informational lines are prepended before each block. There is one limitation: As there is no commonly agreed upon way to pack more than one certificate into an ASN.1 structure, the binary export (i.e. without using armor) works only for the export of one certificate. Thus it is required to specify a pattern which yields exactly one certificate. Ephemeral certificate are only exported if all pattern are given as fingerprints or keygrips.

--export-secret-key-p12 key-id

Export the private key and the certificate identified by key-id using the PKCS#12 format. When used with the --armor option a few informational lines are prepended to the output. Note, that the PKCS#12 format is not very secure and proper transport security should be used to convey the exported key. (See option --p12-charset.)

--export-secret-key-p8 key-id

--export-secret-key-raw key-id

Export the private key of the certificate identified by key-id with any encryption stripped. The ...-raw command exports in PKCS#1 format; the ...-p8 command exports in PKCS#8 format. When used with the --armor option a few informational lines are prepended to the output. These commands are useful to prepare a key for use on a TLS server.

--import [files]

Import the certificates from the PEM or binary encoded files as well as from signed-only messages. This command may also be used to import a secret key from a PKCS#12 file.

--learn-card

Read information about the private keys from the smartcard and import the certificates from there. This command utilizes the gpg-agent and in turn the scdaemon.

--change-passphrase user_id

--passwd user_id

Change the passphrase of the private key belonging to the certificate specified as user_id. Note, that changing the passphrase/PIN of a smartcard is not yet supported.