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 \-\-install-key
 178 .I file
 179 .br
 180 .B gpg-wks-server
 181 .RI [ options ]
 182 .B \-\-remove-key
 183 .I mailaddr
 184 .br
 185 .B gpg-wks-server
 186 .RI [ options ]
 187 .B \-\-revoke-key
 188 .I mailaddr
 189 @end ifset
 190
 191 @mansect description
 192 The @command{gpg-wks-server} is a server site implementation of the
 193 Web Key Service.  It receives requests for publication, sends
 194 confirmation requests, receives confirmations, and published the key.
 195 It also has features to ease the setup and maintenance of a Web Key
 196 Directory.
 197
 198 When used with the command @option{--receive} a single Web Key Service
 199 mail is processed.  Commonly this command is used with the option
 200 @option{--send} to directly send the crerated mails back.  See below
 201 for an installation example.
 202
 203 The command @option{--cron} is used for regualr cleanup tasks.  For
 204 example non-confirmed requested should be removed after their expire
 205 time.  It is best to run this command once a day from a cronjob.
 206
 207 The command @option{--list-domains} prints all configured domains.
 208 Further it creates missing directories for the configuration and
 209 prints warnings pertaining to problems in the configuration.
 210
 211 The commands @option{--install-key}, @option{--remove-key}, and
 212 @option{--revoke-key} are not yet functional.
 213
 214
 215 @mansect options
 216 @noindent
 217 @command{gpg-wks-server} understands these options:
 218
 219 @table @gnupgtabopt
 220
 221 @item --from @var{mailaddr}
 222 @opindex from
 223 Use @var{mailaddr} as the default sender address.
 224
 225 @item --header @var{name}=@var{value}
 226 @opindex header
 227 Add the mail header "@var{name}: @var{value}" to all outgoing mails.
 228
 229 @item --send
 230 @opindex send
 231 Directly send created mails using the @command{sendmail} command.
 232 Requires installation of that command.
 233
 234 @item --output @var{file}
 235 @itemx -o
 236 @opindex output
 237 Write the created mail also to @var{file}. Note that the value
 238 @code{-} for @var{file} would write it to stdout.
 239
 240 @item --verbose
 241 @opindex verbose
 242 Enable extra informational output.
 243
 244 @item --quiet
 245 @opindex quiet
 246 Disable almost all informational output.
 247
 248 @item --version
 249 @opindex version
 250 Print version of the program and exit.
 251
 252 @item --help
 253 @opindex help
 254 Display a brief help page and exit.
 255
 256 @end table
 257
 258 @noindent
 259 @mansect examples
 260 @chapheading Examples
 261
 262 The Web Key Service requires a working directory to store keys
 263 pending for publication.  As root create a working directory:
 264
 265 @example
 266   # mkdir /var/lib/gnupg/wks
 267   # chown webkey:webkey /var/lib/gnupg/wks
 268   # chmod 2750 /var/lib/gnupg/wks
 269 @end example
 270
 271 Then under your webkey account create directories for all your
 272 domains.  Here we do it for "example.net":
 273
 274 @example
 275   $ mkdir /var/lib/gnupg/wks/example.net
 276 @end example
 277
 278 Finally run
 279
 280 @example
 281   $ gpg-wks-server --list-domains
 282 @end example
 283
 284 to create the required sub-directories with the permission set
 285 correctly.  For each domain a submission address needs to be
 286 configured.  All service mails are directed to that address.  It can
 287 be the same address for all configured domains, for example:
 288
 289 @example
 290   $ cd /var/lib/gnupg/wks/example.net
 291   $ echo key-submission@@example.net >submission-address
 292 @end example
 293
 294 The protocol requires that the key to be published is sent with an
 295 encrypted mail to the service.  Thus you need to create a key for
 296 the submission address:
 297
 298 @example
 299   $ gpg --batch --passphrase '' --quick-gen-key key-submission@@example.net
 300   $ gpg --with-wkd-hash -K key-submission@@example.net
 301 @end example
 302
 303 The output of the last command looks similar to this:
 304
 305 @example
 306   sec   rsa2048 2016-08-30 [SC]
 307         C0FCF8642D830C53246211400346653590B3795B
 308   uid           [ultimate] key-submission@@example.net
 309                 bxzcxpxk8h87z1k7bzk86xn5aj47intu@@example.net
 310   ssb   rsa2048 2016-08-30 [E]
 311 @end example
 312
 313 Take the hash of the string "key-submission", which is
 314 "bxzcxpxk8h87z1k7bzk86xn5aj47intu" and manually publish that key:
 315
 316 @example
 317   $ gpg --export-options export-minimal --export \
 318   >  -o /var/lib/gnupg/wks/example.net/hu/bxzcxpxk8h87z1k7bzk86xn5aj47intu \
 319   >  key-submission@@example.new
 320 @end example
 321
 322 Make sure that the created file is world readable.
 323
 324 Finally that submission address needs to be redirected to a script
 325 running @command{gpg-wks-server}.  The @command{procmail} command can
 326 be used for this: Redirect the submission address to the user "webkey"
 327 and put this into webkey's @file{.procmailrc}:
 328
 329 @example
 330 :0
 331 * !^From: webkey@@example.net
 332 * !^X-WKS-Loop: webkey.example.net
 333 |gpg-wks-server -v --receive \
 334      --header X-WKS-Loop=webkey.example.net \
 335      --from webkey@@example.net --send
 336 @end example
 337
 338
 339 @mansect see also
 340 @ifset isman
 341 @command{gpg-wks-client}(1)
 342 @end ifset