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

# Remote Signer

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
[tkkms](https://github.com/iqlusioninc/tmkms). 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 [tkkms](https://github.com/iqlusioninc/tmkms).
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 [tkkms repo](https://github.com/iqlusioninc/tmkms) 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 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:

```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 |