diff options
author | Werner Koch <wk@gnupg.org> | 2017-07-26 17:51:03 +0200 |
---|---|---|
committer | Werner Koch <wk@gnupg.org> | 2017-07-26 17:53:00 +0200 |
commit | be636c3cfca178927b09ef4154c3e555d6f5b1c4 (patch) | |
tree | 7efb8ec38b04698570718bda2b768c9e8306431d /doc | |
parent | wks: Fix program names in the usage diagnostics. (diff) | |
download | gnupg2-be636c3cfca178927b09ef4154c3e555d6f5b1c4.tar.xz gnupg2-be636c3cfca178927b09ef4154c3e555d6f5b1c4.zip |
doc: Add man pages form gpg-wks-server and gpg-wks-client.
* doc/wks.texi: New.
* doc/gnupg.texi: Include wks.texi.
* doc/Makefile.am (gnupg_TEXINFOS): Add wks.texi.
(myman_pages): Add new man pages.
Signed-off-by: Werner Koch <wk@gnupg.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Makefile.am | 6 | ||||
-rw-r--r-- | doc/gnupg.texi | 4 | ||||
-rw-r--r-- | doc/wks.texi | 340 |
3 files changed, 346 insertions, 4 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 1fa04b412..89079b383 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -68,7 +68,7 @@ nobase_dist_doc_DATA = FAQ DETAILS HACKING DCO TRANSLATE OpenPGP KEYSERVER \ gnupg_TEXINFOS = \ gpg.texi gpgsm.texi gpg-agent.texi scdaemon.texi instguide.texi \ tools.texi debugging.texi glossary.texi contrib.texi gpl.texi \ - sysnotes.texi dirmngr.texi \ + sysnotes.texi dirmngr.texi wks.texi \ gnupg-module-overview.svg \ gnupg-card-architecture.fig \ howtos.texi howto-create-a-server-cert.texi @@ -88,11 +88,11 @@ YAT2M_OPTIONS = -I $(srcdir) \ --release "GnuPG @PACKAGE_VERSION@" --source "GNU Privacy Guard 2.1" myman_sources = gnupg7.texi gpg.texi gpgsm.texi gpg-agent.texi \ - dirmngr.texi scdaemon.texi tools.texi + dirmngr.texi scdaemon.texi tools.texi wks.texi myman_pages = gpgsm.1 gpg-agent.1 dirmngr.8 scdaemon.1 \ watchgnupg.1 gpgconf.1 addgnupghome.8 gpg-preset-passphrase.1 \ gpg-connect-agent.1 gpgparsemail.1 symcryptrun.1 \ - applygnupgdefaults.8 \ + applygnupgdefaults.8 gpg-wks-client.1 gpg-wks-server.1 \ dirmngr-client.1 if USE_GPG2_HACK myman_pages += gpg2.1 gpgv2.1 diff --git a/doc/gnupg.texi b/doc/gnupg.texi index c99c129f0..7154fc841 100644 --- a/doc/gnupg.texi +++ b/doc/gnupg.texi @@ -45,7 +45,7 @@ Published by The GnuPG Project@* @copyright{} 2002, 2004, 2005, 2006, 2007, 2010 Free Software Foundation, Inc.@* @copyright{} 2013, 2014, 2015 Werner Koch.@* -@copyright{} 2015 g10 Code GmbH. +@copyright{} 2015, 2016, 2017 g10 Code GmbH. @quotation Permission is granted to copy, distribute and/or modify this document @@ -142,6 +142,7 @@ the administration and the architecture. * Specify a User ID:: How to Specify a User Id. * Helper Tools:: Description of small helper tools +* Web Key Service:: Tools for the Web Key Service * Howtos:: How to do certain things. * System Notes:: Notes pertaining to certain OSes. @@ -180,6 +181,7 @@ the administration and the architecture. @include tools.texi +@include wks.texi @include howtos.texi diff --git a/doc/wks.texi b/doc/wks.texi new file mode 100644 index 000000000..f9b1a0c14 --- /dev/null +++ b/doc/wks.texi @@ -0,0 +1,340 @@ +@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 +@end ifset + +@mansect description +The @command{gpg-wks-client} is used to send requests to a Web Key +Service provider. This is usuallay 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 arbitray +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}. + +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. + +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}. + +@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 --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 --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 \-\-install-key +.I file +.br +.B gpg-wks-server +.RI [ options ] +.B \-\-remove-key +.I mailaddr +.br +.B gpg-wks-server +.RI [ options ] +.B \-\-revoke-key +.I mailaddr +@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 commands @option{--install-key}, @option{--remove-key}, and +@option{--revoke-key} are not yet functional. + + +@mansect options +@noindent +@command{gpg-wks-server} understands these options: + +@table @gnupgtabopt + +@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 --output @var{file} +@itemx -o +@opindex output +Write the created mail also to @var{file}. Note that the value +@code{-} for @var{file} would write it to stdout. + +@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 permission 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 --with-wkd-hash -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 + bxzcxpxk8h87z1k7bzk86xn5aj47intu@@example.net + ssb rsa2048 2016-08-30 [E] +@end example + +Take the hash of the string "key-submission", which is +"bxzcxpxk8h87z1k7bzk86xn5aj47intu" and manually publish that key: + +@example + $ gpg --export-options export-minimal --export \ + > -o /var/lib/gnupg/wks/example.net/hu/bxzcxpxk8h87z1k7bzk86xn5aj47intu \ + > key-submission@@example.new +@end example + +Make sure that the created file is world readable. + +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 |