<<TableOfContents(2)>>

== What is a Web Key Directory?

A Web Key Directory (WKD) provides an easy way to provide and get
the current public key for a given email address 
through H~T~T~P~S.
Thus it is infrastructure **to improve the user experience
for exchanging secure emails and files**.

Because the email address is needed to ask for a public key,
using a Web Key Directory preserves the privacy of this address.
If a public key is found, it can be used to encrypt
to the email address right away.

== for Users
* [[/forUsers]]


== How does an email client use WKD?

# A user selects a recipient for an email.
# The email client uses the domain part of the email address to construct
  which server to ask.
# HTT~PS is used to get the current public key.
# The email client is ready to encrypt and send now.
 
An example: 
{{{https://intevation.de/.well-known/openpgpkey/hu/it5sewh54rxz33fwmr8u6dy4bbz8itz4}}} is the //direct method// URL for "bernhard.reiter@intevation.de".


== What does it mean for users?

A user just selects the recipients of a message and by
default the encryption state of that mail will toggle if
encryption keys can be found for all of them.

[[https://files.intevation.de/users/aheinecke/wkd-autoencrypt.gif|Example from Gpg4win / GpgOL]]

For a basic level of security the user does **not need to check a fingerprint** or do
any key management manually.

== How to set it up?

If you want to set up a Web Key Directory for your own server or your own server
you only need access to a webserver for your domain. See: WKDHosting

For a larger organization it is recommended to set up a complete Web Key
Service, which will help to automate Web Key Directory publishing.

=== Stopgap method - temporary central keyserver

Not recommended - but a temporary workaround - is to use "WKD~aaS"
and delegate delivery of your pubkey to a central service.
Doing this you'll expose all people that want to use crypto when communication with you
towards another party of the central service or monitoring the central service.
This third party can then see the communication pattern.

However this maybe a temporary solution until you will convince your mail provider
to enable at least the WKD serving part or to switch to a more privacy aware mail provider.

One service is keys.openpgp.org, where you can set the ~C~N~A~M~E record of the "openpgpkey" subdomainto "wkd.keys.openpgp.org" the CNAME entry should look like this.
{{{
openpgpkey.example.org. 300     IN      CNAME   wkd.keys.openpgp.org.
}}}

In addition you need to register your pubkey with them. 

Other drawbacks:
* As any WKD service, they'll be able to serve a different pubkey to some domains at some time, however 
opposed to your email provider you do not have a contractual relationship with them.
* Elder Gnu~PGs like the some on Debian Stretch do not offer the necessary modern WKD implementation for a successful request, so you are reaching less communication partners with this compared to real WKD.
* (For the overall ecosystem, we need more decentral services instead, it is at the core of Open~PGP security promise. So you are missing to set a good example. ;) )

== Web Key Directory (WKD) / Web Key Service (WKS) what is the difference?

The Web Key Directory is the H~T~T~P~S directory from which keys can be fetched.

The Web Key Service is a tool / protocol to automatically publish and
update keys in the Web Key Directory. It is **optional** to reduce the
administrative effort of a Web Key Directory.

Documentation how to set up a Web Key Service can be found on the [[WKS|Web Key Service page]].

== Technical Details

You can find the concepts / technical details under WKDDetails.

Trust and security considerations are outlined as part of the AutomatedEncryption concept.

=== Troubleshooting

If you have arrived here after receiving an email saying:

{{{
The web page

       https://gnupg.org/faq/wkd.html

explains how you can process this message anyway in
a few manual steps.
}}}

you can find further instructions at WKSManualConfirmation.

== Implementations

=== GnuPG
* WKD lookup is implemented in GnuPG since v2.1.12. It is enabled by default since 2.1.23..

* WKS server and client tools are part of GnuPG since v2.1.14

=== Mail Clients

Any mail client which uses the {{{--locate-keys}}} option of GnuPG will automatically
do WKD requests.

Known mail clients with WKD Support:
* Desktop:
** Thunderbird/[[https://www.enigmail.net/index.php/en/download/changelog|Enigmail 2.0]]
** KMail since Version 5.6
** Outlook with GpgOL since Version 2.2.0
** Claws Mail since [[https://www.claws-mail.org/news.php|3.18.0 / 4.0.0]]
* Browser-Extensions:
** Mailvelope since Version 3.0.0 (Dez 2018)
* Android:
** K9Mail with OpenKeyChain since Version 5.1 (Jun 2018)
** FairEmail with OpenKeyChain since OpenKeyChain 5.4 ([[https://github.com/M66B/FairEmail/blob/master/FAQ.md#user-content-faq12|FAQ, (12) How does encryption/decryption work?]])

[[/DistributionOfWKD|Progress of WKD]] in different mail clients

Known mail clients with WKS Support:
* Thunderbird/[[https://www.enigmail.net/index.php/en/download/changelog|Enigmail 2.0]]
* KMail since Version 5.6
* Outlook with GpgOL (basic, pre-release) since Version 2.2.1
asyGpg2016)

=== Self-hosted email setups offering WKD + WKS:
* [[https://github.com/vedetta-com/caesonia/|caesonia - OpenBSD email service]].
* [[https://github.com/Excision-Mail/Excision-Mail/| Excision Mail - OpenBSD email service using ansible]]: Has multiple-domain WKS support.
* [[https://github.com/systemli/userli|Userli - Web application to (self-) manage e-mail users and encrypt their mailboxes.]].

=== Mail Service Providers offering WKD
* [[https://posteo.de/en/|Posteo]] offers web key directory lookup and service for {{{@posteo.de}}}-addresses
  (**Since 2016-12**) E.g. [[https://posteo.de/hilfe/easygpg-wie-veroeffentliche-ich-meinen-oeffentlichen-pgp-schluessel-ueber-web-key-directory-wkd-im-posteo-schluesselverzeichnis|German Thunderbird/WKD Instructions]] 
* [[https://protonmail.com|Protonmail]] supports web key directory lookup (**Since ~2018-11**) in [[https://protonmail.com/blog/security-updates-2019/|both ways]].
* [[https://netzguerilla.net|netzguerilla]] offers web key directory lookup.  (**Since 2017-10-11**)
* [[https://systemli.org|systemli.org]] offers web key directory lookup and service for all hosted domains (**Since 2020-10-15**)
* [[https://mailbox.org/en/|mailbox.org]] **claims** to offer web key directory lookup (see https://mailbox.org/en/post/the-keyserver-is-dead-long-live-the-keyserver 2019 and DE Forum question 2021 https://userforum.mailbox.org/topic/wann-wird-ein-web-key-directory-wkd-angeboten )
* [[https://mail.de/|mail.de]] maintains a WKD server (Screenshot: [[attachment:mailde_wkd.png]]
* [[https://mailfence.com/|Mailfence]] supports web key directory lookup (**Since ~2021-11-18**) in [[https://blog.mailfence.com/improving-security/|both ways]].

=== Organizations using WKD

* [[https://www.c3s.cc|C3S]]
* [[https://www.cotech.de|cotech.de]]
* [[https://www.credativ.de/blog/aktuelles/credativde-pgp-schluessel-ueber-wkd-abrufen/|Credativ GmbH, DE]]
* [[https://www.debian.org|debian.org]]
* [[https://gentoo.org|gentoo.org]]
* [[https://gnupg.org|gnupg.org]] (Testing accounts available for developers implementing WKD in ~MUAs.)
* [[https://kdab.com|KDAB.com]]
* [[https://kernel.org|kernel.org]]
* [[https://nikkasystems.com|Nikka Systems]]
* [[https://www.occrp.org|occrp.org]]
* [[https://www.torproject.org|torproject.org]]
* [[https://f-droid.org|f-droid.org]]
* [[https://guardianproject.info|guardianproject.info]]
* [[https://www.privacyguides.org|privacyguides.org]]
* (Several unlisted organisations. And of course the main designers of WKD - g10code.com, intevation.de.)

(//Add yourself or let us know if you want to be publicly listed.//)

== Misc
* [[/BachelorThesisIncreaseWKDUsage2021|Bachelor thesis: How to increase the usage of WKD? (2021, Christoph Klassen)]]