Setting Up HashiCorp Vault + EthSigner

Page Contents

Introduction

Install HashiCorp Vault

Install EthSigner

Prepare Files To Enable TLS

Run Vault Server & Import Private Key

Run EthSigner Server

Test

Introduction

HashiCorp Vault (hereon called Vault) allows you to securely store secrets in one place. Docs: https://developer.hashicorp.com/vault/tutorials/getting-started

EthSigner allows you to sign transactions in an isolated environment using a private key secured by Vault. Docs: https://docs.ethsigner.consensys.io/

Security Notes

The connection between EthSigner and Vault is secured by TLS (the private key is passed along this connection). The connection between the NodeJS App and EthSigner is not TLS secured, which is not a major concern as the signed transaction object cannot be used in replay attacks. All traffic stays within the localhost loopback within your local server, so no messages are passed on your local network.

Install HashiCorp Vault

1. sudo apt update

   • updates apt-installed packages

2. sudo apt install gpg wget

   • installs gpg (GNU Privacy Guard), which is a cryptography library, and wget, which is like curl but used mostly for downloading files

3. wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg

   • This downloads a "keyring" from HashiCorp and puts it into the file defined by the last part of the command (the pipe key "|" takes ouput of statement before and uses it as the input for the statement after)

   • If you get a certificate verification error, use wget -O- https://apt.releases.hashicorp.com/gpg --no-check-certificate | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg

4. gpg --no-default-keyring --keyring /usr/share/keyrings/hashicorp-archive-keyring.gpg --fingerprint

   • This verifies the keyring

5. echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list

   • This writes the string in the quotes to the file after the pipe key ("|"). The string is a command to use the "deb" package manager to download a repo from the https url. The package is signed by the key ring you downloaded earlier. "$lsb_release -cs" prints the version of Ubuntu of your system.

6. sudo apt update && sudo apt install vault

   • This installs Vault using the apt package manager

7. Check installation with vault and vault --version

Install EthSigner

1. sudo apt-get install openjdk-17-jdk

   • Installs Java 17 (must use Java 17, not Java 11); 500MB

2. Download ethsigner.tar.gz file (.tar.gz is like a .zip file) in link:

   • https://cloudsmith.io/~consensys/repos/ethsigner/packages/?q=tag%3Alatest
3. cd into the folder where you want the folder extracted

4. tar -xzvf filename.tar.gz

   • extracts the files into a folder called "ethsigner-23.6.0"

5. Check installation

   1. cd into "ethsigner-23.6.0" folder and run ./bin/ethsigner --help

      • Success shows a list of EthSigner commands

      • If it doesn't work, check the permissions of the "ethsigner" binary:

        1. cd into "ethsigner-23.6.0" folder, cd into "bin" folder

        2. run ls, you should see the files "ethsigner" and "ethsigner.bat"

        3. run ls -l ./ethsigner, ensure you have "x" (executable) permissions. If not, then run chmod +x ./ethsigner

Prepare Files To Enable TLS Between EthSigner and Vault

1. cd "ethsigner-23.6.0" folder, mkdir tls, cd into "tls" folder

2. Generate the TLS private key and certificate

   1. openssl req -x509 -sha256 -days 3560 -nodes -newkey rsa:2048 -subj "/CN=localhost" -addext "subjectAltName=IP:127.0.0.1" -keyout vault.key -out vault.crt

      • the command "-addext "subjectAltName=IP:127.0.0.1"" adds an Alternative Name to the certificate, which is usually not needed but is needed for HashiCorp Vault

3. Get SHA-256 fingerprint of vault.crt

   1. openssl x509 -in vault.crt -noout -fingerprint -sha256

   2. Copy it to somewhere temporarily (we will use it in next step)

4. For TLS connections, EthSigner requires a "knownServers" file. From the perspective of EthSigner, HashiCorp Vault is a server

   1. touch knownServers && vim knownServers

   2. press i to start editing, enter two lines:

      1. line 1: localhost:8200 <sha256 fingerprint of vault.crt>

      2. line 2: 127.0.0.1:8200 <sha256 fingerprint of vault.crt>

      3. ctrl + c , :wq, then Enter to save & exit

Run Vault Server & Import Private Key

1. cd into "ethsigner-23.6.0" folder (cd out of "tls" folder)

