blog: Add blog entry about WKD
[gnupg-doc.git] / misc / blog.gnupg.org / 20161027-hosting-a-web-key-directory.org
1 # How to host your own Web Key Directory
2 #+STARTUP: showall
3 #+AUTHOR: Andre
4 #+DATE: October 27, 2016
5
6 ** Hosting a Web Key Directory
7
8     With the improvements in GnuPG for Key Discovery
9     (see: [[https://www.gnupg.org/blog/20160830-web-key-service.html][Key Discovery Made Simple]]) you may want to provide the
10     OpenPGP keys for your domain. The Web Key Service (WKS) describes
11     a protocol for Mail Service Providers or large organisations to
12     maintain a Web Key Directory (WKD) for their users.
13
14     A Web Key Directory is a static collection of keys provided under
15     well known URLs under your domain. This directory can also be
16     manually generated without using the Web Key Service protocol.
17
18
19     By providing a Web Key Directory other people (or their Mail Software)
20     can obtain the OpenPGP keys for your domain with a simple query like:
21
22     : $ gpg --auto-key-locate wkd --locate-keys <mail address>
23
24     In this note, I explain how to do that.
25
26
27     Note: An updated version of this article may be available in the
28     [[https://wiki.gnupg.org/WKD#Hosting%20a%20Web%20Key%20Directory][GnuPG Wiki]]
29
30 *** Requirements
31
32     - A web server that provides https with a trusted certificate for
33       your domain.
34     - A client machine with Python and PyME installed (debian package
35       python-pyme)
36     - The script:
37       [[https://hg.intevation.de/gnupg/wkd-tools/raw-file/default/generate-openpgpkey-hu][generate-openpgpkey-hu]]
38       (in the [[https://hg.intevation.de/gnupg/wkd-tools/][Mercurial repository "wkd-tools"]])
39
40 *** Setup
41
42     You can either export all the keys in your keyring that belong to
43     a domain or provide an explicit keyring containing just those keys
44     that you want to publish.
45
46     The call:
47
48     : $ ./generate-openpgpkey-hu example.com hu
49
50
51     Will create a directory called hu containing all the keys with
52     user ids that include @example.com.
53
54     If there are multiple valid keys for a user in your keyring this
55     command will error out. In that case you can prepare a keyring
56     with only the keys that you want to publish. For example:
57
58     : $ gpg --export 94A5C9A03C2FE5CA3B095D8E1FDF723CF462B6B1 | \
59     : >   gpg --no-default-keyring --keyring ./wkd-keyring.gpg --import
60
61     And then provide that keyring to generate-openpgpkey-hu:
62
63     : ./generate-openpgpkey-hu example.com hu wkd-keyring.gpg
64
65 *** Publishing
66
67     The hu directory has to be published on your server as
68
69     : https://example.com/.well-known/openpgpkey/hu/
70
71     Create the directory structure  and set the
72     permissions accordingly.
73
74     This example [[https://hg.intevation.de/gnupg/wkd-tools/raw-file/default/Makefile.example][Makefile]] automates the hu directory generation and
75     publishing. Edit the variables at the top of the makefile to set
76     =RSYNC_TARGET= The =KEYRING= variable is optional and can be left
77     empty.
78
79     That's it. You can now test your setup by calling:
80
81     : $ gpg --auto-key-locate wkd --locate-keys <mail address>
82
83     you should see something like this:
84
85 #+begin_example
86 gpg: key AC12F94881D28CB7: public key "testuser10@test.gnupg.org" imported
87 gpg: Total number processed: 1
88 gpg:               imported: 1
89 gpg: automatically retrieved 'testuser10@test.gnupg.org' via WKD
90 pub   ed25519 2016-07-15 [SC]
91       5506894357DC548CC65B0BCFAC12F94881D28CB7
92 uid           [ unknown] testuser10@test.gnupg.org
93 sub   cv25519 2016-07-15 [E]
94 #+end_example