.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 usuallay done to upload a key into a Web
+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 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
-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
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
+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.
@mansect options
@noindent
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
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.
.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 mailaddr
+.I user-id
.br
.B gpg-wks-server
.RI [ options ]
.B \-\-revoke-key
-.I mailaddr
+.I user-id
@end ifset
@mansect description
-The @command{gpg-wks-server} is a server site implementation of the
+The @command{gpg-wks-server} is a server side 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
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
+@option{--send} to directly send the created 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.
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
@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.
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.
+@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.
$ 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:
@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:
@example
- sec rsa2048 2016-08-30 [SC]
+ sec rsa3072 2016-08-30 [SC]
C0FCF8642D830C53246211400346653590B3795B
uid [ultimate] key-submission@@example.net
bxzcxpxk8h87z1k7bzk86xn5aj47intu@@example.net
- ssb rsa2048 2016-08-30 [E]
+ 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
- $ 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
-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"
projects / platform / upstream / gpg2.git / blobdiff