Mailing List Archive

WKD documentation (Re: Testing WKD setup?)
Hi,

Am Sonntag 07 Juli 2019 22:37:00 schrieb Johannes Zarl-Zierl:
> On Sonntag, 7. Juli 2019 20:48:12 CEST Wolfgang Traylor via Gnupg-users
wrote:
> > > is there a service or similar where I can check if this email address
> > > is properly WKD-enabled?
> >
> > https://metacode.biz/openpgp/web-key-directory
>
> Thank you! This is so much easier to comprehend than the official
> documentation...

please make suggestions (or help with improving)
https://wiki.gnupg.org/WKD

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

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.

Best Regards,
Bernhard
ps.: Thanks Wiktor for explaning WKD, I thought you'd be interested in the
feedback. :)

--
www.intevation.de/~bernhard   +49 541 33 508 3-3
Intevation GmbH, Osnabrück, DE; Amtsgericht Osnabrück, HRB 18998
Geschäftsführer Frank Koormann, Bernhard Reiter, Dr. Jan-Oliver Wagner
Re: WKD documentation (Re: Testing WKD setup?) [ In reply to ]
Hi Bernhard,

On 09.07.2019 15:02, Bernhard Reiter wrote:
> 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).

Policy file is checked during WKD check (and I saw the original poster
did set it up). Checking directory listing would be an interesting thing
to add! (Although this would be only heuristic).

--with-wkd gpg version is definitely good thing to add, thanks for the idea!

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

What I like in WKD most is that it's a super-simple standard. Once upon
a time I mailed random PGP-using people asking if they'd consider
setting it up and the feedback has been overwhelmingly positive. The
only thing I needed was basically the local-part hash and actually
that's what I built the checker for, to generate the URL in an easy way,
even without GPG.

--with-wkd mentioned by Alyssa is what I used previously and it was good
but ultimately I've become too lazy to use even that :)

As Phil mentioned the checker has not been updated to latest specs and
gives warnings for issues that I think should be part of the spec (I
mentioned them on the OpenPGP mailing list but did not receive any
feedback from the I-D author).

> Best Regards,
> Bernhard
> ps.: Thanks Wiktor for explaning WKD
>

No problem! I actually also implemented WKD in a couple of projects in
three different languages (OpenKeychain, OpenPGP.js, initial support in
Mailpile, I did have a patch for mutt but they didn't like the idea :)),
so the I-D looks solid!

> I thought you'd be interested in the
> feedback. :)

Yep, thanks for the CC, I'm not subscribed to the ML at all times!

See you later!

Kind regards,
Wiktor

--
https://metacode.biz/@wiktor
Re: WKD documentation (Re: Testing WKD setup?) [ In reply to ]
Hi Wiktor,

[https://metacode.biz/openpgp/web-key-directory]

Am Dienstag 09 Juli 2019 15:50:01 schrieb Wiktor Kwapisiewicz via Gnupg-users:

> On 09.07.2019 15:02, Bernhard Reiter wrote:
> > 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).
>
> Policy file is checked during WKD check (and I saw the original poster
> did set it up).

My suggestion is to mention this in the "Setting up" section,
because otherwise people will only learn it when using the checker.

> Checking directory listing would be an interesting thing
> to add! (Although this would be only heuristic).

Yes, this is just a recommendation (though a strong one). :)
Some people may decide to publish the whole directory.

> Once upon
> a time I mailed random PGP-using people asking if they'd consider
> setting it up and the feedback has been overwhelmingly positive.

