PGP Operations

I found myself going into a LOT more detail while writing the About PGP (aka GnuPG) page, and realized that a lot of what I was writing was more than just information about GnuPG, it was information about how to use GnuPG.

For now I'm creating a separate page to cover these things. Knowing me, I suspect that over time this will grow into separate pages for different operations. For now, the information has already been written,

NOTE: This page is only meant as a quick reference. Knowing me, I may go into more detail (maybe too much detail?) about some things than I do about others. If anything is not clear or not covered, (1) please let me know, and (2) consult the official documentation.

⇒ https://www.gnupg.org/documentation/index.html

Primary Operations

These are the four primary operations that people use PGP for.

Encrypting messages

  • gpg -e or --encrypt

Decrypting messages

  • gpg -d or --decrypt

Signing messages

  • gpg -s or --sign
  • gpg -b or --detach-sign
  • gpg --clearsign or --clear-sign

Verifying signatures

  • gpg --verify

Key Management

These operations are used when copying PGP keys to/from other people.

Generate a new key

  • gpg --gen-key or --generate-key

    • Prompts for name and email, uses defaults for key algorithms and expiration dates.
    • Generates a primary key with usage flags [SC], and subkey with [E].

  • gpg --full-gen-key or --full-generate-key

    • Prompts for all necessary data.
    • Generates a primary key with usage flags [SC], and subkey with [E].

  • gpg --quick-gen-key or --quick-generate-key

    • Identity, key algorithm, usage flags, and expiration date are all specified as command line arguments.
    • Generates a primary key with usage flags named on command line.
    • Expire date format: YYYYmmddTHHMMSS (UTC) or YYYY-mm-dd (12:00:00 UTC on that date)
    • Does not generate any subkeys, use gpg --quick-add-key (which also requires key algorithm, usage flags, and expiration date as command line arguments).

Export keys

The usual way to share keys with other people is to "export" them from a keyring to a file, and distribute that file. (This is exactly what I did to make the https://jms1.pub/jms1.pub.asc file.) Exported keys can be in one of two formats:

  • A binary format, containing a series of raw PGP packets.

  • An "ASCII-armored" format, containing only "printable" characters.

    These files can be sent via email, copy/pasted in chat sessions, or printed on paper and later manually typed (if your typing is that accurate, and you have that kind of patience) without worrying about the key being corrupted in the process.

I normally use the ASCII-armored format, unless there's a speicific reason to need the binary format.

$ gpg --export -a E3F7F5F76640299C5507FBAA49B9FD3BB4422EBB
-----BEGIN PGP PUBLIC KEY BLOCK-----

mQINBFyT6EQBEADKXl/ss7pG15/rknrVSynsA9IlfNSrIPehmPerbvZfpv+hWgtO
hcizxTMUzPfe7P+jDuSyyVaKlFT8jSt2roOqOTtRbFr+jf0hQr+w1RbmqZvpgUON
KXFcY8xadqDdLn5s62IuCRoEyQsibz8buT0O7tarC2g8xtZeRoYX/iQYVykAuhYb
...
vucHCnsaTICZ+cvzhcNDr8eRAhgjTohjEntWcW1Ze22PML80cCYBWh52m0GrgZV2
nWq+bvEf7LllpTqBooNhuxs118Y75MhUWr8kiMZDFG6fiyJ5ALe6lh9ff/EMe4oF
mTBzKPfsw37Ap4X612y24g==
=oYGV
-----END PGP PUBLIC KEY BLOCK-----

The full output from this command, including the -----BEGIN PGP PUBLIC KEY BLOCK----- and -----END PGP PUBLIC KEY BLOCK----- lines, can be shared with others.

Exporting to a file

You can use the normal shell redirection mechanism (i.e. the ">" operator) to save the output to a file.

$ gpg --export -a E3F7F5F76640299C5507FBAA49B9FD3BB4422EBB > jms1.pgp.asc

This file is used in some of the other examples below.

If you're using Keybase, you will find this file in the /keybase/public/jms1/ directory (which is the "document root" for the jms1.pub web site, thanks to the magic of Keybase Sites).

Exporting multiple keys

Note that you can export a single block containing multiple public keys, by specifying multiple Key IDs, or by specifying a single identifier that matches multiple keys. Examples:

  • gpg --export -a 49B9FD3BB4422EBB 101F51733306FCFB

    Two explicit Key IDs. 49..BB is my currently active key, as shown above. 10..FB is an old key which was revoked several years ago after a floppy disk (remember those?) containing a backup copy of the secret key file went missing from my desk at work one day.

  • gpg --export -a jms1@jms1.net

    Identifier matching multiple keys. The keyring on this computer currently has six keys with this email address, some of which are expired (and I don't plan to extend them), one of which is revoked, and the others I just don't use anymore.

Import keys

If you receive an exported key, you can "import" it to your keyring.

Importing from a file

If the file is stored in a file, you can import the file like so:

$ gpg --import jms1.pub.asc
gpg: key 49B9FD3BB4422EBB: 6 signatures not checked due to missing keys
gpg: key 49B9FD3BB4422EBB: public key "John Simpson <jms1@jms1.net>" imported
gpg: Total number processed: 1
gpg:               imported: 1
gpg: no ultimately trusted keys found

So if you're using Keybase, you can import my public key like so:

$ gpg --import /keybase/public/jms1/jms1.pub.asc

Importing from another command

If you run some other command which outputs a PGP key, you can import the key from the first command's output.

$ curl -s https://jms1.pub/jms1.pub.asc | gpg --import
gpg: key 49B9FD3BB4422EBB: "John Simpson <jms1@jms1.net>" not changed
gpg: Total number processed: 1
gpg:              unchanged: 1

In this example, my keyring already had the key so it didn't actually do anything other than showing the contents of the downloaded file.

Importing via copy/paste

If you found a PGP key somewhere (on a web page, in a text file, wherever) you can COPY the key block, and PASTE it into your keyring. To do this ...

  • Highlight and COPY the key from wherever you found it. Be sure to include the -----BEGIN PGP PUBLIC KEY BLOCK----- and -----END PGP PUBLIC KEY BLOCK----- lines.

  • Run gpg --import and hit ENTER. The computer will be waiting for you to enter something.

  • PASTE.

  • Type whatever character tells your shell that the input is finished. For most Linux/macOS shells, this is CONTROL-D. (I remember it being CONTROL-Z for MS-DOS, so it might be the same for windows? Again, I don't use windows so I can't really say for certain.)

The process will look something like this:

$ gpg --import
<PASTE>
-----BEGIN PGP PUBLIC KEY BLOCK-----

mQINBFyT6EQBEADKXl/ss7pG15/rknrVSynsA9IlfNSrIPehmPerbvZfpv+hWgtO
...
nWq+bvEf7LllpTqBooNhuxs118Y75MhUWr8kiMZDFG6fiyJ5ALe6lh9ff/EMe4oF
mTBzKPfsw37Ap4X612y24g==
=oYGV
-----END PGP PUBLIC KEY BLOCK-----
<CONTROL-D>
gpg: key 49B9FD3BB4422EBB: "John Simpson <jms1@jms1.net>" not changed
gpg: Total number processed: 1
gpg:              unchanged: 1

Keyring Management

These operations are used to manage the keyring on your computer.

Technically, importing and exporting keys (above) also involve the keyring, however I think of those two operations differently than the ones below.

List keys

List the public keys on your keyring.

  • gpg -k or --list-keys or --list-public-keys
    • --with-colons option in scripts
    • --with-sig-check or gpg --check-sigs

List the secret keys on your keyring.

  • gpg -K or --list-secret-keys

Show keys

If you find a PGP key block, you can see its contents without importing it into your keyring.

$ gpg --show-key /keybase/public/jms1/jms1.pub.asc
pub   rsa4096 2019-03-21 [SC] [expires: 2024-01-01]
      E3F7F5F76640299C5507FBAA49B9FD3BB4422EBB
uid           [  full  ] John Simpson <jms1@jms1.net>
uid           [  full  ] John Simpson <kg4zow@mac.com>
uid           [  full  ] John Simpson <kg4zow@kg4zow.us>
sub   rsa4096 2019-03-21 [E] [expires: 2024-01-01]
sub   rsa4096 2019-03-21 [S] [expires: 2024-01-01]
sub   rsa4096 2019-03-21 [A] [expires: 2024-01-01]

You can also pipe the output of another command (which prints) a PGP key block) into gpg --show-keys.

$ curl -s https://jms1.pub/jms1.pub.asc | gpg --show-keys
pub   rsa4096 2019-03-21 [SC] [expires: 2024-01-01]
      E3F7F5F76640299C5507FBAA49B9FD3BB4422EBB
uid           [  full  ] John Simpson <jms1@jms1.net>
uid           [  full  ] John Simpson <kg4zow@mac.com>
uid           [  full  ] John Simpson <kg4zow@kg4zow.us>
sub   rsa4096 2019-03-21 [E] [expires: 2024-01-01]
      3C8EC9C7B067A4C542F9727D795C2CF824364755
sub   rsa4096 2019-03-21 [S] [expires: 2024-01-01]
      77DEBB0C8C7FBAFF1E0E70DCE9E44ED30E2F2445
sub   rsa4096 2019-03-21 [A] [expires: 2024-01-01]
      7A6B95B6BF897A6497165AE436823233F8D09EB7

Delete keys

Deletes keys from your keyring.

  • gpg --delete-keys
    • only deletes public keys
  • gpg --delete-secret-keys
    • delete secret keys before deleting public keys
  • gpg --delete-secret-and-public-key
    • I didn't know this option existed until I wrote this. 😎

Notes

  • This only deletes keys from your keyring. If other people have the key you're deleting, they will still have it, and the key will still be just as valid as it was before you "deleted" it.

  • If you delete one of your own secret keys, you won't be able to decrypt messages which were encrypted using that key (unless you have a backup of the secret key and import that.)

🛑 If one of your secret keys has been compromised (or you just don't want to use it anymore), you should create and send out a revocation certificate rather than just deleting it.

Certifications

Certifications are signatures applied to other PGP keys. If you "sign" somebody's PGP key, you are telling the world that you believe the key you're signing, really belongs to the person whose identity it says.

Show the signatures on a key

You can use "gpg --list-sigs" to show the signatures on a key.

$ gpg --list-sigs E3F7F5F76640299C5507FBAA49B9FD3BB4422EBB
pub   rsa4096 2019-03-21 [SC] [expires: 2024-01-01]
      E3F7F5F76640299C5507FBAA49B9FD3BB4422EBB
uid           [  full  ] John Simpson <jms1@jms1.net>
sig 3        49B9FD3BB4422EBB 2023-01-01  [self-signature]
sig          4630606F0B2F31A6 2019-03-21  John Simpson <email@$DAYJOB>
sig          A7EC1FBAB3B50007 2019-03-21  John Simpson <jms1@jms1.net>
uid           [  full  ] John Simpson <kg4zow@mac.com>
sig 3        49B9FD3BB4422EBB 2023-01-01  [self-signature]
sig          4630606F0B2F31A6 2019-03-21  John Simpson <email@$DAYJOB>
sig          A7EC1FBAB3B50007 2019-03-21  John Simpson <jms1@jms1.net>
uid           [  full  ] John Simpson <kg4zow@kg4zow.us>
sig 3        49B9FD3BB4422EBB 2023-01-01  [self-signature]
sig          4630606F0B2F31A6 2019-03-21  John Simpson <email@$DAYJOB>
sig          A7EC1FBAB3B50007 2019-03-21  John Simpson <jms1@jms1.net>
sub   rsa4096 2019-03-21 [E] [expires: 2024-01-01]
      3C8EC9C7B067A4C542F9727D795C2CF824364755
sig          49B9FD3BB4422EBB 2019-03-21  [self-signature]
sig          49B9FD3BB4422EBB 2020-03-14  [self-signature]
sig          49B9FD3BB4422EBB 2020-12-06  [self-signature]
sig          49B9FD3BB4422EBB 2021-12-31  [self-signature]
sig          49B9FD3BB4422EBB 2023-01-01  [self-signature]
sub   rsa4096 2019-03-21 [S] [expires: 2024-01-01]
      77DEBB0C8C7FBAFF1E0E70DCE9E44ED30E2F2445
sig          49B9FD3BB4422EBB 2019-03-21  [self-signature]
sig          49B9FD3BB4422EBB 2020-03-14  [self-signature]
sig          49B9FD3BB4422EBB 2020-12-06  [self-signature]
sig          49B9FD3BB4422EBB 2021-12-31  [self-signature]
sig          49B9FD3BB4422EBB 2023-01-01  [self-signature]
sub   rsa4096 2019-03-21 [A] [expires: 2024-01-01]
      7A6B95B6BF897A6497165AE436823233F8D09EB7
sig          49B9FD3BB4422EBB 2019-03-21  [self-signature]
sig          49B9FD3BB4422EBB 2020-03-14  [self-signature]
sig          49B9FD3BB4422EBB 2020-12-06  [self-signature]
sig          49B9FD3BB4422EBB 2021-12-31  [self-signature]
sig          49B9FD3BB4422EBB 2023-01-01  [self-signature]

You will notice that ...

  • All identities and subkeys should have signatures made by the primary key. (These are shown as [self-signature] in the output.)

  • Only identities will have signatures made by other PGP keys.

    If a key has multiple identities, it's entirely possible that each identity will have a different list of signatures. (Unfortunately this isn't true for this particular key, that would have made for a good example.)

  • Subkeys will have "signatures" which tell when they expire. If a key's expiration date has been changed over time (i.e. "renewed"), there may be multiple signatures with different dates. GnuPG always uses the last date (in chronological order) as the expiration date.

Note that the dates on each signature are when the signatures were created. Each key's current expiration date is shown as [expires: 2024-01-01] on the pub or sub lines.

Check the signatures on a key

The gpg --list-sigs command only shows the signatures on a key, it doesn't actually "do the math" to verify which signatures are actually valid.

  • gpg --check-sigs

    This command will "do the math" and verify that the signatures are valid.

Signing somebody else's key

When somebody "signs" a key, they are asserting that the key belongs to the person matching that identity.

  • gpg --sign-key

    • Your signature will be included if you export the key, or send it to a keyserver.
    • Same as the gpg --edit-key command's sign sub-command.

  • gpg --lsign-key

    • Your signature will NOT be included if you export the key or send it to a keyserver.

    • Same as the gpg --edit-key command's lsign sub-command.

      I'm sure that there are cases where you may want to do this, however I personally have never found one. Every time I've ever signed somebody else's PGP key, it was a normal "exportable" signature.

Trust

View trust levels

  • shown in key listings

  • values

    • undef or undefined
    • never
    • revoked
    • expired
    • marginal
    • full
    • ultimate
    • err

Assign a trust level

  • gpg --edit-key ... sign or lsign sub-commands

    This adds a signature to the target key. Assuming the key you're signing it with is trusted, the target key will be "trusted by association".

  • gpg --edit-key ... trust sub-command

    This will manually set a trust value for the target key. You can do this instead of, or in addition to, signing the key.

Revocation

A Revocation Certificate is a special message which tells other PGP clients to no longer trust a PGP key. This are needed when ...

  • The secret key has been compromised, i.e. if somebody steals a copy of your secret key.

  • You have lost access to the secret key, and no longer have the ability to sign or decrypt messages using that key.

  • The key didn't have an expiration date, and you've decided not to use it anymore.

  • Any other case where you don't want to use a particular key anymore, and need to try and inform the rest of the world not to use it.

When a revocation certificates is "imported" into a computer's keyring ...

  • Any gpg commands will refuse to encrypt messages to that key.

  • If your keyring has the corresponding secret key, you will still be able to decrypt messages using the key. This includes new messages from others who don't know not to use the key anymore, because they haven't imported the revocation certificate into their keyring yet.

    In this case, you should make it a point to send them a copy of the revocation certificate, so they can import it into their keyring, and their PGP software will know not to use that particular key anymore.

  • Signatures created using the key can still be verified, but the output will report that the key has been revoked, so the user can take this into account in deciding whether or not to trust the signature.

Create ahead of time

Revocation certificates are signed by the primary key of the PGP key they are revoking. However, if you need to revoke a PGP key becuase the secret key is no longer available, you won't be able to create a revocation certificate.

The solution is to create a revocation certificate ahead of time, and not distribute it until you need it.

When you do this, you should store it somewhere that ...

  • You won't lose it. The same Tails USB sticks where you have backups of the secret keys will work for this.

  • Only people that you trust will be able to access them. If you don't trust anybody with the passphrase for your Tails USB sticks' persistent storage, you could copy the revocation certificate to a non-encrypted USB stick, and store it with a family member that you really trust, or in a safety deposit box at a bank, with instructions to share the revocation certificate with the world in case something happens and you're no longer around.

🛑 Do not share revocation certificates unless you MEAN to revoke the key.

Once a revocation certificate has been imported into somebody's keyring (or even worse, sent to a key server) there is no way to "undo the revocation". Your only choice will be to generate a new key pair ... and if your previous key was signed by others, your new key would need to be signed by those others as well.

If a revocation certificate "escapes", that key is done.

Default revocation certificate

Recent versions of GnuPG will generate a revocation certificate and store it under your .gnupg/ directory automatically. For example, I just created a new dummy key (in a Docker container running Debian 11).

root@41ab46aa18b6:~# gpg --quick-generate-key 'Dummy key <please@dont-spam.us>' rsa4096 default 20240101T000000
...
gpg: key 5239E161BB5A6B70 marked as ultimately trusted
gpg: directory '/root/.gnupg/openpgp-revocs.d' created
gpg: revocation certificate stored as '/root/.gnupg/openpgp-revocs.d/F25DB69FA96FBA5BDBB0A96F5239E161BB5A6B70.rev'
public and secret key created and signed.

Note that this key cannot be used for encryption.  You may want to use
the command "--edit-key" to generate a subkey for this purpose.
pub   rsa4096 2023-05-20 [SC] [expires: 2024-01-01]
      F25DB69FA96FBA5BDBB0A96F5239E161BB5A6B70
uid                      Dummy key <please@dont-spam.us>

Note the "gpg: revocation certificate stored as ..." message. This tells you the filename where it stored the revocation certificate.

Contents

If you look at the contents of a revocation certificate, you will see that it explains what the file is and which key it revokes, along with the revocation certificate itself.

root@41ab46aa18b6:~# cat /root/.gnupg/openpgp-revocs.d/F25DB69FA96FBA5BDBB0A96F5239E161BB5A6B70.rev
This is a revocation certificate for the OpenPGP key:

pub   rsa4096 2023-05-20 [SC] [expires: 2024-01-01]
      F25DB69FA96FBA5BDBB0A96F5239E161BB5A6B70
uid          Dummy key <please@dont-spam.us>

A revocation certificate is a kind of "kill switch" to publicly
declare that a key shall not anymore be used.  It is not possible
to retract such a revocation certificate once it has been published.

Use it to revoke this key in case of a compromise or loss of
the secret key.  However, if the secret key is still accessible,
it is better to generate a new revocation certificate and give
a reason for the revocation.  For details see the description of
of the gpg command "--generate-revocation" in the GnuPG manual.

To avoid an accidental use of this file, a colon has been inserted
before the 5 dashes below.  Remove this colon with a text editor
before importing and publishing this revocation certificate.

:-----BEGIN PGP PUBLIC KEY BLOCK-----
Comment: This is a revocation certificate

iQI2BCABCgAgFiEE8l22n6lvulvbsKlvUjnhYbtaa3AFAmRpWbkCHQAACgkQUjnh
Ybtaa3DIGw/+MosNoXYWnbwU/dQ4XxMuBDaLXY5bqipW5W+lcIAZdIvSAyqBIOQA
8Uonv9A0c2wh8S/HYMIVBWebBzFBaaiv1WxokGDLZNfdYLbWIbEcjQgopqijzHNA
MLp4ieqm2iOkphV/A1qOofLqzmqYhUTxrs/5MFnR0GSq6pHUYXbH0LkmUjyyecDb
xoaaAjeBsmqmHivr27CrgHesckTsTvQJE648KKpq+6fMWx1+6/mdQR4sa4arlhm0
ANkAgzMxZiUlrmXyanVaeOzg+WMSjOrDnf1NMAEBA1BAEfoez90Q7ifqb+FrLWuV
P216PclCvepC3zDZobqS5at3cRruw4Td26sWNelVaypQFNIvGBNjH7DX1u4Ehhem
mtwjv7f41lO/mO0j5H47wQ3/jsoFwAG94zE6uH5BfkAbAMSMdzUDYsSk7nGqECd0
f27cdp8DnXbEHkEJqN2Z90F1IMyChF6UxR1bPC22n0xeUgjSlQwuFQyVjLLlUtne
VoK54IVu7GQHYQuLzsof+1AKQwkMnjt5n4LpwG/frxsCjlP1IrYXkz9WJkUwTWHw
slXkCyPEh9cs4cUnzOXUMxkbxGmt2HG+s4MdXwOkKS4IAmNJTBpVZFcvg9frRLFZ
KWg8XvhpnCa5l8GY1cOd6xfQiODZyJ7ng8JG5Zbkg9uzgFNnRLD92I0=
=eO+y
-----END PGP PUBLIC KEY BLOCK-----

As you can see, other than the Comment: line it looks like any other PGP PUBLIC KEY BLOCK. (The Comment: line is actually optional, the flag which makes it a revocation certificate is part of a PGP packet within the blob of text.)

Generate a revocation certificate

If you don't have the default revocation certificate, or if you need to create another one so you can specify a reason, you can use "gpg --gen-revoke".

root@41ab46aa18b6:~# gpg --gen-revoke 5239E161BB5A6B70 > revocation.txt

sec  rsa4096/5239E161BB5A6B70 2023-05-20 Dummy key <please@dont-spam.us>

Create a revocation certificate for this key? (y/N) y
Please select the reason for the revocation:
  0 = No reason specified
  1 = Key has been compromised
  2 = Key is superseded
  3 = Key is no longer used
  Q = Cancel
(Probably you want to select 1 here)
Your decision? 3
Enter an optional description; end it with an empty line:
> Example for documentation
>
Reason for revocation: Key is no longer used
Example for documentation
Is this okay? (y/N) y
ASCII armored output forced.
Revocation certificate created.

Please move it to a medium which you can hide away; if Mallory gets
access to this certificate he can use it to make your key unusable.
It is smart to print this certificate and store it away, just in case
your media become unreadable.  But have some caution:  The print system of
your machine might store the data and make it available to others!
root@41ab46aa18b6:~#

Import a revocation certificate

In order for a revocation certificate to take effect, it needs to be imported into the user's keyring.

Check the file

Revocation certificates are normally generated with an extra colon in front of the "-----BEGIN" line, so that if somebody runs the wrong command they won't import it by accident. If you look at the file, it tells you about this.

...
To avoid an accidental use of this file, a colon has been inserted
before the 5 dashes below.  Remove this colon with a text editor
before importing and publishing this revocation certificate.

:-----BEGIN PGP PUBLIC KEY BLOCK-----
Comment: This is a revocation certificate
...

If the colon is there, open the file with your favourite text editor and remove it. You can also use this sed one-liner to remove it.

$ sed -i -e 's/^://' FILENAME

Import the file

This is just like importing a PGP public key from a file.

$ gpg --import FILENAME
gpg: key 3DEC8A7990B2DDB1: "Revoked key <please@dont-spam.us>" revocation certificate imported
gpg: Total number processed: 1
gpg:    new key revocations: 1
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   2  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 2u
gpg: next trustdb check due at 2024-01-01

Send a revocation certificate

In order for others to be aware that the key has been revoked, you need to send the key to them.

First, a short story.

Once upon a time, there was a network of PGP key servers, called SKS. People around the world were free to upload their keys to these servers, and they were free to search for and download keys from them. Best of all, the key servers were constantly synchronizing with each other, so if you uploaded a key to one server, you could be reasonably sure that every other key server in the world would have a copy of that key within about half an hour. And if somebody stood up a new keyserver and added it to the network, it would also have all of the same keys that the other servers did.

It was really cool, everybody was able to share keys through the keyserver network.

Then some joker discovered that if they add a couple hundred thousand signatures to a key, it would make GnuPG "hang" while trying to process all of the signatures. And in true anklebiter fashion, rather than reporting the bug so it could be fixed, they decided to "poison" a bunch of public keys which were already widely distributed, and upload the signatures into the keyserver network.

After doing this, anybody who received or refreshed these keys from the network, also received these hundreds of thousands of signatures, and their GnuPG software started hanging.

Because there is no way to remove keys (or signatures) from the keyserver network, they had to shut down the entire keyserver network. In addition, anybody who had already imported one of the poisoned keys had to deal with fixing their GnuPG installation (i.e. finding and deleting the keys from their keyring, or deleting their entire keyring and starting over from scratch).

This is why we can't have nice things.

At the moment (2023-05-20), there is a single keyserver online, using keyserver software which doesn't allow hundreds of thousands of signatures. GnuPG 2.4.1 is internally overriding the hostname keys.gnupg.net to point to that keyserver. Their documentation recommends using this as the keyserver. This keyserver works, however I don't like the idea that there's only one keyserver. (I also don't like that it's owned by canonical, but ... that's different discusson.)

