Merge PR cosmos#3659: KMS Documentation/Tutorial. How to run a Valida…

…tor with a Ledger device

docs/cosmos-hub/validators/kms/kms.md

@@ -0,0 +1,34 @@
+# KMS - Key Management System
+
+[Tendermint KMS](https://github.com/tendermint/kms) is a key management service that allows separating key management from Tendermint nodes. In addition it provides other advantages such as:
+
+- Improved security and risk management policies
+- Unified API and support for various HSM (hardware security modules)
+- Double signing protection (software or hardware based)
+
+It is recommended that the KMS service runs in a separate physical hosts.
+
+## Building
+
+Detailed build instructions can be found [here](https://github.com/tendermint/kms#installation).
+
+::: tip
+When compiling the KMS, ensure you have enabled the applicable features:
+:::
+
+| Backend               | Recommended Command line              |
+|-----------------------|---------------------------------------|
+| YubiHSM               | ```cargo build --features yubihsm```  |
+| Ledger+Tendermint App | ```cargo build --features ledgertm``` |
+
+## Configuration
+
+A KMS can be configured in various ways:
+
+### Using a YubiHSM
+
+  Detailed information on how to setup a KMS with YubiHSM2 can be found [here](https://github.com/tendermint/kms/blob/master/README.yubihsm.md)
+
+### Using a Ledger device running the Tendermint app
+
+  Detailed information on how to setup a KMS with Ledger Tendermint App can be found [here](kms_ledger.md)

docs/cosmos-hub/validators/kms/kms_ledger.md

@@ -0,0 +1,113 @@
+# Setting up Tendermint KMS + Ledger
+
+::: danger Warning
+The following instructions are a brief walkthrough and not a comprehensive guideline. You should consider and [research more about the security implications](./security.md) of activating an external KMS.
+:::
+
+::: danger Warning
+KMS and Ledger Tendermint app are currently work in progress. Details may vary. Use with care under your own risk.
+:::
+
+## Tendermint Validator app (for Ledger devices)
+
+You should be able to find the Tendermint app in Ledger Live.
+
+*Note: at the moment, you might need to enable `developer mode` in Ledger Live settings*
+
+## KMS configuration
+
+In this section, we will configure a KMS to use a Ledger device running the Tendermint Validator App. 
+
+### Config file
+
+You can find other configuration examples [here](https://github.com/tendermint/kms/blob/master/tmkms.toml.example)
+
+- Create a `~/.tmkms/tmkms.toml` file with the following content (use an adequate `chain_id`)
+
+```toml
+# Example KMS configuration file
+[[validator]]
+addr = "tcp://localhost:26658"    # or "unix:///path/to/socket"
+chain_id = "gaia-11001"
+reconnect = true # true is the default
+secret_key = "~/.tmkms/secret_connection.key"
+
+[[providers.ledgertm]]
+chain_ids = ["gaia-11001"]
+```
+
+- Edit `addr` to point to your `gaiad` instance.
+- Adjust `chain-id` to match your `.gaiad/config/config.toml` settings.
+- `provider.ledgertm` has not additional parameters at the moment, however, it is important that you keep that header to enable the feature.
+
+*Plug your Ledger device and open the Tendermint validator app.*
+
+### Generate secret key
+
+Now you need to generate secret_key:
+
+```bash
+tmkms keygen ~/.tmkms/secret_connection.key
+```
+
+### Retrieve validator key
+
+The last step is to retrieve the validator key that you will use in `gaiad`.
+
+Start the KMS:
+
+```bash
+tmkms start -c ~/.tmkms/tmkms.toml
+```
+
+The output should look similar to:
+
+```text
+07:28:24 [INFO] tmkms 0.3.0 starting up...
+07:28:24 [INFO] [keyring:ledgertm:ledgertm] added validator key cosmosvalconspub1zcjduepqy53m39prgp9dz3nz96kaav3el5e0th8ltwcf8cpavqdvpxgr5slsd6wz6f
+07:28:24 [INFO] KMS node ID: 1BC12314E2E1C29015B66017A397F170C6ECDE4A
+```
+
+The KMS may complain that it cannot connect to gaiad. That is fine, we will fix it in the next section.
+
+This output indicates the validator key linked to this particular device is: `cosmosvalconspub1zcjduepqy53m39prgp9dz3nz96kaav3el5e0th8ltwcf8cpavqdvpxgr5slsd6wz6f`
+
+Take note of the validator pubkey that appears in your screen. *We will use it in the next section.*
+
+## Gaia configuration
+
+You need to enable KMS access by editing `.gaiad/config/config.toml`. In this file, modify `priv_validator_laddr` to create a listening address/port or a unix socket in `gaiad`.
+
+For example:
+
+```toml
+...
+# TCP or UNIX socket address for Tendermint to listen on for
+# connections from an external PrivValidator process
+priv_validator_laddr = "tcp://127.0.0.1:26658"
+...
+```
+
+Let's assume that you have set up your validator account and called it `kmsval`. You can tell gaiad the key that we've got in the previous section.
+
+```bash
+gaiad gentx --name kmsval --pubkey {.ValidatorKey} 
+```
+
+Now start `gaiad`. You should see that the KMS connects and receives a signature request.
+
+Once the ledger receives the first message, it will ask for confirmation that the values are adequate.
+
+![](ledger_1.jpg)
+
+Click the right button, if the height and round are correct.
+
+After that, you will see that the KMS will start forwarding all signature requests to the ledger:
+
+![](ledger_2.jpg)
+
+::: danger Warning
+The word TEST in the second picture, second line appears because they were taken on a pre-release version.
+
+Once the app as been released in Ledger's app store, this word should NOT appear.
+:::

docs/cosmos-hub/validators/security.md

@@ -25,6 +25,7 @@ Sentry nodes can be quickly spun up or change their IP addresses. Because the li
 To setup your sentry node architecture you can follow the instructions below:
 
 Validators nodes should edit their config.toml:
+
 ```bash
 # Comma separated list of nodes to keep persistent connections to
 # Do not add private peers to this list if you don't want them advertised
@@ -35,6 +36,7 @@ pex = false
 ```
 
 Sentry Nodes should edit their config.toml:
+
 ```bash
 # Comma separated list of peer IDs to keep private (will not be gossiped to other peers)
 # Example ID: 3e16af0cead27979e1fc3dac57d03df3c7a77acc@3.87.179.235:26656
@@ -50,5 +52,5 @@ By default, uppercase environment variables with the following prefixes will rep
 - `TM` (for Tendermint flags)
 - `BC` (for democli or basecli flags)
 
-For example, the environment variable `GA_CHAIN_ID` will map to the command line flag `--chain-id`. Note that while explicit command-line flags will take precedence over environment variables, environment variables will take precedence over any of your configuration files. For this reason, it's imperative that you lock down your environment such that any critical parameters are defined as flags on the CLI or prevent modification of any environment variables. 
-
+For example, the environment variable `GA_CHAIN_ID` will map to the command line flag `--chain-id`. Note that while explicit command-line flags will take precedence over environment variables, environment variables will take precedence over any of your configuration files. For this reason, it's imperative that you lock down your environment such that any critical parameters are defined as flags on the CLI or prevent modification of any environment variables.
+

docs/cosmos-hub/validators/validator-setup.md

@@ -6,6 +6,8 @@ Information on how to join the mainnet (`genesis.json` file and seeds) is held [
 
 Before setting up your validator node, make sure you've already gone through the [Full Node Setup](../join-mainnet.md) guide.
 
+If you plan to use a KMS (key management system), you should go through these steps first: [Using a KMS](kms/kms.md).
+
 ## What is a Validator?
 
 [Validators](./overview.md) are responsible for committing new blocks to the blockchain through voting. A validator's stake is slashed if they become unavailable or sign blocks at the same height. Please read about [Sentry Node Architecture](./validator-faq.md#how-can-validators-protect-themselves-from-denial-of-service-attacks) to protect your node from DDOS attacks and to ensure high-availability.