wkd: Add option --directory to the server.
[gnupg.git] / doc / wks.texi
1 @c wks.texi - man pages for the Web Key Service tools.
2 @c Copyright (C) 2017 g10 Code GmbH
3 @c Copyright (C) 2017 Bundesamt für Sicherheit in der Informationstechnik
4 @c This is part of the GnuPG manual.
5 @c For copying conditions, see the file GnuPG.texi.
6
7 @include defs.inc
8
9 @node Web Key Service
10 @chapter Web Key Service
11
12 GnuPG comes with tools used to maintain and access a Web Key
13 Directory.
14
15 @menu
16 * gpg-wks-client::        Send requests via WKS
17 * gpg-wks-server::        Server to provide the WKS.
18 @end menu
19
20 @c
21 @c  GPG-WKS-CLIENT
22 @c
23 @manpage gpg-wks-client.1
24 @node gpg-wks-client
25 @section Send requests via WKS
26 @ifset manverb
27 .B gpg-wks-client
28 \- Client for the Web Key Service
29 @end ifset
30
31 @mansect synopsis
32 @ifset manverb
33 .B gpg-wks-client
34 .RI [ options ]
35 .B \-\-supported
36 .I user-id
37 .br
38 .B gpg-wks-client
39 .RI [ options ]
40 .B \-\-check
41 .I user-id
42 .br
43 .B gpg-wks-client
44 .RI [ options ]
45 .B \-\-create
46 .I fingerprint
47 .I user-id
48 .br
49 .B gpg-wks-client
50 .RI [ options ]
51 .B \-\-receive
52 .br
53 .B gpg-wks-client
54 .RI [ options ]
55 .B \-\-read
56 @end ifset
57
58 @mansect description
59 The @command{gpg-wks-client} is used to send requests to a Web Key
60 Service provider.  This is usuallay done to upload a key into a Web
61 Key Directory.
62
63 With the @option{--supported} command the caller can test whether a
64 site supports the Web Key Service.  The argument is an arbitrary
65 address in the to be tested domain. For example
66 @file{foo@@example.net}.  The command returns success if the Web Key
67 Service is supported.  The operation is silent; to get diagnostic
68 output use the option @option{--verbose}.
69
70 With the @option{--check} command the caller can test whether a key
71 exists for a supplied mail address.  The command returns success if a
72 key is available.
73
74 The @option{--create} command is used to send a request for
75 publication in the Web Key Directory.  The arguments are the
76 fingerprint of the key and the user id to publish.  The output from
77 the command is a properly formatted mail with all standard headers.
78 This mail can be fed to @command{sendmail(8)} or any other tool to
79 actually send that mail.  If @command{sendmail(8)} is installed the
80 option @option{--send} can be used to directly send the created
81 request.  If the provider request a 'mailbox-only' user id and no such
82 user id is found, @command{gpg-wks-client} will try an additional user
83 id.
84
85 The @option{--receive} and @option{--read} commands are used to
86 process confirmation mails as send from the service provider.  The
87 former expects an encrypted MIME messages, the latter an already
88 decrypted MIME message.  The result of these commands are another mail
89 which can be send in the same way as the mail created with
90 @option{--create}.
91
92 @command{gpg-wks-client} is not commonly invoked directly and thus it
93 is not installed in the bin directory.  Here is an example how it can
94 be invoked manually to check for a Web Key Directory entry for
95 @file{foo@@example.org}:
96
97 @example
98 $(gpgconf --list-dirs libexecdir)/gpg-wks-client --check foo@@example.net
99 @end example
100
101 @mansect options
102 @noindent
103 @command{gpg-wks-client} understands these options:
104
105 @table @gnupgtabopt
106
107 @item --send
108 @opindex send
109 Directly send created mails using the @command{sendmail} command.
110 Requires installation of that command.
111
112 @item --output @var{file}
113 @itemx -o
114 @opindex output
115 Write the created mail to @var{file} instead of stdout.  Note that the
116 value @code{-} for @var{file} is the same as writing to stdout.
117
118 @item --status-fd @var{n}
119 @opindex status-fd
120 Write special status strings to the file descriptor @var{n}.
121 This program returns only the status messages SUCCESS or FAILURE which
122 are helpful when the caller uses a double fork approach and can't
123 easily get the return code of the process.
124
125 @item --verbose
126 @opindex verbose
127 Enable extra informational output.
128
129 @item --quiet
130 @opindex quiet
131 Disable almost all informational output.
132
133 @item --version
134 @opindex version
135 Print version of the program and exit.
136
137 @item --help
138 @opindex help
139 Display a brief help page and exit.
140
141 @end table
142
143
144 @mansect see also
145 @ifset isman
146 @command{gpg-wks-server}(1)
147 @end ifset
148
149
150 @c
151 @c  GPG-WKS-SERVER
152 @c
153 @manpage gpg-wks-server.1
154 @node gpg-wks-server
155 @section Provide the Web Key Service
156 @ifset manverb
157 .B gpg-wks-server
158 \- Server providing the Web Key Service
159 @end ifset
160
161 @mansect synopsis
162 @ifset manverb
163 .B gpg-wks-server
164 .RI [ options ]
165 .B \-\-receive
166 .br
167 .B gpg-wks-server
168 .RI [ options ]
169 .B \-\-cron
170 .br
171 .B gpg-wks-server
172 .RI [ options ]
173 .B \-\-list-domains
174 .br
175 .B gpg-wks-server
176 .RI [ options ]
177 .B \-\-check-key
178 .I user-id
179 .br
180 .B gpg-wks-server
181 .RI [ options ]
182 .B \-\-install-key
183 .I file
184 .I user-id
185 .br
186 .B gpg-wks-server
187 .RI [ options ]
188 .B \-\-remove-key
189 .I user-id
190 .br
191 .B gpg-wks-server
192 .RI [ options ]
193 .B \-\-revoke-key
194 .I user-id
195 @end ifset
196
197 @mansect description
198 The @command{gpg-wks-server} is a server site implementation of the
199 Web Key Service.  It receives requests for publication, sends
200 confirmation requests, receives confirmations, and published the key.
201 It also has features to ease the setup and maintenance of a Web Key
202 Directory.
203
204 When used with the command @option{--receive} a single Web Key Service
205 mail is processed.  Commonly this command is used with the option
206 @option{--send} to directly send the crerated mails back.  See below
207 for an installation example.
208
209 The command @option{--cron} is used for regular cleanup tasks.  For
210 example non-confirmed requested should be removed after their expire
211 time.  It is best to run this command once a day from a cronjob.
212
213 The command @option{--list-domains} prints all configured domains.
214 Further it creates missing directories for the configuration and
215 prints warnings pertaining to problems in the configuration.
216
217 The command @option{--check-key} (or just @option{--check}) checks
218 whether a key with the given user-id is installed.  The process returns
219 success in this case; to also print a diagnostic use the option
220 @option{-v}.  If the key is not installed a diagnostic is printed and
221 the process returns failure; to suppress the diagnostic, use option
222 @option{-q}.  More than one user-id can be given; see also option
223 @option{with-file}.
224
225 The command @option{--install-key} manually installs a key into the
226 WKD.  The arguments are a file with the keyblock and the user-id to
227 install.  If the first argument resembles a fingerprint the key is
228 taken from the current keyring; to force the use of a file, prefix the
229 first argument with "./".
230
231 The command @option{--remove-key} uninstalls a key from the WKD.  The
232 process returns success in this case; to also print a diagnostic, use
233 option @option{-v}.  If the key is not installed a diagnostic is
234 printed and the process returns failure; to suppress the diagnostic,
235 use option @option{-q}.
236
237 The command @option{--revoke-key} is not yet functional.
238
239
240 @mansect options
241 @noindent
242 @command{gpg-wks-server} understands these options:
243
244 @table @gnupgtabopt
245
246 @item -C @var{dir}
247 @itemx --directory @var{dir}
248 @opindex directory
249 Use @var{dir} as top level directory for domains.  The default is
250 @file{/var/lib/gnupg/wks}.
251
252 @item --from @var{mailaddr}
253 @opindex from
254 Use @var{mailaddr} as the default sender address.
255
256 @item --header @var{name}=@var{value}
257 @opindex header
258 Add the mail header "@var{name}: @var{value}" to all outgoing mails.
259
260 @item --send
261 @opindex send
262 Directly send created mails using the @command{sendmail} command.
263 Requires installation of that command.
264
265 @item -o @var{file}
266 @itemx --output @var{file}
267 @opindex output
268 Write the created mail also to @var{file}. Note that the value
269 @code{-} for @var{file} would write it to stdout.
270
271 @item --with-dir
272 @opindex with-dir
273 When used with the command @option{--list-domains} print for each
274 installed domain the domain name and its directory name.
275
276 @item --with-file
277 @opindex with-file
278 When used with the command @option{--check-key} print for each user-id,
279 the address, 'i' for installed key or 'n' for not installed key, and
280 the filename.
281
282 @item --verbose
283 @opindex verbose
284 Enable extra informational output.
285
286 @item --quiet
287 @opindex quiet
288 Disable almost all informational output.
289
290 @item --version
291 @opindex version
292 Print version of the program and exit.
293
294 @item --help
295 @opindex help
296 Display a brief help page and exit.
297
298 @end table
299
300 @noindent
301 @mansect examples
302 @chapheading Examples
303
304 The Web Key Service requires a working directory to store keys
305 pending for publication.  As root create a working directory:
306
307 @example
308   # mkdir /var/lib/gnupg/wks
309   # chown webkey:webkey /var/lib/gnupg/wks
310   # chmod 2750 /var/lib/gnupg/wks
311 @end example
312
313 Then under your webkey account create directories for all your
314 domains.  Here we do it for "example.net":
315
316 @example
317   $ mkdir /var/lib/gnupg/wks/example.net
318 @end example
319
320 Finally run
321
322 @example
323   $ gpg-wks-server --list-domains
324 @end example
325
326 to create the required sub-directories with the permissions set
327 correctly.  For each domain a submission address needs to be
328 configured.  All service mails are directed to that address.  It can
329 be the same address for all configured domains, for example:
330
331 @example
332   $ cd /var/lib/gnupg/wks/example.net
333   $ echo key-submission@@example.net >submission-address
334 @end example
335
336 The protocol requires that the key to be published is send with an
337 encrypted mail to the service.  Thus you need to create a key for
338 the submission address:
339
340 @example
341   $ gpg --batch --passphrase '' --quick-gen-key key-submission@@example.net
342   $ gpg -K key-submission@@example.net
343 @end example
344
345 The output of the last command looks similar to this:
346
347 @example
348   sec   rsa3072 2016-08-30 [SC]
349         C0FCF8642D830C53246211400346653590B3795B
350   uid           [ultimate] key-submission@@example.net
351                 bxzcxpxk8h87z1k7bzk86xn5aj47intu@@example.net
352   ssb   rsa3072 2016-08-30 [E]
353 @end example
354
355 Take the fingerprint from that output and manually publish the key:
356
357 @example
358   $ gpg-wks-server --install-key C0FCF8642D830C53246211400346653590B3795B \
359   >                key-submission@@example.net
360 @end example
361
362 Finally that submission address needs to be redirected to a script
363 running @command{gpg-wks-server}.  The @command{procmail} command can
364 be used for this: Redirect the submission address to the user "webkey"
365 and put this into webkey's @file{.procmailrc}:
366
367 @example
368 :0
369 * !^From: webkey@@example.net
370 * !^X-WKS-Loop: webkey.example.net
371 |gpg-wks-server -v --receive \
372      --header X-WKS-Loop=webkey.example.net \
373      --from webkey@@example.net --send
374 @end example
375
376
377 @mansect see also
378 @ifset isman
379 @command{gpg-wks-client}(1)
380 @end ifset