HOWTO - Step by step guide to configure and test TLS on aerospike 3.15+

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

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. disable the non-TLS ports

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 2 different authentication methods using TLS:

name description
server authentication the server presents it’s 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 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

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 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 is what this source cluster expects to receive in a certificate from the destination (server 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 it’s 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.

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

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

Timestamp

June 21 2019