Configuring SSL/TLS Secure Connections

This topic describes how to configure SSL/TLS on your cluster to support secure JDBC connections to your Splice Machine database.

   Learn more

About Encrypted Connections

By default, JDBC connections to your database are not encrypted. You can configure SSL/TLS authentication for two different encryption modes:

  • Basic SSL/TLS Encryption encrypts the data sent back and forth between a client and the server.

  • SSL/TLS Encryption with Peer Authentication encrypts the data sent between client and server, and adds a layer of authentication known as peer authentication, which uses trusted certificates to authenticate the sender and/or receiver.

    The term peer is used in this context to refer to the other side of a server-client communication: the client is the server’s peer, and the server is the client’s peer.You can set up peer authentication on a server, a client, or both.

The remainder of this topic shows you how to configure this authentication, in these sections:

We use highlighted text in this section to display sample names that you should replace with your own names.

Generating Certificates

This section shows you how to generate the required, trusted certificates on your server and client(s).

To configure your database for SSL/TLS authentication, you’ll need to use the keytool application that is included with the JDK; this tool is documented here: http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html.

Generate a Server Certificate

Use the keytool to generate a key-pair in the keystore. Here’s an example of interacting with the keytool:

% keytool -genkey -alias MyServerName -keystore ~/vault/ServerKeyStore
Enter keystore password: myPassword
Re-enter new password: myPassword
What is your first and last name?
   [Unknown]: John Doe
What is the name of your organizational unit?
   [Unknown]: TechPubs
What is the name of your organization?
   [Unknown]: MyCompany
What is the name of your City or Locality?
   [Unknown]: San Francisco
What is the name of your State or Province?
   [Unknown]: CA
What is the two-letter country code for this unit?
   [Unknown]: US
IS CN=John Doe, OU=TechPubs, O=MyCompany, L=San Francisco, ST=CA, C=US correct?
   [no]: yes

Enter key password for <MyServerName>
	    (RETURN if same as keystore password): myPassword

Now issue this keytool command to generate the certificate from the key you just created:

% keytool -export -alias MyServerName \
> -keystore ~/value/ServerKeyStore -rfc -file ServerCertificate \
> -storepass myPassword
Certificate stored in file <ServerCertificate>
% ls -ltr
total 8
-rw-rw-r-- 1 myName myGroup 1295 Aug 3 23:15 ServerKeyStore
-rw-rw-r-- 1 myName myGroup 1181 Aug 3 23:23 ServerCertificate
%

Generate Client Certificates

Now use the keytool to generate a client key-pair in the keystore; for example:

% keytool -genkey -alias MyClientName -keystore ~/vault/ClientKeyStore

Respond to the questions in the same way as you did when generting the server key-pair.

And then generate the client certificate:

% keytool -export -alias MyClientName \
> -keystore ~/value/ClientKeyStore -rfc -file ClientCertificate \
> -storepass myPassword
Certificate stored in file <ClientCertificate>
% ls -ltr
total 8
-rw-rw-r-- 1 myName myGroup 1295 Aug 3 23:15 ClientKeyStore
-rw-rw-r-- 1 myName myGroup 1181 Aug 3 23:23 ClientCertificate
%

Importing Certificates

After you’ve generated your certificates, it’s time to:

Import Server Certificate to Client Keystore

You need to copy (scp) the server certificate to the client, and then use a keytool command like this to import the certificate:

% keytool -import -alias favoriteServerCertificate \
 -file ServerCertificate -keystore ~/vault/ClientTrustStore \
 -storepass secretClientTrustStorePassword
Owner: CN=John Doe, OU=TechPubs, O=MyCompany, L=San Francisco, ST=CA, C=US
Issuer: CN=John Doe, OU=TechPubs, O=MyCompany, L=San Francisco, ST=CA, C=US
Serial number: 24a2c7f7
Valid from: Thu Aug 03 23:15:52 UTC 2017 until: Wed Nov 01 23:15:52 UTC 2017
Certificate fingerprints:
	 MD5:  5B:86:E9:C9:DF:E1:34:41:C8:B0:55:DE:C6:34:8A:21
	 SHA1: 17:C8:43:FE:9C:FF:0C:4A:B2:51:36:0C:79:16:EB:73:24:C3:5A:83
	 SHA256: 8D:55:1A:10:37:39:21:14:8E:21:3A:10:78:A1:C7:25:5F:9C:A7:8D:4E:3F:87:40:A0:ED:70:BE:EC:0F:7A:D9
	 Signature algorithm name: SHA1withDSA
	 Version: 3

