The Using GPG Guide (UGG)

This page is about setting up and using GPG. It's a bit like an alternate manual. GPG is actually GnuPG, a complete and free implementation of the OpenPGP standard as defined by RFC 4880 (also known as PGP). My problem has always been putting it all together, and to explain how to use it. Hopefully this page will help you do just that.

GPG

RFC 4880

This page is for people who are able and willing to use the command line. The problem with explaining how to exchange encrypted messages is that it varies from tool to tool. The command line is the same everywhere. It may be hard to use, but the benefit is that all the various steps can be explained easily in text. This is also why so many git problems are answered with command line invocations of git itself. It's the common denominator. Using gpg directly, on the command line, has the same goal: it's the common denominator, and it's easy to explain in text.

**Table of Contents**

Getting a secret key for GPG

Troubleshooting

Exchanging public keys with partners

Troubleshooting

Encrypting a file

Troubleshooting

Keyservers

Troubleshooting

Changing the Expiry Date

Troubleshooting

Switching keys

Setup WKD

Using a Revocation Certificate

Troubleshooting

Getting a secret key for GPG

We'll generate a new secret key using GPG. A secret key is like your identity. You need to keep it safe. Every secret key comes with a public key. This is what other people will need to send you email. You'll have to get it to them somehow. In return you will get the public keys of your partners. Both secret and public keys are stored in keyrings in your home directory.

Here's what an initial run of gpg looks like:

The “~/.gnupg” directory is where all the files are kept. The “pubring.kbx” file is where the keys are kept. This is the important one. You should backup this file.

Let's create our secret key using `gpg --generate-key`.

Here's what you want to answer:

1. a name

2. an email address

3. a passphrase

A *passphrase* is like a very long password. Use a good one and don't forget it. All your other passwords will end up being protected by this one passphrase.

Here's what the entire process looks like:

The output here lists your fingerprint. You can reprint this using the command `gpg --fingerprint` and an email address. Over the years you might create more and more keys like that so the list gets longer and longer. Watch out for the expired keys!

I like to expire my keys. This simplifies things because I don't have to worry about revocation certificates and all that. If I forget about the key, it’ll be unusable after a few years anyway.

Also note that the message told you about a revocation certificate it created. If you keep it somewhere safe, you'll be able to tell other people that your key got compromised and that it shouldn't be used anymore, in a cryptographically secure manner. This assumes that your enemies might be trying to spoof your friends, telling them that you switched keys when in fact you haven't. The revocation certificate is how you tell them you *are* switching keys!

Usually, you don't have to do that. Instead, you'll *extend* your key, moving the expiration day up a year or two. See below for more about that.

More email addresses

Use `gpg --edit-key FINGERPRINT` to edit the new key and add new email addresses.

A new email address is called a user id (uid), so the command to use to edit the key is `adduid`.

Use multiple `adduid` commands to add more email addresses. Surprisingly, `save` ends editing, much like a text adventure.

This is also where you set the key to "ultimate trust":

Pick one of the user ids as your primary:

Troubleshooting

What if you get “gpg: agent_genkey failed: Permission denied” as you’re trying to generate the key? The problem might be that you switched user accounts inside your terminal. The problem is that gpg is trying to prevent the old account from snooping. Here’s an example where I switch from the “alex” account to the “guest” account:

Here’s how I can show that indeed the terminal belongs to “alex”:

The solution is to use `tmux`:

And now `gpg --generate-key` should work as expected.

Exchanging public keys with partners

This is what we would send our partners:

Let’s export it to a file:

When contacting somebody for the first time, you probably want to attach this file, or just paste it into the email. They would save the attachment, or copy and paste this block into a file called `alex.pub` and import it. Here, I got a public key from a friend and imported it.

If you meet your partners face to face, giving them a copy of your public key is easy. If you never met, it's harder. How do you make sure that criminals didn't interfere? This is called a man-in-the-middle attack. You could make it harder by publishing your fingerprint on various channels. Attackers would have to replace these fingerprints everywhere. It's not perfect, but it's much better than nothing.

