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