Skip to main content
Aerospike Vector is now live with LangChain integrationTell me more
Loading

Transport Layer Security

Overview​

This page describes the Aerospike configuration settings and considerations for using Transport Layer Security (TLS) in Aerospike implementations. For specific information about configuring Aerospike to use TLS on your network, see TLS Configuration.

Aerospike Enterprise Edition supports TLS for the following network traffic:

  • Client-to-Cluster - Traffic between clients and all database nodes.

  • Cluster-to-Cluster - Traffic between clusters (Cross-Datacenter Replication, or XDR).

  • Node-to-Node - Traffic between nodes in a cluster, both fabric and heartbeat.

  • Starting with Database 7.2, Aerospike gains compatibility with OpenSSL 3.0.13, to support Ubuntu 24.04 LTS.

  • Starting with Database 6.3, Aerospike gains compatibility with OpenSSL 3, to support Ubuntu 22.04, RHEL 9/CentOS Stream 9, and other Linux distributions that support OpenSSL 3. The server and clients retain compatibility with OpenSSL 1.1.

  • Clients: Aerospike clients' TLS implementation is specific to the language. Refer to Client Support for details.

  • Server configuration: refer to the Network Configuration/TLS page for details on configuring TLS.

TLS between clients and cluster​

Aerospike offers 3 modes for TLS Security between clients and a cluster, selected by the tls-authenticate-client configuration parameter in the service sub-stanza:

  • Standard authentication (value false)
  • Mutual authentication (value any)
  • Mutual authentication with subject name validation (value is user defined, for example host.domain.com)
note

tls-authenticate-client replaces the tls-mode configuration parameter as of version 3.15.

Standard authentication​

Standard authentication dictates how the client authenticates each of the nodes in the Aerospike Cluster using TLS.

TLS name and authentication​

The TLS name, configured as the tls-name, authenticates each TLS socket connection against a server node, based on the certificate presented by the Aerospike server node during the initial connection handshake. The TLS name for a node is typically the node's hostname. See TLS name clarification.

In a typical connection flow:

  • The expected TLS name is passed in for the seed node(s).
  • For each TLS connection to the seed node, the TLS name match algorithm is executed against the certificate presented by the seed node.
  • Once matched, the client fetches from the seed node all peer nodes' connection information and each of their tls-name information, and continues TLS connections to each of the remaining peer nodes.

The TLS name match algorithm is as follows:

  • Seed node's tls-name matches the certificate's Subject/CN field.

  • Seed node's tls-name matches the certificate's X509v3 Subject Alternative Name (SAN) field.

Typical authentication setup​

Following are some common standard authentication setups that a deployment may use. Aerospike recommends using the Cluster name match setup.

The common server configuration parameters are the following:

  • tls-authenticate-client configuration parameter must be set to false.
  • cert-file must be set. It is a .pem file, which contains the server's own certificate.
  • key-file must be set. It is the .pem file with the private key associated with the certificate.

The client must have the relevant root CA certificate configured.

Hostname match with individual server certificate​

  • Server certificate
    • Each Aerospike server node uses its own certificate.
    • The certificate must have the node's system hostname defined in the Subject/CN or SAN field. For example:
Subject: C=US, ST=California, L=San Jose, O=Acme, Inc., OU=Aerospike Cluster, CN=m1.acme.com
  • Server configuration
    • All Aerospike nodes must configure the system hostname correctly, and the name must match the value in the Subject/CN or SAN field.
    • A tls sub-stanza for <hostname> must be defined in the aerospike.conf file, and the tls-name in the service sub-stanza must be specified and have the value <hostname> for the system's hostname to be read as the TLS name.
  • Client Configuration
    • On client applications, for each seed host passed into the cluster_create() call, pass in the same <hostname> for the tls-name as the TLS name.

Hostname match with common server certificate​

  • Server certificate
    • All Aerospike server nodes use the same certificate.
    • The certificate must include the x509v3 Subject Alternate Name (SAN) extension, and include the list of all the node's hostnames in the field. For example:
X509v3 extensions:
    X509v3 Subject Alternative Name:
    DNS:m1.acme.com, DNS:m2.acme.com, DNS:m3.acme.com

  • Server configuration

    • All Aerospike nodes must configure their system's hostname correctly and the name must match what's presented in the SAN extension.
    • A tls sub-stanza for <hostname> must be defined in the aerospike.conf file, and the tls-name in the service sub-stanza must be specified and have the value <hostname> for the system's hostname to be read as the TLS name.

  • Client configuration

    • On client applications, for each seed host passed into the cluster_create() call, pass in the same <hostname> for the tls-name as the TLS name.

