Skip to main content

Configure client and server TLS

Besu supports TLS for client and server communication. For example, you can configure TLS for communication between Web3Signer and Besu, and Besu and Tessera.

The following instructions allow you to configure client and server authentication to secure HTTP JSON-RPC calls.

Secure Websocket 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.

The following diagram displays an example client and server TLS configuration.

Besu client and server TLS

Configure TLS communication from the command line.

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:

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.
Example
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:

note

Set --rpc-http-tls-ca-clients-enabled to true to allow access to clients with signed and trusted root CAs.

Configure server TLS​

Allow Besu to securely communicate with the server (Tessera).

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.
Example
localhost:8888 3C:B4:5A: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:AC
127.0.0.1:8888 3C:B4:5A: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:AC
note

If you are unsure whether requests use the hostname or an IP address, configure both in the file.

Start Besu​

besu --privacy-tls-enabled --privacy-tls-keystore-file=/Users/me/my_node/keystore.pfx --privacy-tls-keystore-password-file=/Users/me/my_node/keystorePassword --privacy-tls-known-enclave-file=/Users/me/my_node/knownServers

The command line: