Hyperledger Besu client TLS for JSON-RPC and WebSocket

Why Hyperledger Besu client TLS needs a deliberate design

Applications, signing services and partner systems that call a permissioned Besu node over JSON-RPC and WebSocket are often the most exposed part of the network. A node that validates blocks can be fully protected by its peer settings and still be reachable by any client that can open a socket to its API port. Besu includes built-in TLS options for HTTP JSON-RPC and for WebSocket, so the design question is not whether to use them but how to combine encryption and client authentication so that only known callers reach the node and the traffic between them is protected. The settings involved, such as --rpc-http-tls-enabled and --rpc-ws-ssl-enabled, rely on a password-protected PKCS12 keystore and on checks of client certificates, and each choice changes who can connect and how those clients are identified.

The Besu documentation for JSON-RPC authentication states that Besu does not terminate HTTPS natively in that context, so the boundary between the node and any API gateway, load balancer or ingress must be settled before anything is configured. Decide whether TLS ends on the node, on a gateway in front of it, or on both, and document which hop carries the client certificate. If a gateway terminates TLS and forwards plain traffic, the node's client checks no longer see the original caller, and the known clients list becomes a list of gateway identities. Confirm this behavior against the current Besu client TLS documentation and against the gateway product you plan to use.

Plan the work as a set of decisions with owners: who issues and rotates node and client certificates, which certificate authority is trusted, how fingerprints are recorded for each client, which cipher suites and protocol versions your security policy allows, and how the keystore password is stored. Each of these needs a test that proves a rejected client is rejected and an allowed client works, both over HTTP and WebSocket. Treat these checks as evidence for your security team and for any assessment of your network, and expect the certificate lifecycle to recur for as long as the node runs.

Which client authentication model fits each caller

When a small, known group of applications calls the node, the known clients model is usually the simplest fit. Each client presents a certificate, and the node checks its common name and SHA-256 fingerprint against the known clients file. Nothing outside that file is trusted, even if the certificate was issued by a valid authority, which keeps the trust boundary narrow and easy to explain to an auditor.

Small, stable inventory: Every caller is listed by name, so the access list reads as a register of approved applications.
Fingerprint pinning: A certificate reissue changes the fingerprint, so each renewal needs a matching update to the file.
Clear revocation: Removing an entry cuts off that caller on the next configuration load, without touching other clients.
Operational cost: Each new application or certificate rotation adds a manual change that must be reviewed and deployed.
Fit for internal services: Backend services, signing components and monitoring agents often suit this model well.

Before relying on it, confirm in your own environment how the node reloads the known clients file after a change and how you will rotate certificates without a gap in access.

Which TLS options to set and when each fits

This table maps each Besu TLS flag for JSON-RPC and WebSocket to its purpose and the access pattern it suits. Read it top down: the HTTP flags build the base, then client authentication decides who may connect, and the WebSocket flags apply the same controls to subscriptions.

Flag	Purpose	When it fits
--rpc-http-tls-enabled	Serves the HTTP JSON-RPC endpoint over TLS using a password-protected PKCS12 keystore.	Any deployment where application traffic to the node crosses a network segment you do not fully control. Set it first, as every other HTTP TLS option depends on it.
--rpc-http-tls-client-auth-enabled	Requires each connecting client to present a certificate, checked against the known clients file by common name and SHA-256 fingerprint.	A fixed set of known applications or services, such as one backend or a small number of signing services, where you can register each certificate in advance.
--rpc-http-tls-ca-clients-enabled	Accepts client certificates signed by trusted root CAs instead of requiring each certificate to be listed by fingerprint.	Larger or changing client populations issued by an internal CA that already runs certificate lifecycle processes. Confirm how revocation is handled, since the known clients file no longer gates access.
--rpc-http-tls-cipher-suite	Restricts which cipher suites the node will negotiate.	When your cryptographic standard or assessor expects an explicit approved cipher list. Confirm the suite names against the Besu and Java versions you run.
--rpc-http-tls-protocol	Sets which TLS protocol versions the node accepts.	When policy requires disabling older protocol versions. Test client compatibility first, since a narrow setting can block applications that have not been upgraded.
--rpc-ws-ssl-enabled	Serves the WebSocket JSON-RPC endpoint over TLS.	Applications that subscribe to events or receive pending data over WebSocket. Enable it whenever the WebSocket endpoint is reachable beyond the host itself.
--rpc-ws-ssl-client-auth-enabled	Requires client certificates on WebSocket connections.	When WebSocket consumers are authenticated the same way as HTTP clients. Keep the WebSocket and HTTP client lists aligned so no channel becomes the weaker path.

