doc: Make --check-sigs more prominent.
[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 arbitray
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}.
69
70 With the @option{--check} command the caller can test whether a key
71 exists for a supplied mail address.  The command returns success if a
72 key is available.
73
74 The @option{--create} command is used to send a request for
75 publication in the Web Key Directory.  The arguments are the
76 fingerprint of the key and the user id to publish.  The output from
77 the command is a properly formatted mail with all standard headers.
78 This mail can be fed to @command{sendmail(8)} or any other tool to
79 actually send that mail.  If @command{sendmail(8)} is installed the
80 option @option{--send} can be used to directly send the created
81 request.  If the provider request a 'mailbox-only' user id and no such
82 user id is found, @command{gpg-wks-client} will try an additional user
83 id.
84
85 The @option{--receive} and @option{--read} commands are used to
86 process confirmation mails as send from the service provider.  The
87 former expects an encrypted MIME messages, the latter an already
88 decrypted MIME message.  The result of these commands are another mail
89 which can be send in the same way as the mail created with
90 @option{--create}.
91
92 @command{gpg-wks-client} is not commonly invoked directly and thus it
93 is not installed in the bin directory.  Here is an example how it can
94 be invoked manually to check for a Web Key Directory entry for
95 @file{foo@@example.org}:
96
97 @example
98 $(gpgconf --list-dirs libexecdir)/gpg-wks-client --check foo@@example.net
99 @end example
100
101 @mansect options
102 @noindent
103 @command{gpg-wks-client} understands these options:
104
105 @table @gnupgtabopt
106
107 @item --send
108 @opindex send
109 Directly send created mails using the @command{sendmail} command.
110 Requires installation of that command.
111
112 @item --output @var{file}
113 @itemx -o
114 @opindex output
115 Write the created mail to @var{file} instead of stdout.  Note that the
116 value @code{-} for @var{file} is the same as writing to stdout.
117
118 @item --status-fd @var{n}
119 @opindex status-fd
120 Write special status strings to the file descriptor @var{n}.
121 This program returns only the status messages SUCCESS or FAILURE which
122 are helpful when the caller uses a double fork approach and can't
123 easily get the return code of the process.
124
125 @item --verbose
126 @opindex verbose
127 Enable extra informational output.
128
129 @item --quiet
130 @opindex quiet
131 Disable almost all informational output.
132
133 @item --version
134 @opindex version
135 Print version of the program and exit.
136
137 @item --help
138 @opindex help
139 Display a brief help page and exit.
140
141 @end table
142
143
144 @mansect see also
145 @ifset isman
146 @command{gpg-wks-server}(1)
147 @end ifset
148
149
150 @c
151 @c  GPG-WKS-SERVER
152 @c
153 @manpage gpg-wks-server.1
154 @node gpg-wks-server
155 @section Provide the Web Key Service
156 @ifset manverb
157 .B gpg-wks-server
158 \- Server providing the Web Key Service
159 @end ifset
160
161 @mansect synopsis
162 @ifset manverb
163 .B gpg-wks-server
164 .RI [ options ]
165 .B \-\-receive
166 .br
167 .B gpg-wks-server
168 .RI [ options ]
169 .B \-\-cron
170 .br
171 .B gpg-wks-server
172 .RI [ options ]
173 .B \-\-list-domains
174 .br
175 .B gpg-wks-server
176 .RI [ options ]
177 .B \-\-install-key
178 .I file
179 .br
180 .B gpg-wks-server
181 .RI [ options ]
182 .B \-\-remove-key
183 .I mailaddr
184 .br
185 .B gpg-wks-server
186 .RI [ options ]
187 .B \-\-revoke-key
188 .I mailaddr
189 @end ifset
190
191 @mansect description
192 The @command{gpg-wks-server} is a server site implementation of the
193 Web Key Service.  It receives requests for publication, sends
194 confirmation requests, receives confirmations, and published the key.
195 It also has features to ease the setup and maintenance of a Web Key
196 Directory.
197
198 When used with the command @option{--receive} a single Web Key Service
199 mail is processed.  Commonly this command is used with the option
200 @option{--send} to directly send the crerated mails back.  See below
201 for an installation example.
202
203 The command @option{--cron} is used for regualr cleanup tasks.  For
204 example non-confirmed requested should be removed after their expire
205 time.  It is best to run this command once a day from a cronjob.
206
207 The command @option{--list-domains} prints all configured domains.
208 Further it creates missing directories for the configuration and
209 prints warnings pertaining to problems in the configuration.
210
211 The commands @option{--install-key}, @option{--remove-key}, and
212 @option{--revoke-key} are not yet functional.
213
214
215 @mansect options
216 @noindent
217 @command{gpg-wks-server} understands these options:
218
219 @table @gnupgtabopt
220
221 @item --from @var{mailaddr}
222 @opindex from
223 Use @var{mailaddr} as the default sender address.
224
225 @item --header @var{name}=@var{value}
226 @opindex header
227 Add the mail header "@var{name}: @var{value}" to all outgoing mails.
228
229 @item --send
230 @opindex send
231 Directly send created mails using the @command{sendmail} command.
232 Requires installation of that command.
233
234 @item --output @var{file}
235 @itemx -o
236 @opindex output
237 Write the created mail also to @var{file}. Note that the value
238 @code{-} for @var{file} would write it to stdout.
239
240 @item --verbose
241 @opindex verbose
242 Enable extra informational output.
243
244 @item --quiet
245 @opindex quiet
246 Disable almost all informational output.
247
248 @item --version
249 @opindex version
250 Print version of the program and exit.
251
252 @item --help
253 @opindex help
254 Display a brief help page and exit.
255
256 @end table
257
258 @noindent
259 @mansect examples
260 @chapheading Examples
261
262 The Web Key Service requires a working directory to store keys
263 pending for publication.  As root create a working directory:
264
265 @example
266   # mkdir /var/lib/gnupg/wks
267   # chown webkey:webkey /var/lib/gnupg/wks
268   # chmod 2750 /var/lib/gnupg/wks
269 @end example
270
271 Then under your webkey account create directories for all your
272 domains.  Here we do it for "example.net":
273
274 @example
275   $ mkdir /var/lib/gnupg/wks/example.net
276 @end example
277
278 Finally run
279
280 @example
281   $ gpg-wks-server --list-domains
282 @end example
283
284 to create the required sub-directories with the permission set
285 correctly.  For each domain a submission address needs to be
286 configured.  All service mails are directed to that address.  It can
287 be the same address for all configured domains, for example:
288
289 @example
290   $ cd /var/lib/gnupg/wks/example.net
291   $ echo key-submission@@example.net >submission-address
292 @end example
293
294 The protocol requires that the key to be published is sent with an
295 encrypted mail to the service.  Thus you need to create a key for
296 the submission address:
297
298 @example
299   $ gpg --batch --passphrase '' --quick-gen-key key-submission@@example.net
300   $ gpg --with-wkd-hash -K key-submission@@example.net
301 @end example
302
303 The output of the last command looks similar to this:
304
305 @example
306   sec   rsa2048 2016-08-30 [SC]
307         C0FCF8642D830C53246211400346653590B3795B
308   uid           [ultimate] key-submission@@example.net
309                 bxzcxpxk8h87z1k7bzk86xn5aj47intu@@example.net
310   ssb   rsa2048 2016-08-30 [E]
311 @end example
312
313 Take the hash of the string "key-submission", which is
314 "bxzcxpxk8h87z1k7bzk86xn5aj47intu" and manually publish that key:
315
316 @example
317   $ gpg --export-options export-minimal --export \
318   >  -o /var/lib/gnupg/wks/example.net/hu/bxzcxpxk8h87z1k7bzk86xn5aj47intu \
319   >  key-submission@@example.new
320 @end example
321
322 Make sure that the created file is world readable.
323
324 Finally that submission address needs to be redirected to a script
325 running @command{gpg-wks-server}.  The @command{procmail} command can
326 be used for this: Redirect the submission address to the user "webkey"
327 and put this into webkey's @file{.procmailrc}:
328
329 @example
330 :0
331 * !^From: webkey@@example.net
332 * !^X-WKS-Loop: webkey.example.net
333 |gpg-wks-server -v --receive \
334      --header X-WKS-Loop=webkey.example.net \
335      --from webkey@@example.net --send
336 @end example
337
338
339 @mansect see also
340 @ifset isman
341 @command{gpg-wks-client}(1)
342 @end ifset