Merge branch 'allan/pacman-key'

1 files changed, 21 insertions, 2 deletions

diff --git a/doc/pacman-key.8.txt b/doc/pacman-key.8.txt
index 9dc175cf..3582b993 100644
--- a/doc/pacman-key.8.txt
+++ b/doc/pacman-key.8.txt
@@ -80,8 +80,10 @@ Options
 *-r, \--receive* <keyserver> <keyid(s)>::
 	Fetch the specified keyids from the specified key server URL.
 
-*\--reload*::
-	Reloads the keys from the keyring package.
+*\--populate* [<keyring(s)>]::
+	Reload the default keys from the (optionally provided) keyrings in
+	+{pkgdatadir}/keyrings+. For more information, see
+	<<SC,Providing a Keyring for Import>> below.
 
 *-u, \--updatedb*::
 	Equivalent to \--check-trustdb in GnuPG.
@@ -93,6 +95,23 @@ Options
 	Displays the program version.
 
 
+Providing a Keyring for Import
+------------------------------
+A distribution or other repository provided may want to provide a set of valid
+PGP keys used in the signing of its packages and repository databases that can
+be readily imported into the pacman keyring.  This is achieved by providing a
+PGP keyring file `foo.gpg` that contains the keys for the foo keyring in the
+directory +{pkgdatadir}/keyrings+. Optionally the file `foo-revoked` can be
+provided containing a list of revoked key IDs for that keyring. These files are
+required to be signed (detached) by a trusted PGP key that the user must
+manually import to the pacman keyring. This prevents a potentially malicious
+repository adding keys to the pacman keyring without the users knowledge.
+
+A key being marked as revoked always takes priority over the key being added to
+the pacman keyring, regardless of the keyring it is provided in. To prevent a
+key from being revoked when using --populate, its ID can be listed in
++{sysconfdir}/pacman.d/gnupg/holdkeys+.
+
 See Also
 --------
 linkman:pacman[8], linkman:pacman.conf[5]