There are other keyservers out there.

  • pgp.mit.edu was one of the very first PGP keyservers. I didn't realize until just now that it was still working, the last time I tried it was throwing all kinds of internal errors ... but I just tried it again, and it appears to be working again. It even has a copy of one of my ancient PGP keys (from 1996), even though gpg can't process it anymore.

  • keys.openpgp.org will store and distribute keys, however you have to verify the email addresses in the keys' identities before you can find the keys using that email address.

Configure GnuPG

  • In $HOME/.gnupg/dirmngr.conf

    keyserver hkp://keys.gnupg.net

  • In $HOME/.gnupg/gpg.conf

    keyserver hkp://keys.gnupg.net

    For recent versions of GnuPG, having keyserver in the gpg.conf file is supposed to be deprecated. I have it in both files, things seem to work, and I'm not seeing any warnings or error messages because of it, so for now I plan to keep this line in both files.

Send to keyserver

Make sure the revocation certificate has been imported into your keyring.

root@41ab46aa18b6:~# gpg -k
...
pub   rsa4096 2023-05-20 [SC] [revoked: 2023-05-20]
      781C908E54FF164A5873E7533DEC8A7990B2DDB1
uid           [ revoked] Revoked key <please@dont-spam.us>
...

For a fully-revoked key, you should see [revoked: YYYY-MM-DD] on the pub line, and [revoked] on every uid line. (There is a way to revoke an individual identity or subkey, but it doesn't involve using a revocation certificate.)

Then ...

$ gpg --send-key 781C908E54FF164A5873E7533DEC8A7990B2DDB1
gpg: sending key 3DEC8A7990B2DDB1 to hkp://keyserver.ubuntu.com

Other

Send the revocation file out using whatever other mechanism works. You can email it, you can send it out via chat, you can post it on a web site ... whatever works. Basically, whatever mechanism you used to distribute the key in the first place, do the same thing again with the revocation certificate.

And when you talk to people who have sent you PGP-encrypted emails in the past, be sure to tell them that the key was revoked, and where they can find a copy of the revocation certificate.

ℹī¸ If you're sending the revocation certificate file out, be sure to remove the colon from the "-----BEGIN" line first. That way the people who receive the file won't have to edit the file, they can just import it.