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
This commit is contained in:
Alessio Treglia
GitHub
parent
af1037eff8
commit
230a1e8ba3
|
|
@ -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(
|
||||
|
|
|
|||
|
|
@ -12,12 +12,29 @@ import (
|
|||
func Commands() *cobra.Command {
|
||||
cmd := &cobra.Command{
|
||||
Use: "keys",
|
||||
Short: "Add or view local private keys",
|
||||
Long: `Keys allows you to manage your local keystore for tendermint.
|
||||
Short: "Manage your application's keys",
|
||||
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
|
||||
used by light-clients, full nodes, or any other application that
|
||||
needs to sign with a private key.`,
|
||||
The keyring supports the following backends:
|
||||
|
||||
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(),
|
||||
|
|
|
|||
|
|
@ -1,47 +0,0 @@
|
|||
# Keys API
|
||||
|
||||
[](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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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) {
|
||||
|
|
|
|||
Loading…
Reference in New Issue