For AI agents: a documentation index is available at /llms.txt. Markdown versions of pages are available by appending .md to any documentation URL.
Skip to main content
Version: development

Configure TLS

Configure TLS communication from the command line to allow clients (for example Teku, a dapp, or curl) and Web3Signer to communicate securely.

Web3Signer provides multiple options to configure client TLS access:

This example uses a known clients file to limit access to specified clients.

info

The Teku tutorial provides step-by-step instructions to configure the Teku client and Web3Signer for TLS communication, including creating the required keystores and truststore.

Prerequisites​

Web3Signer prerequisites:

  • Web3Signer's password-protected PKCS #12 keystore.
  • File containing the keystore password.

Client prerequisites:

  • The client must be configured for TLS.
  • Client's PKCS #12 keystore information.

Create the known clients file​

Create a file (in this example, knownClients.txt) that lists one or more clients that are trusted to connect to Web3Signer. The file can contain clients that use trusted CA or self-signed certificates.

The file contents use the format <common_name> <hex-string> where:

  • <common_name> is the Common Name used for the client's keystore
  • <hex-string> is the SHA-256 fingerprint of the client's keystore.
curl_client DF:65:B8:02:08:5E:91:82:0F:91:F5:1C:96:56:92:C4:1A:F6:C6:27:FD:6C:FC:31:F2:BB:90:17:22:59:5B:50

You can use OpenSSL or keytool to display the client's Common Name and fingerprint. For example:

keytool -list -v -keystore <keystore> -storetype PKCS12 -storepass <password>

Start Web3Signer​

web3signer --key-store-path=/Users/me/keyFiles/ \
--tls-keystore-file=/Users/me/certs/web3signerKeystore.p12 \
--tls-keystore-password-file=/Users/me/certs/password.txt \
--tls-known-clients-file=/Users/me/certs/knownClients.txt

The command line:

note

Use the --tls-allow-any-client option to allow any client to connect.

You can't use --tls-allow-any-client with --tls-known-clients-file or --tls-allow-ca-clients.

CA compromise risk

--tls-allow-ca-clients trusts any client certificate that chains to a certificate authority in the Java trust store. See the warning on that option.

Server TLS connection​

Allow Web3Signer to send and receive secure HTTP JSON-RPCs from the server (for example Besu).

note

This can only be used when Web3Signer is eth1 mode.

Server prerequisites:

Create the known servers file​

Create a file (in this example, knownServers) that lists one or more trusted servers. The file contents use the format <hostname>:<port> <hex-string> where:

  • <hostname> is the server hostname
  • <port> is the port used for communication
  • <hex-string> is the SHA-256 fingerprint of the server's certificate.
localhost:8590 6C:B2:3E:F9:88:43:5E:62:69:9F:A9:9D:41:14:03:BA:83:24:AC:04:CE:BD:92:49:1B:8D:B2:A4:86:39:4C:BB
127.0.0.1:8590 6C:B2:3E:F9:88:43:5E:62:69:9F:A9:9D:41:14:03:BA:83:24:AC:04:CE:BD:92:49:1B:8D:B2:A4:86:39:4C:BB
note

Specify both hostname and IP address in the file if unsure which is used in requests.

Start Web3Signer​

web3signer eth1 --downstream-http-tls-enabled \
--downstream-http-tls-keystore-file=/Users/me/my_node/keystore.pfx \
--downstream-http-tls-keystore-password-file=/Users/me/my_node/keyPassword \
--downstream-http-tls-known-servers-file=/Users/me/my_node/knownServers \
--downstream-http-tls-ca-auth-enabled=false

The command line:

note

--downstream-http-tls-ca-auth-enabled is true by default. While it is true, Web3Signer accepts a server certificate signed by a certificate authority in the Java trust store, even when the known servers file is set. Set it to false to accept only the fingerprints in that file. See the October 2026 eMudhra CA compromise.