summaryrefslogtreecommitdiffstats
path: root/doc/wks.texi
blob: 26d8b96f6587d6684b8be3f8b1f7ec13cf12718a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
@c wks.texi - man pages for the Web Key Service tools.
@c Copyright (C) 2017 g10 Code GmbH
@c Copyright (C) 2017 Bundesamt für Sicherheit in der Informationstechnik
@c This is part of the GnuPG manual.
@c For copying conditions, see the file GnuPG.texi.

@include defs.inc

@node Web Key Service
@chapter Web Key Service

GnuPG comes with tools used to maintain and access a Web Key
Directory.

@menu
* gpg-wks-client::        Send requests via WKS
* gpg-wks-server::        Server to provide the WKS.
@end menu

@c
@c  GPG-WKS-CLIENT
@c
@manpage gpg-wks-client.1
@node gpg-wks-client
@section Send requests via WKS
@ifset manverb
.B gpg-wks-client
\- Client for the Web Key Service
@end ifset

@mansect synopsis
@ifset manverb
.B gpg-wks-client
.RI [ options ]
.B \-\-supported
.I user-id
.br
.B gpg-wks-client
.RI [ options ]
.B \-\-check
.I user-id
.br
.B gpg-wks-client
.RI [ options ]
.B \-\-create
.I fingerprint
.I user-id
.br
.B gpg-wks-client
.RI [ options ]
.B \-\-receive
.br
.B gpg-wks-client
.RI [ options ]
.B \-\-read
.br
.B gpg-wks-client
.RI [ options ]
.B \-\-mirror
.br
.B gpg-wks-client
.RI [ options ]
.B \-\-install-key
.br
.B gpg-wks-client
.RI [ options ]
.B \-\-remove-key
.br
.B gpg-wks-client
.RI [ options ]
.B \-\-print-wkd-hash
.br
.B gpg-wks-client
.RI [ options ]
.B \-\-print-wkd-url
@end ifset

@mansect description
The @command{gpg-wks-client} is used to send requests to a Web Key
Service provider.  This is usually done to upload a key into a Web
Key Directory.

With the @option{--supported} command the caller can test whether a
site supports the Web Key Service.  The argument is an arbitrary
address in the to be tested domain. For example
@file{foo@@example.net}.  The command returns success if the Web Key
Service is supported.  The operation is silent; to get diagnostic
output use the option @option{--verbose}.  See option
@option{--with-colons} for a variant of this command.

With the @option{--check} command the caller can test whether a key
exists for a supplied mail address.  The command returns success if a
key is available.

The @option{--create} command is used to send a request for
publication in the Web Key Directory.  The arguments are the
fingerprint of the key and the user id to publish.  The output from
the command is a properly formatted mail with all standard headers.
This mail can be fed to @command{sendmail(8)} or any other tool to
actually send that mail.  If @command{sendmail(8)} is installed the
option @option{--send} can be used to directly send the created
request.  If the provider request a 'mailbox-only' user id and no such
user id is found, @command{gpg-wks-client} will try an additional user
id.

The @option{--receive} and @option{--read} commands are used to
process confirmation mails as send from the service provider.  The
former expects an encrypted MIME messages, the latter an already
decrypted MIME message.  The result of these commands are another mail
which can be send in the same way as the mail created with
@option{--create}.

The command @option{--install-key} manually installs a key into a
local directory (see option @option{-C}) reflecting the structure of a
WKD.  The arguments are a file with the keyblock and the user-id to
install.  If the first argument resembles a fingerprint the key is
taken from the current keyring; to force the use of a file, prefix the
first argument with "./".  If no arguments are given the parameters
are read from stdin; the expected format are lines with the
fingerprint and the mailbox separated by a space.  The command
@option{--remove-key} removes a key from that directory, its only
argument is a user-id.

The command @option{--mirror} is similar to @option{--install-key} but
takes the keys from the the LDAP server configured for Dirmngr.  If no
arguments are given all keys and user ids are installed.  If arguments
are given they are taken as domain names to limit the to be installed
keys.  The option @option{--blacklist} may be used to further limit
the to be installed keys.

The command @option{--print-wkd-hash} prints the WKD user-id identifiers
and the corresponding mailboxes from the user-ids given on the command
line or via stdin (one user-id per line).

The command @option{--print-wkd-url} prints the URLs used to fetch the
key for the given user-ids from WKD.  The meanwhile preferred format
with sub-domains is used here.

@mansect options
@noindent
@command{gpg-wks-client} understands these options:

@table @gnupgtabopt

