9f1fff2a8f82b768e1f4cc204413a60895e993ee
[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}.  See option
69 @option{--with-colons} for a variant of this command.
70
71 With the @option{--check} command the caller can test whether a key
72 exists for a supplied mail address.  The command returns success if a
73 key is available.
74
75 The @option{--create} command is used to send a request for
76 publication in the Web Key Directory.  The arguments are the
77 fingerprint of the key and the user id to publish.  The output from
78 the command is a properly formatted mail with all standard headers.
79 This mail can be fed to @command{sendmail(8)} or any other tool to
80 actually send that mail.  If @command{sendmail(8)} is installed the
81 option @option{--send} can be used to directly send the created
82 request.  If the provider request a 'mailbox-only' user id and no such
83 user id is found, @command{gpg-wks-client} will try an additional user
84 id.
85
86 The @option{--receive} and @option{--read} commands are used to
87 process confirmation mails as send from the service provider.  The
88 former expects an encrypted MIME messages, the latter an already
89 decrypted MIME message.  The result of these commands are another mail
90 which can be send in the same way as the mail created with
91 @option{--create}.
92
93 The command @option{--install-key} manually installs a key into a
94 local directory (see option @option{-C}) reflecting the structure of a
95 WKD.  The arguments are a file with the keyblock and the user-id to
96 install.  If the first argument resembles a fingerprint the key is
97 taken from the current keyring; to force the use of a file, prefix the
98 first argument with "./".  If no arguments are given the parameters
99 are read from stdin; the expected format are lines with the
100 fingerprint and the mailbox separated by a space.  The command
101 @option{--remove-key} removes a key from that directory, its only
102 argument is a user-id.
103
104 The command @option{--print-wkd-hash} prints the WKD user-id identifiers
105 and the corresponding mailboxes from the user-ids given on the command
106 line or via stdin (one user-id per line).
107
108 The command @option{--print-wkd-url} prints the URLs used to fetch the
109 key for the given user-ids from WKD.  The meanwhile preferred format
110 with sub-domains is used here.
111
112 @command{gpg-wks-client} is not commonly invoked directly and thus it
113 is not installed in the bin directory.  Here is an example how it can
114 be invoked manually to check for a Web Key Directory entry for
115 @file{foo@@example.org}:
116
117 @example
118 $(gpgconf --list-dirs libexecdir)/gpg-wks-client --check foo@@example.net
119 @end example
120
121 @mansect options
122 @noindent
123 @command{gpg-wks-client} understands these options:
124
125 @table @gnupgtabopt
126
127 @item --send
128 @opindex send
129 Directly send created mails using the @command{sendmail} command.
130 Requires installation of that command.
131
132 @item --with-colons
133 @opindex with-colons
134 This option has currently only an effect on the @option{--supported}
135 command.  If it is used all arguments on the command line are taken
136 as domain names and tested for WKD support.  The output format is one
137 line per domain with colon delimited fields.  The currently specified
138 fields are (future versions may specify additional fields):
139
140 @table @asis
141
142   @item 1 - domain
143   This is the domain name.  Although quoting is not required for valid
144   domain names this field is specified to be quoted in standard C
145   manner.
146
147   @item 2 - WKD
148   If the value is true the domain supports the Web Key Directory.
149
150   @item 3 - WKS
151   If the value is true the domain supports the Web Key Service
152   protocol to upload keys to the directory.
153
154   @item 4 - error-code
155   This may contain an gpg-error code to describe certain
156   failures.  Use @samp{gpg-error CODE} to explain the code.
157
158   @item 5 - protocol-version
159   The minimum protocol version supported by the server.
160
161   @item 6 - auth-submit
162   The auth-submit flag from the policy file of the server.
163
164   @item 7 - mailbox-only
165   The mailbox-only flag from the policy file of the server.
166 @end table
167
168
169
170 @item --output @var{file}
171 @itemx -o
172 @opindex output
173 Write the created mail to @var{file} instead of stdout.  Note that the
174 value @code{-} for @var{file} is the same as writing to stdout.
175
176 @item --status-fd @var{n}
177 @opindex status-fd
178 Write special status strings to the file descriptor @var{n}.
179 This program returns only the status messages SUCCESS or FAILURE which
180 are helpful when the caller uses a double fork approach and can't
181 easily get the return code of the process.
182
183 @item -C @var{dir}
184 @itemx --directory @var{dir}
185 @opindex directory
186 Use @var{dir} as top level directory for the commands
187 @option{--install-key} and @option{--remove-key}.  The default is
188 @file{openpgpkey}.
189
190 @item --verbose
191 @opindex verbose
192 Enable extra informational output.
193
194 @item --quiet
195 @opindex quiet
196 Disable almost all informational output.
197
198 @item --version
199 @opindex version
200 Print version of the program and exit.
201
202 @item --help
203 @opindex help
204 Display a brief help page and exit.
205
206 @end table
207
208
209 @mansect see also
210 @ifset isman
211 @command{gpg-wks-server}(1)
212 @end ifset
213
214
215 @c
216 @c  GPG-WKS-SERVER
217 @c
218 @manpage gpg-wks-server.1
219 @node gpg-wks-server
220 @section Provide the Web Key Service
221 @ifset manverb
222 .B gpg-wks-server
223 \- Server providing the Web Key Service
224 @end ifset
225
226 @mansect synopsis
227 @ifset manverb
228 .B gpg-wks-server
229 .RI [ options ]
230 .B \-\-receive
231 .br
232 .B gpg-wks-server
233 .RI [ options ]
234 .B \-\-cron
235 .br
236 .B gpg-wks-server
237 .RI [ options ]
238 .B \-\-list-domains
239 .br
240 .B gpg-wks-server
241 .RI [ options ]
242 .B \-\-check-key
243 .I user-id
244 .br
245 .B gpg-wks-server
246 .RI [ options ]
247 .B \-\-install-key
248 .I file
249 .I user-id
250 .br
251 .B gpg-wks-server
252 .RI [ options ]
253 .B \-\-remove-key
254 .I user-id
255 .br
256 .B gpg-wks-server
257 .RI [ options ]
258 .B \-\-revoke-key
259 .I user-id
260 @end ifset
261
262 @mansect description
263 The @command{gpg-wks-server} is a server site implementation of the
264 Web Key Service.  It receives requests for publication, sends
265 confirmation requests, receives confirmations, and published the key.
266 It also has features to ease the setup and maintenance of a Web Key
267 Directory.
268
269 When used with the command @option{--receive} a single Web Key Service
270 mail is processed.  Commonly this command is used with the option
271 @option{--send} to directly send the crerated mails back.  See below
272 for an installation example.
273
274 The command @option{--cron} is used for regular cleanup tasks.  For
275 example non-confirmed requested should be removed after their expire
276 time.  It is best to run this command once a day from a cronjob.
277
278 The command @option{--list-domains} prints all configured domains.
279 Further it creates missing directories for the configuration and
280 prints warnings pertaining to problems in the configuration.
281
282 The command @option{--check-key} (or just @option{--check}) checks
283 whether a key with the given user-id is installed.  The process returns
284 success in this case; to also print a diagnostic use the option
285 @option{-v}.  If the key is not installed a diagnostic is printed and
286 the process returns failure; to suppress the diagnostic, use option
287 @option{-q}.  More than one user-id can be given; see also option
288 @option{with-file}.
289
290 The command @option{--install-key} manually installs a key into the
291 WKD.  The arguments are a file with the keyblock and the user-id to
292 install.  If the first argument resembles a fingerprint the key is
293 taken from the current keyring; to force the use of a file, prefix the
294 first argument with "./".  If no arguments are given the parameters
295 are read from stdin; the expected format are lines with the
296 fingerprint and the mailbox separated by a space.
297
298 The command @option{--remove-key} uninstalls a key from the WKD.  The
299 process returns success in this case; to also print a diagnostic, use
300 option @option{-v}.  If the key is not installed a diagnostic is
301 printed and the process returns failure; to suppress the diagnostic,
302 use option @option{-q}.
303
304 The command @option{--revoke-key} is not yet functional.
305
306
307 @mansect options
308 @noindent
309 @command{gpg-wks-server} understands these options:
310
311 @table @gnupgtabopt
312
313 @item -C @var{dir}
314 @itemx --directory @var{dir}
315 @opindex directory
316 Use @var{dir} as top level directory for domains.  The default is
317 @file{/var/lib/gnupg/wks}.
318
319 @item --from @var{mailaddr}
320 @opindex from
321 Use @var{mailaddr} as the default sender address.
322
323 @item --header @var{name}=@var{value}
324 @opindex header
325 Add the mail header "@var{name}: @var{value}" to all outgoing mails.
326
327 @item --send
328 @opindex send
329 Directly send created mails using the @command{sendmail} command.
330 Requires installation of that command.
331
332 @item -o @var{file}
333 @itemx --output @var{file}
334 @opindex output
335 Write the created mail also to @var{file}. Note that the value
336 @code{-} for @var{file} would write it to stdout.
337
338 @item --with-dir
339 @opindex with-dir
340 When used with the command @option{--list-domains} print for each
341 installed domain the domain name and its directory name.
342
343 @item --with-file
344 @opindex with-file
345 When used with the command @option{--check-key} print for each user-id,
346 the address, 'i' for installed key or 'n' for not installed key, and
347 the filename.
348
349 @item --verbose
350 @opindex verbose
351 Enable extra informational output.
352
353 @item --quiet
354 @opindex quiet
355 Disable almost all informational output.
356
357 @item --version
358 @opindex version
359 Print version of the program and exit.
360
361 @item --help
362 @opindex help
363 Display a brief help page and exit.
364
365 @end table
366
367 @noindent
368 @mansect examples
369 @chapheading Examples
370
371 The Web Key Service requires a working directory to store keys
372 pending for publication.  As root create a working directory:
373
374 @example
375   # mkdir /var/lib/gnupg/wks
376   # chown webkey:webkey /var/lib/gnupg/wks
377   # chmod 2750 /var/lib/gnupg/wks
378 @end example
379
380 Then under your webkey account create directories for all your
381 domains.  Here we do it for "example.net":
382
383 @example
384   $ mkdir /var/lib/gnupg/wks/example.net
385 @end example
386
387 Finally run
388
389 @example
390   $ gpg-wks-server --list-domains
391 @end example
392
393 to create the required sub-directories with the permissions set
394 correctly.  For each domain a submission address needs to be
395 configured.  All service mails are directed to that address.  It can
396 be the same address for all configured domains, for example:
397
398 @example
399   $ cd /var/lib/gnupg/wks/example.net
400   $ echo key-submission@@example.net >submission-address
401 @end example
402
403 The protocol requires that the key to be published is send with an
404 encrypted mail to the service.  Thus you need to create a key for
405 the submission address:
406
407 @example
408   $ gpg --batch --passphrase '' --quick-gen-key key-submission@@example.net
409   $ gpg -K key-submission@@example.net
410 @end example
411
412 The output of the last command looks similar to this:
413
414 @example
415   sec   rsa3072 2016-08-30 [SC]
416         C0FCF8642D830C53246211400346653590B3795B
417   uid           [ultimate] key-submission@@example.net
418                 bxzcxpxk8h87z1k7bzk86xn5aj47intu@@example.net
419   ssb   rsa3072 2016-08-30 [E]
420 @end example
421
422 Take the fingerprint from that output and manually publish the key:
423
424 @example
425   $ gpg-wks-server --install-key C0FCF8642D830C53246211400346653590B3795B \
426   >                key-submission@@example.net
427 @end example
428
429 Finally that submission address needs to be redirected to a script
430 running @command{gpg-wks-server}.  The @command{procmail} command can
431 be used for this: Redirect the submission address to the user "webkey"
432 and put this into webkey's @file{.procmailrc}:
433
434 @example
435 :0
436 * !^From: webkey@@example.net
437 * !^X-WKS-Loop: webkey.example.net
438 |gpg-wks-server -v --receive \
439      --header X-WKS-Loop=webkey.example.net \
440      --from webkey@@example.net --send
441 @end example
442
443
444 @mansect see also
445 @ifset isman
446 @command{gpg-wks-client}(1)
447 @end ifset