Brief

Today I’ll show you how to set up PGP WKD (Web Key Discovery), to easily distribute your public key, so that anyone who has your email address will be able to get your public key (in some cases automatically) while being reasonably sure that it’s the real key.

Requirements

  • E-Mail address with either:
    • Provider that supports WKD, or
    • running on your own domain.
  • If running on your own domain, a HTTPS server on that domain which you can upload files to.

Without WKD

Sure, there are PGP key servers, but those have many downsides, like no verification, not being able to delete your keys, and being overall a privacy nightmare, but also being attackable.

You could attach your public key to every outgoing email by default, but for people that don’t use PGP, this causes confusion. And for people that do use PGP, there’s no way to easily verify an attached key.

With WKD

With WKD, you essentially place your public key on an HTTPS server running with the same domain as your email domain, based on a standardized path.

This way, any client that supports WKD, can automatically pull the key from the server, and since it’s running on the same domain, you can be reasonably sure it’s the correct key.

Of course, this does not replace full verification in person or over the phone, but it’s “good enough” for most.

If you’re not using your own domain, you need to check with your email hoster if they offer WKD hosting, but if you’re using your own domain, proceed with this guide.

Basic Server Setup

Let’s say your email address is [email protected], you’d have to run a web server (HTTPS) that listens on example.com, where you will place the public key.

Let’s say your web server has its root at /var/www/html (that’s just the default on many systems, we’ll use this as example) so that example.com points to /var/www/html.

First, we create the required directory structure:

mkdir -p /var/www/html/.well-known/openpgpkey/hu

Tip: If you’re using a GUI with SFTP/SCP/FTPS, you can also right click and choose to create a new directory, to create them manually.

Fun fact: .well-known is a well-known directory, used for many HTTP things, including Let’s Encrypt verification, so you might already have it on your server!

Fun fact: The directory is named “hu” which stands for “hashed-userid”.

Then we create the “policy” file (it’s just an empty file), which allows your PGP client to check if WKD is offered at that host in general:

touch /var/www/html/.well-known/openpgpkey/policy

To test that this worked out, you can then point your web-browser, in our example, to https://example.com/.well-known/openpgpkey/policy which should just open an empty site.

Got an empty site, no errors? Great! Let’s proceed.

Exporting your key

Now we need to list your key, but with the WKD hash. You see, the username part of the email will be hashed for privacy reasons, so one needs to have your email address to get the key, but not the other way around. Let’s list your email with:

gpg --with-wkd-hash -k

Now you should see the email address [email protected] and underneath again, but with a weird hash in front of @example.com, copy that hash!

Now let’s export your public key:

gpg --no-armor --export [email protected] > YourHash

We specifically said --no-armor because we want the key in binary format (not ASCII).

You should now have a file with the hash as file name, and no extension.

Uploading your key

Now that we have a file with the hash as name (make sure no extension!), we are ready to upload it to the web server.

Simply take that file we just created, and upload it to your web host at /var/www/html/.well-known/openpgpkey/hu like you usually would, of course adjust the path.

You can do this through your web hoster’s web interface if you’re using one, otherwise through SCP/SFTP/FTPS or whichever method you prefer.

Example with scp:

scp YourHash user@server:/var/www/html/.well-known/openpgpkey/hu/.

And in the end you should have the file:

/var/www/html/.well-known/openpgpkey/hu/YourHash

And you should be able to access it through your browser at https://example.com/.well-known/openpgpkey/hu/YourHash too!

Congratulations! You now have a pool for all your PGP keys on that domain, and you uploaded your first key! Now, anyone with a supported client, will automatically fetch your key.

To upload more keys, repeat the exporting and uploading steps.

Fetching keys

Now any client that supports WKD and has it enabled, should fetch your key, but we can also do this manually from the GPG command line with:

gpg --auto-key-locate clear,wkd,nodefault --locate-key [email protected]

This command will forcefully fetch the key, even if it’s already in the keychain!

Final notes

As you can see, if you already use your very own domain that you’re using for email, and have a web server running, setting up WKD is incredibly easy: Just create a directory structure, then a policy file, and finally export and upload your key. However, writing this guide is not as quick as setting up WKD. If this helped you out, feel free to use one of the donation buttons on the top right (or bottom if on mobile) to keep the blog running. ;D

That’s all there is to it!