== Hosting a Web Key Directory (without dynamic service) ==
Ideally a Web Key Directory will be created and maintained through a [[WKS|web service]], but organizations or individuals may want to just host a WKD without a service, instead relying on a flat file structure which must be recreated whenever a public key changes.

=== How-tos ===
**[[WKS|Using GnuPG's included gpg-wks-server executable to provide a dynamic Web Key Service]]**

* [[https://github.com/PennockTech/openpgpkey-control|Hosting with website content management]] ([[https://lists.gnupg.org/pipermail/gnupg-devel/2020-January/034501.html|Introduction by Phil Pennock]], written 2020-01-12)
* [[https://www.kuketz-blog.de/gnupg-web-key-directory-wkd-einrichten/|GnuPG Web Key Directory Setup]] by Mike Kuketz (in German, written 2019-09-11)
* [[https://lab.uberspace.de/guide_wkd.html|Hosting a Web Key Directory]] – for ~UberLab users (last updated 2021-08-03)
* [[https://florian.latzel.io/gnupg-micro-howto.html#web-key-directory-wkd|GnuPG Micro Howto § Web Key Directory Setup]] by Florian Latzel (in German, last updated 2025-07-20)
* [[https://encrypted.tesio.it/2025/11/16/crittografia-end-to-end-chiavi-pgp-via-web-key-directory-wkd.html|End-to-End Encryption: PGP keys via WKD]] by Giacomo Tesio (in Italian, written 2025-11-16)

==== Using other keyserver software ====
* [[https://github.com/mailvelope/keyserver|Mailvelope Keyserver]] can act as a Web Key Directory host with a [[https://github.com/mailvelope/keyserver/pull/147/commits/c25ae59160f3a9cd10edfb7ff5a672179c5f9998|small patch]] and a [[https://github.com/mailvelope/keyserver/blob/72bf97b856eba9e2e70e87b8471b599cdad46525/README.md#web-key-directory-support|reverse proxy]], like [[https://caddyserver.com/|Caddy]].

== Requirements ==
* A web server that provides https with a trusted certificate.

=== Test ===
After setting it up the following should work with your email address (on a GNU/Linux system
with GnuPG installed ). It does not import your pubkey.
{{{
   gpg --homedir "$(mktemp -d)" --verbose --locate-keys your.email@example.org
}}}
\\

An alternative test with extra output is:
{{{
gpg-wks-client --check -v --debug=ipc your.email@example.org
}}}

=== Using gpg-wks-client from GnuPG (since v2.2.12) ===
Gnu~PG [[https://dev.gnupg.org/T4289|2.2.12]] has an improved {{{gpg-wks-client}}} tool which can be used to create a local file under the subdir openpgpkey, which has to be created.

It takes the (public) keys from the GnuPG keyring, so the keys need to be known to GnuPG.
{{{
PATTERN="@example.org"
gpg --list-options show-only-fpr-mbox  -k $PATTERN | gpg-wks-client -v --install-key
}}}
(//Note for windows 10 - ~PowerShell: You may require path names to the binary, e.g. {{{'C:\Program Files(x86)\GnuPG\bin\gpg-wks-client.exe'}}}//)

Details:
* The gnupg keyring is searched for all public keys (-k) matching the defined pattern, the output is generated as {{{fingerprint user_id}}} values (show-only-fpr-mbox).
* WKD will be only useful for keys of the domain serving the directory. If you specify other patterns (e.g. "jane.Doe@example.org"), all keys matching that pattern will be considered for the update (which will be useless in the case of domains you do not serve, but useful if you only want to update a subset of keys).
* This listing will then be piped to gpg-wks-client, which will create the appropiate folder structure and entries for each result.
* the output will be written to the openpgpkey folder (or any folder you specify with the {{{-C}}} option). See [[WKDHosting#Publishing|publishing]] for the final placements and additional adaptions.

=== Method with older GnuPG version
Use the [[https://hg.intevation.de/gnupg/wkd-tools/raw-file/default/generate-openpgpkey-hu|generate-openpgpkey-hu]] script in the [[https://hg.intevation.de/gnupg/wkd-tools/|wkd-tools]] Mercurial repository; this implementation uses Python 2 and either the [[https://pypi.org/project/python-gnupg/|python-gnupg]] or [[https://pyme.sourceforge.net|PyMe]] modules.

There is an [[https://gitlab.com/Martin_/generate-openpgpkey-hu-3/|alternative implementation]] using Python 3 and python-gnupg available on GitLab.

==== Usage
You can either export all the keys in your keyring which belong to a domain or provide an explicit keyring containing the keys you want to publish.

The call:
{{{
    ./generate-openpgpkey-hu example.com hu
}}}

Will create a directory called hu containing all the keys with @example.com mail addresses.

If there are multiple valid keys for a user in your keyring this command will error out. In that case you can prepare a keyring with only the keys you want to publish, e.g.:
{{{
    gpg --export 94A5C9A03C2FE5CA3B095D8E1FDF723CF462B6B1 | \
    gpg --no-default-keyring --keyring ./wkd-keyring.gpg --import
}}}

And then provide that keyring to generate-openpgpkey-hu:
{{{
    ./generate-openpgpkey-hu example.com hu wkd-keyring.gpg
}}}

=== Publishing
The hu directory has to be published on your server as
{{{https://openpgpkey.example.com/.well-known/openpgpkey/example.com/hu/}}} (or {{{https://example.com/.well-known/openpgpkey/hu/}}} if {{{openpgpkey.example.com}}} is not resolvable via DNS).

On your server create the according directory and set the permissions according to your system.
**Make sure that there is no automatic directory listing for {{{.well-known/openpgpkey/example.com/hu/}}} (or {{{.well-known/openpgpkey/hu}}} if using the fallback "direct" URL scheme).**

Starting with draft 05 the
[[https://datatracker.ietf.org/doc/html/draft-koch-openpgp-webkey-service|OpenPGP Web Key Directory specification]] requires that a policy file {{{https://openpgpkey.example.com/.well-known/openpgpkey/example.com/policy}}} (or {{{https://example.com/.well-known/openpgpkey/policy}}} if using the "direct" URL scheme) is available. It can be an empty file, which fits well here, because it is only relevant for the update protocol anyway.

A free [[https://www.webkeydirectory.com/|WKD Checker web service]] can verify the functionality of the WKD.

This example [[https://hg.intevation.de/gnupg/wkd-tools/raw-file/default/Makefile.example|Makefile]] automates the hu directory generation and publishing (using the python script for the older gnupg version method as documented above). Edit
the variables at the top of the makefile to your {{{RSYNC_TARGET}}}
The {{{KEYRING}}} variable is optional and can be empty.