Merge PR #3659: KMS Documentation/Tutorial. How to run a Validator 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

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.