Wildcard hostname match​

  • Server certificate
    • All Aerospike server nodes use the same cert.
    • The certificate must have a matchable wildcard in the Subject/CN field or SAN field. For example:
Subject: C=US, ST=California, L=San Jose, O=Acme, Inc., OU=Aerospike Cluster, CN=*.aerospike-cluster.acme.com

  • Server configuration

    • All Aerospike nodes must configure their system's hostname correctly to follow the wild card rule.
    • A tls sub-stanza for <hostname> has to be defined in the aerospike.conf file and the tls-name in the service sub-stanza must be specified and have the value <hostname> in order for the system's hostname to be read as the TLS name.

  • Client configuration

    • On client applications, for each seed host passed into the cluster_create() call, pass in the node's hostname as the TLS name.
    • Wildcard hostname match is not available with the Java and C# Clients.

Cluster name match​

  • Server Certificate
    • All Aerospike server nodes use the same cert.
    • The certificate must have the clustername defined in the Subject/CN field or SAN field. For example:
Subject: C=US, ST=California, L=San Jose, O=Acme, Inc., OU=Aerospike Cluster, CN=as-cluster-west

  • Server Configuration

    • All Aerospike server nodes use the same aerospike.conf file, with the same clustername specified in the aerospike.conf file.
    • A tls sub-stanza for <cluster-name> has to be defined in the aerospike.conf file and the tls-name in the service sub-stanza must be specified and have the value <cluster-name> in order for the node's configured clustername to be used as the TLS name.
    • Using the clustername (cluster-name) requires using Aerospike's heartbeat-v3 protocol.

  • Client Configuration

    • On client applications, for each seed host passed into the cluster_create() call, pass in the same <cluster-name> for the tls-name as the TLS name.

Mutual authentication​

Mutual authentication requires first deciding on one of the above Standard authentication setups to allow client authentication of server nodes.

In addition, for the server to authenticate the client, the following is required:

  • Client certificate
    • The certificate must be a valid certificate chain, and must be signed by the same certificate authority as the server.
    • No additional name matching is done.
  • Server configuration
note

There can be more than one tls-authenticate-client directive in order to accept multiple subject names. A typical example would be to use different subject names between local clients and XDR clients.

Mutual authentication with subject name validation​

This is similar to Mutual authentication, the only difference being that the name matching would be done.

  • Client certificate
    • The certificate must be a valid certificate chain, and must be signed by the same certificate authority as the server.
    • Name matching is done.
  • Server configuration
    • tls-authenticate-client configuration parameter must be set to the specific name (for example host.domain.com). This is the TLS name a cluster node expects clients to present on incoming client connections.
    • ca-file/ca-path must be configured to point to the client's signing CA cert.

TLS between cluster nodes​

For intra-cluster traffic (both fabric and heartbeat), all cluster nodes share the same TLS name and can thus use the same certificate. Even though intra-cluster TCP connections happen between equal peers, in terms of the TLS handshake between the cluster nodes, the connecting node plays the TLS client role and the accepting node plays the TLS server role. Therefore, the following applies:

  • TLS authentication between cluster nodes is always mutual. The TLS client authenticates the server and vice versa. In contrast to client-facing TLS, this isn't optional or configurable.
  • The subject name in a certificate is always validated. A TLS client with a given TLS name expects the accepting TLS server to present a certificate with the same subject name. A TLS server with TLS name X expects the connecting TLS client to present a certificate with subject name X. This means that all cluster nodes need to use the same TLS name.

TLS between XDR replicated clusters​

TLS for XDR traffic is similar to the client-server TLS implementation:

  • The source cluster is the "client". It must have all relevant configurations a TLS client requires. For each datacenter:
    • tls-node specifying the seed-node's IP address, the tls-name (of the remote DC), and port.
    • The tls-name (of the local DC).
    • The destination cluster is the "server", and must have all relevant configurations that a TLS server requires. The "service" section must be correctly set up to receive TLS traffic.

TLS name clarification​

