Skip to main content

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 uses the keytool utility to generate keystores and a truststore that contain self-signed certificates.

info

keytool is available with the JDK or JRE installation, you can also use OpenSSL.

Prerequisites:

This tutorial connects to the Holesky testnet. You can run a Besu node on Holesky.

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.

    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.

  2. Create a plain text file (for example web3signer_keystore_password.txt) that stores the password used to create the keystore.

    web3signer_keystore_password.txt
    changeit

You now have the web3signer_keystore.p12 and web3signer_keystore_password.txt files that must be supplied when starting 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.

    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.

  2. Create a plain text file (for example teku_keystore_password.txt) that stores the password used to create the keystore.

    teku_keystore_password.txt
    changeit

You now have the teku_client_keystore.p12 and teku_keystore_password.txt files that must be supplied when starting 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.

    keytool -exportcert -keystore ./web3signer_keystore.p12 -alias web3signer -rfc -file web3signer.pem

  2. Import the public certificate into a truststore to be used by Teku, and type yes if asked to trust the certificate.

    keytool -importcert -storetype PKCS12 -keystore web3signer_truststore.p12 -alias web3signer -trustcacerts -storepass changeit -file ./web3signer.pem

  3. Create a plain text file (for example truststore_pass.txt) that stores the password used to create the keystore.

    truststore_pass.txt
    changeit

You now have the web3signer_truststore.p12 and truststore_pass.txt files that must be supplied when starting 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.

    keytool -list -v -keystore teku_client_keystore.p12

  2. 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).

    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​

warning

This example disables Web3Signer slashing protection, this is not recommended on Mainnet.

Start Web3Signer using the keystore and password, and known clients file created earlier.

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 and truststore created earlier, with the accompanying password files.

note

This example connects to the Holesky or Ephemery testnet, and connects to the execution client's JSON-RPC URL at http://127.0.0.1:8551.

teku --network=holesky \
--ee-endpoint=http://127.0.0.1:8551 \
--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