WKD documentation (Re: Testing WKD setup?)
johannes at zarl-zierl.at
Tue Jul 9 23:33:19 CEST 2019
On Dienstag, 9. Juli 2019 15:02:26 CEST Bernhard Reiter wrote:
> please make suggestions (or help with improving)
I think the problem with that page is that it is handed out as a starting
point to users asking "how can I enable WKD for my key?". To give credit, the
page does give a decent explanation of the concepts of WKD:
What is a Web Key Directory?
How does it work?
These two sections are a good start.
What does it mean for users?
Here I got sidelined a little: Basically, everything's nice for users and we
don't need to do anything, I guess? I think the example video shows that you
can just write an email and the mail client encrypted it to the recipient.
Having subtitles (or a narrator) would probably make the intent of the video
For me as a user, it would also be nice to know if WKD "just happens"
automatically, or if I need to enable it, or give it precedence over my
configured default keyserver...
How to set it up?
This section is "lots" of text with the important info hidden behind a link. I
say "lots" even though it's hardly a paragraph, because it's roughly a whole
line with boilerplate text and the link is a single word. Just putting "See:
WKDHosting" without the paragraph would be better.
Maybe a bullet-list could do the job:
- Simple deployment (just a webserver): WKDHosting
- Deployment with automated updates (recommended for organizations): WKS
Web Key Directory (WKD) / Web Key Service (WKS) what is the difference?
This is literally a list of differences - why not make it a list?
(Nothing wrong with those two sections).
> Note that on Wiktor's page a few details are missing:
> * policy file is needed
> * directory listing strongly recommend to be off
> * minimum version of gpg that has --with-wkd (some versions don't).
Wiktor's page gave me enough of a starting point so that I could figure out
the missing details. Actually, just entering my email into the form and then
working to fix every complaint until it works wasn't too bad a user experience
> BTW, last week we've updated
> with a how to use gpg-wks-client on Gnu and Windows systems
> to create a flat file structure.
That's definitely an improvement - previously, I only took passing note of the
page, noting that there has to be an easier way than "download some code from
mercurial somewhere, install python prerequisites, create specially crafted
keyring, and then it's just a one-liner to create the WKD.
Now that I have done it once, I think the setup without /usr/lib/gnupg/gpg-
wks-client isn't that complicated either:
1. Create directory structure: mkdir -p .well-known/openpgp/hu
2. Create policy file: touch .well-known/openpgp/policy
(explaining valid policies and why one would want one)
3. Identify your key hash: gpg --list-secret-keys --with-wkd $KEYID
-> Make sure to omit the domain part starting with "@"
4. Export your key to the right place:
gpg --export-options export-clean --export $KEYID > .well-known/openpgp/hu/
(I'm not sure about the export-clean - it just seemed like a reasonable
1. Turn off directory listing for .well-known/openpgp unless you really want
2. Enable those header things that are mentioned in the wkd checker
(explain the rationale behind this)
a. using Wiktors web wkd-checker, which also checks best-practice
b. Manually, using gpg: gpg --homedir "$(mktemp -d)" --locate-keys $KEYID
I hope this helps a little,
P.S.: Now that I've read up on the other mails it seems that it is also
possible to host the WKD on a subdomain - I guess this could also need some
documentation (describe the lookup-procedure on the WKD page under "How it
works"; describe the differences in setup on WKDHosting)
More information about the Gnupg-users