How to configure mutual TLS on a Besu node

This sequence turns plain HTTP JSON-RPC on a Besu node into a TLS endpoint that only accepts clients presenting a certificate the node has been told to trust. Each step ends with a check so the team knows the previous layer works before the next one is switched on.

Create a password-protected PKCS12 keystore
The node's platform or security team generates the server certificate and private key, then packages them into a password-protected PKCS12 keystore on the node host. Store the keystore password in your secrets manager, not in the node's start script or shell history, and restrict read access to the Besu service account. Done means the keystore opens with its password and lists the server certificate with the expected common name or subject alternative names for the hostnames applications will use. Confirm the exact keystore and password options against the Besu TLS documentation for your Besu release before you rely on them.
Enable HTTP JSON-RPC TLS
Turn on TLS for the HTTP JSON-RPC port with the --rpc-http-tls-enabled option and point the node at the keystore and its password. Keep client authentication off at this stage so the change is isolated and easy to diagnose. Restart the node in a test environment and confirm that an HTTPS request with the server's CA certificate returns a JSON-RPC response, such as a call to eth_blockNumber. Plain HTTP requests to the same port should fail. Note that Besu does not terminate HTTPS natively in every deployment pattern, so check your ingress or proxy design against the documentation before exposing the port.
Enable client certificate authentication
Set --rpc-http-tls-client-auth-enabled so the node requests a client certificate during the TLS handshake and rejects connections that do not present one. Before moving on, run a test with no client certificate and confirm the connection is refused at the handshake, not at the JSON-RPC layer. Then run a test with a certificate that is not in the known clients file and confirm it is also refused. Record both results in the change ticket. This pair of negative tests is the evidence that the control is active, and it should be repeated after any configuration change or Besu upgrade.
Populate the known clients file
Build the known clients file with one entry per client, listing the certificate common name and the SHA-256 fingerprint of that client's certificate. Compute the fingerprint from the exact certificate file each client will present, and have the owning application team confirm the common name matches their certificate. Point the node at the file with the option named in the Besu TLS documentation for your release. Done means a client whose certificate and fingerprint match the file connects and receives a JSON-RPC response, and a client with the right common name but a different fingerprint is refused. Rotate entries through a change process whenever a client certificate is reissued.
Enable CA-signed client certificates if used
If your clients are issued certificates from an internal certificate authority, enable --rpc-http-tls-ca-clients-enabled so the node accepts any client certificate chaining to a trusted root CA, instead of listing each fingerprint. Decide before enabling it whether a CA-wide trust is acceptable, because any certificate the CA issues will then be accepted until it expires or is revoked. Your PKI team should confirm revocation handling, since the node's trust decision depends on the CA chain. Test a certificate issued by the trusted CA, one from an untrusted CA, and one from the trusted CA that has been revoked, and record the outcome of each.
Set cipher suites and protocol versions
Set the permitted protocol versions with --rpc-http-tls-protocol and the allowed cipher suites with --rpc-http-tls-cipher-suite, aligning both with your organization's cryptographic policy and the approved list from your security team. Use a TLS scanning tool from a host on the application network to confirm the node negotiates only the approved protocol versions and suites, and that weaker options are refused. Repeat this check whenever the policy or Besu release changes, because default values can differ between versions. Retain the scan output as evidence for your security assessment.
Add WebSocket TLS with client authentication
Configure the WebSocket endpoint separately by enabling --rpc-ws-ssl-enabled and, where clients must authenticate, --rpc-ws-ssl-client-auth-enabled. The WebSocket listener does not inherit the HTTP settings, so repeat the keystore, known clients and cipher checks for it. Confirm that a secure WebSocket connection with an approved certificate subscribes and receives events, and that a connection without a certificate is refused. Applications that also use Web3Signer should be tested against the same TLS settings in a separate step, using the certificates and trust chain their signing service expects.
Verify the full configuration and record evidence
Run the complete test set against the final configuration on a non-production node: the HTTPS success path, the no-certificate refusal, the unknown-certificate refusal, the CA-signed and revoked cases if used, the protocol and cipher scan, and the WebSocket tests. Store the configuration file, test commands and results in version control alongside the node's other configuration, and link them to the change record. Ask the security team to review the evidence before the configuration reaches production, and schedule the same test set to run after each Besu upgrade and each certificate rotation.

