1 files changed, 481 insertions, 0 deletions
diff --git a/doc/wks.texi b/doc/wks.texi
new file mode 100644
index 0000000..e398ccb
--- /dev/null
+++ b/doc/wks.texi
@@ -0,0 +1,481 @@
+@c wks.texi - man pages for the Web Key Service tools.
+@c Copyright (C) 2017 g10 Code GmbH
+@c Copyright (C) 2017 Bundesamt für Sicherheit in der Informationstechnik
+@c This is part of the GnuPG manual.
+@c For copying conditions, see the file GnuPG.texi.
+
+@include defs.inc
+
+@node Web Key Service
+@chapter Web Key Service
+
+GnuPG comes with tools used to maintain and access a Web Key
+Directory.
+
+@menu
+* gpg-wks-client::        Send requests via WKS
+* gpg-wks-server::        Server to provide the WKS.
+@end menu
+
+@c
+@c  GPG-WKS-CLIENT
+@c
+@manpage gpg-wks-client.1
+@node gpg-wks-client
+@section Send requests via WKS
+@ifset manverb
+.B gpg-wks-client
+\- Client for the Web Key Service
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B gpg-wks-client
+.RI [ options ]
+.B \-\-supported
+.I user-id
+.br
+.B gpg-wks-client
+.RI [ options ]
+.B \-\-check
+.I user-id
+.br
+.B gpg-wks-client
+.RI [ options ]
+.B \-\-create
+.I fingerprint
+.I user-id
+.br
+.B gpg-wks-client
+.RI [ options ]
+.B \-\-receive
+.br
+.B gpg-wks-client
+.RI [ options ]
+.B \-\-read
+.br
+.B gpg-wks-client
+.RI [ options ]
+.B \-\-mirror
+.br
+.B gpg-wks-client
+.RI [ options ]
+.B \-\-install-key
+.br
+.B gpg-wks-client
+.RI [ options ]
+.B \-\-remove-key
+.br
+.B gpg-wks-client
+.RI [ options ]
+.B \-\-print-wkd-hash
+.br
+.B gpg-wks-client
+.RI [ options ]
+.B \-\-print-wkd-url
+@end ifset
+
+@mansect description
+The @command{gpg-wks-client} is used to send requests to a Web Key
+Service provider.  This is usually done to upload a key into a Web
+Key Directory.
+
+With the @option{--supported} command the caller can test whether a
+site supports the Web Key Service.  The argument is an arbitrary
+address in the to be tested domain. For example
+@file{foo@@example.net}.  The command returns success if the Web Key
+Service is supported.  The operation is silent; to get diagnostic
+output use the option @option{--verbose}.  See option
+@option{--with-colons} for a variant of this command.
+
+With the @option{--check} command the caller can test whether a key
+exists for a supplied mail address.  The command returns success if a
+key is available.
+
+The @option{--create} command is used to send a request for
+publication in the Web Key Directory.  The arguments are the
+fingerprint of the key and the user id to publish.  The output from
+the command is a properly formatted mail with all standard headers.
+This mail can be fed to @command{sendmail(8)} or any other tool to
+actually send that mail.  If @command{sendmail(8)} is installed the
+option @option{--send} can be used to directly send the created
+request.  If the provider request a 'mailbox-only' user id and no such
+user id is found, @command{gpg-wks-client} will try an additional user
+id.
+
+The @option{--receive} and @option{--read} commands are used to
+process confirmation mails as send from the service provider.  The
+former expects an encrypted MIME messages, the latter an already
+decrypted MIME message.  The result of these commands are another mail
+which can be send in the same way as the mail created with
+@option{--create}.
+
+The command @option{--install-key} manually installs a key into a
+local directory (see option @option{-C}) reflecting the structure of a
+WKD.  The arguments are a file with the keyblock and the user-id to
+install.  If the first argument resembles a fingerprint the key is
+taken from the current keyring; to force the use of a file, prefix the
+first argument with "./".  If no arguments are given the parameters
+are read from stdin; the expected format are lines with the
+fingerprint and the mailbox separated by a space.  The command
+@option{--remove-key} removes a key from that directory, its only
+argument is a user-id.
+
+The command @option{--mirror} is similar to @option{--install-key} but
+takes the keys from the the LDAP server configured for Dirmngr.  If no
+arguments are given all keys and user ids are installed.  If arguments
+are given they are taken as domain names to limit the to be installed
+keys.  The option @option{--blacklist} may be used to further limit
+the to be installed keys.
+
+The command @option{--print-wkd-hash} prints the WKD user-id identifiers
+and the corresponding mailboxes from the user-ids given on the command
+line or via stdin (one user-id per line).
+
+The command @option{--print-wkd-url} prints the URLs used to fetch the
+key for the given user-ids from WKD.  The meanwhile preferred format
+with sub-domains is used here.
+
+@command{gpg-wks-client} is not commonly invoked directly and thus it
+is not installed in the bin directory.  Here is an example how it can
+be invoked manually to check for a Web Key Directory entry for
+@file{foo@@example.org}:
+
+@example
+$(gpgconf --list-dirs libexecdir)/gpg-wks-client --check foo@@example.net
+@end example
+
+@mansect options
+@noindent
+@command{gpg-wks-client} understands these options:
+
+@table @gnupgtabopt
+
+@item --send
+@opindex send
+Directly send created mails using the @command{sendmail} command.
+Requires installation of that command.
+
+@item --with-colons
+@opindex with-colons
+This option has currently only an effect on the @option{--supported}
+command.  If it is used all arguments on the command line are taken
+as domain names and tested for WKD support.  The output format is one
+line per domain with colon delimited fields.  The currently specified
+fields are (future versions may specify additional fields):
+
+@table @asis
+
+  @item 1 - domain
+  This is the domain name.  Although quoting is not required for valid
+  domain names this field is specified to be quoted in standard C
+  manner.
+
+  @item 2 - WKD
+  If the value is true the domain supports the Web Key Directory.
+
+  @item 3 - WKS
+  If the value is true the domain supports the Web Key Service
+  protocol to upload keys to the directory.
+
+  @item 4 - error-code
+  This may contain an gpg-error code to describe certain
+  failures.  Use @samp{gpg-error CODE} to explain the code.
+
+  @item 5 - protocol-version
+  The minimum protocol version supported by the server.
+
+  @item 6 - auth-submit
+  The auth-submit flag from the policy file of the server.
+
+  @item 7 - mailbox-only
+  The mailbox-only flag from the policy file of the server.
+@end table
+
+
+
+@item --output @var{file}
+@itemx -o
+@opindex output
+Write the created mail to @var{file} instead of stdout.  Note that the
+value @code{-} for @var{file} is the same as writing to stdout.
+
+@item --status-fd @var{n}
+@opindex status-fd
+Write special status strings to the file descriptor @var{n}.
+This program returns only the status messages SUCCESS or FAILURE which
+are helpful when the caller uses a double fork approach and can't
+easily get the return code of the process.
+
+@item -C @var{dir}
+@itemx --directory @var{dir}
+@opindex directory
+Use @var{dir} as top level directory for the commands
+@option{--mirror}, @option{--install-key} and @option{--remove-key}.
+The default is @file{openpgpkey}.
+
+
+@item --blacklist @var{file}
+@opindex blacklist
+This option is used to exclude certain mail addresses from a mirror
+operation.  The format of @var{file} is one mail address (just the
+addrspec, e.g. "postel@@isi.edu") per line.  Empty lines and lines
+starting with a '#' are ignored.
+
+@item --verbose
+@opindex verbose
+Enable extra informational output.
+
+@item --quiet
+@opindex quiet
+Disable almost all informational output.
+
+@item --version
+@opindex version
+Print version of the program and exit.
+
+@item --help
+@opindex help
+Display a brief help page and exit.
+
+@end table
+
+
+@mansect see also
+@ifset isman
+@command{gpg-wks-server}(1)
+@end ifset
+
+
+@c
+@c  GPG-WKS-SERVER
+@c
+@manpage gpg-wks-server.1
+@node gpg-wks-server
+@section Provide the Web Key Service
+@ifset manverb
+.B gpg-wks-server
+\- Server providing the Web Key Service
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B gpg-wks-server
+.RI [ options ]
+.B \-\-receive
+.br
+.B gpg-wks-server
+.RI [ options ]
+.B \-\-cron
+.br
+.B gpg-wks-server
+.RI [ options ]
+.B \-\-list-domains
+.br
+.B gpg-wks-server
+.RI [ options ]
+.B \-\-check-key
+.I user-id
+.br
+.B gpg-wks-server
+.RI [ options ]
+.B \-\-install-key
+.I file
+.I user-id
+.br
+.B gpg-wks-server
+.RI [ options ]
+.B \-\-remove-key
+.I user-id
+.br
+.B gpg-wks-server
+.RI [ options ]
+.B \-\-revoke-key
+.I user-id
+@end ifset
+
+@mansect description
+The @command{gpg-wks-server} is a server site implementation of the
+Web Key Service.  It receives requests for publication, sends
+confirmation requests, receives confirmations, and published the key.
+It also has features to ease the setup and maintenance of a Web Key
+Directory.
+
+When used with the command @option{--receive} a single Web Key Service
+mail is processed.  Commonly this command is used with the option
+@option{--send} to directly send the crerated mails back.  See below
+for an installation example.
+
+The command @option{--cron} is used for regualr cleanup tasks.  For
+example non-confirmed requested should be removed after their expire
+time.  It is best to run this command once a day from a cronjob.
+
+The command @option{--list-domains} prints all configured domains.
+Further it creates missing directories for the configuration and
+prints warnings pertaining to problems in the configuration.
+
+The command @option{--check-key} (or just @option{--check}) checks
+whether a key with the given user-id is installed.  The process returns
+success in this case; to also print a diagnostic use the option
+@option{-v}.  If the key is not installed a diagnostic is printed and
+the process returns failure; to suppress the diagnostic, use option
+@option{-q}.  More than one user-id can be given; see also option
+@option{with-file}.
+
+The command @option{--install-key} manually installs a key into the
+WKD.  The arguments are a file with the keyblock and the user-id to
+install.  If the first argument resembles a fingerprint the key is
+taken from the current keyring; to force the use of a file, prefix the
+first argument with "./".  If no arguments are given the parameters
+are read from stdin; the expected format are lines with the
+fingerprint and the mailbox separated by a space.
+
+The command @option{--remove-key} uninstalls a key from the WKD.  The
+process returns success in this case; to also print a diagnostic, use
+option @option{-v}.  If the key is not installed a diagnostic is
+printed and the process returns failure; to suppress the diagnostic,
+use option @option{-q}.
+
+The command @option{--revoke-key} is not yet functional.
+
+
+@mansect options
+@noindent
+@command{gpg-wks-server} understands these options:
+
+@table @gnupgtabopt
+
+@item -C @var{dir}
+@itemx --directory @var{dir}
+@opindex directory
+Use @var{dir} as top level directory for domains.  The default is
+@file{/var/lib/gnupg/wks}.
+
+@item --from @var{mailaddr}
+@opindex from
+Use @var{mailaddr} as the default sender address.
+
+@item --header @var{name}=@var{value}
+@opindex header
+Add the mail header "@var{name}: @var{value}" to all outgoing mails.
+
+@item --send
+@opindex send
+Directly send created mails using the @command{sendmail} command.
+Requires installation of that command.
+
+@item -o @var{file}
+@itemx --output @var{file}
+@opindex output
+Write the created mail also to @var{file}. Note that the value
+@code{-} for @var{file} would write it to stdout.
+
+@item --with-dir
+@opindex with-dir
+When used with the command @option{--list-domains} print for each
+installed domain the domain name and its directory name.
+
+@item --with-file
+@opindex with-file
+When used with the command @option{--check-key} print for each user-id,
+the address, 'i' for installed key or 'n' for not installed key, and
+the filename.
+
+@item --verbose
+@opindex verbose
+Enable extra informational output.
+
+@item --quiet
+@opindex quiet
+Disable almost all informational output.
+
+@item --version
+@opindex version
+Print version of the program and exit.
+
+@item --help
+@opindex help
+Display a brief help page and exit.
+
+@end table
+
+@noindent
+@mansect examples
+@chapheading Examples
+
+The Web Key Service requires a working directory to store keys
+pending for publication.  As root create a working directory:
+
+@example
+  # mkdir /var/lib/gnupg/wks
+  # chown webkey:webkey /var/lib/gnupg/wks
+  # chmod 2750 /var/lib/gnupg/wks
+@end example
+
+Then under your webkey account create directories for all your
+domains.  Here we do it for "example.net":
+
+@example
+  $ mkdir /var/lib/gnupg/wks/example.net
+@end example
+
+Finally run
+
+@example
+  $ gpg-wks-server --list-domains
+@end example
+
+to create the required sub-directories with the permissions set
+correctly.  For each domain a submission address needs to be
+configured.  All service mails are directed to that address.  It can
+be the same address for all configured domains, for example:
+
+@example
+  $ cd /var/lib/gnupg/wks/example.net
+  $ echo key-submission@@example.net >submission-address
+@end example
+
+The protocol requires that the key to be published is send with an
+encrypted mail to the service.  Thus you need to create a key for
+the submission address:
+
+@example
+  $ gpg --batch --passphrase '' --quick-gen-key key-submission@@example.net
+  $ gpg -K key-submission@@example.net
+@end example
+
+The output of the last command looks similar to this:
+
+@example
+  sec   rsa2048 2016-08-30 [SC]
+        C0FCF8642D830C53246211400346653590B3795B
+  uid           [ultimate] key-submission@@example.net
+  ssb   rsa2048 2016-08-30 [E]
+@end example
+
+Take the fingerprint from that output and manually publish the key:
+
+@example
+  $ gpg-wks-server --install-key C0FCF8642D830C53246211400346653590B3795B \
+  >                key-submission@@example.net
+@end example
+
+Finally that submission address needs to be redirected to a script
+running @command{gpg-wks-server}.  The @command{procmail} command can
+be used for this: Redirect the submission address to the user "webkey"
+and put this into webkey's @file{.procmailrc}:
+
+@example
+:0
+* !^From: webkey@@example.net
+* !^X-WKS-Loop: webkey.example.net
+|gpg-wks-server -v --receive \
+     --header X-WKS-Loop=webkey.example.net \
+     --from webkey@@example.net --send
+@end example
+
+
+@mansect see also
+@ifset isman
+@command{gpg-wks-client}(1)
+@end ifset