diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/wks.texi | 481 |
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 |