gnupg: Use 'gpgv' and keybox files; adjust 'guix refresh' accordingly.

* guix/gnupg.scm (%gpgv-command, current-keyring): New variables
(gnupg-verify): Add optional 'keyring' parameter.  Use 'gpgv' instead of
'gpg' and pass it '--keyring'.
(gnupg-receive-keys): Add optional 'keyring' parameter and honor it.
(gnupg-verify*): Add #:keyring and honor it.
* guix/scripts/refresh.scm (%options, show-help): Add '--keyring'.
(guix-refresh): Parameterize CURRENT-KEYRING.
* doc/guix.texi (Invoking guix refresh): Document '--keyring' and the
keybox format.

1 files changed, 30 insertions, 0 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 9a19eb89cd..8987b20fa9 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -7268,6 +7268,36 @@ The following options can be used to customize GnuPG operation:
 Use @var{command} as the GnuPG 2.x command.  @var{command} is searched
 for in @code{$PATH}.
 
+@item --keyring=@var{file}
+Use @var{file} as the keyring for upstream keys.  @var{file} must be in the
+@dfn{keybox format}.  Keybox files usually have a name ending in @file{.kbx}
+and the GNU@tie{}Privacy Guard (GPG) can manipulate these files
+(@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard}, for
+information on a tool to manipulate keybox files).
+
+When this option is omitted, @command{guix refresh} uses
+@file{~/.config/guix/upstream/trustedkeys.kbx} as the keyring for upstream
+signing keys.  OpenPGP signatures are checked against keys from this keyring;
+missing keys are downloaded to this keyring as well (see
+@option{--key-download} below.)
+
+You can export keys from your default GPG keyring into a keybox file using
+commands like this one:
+
+@example
+gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx
+@end example
+
+Likewise, you can fetch keys to a specific keybox file like this:
+
+@example
+gpg --no-default-keyring --keyring mykeyring.kbx \
+  --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
+@end example
+
+@ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU
+Privacy Guard}, for more information on GPG's @option{--keyring} option.
+
 @item --key-download=@var{policy}
 Handle missing OpenPGP keys according to @var{policy}, which may be one
 of: