tendermint/docs/tools/remote-signer-validation.md

Remote Signer

Located under the tools/tm-signer-harness folder in the Tendermint repository.

The Tendermint remote signer test harness facilitates integration testing between Tendermint and remote signers such as tkkms. Such remote signers allow for signing of important Tendermint messages using HSMs, providing additional security.

When executed, tm-signer-harness:

1. Runs a listener (either TCP or Unix sockets).
2. Waits for a connection from the remote signer.
3. Upon connection from the remote signer, executes a number of automated tests to ensure compatibility.
4. Upon successful validation, the harness process exits with a 0 exit code. Upon validation failure, it exits with a particular exit code related to the error.

Prerequisites

Requires the same prerequisites as for building Tendermint.

Building

From the tools/tm-signer-harness directory in your Tendermint source repository, simply run:

make

# To have global access to this executable
make install

Docker Image

To build a Docker image containing the tm-signer-harness, also from the tools/tm-signer-harness directory of your Tendermint source repo, simply run:

make docker-image

Running against KMS

As an example of how to use tm-signer-harness, the following instructions show you how to execute its tests against tkkms. For this example, we will make use of the software signing module in KMS, as the hardware signing module requires a physical YubiHSM device.

Step 1: Install KMS on your local machine

See the tkkms repo for details on how to set KMS up on your local machine.

If you have Rust installed on your local machine, you can simply install KMS by:

cargo install tmkms

Step 2: Make keys for KMS

The KMS software signing module needs a key with which to sign messages. In our example, we will simply export a signing key from our local Tendermint instance.

# Will generate all necessary Tendermint configuration files, including:
# - ~/.tendermint/config/priv_validator_key.json
# - ~/.tendermint/data/priv_validator_state.json
tendermint init validator

# Extract the signing key from our local Tendermint instance
tm-signer-harness extract_key \      # Use the "extract_key" command
    -tmhome ~/.tendermint \          # Where to find the Tendermint home directory
    -output ./signing.key            # Where to write the key

Also, because we want KMS to connect to tm-signer-harness, we will need to provide a secret connection key from KMS' side:

tmkms keygen secret_connection.key

Step 3: Configure and run KMS

KMS needs some configuration to tell it to use the softer signing module as well as the signing.key file we just generated. Save the following to a file called tmkms.toml:

[[validator]]
addr = "tcp://127.0.0.1:61219"         # This is where we will find tm-signer-harness.
chain_id = "test-chain-0XwP5E"         # The Tendermint chain ID for which KMS will be signing (found in ~/.tendermint/config/genesis.json).
reconnect = true                       # true is the default
secret_key = "./secret_connection.key" # Where to find our secret connection key.

[[providers.softsign]]
id = "test-chain-0XwP5E"               # The Tendermint chain ID for which KMS will be signing (same as validator.chain_id above).
path = "./signing.key"                 # The signing key we extracted earlier.

Then run KMS with this configuration:

tmkms start -c tmkms.toml

This will start KMS, which will repeatedly try to connect to tcp://127.0.0.1:61219 until it is successful.

Step 4: Run tm-signer-harness

Now we get to run the signer test harness:

tm-signer-harness run \             # The "run" command executes the tests
    -addr tcp://127.0.0.1:61219 \   # The address we promised KMS earlier
    -tmhome ~/.tendermint           # Where to find our Tendermint configuration/data files.

If the current version of Tendermint and KMS are compatible, tm-signer-harness should now exit with a 0 exit code. If they are somehow not compatible, it should exit with a meaningful non-zero exit code (see the exit codes below).

Step 5: Shut down KMS

Simply hit Ctrl+Break on your KMS instance (or use the kill command in Linux) to terminate it gracefully.

Exit Code Meanings

The following list shows the various exit codes from tm-signer-harness and their meanings:

Exit Code	Description
0	Success!
1	Invalid command line parameters supplied to tm-signer-harness
2	Maximum number of accept retries reached (the -accept-retries parameter)
3	Failed to load ${TMHOME}/config/genesis.json
4	Failed to create listener specified by -addr parameter
5	Failed to start listener
6	Interrupted by SIGINT (e.g. when hitting Ctrl+Break or Ctrl+C)
7	Other unknown error
8	Test 1 failed: public key mismatch
9	Test 2 failed: signing of proposals failed
10	Test 3 failed: signing of votes failed