# TLS Setup (/sdks/java/how-to/tls/tls-setup)



## Overview [#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](/sdks/java/how-to/tls/mtls-setup) 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 [#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 [#code]

```java title="TlsSetupExample.java"
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 [#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 [#related]

* [Java SDK Reference](/sdks/java/reference)
* [mTLS Setup](/sdks/java/how-to/tls/mtls-setup)