fix up 6562de7475b21cd03c7b1a83a591fa563c589f5b
[gnupg.git] / doc / wks.texi
index 55dfee6..9f1fff2 100644 (file)
@@ -61,11 +61,12 @@ 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
 Key Directory.
 
 With the @option{--supported} command the caller can test whether a
-site supports the Web Key Service.  The argument is an arbitray
+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
 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}.
+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
 
 With the @option{--check} command the caller can test whether a key
 exists for a supplied mail address.  The command returns success if a
@@ -89,6 +90,25 @@ 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}.
 
 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{--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
 @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
@@ -109,6 +129,44 @@ $(gpgconf --list-dirs libexecdir)/gpg-wks-client --check foo@@example.net
 Directly send created mails using the @command{sendmail} command.
 Requires installation of that command.
 
 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
 @item --output @var{file}
 @itemx -o
 @opindex output
@@ -122,6 +180,13 @@ 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.
 
 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{--install-key} and @option{--remove-key}.  The default is
+@file{openpgpkey}.
+
 @item --verbose
 @opindex verbose
 Enable extra informational output.
 @item --verbose
 @opindex verbose
 Enable extra informational output.
@@ -174,18 +239,24 @@ Display a brief help page and exit.
 .br
 .B gpg-wks-server
 .RI [ options ]
 .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
 .B \-\-install-key
 .I file
+.I user-id
 .br
 .B gpg-wks-server
 .RI [ options ]
 .B \-\-remove-key
 .br
 .B gpg-wks-server
 .RI [ options ]
 .B \-\-remove-key
-.I mailaddr
+.I user-id
 .br
 .B gpg-wks-server
 .RI [ options ]
 .B \-\-revoke-key
 .br
 .B gpg-wks-server
 .RI [ options ]
 .B \-\-revoke-key
-.I mailaddr
+.I user-id
 @end ifset
 
 @mansect description
 @end ifset
 
 @mansect description
@@ -200,7 +271,7 @@ 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.
 
 @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
+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.
 
 example non-confirmed requested should be removed after their expire
 time.  It is best to run this command once a day from a cronjob.
 
@@ -208,8 +279,29 @@ 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.
 
 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.
+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
 
 
 @mansect options
@@ -218,6 +310,12 @@ The commands @option{--install-key}, @option{--remove-key}, and
 
 @table @gnupgtabopt
 
 
 @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 --from @var{mailaddr}
 @opindex from
 Use @var{mailaddr} as the default sender address.
@@ -231,12 +329,23 @@ Add the mail header "@var{name}: @var{value}" to all outgoing mails.
 Directly send created mails using the @command{sendmail} command.
 Requires installation of that command.
 
 Directly send created mails using the @command{sendmail} command.
 Requires installation of that command.
 
-@item --output @var{file}
-@itemx -o
+@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.
 
 @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 --verbose
 @opindex verbose
 Enable extra informational output.
@@ -281,7 +390,7 @@ Finally run
   $ gpg-wks-server --list-domains
 @end example
 
   $ gpg-wks-server --list-domains
 @end example
 
-to create the required sub-directories with the permission set
+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:
 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:
@@ -291,13 +400,13 @@ be the same address for all configured domains, for example:
   $ echo key-submission@@example.net >submission-address
 @end example
 
   $ echo key-submission@@example.net >submission-address
 @end example
 
-The protocol requires that the key to be published is sent with an
+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
 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
+  $ gpg -K key-submission@@example.net
 @end example
 
 The output of the last command looks similar to this:
 @end example
 
 The output of the last command looks similar to this:
@@ -310,17 +419,13 @@ The output of the last command looks similar to this:
   ssb   rsa3072 2016-08-30 [E]
 @end example
 
   ssb   rsa3072 2016-08-30 [E]
 @end example
 
-Take the hash of the string "key-submission", which is
-"bxzcxpxk8h87z1k7bzk86xn5aj47intu" and manually publish that key:
+Take the fingerprint from that output and manually publish the key:
 
 @example
 
 @example
-  $ gpg --export-options export-minimal --export \
-  >  -o /var/lib/gnupg/wks/example.net/hu/bxzcxpxk8h87z1k7bzk86xn5aj47intu \
-  >  key-submission@@example.new
+  $ gpg-wks-server --install-key C0FCF8642D830C53246211400346653590B3795B \
+  >                key-submission@@example.net
 @end example
 
 @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"
 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"