Located under the
tools/tm-signer-harness folder in the Tendermint
The Tendermint remote signer test harness facilitates integration testing between Tendermint and remote signers such as KMS. Such remote signers allow for signing of important Tendermint messages using HSMs, providing additional security.
- Runs a listener (either TCP or Unix sockets).
- Waits for a connection from the remote signer.
- Upon connection from the remote signer, executes a number of automated tests to ensure compatibility.
- 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.
Requires the same prerequisites as for building Tendermint.
tools/tm-signer-harness directory in your Tendermint source
repository, simply run:
make # To have global access to this executable make install
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:
Running against KMS
As an example of how to use
tm-signer-harness, the following instructions show
you how to execute its tests against KMS.
For this example, we will make use of the software signing module in KMS, as
the hardware signing module requires a physical
Step 1: Install KMS on your local machine
See the KMS 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 # 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
signing.key file we just generated. Save the following to a file called
[[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,
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
|1||Invalid command line parameters supplied to |
|2||Maximum number of accept retries reached (the |
|3||Failed to load |
|4||Failed to create listener specified by |
|5||Failed to start listener|
|6||Interrupted by |
|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|