Extensions:

#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 8B 71 1E 04 E7 E4 84 E6   35 B3 6B EB B5 92 1A 35  .q......5.k....5
0010: 5E FD B1 40                                        ^..@
]
]

Import Client Certificates to Server Keystore

Next, copy (scp) the client certificate to the region server and use keytool to import the certificate:

% keytool -import -alias Client_1_Certificate \
 -file ClientCertificate -keystore ~/vault/ServerTrustStore \
 -storepass secretServerTrustStorePassword
Owner: CN=John Doe, OU=TechPubs, O=MyCompany, L=San Francisco, ST=CA, C=US
Issuer: CN=John Doe, OU=TechPubs, O=MyCompany, L=San Francisco, ST=CA, C=US
Serial number: 7507d351
Valid from: Thu Aug 03 23:25:19 UTC 2017 until: Wed Nov 01 23:25:19 UTC 2017
Certificate fingerprints:
	 MD5:  19:46:4C:D5:6C:A5:40:AC:6C:F6:2C:DC:7B:86:C5:45
	 SHA1: BB:D7:9C:5E:5A:EB:E3:D1:F0:22:49:47:D4:C5:31:24:1E:06:0F:AE
	 SHA256: 88:8E:6E:97:ED:78:B1:AE:5E:65:09:30:C2:E8:AF:B3:DD:40:5A:7B:19:97:ED:04:E0:A3:82:66:E9:A4:3E:2A
	 Signature algorithm name: SHA1withDSA
	 Version: 3

Extensions:

#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 59 37 E4 92 34 0A A2 45   93 E6 45 3A AF 57 77 E8  Y7..4..E..E:.Ww.
0010: E6 B9 24 08                                        ..$.
]
]

Trust this certificate? [no]:  yes
Certificate was added to keystore
%

Secure and Deploy the Keystore and Trust Store

Once you’ve imported your certificates, you should copy the vault directory to a location that is directly accessible from HBase. We recommend copying it to a directory such as /etc/vault or /hbase/vault.

You MUST deploy the vault directory to the same location on each region server, so that all region servers can access it during server startup.

Updating Configuration Options

Now that you’ve got your certificates all set up, you need to modify a few configuration options and restart the server to take your new security options live. On a CDH cluster, you need to update the region server Java options, which you’ll find in the Admin console:

CDH->HBase->Configuration->Java Configuration Options for HBase Region Server
  • If you’re using basic SSL/TLS (without peer authentication), add this property:

    -Dderby.drda.sslMode=basic
    -Djavax.net.ssl.keyStore=/tmp/vault/ServerKeyStore
    -Djavax.net.ssl.keyStorePassword=myPassword
    -Djavax.net.ssl.trustStore=/tmp/vault/ServerTrustStore
    -Djavax.net.ssl.trustStorePassword=secretServerTrustStorePassword
    
  • If you’re using full SSL/TLS (with peer authentication), add these properties:

    -Dderby.drda.sslMode=peerAuthentication
    -Djavax.net.ssl.keyStore=/tmp/vault/ServerKeyStore
    -Djavax.net.ssl.keyStorePassword=myPassword
    -Djavax.net.ssl.trustStore=/tmp/vault/ServerTrustStore
    -Djavax.net.ssl.trustStorePassword=secretServerTrustStorePassword
    

Rebooting Your Cluster

Once you’ve updated your configuration, restart HBase to make the changes effective in your cluster. After HBase restart, you can verify that the server started in secure mode by examining the logs: If you look at /var/log/hbase/splice.log, you should see a message similar to this:

Mon AUG 28 04:52:03 UTC 2017 : Splice Machine Network Server - 10.9.2.2 - (1) started and ready to accept SSL connections on port 1527

Connecting Securely From a Client

You can now connect securely to your database. This section provides several examples:

Running the splice> Command Line Securely

To run the splice> command line securely, you need to export several env variables before starting sqlshell. You can then issue a connect command that specifies the type of security, as shown below.

First export the environmental variables that specify your key stores:

export CLIENT_SSL_KEYSTORE=/home/splice/vault/ClientKeyStore
export CLIENT_SSL_KEYSTOREPASSWD=myPassword
export CLIENT_SSL_TRUSTSTORE=/home/splice/vault/ClientTrustStore
export CLIENT_SSL_TRUSTSTOREPASSWD=secretClientTrustStorePassword

