Changing to TCP: Configuration, SSL, Whitelisting & Startup
This post continues from our earlier walkthrough, Anatomy of a .NET Calling Java Project (Shared Memory), and uses the same BridgeDemo project to demonstrate how to change from Shared Memory to TCP communication.
While Shared Memory offers high performance for co-located components, TCP mode is used when the .NET and Java sides run on different machines. When using TCP, you can optionally enable additional features such as SSL encryption, IP whitelisting, and class whitelisting — features that aren’t applicable to Shared Memory connections.
1) Overview of the TCP Bridge
When the bridge runs in TCP mode, the .NET side and the Java side communicate through a socket connection rather than shared memory.
This offers several advantages:
- Cross-platform independence – the .NET and Java components can run on different hosts or operating systems.
- Remote accessibility – the bridge can connect across LAN or WAN networks.
- Security options – TCP supports SSL, IP whitelisting, and class-level restrictions(class whitelisting).
Unlike Shared Memory, the Java side must be started first in TCP mode so that the .NET side can connect to it.
2) Updating the .NET Configuration (App.config)
In BridgeDemo, open App.config and locate the <dotNetToJavaConfig> section.
Change the scheme from sharedmem to jtcp, and specify the host, port, and optional SSL parameters.
- scheme – must be set to jtcp
- host – the machine where the Java side is running
- port – must match the port defined in java.properties
Example:
<jnbridge>
<dotNetToJavaConfig
scheme="jtcp"
host="localhost"
port="8085"
useSSL="true"
clientCertificateLocation=".\testclient.p12"
clientCertificatePassword="pw"
sslAlternateServerNames="myServer" />
/>
</jnbridge>
If you are not using SSL, simply omit those attributes or set useSSL to false.
3) Updating the Java-Side Configuration (java.properties)
On the Java side, update java.properties to switch the bridge to TCP, define the connection port, and enable optional security features like IP and class whitelisting or SSL.
Example — javaSide.properties
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=changeit4) Adding Whitelisting (Class and IP)
When using TCP, you can restrict which classes are exposed to .NET and which clients are allowed to connect. These options improve security and control without affecting performance.
a) Class Whitelisting
Create a file named classWhiteList.txt in the same directory as java.properties.
Each line specifies a fully qualified Java class name that can be accessed from the .NET side.
Example — classWhiteList.txt
bridgeDemo.JavaToCall
Then, enable class whitelisting in java.properties:
javaSide.useClassWhiteList=true
javaSide.classWhiteListFile=./classWhiteList.txt
Only the classes listed here can be loaded by the bridge; all others are blocked automatically.
b) IP Whitelisting
IP whitelisting limits which machines can connect to the Java bridge.
Add the following property to java.properties:
dotNetSide.ipWhitelist=127.0.0.1
5) Enabling SSL
SSL enables encryption, server authentication, and client authentication, protecting both sides of the bridge and preventing unauthorized access or code execution.
To implement SSL, you must complete all of the steps outlined in the “Secure communications using SSL” section of the User Guide(p.78)
1) Generate and install certificates
-Each Java side requires an X.509 server certificate whose Common Name (CN) matches the host where the Java side runs.
-Each .NET side requires its own client certificate, consisting of a public certificate and a corresponding private-key file.
2) Create and install the keystore and truststore on the Java side
-Install the Java side’s server certificate in a keystore file.
-Install each authorized .NET side’s client certificate in a truststore file.
-Both files must have passwords and be referenced in the JavaSide.properties file:
3) Create and install the keystore and truststore on the Java side
-Import the client certificate into the Windows Certificate Store.
-Leave the public certificate file accessible on disk so it can be referenced in the bridge configuration.
4) Configure the .NET side for SSL
-specify properties in app.config for SSL
After these steps are completed, all communication between .NET and Java occurs over an encrypted, mutually authenticated SSL channel.
For example, when .NET calls Ping.incr(1) the invocation is transmitted through this secure connection. The Java server’s identity is verified, the .NET client is authenticated, and all data is protected from interception.
The IP and class whitelists, worker-thread pool, and timeout settings continue to apply normally within this secure channel.
5) Starting the Java side
– The Java side must be started manually before any .NET connections are made.
– This launches the JNBridge Java component, loads all required classes, and applies the configuration defined in the properties file.
– Use the following command:
java -cp “.;javaToCall.jar;jnbcore.jar” com.jnbridge.jnbcore.JNBMain /props “javaSide.properties”
This command must be run from the directory that contains the listed JAR files and the javaSide.properties file. When you execute it, Java uses the classpath (-cp) to locate javaToCall.jar (your Java classes) and jnbcore.jar (the JNBridge runtime).