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