Connecting Web3Signer and signing services over TLS

A Besu node that delegates signing to an external service needs the signer and the node to trust each other's certificates before any signing request can succeed. The cards below cover the trust model, the certificate work on both sides, and the checks to run before a signer goes near production. Exact Web3Signer settings change between versions, so confirm each one against the release you deploy.

Two-way trust between node and signer

A signing connection is mutual: the signer must trust the certificate the Besu node presents, and the node must trust the certificate the signer presents. Most failed connections trace back to one side trusting a certificate the other side never issued or never sends. Map both directions on paper before configuring either end, including which root or intermediate CA signs each certificate. Treat this trust map as a design artifact that your change process reviews.

Client certificate the node presents

When the node calls the signer, it must present a valid client certificate, and the signer must accept it. Confirm which keystore format and key usages your signer expects, since a Besu PKCS12 keystore is built for inbound RPC and may not match the signer's own requirements. Keep the node's client identity separate from its RPC server identity so one rotation does not break the other. Record the subject name and fingerprint of each client certificate in your inventory.

Signer certificate and CA chain

The signer presents its own server certificate to the node, and the node must be able to validate it. Ensure the full chain, including intermediates, is available to the trust store the node uses. Check subject alternative names against the hostname or address the node uses, because a name mismatch can look like a generic handshake failure. Confirm trust store file format and location with the signer release you run.

Protocol and cipher alignment

The node and the signer must agree on a TLS protocol version and a cipher suite. If you restrict either side with the node's protocol or cipher settings, verify the signer supports the same combination before the change window. A mismatch is often reported as a handshake failure, so test the signer connection after each change to the node's TLS settings, not only at first deployment.

Certificate rotation without outages

Signer and node certificates expire on their own schedules, and a rotation that touches only one side will stop signing. Plan a rotation order that adds the new trust material on both ends before the old credential is removed. Keep a dated inventory of every certificate, its issuer, and its expiry, and set alerts well before expiry. Rehearse the rotation on a non-production network that uses the same signer release.

Failure behavior and key custody

Decide what the node does when the signer is unreachable or rejects a certificate, because signing that stops silently can halt block production or transactions. Confirm with the signer documentation whether the signer holds the keys or only proxies to hardware storage, and where its own keys are protected. Ask for a test that deliberately breaks trust on each side, and record the error seen in logs so operators can recognize it in an incident.

What teams ask before configuring Besu client TLS

What drives the cost of configuring client TLS on a Besu node?

The main cost drivers are the number of clients that connect, the certificate authority model, how often certificates rotate, and whether a gateway sits in front of the nodes. Each client needs an identity, either a fingerprint entry in the known clients file or a certificate chained to a trusted root CA, so more clients means more onboarding, testing and records to maintain. Setup is mostly one-time work, while rotation, client onboarding and monitoring of expiry dates recur. No price or duration figures are supplied for this topic, so a quote follows the written scope that lists the nodes, clients, CA model and environments in play.

How long does Besu client TLS setup take?

Duration depends on how many nodes and clients need access, whether an existing internal CA will issue client certificates, and how many environments must be tested before production. A single node with a few known clients is a smaller job than a fleet with CA-signed clients and WebSocket endpoints. No timeline figures are supplied for this topic, so ask for a schedule in the written scope, with the dependencies on certificate issuance and test access stated separately.

What does our team need to provide for the work?

Plan to provide certificate issuance or approval from your PKI team, access to the hosts running Besu, and test environments that mirror production settings. Your team should also confirm which applications and gateways will connect, their certificate common names or CA chains, and the approved cipher suites and protocol versions. Without these inputs, the work stalls at the point where client identities are needed, so agree the responsibilities in the written scope before work starts.

