GnuPG Web Key Service

Web Key Directory (WKD) and Web Key Service (WKS) provide easier ways to discover OpenPGP public keys through HTTPS. They improve the user experience for exchanging secure emails and files.

In contrast to the public keyservers a WKD or WKS do not publish mail addresses. And they are authoritative public key sources for its domain.

In this document we set up a Web Key Service (WKS).


  1. GnuPG version 2.1.15 or later (Ubuntu 18.04 LTS bionic comes with GnuPG 2.2.4).

  2. Working Mail Servers installation.

  3. Working Web Server installation.

System Service User

Create a system user who will own the directories and files and run the Web Key Service programs:

$ sudo adduser --system --group --home /var/lib/webkey webkey

Directories and Domains

The Web Key Service requires a working directory to store keys pending for publication. As root create a working directory:

$ mkdir -p /var/lib/gnupg/wks
$ chown webkey:webkey /var/lib/gnupg/wks
$ chmod 2750 /var/lib/gnupg/wks

Then under your webkey account create directories for all your domains. Here we do it for “”, “” and “”:

$ mkdir -p /var/lib/gnupg/wks/{}


Apparently the location of the service working directory is hard-coded and can’t be changed.

The WKS command --list-domains can then take care of creating required subdirectories and setting appropriate permissions:

$ gpg-wks-server --list-domains

Submission Mail Address

The WKS clients (users mail clients), interact with the service by email. If a new key has to be submitted, the client looks up the mail address of the submission service at a well-known URL under the users domain domain.

The submission address is expected to be a downloadable text file with only one line containing the mail address where new keys can be submitted.

To create these downloadable files:

$ cd /var/lib/gnupg/wks/
$ echo '' >
$ echo '' >
$ echo '' >

The mail server need to forward all incoming mails on these addresses, to the webkey mail account.

This is done in the MTA - Mail Transfer Server configuration trough alias addresses.

# ----------------------------------------
# Alias Addresses Mapping
# Postfix version 3.4.13
# ----------------------------------------
# The aliases(5) table provides a system-wide mechanism to redirect mail for
# local recipients. The redirections are processed by the Postfix local(8)
# delivery agent.
# An alias definition has the form
#     name: value1, value2, ...
# The name is a local address (no domain part). when an alias exists for
# owner-name, this will override the envelope sender address, so that
# delivery diagnostics are directed to owner-name.
# The value contains one or more of the following:
#     address             - Mail is forwarded to to a RFC 822 standard addres.
#     /file/name          - Mail is appended to /file/name.
#     |command            - Mail is piped into command.
#     :include:/file/name - Mail is sent to destinations listed in the file.
# Run the following after changing this file:
#   $ cd /etc/postfix && sudo make"


# -*- mode: txt; indent-tabs-mode: nil; tab-width: 4; -*-

The contents of the file are cached in the database /etc/postfix/aliases.db. Because of that the database must be refreshed after each and every change made in /etc/postfix/

$ cd /etc/postfix
$ sudo make

Submission Keys

Mails sent to the service should be encrypted. The Submission mail addresses therefore need OpenPGP keys.

These keys are not passphrase-protected, as the will be used by an automated service.

They should be created as the webkey user:

$ sudo -H -u webkey \
    gpg --batch --passphrase '' --quick-gen-key
$ sudo -H -u webkey \
    gpg --batch --passphrase '' --quick-gen-key
$ sudo -H -u webkey \
    gpg --batch --passphrase '' --quick-gen-key

These keys will be the first to be published by our WKS. In WKS keys are identified by a hash, so no mail addresses or key IDs are transferred between WKS client and servers.

To create these hashes from a key uid, gpg provides the --with-wkd-hash parameter:

$ sudo -H -u webkey \
    gpg --with-wkd-hash -K
sec   rsa2048 2020-06-28 [SC]
uid           [ultimate]
ssb   rsa2048 2020-06-28 [E]

Take the hash of the string “key-submission”, which is 54f6ry7x1qqtpor16txw5gdmdbbh6a73 and manually publish that key:

$ sudo -H -u webkey \
    gpg -o /var/lib/gnupg/wks/ \
        --export-options export-minimal --export
$ sudo chmod +r /var/lib/gnupg/wks/

Make sure that the created file is world readable.