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