man-in-the-middle attack

The fingerprint is right here: `ABEF 08C3 4DB4 DB8A 73EB BBB8 AE49 5BC6 3253 DDE8`. Put it on your web page, in your email signatures, tweet it, and so on.

Since we just got a key, we should do the same, of course:

Perhaps he sent us the fingerprint via Signal, Threema, phone call, website, etc. It’s just good form to verify it using some other channel.

Troubleshooting

Todo

Encrypting a file

Let's encrypt a file before we get started. Create a text file using your favourite editor and save it as `message.txt`. Let’s encrypt it:

Now, you'll have an encrypted file called `message.txt.gpg` next to the unencrypted `message.txt` file and both you and Roland can decrypt it. Note that if you didn't add yourself to the recipients, not even you can read your message!

Don't name your file for the things you're talking about or you'll be giving away important information.

Troubleshooting

You are trying to encrypt a file and gpg tells you that you have an “unusable key”… Now what?

The problem is that you have a key in your keyring, but it is unusable for what you’re trying to do, which is encrypting a file. So how do we verify this? Here’s what my keys look like, after a few years:

If you see the expiry date approaching for your own key, you should change its expiry date. See below for more.

If you want to encrypt a file for somebody and all you have is revoked and expired keys, then you have to check whether there are updated keys available from the keyservers. See below for more.

If the intended recipient doesn’t use keyservers, you need to let them know some other way… Tricky!

Keyservers

Send the key to your default keyserver:

If you're using `keys.openpgp.org` as your key server, you need to upload the key via their web site when you're uploading it for the first time.

Export the key to a file:

Upload this file and confirm the email addresses you want to make public.

Upload

Once you have done that, you can send them the key like you usually would. Or use the keyserver explicitly:

Keyoxide

To link your key with social media, software forges and the like, you can add special notes tools can verify. Keyoxide is one of them.

Keyoxide

Here's an exampe using GitHub.

1. sign in

2. create a Gist linking to your Keyoxide profile

3. add a notation to your GPG key linking to the Gist (see below)

4. send your key to the keyserver

This is how you add the key. Note that I select my uid before adding the notation. If I don't do this, the notation is added to all of them.

If you added the notation to the wrong uid, select the uids where you want to delete the notation, use the `notation` command and answer `none`.

Upload to keyservers as before.

keyservers

Now, when you visit the Keyoxide profile, you'll see a check next to the GitHub account.

Keyoxide profile

Other people can now be sure that the public key they're getting is the one the GitHub user used, even if they can't confirm the user's legal name.

Changing the Expiry Date

Eventually, you’ll want to change the expiry date of your key. Here’s how to extend it by two years.

Alternatively:

Troubleshooting

Again, if you’re getting “gpg: agent_genkey failed: Permission denied” then your terminal belongs to a different user (most likely because you switched users using `sudo su`) and if you’re sure this is correct, you can run `tmux` and continue inside the tmux environment to work around that.

Switching keys

What if you don't want to extend the key? Let the old one expire, no harm done.

Create a new key pair using `gpg --generate-key` (or `gpg --full-generate-key`).

Upload to keyservers as before.

keyservers

Setup WKD

If you own your email domain, tools can fetch your key for their users so they can send you encrypted mail without using keyservers. They do this using the conventions of a Web Key Directory (WKD).

On your server, in your (virtual) web server's document root, create the directory `.well-known/openpgpkey/hu/`. This is where a copy of your key is made available using your hashed email address. The email address is hashed so that web scrapers listing `https://example.org/.well-known/openpgpkey/hu/` don't immediately know what email addresses they can mail.

Determine the filename to use with `gpg`:

The hash is `cddpr77ezsy7h967hgjydxhhmnt76n8w`.

Export the key:

Upload it and put it into the directory you created.

The goal is that `https://alexschroeder.ch/.well-known/openpgpkey/hu/cddpr77ezsy7h967hgjydxhhmnt76n8w` downloads my public key.

Using a Revocation Certificate

Todo

Troubleshooting

Todo