Add Teku and Web3Signer TLS configuration information (#227)

* Add CLI option to disable built-in slashing protection for external signers. Signed-off-by: Byron Gravenorst <[email protected]> * Add instructions to connect to mainnet. Signed-off-by: Byron Gravenorst <[email protected]> * updating submodule to latest * Add instructions to connect to mainnet. Signed-off-by: Byron Gravenorst <[email protected]> * Fix markdown issue. Signed-off-by: Byron Gravenorst <[email protected]> * Add instructions to use TLS with external signer. Signed-off-by: Byron Gravenorst <[email protected]> * Add TLS configuration information. Signed-off-by: Byron Gravenorst <[email protected]> * Fix markdown issues. Signed-off-by: Byron Gravenorst <[email protected]> * Address reviewer feedback. Signed-off-by: Byron Gravenorst <[email protected]>
Consensys · Dec 22, 2020 · 8f3525e · 8f3525e
1 parent 266cbae
commit 8f3525e
Show file tree

Hide file tree

Showing 4 changed files with 399 additions and 0 deletions.
diff --git a/docs/HowTo/Configure/Configure-TLS.md b/docs/HowTo/Configure/Configure-TLS.md
@@ -0,0 +1,83 @@
+---
+title: Configure TLS for an external signer
+---
+
+# Configure TLS
+
+You can configure TLS for communication between Teku and an external signer, for example [Web3Signer].
+
+!!! info
+
+    The [Teku and Web3Signer TLS configuration tutorial] provides instructions to create the required
+    keystores and configuration.
+
+## Prerequisites
+
+**Web3Signer prerequisites**:
+
+* [Password-protected PKCS12 keystore and password file].
+* [Known clients file].
+
+**Teku prerequisites**:
+
+* [Teku's password-protected PKCS12 or JKS keystore and password file].
+* [Web3Signer's password-protected PKCS12 or JKS truststore and password file].
+* ETH1 client (for example [Hyperledger Besu]) synced to the required network.
+
+## Start Web3Signer
+
+Start Web3Signer with the TLS configuration options and specify the keystore and known clients file.
+
+```bash
+web3signer --key-store-path=/Users/me/keyFiles/ \
+--tls-keystore-file=/Users/me/certs/web3signer_keystore.p12 \
+--tls-keystore-password-file=/Users/me/certs/web3signer_keystore_password.txt \
+--tls-known-clients-file=/Users/me/certs/knownClients.txt \
+eth2
+```
+
+!!! note
+
+    [Slashing protection] is enabled by default when using the `eth2` Web3Signer subcommand.
+    If using Web3Signer slashing protection, ensure you [configure your slashing protection database].
+
+## Start Teku
+
+Start Teku with the external signer, keystore, and truststore details:
+
+```bash
+teku --network=pyrmont \
+--eth1-endpoint=http://localhost:8545 \
+--validators-external-signer-public-keys=0xa99a...e44c,0xb89b...4a0b \
+--validators-external-signer-url=https://localhost:9000 \
+--validators-external-signer-truststore=/Users/me/certs/web3signer_truststore.p12 \
+--validators-external-signer-truststore-password-file=/Users/me/certs/truststore_pass.txt \
+--validators-external-signer-keystore=/Users/me/certs/teku_client_keystore.p12 \
+--validators-external-signer-keystore-password-file=/Users/me/certs/teku_keystore_password.txt
+```
+
+In the command:
+
+* Specify the JSON-RPC URL of the ETH1 node using
+    [`--eth1-endpoint`](../../Reference/CLI/CLI-Syntax.md#eth1-endpoint).
+* Specify the validator's public keys using
+    [`--validators-external-signer-public-keys`](../../Reference/CLI/CLI-Syntax.md#validators-external-signer-public-keys).
+* Specify the URL of the running external signer using
+    [`--validators-external-signer-url`](../../Reference/CLI/CLI-Syntax.md#validators-external-signer-url).
+* Specify the truststore and password file using
+    [`validators-external-signer-truststore`](../../Reference/CLI/CLI-Syntax.md#validators-external-signer-truststore) and
+    [`validators-external-signer-truststore-password-file`](../../Reference/CLI/CLI-Syntax.md#validators-external-signer-truststore-password-file).
+* Specify the keystore and password file using
+    [`validators-external-signer-keystore`](../../Reference/CLI/CLI-Syntax.md#validators-external-signer-keystore) and
+    [`validators-external-signer-keystore-password-file`](../../Reference/CLI/CLI-Syntax.md#validators-external-signer-keystore-password-file).
+
+<!-- links -->
+[Web3Signer]: https://docs.web3signer.consensys.net/en/latest/
+[Teku and Web3Signer TLS configuration tutorial]: ../../Tutorials/Configure-External-Signer-TLS.md
+[Password-protected PKCS12 keystore and password file]: ../../Tutorials/Configure-External-Signer-TLS.md#web3signer-keystore-and-password-file
+[Known clients file]: ../../Tutorials/Configure-External-Signer-TLS.md#3-create-the-known-clients-file
+[Teku's password-protected PKCS12 or JKS keystore and password file]: ../../Tutorials/Configure-External-Signer-TLS.md#teku-keystore-and-password-file
+[Web3Signer's password-protected PKCS12 or JKS truststore and password file]: ../../Tutorials/Configure-External-Signer-TLS.md#2-create-the-truststore-and-password-file
+[Hyperledger Besu]: https://besu.hyperledger.org/en/stable/HowTo/Get-Started/Installation-Options/Options/
+[Slashing protection]: https://docs.web3signer.consensys.net/en/latest/Concepts/Slashing-Protection/
+[configure your slashing protection database]: https://docs.web3signer.consensys.net/en/latest/HowTo/Configure-Slashing-Protection/
diff --git a/docs/Reference/CLI/CLI-Syntax.md b/docs/Reference/CLI/CLI-Syntax.md
@@ -1373,6 +1373,65 @@ When specifying file names, Teku expects that the files exist.
 
     The path separator is operating system dependent, and should be `;` in Windows rather than `:`.
 
+### validators-external-signer-keystore
+
+=== "Syntax"
+
+    ```bash
+    --validators-external-signer-keystore=<FILE>
+    ```
+
+=== "Command Line"
+
+    ```bash
+    --validators-external-signer-keystore=teku_client_keystore.p12
+    ```
+
+=== "Environment Variable"
+
+    ```bash
+    TEKU_VALIDATORS_EXTERNAL_KEYSTORE=teku_client_keystore.p12
+    ```
+
+=== "Configuration File"
+
+    ```bash
+    validators-external-signer-keystore: "teku_client_keystore.p12"
+    ```
+
+The keystore that Teku presents to the external signer for TLS authentication. Teku can use
+PKCS12 or JKS keystore types.
+
+Use the PKCS12 keystore type if connecting to Web3Signer.
+
+### validators-external-signer-keystore-password-file
+
+=== "Syntax"
+
+    ```bash
+    --validators-external-signer-keystore-password-file=<FILE>
+    ```
+
+=== "Command Line"
+
+    ```bash
+    --validators-external-signer-keystore-password-file=keystore_pass.txt
+    ```
+
+=== "Environment Variable"
+
+    ```bash
+    TEKU_VALIDATORS_EXTERNAL_KEYSTORE_PASSWORD_FILE=keystore_pass.txt
+    ```
+
+=== "Configuration File"
+
+    ```bash
+    validators-external-signer-keystore-password-file: "keystore_pass.txt"
+    ```
+
+Password file used to decrypt the keystore.
+
 ### validators-external-signer-public-keys
 
 === "Syntax"
@@ -1468,6 +1527,63 @@ using Teku to sign blocks and attestations always uses its built-in slashing pro
 
 Timeout in milliseconds for requests to the external signer. Default is 1000.
 
+### validators-external-signer-truststore
+
+=== "Syntax"
+
+    ```bash
+    --validators-external-signer-truststore=<FILE>
+    ```
+
+=== "Command Line"
+
+    ```bash
+    --validators-external-signer-truststore=websigner_truststore.p12
+    ```
+
+=== "Environment Variable"
+
+    ```bash
+    TEKU_VALIDATORS_EXTERNAL_TRUSTSTORE=websigner_truststore.p12
+    ```
+
+=== "Configuration File"
+
+    ```bash
+    validators-external-signer-truststore: "websigner_truststore.p12"
+    ```
+
+PKCS12 or JKS keystore used to trust external signer's self-signed certificate or CA certificate
+which signs the external signer's certificate.
+
+### validators-external-signer-truststore-password-file
+
+=== "Syntax"
+
+    ```bash
+    --validators-external-signer-truststore-password-file=<FILE>
+    ```
+
+=== "Command Line"
+
+    ```bash
+    --validators-external-signer-truststore-password-file=truststore_pass.txt
+    ```
+
+=== "Environment Variable"
+
+    ```bash
+    TEKU_VALIDATORS_EXTERNAL_TRUSTSTORE_PASSWORD_FILE=truststore_pass.txt
+    ```
+
+=== "Configuration File"
+
+    ```bash
+    validators-external-signer-truststore-password-file: "truststore_pass.txt"
+    ```
+
+Password file used to decrypt the keystore.
+
 ### validators-external-signer-url
 
 === "Syntax"