Managing mTLS with the Go client

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Aerospike Database Enterprise Edition supports standard TLS and mutual authentication TLS (mTLS). This page describes how to configure a Go application to connect to an Aerospike cluster that uses mTLS.

You can find a fully-functional example project in the aerospike-tls-examples GitHub repository.

Keys and certificates

For mTLS, both the client and server must have their own private key and certificate. In the following example, they are both signed by the same Certificate Authority (CA).

Install the certificates and the key on the Aerospike server nodes:

CA Certificate: example.ca.crt
Server Certificate: example.server.crt
Server Private Key: example.server.key

Install the certificates and the key on the Go client nodes:

CA Certificate: example.ca.crt
Client Certificate: example.client.crt
Client Private Key: example.client.key

Aerospike configuration

The following example aerospike.conf file shows only the directives that are relevant for this TLS configuration:

network {
    tls example.server {
        ca-file /opt/aerospike/etc/certs/example.ca.crt
        cert-file /opt/aerospike/etc/certs/example.server.crt
        key-file /opt/aerospike/etc/private/example.server.key
    }

    service {
        tls-address any
        tls-port 4000
        tls-name example.server
        tls-authenticate-client example.client
    }
}

The network.tls section defines the TLS configuration for the Aerospike Database certificate. This is used in both standard TLS as well as in mTLS.

The name example.server is known as the TLS name. This must match the value of the Common Name (CN) or Subject Alternative Name (SAN) of the server certificate example.server.crt. It must also be referenced in the application code to connect to the cluster. The following command verifies that the certificate has the expected CN value in the subject:

Command

openssl x509 -in example.server.crt -text -noout | grep -E -- "Subject:"

Example output

        Subject: CN = example.server, O = "Aerospike, Inc.", C = US

The tls-authenticate-client directive specifies example.client. This must match the value of the Common Name (CN) or Subject Alternative Name (SAN) of the client certificate example.client.crt. The following command verifies that the certificate has the expected CN value in the subject:

Command

openssl x509 -in example.client.crt -text -noout | grep -E -- "Subject:"

Example output

        Subject: CN = example.client, O = "Aerospike, Inc.", C = US

Go client TLS configuration

During the TLS handshake, the client sends its certificate to the server. Configure mutual TLS in Go using a standard crypto/tls.Config on ClientPolicy.TlsConfig.

Load the CA certificate into a cert pool, load the client certificate and key pair, then attach both to tls.Config:

import (
  "crypto/tls"
  "crypto/x509"
  "log"
  "os"

  as "github.com/aerospike/aerospike-client-go/v8"
)

caCert, err := os.ReadFile("/etc/aerospike/ssl/example.ca.crt")
if err != nil {
  log.Fatal(err)
}

serverPool := x509.NewCertPool()
if ok := serverPool.AppendCertsFromPEM(caCert); !ok {
  log.Fatal("unable to parse CA certificate")
}

clientCert, err := tls.LoadX509KeyPair(
  "/etc/aerospike/ssl/example.client.crt",
  "/etc/aerospike/ssl/example.client.key",
)
if err != nil {
  log.Fatal(err)
}

clientPolicy := as.NewClientPolicy()
clientPolicy.TlsConfig = &tls.Config{
  ServerName:   "example.server",
  RootCAs:      serverPool,
  Certificates: []tls.Certificate{clientCert},
}

If your cluster uses PKI-based user authentication (the client certificate’s CN is the Aerospike username), set AuthModePKI in the client policy. AuthModePKI requires Aerospike Database Enterprise Edition 5.7.0 and later. For transport-only mTLS with password-based users, omit AuthMode or leave it at the default AuthModeInternal:

clientPolicy.AuthMode = as.AuthModePKI

Go application

A Go application that connects to an Aerospike cluster using mTLS:

Must set TlsConfig on the client policy.
Must specify the host’s TLS name.
Must provide the client certificate in tls.Config.Certificates.
We recommend enabling Go client debug logging when troubleshooting.

The following example connects to a cluster using mTLS:

import (
  "crypto/tls"
  "crypto/x509"
  "log"
  "os"

  as "github.com/aerospike/aerospike-client-go/v8"
)

caCert, err := os.ReadFile("/etc/aerospike/ssl/example.ca.crt")
if err != nil {
  log.Fatal(err)
}

serverPool := x509.NewCertPool()
if ok := serverPool.AppendCertsFromPEM(caCert); !ok {
  log.Fatal("unable to parse CA certificate")
}

clientCert, err := tls.LoadX509KeyPair(
  "/etc/aerospike/ssl/example.client.crt",
  "/etc/aerospike/ssl/example.client.key",
)
if err != nil {
  log.Fatal(err)
}

clientPolicy := as.NewClientPolicy()
clientPolicy.AuthMode = as.AuthModePKI
clientPolicy.TlsConfig = &tls.Config{
  ServerName:   "example.server",
  RootCAs:      serverPool,
  Certificates: []tls.Certificate{clientCert},
}

host := as.NewHost("127.0.0.1", 4000)
host.TLSName = "example.server"

client, err := as.NewClientWithPolicyAndHost(clientPolicy, host)
if err != nil {
  log.Fatal(err)
}
defer client.Close()

The TLS name must match the Common Name (CN) or Subject Alternative Name (SAN) in the server certificate, as well as the tls-name used in the Aerospike configuration file.

To log Aerospike debug messages, see the Go client logging usage.

For standard TLS without mutual authentication, see Connecting.