Updated 2020-03-01

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.

Prerequisites:

  • 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.

Example

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.

Example

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:

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

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: