Web Key Directory

I think everyone had the the moment from time to time when you feel like you have been sleeping under a rock for one year or two, that happened me last night. Web Key Directory was the secret words, which made me to realize that I have been blind or just had so much other things to do the last year.

Share your public key with friends and strangers with ease. This article describe what Web Key Directory is for GnuPG.

Clients and e-mail providers are listed at GnuPG WKD had added support for Web Key Directory also known as WKD. GnuPG which is an implementation of OpenPGP which is a system for signing or encrypting messages, documents and files. Authentication to login on different systems with your keys.


There is two different encryption models on how you can unlock an encryption; Symmetric and Asymmetric which have its own applications and can also be combined for different actions.

In simple words Symmetric is when both sender and receiver must have the same key to encrypt and decrypt a message and everyone which get their hands on this shared key will also be able to read the messages.

Asymmetric is harder to understand how it works because the sender does not need to share any secret key to the receiver, the only thing she needs is a public key from the receiver which is not enough to decrypt any message, but it is well enough to encrypt with if the sender have its own private key which he will never share with anyone.

This means that every time you want to encrypt a message with some one new, you need to ask for the public key. To make it easier there exists some dictionaries like the old fashion yellow pages but digital OpenPGP keyserver, where people can chose to publish their contact information together with a public key. For many years the servers have been useful, but about a year ago some one decided to exploit a known vulnerability which made some of these key servers to crash. This have become a very critical infrastructure for many opensource projects who kept their public keys there to let users of their software verify that the software they are about to install is really released from the correct team.

So one of the solution of this is Web Key Directory which is a super simple way of how to distribute the centralization on not just one central point of failure but on every possible domain which is connected to an e-mail. It uses traditional http with SSL (https) and a folder structure with your public key stored in a file. The URL for reaching your public key will be like bellow.

example.com/.well-known/openpgpkey/hu/<hash e-mail prefix>
│           │          │          │   │
│           │          │          │   └ sha1 + z-Base-32 
│           │          │          └ Human use folder
│           │          └ openpgpkey folder, RFC Draft (1) 
│           └ RFC8615 Well-known folder for metadata
└ Domain name same as your e-mail

(1): https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-08

if you cannot use your primary naked domain record create a subdomain named openpgpkey and point it to a http server which can handle SSL and keep your .well-known folder safe. Se bellow how the URL shall look like.

openpgpkey.example.org/.well-known/example.org/openpgpkey/hu/<hash e-mail prefix>

Files needed in the root of your web server for the domain

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

3 directories, 2 files

the policy file is for clients to check for Web Key Directory support. It is also used for different policy flags, as default this needs to be an empty file.

How to

To list your keys

gpg --list-keys --with-wkd

pub   rsa4096/0xFB12FB1BCB8D0713 2019-09-26 [SC]
      Key fingerprint = 9D1A 01CF C4C2 5B90 DA81  55D8 FB12 FB1B CB8D 0713
uid                   [ultimate] hello <hello@example.com>
sub   rsa4096/0x002C57D3FC48ABFB 2019-09-26 [E]

in this example the sha1 + z-Base-32 hash of hello is im4cc8qhazwkfsi65a8us1bc5gzk1o4p which will be the name of the file you place on your web server.

Export your public key where im4cc8qhazwkfsi65a8us1bc5gzk1o4p is the sha1 + z-Base-32 of your e-mail prefix, execute following command.

gpg --output\

Copy the file to the .well-known folder on your webserver place it under openpgpkey/hu

test your configuration

For downloading public keys with Web Key Directory
gpg --auto-key-locate clear,nodefault,wkd --locate-keys hello@example.com