Can our own engineers configure Besu client TLS without a partner?

Yes, if your team has Linux administration skills, access to a certificate authority, and time to test changes against each client. The Besu documentation describes the flags and keystore format, so the core steps are documented. A partner adds value when you need a verified build sequence, evidence for an assessment, or help coordinating many clients across environments. Decide based on your internal capacity, the number of clients, and how much testing you want to carry.

Should we use a known clients file or CA-signed client certificates?

A known clients file works well when you have a small, stable set of clients, because each entry lists a certificate common name and SHA-256 fingerprint that you manage directly. CA-signed clients, enabled with the CA clients option, scale better when many applications need access and your PKI already issues certificates. The trade-off is operational: fingerprint lists need updating on every certificate replacement, while CA trust depends on controlling which roots are trusted and how revocation is handled. Confirm the revocation approach with your security team before choosing.

How does certificate rotation affect ongoing effort?

Rotation is the recurring part of the work. With a known clients file, every rotation means generating a new certificate, recording its fingerprint, updating the file and restarting or reloading the node as your setup requires. With CA-signed clients, rotation is mostly handled by the CA, but you still need to confirm that the node trusts the right roots and that expiry dates are tracked. Ask for a rotation runbook as part of the deliverables, with the owner and frequency of each step.

Do we need a gateway in front of the Besu nodes for TLS?

Not always, but the choice changes the work. The Besu documentation states that Besu does not terminate HTTPS natively in the JSON-RPC authentication model, and client TLS settings apply to the node's own endpoints. A gateway can terminate TLS, apply authentication and route requests, which shifts certificate management to the gateway. Decide whether the gateway or the node holds the client identities, and confirm that the chain of trust from applications to the node is what your risk assessment expects.

Limits to confirm in your environment before go-live

The Besu TLS settings are simple to switch on, but their exact behavior depends on the client version you run, the TLS libraries it links against and the access path your applications use. The cards below list what to test in your own environment rather than assume, so the evidence you collect matches the trust model you intend to document.

Flag behavior in your Besu version

Each of the --rpc-http-tls-* and --rpc-ws-ssl-* flags should be tested against the exact Besu release you deploy, not against documentation written for another version. Confirm which flags are required together, what happens when a flag is set without its companion, and whether the node refuses to start or silently falls back to plaintext. Keep the test output with your change record. Besu release notes list version changes, so read the notes for every release between your current build and your target before you upgrade.

Protocol and cipher suite names

The accepted values for --rpc-http-tls-protocol and --rpc-http-tls-cipher-suite depend on the Java runtime and its TLS provider. Do not copy a cipher list from a blog post. Ask your security team which protocol versions and suites your policy allows, then confirm each name is accepted by the Besu build and JDK you run. Test with a client that negotiates the weakest allowed suite, and a client that is refused, so both outcomes are proven.

Certificate lifecycle and revocation

The known clients file pins each client by common name and SHA-256 fingerprint, so a rotated client certificate stops working until the file is updated. Decide who owns renewal, how the new fingerprint is distributed and how a compromised certificate is removed. Confirm with your Besu version whether certificate revocation checks are performed for CA-signed clients. If they are not, document the compensating control, such as short certificate lifetimes or removing the client from the known clients file.

Interaction with JSON-RPC authentication

Besu can also require a username and password credentials file or JWTs validated against a public key. TLS client authentication and these methods are separate checks, so confirm whether your deployment needs both and that a request failing one check is rejected as you expect. Test a JWT from an expired or unexpected issuer, and a valid client certificate paired with a missing token. Record which algorithms your identity provider signs with, since Besu validates only the RS and ES algorithms listed in its documentation.

Reverse proxy and gateway trust model

Besu does not terminate HTTPS natively in the way many operators assume, so the TLS settings above apply to the connection Besu accepts. If a reverse proxy, API gateway or load balancer sits in front, confirm whether it terminates TLS, whether it forwards the client certificate and whether Besu sees the proxy as the only client. A proxy that re-encrypts traffic changes who is authenticated. Write down the hop-by-hop path and test it end to end from the application side.

Signer and WebSocket connections

