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