github.com/fiagdao/tendermint@v0.32.11-0.20220824195748-2087fcc480c1/docs/tools/remote-signer-validation.md (about) 1 # tm-signer-harness 2 3 Located under the `tools/tm-signer-harness` folder in the [Tendermint 4 repository](https://github.com/tendermint/tendermint). 5 6 The Tendermint remote signer test harness facilitates integration testing 7 between Tendermint and remote signers such as 8 [KMS](https://github.com/tendermint/kms). Such remote signers allow for signing 9 of important Tendermint messages using 10 [HSMs](https://en.wikipedia.org/wiki/Hardware_security_module), providing 11 additional security. 12 13 When executed, `tm-signer-harness`: 14 15 1. Runs a listener (either TCP or Unix sockets). 16 2. Waits for a connection from the remote signer. 17 3. Upon connection from the remote signer, executes a number of automated tests 18 to ensure compatibility. 19 4. Upon successful validation, the harness process exits with a 0 exit code. 20 Upon validation failure, it exits with a particular exit code related to the 21 error. 22 23 ## Prerequisites 24 Requires the same prerequisites as for building 25 [Tendermint](https://github.com/tendermint/tendermint). 26 27 ## Building 28 From the `tools/tm-signer-harness` directory in your Tendermint source 29 repository, simply run: 30 31 ```bash 32 make 33 34 # To have global access to this executable 35 make install 36 ``` 37 38 ## Docker Image 39 To build a Docker image containing the `tm-signer-harness`, also from the 40 `tools/tm-signer-harness` directory of your Tendermint source repo, simply run: 41 42 ```bash 43 make docker-image 44 ``` 45 46 ## Running against KMS 47 As an example of how to use `tm-signer-harness`, the following instructions show 48 you how to execute its tests against [KMS](https://github.com/tendermint/kms). 49 For this example, we will make use of the **software signing module in KMS**, as 50 the hardware signing module requires a physical 51 [YubiHSM](https://www.yubico.com/products/yubihsm/) device. 52 53 ### Step 1: Install KMS on your local machine 54 See the [KMS repo](https://github.com/tendermint/kms) for details on how to set 55 KMS up on your local machine. 56 57 If you have [Rust](https://www.rust-lang.org/) installed on your local machine, 58 you can simply install KMS by: 59 60 ```bash 61 cargo install tmkms 62 ``` 63 64 ### Step 2: Make keys for KMS 65 The KMS software signing module needs a key with which to sign messages. In our 66 example, we will simply export a signing key from our local Tendermint instance. 67 68 ```bash 69 # Will generate all necessary Tendermint configuration files, including: 70 # - ~/.tendermint/config/priv_validator_key.json 71 # - ~/.tendermint/data/priv_validator_state.json 72 tendermint init 73 74 # Extract the signing key from our local Tendermint instance 75 tm-signer-harness extract_key \ # Use the "extract_key" command 76 -tmhome ~/.tendermint \ # Where to find the Tendermint home directory 77 -output ./signing.key # Where to write the key 78 ``` 79 80 Also, because we want KMS to connect to `tm-signer-harness`, we will need to 81 provide a secret connection key from KMS' side: 82 83 ```bash 84 tmkms keygen secret_connection.key 85 ``` 86 87 ### Step 3: Configure and run KMS 88 KMS needs some configuration to tell it to use the softer signing module as well 89 as the `signing.key` file we just generated. Save the following to a file called 90 `tmkms.toml`: 91 92 ```toml 93 [[validator]] 94 addr = "tcp://127.0.0.1:61219" # This is where we will find tm-signer-harness. 95 chain_id = "test-chain-0XwP5E" # The Tendermint chain ID for which KMS will be signing (found in ~/.tendermint/config/genesis.json). 96 reconnect = true # true is the default 97 secret_key = "./secret_connection.key" # Where to find our secret connection key. 98 99 [[providers.softsign]] 100 id = "test-chain-0XwP5E" # The Tendermint chain ID for which KMS will be signing (same as validator.chain_id above). 101 path = "./signing.key" # The signing key we extracted earlier. 102 ``` 103 104 Then run KMS with this configuration: 105 106 ```bash 107 tmkms start -c tmkms.toml 108 ``` 109 110 This will start KMS, which will repeatedly try to connect to 111 `tcp://127.0.0.1:61219` until it is successful. 112 113 ### Step 4: Run tm-signer-harness 114 Now we get to run the signer test harness: 115 116 ```bash 117 tm-signer-harness run \ # The "run" command executes the tests 118 -addr tcp://127.0.0.1:61219 \ # The address we promised KMS earlier 119 -tmhome ~/.tendermint # Where to find our Tendermint configuration/data files. 120 ``` 121 122 If the current version of Tendermint and KMS are compatible, `tm-signer-harness` 123 should now exit with a 0 exit code. If they are somehow not compatible, it 124 should exit with a meaningful non-zero exit code (see the exit codes below). 125 126 ### Step 5: Shut down KMS 127 Simply hit Ctrl+Break on your KMS instance (or use the `kill` command in Linux) 128 to terminate it gracefully. 129 130 ## Exit Code Meanings 131 The following list shows the various exit codes from `tm-signer-harness` and 132 their meanings: 133 134 | Exit Code | Description | 135 | --- | --- | 136 | 0 | Success! | 137 | 1 | Invalid command line parameters supplied to `tm-signer-harness` | 138 | 2 | Maximum number of accept retries reached (the `-accept-retries` parameter) | 139 | 3 | Failed to load `${TMHOME}/config/genesis.json` | 140 | 4 | Failed to create listener specified by `-addr` parameter | 141 | 5 | Failed to start listener | 142 | 6 | Interrupted by `SIGINT` (e.g. when hitting Ctrl+Break or Ctrl+C) | 143 | 7 | Other unknown error | 144 | 8 | Test 1 failed: public key mismatch | 145 | 9 | Test 2 failed: signing of proposals failed | 146 | 10 | Test 3 failed: signing of votes failed |