HOWTO - Step by step guide to configure and test TLS on Aerospike

Knowledge Base Deploying
1

The Aerospike Knowledge Base has moved to https://support.aerospike.com. Content on https://discuss.aerospike.com is being migrated to either https://support.aerospike.com or https://docs.aerospike.com. Maintenance on articles stored in this repository ceased on December 31st 2022 and this article may be stale. If you have any questions, please do not hesitate to raise a case via https://support.aerospike.com.

HOWTO - Step by step guide to configure and test TLS on Aerospike

NOTE: This does not apply to versions 3.14 and earlier.

Description

Configuring TLS for Aerospike consists of the following steps:

  1. Configure the tls{} stanza(s), to specify which certificates will be used.
  2. Add the TLS configuration to the relevant protocol stanzas, specifying which TLS name to use.
  3. Configure the parties that would connect to the cluster (XDR / client), if required, to use TLS.
  4. (OPTIONAL) Disable the non-TLS ports. This step may be omitted if you want to use TLS for XDR and not client connections, or vice versa.

In essence, you first configure a tls{} stanza for a specific tls-name and you then specify which protocols will use which tls-name.

The stanzas where TLS can be configured are:

name use-case
service{} server<->client communication
fabric{} server<->server fabric communication
heartbeat{} server<->server heartbeats (only if in mesh mode)
xdr{} XDR inter-cluster communication

Note that once TLS is enabled in the service{} protocol, the info{} port (default 3003) is automatically disabled as it currently does not support TLS.

Types of authentication

There exist two different authentication methods using TLS:

name description
standard (server) authentication the server presents its certificate so that the client can authenticate it using the ca-cert the client holds. This allows the client to trust that it connected to the correct server.
mutual authentication both client and server present their respective certificate. This allows the client to trust that it connected to the correct server and the server to trust that the client is allowed to connect.

Details

Configuring the TLS stanza

Let’s assume the key, certificate and CA cert are stored under the /etc/aerospike/tls/{tlsname} directory, where tls-name matches the certificate CN (common name) field in the certificate.

tls <tls-name> {
  cert-file           /etc/aerospike/tls/{tlsname}/cert.pem
  key-file            /etc/aerospike/tls/{tlsname}/key.pem
  ca-file             /etc/aerospike/tls/{tlsname}/cacert.pem
}

You can then specify multiple tls{} stanzas for different TLS names and, therefore, use different certificates for different protocols.

Which parameters are required depends on what you will use the TLS stanza for, as follows:

name required
service{} cert-file, key-file. If using mutual-authentication, also ca-file
fabric{} cert-file, key-file, ca-file
heartbeat{} cert-file, key-file, ca-file
xdr{} ca-file. If destination cluster performs mutual-authentication on service{}, also cert-file and key-file.

Enabling TLS for client connections

If enabling TLS for client connections, you need to:

  1. Enable TLS for the service{} protocol stanza on the cluster.
  2. Enable TLS connections on the client side.
  3. Disable non-TLS connection ports in the service{} stanza.

Enabling TLS for XDR

If you are enabling TLS for XDR, you need to:

  1. Enable TLS for the service{} protocol stanza on the destination cluster.
  2. Enable TLS connections on the source cluster in the xdr{} stanza.
  3. Disable non-TLS connection ports in the service{} stanza on the destination cluster.

Note that this is essentially the same as configuring TLS for client connections, where the source cluster plays the part of the client.

Enabling TLS for fabric and heartbeat protocols

If enabling TLS for the fabric and / or heartbeat protocols you need to, in a rolling fashion:

  1. Enable TLS for the heartbeat{} and fabric{} protocol stanzas on the cluster, one node at a time.
  2. Disable non-TLS connection ports in the heartbeat{} and fabric{} protocol stanzas on the cluster, one node at a time.

Configuring the protocol stanzas

This part explains how to enable all protocol TLS stanzas. Note that if enabling XDR, the service{} part must first be enabled on the destination following the instructions below, before enabling the xdr{} part on the source cluster.

1. Configure heartbeat protocol to use TLS. Do NOT disable the non-TLS port at this stage as it would prevent proper heartbeat exchanges with the nodes that have not been configured yet.

  heartbeat {
  mode                      mesh
  port                      3002
  tls-port                  3012
  tls-name                  <tls-name>
  tls-mesh-seed-address-port  10.0.0.100 3012
  tls-mesh-seed-address-port  10.0.0.104 3012
  ...
}

2. Configure fabric protocol to use TLS. Do not disable non-TLS port at this stage as it would prevent proper fabric exchanges with the nodes that have not been configured yet.

fabric {
  port        3001
  tls-port    3011
  tls-name    <tls-name>
  ...
}

3. Configure the service protocol to use TLS. Do NOT disable the non-TLS port at this stage as it would prevent clients (including XDR clients) to connect to the cluster since they would still be using the clear (non-TLS) port at this point.

service {
    address                  10.0.0.100
    port                     3000
    tls-address              10.0.0.100
    tls-port                 4333
    tls-authenticate-client  any          // mutual authentication
    tls-authenticate-client  false        // server authentication
    tls-name                 <tls-name>
    ...
}

4. Configure the XDR protocol stanza to use TLS.

Note that the tls-name specified in tls-node or node-address-port is what this source cluster expects to receive in a certificate from the destination (standard authentication - as the destination is the server). This (source) cluster will need the ca-file for that tls-name in the tls{} stanza, so it can authenticate the server. The server (destination cluster) will need this TLS name in the service{} stanza specified with key-file and cert-file.

The name specified in the tls-name part is the TLS name that will be used for mutual authentication (if the server, i.e. destination cluster, has the tls-authenticate-client specified, to be either ‘any’ or this TLS name in its service{} stanza). Since this part is used for client (i.e. source cluster) authentication, the TLS name specified here will need the cert-file and key-file. The destination cluster will need the ca-file of this TLS name to authenticate the client.

Example for versions 3.15 through 4.9

xdr {
    datacenter remote_dc1 {
        tls-node       10.0.0.100 destination-cluster-tls-name 4333
        tls-name       this-cluster-tls-name
    }
    enable-xdr true
    ...
}

Example for versions 5.0 and later

xdr {
    dc dataCenter1 {
        node-address-port 10.0.0.100 4333 destination-cluster-tls-name
        tls-name this-cluster-tld-name
        namespace someNamespace {
          ...
        }
    }
    ...
}

5. Restart the node and proceed to update the next node configuration.

6. Once all nodes are updated, update the client configurations to use TLS ports. If this is a destination datacenter, now update the xdr{} stanza on the source cluster as well, so that it will connect to this cluster’s TLS ports.

7. Remove the non-tls configurations, one node at a time, followed by that node restart.

  • service: address and port
  • fabric: port
  • heartbeat: port

Notes

Keywords

TLS AEROSPIKE FABRIC XDR CLIENT HEARTBEAT HB

Timestamp

June 2021