SSL in the cluster

Overview

Full transport security in the Open Access API is provided by SSL, specifically TLSv1.

Both ends of the connection verify each others’ keys, in contrast to protocols such as HTTPS which generally only verify the server.

Each cluster node shares the same public and private key to verify each other. They additionally have the public keys to be used by API clients.

This is managed using the Java Secure Socket Extension (JSSE) API. If you already have a process for managing keystores under JSSE, the Open Access cluster can fit right in.

Creating keystore files

Two key pairs are required:

• Public/private key identifying nodes in the cluster
• Public/private key identifying API clients

The keys must then be imported into keystore files. Four files should be created:

• Cluster Node Key Store (containing cluster node public and private key)
• Cluster Node Trust Store (containing cluster node public key and client public key)
• Client Key Store (containing client public and private key)
• Client Trust Store (containing cluster node public key)

Note the keystore should only contain entries with the PrivateKeyEntry type. Similarly, the truststore should only contain trustedCertEntry types.

Keys can be added and removed from the stores using the keytool command shipped with the Oracle JRE.

Enable SSL

SSL is enabled by editing the settings in config/application.conf.

akka {
    remote {
        enabled-transports = [akka.remote.netty.ssl]
        netty.ssl {
           enable-ssl = true
           hostname = ${akka.remote.netty.tcp.hostname}
           port = ${akka.remote.netty.tcp.port}
           security {
               key-store = "<path to keystore>"               key-store-password = "<keystore password>"               key-password = "<key password>"               trust-store = "<path to truststore>"               trust-store-password = "<truststore password>"               protocol = "TLSv1"               random-number-generator = "AES128CounterSecureRNG"               enabled-algorithms = [TLS_RSA_WITH_AES_128_CBC_SHA]
           }
        }
    }
}

On the client side, the port should be set to 0.

Note that the URL protocol for cluster seed nodes changes when SSL is enabled. Replace akka.tcp with akka.ssl.tcp.

# Before
seed-nodes = ["akka.tcp://ClusterSystem@localhost:2551", "akka.tcp://ClusterSystem@localhost:2552"]

# After
seed-nodes = ["akka.ssl.tcp://ClusterSystem@localhost:2551", "akka.ssl.tcp://ClusterSystem@localhost:2552"]

Connect using SSL in the API

To connect using SSL in the API, change the URL protocol from geneos.cluster to geneos.cluster.ssl:

OpenAccess.Connection conn = OpenAccess.connect("geneos.cluster.ssl://localhost:2551");