Skip to content

Latest commit

 

History

History
92 lines (70 loc) · 4.3 KB

keyring.md

File metadata and controls

92 lines (70 loc) · 4.3 KB
Raw

The keyring

This document describes how to configure and use the keyring and its various backends for an application. A separate document for implementing a CLI for an SDK module can be found here. {synopsis}

Starting with the v0.38.0 release, Cosmos SDK comes with a new keyring implementation that provides a set of commands to manage cryptographic keys in a secure fashion. The new keyring supports multiple storage backends, some of which may not be available on all operating systems.

The os backend

The os backend relies on operating system-specific defaults to handle key storage securely. Typically, operating systems credentials sub-systems handle passwords prompt, private keys storage, and user sessions according to their users password policies. Here is a list of the most popular operating systems and their respective passwords manager:

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 former is a kwallet client.

os is the default option since operating system's default credentials managers are designed to meet users' most common needs and provide them with a comfortable experience without compromising on security.

The file backend

The file backend more closely resembles the keybase implementation 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. If using bash scripts to execute commands using the file option you may want to utilize the following format for multiple prompts:

# assuming that KEYPASSWD is set in the environment
$ gaiacli config keyring-backend file                             # use file backend
$ (echo $KEYPASSWD; echo $KEYPASSWD) | gaiacli keys add me        # multiple prompts
$ echo $KEYPASSWD | gaiacli keys show me                          # single prompt

::: tip The first time you add a key to an empty keyring, you will be prompted to type the password twice. :::

The pass backend

The pass backend uses the pass utility to manage on-disk encryption of keys' 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.

::: tip 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 test backend

The test backend is a password-less variation of the file backend. Keys are stored unencrypted on disk. This backend is meant for testing purposes only and should never be used in production environments.

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.