WebSocket TLS uses its own enable and client authentication flags, so a secured HTTP endpoint does not secure the WebSocket endpoint. Web3Signer connections also need their own certificate checks. Confirm each connection path separately with a test client, including reconnect behavior after a certificate change. Verify the signer's certificate chain is trusted by the node and that a rejected signer connection fails closed.

Keeping client TLS working across Besu upgrades

Treat every Besu upgrade as a change that can break client TLS, even when the TLS settings themselves do not change. Besu ships calendar releases roughly monthly, and the Besu 26.10.0 release notes state that the Bonsai database auto-upgrades on first start and that older Besu versions cannot open an upgraded database. That means a rollback after a failed upgrade is only possible if you took a backup of the data directory before the upgrade started. Before you schedule a production upgrade, restore a recent backup onto a separate host, start the target Besu version with the same --rpc-http-tls-enabled and --rpc-ws-ssl-enabled settings, and confirm that a client holding a valid certificate can still connect over both HTTPS and WebSocket.

Certificate reissuance is the more frequent source of breakage. Every client listed in the known clients file is matched by its certificate common name and SHA-256 fingerprint, so a reissued certificate with a new key will be rejected until the entry is updated. Plan the rotation as one change: issue the new certificate, update the known clients file with the new fingerprint, roll the change to the nodes, then retire the old certificate. Confirm with your certificate authority team how long the old and new certificates overlap, because a gap in that window is the most common cause of an application outage that looks like a node failure. If clients rely on --rpc-http-tls-ca-clients-enabled instead, check that the issuing CA and its chain are still trusted after any CA change.

After each TLS change or upgrade, use the Besu metrics endpoint enabled with --metrics-enabled to confirm node health, watching peer count and block height so you can tell a TLS misconfiguration from a node that has fallen behind. Scrape the endpoint from your existing Prometheus setup and alert on the absence of metrics as well as on their values, because a node that refuses client connections may still be syncing normally. Record the cipher suite and protocol settings, the keystore version and the known clients file revision in your change record so the next upgrade starts from a known configuration. Confirm with your Besu release plan which versions your organization will run and the rollback window you will accept before the first upgrade.

How DeployOpen scopes and delivers Besu client TLS

Client TLS touches the node, the applications that call it, and the teams who rotate certificates later, so the work is scoped in writing before any configuration changes. The cards below follow the engagement from agreed scope through configuration in your environment, verification and operator handover, with optional retainers after go-live.

Fixed scope agreed in writing

Before work starts, the engagement records which RPC and WebSocket endpoints need TLS, which client types will connect, whether CA-signed certificates or a known clients file is the authentication model, and which protocol and cipher settings your security policy requires. Deliverables and timelines are agreed in writing, so the quote follows from a defined list of nodes and clients rather than an open-ended estimate. Ask for the list of endpoints and clients to be confirmed before pricing.

Configuration in your infrastructure

The TLS settings are applied to Besu nodes in your cloud accounts, data centers or closed networks, with keystores and certificate material kept where your key custody rules place them. Work covers the PKCS12 keystore with its password, the known clients file, and the enablement flags for HTTP JSON-RPC and WebSocket TLS. Confirm who holds the keystore password and where it is stored before configuration begins.

Verification of TLS and client authentication

Verification tests that connections fail without a valid client certificate, that accepted clients reach the expected methods, and that unsupported protocol versions and cipher suites are refused. Tests run against each node and each client path, including WebSocket subscriptions and Web3Signer connections. Ask for the test cases and the results to be delivered as part of the engagement record.

Operator documentation and handover

Operators receive documentation covering the configuration as built, how to add a new client fingerprint or CA-signed client, how to rotate a keystore, and how to recover when a certificate expires. Handover includes a walkthrough with the team that will run the nodes. Documentation supports your own change control and evidence files, but it does not replace an independent audit or certification.

Optional retainers after go-live

After go-live, many teams keep DeployOpen on a retainer for ongoing support, certificate rotation, Besu version upgrades and repeat verification when clients change. Retainer scope, response expectations and frequency are agreed in writing, like the original engagement. Ask what is included in the retainer and how upgrades that change TLS defaults are tested before rollout.

Hyperledger Besu client TLS for JSON-RPC and WebSocket APIs