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