> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting up the keyring

<Note>
  **Prerequisite Readings**

  * [Prerequisites](/sdk/latest/node/prerequisites) - Set up Go and build the `simd` binary
</Note>

The keyring holds the private/public key pairs used to interact with a node. A validator key needs to be set up before running the blockchain node so that blocks can be correctly signed.

## Create a key

1. Create a new key for your validator:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
simd keys add my_validator --keyring-backend test
```

2. Store the address for later use:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}

MY_VALIDATOR_ADDRESS=$(simd keys show my_validator -a --keyring-backend test)
```

This generates a 24-word mnemonic phrase and stores your key. **Save the mnemonic** if you'll use this key for value-bearing tokens.

<Tip>
  This tutorial uses the `test` backend (unencrypted, for testing only). For production, use the `os` backend which integrates with your system's secure keyring. See [keyring backends](#reference:-keyring-backends) below for more information.
</Tip>

## Next steps

You have just created your first key. The keyring is now ready to manage keys for interacting with your blockchain node.

If you are running through this tutorial as a test, continue to [Run a node](/sdk/latest/node/run-node) to initialize your blockchain and start your node.

For more information on the keyring and its various backends, continue reading below.

## Reference: Keyring backends

The Cosmos SDK keyring supports multiple storage backends. The private key can be stored in different locations such as a file or the operating system's own key storage.

### The `os` backend

The `os` backend relies on operating system-specific defaults to handle key storage
securely. Typically, an operating system's credential subsystem handles password prompts,
private key storage, and user sessions according to the user's password policies. Here
is a list of the most popular operating systems and their respective password managers:

* macOS: [Keychain](https://support.apple.com/en-gb/guide/keychain-access/welcome/mac)
* Windows: [Credentials Management API](https://docs.microsoft.com/en-us/windows/win32/secauthn/credentials-management)
* GNU/Linux:
  * [libsecret](https://gitlab.gnome.org/GNOME/libsecret)
  * [kwallet](https://api.kde.org/kwallet-index.html)
  * [keyctl](https://www.kernel.org/doc/html/latest/security/keys/core.html)

GNU/Linux distributions that use GNOME as the default desktop environment typically come with
[Seahorse](https://wiki.gnome.org/Apps/Seahorse). Users of KDE based distributions are
commonly provided with [KDE Wallet Manager](https://userbase.kde.org/KDE_Wallet_Manager).
Whilst the former is in fact a `libsecret` convenient frontend, the latter is a `kwallet`
client. `keyctl` is a secure backend that leverages the Linux's kernel security key management system
to store cryptographic keys securely in memory.

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

The recommended backends for headless environments are `file` and `pass`.

### 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 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. If using bash scripts
to execute commands using the `file` option, you may want to utilize the following format
for multiple prompts:

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# 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.
</Tip>

### The `pass` backend

The `pass` backend uses the [pass](https://www.passwordstore.org/) 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](https://gnupg.org/) 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.
</Tip>

The password store must be set up prior to first use:

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
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](https://userbase.kde.org/KDE_Wallet_Manager) for more
information.

### The `keyctl` backend

The *Kernel Key Retention Service* is a security facility that
has been added to the Linux kernel relatively recently. It allows sensitive
cryptographic data such as passwords, private keys, authentication tokens, etc.
to be stored securely in memory.

The `keyctl` backend is available on Linux platforms only.

### The `test` backend

The `test` backend is a password-less variation of the `file` backend. Keys are stored
unencrypted on disk.

**Provided for testing purposes only. The `test` backend is not recommended for use in production environments**.

### The `memory` backend

The `memory` backend stores keys in memory. The keys are immediately deleted after the program has exited.

**Provided for testing purposes only. The `memory` backend is not recommended for use in production environments**.

### Setting backend using the env variable

You can set the keyring-backend using an environment variable: `BINNAME_KEYRING_BACKEND`. For example, if your binary name is `gaia-v5`, then set: `export GAIA_V5_KEYRING_BACKEND=pass`

### Additional key management

By default, the keyring generates a `secp256k1` keypair. The keyring also supports `ed25519` keys, which may be created by passing the `--algo ed25519` flag. A keyring can hold both types of keys simultaneously, and the Cosmos SDK's `x/auth` module supports both public key algorithms natively.

For help with key management commands, use `simd keys --help` or `simd keys [command] --help`.