TLS Setup
Configure server-side TLS encryption for Java client connections
Overview
Server-side TLS is the baseline transport security for any KubeMQ connection that leaves a trusted network — it encrypts the wire and lets the client confirm it's really talking to your KubeMQ server, not an impersonator. Reach for it whenever traffic crosses a public network or a boundary you don't fully control; skip it and channel names, payloads, and client IDs travel in plaintext with no protection against a spoofed endpoint.
It works by pairing the client with the CA certificate that signed the server's TLS certificate: the builder's .tls(true) with .caCertFile() loads that CA file, and the client performs a standard TLS handshake, validating the server's certificate chain before any request is sent. The client presents no certificate of its own — only the server proves its identity.
Gotchas: this is one-way trust — it stops eavesdropping and server impersonation, but the server still can't verify who the client is (that's what mTLS adds). caCertFile must point to the issuing CA (or full chain), not the server's leaf certificate, or the handshake fails outright. The SDK also validates configuration eagerly — supplying a client cert without its matching key throws IllegalArgumentException before any network call is attempted, which is useful for catching misconfiguration early but easy to mistake for a connection failure.
Prerequisites
- KubeMQ server running with TLS enabled
- Java SDK installed (Maven/Gradle dependency
io.kubemq.sdk:kubemq-sdk-Java:3.1.1) - TLS certificates (CA certificate file)
Code
package io.kubemq.example.tls;
import io.kubemq.sdk.client.KubeMQClient;
import io.kubemq.sdk.common.ServerInfo;
import io.kubemq.sdk.queues.QueuesClient;
/**
* TLS Setup Example
*
* Demonstrates establishing a secure TLS connection to KubeMQ server.
*/
public class TlsSetupExample {
private static final String ADDRESS = "localhost:50001";
private static final String CLIENT_ID = "java-tls-tls-setup-client";
private static final String CA_CERT_FILE = "/path/to/ca.pem";
public void connectWithServerTLS() {
System.out.println("=== Server-Side TLS Connection ===\n");
// Create a client with server-side TLS (CA cert for verification)
try {
QueuesClient client = QueuesClient.builder()
.address(ADDRESS)
.clientId(CLIENT_ID)
.tls(true)
.caCertFile(CA_CERT_FILE)
.logLevel(KubeMQClient.Level.INFO)
.build();
// Verify TLS connection
ServerInfo serverInfo = client.ping();
System.out.println("Successfully connected with server-side TLS!");
System.out.println("Server Info: " + serverInfo);
// Clean up resources
client.close();
} catch (Exception e) {
System.err.println("TLS connection failed: " + e.getMessage());
}
}
public void connectWithTLSValidation() {
System.out.println("=== TLS Validation ===\n");
// Test that incomplete TLS config (cert without key) fails validation
try {
System.out.println("Testing incomplete TLS configuration...");
QueuesClient client = QueuesClient.builder()
.address(ADDRESS)
.clientId(CLIENT_ID)
.tls(true)
.tlsCertFile("/path/to/client.pem")
.build();
client.close();
} catch (IllegalArgumentException e) {
System.out.println("Caught validation error: " + e.getMessage());
System.out.println("Cert and key must be provided together.\n");
}
}
public static void main(String[] args) {
TlsSetupExample example = new TlsSetupExample();
example.connectWithTLSValidation();
// Uncomment when TLS server is available:
// example.connectWithServerTLS();
System.out.println("TLS setup examples completed.");
}
}How It Works
- The builder pattern with
.tls(true)and.caCertFile()enables server-side TLS verification. - The client verifies the server's certificate against the provided CA certificate before establishing the connection.
- The validation example demonstrates that the SDK catches misconfigured TLS settings (e.g., providing a cert without a key).
- Replace
"/path/to/ca.pem"with the actual path to your CA certificate.
Related
Was this page helpful?