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