Located under the
tools/tm-signer-harness folder in the Tendermint
repository (opens new window).
The Tendermint remote signer test harness facilitates integration testing between Tendermint and remote signers such as KMS (opens new window). Such remote signers allow for signing of important Tendermint messages using HSMs (opens new window), 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 (opens new window).
tools/tm-signer-harness directory in your Tendermint source
repository, simply run:
# 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:
# 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 (opens new window).
For this example, we will make use of the software signing module in KMS, as
the hardware signing module requires a physical
YubiHSM (opens new window) device.
# Step 1: Install KMS on your local machine
See the KMS repo (opens new window) for details on how to set KMS up on your local machine.
If you have Rust (opens new window) installed on your local machine, you can simply install KMS by:
# 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.
Also, because we want KMS to connect to
tm-signer-harness, we will need to
provide a secret connection key from KMS' side:
# 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
Then run KMS with this configuration:
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:
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|