@item --send
@opindex send
Directly send created mails using the @command{sendmail} command.
Requires installation of that command.

@item --with-colons
@opindex with-colons
This option has currently only an effect on the @option{--supported}
command.  If it is used all arguments on the command line are taken
as domain names and tested for WKD support.  The output format is one
line per domain with colon delimited fields.  The currently specified
fields are (future versions may specify additional fields):

@table @asis

  @item 1 - domain
  This is the domain name.  Although quoting is not required for valid
  domain names this field is specified to be quoted in standard C
  manner.

  @item 2 - WKD
  If the value is true the domain supports the Web Key Directory.

  @item 3 - WKS
  If the value is true the domain supports the Web Key Service
  protocol to upload keys to the directory.

  @item 4 - error-code
  This may contain an gpg-error code to describe certain
  failures.  Use @samp{gpg-error CODE} to explain the code.

  @item 5 - protocol-version
  The minimum protocol version supported by the server.

  @item 6 - auth-submit
  The auth-submit flag from the policy file of the server.

  @item 7 - mailbox-only
  The mailbox-only flag from the policy file of the server.
@end table



@item --output @var{file}
@itemx -o
@opindex output
Write the created mail to @var{file} instead of stdout.  Note that the
value @code{-} for @var{file} is the same as writing to stdout.  If
this option is used with the @option{--check} command and a key was
found it is written to the given file.

@item --status-fd @var{n}
@opindex status-fd
Write special status strings to the file descriptor @var{n}.
This program returns only the status messages SUCCESS or FAILURE which
are helpful when the caller uses a double fork approach and can't
easily get the return code of the process.

@item -C @var{dir}
@itemx --directory @var{dir}
@opindex directory
Use @var{dir} as top level directory for the commands
@option{--mirror}, @option{--install-key} and @option{--remove-key}.
The default is @file{openpgpkey}.


@item --blacklist @var{file}
@opindex blacklist
This option is used to exclude certain mail addresses from a mirror
operation.  The format of @var{file} is one mail address (just the
addrspec, e.g. "postel@@isi.edu") per line.  Empty lines and lines
starting with a '#' are ignored.

@item --add-revocs
@itemx --no-add-revocs
@opindex add-revocs
@opindex no-add-revocs
If enabled append revocation certificates for the same addrspec as
used in the WKD to the key.  Modern gpg version are able to import and
apply them for existing keys.  Note that when used with the
@option{--mirror} command the revocation are searched in the local
keyring and not in an LDAP directory.  The default is @option{--add-revocs}.

@item --verbose
@opindex verbose
Enable extra informational output.

@item --quiet
@opindex quiet
Disable almost all informational output.

@item --version
@opindex version
Print version of the program and exit.

@item --help
@opindex help
Display a brief help page and exit.

@end table


@mansect see also
@ifset isman
@command{gpg-wks-server}(1)
@end ifset


@c
@c  GPG-WKS-SERVER
@c
@manpage gpg-wks-server.1
@node gpg-wks-server
@section Provide the Web Key Service
@ifset manverb
.B gpg-wks-server
\- Server providing the Web Key Service
@end ifset

@mansect synopsis
@ifset manverb
.B gpg-wks-server
.RI [ options ]
.B \-\-receive
.br
.B gpg-wks-server
.RI [ options ]
.B \-\-cron
.br
.B gpg-wks-server
.RI [ options ]
.B \-\-list-domains
.br
.B gpg-wks-server
.RI [ options ]
.B \-\-check-key
.I user-id
.br
.B gpg-wks-server
.RI [ options ]
.B \-\-install-key
.I file
.I user-id
.br
.B gpg-wks-server
.RI [ options ]
.B \-\-remove-key
.I user-id
.br
.B gpg-wks-server
.RI [ options ]
.B \-\-revoke-key
.I user-id
@end ifset

@mansect description
The @command{gpg-wks-server} is a server side implementation of the
Web Key Service.  It receives requests for publication, sends
confirmation requests, receives confirmations, and published the key.
It also has features to ease the setup and maintenance of a Web Key
Directory.

When used with the command @option{--receive} a single Web Key Service
mail is processed.  Commonly this command is used with the option
@option{--send} to directly send the created mails back.  See below
for an installation example.

The command @option{--cron} is used for regular cleanup tasks.  For
example non-confirmed requested should be removed after their expire
time.  It is best to run this command once a day from a cronjob.

The command @option{--list-domains} prints all configured domains.
Further it creates missing directories for the configuration and
prints warnings pertaining to problems in the configuration.

