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