[Pkg-gnupg-commit] [gnupg2] 163/185: doc: Add man pages form gpg-wks-server and gpg-wks-client.
Daniel Kahn Gillmor
dkg at fifthhorseman.net
Mon Aug 7 11:55:32 UTC 2017
This is an automated email from the git hooks/post-receive script.
dkg pushed a commit to branch experimental
in repository gnupg2.
commit be636c3cfca178927b09ef4154c3e555d6f5b1c4
Author: Werner Koch <wk at gnupg.org>
Date: Wed Jul 26 17:51:03 2017 +0200
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 at gnupg.org>
---
doc/Makefile.am | 6 +-
doc/gnupg.texi | 4 +-
doc/wks.texi | 340 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 346 insertions(+), 4 deletions(-)
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 1fa04b4..89079b3 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 c99c129..7154fc8 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.@*
- at copyright{} 2015 g10 Code GmbH.
+ at 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
+ at include wks.texi
@include howtos.texi
diff --git a/doc/wks.texi b/doc/wks.texi
new file mode 100644
index 0000000..f9b1a0c
--- /dev/null
+++ b/doc/wks.texi
@@ -0,0 +1,340 @@
+ at c wks.texi - man pages for the Web Key Service tools.
+ at c Copyright (C) 2017 g10 Code GmbH
+ at c Copyright (C) 2017 Bundesamt für Sicherheit in der Informationstechnik
+ at c This is part of the GnuPG manual.
+ at c For copying conditions, see the file GnuPG.texi.
+
+ at include defs.inc
+
+ at node Web Key Service
+ at chapter Web Key Service
+
+GnuPG comes with tools used to maintain and access a Web Key
+Directory.
+
+ at menu
+* gpg-wks-client:: Send requests via WKS
+* gpg-wks-server:: Server to provide the WKS.
+ at end menu
+
+ at c
+ at c GPG-WKS-CLIENT
+ at c
+ at manpage gpg-wks-client.1
+ at node gpg-wks-client
+ at section Send requests via WKS
+ at ifset manverb
+.B gpg-wks-client
+\- Client for the Web Key Service
+ at end ifset
+
+ at mansect synopsis
+ at 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
+ at end ifset
+
+ at 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
+ at 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
+ at option{--create}.
+
+ at 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
+ at file{foo@@example.org}:
+
+ at example
+$(gpgconf --list-dirs libexecdir)/gpg-wks-client --check foo@@example.net
+ at end example
+
+ at mansect options
+ at noindent
+ at command{gpg-wks-client} understands these options:
+
+ at table @gnupgtabopt
+
+ at item --send
+ at opindex send
+Directly send created mails using the @command{sendmail} command.
+Requires installation of that command.
+
+ at item --output @var{file}
+ at itemx -o
+ at 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.
+
+ at item --status-fd @var{n}
+ at 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.
+
+ at item --verbose
+ at opindex verbose
+Enable extra informational output.
+
+ at item --quiet
+ at opindex quiet
+Disable almost all informational output.
+
+ at item --version
+ at opindex version
+Print version of the program and exit.
+
+ at item --help
+ at opindex help
+Display a brief help page and exit.
+
+ at end table
+
+
+ at mansect see also
+ at ifset isman
+ at command{gpg-wks-server}(1)
+ at end ifset
+
+
+ at c
+ at c GPG-WKS-SERVER
+ at c
+ at manpage gpg-wks-server.1
+ at node gpg-wks-server
+ at section Provide the Web Key Service
+ at ifset manverb
+.B gpg-wks-server
+\- Server providing the Web Key Service
+ at end ifset
+
+ at mansect synopsis
+ at 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
+ at end ifset
+
+ at 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
+ at 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
+ at option{--revoke-key} are not yet functional.
+
+
+ at mansect options
+ at noindent
+ at command{gpg-wks-server} understands these options:
+
+ at table @gnupgtabopt
+
+ at item --from @var{mailaddr}
+ at opindex from
+Use @var{mailaddr} as the default sender address.
+
+ at item --header @var{name}=@var{value}
+ at opindex header
+Add the mail header "@var{name}: @var{value}" to all outgoing mails.
+
+ at item --send
+ at opindex send
+Directly send created mails using the @command{sendmail} command.
+Requires installation of that command.
+
+ at item --output @var{file}
+ at itemx -o
+ at opindex output
+Write the created mail also to @var{file}. Note that the value
+ at code{-} for @var{file} would write it to stdout.
+
+ at item --verbose
+ at opindex verbose
+Enable extra informational output.
+
+ at item --quiet
+ at opindex quiet
+Disable almost all informational output.
+
+ at item --version
+ at opindex version
+Print version of the program and exit.
+
+ at item --help
+ at opindex help
+Display a brief help page and exit.
+
+ at end table
+
+ at noindent
+ at mansect examples
+ at chapheading Examples
+
+The Web Key Service requires a working directory to store keys
+pending for publication. As root create a working directory:
+
+ at example
+ # mkdir /var/lib/gnupg/wks
+ # chown webkey:webkey /var/lib/gnupg/wks
+ # chmod 2750 /var/lib/gnupg/wks
+ at end example
+
+Then under your webkey account create directories for all your
+domains. Here we do it for "example.net":
+
+ at example
+ $ mkdir /var/lib/gnupg/wks/example.net
+ at end example
+
+Finally run
+
+ at example
+ $ gpg-wks-server --list-domains
+ at 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:
+
+ at example
+ $ cd /var/lib/gnupg/wks/example.net
+ $ echo key-submission@@example.net >submission-address
+ at 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:
+
+ at example
+ $ gpg --batch --passphrase '' --quick-gen-key key-submission@@example.net
+ $ gpg --with-wkd-hash -K key-submission@@example.net
+ at end example
+
+The output of the last command looks similar to this:
+
+ at example
+ sec rsa2048 2016-08-30 [SC]
+ C0FCF8642D830C53246211400346653590B3795B
+ uid [ultimate] key-submission@@example.net
+ bxzcxpxk8h87z1k7bzk86xn5aj47intu@@example.net
+ ssb rsa2048 2016-08-30 [E]
+ at end example
+
+Take the hash of the string "key-submission", which is
+"bxzcxpxk8h87z1k7bzk86xn5aj47intu" and manually publish that key:
+
+ at example
+ $ gpg --export-options export-minimal --export \
+ > -o /var/lib/gnupg/wks/example.net/hu/bxzcxpxk8h87z1k7bzk86xn5aj47intu \
+ > key-submission@@example.new
+ at 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}:
+
+ at 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
+ at end example
+
+
+ at mansect see also
+ at ifset isman
+ at command{gpg-wks-client}(1)
+ at end ifset
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-gnupg/gnupg2.git
More information about the Pkg-gnupg-commit
mailing list