Configure client TLS
Besu supports TLS for client communication. For example, you can configure TLS for communication between Web3Signer and Besu.
The following instructions allow you to configure client authentication to secure HTTP JSON-RPC calls.
You can configure SSL/TLS authentication for WebSocket calls by enabling
--rpc-ws-ssl-enabled for
server authentication, and
--rpc-ws-ssl-client-auth-enabled for client authentication.
Prerequisites
- Besu's password-protected PKCS12 keystore
- File containing the keystore password
Configure client TLS
Allow clients (for example a dapp, curl, or Web3Signer) to send and receive secure HTTP JSON-RPCs.
Client prerequisites:
- Configure the client for TLS
- Client's PKCS12 keystore information
Create the known clients file
The known clients file allows clients with self-signed certificates or non-public certificates to connect to Besu.
Create a file (in this example, knownClients) that lists one or more trusted clients. Use the format<common_name> <hex-string> where:
<common_name>is the Common Name specified in the client certificate.<hex-string>is the SHA-256 fingerprint of the client certificate.
web3signer 8E:E0:85:9F:FC:2E:2F:21:31:46:0B:82:4C:A6:88:AB:30:34:9A:C6:EA:4F:04:31:ED:0F:69:A7:B5:C2:2F:A7
curl FC:18:BF:39:45:45:9A:15:46:76:A6:E7:C3:94:64:B8:34:84:A3:8E:B8:EA:67:DC:61:C0:29:E6:38:B8:B7:99
You can use openssl or keytool to display the SHA256 fingerprint.
keytool -list -v -keystore <keystore> -storetype PKCS12 -storepass <MY_PASSWORD>`.
Start Besu
besu --rpc-http-enabled --rpc-http-tls-enabled --rpc-http-tls-client-auth-enabled --rpc-http-tls-keystore-file=/Users/me/my_node/keystore.pfx --rpc-http-tls-keystore-password-file=/Users/me/my_node/keystorePassword --rpc-http-tls-known-clients-file=/Users/me/my_node/knownClients --rpc-http-tls-cipher-suite=TLS_AES_256_GCM_SHA384 --rpc-http-tls-protocol=TLSv1.3,TLSv1.2
The command line:
- Enables the HTTP JSON-RPC service using the
--rpc-http-enabledoption. - Enables TLS for the HTTP JSON-RPC service using the
--rpc-http-tls-enabledoption. - Enables TLS client authentication using the
--rpc-http-tls-client-auth-enabledoption. - Specifies the keystore using the
--rpc-http-tls-keystore-fileoption. - Specifies the file that contains the password to decrypt the keystore using the
--rpc-http-tls-keystore-password-fileoption. - Specifies the clients allowed to connect to Besu using the
--rpc-http-tls-known-clients-fileoption. - specifies the Java cipher suites using the
--rpc-http-tls-cipher-suiteoption. - specifies the TLS protocol version using the
--rpc-http-tls-protocoloption.
Enabling --rpc-http-tls-ca-clients-enabled
trusts any client certificate that chains to a certificate authority in the JVM
truststore, including public CAs.
Following the
October 2026 eMudhra CA compromise,
prefer --rpc-http-tls-known-clients-file,
or a truststore that contains only your own CA, to authenticate clients.