WKD documentation (Re: Testing WKD setup?)

[Johannes Zarl-Zierl]

Hi,

On Dienstag, 9. Juli 2019 15:02:26 CEST Bernhard Reiter wrote:
> please make suggestions (or help with improving)
> https://wiki.gnupg.org/WKD

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 
clearer.

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?

    Technical Details
    Implementations

(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
>   https://wiki.gnupg.org/WKDHosting
> 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:

Basic steps:
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/
$WKD_HASH
   (I'm not sure about the export-clean - it just seemed like a reasonable 
default.)

Webserver configuration:
1. Turn off directory listing for .well-known/openpgp unless you really want 
this
2. Enable those header things that are mentioned in the wkd checker
   (explain the rationale behind this)

Testing:
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,
  Johannes

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)