adding support for export of private gpg key (#22557)

This PR allows users to `--export`, `--export-secret`, or both to  export GPG keys
from Spack. The docs are updated that include a warning that this usually does not
need to be done.

This addresses an issue brought up in slack, and also represented in #14721.

Signed-off-by: vsoch <vsoch@users.noreply.github.com>

Co-authored-by: vsoch <vsoch@users.noreply.github.com>

1 files changed, 75 insertions, 1 deletions

diff --git a/lib/spack/docs/getting_started.rst b/lib/spack/docs/getting_started.rst
index 805149af90..fa77d74cd6 100644
--- a/lib/spack/docs/getting_started.rst
+++ b/lib/spack/docs/getting_started.rst
@@ -1119,6 +1119,33 @@ Secret keys may also be later exported using the
       <https://www.digitalocean.com/community/tutorials/how-to-setup-additional-entropy-for-cloud-servers-using-haveged>`_
       provides a good overview of sources of randomness.
 
+Here is an example of creating a key. Note that we provide a name for the key first
+(which we can use to reference the key later) and an email address:
+
+.. code-block:: console
+
+    $ spack gpg create dinosaur dinosaur@thedinosaurthings.com
+
+
+If you want to export the key as you create it:
+
+
+.. code-block:: console
+
+    $ spack gpg create --export key.pub dinosaur dinosaur@thedinosaurthings.com
+
+Or the private key:
+
+
+.. code-block:: console
+
+    $ spack gpg create --export-secret key.priv dinosaur dinosaur@thedinosaurthings.com
+
+
+You can include both ``--export`` and ``--export-secret``, each with
+an output file of choice, to export both.
+
+
 ^^^^^^^^^^^^
 Listing keys
 ^^^^^^^^^^^^
@@ -1127,7 +1154,22 @@ In order to list the keys available in the keyring, the
 ``spack gpg list`` command will list trusted keys with the ``--trusted`` flag
 and keys available for signing using ``--signing``. If you would like to
 remove keys from your keyring, ``spack gpg untrust <keyid>``. Key IDs can be
-email addresses, names, or (best) fingerprints.
+email addresses, names, or (best) fingerprints. Here is an example of listing
+the key that we just created:
+
+.. code-block:: console
+
+    gpgconf: socketdir is '/run/user/1000/gnupg'
+    /home/spackuser/spack/opt/spack/gpg/pubring.kbx
+    ----------------------------------------------------------
+    pub   rsa4096 2021-03-25 [SC]
+          60D2685DAB647AD4DB54125961E09BB6F2A0ADCB
+    uid           [ultimate] dinosaur (GPG created for Spack) <dinosaur@thedinosaurthings.com>
+
+    
+Note that the name "dinosaur" can be seen under the uid, which is the unique
+id. We might need this reference if we want to export or otherwise reference the key.
+
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Signing and Verifying Packages
@@ -1142,6 +1184,38 @@ may also be used to create a signed file which contains the contents, but it
 is not recommended. Signed packages may be verified by using
 ``spack gpg verify <file>``.
 
+
+^^^^^^^^^^^^^^
+Exporting Keys
+^^^^^^^^^^^^^^
+
+You likely might want to export a public key, and that looks like this. Let's
+use the previous example and ask spack to export the key with uid "dinosaur."
+We will provide an output location (typically a `*.pub` file) and the name of
+the key.
+
+.. code-block:: console
+
+    $ spack gpg export dinosaur.pub dinosaur
+
+You can then look at the created file, `dinosaur.pub`, to see the exported key.
+If you want to include the private key, then just add `--secret`:
+
+.. code-block:: console
+
+    $ spack gpg export --secret dinosaur.priv dinosaur
+
+This will write the private key to the file `dinosaur.priv`. 
+
+.. warning::
+
+    You should be very careful about exporting private keys. You likely would
+    only want to do this in the context of moving your spack installation to
+    a different server, and wanting to preserve keys for a buildcache. If you
+    are unsure about exporting, you can ask your local system administrator
+    or for help on an issue or the Spack slack.
+
+
 .. _cray-support:
 
 -------------