JNBridge TCP Configuration: SSL, Whitelisting & Startup Guide

If you started with Shared Memory and now need your .NET and Java components on separate hosts, TCP is the next step. The move is straightforward, but there are a few settings that matter a lot in production: startup order, SSL, and access controls.

In this walkthrough, I’ll show exactly how to switch a JNBridgePro project to TCP mode and lock it down with class/IP whitelisting and TLS.

When to Use TCP Instead of Shared Memory

Use Shared Memory when both runtimes are co-located and you need the lowest possible latency.

Use TCP when:

• .NET and Java run on different machines
• You need network-level separation between services
• You want transport-level security controls (TLS + host restrictions)

In TCP mode, the Java side runs as a server process, and the .NET side connects to it over a socket.

If you want the shared-memory architecture first, see the companion guide: Shared Memory Bridge Anatomy.

1) Update .NET App.config to TCP (jtcp)

Switch your bridge transport from sharedmem to jtcp, then set host and port:

<jnbridge>
  <dotNetToJavaConfig
    scheme="jtcp"
    host="localhost"
    port="8085"
    useSSL="true"
    clientCertificateLocation=".\testclient.p12"
    clientCertificatePassword="pw"
    sslAlternateServerNames="myServer" />
</jnbridge>

Key attributes

• scheme="jtcp" → enables TCP transport
• host → machine running the Java side
• port → must match Java-side properties
• useSSL + certificate fields → optional but strongly recommended for production

If SSL is disabled, remove SSL attributes (or set useSSL="false").

2) Update Java-side javaSide.properties

Set server mode to TCP and configure security knobs:

javaSide.serverType=tcp
javaSide.workers=5
javaSide.timeout=10000
javaSide.port=8085

javaSide.useClassWhiteList=true
javaSide.classWhiteListFile=./classWhiteList.txt

dotNetSide.ipWhitelist=127.0.0.1

javaSide.keyStore=./keystore.jks
javaSide.keyStorePassword=changeit
javaSide.trustStore=./cacerts.jks
javaSide.trustStorePassword=changeit

What each block does

• Server/runtime: serverType, workers, timeout, port
• Class restrictions: only listed Java classes are invocable from .NET
• Client restrictions: only approved client IPs can connect
• TLS materials: keystore + truststore for encrypted, authenticated sessions

3) Add Class Whitelisting (recommended)

Create classWhiteList.txt beside your properties file:

bridgeDemo.JavaToCall

Then ensure these are enabled:

javaSide.useClassWhiteList=true
javaSide.classWhiteListFile=./classWhiteList.txt

This prevents accidental exposure of internal classes and limits callable surface area.

4) Add IP Whitelisting (recommended)

Limit who can connect to the Java bridge server:

dotNetSide.ipWhitelist=127.0.0.1

In real deployments, replace localhost with your actual trusted app hosts/subnets.

5) Enable SSL/TLS Correctly

For production workloads, treat TLS as mandatory. The high-level flow:

1. Generate server/client certificates
2. Install server cert in Java keystore
3. Install trusted client certs in Java truststore
4. Install client cert on the .NET side
5. Reference certs in both App.config and javaSide.properties

Once done, Java↔.NET traffic is encrypted and mutually authenticated.

For implementation details, follow the SSL section in the JNBridgePro docs and the Java JSSE reference:

• JNBridgePro Developer Center
• Oracle JSSE Reference Guide

6) Start Order Matters in TCP Mode

Unlike shared memory, Java must be started first in TCP mode.

Use:

java -cp ".;javaToCall.jar;jnbcore.jar" com.jnbridge.jnbcore.JNBMain /props "javaSide.properties"

This starts the Java bridge process with your TCP + security configuration loaded.

After Java is listening, start the .NET app so it can connect successfully.

Common TCP Migration Pitfalls

Port mismatch

If .NET App.config and javaSide.properties ports differ, connection attempts fail immediately.

TLS config mismatch

If CN/SAN values, trust chains, or client cert references are wrong, SSL handshake fails even when host/port are correct.

Whitelist too strict (or too loose)

• Too strict → valid calls blocked
• Too loose → unnecessary attack surface

Start with least privilege and expand only as needed.

Java side not running first

In TCP mode, .NET is the client and Java is the server. If Java isn’t up, .NET connection retries/failures are expected.

Suggested Production Checklist

Before go-live, verify:

• [ ] scheme="jtcp" set on .NET side
• [ ] Same port on both sides
• [ ] Java side starts before .NET side
• [ ] Class whitelist enabled and minimal
• [ ] IP whitelist restricted to trusted hosts
• [ ] TLS enabled with valid cert chain
• [ ] Timeout/worker values tuned for expected load

Final Takeaway

TCP mode is how you scale JNBridgePro beyond single-host deployments while keeping strong security boundaries. The core move is simple (sharedmem → jtcp), and most reliability issues come from three things: startup order, inconsistent port/cert settings, and missing whitelist hygiene.

If you configure those early, TCP deployments stay predictable under real production traffic.

For related deep dives:

• Shared Memory Bridge Anatomy
• JNBridgePro v12 Crash Fix (x86 shared memory)
• How to Call Java from C#