Install and configure TMKMS (softsign) for Agoric

Emre NOP |
3 min readApr 25


TMKMS is the key management system for Tendermint applications. TMKMS provides support for hardware and software signing.
HSM modules are recommended for use with TMKMS which can be FortanixDSM, YubiHSM2, or Ledger. YubiHSM2 is the most popular HSM currently and is recommended to use but if you want to install TMKMS on one of the virtual servers that you can not attach an HSM device, you may prefer to Soft-signing.
By using soft-signing, You’ll be protected from double signing but still, the private key will be on the server and required to take additional hardening measures to keep keys secure. If your key leaks somehow, a Malicious intruder can create a new validator node and might end up with double signing again. Please be aware of the risk before installing TMKMS and keep your TMKMS node secure as your validator node.
in this article, I would like to describe how you can set up TMKMS and connect to your Agoric node which is working for a while as a validator. All steps would be the same for other Cosmos Nodes.

0 — Install required libraries

apt install curl, git

install rust from and

source "$HOME/.cargo/env"

1 — Compiling from source code

Download source code

$ git clone && cd tmkms

Features are just including soft sign but if you would like to compile with YubiHSM2 support add Yubihsm as well. ( — features=yubihsm,softsign)

$ cargo build --release --features=softsign
$ cargo install tmkms --features=softsign
$ mkdir -p ~/.tmkms/state && mkdir ~/.tmkms/secrets
$ cd ~/.tmkms && touch tmkms.toml

2 — Add your config

Add the below config to tmkms.toml file and update required parts like chain-id, ip address, etc.

# Tendermint KMS configuration file

## Chain Configuration

### Cosmos Hub Network

id = "agoric-emerynet-5"
key_format = { type = "bech32", account_key_prefix = "agoricpub", consensus_key_prefix = "agoricvalconspub" }
state_file = "/root/.tmkms/state/priv_validator_state.json"

## Signing Provider Configuration

### Software-based Signer Configuration

chain_ids = ["agoric-emerynet-5"]
key_type = "consensus"
path = "/root/.tmkms/secrets/priv_validator_key"

## Validator Configuration

chain_id = "agoric-emerynet-5"
addr = "tcp://"
secret_key = "/root/.tmkms/secrets/secret_connection_key"
protocol_version = "v0.34"
reconnect = true

3 — Create your secret connection key

This key will be used to communicate with your validator server.

tmkms softsign keygen ~/.tmkms/secrets/secret_connection_key

4 — Copy your priv_validator_key.json and import

Copy your validator private validator key file into TMKMS server. You’ll find the key file in the config path of your validator server (~/.agoric/config/priv_validator_key.json)

$ tmkms softsign import emerynet-priv_validator_key.json ~/.tmkms/secrets/priv_validator_key

5 — Start TMKMS server

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

6 — Update your validator config

3 configuration needs to be updated on your validator server. Comment out the below three configurations and add priv_validator_laddr as below.

# priv_validator_key_file = "config/priv_validator_key.json"
# priv_validator_state_file = "data/priv_validator_state.json"
# priv_validator_laddr = ""
priv_validator_laddr = "tcp://"

7 — Restart your validator node and check TMKMS Logs

You validator node will start listening port 26659 after restart and you should see TMKMS connect log like below:

2023-04-25T18:50:37.488682Z ERROR tmkms::client: [agoric-emerynet-5@tcp://] I/O error: Connection refused (os error 111)
^[[I2023-04-25T18:50:38.488855Z INFO tmkms::connection::tcp: KMS node ID: b42e5ebf729cede2e892384a94eaa878a6368bfc
2023-04-25T18:50:38.490027Z INFO tmkms::session: [agoric-emerynet-5@tcp://] connected to validator successfully
2023-04-25T18:50:38.490054Z WARN tmkms::session: [agoric-emerynet-5@tcp://]: unverified validator peer ID! (755ddc631c64f92f22a173983a7a01a83954a7fa)
2023-04-25T18:53:15.291904Z INFO tmkms::session: [agoric-emerynet-5@tcp://] signed PreCommit:<nil> at h/r/s 3944352/0/2 (0 ms)
2023-04-25T18:53:15.481364Z INFO tmkms::session: [agoric-emerynet-5@tcp://] signed PreVote:F082CA4A47 at h/r/s 3944353/0/1 (0 ms)
2023-04-25T18:53:15.683202Z INFO tmkms::session: [agoric-emerynet-5@tcp://] signed PreCommit:F082CA4A47 at h/r/s 3944353/0/2 (0 ms)
2023-04-25T18:53:20.813982Z INFO tmkms::session: [agoric-emerynet-5@tcp://] signed PreVote:7C3A42B624 at h/r/s 3944354/0/1 (0 ms)

8 — Remove key files

If everything goes well, and your TMKMS starts to sign blocks, You can delete the priv_validator_key.json file from your Agoric and TMKMS node and store it safely offline place. ~/.tmkms/secrets/priv_validator_key will be used to sign blocks.