github.com/fibonacci-chain/fbc@v0.0.0-20231124064014-c7636198c1e9/libs/cosmos-sdk/docs/run-node/keyring.md (about)

     1  <!--
     2  order: 1
     3  -->
     4  
     5  # Setting up the keyring
     6  
     7  This document describes how to configure and use the keyring and its various backends for an [**application**](../basics/app-anatomy.md). {synopsis}
     8  
     9  The keyring holds the private/public keypairs used to interact with a node. For instance, a validator key needs to be set up before running the blockchain node, so that blocks can be correctly signed. The private key can be stored in different locations, called "backends", such as a file or the operating system's own key storage.
    10  
    11  ## Available backends for the keyring
    12  
    13  Starting with the v0.38.0 release, Cosmos SDK comes with a new keyring implementation
    14  that provides a set of commands to manage cryptographic keys in a secure fashion. The
    15  new keyring supports multiple storage backends, some of which may not be available on
    16  all operating systems.
    17  
    18  ### The `os` backend
    19  
    20  The `os` backend relies on operating system-specific defaults to handle key storage
    21  securely. Typically, an operating system's credential sub-system handles password prompts,
    22  private keys storage, and user sessions according to the user's password policies. Here
    23  is a list of the most popular operating systems and their respective passwords manager:
    24  
    25  - macOS (since Mac OS 8.6): [Keychain](https://support.apple.com/en-gb/guide/keychain-access/welcome/mac)
    26  - Windows: [Credentials Management API](https://docs.microsoft.com/en-us/windows/win32/secauthn/credentials-management)
    27  - GNU/Linux:
    28    - [libsecret](https://gitlab.gnome.org/GNOME/libsecret)
    29    - [kwallet](https://api.kde.org/frameworks/kwallet/html/index.html)
    30  
    31  GNU/Linux distributions that use GNOME as default desktop environment typically come with
    32  [Seahorse](https://wiki.gnome.org/Apps/Seahorse). Users of KDE based distributions are
    33  commonly provided with [KDE Wallet Manager](https://userbase.kde.org/KDE_Wallet_Manager).
    34  Whilst the former is in fact a `libsecret` convenient frontend, the former is a `kwallet`
    35  client.
    36  
    37  `os` is the default option since operating system's default credentials managers are
    38  designed to meet users' most common needs and provide them with a comfortable
    39  experience without compromising on security.
    40  
    41  ### The `file` backend
    42  
    43  The `file` backend more closely resembles the keybase implementation used prior to
    44  v0.38.1. It stores the keyring encrypted within the app's configuration directory. This
    45  keyring will request a password each time it is accessed, which may occur multiple
    46  times in a single command resulting in repeated password prompts. If using bash scripts
    47  to execute commands using the `file` option you may want to utilize the following format
    48  for multiple prompts:
    49  
    50  ```sh
    51  # assuming that KEYPASSWD is set in the environment
    52  $ gaiacli config keyring-backend file                             # use file backend
    53  $ (echo $KEYPASSWD; echo $KEYPASSWD) | gaiacli keys add me        # multiple prompts
    54  $ echo $KEYPASSWD | gaiacli keys show me                          # single prompt
    55  ```
    56  
    57  ::: tip
    58  The first time you add a key to an empty keyring, you will be prompted to type the password twice.
    59  :::
    60  
    61  ### The `pass` backend
    62  
    63  The `pass` backend uses the [pass](https://www.passwordstore.org/) utility to manage on-disk
    64  encryption of keys' sensitive data and metadata. Keys are stored inside `gpg` encrypted files
    65  within app-specific directories. `pass` is available for the most popular UNIX
    66  operating systems as well as GNU/Linux distributions. Please refer to its manual page for
    67  information on how to download and install it.
    68  
    69  ::: tip
    70  **pass** uses [GnuPG](https://gnupg.org/) for encryption. `gpg` automatically invokes the `gpg-agent`
    71  daemon upon execution, which handles the caching of GnuPG credentials. Please refer to `gpg-agent`
    72  man page for more information on how to configure cache parameters such as credentials TTL and
    73  passphrase expiration.
    74  :::
    75  
    76  The password store must be set up prior to first use:
    77  
    78  ```sh
    79  $ pass init <GPG_KEY_ID>
    80  ```
    81  
    82  Replace `<GPG_KEY_ID>` with your GPG key ID. You can use your personal GPG key or an alternative
    83  one you may want to use specifically to encrypt the password store.
    84  
    85  ### The `test` backend
    86  
    87  The `test` backend is a password-less variation of the `file` backend. Keys are stored
    88  unencrypted on disk. This backend is meant for testing purposes only and **should never be used
    89  in production environments**.
    90  
    91  ### The `kwallet` backend
    92  
    93  The `kwallet` backend uses `KDE Wallet Manager`, which comes installed by default on the
    94  GNU/Linux distributions that ships KDE as default desktop environment. Please refer to
    95  [KWallet Handbook](https://docs.kde.org/stable5/en/kdeutils/kwallet5/index.html) for more
    96  information.
    97  
    98  ## Adding keys to the keyring
    99  
   100  ::: warning
   101  Make sure you can build your own binary, and replace `simd` with the name of your binary in the snippets.
   102  :::
   103  
   104  Applications developed using the Cosmos SDK come with the `keys` subcommand. For the purpose of this tutorial, we're running the `simd` CLI, which is an application built using the Cosmos SDK for testing and educational purposes. For more information, see [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/v0.40.0-rc3/simapp).
   105  
   106  You can use `simd keys` for help about the keys command and `simd keys [command] --help` for more information about a particular subcommand.
   107  
   108  ::: tip
   109  You can also enable auto-completion with the `simd completion` command. For example, at the start of a bash session, run `. <(simd completion)`, and all `simd` subcommands will be auto-completed.
   110  :::
   111  
   112  To create a new key in the keyring, run the `add` subcommand with a `<key_name>` argument. For the purpose of this tutorial, we will solely use the `test` backend, and call our new key `my_validator`. This key will be used in the next section.
   113  
   114  ```bash
   115  $ simd keys add my_validator --keyring-backend test
   116  
   117  # Put the generated address in a variable for later use.
   118  MY_VALIDATOR_ADDRESS=$(simd keys show my_validator -a --keyring-backend test)
   119  ```
   120  
   121  This command generates a new 24-word mnemonic phrase, persists it to the relevant backend, and outputs information about the keypair. If this keypair will be used to hold value-bearing tokens, be sure to write down the mnemonic phrase somewhere safe!
   122  
   123  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 of course hold both types of keys simultaneously, and the Cosmos SDK's `x/auth` module (in particular its [AnteHandlers](../core/baseapp.md#antehandler)) supports natively these two public key algorithms.
   124  
   125  ## Next {hide}
   126  
   127  Read about [running a node](./run-node.md) {hide}
   128