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