Implementing a Secure Binary Interface

Follow these instructions to start an HEAVY.AI server with an encrypted main port.

Required PKI Components

You need the following PKI (Public Key Infrastructure) components to implement a Secure Binary Interface.

• A CRT (short for certificate) file containing the server's PKI certificate. This file must be shared with the clients that connect using encrypted communications. Ideally, this file is signed by a recognized certificate issuing agency.

• A key file containing the server's private key. Keep this file secret and secure.

• A Java TrustStore containing the server's PKI certificate. The password for the trust store is also required.

Although in this instance the trust store contains only information that can be shared, the Java TrustStore program requires it to be password protected.

• A Java KeyStore and password.

• In a distributed system, add the configuration parameters to the heavyai.conf file on the aggregator and all leaf nodes in your HeavyDB cluster.

Demonstration Script to Create "Mock/Test" PKI Components

You can use OpenSSL utilities to create the various PKI elements. The server certificate in this instance is self-signing, and should not be used in a production system.

1. Generate a new private key.

   openssl genrsa -out server.key 2048

2. Use the private key to generate a certificate signing request.

   openssl req -new -key server.key -out server.csr

3. Self sign the certificate signing request to create a public certificate.

   openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

4. Use the Java tools to create a key store from the public certificate.

   keytool -importcert  -file server.crt -keystore server.jks

To generate a keystore file from your server key:

1. Copy server.key to server.txt. Concatenate it with server.crt.

   cp server.key server.txt
   cat server.crt >> server.txt

2. Use server.txt to create a PKCS12 file.

   openssl pkcs12 -export -in server.txt -out server.p12

3. Use server.p12 to create a keystore.

   keytool -importkeystore -v -srckeystore server.p12  -srcstoretype PKCS12 -destkeystore keystore.jks -deststoretype pkcs12

Start the Server in Encrypted Mode with PKI Client Authentication

Start the server using the following options.

--pki-db-client-auth true
--ssl-cert 
--ssl-private-key 
--ssl-trust-store 
--ssl-trust-password 
--ssl-keystore 
--ssl-keystore-password 
--ssl-trust-ca 
--ssl-trust-ca-server 

Example

sudo start heavyai_server --port 6274 --data /data --pki-db-client-auth true  
--ssl-cert /tls_certs/self_signed_server.example.com_self_signed/self_signed_server.example.com.pem 
--ssl-private-key /tls_certs/self_signed_server.example.com_self_signed/private/self_signed_server.example.com_key.pem 
--ssl-trust-store /tls_certs/self_signed_server.example.com_self_signed/trust_store_self_signed_server.example.com.jks 
--ssl-trust-password truststore_password 
--sslkeystore /tls_certs/self_signed_server.example.com_self_signed/key_store_self_signed_server.example.com.jks
--ssl-keystore-password keystore_password 
--ssl-trust-ca = "/tls_certs/self_signed_server.example.com_self_signed/self_signed_server.example.com.pem" 
--ssl-trust-ca-server /tls_certs/ca_primary/ca_primary_cert.pem

Configuring heavyai.conf for Encrypted Connection

Alternatively, you can add the following configuration parameters to heavyai.conf to establish a Secure Binary Interface. The following configuration flags implement the same encryption shown in the runtime example above:

# Start pki authentication 
pki-db-client-auth = true 
ssl-cert = "/tls_certs/self_signed_server.example.com_self_signed/self_signed_server.example.com.pem" 
ssl-private-key = "/tls_certs/self_signed_server.example.com_self_signed/private/self_signed_server.example.com_key.pem" 
ssl-trust-store = "/tls_certs/self_signed_server.example.com_self_signed/trust_store_self_signed_server.example.com.jks" 
ssl-trust-password = "truststore_password"  
ssl-keystore = "/tls_certs/self_signed_server.example.com_self_signed/key_store_self_signed_server.example.com.jks" 
ssl-keystore-password = "keystore_password" 
ssl-trust-ca = "/tls_certs/self_signed_server.example.com_self_signed/self_signed_server.example.com.pem" 
ssl-trust-ca-server = "/tls_certs/ca_primary/ca_primary_cert.pem" 

Passwords for the SSL truststore and keystore can be enclosed in single (') or double (") quotes.

Why Use Both server.crt and a Java TrustStore?

The server.crt file and the Java truststore contain the same public key information in different formats. Both are required by the server to establish both the secure client communication with the various interfaces and with its Calcite server. At startup, the Java truststore is passed to the Calcite server for authentication and to encrypt its traffic with the HEAVY.AI server.