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