Setting up OpenPGP Web Key Directory (WKD)

Suppose you value privacy and use OpenPGP to secure your email communication and have a secure web server running on the same domain. In that case, you might consider publishing your public key through Web Key Directory. This allows supporting email clients to automatically retrieve your public key using the HTTPS protocol.

How does it work?

When a sender uses a supporting mail client and adds an email address to a message, the client will automatically check whether WKD is set up for the domain name of the receiver. If a public key is found, it is directly imported to the keyring, allowing secure communication.

Advanced vs. Direct

There are two ways to implement WKD. The first is the advanced method, which is harder to set up and requires a CA-signed and trusted certificate for the openpgpkey sub-domain. The direct method requires no additional DNS entries, but you have to ensure that the openpgpkey sub-domain does not exist and is not subject to wildcarding. If you use a wildcard for the domain, you need to insert an empty TXT RR for the openpgpkey sub-domain.

For the advanced implementation, create the following folder inside your webroot folder for sub-domain openpgpkey.example.org:

/.well-known/openpgpkey/example.org/hu/

If you're going to implement the direct method, create the following folder inside your webroot folder:

/.well-known/openpgpkey/hu/

After you've created the folder, add an empty policy file to let clients know that you've set up the WKD service. Then, put the file in the "/hu/"-parent folder and check that you can access the empty file with your browser.

Advanced:
https://openpgpkey.example.org/.well-known/openpgpkey/example.org/policy

Direct:
https://example.org/.well-known/openpgpkey/policy

If the link above works, we need to make a few adjustments to the webserver setup before adding the public keys to the "/hu/" folder.

Nginx

location /.well-known/openpgpkey/hu/ {
    default_type        "application/octet-stream";
    add_header          Access-Control-Allow-Origin * always;
}

Apache (config)

<Directory "/.well-known/openpgpkey/hu">
    <IfModule mod_mime.c>
        ForceType application/octet-stream
    </IfModule>
    <IfModule mod_headers.c>
        Header always set Access-Control-Allow-Origin "*"
    </IfModule>
</Directory>

Apache (.htaccess in /hu/ folder)

<IfModule mod_mime.c>
    ForceType application/octet-stream
</IfModule>
<IfModule mod_headers.c>
    Header always set Access-Control-Allow-Origin "*"
</IfModule>

All that's left to do now is figure out the hash of the local part of your email address and save a binary (not ASCII armored) version of your public key under that name in the "/hu/" folder.

Local-part hash as the filename

The public key lookup is done using a calculated fixed-sized string of the local part of the email address (the part before the @ symbol). By hashing it using an SHA-1 algorithm and then encoding the result using a Z-Base-32 method, you are left with 32 octets that should be used as the filename for your key. Calculating this string sounds complicated, but fortunately, we can use the gpg (GnuPG v2.1.12 or newer) command below :

gpg --with-wkd-hash -k yourmail@example.org

The 32 characters outlined in the image above are the filename we want to save the public key to using the following command:

gpg --export yourmail@example.org > hacabazoakmnagxwmkjerb9yehuwehbm

Move the created file to the "/hu/" folder and check whether the file is downloadable using the links below:

Advanced:
https://openpgpkey.example.org/.well-known/openpgpkey/example.org/hu/hacabazoakmnagxwmkjerb9yehuwehbm

Direct:
https://example.org/.well-known/openpgpkey/policy/hu/hacabazoakmnagxwmkjerb9yehuwehbm

Done!

Once the file is saved and accessible, you are all set! Test whether the configuration works by using a WKD validator like this one: https://metacode.biz/openpgp/web-key-directory

Congratulations! As more and more mail clients and mail service providers are adopting WKD, you'll automatically receive more encrypted messages from new communication partners without off-channel key exchange or the need for them to search the network of public key servers.

Email security

While you're taking your email configuration to the next level, have you configured MTA-STS, DANE, SPF, DKIM, and DMARC yet? You'll find more on the subject of email security here in my blog.