GPG

Getting started

The first time you are run the gpg command, it will create a configuration directory which contains your keyring.

gpg: directory '/home/user/.gnupg' created
gpg: keybox '/home/user/.gnupg/pubring.kbx' created
gpg: /home/user/.gnupg/trustdb.gpg: trustdb created

Creating a key

To receive an encrypted file that only you can open, you first need to create a key pair and then share your public key. Creating the key pair is similar to creating ssh keys in that you choose a key size, specify an identifier, and set a passphrase.

The gpg command has three options for creating a key pair:

1. The --quick-generate-key option requires you to specify the USER-ID field on the command line and optionally an algorithm, usage, and expire date. It implements defaults for all other options.
2. The --generate-key option prompts for the real name and email fields before asking for a confirmation to proceed. In addition to creating the key, it also stores a revocation certificate.
3. The --full-generate-key option, demonstrated below, provides a dialog for all options.

Examples

quick-generate-key

About to create a key for:
    "user@example.com"

Continue? (Y/n) y

You will prompted twice to enter your passphrase. Make sure you enter the same string both times.
Then it continues with output similar to:

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.

If your system has enough entropy already, you won’t need to do anything here. If not, it will pause to let you perform any of the suggested tasks.

Once you have caused enough chaos, GPG will create the requested key and present the results:

gpg: key BFD64F6B507A5AD4 marked as ultimately trusted
gpg: revocation certificate stored as '/home/user/.gnupg/openpgp-revocs.d/2F0E6A3A29026918C305BF0ABFD64F6B507A5AD4.rev'
public and secret key created and signed.

pub   rsa3072 2022-10-23 [SC] [expires: 2024-10-22]
      2F0E6A3A29026918C305BF0ABFD64F6B507A5AD4
uid                      user@example.com
sub   rsa3072 2022-10-23 [E]

Be sure to store the revocation certificate somewhere secure. You will need it to let others know that this version of this key is no longer to be trusted. For example, if your private key is stolen or you no longer use the email address that you were encrypting message for.

Listing keys

Public keys

To list your public GPG keys run:

gpg --list-keys

If you don’t have any keys in your keyring you will get output similar to the following:

gpg: checking the trustdb
gpg: no ultimately trusted keys found

If you do have keys in your keyring you should have output similar to this:

gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: next trustdb check due at 2024-10-22
/home/user/.gnupg/pubring.kbx
------------------------
pub   rsa3072 2022-10-23 [SC] [expires: 2024-10-22]
      2F0E6A3A29026918C305BF0ABFD64F6B507A5AD4
uid           [ultimate] user@example.com
sub   rsa3072 2022-10-23 [E]

The pub line tells you the type of key this is, rsa3072, the creation date, 2022-10-23, the usage flags, and the expiration date, 2024-10-22, which defaults to one (1) year from the creation date.
The next line, 2F0E6A3A29026918C305BF0ABFD64F6B507A5AD4 is the key-ID or fingerprint. You will need to know this value for many of the other gpg commands.
The last line is a sub-key.

Private keys

To list your private GPG keys run:

gpg --list-secret-keys

If you don’t have any private keys in your keyring, gpg will not print anything out. Otherwise, you will have something similar to:

/home/user/.gnupg/pubring.kbx
------------------------
sec   rsa3072 2022-10-23 [SC] [expires: 2024-10-22]
      2F0E6A3A29026918C305BF0ABFD64F6B507A5AD4
uid           [ultimate] user@example.com
ssb   rsa3072 2022-10-23 [E]

Deleting keys

If the key you want to delete is one you created, you will need to delete the secret key before deleting the public key.

If you aren’t sure if a public key has a paired private key or not, there are three (3) ways you can find out:

1. You can list all your private keys and see if the one you want is in the output list.
2. You can try deleting the private key with the command above and gpg will let you know if it doesn’t exist.
3. You can try deleting the public key with the command below and gpg will let you know if you need to delete the private key first.

Private key

Use this command to delete a private key:

gpg --delete-secret-keys key-ID

You will be asked a number of times if you real want to delete this private key and the associated sub-key:

gpg (GnuPG) 2.2.19; Copyright (C) 2019 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.


sec  rsa3072/BFD64F6B507A5AD4 2022-10-23 user@example.com

Delete this key from the keyring? (y/N) y
This is a secret key! - really delete? (y/N) y

Public key

Use this command to delete a public key:

gpg --delete-key key-ID

You will prompted just once to verify you want to delete the keys:

gpg (GnuPG) 2.2.19; Copyright (C) 2019 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.


pub  rsa3072/BFD64F6B507A5AD4 2022-10-23 user@example.com

Delete this key from the keyring? (y/N) y

GPG Flags