OpenPGP Web Key Directory (WKD) hosting

May 21, 2019    Post   355 words   2 mins read

An OpenPGP Web Key Directory is a method for users to discover the public key of a new contact. The user requests the public key from the contacts an organisation maintains.

Compared to previous key discovery schemes that relied on DNS, WKD can be easily deployed on any HTTPS server because WKD is a lookup scheme that relies on HTTPS and correctly placed files on your web server and no other software is required to run on the web server.

You can use automatic key discovery with WKD to make it easy for users to import your key in GPG since version 2.1.12. There are plenty of email clients that already implemented it, Thunderbird/Enigmail, Outlook with GpgOL, Kmail, and more.

The implementation is really easy.

Create the correct directory structure, making sure you replace <WEB_ROOT_DIR> with the actual path to the root html of your website, on a Debian/Ubuntu default install it’s /var/www/html/

$ mkdir -p <WEB_ROOT_DIR>/.well-known/openpgpkey/hu/

Create an empty policy file in the proper location. It is mandatory.

$ touch <WEB_ROOT_DIR>/.well-known/openpgpkey/policy

Use gpg to find your email address’ hash in WKD format. Replace <EMAIL_ADDRESS> with the email address of the key you want to use. Look for the line that is similar to an email address with a hash in front. For example, mine is kqok36si1ph58anogqf9uhth9om173h8@sizeof.cat. Also note your <KEY_ID>, mine was 0xFAEA6AF5567BE45D.

$ gpg --with-wkd-hash --fingerprint --keyid-format 0xlong <EMAIL_ADDRESS>

Export your public key binary (not ASCII armored) file from the key with the specified id <KEY_ID> and place it as a correctly named file on your web-server. The name of the file (<KEY_HASH>) must be the hash from the previous step, without the @domain part.

$ gpg --no-armor --export 0x<KEY_ID> > <WEB_ROOT_DIR>/.well-known/openpgpkey/hu/<KEY_HASH>

In case you’re using GitHub Pages to deploy your website (and the .well-known directory with it), you will notice the directory doesn’t get copied correctly because of Jekyll so you need to bypass it. Add an empty .nojekyll file to the root of your website (the one with the index.html file, obviously).

You can validate if everything is ok by using this checker.