Each TLS connection has a TLS name for the client where the TLS connection is initiated, and one for the server where the TLS connection is accepted. More precisely, "having a TLS name of X" means "presenting a certificate issued to a subject name of X". If a TLS server has a TLS name of server.aerospike.com, it will present a certificate issued to server.aerospike.com when a TLS client connects to it. Conversely, if a TLS client has a TLS name client.aerospike.com, it will present a certificate issued to client.aerospike.com to a TLS server that it connects to.

All cluster nodes share the same TLS name for intra-cluster heartbeat and fabric connections. A cluster node always uses the same TLS name, presenting the same certificate, regardless of which end of the connection it is on. Only one TLS name needs to be specified for heartbeat and fabric. This is done using the tls-name directive.

For the client service and for XDR this is different. Clients are allowed to use a different TLS name than the cluster they connect to. Similarly, an XDR remote DC being replicated to from a local DC is allowed to use a different TLS name than the local DC. This requires the ability to specify two TLS names. In these cases, the tls-name directive specifies the local TLS name (the TLS name that a cluster node presents on incoming client connections or on outgoing XDR connections). This covers the first of the two TLS names. The TLS name that a cluster node expects clients to present on incoming client connections is specified using tls-authenticate-client. The TLS name that a cluster node expects the remote DC to present on XDR connections is specified using tls-node.

In summary:

Client support​

  • C-Client - uses OpenSSL
    • Asynchronous libuv API supports TLS
  • Java Client - uses Java's built-in security library, javax.net.ssl.SSLSocket, and java.security.cert.X509Certificate
    • Asynchronous API supports TLS only when using the netty async framework (as of version 4.1.10)
    • Wildcard match not supported
    • For running with TLS, a java application must have the appropriate certificate added to the local truststore (for standard authentication) and local keystore (for mutual authentication). When required, the relevant script should be modified to supply the location of the truststore and keystore
  • C# Client - uses C#'s built-in security library, System.Security.Authentication
    • Asynchronous API supports TLS starting with C# client version 5.1.0
    • Wildcard match not supported
  • Python Client - uses OpenSSL
    • An OpenSSL library comes bundled with the wheel if you install using pip
    • Building from source uses the system's OpenSSL library

Revoking rogue certificates​

Aerospike provides an easy way to filter out rogue certificates through a black-list mechanism. If a certificate should no longer be legitimate, it should be added to the appropriate blacklist.

Refer to the cert-blacklist configuration parameter for further details.

TLS version and cipher choice​

Aerospike server defaults to TLS1.2. This can be overridden through configurations both on client and server side.

Aerospike relies on the TLS handshake to determine optimal cipher suite to pick, with server as the choice preference. It is also possible to explicitly set the cipher choice through configurations both on client and server side.

Refer to the cipher-suite configuration parameter for further details.

TLS certificate rotations​

Prior to version 7.0, only file-based TLS certificate rotation is supported. If the timestamp or content of the TLS certificate file changes, then they rotate dynamically.

Database 7.1 supports dynamic rotation of TLS certificates (private keys, certificates, password-protected private keys and blacklist) stored in the external Secret Manager along with file-based TLS certificates. Prior to Database 7.0, dynamic rotation of TLS certificates stored in the external secret managers is not supported. Starting with version 6.4, the Aerospike server can fetch secrets from external secret managers like AWS, GCP and Hashicorp Vault using secret agent. Default rotation period is 60 seconds. Configure the rotation period with tls-refresh-period. File-based TLS certificates are rotated only if actual content of the certificate file changes. If only timestamp of the file changes but not content, then they are not rotated.

Starting with Database 7.1, if either of TLS cert-file or key-file fails to update, then both cert-file and key-file will not be updated and will continue to use the old TLS cert-file and key-file. New connections with old TLS cert-file and key-file will continue to work. If the TLS certificates fail to rotate, then the Aerospike server reattempts and updates the new certificates every 30 seconds until they are successfully updated. Prior to Database 7.1, a partial update of TLS certificate and key is possible, meaning the certificate is updated successfully while the private key update fails, and vice versa. In such cases, the Aerospike server uses mis-matched TLS cert-file and key-file and new connections fail.

info
  • Rotation of password of password-protected private keys is not supported.
  • Dynamically rotating ECDSA private keys and certificates as well as password-protected private keys is not supported in Aerospike Database versions prior to 4.7.0.5, 4.6.0.8, 4.5.3.10, 4.5.2.10, 4.5.1.15, 4.5.0.19. More details in the FAQ on TLS.