Skip to content
You are reading Hyperledger Besu development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.
Last update: September 24, 2020

Configure TLS

Hyperledger Besu supports TLS for client and server communication. For example, you can configure TLS for communication between EthSigner and Besu, and Besu and Orion.

Configure TLS communication from the command line.


  • Besu’s password-protected PKCS #12 keystore.
  • File containing the keystore password

Configure Client TLS

Allow clients (for example a dApp, curl, or EthSigner) 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.


ethsigner 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

The command line:


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 (Orion).

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 <hostame>:<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: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 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


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:

Questions or feedback? You can discuss issues and obtain free support on Hyperledger Besu chat channel.
For Hyperledger Besu community support, contact the mailing list