Managing mTLS with the Node.js client

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

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 Node.js client nodes:

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

Aerospike configuration

The following example aerospike.conf configuration shows only the stanzas and 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 tls block in the network stanza 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:

openssl x509 -in example.server.crt -text -noout | grep -E -- "Subject:"
        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:

openssl x509 -in example.client.crt -text -noout | grep -E -- "Subject:"
        Subject: CN = example.client, O = "Aerospike, Inc.", C = US

Node.js client TLS configuration

Add CA certificate to Node.js client config

The CA certificate is a public certificate which verifies that the certificate presented by the Aerospike Database is signed by a trusted authority.

Specify a path to the CA Certificate using the Node.js Client Configuration.

let config = {
    tls: {
        enable: true,
        cafile: '/etc/aerospike/ssl/example.ca.crt',
    },
}

Add client certificate to Node.js KeyStore

During the TLS handshake, the client sends its certificate and a message encrypted with the client’s private key to the server. Since the Node.js application needs access to both the client certificate and the client private key, a path to each must be given.

Specify a path to the client certificate and key using the Node.js client configuration.

let config = {
    tls: {
        enable: true,
        certfile: '/etc/aerospike/ssl/example.client.crt',
        keyfile: '/etc/aerospike/ssl/example.client.key.pem'
    },
}

Node.js application

A Node.js application that connects to an Aerospike cluster using TLS:

Must enable TLS in the client policy.
Must specify the host’s TLS name.
Should log Aerospike debug messages.
Should log debug messages during the TLS handshake when troubleshooting.

To enable TLS in the Aerospike Client, the config must have some tlsInfo assigned to the tls property. Additionally, the enable parameter in tls must be true.

let config = {
    tls: {
        enable: true,

        // Specify necessary certificates below

        // cafile: '/etc/aerospike/ssl/example.ca.crt',
        // certfile: '/etc/aerospike/ssl/example.client.crt',
        // keyfile: '/etc/aerospike/ssl/example.client.key.pem'
    },
}

To specify the TLS name, add the tlsname property to any Host objects.

let config = {
    hosts: [
        { addr: "127.0.0.1", port: 4333,  tlsname: 'example.server'},
        { addr: "127.0.0.2", port: 4333,  tlsname: 'example.server'}
    ],
}

Remember that 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 Node.js Client logging usage.