Cool, if you receive answer, please help us to keep the list of supporting
organisations growing at https://wiki.gnupg.org/WKD
(We'd have to move it to a subpage soon.)

> No problem! I actually also implemented WKD in a couple of projects in
> three different languages (OpenKeychain, OpenPGP.js, initial support in
> Mailpile,

Cool! Anything more you can share?

> I did have a patch for mutt but they didn't like the idea :))

Do you have a link to your upstream submission? Maybe others users can help to
state their interest? Did you also give it to https://neomutt.org/?

Best Regards,
Bernhard


--
www.intevation.de/~bernhard   +49 541 33 508 3-3
Intevation GmbH, Osnabrück, DE; Amtsgericht Osnabrück, HRB 18998
Geschäftsführer Frank Koormann, Bernhard Reiter, Dr. Jan-Oliver Wagner
Re: WKD documentation (Re: Testing WKD setup?) [ In reply to ]
Hi Bernhard,

On 09.07.2019 16:47, Bernhard Reiter wrote:
>> Once upon
>> a time I mailed random PGP-using people asking if they'd consider
>> setting it up and the feedback has been overwhelmingly positive.
>
> Cool, if you receive answer, please help us to keep the list of supporting
> organisations growing at https://wiki.gnupg.org/WKD
> (We'd have to move it to a subpage soon.)

You can also add Debian there and occrp.org (although the latter doesn't
have policy file :().

I think Linux distributions are particularly good target for WKD - they
can manage their developer's keys. They use HTTPS and usually developers
have e-mail aliases at the distro domain. Additionally now with GnuPG
2.2.17 they can easily make first signature verification faster by
utilizing Signer's UID packet (--sender option).

(As a side note, I did contact two distros with that in mind and one of
them, I'll share this openly: Gentoo - did handle it in a very
professional matter enabling WKD for developers in days and keeping me -
an outsider - in the loop for the whole time. I'm still impressed by
their execution!)

>> No problem! I actually also implemented WKD in a couple of projects in
>> three different languages (OpenKeychain, OpenPGP.js, initial support in
>> Mailpile,
>
> Cool! Anything more you can share?

I'll think about it, this was just the most pleasant experiences I had
in contributing (in no particular order!). I've got a small to-do list
for project that I still want to contribute WKD support but sadly I'm
out of time currently :-/

>> I did have a patch for mutt but they didn't like the idea :))
>
> Do you have a link to your upstream submission? Maybe others users can help to
> state their interest?

Sure, take a look at the thread starting here:
http://lists.mutt.org/pipermail/mutt-dev/Week-of-Mon-20180702/000157.html

(The patch is not there but it's basically setting external locate
mechanism in gpgme so, except one bugfix that I also found, it would be
a one-liner).

From what I can see Werner also planned to add that but I don't know
how it ended up:

http://lists.mutt.org/pipermail/mutt-dev/Week-of-Mon-20181119/000246.html

> Did you also give it to https://neomutt.org/?

Neomutt deferred to Mutt's mailing list, see:
https://github.com/neomutt/neomutt/issues/1282#issuecomment-411401300

On the bright side I've seen other TUI mail clients planning to add WKD
support e.g. Aerc (homepage: https://aerc-mail.org/), author's opinion
on WKD: https://news.ycombinator.com/item?id=20091100

Kind regards,
Wiktor

--
https://metacode.biz/@wiktor
Re: WKD documentation (Re: Testing WKD setup?) [ In reply to ]
On Tue, 9 Jul 2019 15:50, gnupg-users@gnupg.org said:

> setting it up and the feedback has been overwhelmingly positive. The
> only thing I needed was basically the local-part hash and actually
> that's what I built the checker for, to generate the URL in an easy

I think things are even easier now. I have not checked whether this has
made it into the wiki. From gpg-wks-client(1):

Since 2.2.12 we have:

The command --install-key manually installs a key into a local
directory (see option -C) reflecting the structure of a WKD. The
arguments are a file with the keyblock and the user-id to
install. If the first argument resembles a fingerprint the key
is taken from the current keyring; to force the use of a file,
prefix the first argument with "./". If no arguments are given
the parameters are read from stdin; the expected format are lines
with the fingerprint and the mailbox separated by a space. The
command --remove-key removes a key from that directory, its only
argument is a user-id.

The idea is that you can prepare a WKD on your local machine and upload
it by whatever you commonly use to for web pages. And it works on
Windows.

Since we 2.2.15 we also have:

The command --print-wkd-hash prints the WKD user-id identifiers
and the corresponding mail-boxes from the user-ids given on the
command line or via stdin (one user-id per line).

The command --print-wkd-url prints the URLs used to fetch the key
for the given user-ids from WKD. The meanwhile preferred format
with sub-domains is used here.

It is a bit unfortunate that under Unix we install that tool in
/usr/libexec or /usr/lib/.


Shalom-Salam,

Werner


--
Die Gedanken sind frei. Ausnahmen regelt ein Bundesgesetz.
Re: WKD documentation (Re: Testing WKD setup?) [ In reply to ]
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)



_______________________________________________
Gnupg-users mailing list
Gnupg-users@gnupg.org
http://lists.gnupg.org/mailman/listinfo/gnupg-users
Re: WKD documentation (Re: Testing WKD setup?) [ In reply to ]
On Tue, 9 Jul 2019 23:33, johannes@zarl-zierl.at said:

> Now that I have done it once, I think the setup without /usr/lib/gnupg/gpg-
> wks-client isn't that complicated either:

Please use gpg-wks-tool instead; it is much easier and less error prone.

> b. Manually, using gpg: gpg --homedir "$(mktemp -d)" --locate-keys $KEYID

With 2.2.17 use

gpg --locate-external-key -v foo@example.org

Granted it imports the key but after all that is what you want. That
new command does not check the local keyring so it can be used to
refresh from a WKD (or whatever has been configured in your AKL)

You may use

gpg-wks-client --with-colons --supported DOMAINS

to get the status of the Web Key Service for the requested domains.
See the man page for details.


Shalom-Salam,

Werner


--
Die Gedanken sind frei. Ausnahmen regelt ein Bundesgesetz.
Re: WKD documentation (Re: Testing WKD setup?) [ In reply to ]
Am Mittwoch, 10. Juli 2019, 19:34:41 CEST schrieb Werner Koch:
> On Tue, 9 Jul 2019 23:33, johannes@zarl-zierl.at said:
> > Now that I have done it once, I think the setup without
> > /usr/lib/gnupg/gpg-
>
> > wks-client isn't that complicated either:
> Please use gpg-wks-tool instead; it is much easier and less error prone.

...except it isn't installed by default. Will this be part of gpg-wks-client?
But in the future when it is installed by default, I 100% agree with you.

Btw, and because we are on the topic of documentation: there is no mention of
gpg-wks-tool anywhere in the WKD or WKDHosting pages.

Anyways: whether you promote gpg-wks-client or gpg-wks-tool (which, hopefully,
won't be installed to libexec), it would still be beneficial to describe the
actual file system layout.


> > b. Manually, using gpg: gpg --homedir "$(mktemp -d)" --locate-keys $KEYID
>
> With 2.2.17 use
>
> gpg --locate-external-key -v foo@example.org
>
> Granted it imports the key but after all that is what you want. That
> new command does not check the local keyring so it can be used to
> refresh from a WKD (or whatever has been configured in your AKL)

That seems nice - I will take note for the time this enters Debian...

Cheers,
Johannes





_______________________________________________
Gnupg-users mailing list
Gnupg-users@gnupg.org
http://lists.gnupg.org/mailman/listinfo/gnupg-users
Re: WKD documentation (Re: Testing WKD setup?) [ In reply to ]
On Wed, 10 Jul 2019 21:47, johannes@zarl-zierl.at said:

> ...except it isn't installed by default. Will this be part of gpg-wks-client?

Ooops. I meant gpg-wks-client. There is no gpg-wks-tool.

> won't be installed to libexec), it would still be beneficial to describe the
> actual file system layout.

You mean, where it gets installed? When running ./configure without any
options gpg-wks-tool whill be installed under /usr/local/libexec as per
GNU standards. Debian and other distors don't have this directory and
install it under /usr/lib. You can of course use

$(gpgconf --list-dirs libexecdir)/gpg-wks-client



Shalom-Salam,

Werner

--
Die Gedanken sind frei. Ausnahmen regelt ein Bundesgesetz.
Re: WKD documentation (Re: Testing WKD setup?) [ In reply to ]
Am Freitag, 12. Juli 2019, 10:30:30 CEST schrieb Werner Koch via Gnupg-users:
> On Wed, 10 Jul 2019 21:47, johannes@zarl-zierl.at said:
> > ...except it isn't installed by default. Will this be part of
> > gpg-wks-client?
> Ooops. I meant gpg-wks-client. There is no gpg-wks-tool.

Thanks for the clarification.


> > won't be installed to libexec), it would still be beneficial to describe
> > the actual file system layout.
>
> You mean, where it gets installed? When running ./configure without any
> options gpg-wks-tool whill be installed under /usr/local/libexec as per
> GNU standards. Debian and other distors don't have this directory and
> install it under /usr/lib. You can of course use

Sorry, I should have separated this better from the previous sentence. What I
meant are two things:

1. If a user is ever to execute gpg-wks-client directly or through a script,
libexec should not be used: [1]

Right now I have the bizarre situation on Debian unstable that gpg-wks-server
is in /usr/bin even though it is meant to be executed by a service and not by
a user, but gpg-wks-client is located in /usr/lib/gnupg (Debian has no
libexec, I think).

[1] https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html

2. It would still be beneficial to describe the actual file system layout of
the WKD.
This can either be done implicitly in the step-by-step guide ("After the call
to gpg-wks-client, 'find .well-known/openpgp' should list a directory
structure similar to this one: ..."). Or it can be documented separately on
the WKD page, also explaining different options (e.g. is there a different WKD
layout when WKD is deployed on a sub-domain, what are possible values for the
policy file) with links to the canonical reference documentation.

Cheers,
Johannes