# TLS Setup (/sdks/cpp/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: `TlsConfig::FromCertFile()` loads that CA file, and `Client::Create()` 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/cpp/how-to/tls/mtls-setup) adds). The CA file must be the issuing CA (or full chain), not the server's leaf certificate, or the handshake fails outright. And because `Client::Create()` returns a `StatusOr`, a wrong CA path, an expired certificate, and an unreachable server all surface the same way — as `!ok()` — so check `status().message()` before assuming the CA file is at fault.

## Prerequisites [#prerequisites]

* KubeMQ server running on `localhost:50000`
* C++ SDK installed (vcpkg or CMake FetchContent)
* C++17 compiler (GCC 9+, Clang 9+, MSVC 2019+)
* CA certificate file for the KubeMQ server

## Code [#code]

```cpp title="main.cc"
// Example: tls/tls_setup
//
// Demonstrates connecting to a KubeMQ server over TLS using a CA certificate.
// The client verifies the server's identity via the CA certificate without
// providing client credentials (server-side TLS only).
//
// Channel: cpp-tls.tls-setup
// Client ID: cpp-tls-tls-setup-client
//
// Run with a KubeMQ server configured for TLS.
// Update the CA certificate path before running.

#include <kubemq/kubemq.h>

#include <iostream>

int main() {
    std::cout << "[1] Connecting with TLS to localhost:50000" << std::endl;

    // Create TLS config with CA certificate file
    auto tls = kubemq::TlsConfig::FromCertFile("/path/to/ca.pem");

    kubemq::ClientOptions options;
    options.set_address("localhost", 50000);
    options.set_client_id("cpp-tls-tls-setup-client");
    options.set_tls_config(tls);

    auto client_result = kubemq::Client::Create(options);
    if (!client_result.ok()) {
        std::cerr << "[ERROR] Failed to create client: " << client_result.status().message()
                  << std::endl;
        std::cout << "[INFO] Ensure the KubeMQ server has TLS enabled and the CA cert path is correct."
                  << std::endl;
        return 1;
    }
    auto& client = *client_result;

    auto ping_result = client->Ping();
    if (!ping_result.ok()) {
        std::cerr << "[ERROR] Ping failed: " << ping_result.status().message() << std::endl;
        return 1;
    }
    std::cout << "[2] Connected with TLS. Server version: " << ping_result->version << std::endl;

    auto close_status = client->Close();
    if (!close_status.ok()) {
        std::cerr << "[ERROR] Close failed: " << close_status.message() << std::endl;
        return 1;
    }
    std::cout << "[3] Client closed" << std::endl;

    return 0;
}
```

## How It Works [#how-it-works]

* Calls `TlsConfig::FromCertFile("/path/to/ca.pem")` to create a server-side TLS configuration — the client loads the CA certificate from disk to verify the broker's identity.
* Passes the `TlsConfig` to `options.set_tls_config(tls)` before calling `Client::Create()`.
* All gRPC traffic between the client and broker is encrypted from this point forward; no client certificate is sent (server-side TLS only).
* `Client::Create()` returns a `StatusOr<unique_ptr<Client>>` — if the TLS handshake fails (wrong CA, expired cert, wrong path), `ok()` returns false and `status().message()` describes the error.
* Verifies the secure connection with `Ping()`, which confirms both transport encryption and server reachability.

## Related [#related]

* [C++ SDK Reference](/sdks/cpp/reference/client)
* [mTLS Setup](/sdks/cpp/how-to/tls/mtls-setup)
* [Token Authentication](/sdks/cpp/how-to/connection/token-auth)