diff --git a/doc/Makefile.am b/doc/Makefile.am index 1fa04b412..89079b383 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,199 +1,199 @@ # Copyright (C) 2002, 2004 Free Software Foundation, Inc. # # This file is part of GnuPG. # # GnuPG is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 3 of the License, or # (at your option) any later version. # # GnuPG is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, see . ## Process this file with automake to produce Makefile.in AM_CPPFLAGS = include $(top_srcdir)/am/cmacros.am examples = examples/README examples/scd-event examples/trustlist.txt \ examples/vsnfd.prf examples/debug.prf \ examples/systemd-user/README \ examples/systemd-user/dirmngr.service \ examples/systemd-user/dirmngr.socket \ examples/systemd-user/gpg-agent.service \ examples/systemd-user/gpg-agent.socket \ examples/systemd-user/gpg-agent-ssh.socket \ examples/systemd-user/gpg-agent-browser.socket \ examples/systemd-user/gpg-agent-extra.socket \ examples/gpgconf.conf examples/pwpattern.list helpfiles = help.txt help.be.txt help.ca.txt help.cs.txt \ help.da.txt help.de.txt help.el.txt help.eo.txt \ help.es.txt help.et.txt help.fi.txt help.fr.txt \ help.gl.txt help.hu.txt help.id.txt help.it.txt \ help.ja.txt help.nb.txt help.pl.txt help.pt.txt \ help.pt_BR.txt help.ro.txt help.ru.txt help.sk.txt \ help.sv.txt help.tr.txt help.zh_CN.txt help.zh_TW.txt profiles = EXTRA_DIST = samplekeys.asc mksamplekeys com-certs.pem qualified.txt \ gnupg-logo.eps gnupg-logo.pdf gnupg-logo.png gnupg-logo-tr.png \ gnupg-module-overview.png gnupg-module-overview.pdf \ gnupg-card-architecture.png gnupg-card-architecture.pdf \ FAQ gnupg7.texi mkdefsinc.c defsincdate \ opt-homedir.texi see-also-note.texi specify-user-id.texi \ gpgv.texi yat2m.c ChangeLog-2011 whats-new-in-2.1.txt BUILT_SOURCES = gnupg-module-overview.png gnupg-module-overview.pdf \ gnupg-card-architecture.png gnupg-card-architecture.pdf \ defsincdate defs.inc info_TEXINFOS = gnupg.texi dist_pkgdata_DATA = $(helpfiles) $(profiles) nobase_dist_doc_DATA = FAQ DETAILS HACKING DCO TRANSLATE OpenPGP KEYSERVER \ $(examples) #dist_html_DATA = 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 gnupg.texi : defs.inc # We need EPS files for "make distcheck" but we do not want to distribute # them due to their size. Let's build them as needed. gnupg.dvi : gnupg-module-overview.eps gnupg-card-architecture.eps DVIPS = TEXINPUTS="$(srcdir)$(PATH_SEPARATOR)$$TEXINPUTS" dvips AM_MAKEINFOFLAGS = -I $(srcdir) --css-ref=/share/site.css 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 else myman_pages += gpg.1 gpgv.1 endif man_MANS = $(myman_pages) gnupg.7 watchgnupg_SOURCE = gnupg.texi CLEANFILES = yat2m mkdefsinc defs.inc DISTCLEANFILES = gnupg.tmp gnupg.ops yat2m-stamp.tmp yat2m-stamp \ gnupg-card-architecture.eps \ gnupg-module-overview.eps \ $(myman_pages) gpg-zip.1 gnupg.7 yat2m: yat2m.c $(CC_FOR_BUILD) -o $@ $(srcdir)/yat2m.c mkdefsinc: mkdefsinc.c Makefile ../config.h $(CC_FOR_BUILD) -I. -I.. -I$(srcdir) $(AM_CPPFLAGS) \ -o $@ $(srcdir)/mkdefsinc.c .svg.eps: convert `test -f '$<' || echo '$(srcdir)/'`$< $@ .svg.png: convert `test -f '$<' || echo '$(srcdir)/'`$< $@ .svg.pdf: convert `test -f '$<' || echo '$(srcdir)/'`$< $@ .fig.png: fig2dev -L png `test -f '$<' || echo '$(srcdir)/'`$< $@ .fig.jpg: fig2dev -L jpeg `test -f '$<' || echo '$(srcdir)/'`$< $@ .fig.eps: fig2dev -L eps `test -f '$<' || echo '$(srcdir)/'`$< $@ .fig.pdf: fig2dev -L pdf `test -f '$<' || echo '$(srcdir)/'`$< $@ yat2m-stamp: $(myman_sources) defs.inc @rm -f yat2m-stamp.tmp @touch yat2m-stamp.tmp incd="`test -f defsincdate || echo '$(srcdir)/'`defsincdate"; \ for file in $(myman_sources) ; do \ $(YAT2M) $(YAT2M_OPTIONS) --store \ --date "`cat $$incd 2>/dev/null`" \ `test -f '$$file' || echo '$(srcdir)/'`$$file ; done @mv -f yat2m-stamp.tmp $@ yat2m-stamp: $(YAT2M) $(myman_pages) gnupg.7 : yat2m-stamp defs.inc @if test -f $@; then :; else \ trap 'rm -rf yat2m-stamp yat2m-lock' 1 2 13 15; \ if mkdir yat2m-lock 2>/dev/null; then \ rm -f yat2m-stamp; \ $(MAKE) $(AM_MAKEFLAGS) yat2m-stamp; \ rmdir yat2m-lock; \ else \ while test -d yat2m-lock; do sleep 1; done; \ test -f yat2m-stamp; exit $$?; \ fi; \ fi dist-hook: defsincdate defsincdate: $(gnupg_TEXINFOS) : >defsincdate ; \ if test -e $(top_srcdir)/.git; then \ (cd $(srcdir) && git log -1 --format='%ct' \ -- $(gnupg_TEXINFOS) 2>/dev/null) >>defsincdate; \ fi defs.inc : defsincdate Makefile mkdefsinc incd="`test -f defsincdate || echo '$(srcdir)/'`defsincdate"; \ ./mkdefsinc -C $(srcdir) --date "`cat $$incd 2>/dev/null`" \ $(gnupg_TEXINFOS) >$@ online: gnupg.html gnupg.pdf gnupg-module-overview.png \ gnupg-card-architecture.png set -e; \ echo "Uploading current manuals to www.gnupg.org ..."; \ cp $(srcdir)/gnupg-logo-tr.png gnupg.html/; \ cp gnupg-module-overview.png gnupg.html/; \ cp gnupg-card-architecture.png gnupg.html/; \ user=werner ; webhost="ftp.gnupg.org" ; dashdevel="" ; \ if echo "@PACKAGE_VERSION@" | grep -- "-beta" >/dev/null; then \ dashdevel="-devel" ; \ else \ rsync -v gnupg.pdf $${user}@$${webhost}:webspace/manuals/ ; \ fi ; \ cd gnupg.html ; \ rsync -vr --exclude='.git' . \ $${user}@$${webhost}:webspace/manuals/gnupg$${dashdevel}/ diff --git a/doc/gnupg.texi b/doc/gnupg.texi index c99c129f0..7154fc841 100644 --- a/doc/gnupg.texi +++ b/doc/gnupg.texi @@ -1,233 +1,235 @@ \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename gnupg.info @include defs.inc @settitle Using the GNU Privacy Guard @c A couple of macros with no effect on texinfo @c but used by the yat2m processor. @macro manpage {a} @end macro @macro mansect {a} @end macro @macro manpause @end macro @macro mancont @end macro @c Create a separate index for command line options. @defcodeindex op @c Create an index vor environment variables and files. @defcodeindex ef @c Merge the function index into the concept index. @syncodeindex fn cp @c Merge the variable index into the concept index. @syncodeindex vr cp @c Merge the keystroke index into the concept index. @syncodeindex ky cp @c Merge the program index into the concept index. @syncodeindex pg cp @c Merge the data type index into the concept index. @syncodeindex tp cp @c %**end of header @copying This is the @cite{The GNU Privacy Guard Manual} (version @value{VERSION}, @value{UPDATED-MONTH}). @iftex Published by The GnuPG Project@* @url{https://gnupg.org}@* (or @url{http://ic6au7wa3f6naxjq.onion}) @end iftex @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 under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. The text of the license can be found in the section entitled ``Copying''. @end quotation @end copying @dircategory GNU Utilities @direntry * gpg2: (gnupg). OpenPGP encryption and signing tool. * gpgsm: (gnupg). S/MIME encryption and signing tool. * gpg-agent: (gnupg). The secret key daemon. * dirmngr: (gnupg). X.509 CRL and OCSP server. * dirmngr-client: (gnupg). X.509 CRL and OCSP client. @end direntry @c @c Printing stuff taken from gcc. @c @macro gnupgtabopt{body} @code{\body\} @end macro @macro gnupgoptlist{body} @smallexample \body\ @end smallexample @end macro @c Makeinfo handles the above macro OK, TeX needs manual line breaks; @c they get lost at some point in handling the macro. But if @macro is @c used here rather than @alias, it produces double line breaks. @iftex @alias gol = * @end iftex @ifnottex @macro gol @end macro @end ifnottex @c @c Titlepage @c @setchapternewpage odd @titlepage @title Using the GNU Privacy Guard @subtitle Version @value{VERSION} @subtitle @value{UPDATED-MONTH} @sp 3 @image{gnupg-logo,,,The GnuPG Logo} @sp 3 @author The GnuPG Project (@url{https://gnupg.org}) @page @vskip 0pt plus 1filll @insertcopying @end titlepage @ifnothtml @summarycontents @contents @page @end ifnothtml @ifhtml @center @image{gnupg-logo-tr,6cm,,The GnuPG Logo} @end ifhtml @ifnottex @node Top @top @insertcopying This manual documents how to use the GNU Privacy Guard system as well as the administration and the architecture. @end ifnottex @menu * Installation:: A short installation guide. * Invoking GPG-AGENT:: How to launch the secret key daemon. * Invoking DIRMNGR:: How to launch the CRL and OCSP daemon. * Invoking GPG:: Using the OpenPGP protocol. * Invoking GPGSM:: Using the S/MIME protocol. * Invoking SCDAEMON:: How to handle Smartcards. * 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. * Debugging:: How to solve problems * Copying:: GNU General Public License says how you can copy and share GnuPG * Contributors:: People who have contributed to GnuPG. * Glossary:: Short description of terms used. * Option Index:: Index to command line options. * Environment Index:: Index to environment variables and files. * Index:: Index of concepts and symbol names. @end menu @ifhtml @page @summarycontents @contents @end ifhtml @include instguide.texi @include gpg-agent.texi @include dirmngr.texi @include gpg.texi @include gpgsm.texi @include scdaemon.texi @node Specify a User ID @chapter How to Specify a User Id @anchor{how-to-specify-a-user-id} @include specify-user-id.texi @include tools.texi +@include wks.texi @include howtos.texi @include sysnotes.texi @include debugging.texi @include gpl.texi @include contrib.texi @c --------------------------------------------------------------------- @c Indexes @c --------------------------------------------------------------------- @include glossary.texi @node Option Index @unnumbered Option Index @printindex op @node Environment Index @unnumbered Environment Variable and File Index @printindex ef @node Index @unnumbered Index @printindex cp @c --------------------------------------------------------------------- @c Epilogue @c --------------------------------------------------------------------- @c @node History @c @unnumbered History @c @c Here are the notices from the old dirmngr manual: @c @c @itemize @c @item Using DirMngr, 2002, Steffen Hansen, Klar"alvdalens Datakonsult AB. @c @item Using DirMngr, 2004, 2005, 2006, 2008 Werner Koch, g10 Code GmbH. @c @end itemize @c @bye 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