crypto/keys: improve documentation (#5833)

* crypto/keys: improve documentation

Remove out of date crypto/keys README.md file.

Populate client keys commands help screen with
more information regarding keyring backends.

* Fix formatting

* Fix lint warning

client/flags/flags.go

@@ -118,7 +118,7 @@ func PostCommands(cmds ...*cobra.Command) []*cobra.Command {
 		c.Flags().Bool(FlagGenerateOnly, false, "Build an unsigned transaction and write it to STDOUT (when enabled, the local Keybase is not accessible)")
 		c.Flags().Bool(FlagOffline, false, "Offline mode (does not allow any online functionality")
 		c.Flags().BoolP(FlagSkipConfirmation, "y", false, "Skip tx broadcasting prompt confirmation")
-		c.Flags().String(FlagKeyringBackend, DefaultKeyringBackend, "Select keyring's backend (os|file|test)")
+		c.Flags().String(FlagKeyringBackend, DefaultKeyringBackend, "Select keyring's backend (os|file|kwallet|pass|test)")
 
 		// --gas can accept integers and "simulate"
 		c.Flags().Var(&GasFlagVar, "gas", fmt.Sprintf(

client/keys/root.go

@@ -12,12 +12,29 @@ import (
 func Commands() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "keys",
-		Short: "Add or view local private keys",
+		Short: "Manage your application's keys",
-		Long: `Keys allows you to manage your local keystore for tendermint.
+		Long: `Keyring management commands. These keys may be in any format supported by the
+Tendermint crypto library and can be used by light-clients, full nodes, or any other application
+that needs to sign with a private key.
 
-    These keys may be in any format supported by go-crypto and can be
+The keyring supports the following backends:
-    used by light-clients, full nodes, or any other application that
+
-    needs to sign with a private key.`,
+    os          Uses the operating system's default credentials store.
+    file        Uses encrypted file-based keystore within the app's configuration directory.
+                This keyring will request a password each time it is accessed, which may occur
+                multiple times in a single command resulting in repeated password prompts.
+    kwallet     Uses KDE Wallet Manager as a credentials management application.
+    pass        Uses the pass command line utility to store and retrieve keys.
+    test        Stores keys insecurely to disk. It does not prompt for a password to be unlocked
+                and it should be use only for testing purposes.
+
+kwallet and pass backends depend on external tools. Refer to their respective documentation for more
+information:
+    KWallet     https://github.com/KDE/kwallet
+    pass        https://www.passwordstore.org/
+
+The pass backend requires GnuPG: https://gnupg.org/
+`,
 	}
 	cmd.AddCommand(
 		MnemonicKeyCommand(),

crypto/keys/README.md

@@ -1,47 +0,0 @@
-# Keys API
-
-[![API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk/crypto/keys?status.svg)](https://godoc.org/github.com/cosmos/cosmos-sdk/crypto/keys)
-
-
-## The Keybase interface
-
-The [Keybase](https://godoc.org/github.com/cosmos/cosmos-sdk/crypto/keys#Keybase) interface defines
-the methods that a type needs to implement to be used as key storage backend. This package provides
-few implementations out-of-the-box.
-
-## Constructors
-
-### New
-
-The [New](https://godoc.org/github.com/cosmos/cosmos-sdk/crypto/keys#New) constructor returns
-an on-disk implementation backed by LevelDB storage that has been the default implementation used by the SDK until v0.38.0.
-Due to [security concerns](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-006-secret-store-replacement.md), we recommend to drop
-it in favor of the `NewKeyring` or `NewKeyringFile` constructors. We strongly advise to migrate away from this function as **it may be removed in a future
-release**.
-
-### NewInMemory
-
-The [NewInMemory](https://godoc.org/github.com/cosmos/cosmos-sdk/crypto/keys#NewInMemory) constructor returns
-an implementation backed by an in-memory, goroutine-safe map that we've historically used for testing purposes or on-the-fly
-key generation and we consider safe for the aforementioned use cases since the generated keys are discarded when the process
-terminates or the type instance is garbage collected.
-
-### NewKeyring
-
-The [NewKeyring](https://godoc.org/github.com/cosmos/cosmos-sdk/crypto/keys#NewKeyring) constructor returns
-an implementation backed by the [Keyring](https://github.com/99designs/keyring) library, whose aim is to provide a common
-abstraction and uniform interface between secret stores available for Windows, macOS, and most GNU/Linux distributions.
-The instance returned by this constructor will use the operating system's default credentials store, which will then handle
-keys storage operations securely. 
-
-### NewKeyringFile, NewTestKeyring
-
-Both [NewKeyringFile](https://godoc.org/github.com/cosmos/cosmos-sdk/crypto/keys#NewKeyringFile) and
-[NewTestKeyring](https://godoc.org/github.com/cosmos/cosmos-sdk/crypto/keys#NewTestKeyring) constructors return
-on-disk implementations backed by the [Keyring](https://github.com/99designs/keyring) `file` backend.
-Whilst `NewKeyringFile` returns a secure, encrypted file-based type that requires user's password in order to
-function correctly, the implementation returned by `NewTestKeyring` stores keys information in clear text and **must be used
-only for testing purposes**.
-
-`NewKeyringFile` and `NewTestKeyring` store key files in the client home directory's `keyring`
-and `keyring-test` subdirectories respectively.

crypto/keys/doc.go

@@ -0,0 +1,45 @@
+// Package keys provides common key management API.
+//
+//
+// The Keybase interface
+//
+// The Keybase interface defines the methods that a type needs to implement to be used
+// as key storage backend. This package provides few implementations out-of-the-box.
+//
+// New
+//
+// The New constructor returns an on-disk implementation backed by LevelDB storage that has been
+// the default implementation used by the SDK until v0.38.0. Due to security concerns, it is
+// recommended to drop it in favor of the NewKeyring or NewKeyringFile constructors as it will be
+// removed in future releases.
+//
+// NewInMemory
+//
+// The NewInMemory constructor returns an implementation backed by an in-memory, goroutine-safe
+// map that has historically been used for testing purposes or on-the-fly key generation as the
+// generated keys are discarded when the process terminates or the type instance is garbage
+// collected.
+//
+// NewKeyring
+//
+// The NewKeyring constructor returns an implementation backed by a keyring library
+// (https://github.com/99designs/keyring), whose aim is to provide a common abstraction and uniform
+// interface between secret stores available for Windows, macOS, and most GNU/Linux distributions
+// as well as operating system-agnostic encrypted file-based backends.
+//
+// The backends:
+// 	os		The instance returned by this constructor uses the operating system's default
+// 			credentials store to handle keys storage operations securely. It should be noted
+// 			that the keyring keyring may be kept unlocked for the whole duration of the user
+// 			session.
+// 	file	This backend more closely resembles the previous keyring storage used prior to
+// 			v0.38.1. It stores the keyring encrypted within the apps configuration directory.
+// 			This keyring will request a password each time it is accessed, which may occur
+// 			multiple times in a single command resulting in repeated password prompts.
+// 	kwallet	This backend uses KDE Wallet Manager as a credentials management application:
+// 			https://github.com/KDE/kwallet
+// 	pass	This backend uses the pass command line utility to store and retrieve keys:
+// 			https://www.passwordstore.org/
+// 	test	This backend stores keys insecurely to disk. It does not prompt for a password to
+// 			be unlocked and it should be use only for testing purposes.
+package keys

crypto/keys/keyring.go

@@ -56,7 +56,7 @@ func newKeyringKeybase(db keyring.Keyring, opts ...KeybaseOption) Keybase {
 
 // NewKeyring creates a new instance of a keyring. Keybase
 // options can be applied when generating this new Keybase.
-// Available backends are "os", "file", "test".
+// Available backends are "os", "file", "kwallet", "pass", "test".
 func NewKeyring(
 	appName, backend, rootDir string, userInput io.Reader, opts ...KeybaseOption,
 ) (Keybase, error) {