From 218992862c436d4e1bd2ecde2d5914ce8fa5b448 Mon Sep 17 00:00:00 2001 From: "Adam J. Stewart" Date: Fri, 9 Jun 2017 12:27:29 -0500 Subject: Move gpg section of docs to Getting Started (#4446) --- lib/spack/docs/basic_usage.rst | 64 ------------------------------------ lib/spack/docs/getting_started.rst | 67 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+), 64 deletions(-) (limited to 'lib') diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst index 6eba26a4b5..f25247579b 100644 --- a/lib/spack/docs/basic_usage.rst +++ b/lib/spack/docs/basic_usage.rst @@ -276,70 +276,6 @@ Seeing installed packages We know that ``spack list`` shows you the names of available packages, but how do you figure out which are already installed? -.. _cmd-spack-gpg: - -^^^^^^^^^^^^^ -``spack gpg`` -^^^^^^^^^^^^^ - -Spack has support for signing and verifying packages using GPG keys. A -separate keyring is used for Spack, so any keys available in the user's home -directory are not used. - -^^^^^^^^^^^^^^^^^^ -``spack gpg init`` -^^^^^^^^^^^^^^^^^^ - -When Spack is first installed, its keyring is empty. Keys stored in -:file:`var/spack/gpg` are the default keys for a Spack installation. These -keys may be imported by running ``spack gpg init``. This will import the -default keys into the keyring as trusted keys. - -------------- -Trusting keys -------------- - -Additional keys may be added to the keyring using -``spack gpg trust ``. Once a key is trusted, packages signed by the -owner of they key may be installed. - -------------- -Creating keys -------------- - -You may also create your own key so that you may sign your own packages using -``spack gpg create ``. By default, the key has no expiration, -but it may be set with the ``--expires `` flag (see the ``gnupg2`` -documentation for accepted date formats). It is also recommended to add a -comment as to the use of the key using the ``--comment `` flag. The -public half of the key can also be exported for sharing with others so that -they may use packages you have signed using the ``--export `` flag. -Secret keys may also be later exported using the -``spack gpg export [...]`` command. - ------------- -Listing keys ------------- - -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 ``. Key IDs can be -email addresses, names, or (best) fingerprints. - ------------------------------- -Signing and Verifying Packages ------------------------------- - -In order to sign a package, ``spack gpg sign `` should be used. By -default, the signature will be written to ``.asc``, but that may be -changed by using the ``--output `` flag. If there is only one signing -key available, it will be used, but if there is more than one, the key to use -must be specified using the ``--key `` flag. The ``--clearsign`` flag -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 ``. - .. _cmd-spack-find: ^^^^^^^^^^^^^^ diff --git a/lib/spack/docs/getting_started.rst b/lib/spack/docs/getting_started.rst index 9b31ea4491..eaa92db694 100644 --- a/lib/spack/docs/getting_started.rst +++ b/lib/spack/docs/getting_started.rst @@ -987,6 +987,73 @@ written in C/C++/Fortran would need it. A potential workaround is to load a recent ``binutils`` into your environment and use the ``--dirty`` flag. +----------- +GPG Signing +----------- + +.. _cmd-spack-gpg: + +^^^^^^^^^^^^^ +``spack gpg`` +^^^^^^^^^^^^^ + +Spack has support for signing and verifying packages using GPG keys. A +separate keyring is used for Spack, so any keys available in the user's home +directory are not used. + +^^^^^^^^^^^^^^^^^^ +``spack gpg init`` +^^^^^^^^^^^^^^^^^^ + +When Spack is first installed, its keyring is empty. Keys stored in +:file:`var/spack/gpg` are the default keys for a Spack installation. These +keys may be imported by running ``spack gpg init``. This will import the +default keys into the keyring as trusted keys. + +^^^^^^^^^^^^^ +Trusting keys +^^^^^^^^^^^^^ + +Additional keys may be added to the keyring using +``spack gpg trust ``. Once a key is trusted, packages signed by the +owner of they key may be installed. + +^^^^^^^^^^^^^ +Creating keys +^^^^^^^^^^^^^ + +You may also create your own key so that you may sign your own packages using +``spack gpg create ``. By default, the key has no expiration, +but it may be set with the ``--expires `` flag (see the ``gnupg2`` +documentation for accepted date formats). It is also recommended to add a +comment as to the use of the key using the ``--comment `` flag. The +public half of the key can also be exported for sharing with others so that +they may use packages you have signed using the ``--export `` flag. +Secret keys may also be later exported using the +``spack gpg export [...]`` command. + +^^^^^^^^^^^^ +Listing keys +^^^^^^^^^^^^ + +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 ``. Key IDs can be +email addresses, names, or (best) fingerprints. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Signing and Verifying Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In order to sign a package, ``spack gpg sign `` should be used. By +default, the signature will be written to ``.asc``, but that may be +changed by using the ``--output `` flag. If there is only one signing +key available, it will be used, but if there is more than one, the key to use +must be specified using the ``--key `` flag. The ``--clearsign`` flag +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 ``. .. _cray-support: -- cgit v1.2.3-60-g2f50