Setting up OpenPGP Web Key Directory (WKD)

Sunday, February 5, 2023


Quick note on OpenPGP Web Key Directory (WKD). The GnuPG wiki states:

A Web Key Directory (WKD) provides an easy way to provide and get the current public key for a given email address through HTTPS. Thus it is infrastructure to improve the user experience for exchanging secure emails and files. –

It basically means it becomes simple to manage your gpg key yourself on your own server. So people can easily add your gpg key with one command: gpg --locate-keys email@domain.tld. They key will be automatically found.

For this to work, there are 2 solutions:

  • Implementing a Web Key Service (WKS): Allow to manage multiple keys for the same domain
  • Hosting a Web Key Directory (WKD): Manage a simple flat structure files “manually” to manage keys of the domain

In this post, I’m setting up Web Key Directory (WKD), not Web Key Service (WKS). WKS is a more advanced configuration that is usefull in case you want to manage many domains and/or many email addresses. In my use case, for the domain I only manage 1 email address (bac@). In this case, setting up WKD is way easier and faster.

The documentation says:

The Web Key Directory is the HTTPS directory from which keys can be fetched. The Web Key Service is a tool / protocol to automatically publish and update keys in the Web Key Directory. It is optional to reduce the administrative effort of a Web Key Directory. –

To setup WKD, the documentation indicates:

The hu directory has to be published on your server as (or if is not resolvable via DNS).

So I decided to use the non subdomain option ( for extra simplicity.

Following the gnupg wiki for installing WKD, as my gpg version is newer than 2.2.12, I can use the gpg-wks-client command to help:

mkdir /path/to/domain.tld/.well-known/opengpgkey && cd /path/to/domain.tld/ # Creating our working directory
chmod o-rw .well-known/openpgpkey # Set the right permission, otherwise the gpg-wks-client command will fail
gpg --list-options show-only-fpr-mbox -k mail@domain.tld | gpg-wks-client -v --install-key


gpg-wks-server: gpg: Quantité totale traitée : 1
gpg-wks-server: using key with user id 'User <mail@domain.tld>'
gpg-wks-server: gpg: Quantité totale traitée : 1
gpg-wks-server: directory '.well-known/openpgpkey/domain.tld' created
gpg-wks-server: directory '.well-known/openpgpkey/domain.tld/hu' created
gpg-wks-server: policy file '.well-known/openpgpkey/domain.tld/policy' created
gpg-wks-server: key XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX published for 'mail@domain.tld'
└── .well-known
    └── openpgpkey
        └── domain.tld
            ├── hu
            │   └── yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
            └── policy

Because I’m using the solution without the openpgpkey subdomain, it means that the tree is incorrect. I shouldn’t have domain.tld directory within openpgpkey but directly the hu directory. Let’s move things around:

cd .well-known/openpgpkey
mv domain.tld/* ./
rmdir domain.tld

Now, the tree is:

└── .well-known
    └── openpgpkey
        ├── hu
        │   └── yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
        └── policy

Now I just need to scp the .well-known directory to the web server.

For the root of the directory, as I’m not using this domain for an actual site, I just created a basic html file that redirects to my main site

<!DOCTYPE html>
    <meta http-equiv="refresh" content="3; url=''" />
    <p>Nothing here, please go to <a href="">my blog</a>.</p>

And voilà, this should normally allow anyone to use gpg --locate-key with my email bac -at-


If you find any issue or have any question about this article, feel free to reach out to me via email, mastodon, matrix or even IRC, see the About Me page for details.

New laptop part 4: Dracula theme

Headless installation of RaspberryPiOS