Advanced TLS configuration

This guide covers advanced TLS configuration including cipher suite selection, naming conventions, and troubleshooting.

For basic TLS configuration, see Connect with TLS.

Caution

Aerospike Database does not support TLS 1.3. Use TLS 1.2 for client and server TLS configuration.

Cipher suite selection

Cipher suites determine the encryption algorithms used for TLS connections. Choose suites based on your security requirements and performance needs.

Recommended cipher suites

Security Level	Cipher Suites	Use Case
High	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384	Financial, healthcare
Standard	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256	General production
Compatible	Include TLS_ECDHE_RSA_*	RSA certificates and broader client support

OpenSSL vs IANA naming

Aerospike Database uses OpenSSL naming, while the Java and Python SDKs use IANA (RFC) naming. Use this mapping table:

IANA Name (Java and Python SDKs)	OpenSSL Name (Server)
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384	ECDHE-RSA-AES256-GCM-SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256	ECDHE-RSA-AES128-GCM-SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384	ECDHE-ECDSA-AES256-GCM-SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256	ECDHE-ECDSA-AES128-GCM-SHA256

Server-side cipher configuration

Configure allowed ciphers in aerospike.conf:

network {
    tls tls-name {
        cert-file /etc/aerospike/certs/server.crt
        key-file /etc/aerospike/certs/server.key
        ca-file /etc/aerospike/certs/ca.crt

        cipher-suite ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256

        protocols TLSv1.2
    }
}

Client-side cipher configuration

Java

import com.aerospike.client.sdk.Cluster;
import com.aerospike.client.sdk.ClusterDefinition;

// Configure cluster with TLS, restricted to specific protocols and ciphers
try (Cluster cluster = new ClusterDefinition("secure.aerospike.example.com", 4333)
    .withTlsConfig(tls -> tls
        .tlsName("aerospike-server")
        .caFile("/path/to/ca.crt")
        .protocols("TLSv1.2")
        .ciphers(
            "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
            "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
            "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
            "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
        ))
    .connect()) {
    // Use cluster / session here
}

📖 API reference: ClusterDefinition(String,int) | ClusterDefinition.connect() | ClusterDefinition.withTlsConfig(...) | Cluster.close()

Using a custom SSLContext

The protocol and cipher restrictions from protocols() and ciphers() also apply when you supply a custom SSLContext.

import com.aerospike.client.sdk.Cluster;
import com.aerospike.client.sdk.ClusterDefinition;
import javax.net.ssl.SSLContext;
import javax.net.ssl.TrustManagerFactory;
import java.io.FileInputStream;
import java.io.InputStream;
import java.security.KeyStore;

KeyStore trustStore = KeyStore.getInstance("PKCS12");
try (InputStream in = new FileInputStream("/path/to/truststore.p12")) {
    trustStore.load(in, "password".toCharArray());
}

TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
tmf.init(trustStore);
SSLContext customSslContext = SSLContext.getInstance("TLSv1.2");
customSslContext.init(null, tmf.getTrustManagers(), null);

try (Cluster cluster = new ClusterDefinition("secure.aerospike.example.com", 4333)
    .withTlsConfig(tls -> tls
        .tlsName("aerospike-server")
        .customSslContext(customSslContext))
    .connect()) {
    // Use cluster / session here
}

📖 API reference: ClusterDefinition(String,int) | ClusterDefinition.connect() | Cluster.close()

Python

from aerospike_sdk import ClusterDefinition

cluster = await (
    ClusterDefinition("secure.aerospike.example.com", 4333)
    .with_tls_config(
        tls_name="aerospike-server",
        ca_file="/path/to/ca.crt",
        protocols=["TLSv1.2"],
        ciphers=[
            "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
            "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
            "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
            "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
        ],
    )
    .connect()
)

The Python SDK has no custom SSLContext option. It rejects an unknown cipher or protocol name, such as an OpenSSL-style cipher name, with ValueError at connect().

📖 API reference: ClusterDefinition.with_tls_config()

Troubleshooting TLS handshake issues

Common error messages

Error	Likely Cause	Solution
handshake_failure	No common cipher suite	Check cipher configuration on both sides
certificate_unknown	CA not trusted	Verify CA certificate path
certificate_expired	Cert past validity	Renew certificate
bad_certificate	Cert/key mismatch	Regenerate cert with correct key

Debugging with Java

Enable TLS debugging to see handshake details:

# Full TLS debugging
java -Djavax.net.debug=ssl:handshake -jar your-app.jar

# Only handshake messages
java -Djavax.net.debug=ssl:handshake:verbose -jar your-app.jar

# Only cipher negotiation
java -Djavax.net.debug=ssl:handshake:ciphersuites -jar your-app.jar

Sample debug output for cipher negotiation:

javax.net.ssl|DEBUG|...ClientHello, TLSv1.2
...
Cipher Suites: [TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, ...]
...
javax.net.ssl|DEBUG|...ServerHello, TLSv1.2
...
Cipher Suite: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

Debugging with Python

The Python SDK’s TLS layer (rustls, inside the native client) logs handshake details, including the negotiated cipher suite, to the rustls logger:

import logging

# Enable TLS handshake debugging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("rustls").setLevel(logging.DEBUG)

# Or use OpenSSL directly
import subprocess
result = subprocess.run([
    'openssl', 's_client',
    '-connect', 'secure.aerospike.example.com:4333',
    '-tls1_2',
    '-CAfile', '/path/to/ca.crt'
], capture_output=True, text=True)
print(result.stdout)

📖 PSDK Guide: Connecting → TLS

Verify server cipher support

Use OpenSSL to check which ciphers the server accepts:

# Check TLS 1.2 ciphers
openssl s_client -connect server:4333 -tls1_2 -cipher ECDHE-RSA-AES256-GCM-SHA384

# List all supported ciphers
nmap --script ssl-enum-ciphers -p 4333 server

Certificate chain verification

Verify your certificate chain is complete:

# Check certificate
openssl x509 -in server.crt -text -noout

# Verify chain
openssl verify -CAfile ca.crt server.crt

# Check key matches certificate
openssl x509 -noout -modulus -in server.crt | openssl md5
openssl rsa -noout -modulus -in server.key | openssl md5
# Both should output the same hash

Performance considerations

Cipher performance

Cipher	Relative Performance	Notes
ECDHE-RSA-AES128-GCM-SHA256	Fastest	Hardware AES-NI
ECDHE-RSA-AES256-GCM-SHA384	Fast	Hardware AES-NI
ECDHE-RSA-CHACHA20-POLY1305	Fast	Better on ARM without AES-NI

Recommendations

1. Use TLS 1.2 for Aerospike Database and client TLS settings.
2. Prefer AES-GCM on x86 with AES-NI support
3. Use ChaCha20 on ARM or older CPUs without AES-NI
4. Enable session resumption to reduce handshake overhead

Java

import javax.net.ssl.SSLContext;
import javax.net.ssl.SSLSessionContext;

// Enable session caching (default in most JVMs)
SSLContext sslContext = SSLContext.getInstance("TLSv1.2");
SSLSessionContext sessionContext = sslContext.getClientSessionContext();
sessionContext.setSessionCacheSize(100);
sessionContext.setSessionTimeout(3600);  // 1 hour

📖 API reference: com.aerospike.client.sdk

Python

The Python SDK does not use Python’s ssl module, so there is no SSLContext to tune. Its TLS layer keeps a client session cache automatically.

📖 PSDK Guide: Connecting → TLS

Next steps

Connect with TLS

Basic TLS setup guide.

TLS Connection →

Common Issues

Troubleshoot connection problems.

Common Issues →