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}.
  69
  70 With the @option{--check} command the caller can test whether a key
  71 exists for a supplied mail address.  The command returns success if a
  72 key is available.
  73
  74 The @option{--create} command is used to send a request for
  75 publication in the Web Key Directory.  The arguments are the
  76 fingerprint of the key and the user id to publish.  The output from
  77 the command is a properly formatted mail with all standard headers.
  78 This mail can be fed to @command{sendmail(8)} or any other tool to
  79 actually send that mail.  If @command{sendmail(8)} is installed the
  80 option @option{--send} can be used to directly send the created
  81 request.  If the provider request a 'mailbox-only' user id and no such
  82 user id is found, @command{gpg-wks-client} will try an additional user
  83 id.
  84
  85 The @option{--receive} and @option{--read} commands are used to
  86 process confirmation mails as send from the service provider.  The
  87 former expects an encrypted MIME messages, the latter an already
  88 decrypted MIME message.  The result of these commands are another mail
  89 which can be send in the same way as the mail created with
  90 @option{--create}.
  91
  92 @command{gpg-wks-client} is not commonly invoked directly and thus it
  93 is not installed in the bin directory.  Here is an example how it can
  94 be invoked manually to check for a Web Key Directory entry for
  95 @file{foo@@example.org}:
  96
  97 @example
  98 $(gpgconf --list-dirs libexecdir)/gpg-wks-client --check foo@@example.net
  99 @end example
 100
 101 @mansect options
 102 @noindent
 103 @command{gpg-wks-client} understands these options:
 104
 105 @table @gnupgtabopt
 106
 107 @item --send
 108 @opindex send
 109 Directly send created mails using the @command{sendmail} command.
 110 Requires installation of that command.
 111
 112 @item --output @var{file}
 113 @itemx -o
 114 @opindex output
 115 Write the created mail to @var{file} instead of stdout.  Note that the
 116 value @code{-} for @var{file} is the same as writing to stdout.
 117
 118 @item --status-fd @var{n}
 119 @opindex status-fd
 120 Write special status strings to the file descriptor @var{n}.
 121 This program returns only the status messages SUCCESS or FAILURE which
 122 are helpful when the caller uses a double fork approach and can't
 123 easily get the return code of the process.
 124
 125 @item --verbose
 126 @opindex verbose
 127 Enable extra informational output.
 128
 129 @item --quiet
 130 @opindex quiet
 131 Disable almost all informational output.
 132
 133 @item --version
 134 @opindex version
 135 Print version of the program and exit.
 136
 137 @item --help
 138 @opindex help
 139 Display a brief help page and exit.
 140
 141 @end table
 142
 143
 144 @mansect see also
 145 @ifset isman
 146 @command{gpg-wks-server}(1)
 147 @end ifset
 148
 149
 150 @c
 151 @c  GPG-WKS-SERVER
 152 @c
 153 @manpage gpg-wks-server.1
 154 @node gpg-wks-server
 155 @section Provide the Web Key Service
 156 @ifset manverb
 157 .B gpg-wks-server
 158 \- Server providing the Web Key Service
 159 @end ifset
 160
 161 @mansect synopsis
 162 @ifset manverb
 163 .B gpg-wks-server
 164 .RI [ options ]
 165 .B \-\-receive
 166 .br
 167 .B gpg-wks-server
 168 .RI [ options ]
 169 .B \-\-cron
 170 .br
 171 .B gpg-wks-server
 172 .RI [ options ]
 173 .B \-\-list-domains
 174 .br
 175 .B gpg-wks-server
 176 .RI [ options ]
 177 .B \-\-check-key
 178 .I user-id
 179 .br
 180 .B gpg-wks-server
 181 .RI [ options ]
 182 .B \-\-install-key
 183 .I file
 184 .I user-id
 185 .br
 186 .B gpg-wks-server
 187 .RI [ options ]
 188 .B \-\-remove-key
 189 .I user-id
 190 .br
 191 .B gpg-wks-server
 192 .RI [ options ]
 193 .B \-\-revoke-key
 194 .I user-id
 195 @end ifset
 196
 197 @mansect description
 198 The @command{gpg-wks-server} is a server site implementation of the
 199 Web Key Service.  It receives requests for publication, sends
 200 confirmation requests, receives confirmations, and published the key.
 201 It also has features to ease the setup and maintenance of a Web Key
 202 Directory.
 203
 204 When used with the command @option{--receive} a single Web Key Service
 205 mail is processed.  Commonly this command is used with the option
 206 @option{--send} to directly send the crerated mails back.  See below
 207 for an installation example.
 208
 209 The command @option{--cron} is used for regualr cleanup tasks.  For
 210 example non-confirmed requested should be removed after their expire
 211 time.  It is best to run this command once a day from a cronjob.
 212
 213 The command @option{--list-domains} prints all configured domains.
 214 Further it creates missing directories for the configuration and
 215 prints warnings pertaining to problems in the configuration.
 216
 217 The command @option{--check-key} (or just @option{--check}) checks
 218 whether a key with the given user-id is installed.  The process return
 219 success in this case; to also print a diagnostic, use option
 220 @option{-v}.  If the key is not installed a diagnostics is printed and
 221 the process returns failure; to suppress the diagnostic, use option
 222 @option{-q}.  More than one user-id can be given; see also option
 223 @option{with-file}.
 224
 225 The command @option{--install-key} manually installs a key into the
 226 WKD.  The arguments are a file with the keyblock and the user-id to
 227 install.  If the first argument resembles a fingerprint the key is
 228 taken from the current keyring; to force the use of a file, prefix the
 229 first argument with "./".
 230
 231 The command @option{--remove-key} uninstalls a key from the WKD.  The
 232 process returns success in this case; to also print a diagnostic, use
 233 option @option{-v}.  If the key is not installed a diagnostic is
 234 printed and the process returns failure; to suppress the diagnostic,
 235 use option @option{-q}.
 236
 237 The command @option{--revoke-key} is not yet functional.
 238
 239
 240 @mansect options
 241 @noindent
 242 @command{gpg-wks-server} understands these options:
 243
 244 @table @gnupgtabopt
 245
 246 @item --from @var{mailaddr}
 247 @opindex from
 248 Use @var{mailaddr} as the default sender address.
 249
 250 @item --header @var{name}=@var{value}
 251 @opindex header
 252 Add the mail header "@var{name}: @var{value}" to all outgoing mails.
 253
 254 @item --send
 255 @opindex send
 256 Directly send created mails using the @command{sendmail} command.
 257 Requires installation of that command.
 258
 259 @item --output @var{file}
 260 @itemx -o
 261 @opindex output
 262 Write the created mail also to @var{file}. Note that the value
 263 @code{-} for @var{file} would write it to stdout.
 264
 265 @item --with-dir
 266 @opindex with-dir
 267 Also print the directory name for each domain listed by command
 268 @option{--list-domains}.
 269
 270 @item --with-file
 271 @opindex with-file
 272 With command @option{--check-key} print for each user-id, the address,
 273 'i' for installed key or 'n' for not installed key, and the filename.
 274
 275 @item --verbose
 276 @opindex verbose
 277 Enable extra informational output.
 278
 279 @item --quiet
 280 @opindex quiet
 281 Disable almost all informational output.
 282
 283 @item --version
 284 @opindex version
 285 Print version of the program and exit.
 286
 287 @item --help
 288 @opindex help
 289 Display a brief help page and exit.
 290
 291 @end table
 292
 293 @noindent
 294 @mansect examples
 295 @chapheading Examples
 296
 297 The Web Key Service requires a working directory to store keys
 298 pending for publication.  As root create a working directory:
 299
 300 @example
 301   # mkdir /var/lib/gnupg/wks
 302   # chown webkey:webkey /var/lib/gnupg/wks
 303   # chmod 2750 /var/lib/gnupg/wks
 304 @end example
 305
 306 Then under your webkey account create directories for all your
 307 domains.  Here we do it for "example.net":
 308
 309 @example
 310   $ mkdir /var/lib/gnupg/wks/example.net
 311 @end example
 312
 313 Finally run
 314
 315 @example
 316   $ gpg-wks-server --list-domains
 317 @end example
 318
 319 to create the required sub-directories with the permission set
 320 correctly.  For each domain a submission address needs to be
 321 configured.  All service mails are directed to that address.  It can
 322 be the same address for all configured domains, for example:
 323
 324 @example
 325   $ cd /var/lib/gnupg/wks/example.net
 326   $ echo key-submission@@example.net >submission-address
 327 @end example
 328
 329 The protocol requires that the key to be published is sent with an
 330 encrypted mail to the service.  Thus you need to create a key for
 331 the submission address:
 332
 333 @example
 334   $ gpg --batch --passphrase '' --quick-gen-key key-submission@@example.net
 335   $ gpg -K key-submission@@example.net
 336 @end example
 337
 338 The output of the last command looks similar to this:
 339
 340 @example
 341   sec   rsa2048 2016-08-30 [SC]
 342         C0FCF8642D830C53246211400346653590B3795B
 343   uid           [ultimate] key-submission@@example.net
 344   ssb   rsa2048 2016-08-30 [E]
 345 @end example
 346
 347 Take the fingerprint from that output and manually publish the key:
 348
 349 @example
 350   $ gpg-wks-server --install-key C0FCF8642D830C53246211400346653590B3795B \
 351   >                key-submission@@example.net
 352 @end example
 353
 354 Finally that submission address needs to be redirected to a script
 355 running @command{gpg-wks-server}.  The @command{procmail} command can
 356 be used for this: Redirect the submission address to the user "webkey"
 357 and put this into webkey's @file{.procmailrc}:
 358
 359 @example
 360 :0
 361 * !^From: webkey@@example.net
 362 * !^X-WKS-Loop: webkey.example.net
 363 |gpg-wks-server -v --receive \
 364      --header X-WKS-Loop=webkey.example.net \
 365      --from webkey@@example.net --send
 366 @end example
 367
 368
 369 @mansect see also
 370 @ifset isman
 371 @command{gpg-wks-client}(1)
 372 @end ifset