Then, start the splice> command line:

% ./sqlshell.sh

The sqlshell command issues a default (no security) connection command. To connect securely, add an ssl= option to the connect command. You use different connect commands for each of the three security modes:

Security Mode Connect Command
None
connect 'jdbc:splice://x.x.x.xxx:1527/splicedb;user=YourUserId;password=YourPassword';
Basic SSL
connect 'jdbc:splice://x.x.x.xxx:1527/splicedb;user=YourUserId;password=YourPassword;ssl=basic';
SSL w/Peer Authentication
connect 'jdbc:splice://x.x.x.xxx:1527/splicedb;user=YourUserId;password=YourPassword;ssl=peerAuthentication';

Running a JDBC Client App Securely

To use a secured connection with a JDBC client app, you need to specify a connection string that includes the ssl option. If you don’t specify this option, the default JDBC connection is unsecured, as shown in the Connect Command table in the previous section.

Here’s a sample declaration for a peer authenticated connection to a Splice Machine database:

String dbUrl = "jdbc:splice://1.2.3.456:1527/splicedb;user=YourUserId;password=YourPassword;ssl=peerAuthentication";

We can create a Java program that includes that declaration and then compile it into SampleJDBC.java with a command like this:

+ javac -classpath ".:./db-client-2.6.0.1729-SNAPSHOT.jar" ./SampleJDBC.java

We can then use a command like this to execute and JDBC app with the correct SSL keystore and truststore properties:

% java -classpath .:./db-client-2.6.0.1729-SNAPSHOT.jar
-Djavax.net.ssl.keyStore=/home/splice/vault/ClientKeyStore
-Djavax.net.ssl.keyStorePassword=myPassword
-Djavax.net.ssl.trustStore=/home/splice/vault/ClientTrustStore
-Djavax.netDjavax.net.ssl.trustStore.ssl.trustStorePassword=secretClientTrustStorePassword SampleJDBC

Adding New Client Nodes

Whenever you connect a new client node to a server, you need to perform a few steps to enable SSL/TLS on the new node:

Finally, you need to set these env variables:

export CLIENT_SSL_KEYSTORE=/home/splice/vault/ClientKeyStore
export CLIENT_SSL_KEYSTOREPASSWD=myPassword
export CLIENT_SSL_TRUSTSTORE=/home/splice/vault/ClientTrustStore
export CLIENT_SSL_TRUSTSTOREPASSWD=secretClientTrustStorePassword

Connecting Securely From a Third Party Client

This section describes what you need to do to connect securely to your Splice Machine from a third party client. We use Zeppelin as an example; other clients will have similar requirements. For Zeppelin, follow these steps

  1. Navigate to and edit the bin/interpreter.sh file in the Zeppelin installation directory.

  2. Find the JAVA_INTP_OPTS property definition.

  3. Append the following SSL properties onto that definition:

    JAVA_INTP_OPTS+="
    -Dzeppelin.log.file=${ZEPPELIN_LOGFILE} \
    -Djavax.net.ssl.keyStore=${CLIENT_SSL_KEYSTORE} \
    -Djavax.net.ssl.keyStorePassword=${CLIENT_SSL_KEYSTOREPASSWD} \
    -Djavax.net.ssl.trustStore=${CLIENT_SSL_TRUSTSTORE} \
    -Djavax.netDjavax.net.ssl.trustStore.ssl.trustStorePassword=${CLIENT_SSL_TRUSTSTOREPASSWD} "
    
  4. Make sure that you have exported the SSL keystore and truststore env variables:

    export CLIENT_SSL_KEYSTORE=/home/splice/vault/ClientKeyStore
    export CLIENT_SSL_KEYSTOREPASSWD=myPassword
    export CLIENT_SSL_TRUSTSTORE=/home/splice/vault/ClientTrustStore
    export CLIENT_SSL_TRUSTSTOREPASSWD=secretClientTrustStorePassword
    
  5. Restart Zeppelin:

    % zeppelin-daemon.sh start
    
  6. Create a new JDBC Interpreter

    Navigate to the Zeppelin interface URL:, then click Interpreter->+Create to create a new interpreter. The image below shows sample settings for the new interpreter:

    Be sure to provide the correct JDBC driver loaction in the artifact dependencies section.

  7. Save the new interpreter.
  8. Create a new Note with the new interpreter.