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