TLS Setup

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 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

• 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

// 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

• 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

• C++ SDK Reference
• mTLS Setup
• Token Authentication