Setting up the Keyring
This document describes how to configure and use the keyring and its various backends. For this guide, The gitopia Binary is required which you can install from here.
The keyring stores the private/public keypairs required to interact with a node. For example, before running the blockchain node, a validator key must be created so that blocks can be properly signed. The private key can be stored in different locations, called "backends", such as a file or the operating system's own key storage.
Like every Cosmos-based network, Gitopia nodes store secret keys in a keyring. The keyring can be configured with one of several backend implementations.
Available backends for the keyring
The OS backend
The os backend relies on operating system-specific defaults to handle key storage
securely. Typically, an operating system's credential sub-system handles password prompts,
private keys storage, and user sessions according to the user's password policies. Here
is a list of the most popular operating systems and their respective passwords manager:
- macOS: Keychain
- Windows: Credentials Management API
- GNU/Linux:
GNU/Linux distributions that use GNOME as default desktop environment typically come with
Seahorse. Users of KDE based distributions are
commonly provided with KDE Wallet Manager.
Whilst the former is in fact a libsecret convenient frontend, the latter is a kwallet
client.
os is the default option since operating system's default credentials managers are designed to meet user's most common needs and provide them with a comfortable experience without compromising on security.
Example:
gitopiad keys add file-key-name --keyring-backend os
- address: gitopia1pw52vhsx7lfaq3pdza86q2u6z49m65nzwdhf6e
name: file-key-name
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"AgpZ3w81G8xKGoqB0ca32ECn6JPjBZkCzOtL4gHt5Hnv"}'
type: local
**Important** write this mnemonic phrase in a safe place.
It is the only way to recover your account if you ever forget your password.
arrow cigar staff rhythm merit drama actress pulp cradle mind clump melt hair install...
The file backend
The file backend stores the keyring encrypted 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.
Example:
gitopiad keys add file-key-name --keyring-backend file
Enter keyring passphrase:
Re-enter keyring passphrase:
- address: gitopia1a23yemhm2fuq0qlwf30ksd45pajgpwdv8dlrss
name: file-key-name
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"AyXTVSq3rTm3Egl6/YPFKsr7uP07MZptx9P9MsZDI7qg"}'
type: local
**Important** write this mnemonic phrase in a safe place.
It is the only way to recover your account if you ever forget your password.
vital giggle welcome kind alley inmate camera kingdom glide begin sunset bag ...
The pass backend
The pass backend uses the pass utility to manage on-disk
encryption of key's sensitive data and metadata. Keys are stored inside gpg encrypted files
within app-specific directories. pass is available for the most popular UNIX
operating systems as well as GNU/Linux distributions. Please refer to its manual page for
information on how to download and install it.
pass uses GnuPG for encryption. gpg automatically invokes the gpg-agent
daemon upon execution, which handles the caching of GnuPG credentials. Please refer to gpg-agent
man page for more information on how to configure cache parameters such as credentials TTL and
passphrase expiration.
The password store must be set up prior to first use:
pass init <GPG_KEY_ID>
Replace <GPG_KEY_ID> with your GPG key ID. You can use your personal GPG key or an alternative
one you may want to use specifically to encrypt the password store.
The kwallet backend
The kwallet backend uses KDE Wallet Manager, which comes installed by default on the
GNU/Linux distributions that ships KDE as default desktop environment. Please refer to
KWallet Handbook for more
information.
The test backend
Provided for testing purposes only. The test backend is not recommended for use in production environments
The test backend is a password-less variation of the file backend. Keys are stored
unencrypted on disk.
Example:
gitopiad keys add file-key-name --keyring-backend test
- address: gitopia1gck2p3z403m9df65ddg7agjxyeuh0xdxg7n53c
name: file-key-name
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"AkCK8Muz/xxsjYdS6FOdh7KSZ4lHwCXdLvgf+Tq8GMQ8"}'
type: local
**Important** write this mnemonic phrase in a safe place.
It is the only way to recover your account if you ever forget your password.
increase bar track foil butter dolphin inside guard wave social subway net mind salt suit...
The memory backend
Provided for testing purposes only. The memory backend is not recommended for use in production environments. Use at your own risk!
The memory backend stores keys in memory. The keys are immediately deleted after the program has exited.
Example:
gitopiad keys add file-key-name --keyring-backend memory
- address: gitopia16jzvh6yss8us85l4zqd66xc42duu8l4y4fcs98
name: file-key-name
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"AsH2NtCT1HvSBB1KIT/LnppA1PoQaQD/zNERhXmRKaZ9"}'
type: local
**Important** write this mnemonic phrase in a safe place.
It is the only way to recover your account if you ever forget your password.
veteran this blur advice raw burden sing depart breeze globe smoke hybrid quality check ahead...
The recommended backends for headless environments are file and pass.
Basic Key Management
Create a new key
gitopiad keys add <wallet_name>
You can create a new key with the name gitopia-key as in the following example:
gitopiad keys add gitopia-key
- address: gitopia1mdlj63583hflhl72ea93n9le2n8mqtskt93t4p
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A/JD4In8ZoOYtTmD3DGSia8oPGueDsS9+HQm/IIpiE+Y"}'
type: local
**Important** write this mnemonic phrase in a safe place.
It is the only way to recover your account if you ever forget your password.
ink often atom stop squirrel step forum sight age main south hold permit grunt tooth wonder soup ...
It is important that you keep the mnemonic for address secure, as there is no way to recover it. You would not be able to recover and access the funds in the wallet if you forget the mnemonic phrase.
Restore existing key by seed phrase
gitopiad keys add <YOUR-KEY-NAME> --recover
You can create a new key with the name gitopia-key as in the following example
Example:
gitopiad keys add gitopia-key --recover
List your keys
gitopiad keys list
Multiple keys can be created when needed. You can list all keys saved.
gitopiad keys list
- address: gitopia10vazc96z8g032gqaaaeangd7zsydm5luzaayxt
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A+I4HCUY/TJ/x/I7h2Ju64/cYfT/8ZeTRcyvDiCQo6qj"}'
type: local
- address: gitopia1qg7u0mvamw6k6pk9mn9ncxrwnpjdlgt7plapvq
name: test-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"AxfC40EsEdUPeweFgVV9VL8lp0wwK+t46/4NE7lbv9tj"}'
type: ledger
Retrieve key information
gitopiad keys show <YOUR-KEY-NAME>
You can retrieve key information by its name:
Examples:
Retrieve key information - Account Address and its public key
gitopiad keys show gitopia-key --bech acc
- address: gitopia1mdlj63583hflhl72ea93n9le2n8mqtskt93t4p
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A/JD4In8ZoOYtTmD3DGSia8oPGueDsS9+HQm/IIpiE+Y"}'
type: local
Retrieve key information - Validator Address and its public key
gitopiad keys show gitopia-key --bech val
- address: gitopiavaloper1mdlj63583hflhl72ea93n9le2n8mqtskrl4m46
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A/JD4In8ZoOYtTmD3DGSia8oPGueDsS9+HQm/IIpiE+Y"}'
type: local
Retrieve key information - Consensus nodes Address and its public key
gitopiad keys show gitopia-key --bech acc
- address: gitopia1mdlj63583hflhl72ea93n9le2n8mqtskt93t4p
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A/JD4In8ZoOYtTmD3DGSia8oPGueDsS9+HQm/IIpiE+Y"}'
type: local
Delete a key
gitopiad keys delete <key_name>
You can delete a key in your storage path by its name.
Make sure you have backed up the key mnemonic before removing any of your keys, as there will be no way to recover your key without the mnemonic.
gitopiad keys delete gitopia-key
Key reference will be deleted. Continue? [y/N]: y
Key deleted forever (uh oh!)