diff --git a/docs/HowTo/Configure/Configure-TLS.md b/docs/HowTo/Configure/Configure-TLS.md new file mode 100644 index 000000000..a084e81db --- /dev/null +++ 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). + + +[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 index 8f7a0a8a4..07bbd935b 100644 --- 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= + ``` + +=== "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= + ``` + +=== "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= + ``` + +=== "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= + ``` + +=== "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" diff --git a/docs/Tutorials/Configure-External-Signer-TLS.md b/docs/Tutorials/Configure-External-Signer-TLS.md new file mode 100644 index 000000000..0a6fb32f3 --- /dev/null +++ b/docs/Tutorials/Configure-External-Signer-TLS.md @@ -0,0 +1,197 @@ +--- +title: Configure TLS communication with an external signer +--- + +# Configure TLS communication + +Configure TLS communication with an external signer such as [Web3Signer] which accepts +connections from clients that use trusted CA certificates or self-signed certificates. + +This tutorial configures TLS between Teku and Web3Signer, and use the +[`keytool`](https://docs.oracle.com/en/java/javase/12/tools/keytool.html) utility to generate +keystores and the truststore that contain self-signed certificates. + +!!! info + + `keytool` is available with the JDK or JRE installation, you can also use OpenSSL. + +**Prerequisites**: + +- [Web3Signer installed](https://docs.web3signer.consensys.net/en/latest/HowTo/Get-Started/Install-Binaries/). +- [Web3Signer signing key files](https://docs.web3signer.consensys.net/en/latest/HowTo/Use-Signing-Keys/) for + validators on the Pyrmont testnet. +- [Teku Installed](../HowTo/Get-Started/Installation-Options/Install-Binaries.md). +- [Java `keytool`](https://docs.oracle.com/en/java/javase/12/tools/keytool.html). +- A running Ethereum 1.0 node such as [Hyperledger Besu], or cloud-based service such as [Infura] + synced to the Goerli testnet. + +This tutorial connects to the Pyrmont testnet ETH2 testnet, and uses [Infura] to access the +Goerli ETH1 testnet. You can sign up for a free [Infura] account, or you can start your own +[ETH1 Goerli node]. + +## 1. Create keystores + +A keystore contains the certificate and private key used to authenticate yourself during TLS +mutual authentication. + +Teku can use either the PKCS12 or JKS keystore type, whereas Web3Signer only uses a PKCS12 keystore. + +For each keystore you must create a plain text file containing the password to decrypt the keystore. + +### Web3Signer keystore and password file + +1. Generate the Web3Signer keystore. + + ```bash + keytool -genkeypair -keystore web3signer_keystore.p12 -storetype PKCS12 -storepass changeit -alias web3signer -keyalg RSA -keysize 2048 -validity 109500 -dname "CN=localhost, OU=PegaSys, O=ConsenSys, L=Brisbane, ST=QLD, C=AU" -ext san=dns:localhost,ip:127.0.0.1 + ``` + + !!! info + + Common name (`CN`) is generally the fully qualified name of Web3Server, you can use + `-ext san` to add additional hostnames or IP addresses. This allows the same certificate to + be used for more than one hostname or IP address if Web3Signer is running on a different + machine to Teku with multiple hostnames. + +1. Create a plain text file (for example `web3signer_keystore_password.txt`) that stores the + password used to create the keystore. + + !!! example "web3signer_keystore_password.txt" + + ```bash + changeit + ``` + +You now have the `web3signer_keystore.p12` and `web3signer_keystore_password.txt` files that must be +supplied when [starting Web3Signer](#4-start-web3signer). + +### Teku keystore and password file + +Teku presents the keystore to Web3Signer for TLS mutual authentication. We recommend using PKCS12. + +1. Generate the Teku keystore. + + ```bash + keytool -genkeypair -keystore teku_client_keystore.p12 -storetype PKCS12 -storepass changeit -alias teku_client -keyalg RSA -keysize 2048 -validity 109500 -dname "CN=teku, OU=PegaSys, O=ConsenSys, L=Brisbane, ST=QLD, C=AU" + ``` + + !!! info + + For Teku as a client, `CN` doesn't need to have a hostname, however it must be a lowercase value, + such as `CN=teku`. + +1. Create a plain text file (for example `teku_keystore_password.txt`) that stores the + password used to create the keystore. + + !!! example "teku_keystore_password.txt" + + ```bash + changeit + ``` + +You now have the `teku_client_keystore.p12` and `teku_keystore_password.txt` files that must be +supplied when [starting Teku](#5-start-teku). + +## 2. Create the truststore and password file + +The truststore contains certificates that you are willing to trust. Create the truststore to trust +the Web3Signer certificate during TLS mutual authentication. + +To create the truststore: + +1. Export the Web3Signer public certificate from the Web3Signer keystore to `PEM` format. + + ```bash + keytool -exportcert -keystore ./web3signer_keystore.p12 -alias web3signer -rfc -file web3signer.pem + ``` + +1. Import the public certificate into a truststore to be used by Teku, and type `yes` if asked + to trust the certificate. + + ```bash + keytool -importcert -storetype PKCS12 -keystore web3signer_truststore.p12 -alias web3signer -trustcacerts -storepass changeit -file ./web3signer.pem + ``` + +1. Create a plain text file (for example `truststore_pass.txt`) that stores the + password used to create the keystore. + + !!! example "truststore_pass.txt" + + ```bash + changeit + ``` + +You now have the `web3signer_truststore.p12` and `truststore_pass.txt` files that must be +supplied when [starting Teku](#5-start-teku). + +## 3. Create the known clients file + +Web3Signer uses a known clients file to trust client certificates. + +1. Retrieve the `CN` and `SHA256` details from the Teku keystore. + + ```bash + keytool -list -v -keystore teku_client_keystore.p12 + ``` + +1. Create a plain text file (in this case `knownClients.txt`) and add the `CN` and `SHA256` details + in one line (separated by a single space). + + ```bash + teku 67:89:C8:95:70:E0:38:10:2F:AB:7E:A3:75:4A:8C:29:C1:64:52:37:E5:E9:CD:EF:CD:27:C2:88:BF:84:3A:A1 + ``` + +!!! info + + You can add multiple known clients to the file by adding the `CN` and `SHA256` details on a new + line. + +You now have the `knownClients.txt` file that must be supplied when +[starting Web3Signer](#4-start-web3signer). + +## 4. Start Web3Signer + +!!! danger + + This example disables [Web3Signer slashing protection], this is not recommended on + Mainnet. + +Start Web3Signer using the [keystore and password](#web3signer-keystore-and-password-file), and +[known clients file](#3-create-the-known-clients-file) created earlier. + +```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 --slashing-protection-enabled=false +``` + +## 5. Start Teku + +Start Teku and specify the [keystore](#teku-keystore-and-password-file) and +[truststore](#2-create-the-truststore-and-password-file) created earlier, with the accompanying +password files. + +!!! important + + This example connects to an [Infura] ETH1 endpoint, if running your own client, like + [Hyperledger Besu], then replace [`--eth1-endpoint`](../Reference/CLI/CLI-Syntax.md#eth1-endpoint) + with the location of the JSON-RPC URL of the ETH1 node. + +```bash +teku --network=pyrmont \ +--eth1-endpoint=https://goerli.infura.iov3/d0f36ceb0c324eef9984422efbc51f21 \ +--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 +``` + +[Web3Signer]: https://docs.web3signer.consensys.net/en/latest/ +[Hyperledger Besu]: https://besu.hyperledger.org/en/stable/HowTo/Get-Started/Installation-Options/Options/ +[Infura]: https://infura.io/ +[ETH1 Goerli node]: https://besu.hyperledger.org/en/stable/HowTo/Get-Started/Starting-node/#run-a-node-on-goerli-testnet +[Web3Signer slashing protection]: https://docs.web3signer.consensys.net/en/latest/Concepts/Slashing-Protection/ diff --git a/mkdocs.yml b/mkdocs.yml index fc52a9df4..5db37c070 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,6 +69,7 @@ nav: - Configure logging: HowTo/Monitor/Logging.md - Configure: - Specify options in a configuration file: HowTo/Configure/Use-Configuration-File.md + - Configure TLS: HowTo/Configure/Configure-TLS.md - Prevent slashing offences: HowTo/Prevent-Slashing.md - Find and connect to peers: - Improve P2P connectivity: HowTo/Find-and-Connect/Improve-Connectivity.md @@ -78,6 +79,8 @@ nav: - Concepts: - Slashing protection: Concepts/Slashing-Protection.md - Weak subjectivity: Concepts/Weak-Subjectivity.md + - Tutorials: + - External signer TLS: Tutorials/Configure-External-Signer-TLS.md - Reference: - Teku command line: - Options: Reference/CLI/CLI-Syntax.md