2. create config.hcl file

   1. touch config.hcl && vim config.hcl

   2. i to start editing. Copy in the below:

      • storage "raft" {
          path    = "./vault/data"
          node_id = "node1"
        }
        
        listener "tcp" {
        address = "127.0.0.1:8200"
        tls_cert_file = "./tls/vault.crt"
        tls_key_file = "./tls/vault.key"
        }
        
        disable_mlock = true
        
        api_addr = "http://127.0.0.1:8200"
        cluster_addr = "https://127.0.0.1:8201"
        ui = true

   3. ctrl + c , :wq, then Enter to save & exit

3. mkdir -p ./vault/data to create "vault/data" folder

   • If you previously created a Vault instance, be sure to delete all contents of old data folder

   • This is where encrypted secrets are stored using Raft, which is the Integrated Storage backend used to persist Vault's data

4. Run Vault server in tmux window

   1. tmux new -s vault (you should be in "ethsigner-23.6.0" folder)

   2. vault server -config=config.hcl

   3. ctrl + b, then d to leave tmux

5. Initialize Vault

   1. set env var export VAULT_CAPATH="/home/brianhuang/ethsigner-23.6.0/tls/vault.crt"

      • replace full path with one for your system

   2. vault operator init

      • Success shows five "Unseal Keys" and one "Initial Root Token"

   3. Save the "Initial Root Token" somewhere temporarily

      • This token is used for authenticating a terminal session

   4. Save the "Unseal Keys" somewhere extremely safe, possibly in separate locations

      • 3 of 5 Unseal Keys can unseal the Vault and reveal the secrets inside

6. EthSigner requires you save the Initial Root Token into a file

   1. cd into "ethsigner-23.6.0" folder, cd into "bin" folder

   2. touch authFile && vim authFile

   3. i to edit, paste Initial Root Token into first line

   4. ctrl + c , :wq, then Enter to save & exit

7. Unseal the Vault to import your private key and initialize EthSigner (you will seal it back up later)

   1. vault operator unseal

   2. copy in one Unseal Key (characters will not show), then press Enter

   3. Repeat the above two steps two more times with the 2nd and 3rd Unseal Keys (you need 3/5 keys to unseal the Vault)

8. Authenticate your terminal

   1. must have VAULT_CAPATH env var in this terminal

      1. export VAULT_CAPATH="/home/brianhuang/ethsigner-23.6.0/tls/vault.crt"

   2. vault login

   3. paste in the Initial Root Token

      • Success shows: "Success! You are now authenticated."

9. Import private keys (see Static Secrets: Key/value secrets engine for more info)

   1. Enable storage path with vault secrets enable -path=secret kv

      • Success shows: "Success! Enabled the kv secrets engine at: secret/"

   2. Upgrade Key/Value Secrets Engine from v1 to v2 with vault kv enable-versioning secret/

      • Success shows: "Success! Tuned the secrets engine at: secret/"

   3. Add private key with vault kv put secret/ethsignerSigningKey value=<privateKeyWithout0x>

Run EthSigner Server

1. cd into "ethsigner-23.6.0" folder (you may be in "bin" folder right now)

2. create new tmux window called "ethsigner" with tmux new -s ethsigner

3. ./bin/ethsigner --chain-id=137 --downstream-http-port=443 hashicorp-signer --host=127.0.0.1 --port=8200 --auth-file=./bin/authFile --signing-key-path=/v1/secret/data/ethsignerSigningKey --tls-known-server-file=./tls/knownServers

   • Replace above with correct chain ID (137 = "Polygon")

4. Leave tmux window with ctrl + b, then d

5. Check EthSigner is running

   1. test1: curl -X GET http://127.0.0.1:8545/upcheck

      • Success should show "I'm up!"

   2. test2: curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}' http://127.0.0.1:8545

      • Success should show your address

6. Seal the Vault with vault operator seal

   • Success shows: "Success! Vault is sealed."

View all active ports with sudo lsof -i -P -n | grep LISTEN

Test

Send a Trading View alert or mimic one using sendAlert.js.

If you already set up Ngrok, use the Ngrok URL as the webhook URL. If not, your NodeJS App should be listening on http://localhost:8080/. If using the "localhost" URL, you must run node sendAlert.js on the same machine.

A successful test should show transaction details the the swap hash in the console.