TLS Setup
Configure server-side TLS for encrypted KubeMQ connections, including config validation, in the Kotlin SDK.
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 tls { } DSL block's 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. TLS-enabled deployments commonly listen on a separate port from the plaintext one (e.g. 50001 vs 50000) — connecting to the wrong port produces a generic connection error that looks like a certificate problem but isn't.
Prerequisites
- KubeMQ server running with TLS enabled (typically on port 50001)
- Kotlin SDK installed (
implementation("io.kubemq.sdk:kubemq-sdk-kotlin:1.0.1")) - CA certificate file (
ca.pem) for server verification
Code
package io.kubemq.sdk.examples.tls
import io.kubemq.sdk.client.KubeMQClient
import kotlinx.coroutines.runBlocking
private const val ADDRESS = "localhost:50001"
private const val CLIENT_ID = "kotlin-tls-tls-setup"
private const val CA_CERT_FILE = "/path/to/ca.pem"
fun main() = runBlocking {
connectWithTlsValidation()
// Uncomment when TLS server is available:
// connectWithServerTls()
println("TLS setup examples completed.")
}
private suspend fun connectWithServerTls() {
println("=== Server-Side TLS Connection ===\n")
// Create a client with server-side TLS (CA cert for verification)
try {
val client = KubeMQClient.queues {
address = ADDRESS
clientId = CLIENT_ID
tls {
caCertFile = CA_CERT_FILE
}
}
client.use {
val info = it.ping()
println("Successfully connected with server-side TLS!")
println("Server Info: host=${info.host}, version=${info.version}")
}
} catch (e: Exception) {
println("TLS connection failed: ${e.message}")
}
}
private fun connectWithTlsValidation() {
println("=== TLS Validation ===\n")
// Demonstrate TLS configuration (does not require live TLS server)
println("Test: TLS configuration with cert and key...")
try {
val client = KubeMQClient.queues {
address = ADDRESS
clientId = CLIENT_ID
tls {
certFile = "/path/to/client.pem"
keyFile = "/path/to/client-key.pem"
caCertFile = CA_CERT_FILE
}
}
println("TLS client configured successfully.")
println(" certFile, keyFile, and caCertFile all set.")
client.close()
} catch (e: Exception) {
println("Configuration error: ${e.message}")
}
println()
}How It Works
- The
tls { }DSL block configures TLS on the client. caCertFilesets the CA certificate for verifying the server's identity.- For server-side TLS, only the CA certificate is needed.
- The client validates the server certificate against the provided CA.
- TLS connections typically use a different port (e.g., 50001).
Related
Was this page helpful?