Skip to main content

Tendermint KMS

Tendermint KMS is a  Key Management Service (KMS) that allowing key management to be separated from Tendermint nodes. Additionally, it offers additional benefits like:

  • Improved risk management and security procedures
  • Support for numerous HSMs (hardware security modules) and a unified API
  • Hardware-based or software-based double signing protection

Running the KMS service on a different physical host is advised. You may find instructions for setting up a Key Management System for Humans.ai with or without a Ledger device on this page.

Install Tendermint KMS onto the node​

You will need the following prerequisites:

  • ✅ Rust (stable; 1.56+): https://rustup.rs/

  • ✅ C compiler: e.g. gcc, clang

  • ✅ pkg-config

  • ✅ libusb (1.0+). Install instructions for common platforms

  • ✅ Debian/Ubuntu

    apt install libusb-1.0-0-dev

  • ✅ RedHat/CentOS

    yum install libusb1-devel

  • ✅ macOS (Homebrew)

    brew install libusb
tip

Only for x86_64 architecture, RUSTFLAGS environment variable configuration:

export RUSTFLAGS=-Ctarget-feature=+aes,+ssse3

KMS installation is ready to go. You can install using Rusts cargo-install or compile from source, respectively. We'll pick the first possibility.

Compile from source code​

The --features=ledger option is added to the example below to enable Ledger support. The following commands can be used to compile tmkms directly from the source code of the git repository:

gh repo clone iqlusioninc/tmkms && cd tmkms
[...]
cargo build --release --features=ledger

To enable support for YubiHSM, use the alternative command line argument --features=yubihsm.

tmkms executable, which is located at ./target/release/tmkms, will be created if it is successful.

Configuration​

These HSMs can be used to configure a KMS:

YubiHSM​

You can find comprehensive instructions on setting up a KMS with YubiHSM 2 here.

Tendermint KMS + Ledger​

Set up Tendermint KMS with the Tendermint Ledger app.

danger

🚧 The guidelines that follow are not a comprehensive manual; rather, they are a quick walkthrough.

🚨IMPORTANT: Use KMS and Ledger Tendermint at your own risk, as the app is currently work in progress.

Prerequisites​

Checklist​

  • Ledger Nano X or Nano S device (compare here)
  • Ledger Live installed
  • Tendermint app installed (only in Developer Mode)
  • Latest Versions (Firmware and Tendermint app)

Tendermint Validator app (for Ledger devices)​

The Tendermint app should be accessible in Ledger Live. To find the app, you must 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 may find further configuration examples here

  • Create a ~/.tmkms/tmkms.toml file with the following information (use a correct chain_id)
# Example KMS configuration file
[[validator]]
addr = "tcp://localhost:26658"                  # or "unix:///path/to/socket"
chain_id = "humans_1089-1"
reconnect = true                                # true is the default
secret_key = "~/.tmkms/secret_connection.key"

[[providers.ledger]]
chain_ids = ["humans_1089-1"]
  • Modify addr to point to your instance of humansd.
  • Modify chain-id to reflect the parameters in your .humansd/config/config.toml file.
  • Although provider.ledger does not yet have any further parameters, it is crucial that you preserve that header in order to enable the feature.

Connect your Ledger device, then launch the Tendermint validator application.

Generate secret key​

You must now create a secret_key:

tmkms keygen ~/.tmkms/secret_connection.key

Retrieve validator key​

The final step is to get the validator key you'll need for "humansd."

Launch the KMS:

tmkms start -c ~/.tmkms/tmkms.toml

The output should look similar to:

07:28:24 [INFO] tmkms 0.11.0 starting up...
07:28:24 [INFO] [keyring:ledger:ledger] added validator key humanvalconspub1jhgbnmvpqr53is9pcta9mz96xhgdcee2v0th8lts7a8cvqdvpxgr5slsd6wz6f
07:28:24 [INFO] KMS node ID: 1AC12345F2E1C29015B66017A397F170C6ECEF5B

If the KMS cannot connect to humansd, it can complain. Fine, we'll change that in the section after this one. According to this output, the validator key associated with this specific device is: humanvalconspub1jhgbnmvpqr53is9pcta9mz96xhgdcee2v0th8lts7a8cvqdvpxgr5slsd6wz6f Observe the validator pubkey that displays on your screen and take note of it. In the section after this, we'll use it.

Humans.ai configuration​

Editing .humansd/config/config.toml is required to enable KMS access. Change the value of the priv_validator_laddr variable in this file to humansd to create a listening address/port or a unix socket.

For example:

...
# 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"
...

Assume you have created your validator account and given it the name "kmsval." You can inform humansd of the key we discussed in the earlier section.

humansd gentx --name kmsval --pubkey <pub_key>

Start humansd at this point. You need to observe that the KMS connects and receives a request for a signature.

The Ledger device will request confirmation that the settings are appropriate when it gets the first message.

If the height and round are accurate, press the right button.

Following that, you will observe that the KMS will begin sending all requests for signatures to the Ledger app:

danger

Because they were captured using a pre-release version, the word TEST can be seen in the second image's second line. This phrase should not show until the app has been made available in Ledger's app store.