gnupg/doc/wks.texi

@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.

All commands may also be given without the two leading dashes.

@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.  If
this option is used with the @option{--check} command and a key was
found it is written to the given file.

@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 --add-revocs
@itemx --no-add-revocs
@opindex add-revocs
@opindex no-add-revocs
If enabled append revocation certificates for the same addrspec as
used in the WKD to the key.  Modern gpg version are able to import and
apply them for existing keys.  Note that when used with the
@option{--mirror} command the revocation are searched in the local
keyring and not in an LDAP directory.  The default is @option{--add-revocs}.

@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

To use the services with clients lacking integrated support, the
mailcap mechanism can be used.  Simply put:
@example
application/vnd.gnupg.wks; \
  @value{BINDIR}/gpg-wks-client -v --read --send; \
  needsterminal; \
  description=WKS message
@end example
into the @file{/etc/mailcap}.  This assumes that a /usr/lib/sendmail
is installed.  With this configuration any real mail programs will run
gpg-wks-client for messages received from a Web Key Service.

@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 side 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 created mails back.  See below
for an installation example.

The command @option{--cron} is used for regular 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 sent 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   rsa3072 2016-08-30 [SC]
        C0FCF8642D830C53246211400346653590B3795B
  uid           [ultimate] key-submission@@example.net
                bxzcxpxk8h87z1k7bzk86xn5aj47intu@@example.net
  ssb   rsa3072 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