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