The command @option{--check-key} (or just @option{--check}) checks
whether a key with the given user-id is installed.  The process returns
success in this case; to also print a diagnostic use the option
@option{-v}.  If the key is not installed a diagnostic is printed and
the process returns failure; to suppress the diagnostic, use option
@option{-q}.  More than one user-id can be given; see also option
@option{with-file}.

The command @option{--install-key} manually installs a key into the
WKD.  The arguments are a file with the keyblock and the user-id to
install.  If the first argument resembles a fingerprint the key is
taken from the current keyring; to force the use of a file, prefix the
first argument with "./".  If no arguments are given the parameters
are read from stdin; the expected format are lines with the
fingerprint and the mailbox separated by a space.

The command @option{--remove-key} uninstalls a key from the WKD.  The
process returns success in this case; to also print a diagnostic, use
option @option{-v}.  If the key is not installed a diagnostic is
printed and the process returns failure; to suppress the diagnostic,
use option @option{-q}.

The command @option{--revoke-key} is not yet functional.


@mansect options
@noindent
@command{gpg-wks-server} understands these options:

@table @gnupgtabopt

@item -C @var{dir}
@itemx --directory @var{dir}
@opindex directory
Use @var{dir} as top level directory for domains.  The default is
@file{/var/lib/gnupg/wks}.

@item --from @var{mailaddr}
@opindex from
Use @var{mailaddr} as the default sender address.

@item --header @var{name}=@var{value}
@opindex header
Add the mail header "@var{name}: @var{value}" to all outgoing mails.

@item --send
@opindex send
Directly send created mails using the @command{sendmail} command.
Requires installation of that command.

@item -o @var{file}
@itemx --output @var{file}
@opindex output
Write the created mail also to @var{file}. Note that the value
@code{-} for @var{file} would write it to stdout.

@item --with-dir
@opindex with-dir
When used with the command @option{--list-domains} print for each
installed domain the domain name and its directory name.

@item --with-file
@opindex with-file
When used with the command @option{--check-key} print for each user-id,
the address, 'i' for installed key or 'n' for not installed key, and
the filename.

@item --verbose
@opindex verbose
Enable extra informational output.

@item --quiet
@opindex quiet
Disable almost all informational output.

@item --version
@opindex version
Print version of the program and exit.

@item --help
@opindex help
Display a brief help page and exit.

@end table

@noindent
@mansect examples
@chapheading Examples

The Web Key Service requires a working directory to store keys
pending for publication.  As root create a working directory:

@example
  # mkdir /var/lib/gnupg/wks
  # chown webkey:webkey /var/lib/gnupg/wks
  # chmod 2750 /var/lib/gnupg/wks
@end example

Then under your webkey account create directories for all your
domains.  Here we do it for "example.net":

@example
  $ mkdir /var/lib/gnupg/wks/example.net
@end example

Finally run

@example
  $ gpg-wks-server --list-domains
@end example

to create the required sub-directories with the permissions set
correctly.  For each domain a submission address needs to be
configured.  All service mails are directed to that address.  It can
be the same address for all configured domains, for example:

@example
  $ cd /var/lib/gnupg/wks/example.net
  $ echo key-submission@@example.net >submission-address
@end example

The protocol requires that the key to be published is sent with an
encrypted mail to the service.  Thus you need to create a key for
the submission address:

@example
  $ gpg --batch --passphrase '' --quick-gen-key key-submission@@example.net
  $ gpg -K key-submission@@example.net
@end example

The output of the last command looks similar to this:

@example
  sec   rsa3072 2016-08-30 [SC]
        C0FCF8642D830C53246211400346653590B3795B
  uid           [ultimate] key-submission@@example.net
                bxzcxpxk8h87z1k7bzk86xn5aj47intu@@example.net
  ssb   rsa3072 2016-08-30 [E]
@end example

Take the fingerprint from that output and manually publish the key:

@example
  $ gpg-wks-server --install-key C0FCF8642D830C53246211400346653590B3795B \
  >                key-submission@@example.net
@end example

Finally that submission address needs to be redirected to a script
running @command{gpg-wks-server}.  The @command{procmail} command can
be used for this: Redirect the submission address to the user "webkey"
and put this into webkey's @file{.procmailrc}:

@example
:0
* !^From: webkey@@example.net
* !^X-WKS-Loop: webkey.example.net
|gpg-wks-server -v --receive \
     --header X-WKS-Loop=webkey.example.net \
     --from webkey@@example.net --send
@end example


@mansect see also
@ifset isman
@command{gpg-wks-client}(1)
@end ifset