mirror of
https://github.com/fluencelabs/tendermint
synced 2025-04-25 06:42:16 +00:00
e70f27c8e4
* WIP: Starts adding remote signer test harness This commit adds a new command to Tendermint to allow for us to build a standalone binary to test remote signers such as KMS (https://github.com/tendermint/kms). Right now, all it does is test that the local public key matches the public key reported by the client, and fails at the point where it attempts to get the client to sign a proposal. * Fixes typo * Fixes proposal validation test This commit fixes the proposal validation test as per #3149. It also moves the test harness into its own internal package to isolate its exports from the `privval` package. * Adds vote signing validation * Applying recommendations from #3149 * Adds function descriptions for test harness * Adds ability to ask remote signer to shut down Prior to this commit, the remote signer needs to manually be shut down, which is not ideal for automated testing. This commit allows us to send a poison pill message to the KMS to let it shut down gracefully once testing is done (whether the tests pass or fail). * Adds tests for remote signer test harness This commit makes some minor modifications to a few files to allow for testing of the remote signer test harness. Two tests are added here: checking for a fully successful (the ideal) case, and for the case where the maximum number of retries has been reached when attempting to accept incoming connections from the remote signer. * Condenses serialization of proposals and votes using existing Tendermint functions * Removes now-unnecessary amino import and codec * Adds error message for vote signing failure * Adds key extraction command for integration test Took the code from here: https://gist.github.com/Liamsi/a80993f24bff574bbfdbbfa9efa84bc7 to create a simple utility command to extract a key from a local Tendermint validator for use in KMS integration testing. * Makes path expansion success non-compulsory * Fixes segfault on SIGTERM We need an additional variable to keep track of whether we're successfully connected, otherwise hitting Ctrl+Break during execution causes a segmentation fault. This now allows for a clean shutdown. * Consolidates shutdown checks * Adds comments indicating codes for easy lookup * Adds Docker build for remote signer harness Updates the `DOCKER/build.sh` and `DOCKER/push.sh` files to allow one to override the image name and Dockerfile using environment variables. Updates the primary `Makefile` as well as the `DOCKER/Makefile` to allow for building the `remote_val_harness` Docker image. * Adds build_remote_val_harness_docker_image to .PHONY * Removes remote signer poison pill messaging functionality * Reduces fluff code in command line parsing As per https://github.com/tendermint/tendermint/pull/3149#pullrequestreview-196171788, this reduces the amount of fluff code in the PR down to the bare minimum. * Fixes ordering of error check and info log * Moves remove_val_harness cmd into tools folder It seems to make sense to rather keep the remote signer test harness in its own tool folder (now rather named `tm-signer-harness` to keep with the tool naming convention). It is actually a separate tool, not meant to be one of the core binaries, but supplementary and supportive. * Updates documentation for tm-signer-harness * Refactors flag parsing to be more compact and less redundant * Adds version sub-command help * Removes extraneous flags parsing * Adds CHANGELOG_PENDING entry for tm-signer-harness * Improves test coverage Adds a few extra parameters to the `MockPV` type to fake broken vote and proposal signing. Also adds some more tests for the test harness so as to increase coverage for failed cases. * Fixes formatting for CHANGELOG_PENDING.md * Fix formatting for documentation config * Point users towards official Tendermint docs for tools documentation * Point users towards official Tendermint docs for tm-signer-harness * Remove extraneous constant * Rename TestHarness.sc to TestHarness.spv for naming consistency * Refactor to remove redundant goroutine * Refactor conditional to cleaner switch statement and better error handling for listener protocol * Remove extraneous goroutine * Add note about installing tmkms via Cargo * Fix typo in naming of output signing key * Add note about where to find chain ID * Replace /home/user with ~/ for brevity * Fixes "signer.key" typo * Minor edits for clarification for tm-signer-harness bulid/setup process
147 lines
5.3 KiB
Markdown
147 lines
5.3 KiB
Markdown
# tm-signer-harness
|
|
|
|
Located under the `tools/tm-signer-harness` folder in the [Tendermint
|
|
repository](https://github.com/tendermint/tendermint).
|
|
|
|
The Tendermint remote signer test harness facilitates integration testing
|
|
between Tendermint and remote signers such as
|
|
[KMS](https://github.com/tendermint/kms). Such remote signers allow for signing
|
|
of important Tendermint messages using
|
|
[HSMs](https://en.wikipedia.org/wiki/Hardware_security_module), 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](https://github.com/tendermint/tendermint).
|
|
|
|
## Building
|
|
From the `tools/tm-signer-harness` directory in your Tendermint source
|
|
repository, simply run:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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 [KMS](https://github.com/tendermint/kms).
|
|
For this example, we will make use of the **software signing module in KMS**, as
|
|
the hardware signing module requires a physical
|
|
[YubiHSM](https://www.yubico.com/products/yubihsm/) device.
|
|
|
|
### Step 1: Install KMS on your local machine
|
|
See the [KMS repo](https://github.com/tendermint/kms) for details on how to set
|
|
KMS up on your local machine.
|
|
|
|
If you have [Rust](https://www.rust-lang.org/) installed on your local machine,
|
|
you can simply install KMS by:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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 |
|