Configuring JDBC over SSL with own Certificates

Default SSL Settings

By the default configuration, the CData Virtuality Server provides a certificate-free SSL connection via port 31001. The SSL suite TLS_DH_anon_WITH_AES_128_CBC_SHA will be used in this scenario. However, CData Virtuality Server can be configured to use a custom certificate with some additional changes to the security settings. 

If you implement the usage of your own certificate, you also need to configure the Studio to accept this certificate with the means of a truststore. If you want to implement 2-way authentication, you must also deploy a client certificate at the client machine and a truststore, which accepts the client certificate, at the server.

Configure the Server to Use a Certificate

1a) New Self-Signed Certificate

Please skip this part and continue with step 1b) if you already possess a certificate. Otherwise, the following three steps will create a keystore with an encryption key, a certificate and a truststore that has the certificate listed as trusted. 

The following commands will generate a certificate and the corresponding public/private keys in keystore and truststore files. The names for the keystores, certificates and truststores are suggestions, and we recommend including the server's name and the client's name in the file names when you have several servers or clients you want to equip with a certificate. Both subsections contain commands to create valid keys for 356 days, and you can also define another validity period. 

1-Way Authentication

Perform the following steps in an elevated command prompt. Where applicable, provide the necessary details within the interactive commands. 

keytool -genkey -alias dv_server -keyalg RSA -validity 365 -keystore dv_jdbc_server.keystore -storetype JKS
keytool -export -alias dv_server -keystore dv_jdbc_server.keystore -rfc -file dv_server_public.cert
keytool -import -alias dv_server -file dv_server_public.cert -storetype JKS -keystore dv_jdbc_server.truststore

Note that each server uses exactly one keystore, and each client uses exactly one truststore. If you have multiple servers deployed, you need one truststore containing the public keys of all servers' certificates. To do this, execute the command from c) once for each server certificate with always the same server truststore file as a destination. 

2-Way Authentication

Perform the following steps in an elevated command prompt. Where applicable, provide the necessary details within the interactive commands.

# Make sure that the key password is the same as the keystore password when entering the details
keytool -genkey -alias dv_server -keyalg RSA -validity 365 -keystore dv_jdbc_server.keystore -storetype JKS
keytool -export -alias dv_server -keystore dv_jdbc_server.keystore -rfc -file dv_server_public.cert
# Make sure that the key password is the same as the keystore password when entering the details
keytool -genkey -alias dv_client -keyalg RSA -validity 365 -keystore dv_jdbc_client.keystore -storetype JKS
keytool -export -alias dv_client -keystore dv_jdbc_client.keystore -rfc -file dv_client_public.cert
keytool -import -alias dv_server -file dv_server_public.cert -storetype JKS -keystore dv_jdbc_server.truststore
keytool -import -alias dv_client -file dv_client_public.cert -storetype JKS -keystore dv_jdbc_client.truststore

Note that each server uses exactly one keystore and each client uses exactly one truststore. If you have multiple servers deployed, you need one truststore that contains the public keys of all servers' certificates. To do this, execute the command from e) once for each server certificate with always the same server truststore file as a destination.

If you have multiple clients deployed, you need one truststore that contains the public keys of all clients' certificates. To do this, execute the command from step f) once for each client certificate with always the same client truststore file as a destination.

1b) Existing Certificate

If you created a new self-signed certificate in step 1a) then please skip this part and proceed with step 2.

1-Way Authentication

Perform the following steps in an elevated command prompt. Where applicable, provide the necessary details within the interactive commands. 

# Make sure that the keystore password is the same as the certificate's key password
keytool -import -alias dv_server -file %pathToCertificateFile% -keystore dv_jdbc_server.keystore -storetype JKS
keytool -export -alias dv_server -keystore dv_jdbc_server.keystore -rfc -file dv_server_public.cert
keytool -import -alias dv_server -file dv_server_public.cert -storetype JKS -keystore dv_jdbc_server.truststore

Note that each server uses exactly one keystore and each client uses exactly one truststore. If you have multiple servers deployed, you need one truststore that contains the public keys of all servers' certificates. In order to do this, you execute the command from c) once for each server certificate with always the same server truststore file as a destination. 

2-Way Authentication

Perform the following steps in an elevated command prompt. Where applicable, provide the necessary details within the interactive commands. 

# Make sure that the keystore password is the same as the certificate's key password
keytool -import -alias dv_server -file %pathToServerCertificateFile% -keystore dv_jdbc_server.keystore -storetype JKS
keytool -export -alias dv_server -keystore dv_jdbc_server.keystore -rfc -file dv_server_public.cert
# Make sure that the keystore password is the same as the certificate's key password
keytool -import -alias dv_server -file %pathToClientCertificateFile% -keystore dv_jdbc_client.keystore -storetype JKS
keytool -export -alias dv_client -keystore dv_jdbc_client.keystore -rfc -file dv_client_public.cert
keytool -import -alias dv_server -file dv_server_public.cert -storetype JKS -keystore dv_jdbc_server.truststore
keytool -import -alias dv_client -file dv_client_public.cert -storetype JKS -keystore dv_jdbc_client.truststore

Note that each server uses exactly one keystore and each client uses exactly one truststore. If you have multiple servers deployed, you need one truststore that contains the public keys of all servers' certificates. In order to do this, you execute the command from e) once for each server certificate with always the same server truststore file as a destination.

If you have multiple clients deployed, you need one truststore that contains the public keys of all clients' certificates. In order to do this, you execute the command from f) once for each client certificate with always the same client truststore file as a destination.

2) Place the Files in the Server Location

1-Way Authentication

• Place the dv_jdbc_server.keystore file in the %dvDir%/standalone/configuration folder. If you have multiple servers, you have to do this for every server and each time with the corresponding keystore file. 

2-Way Authentication

• Place the dv_jdbc_server.keystore file in the %dvDir%/standalone/configuration folder. If you have multiple servers, you have to do this for every server and each time with the corresponding keystore file;
• Place the dv_jdbc_client.truststore file in the %dvDir%/standalone/configuration folder. If you have multiple servers, you have to do this for every server and each time with the same truststore file. Remember that the truststore has to contain the public keys of all client certificates you have in use for your CData Virtuality environment.

3) Configure the SSL Settings

1-Way Authentication

Modify the %dvDir%/standalone/configuration/dvserver-standalone.xml file as follows. Replace the XML part:

<transport name="jdbc-ssl" socket-binding="dv-jdbc-ssl" protocol="teiid">
	<authentication security-domain="dv-security"/>
	<ssl mode="enabled" authentication-mode="anonymous" ssl-protocol="SSLv3"/>
</transport>

With the new one:

<transport name="jdbc-ssl" socket-binding="dv-jdbc-ssl" protocol="teiid">
	<authentication security-domain="dv-security"/>
	<ssl mode="enabled" ssl-protocol="SSLv3" keymanagement-algorithm="SunX509">
		<keystore name="../standalone/configuration/dv_jdbc_server.keystore" password="serverKeystorePw"/>
	</ssl>
</transport>

 Replace the file names and passwords according to your setup.

2-Way Authentication

Modify the %dvDir%/standalone/configuration/dvserver-standalone.xml file as follows. Replace the XML part

<transport name="jdbc-ssl" socket-binding="dv-jdbc-ssl" protocol="teiid">
	<authentication security-domain="dv-security"/>
	<ssl mode="enabled" authentication-mode="anonymous" ssl-protocol="SSLv3"/>
</transport>

With the new one:

<transport name="jdbc-ssl" socket-binding="dv-jdbc-ssl" protocol="teiid">
	<authentication security-domain="dv-security"/>
	<ssl mode="enabled" ssl-protocol="SSLv3" keymanagement-algorithm="SunX509">
		<keystore name="../standalone/configuration/dv_jdbc_server.keystore" password="serverKeystorePw"/>
		<truststore name="../standalone/configuration/dv_jdbc_client.truststore" password="clientTruststorePw"/>
	</ssl>
</transport>

Replace the file names and passwords according to your setup.

Overview of All Properties

The configurable properties are as follows:

Configuring the Studio to Accept the Certificate

1) Place the files in the Studio's Location

1-Way Authentication

• Place the dv_jdbc_server.truststore file in the direct folder of the CData Virtuality Studio - the same location where the dvstudio.ini file is located. If you have multiple clients, you have to do this for every server, and each time with the same truststore file. Remember that the truststore has to contain the public keys of all server certificates you have in use for your CData Virtuality environment.

2-Way Authentication

• Place the dv_jdbc_server.truststore file in the direct folder of CData Virtuality Studio - the same location where the dvstudio.ini file is located. If you have multiple clients, you have to do this for every server and each time with the same truststore file. Remember that the truststore has to contain the public keys of all server certificates you have in use for your CData Virtuality environment.
• Place the dv_jdbc_client.keystore file in the direct folder of CData Virtuality Studio - the same location where the dvstudio.ini file is located. If you have multiple clients, you have to do this for every client and each time with the corresponding keystore file.

2) Configure CData Virtuality Studio

1-Way Authentication

Add the following lines at the bottom of the %dvStudioDir%/dvstudio.ini file and replace the file names and passwords according to your setup:

-Djavax.net.ssl.trustStore=dv_jdbc_server.truststore
-Djavax.net.ssl.trustStorePassword=serverTruststorePw
-Djavax.net.ssl.keyStoreType=JKS

2-Way Authentication

Add the following lines at the bottom of the %dvStudioDir%/dvstudio.ini file and replace the file names and passwords according to your setup:

-Djavax.net.ssl.keyStore=dv_jdbc_client.keystore
-Djavax.net.ssl.keyStorePassword=clientKeyStorePw
-Djavax.net.ssl.trustStore=dv_jdbc_server.truststore
-Djavax.net.ssl.trustStorePassword=serverTruststorePw
-Djavax.net.ssl.keyStroreType=JKS

Studio Shows 'Remote host closed during handshake'

• Check the server's configuration for the keystore;
• Check that the file is accessible and correctly spelt in the dvserver-standalone.xml file;
• Check that the correct keystore password is used in the dvserver-standalone.xml file;
• Check the server.log file for more details. 

The trustAnchors parameter must be non-empty

This error means that truststore file cannot be opened. Here is what to check:

• Check its spelling and the access permissions;
• If 1-way authentication is used, check the configuration of the Studio file;
• For 2-way authentication, check the server's configuration as well. 

java.security.NoSuchAlgorithmException: TSLv1 SSLContext not available

• Make sure that the used certificates all support the security type;
• Alternatively, try SSLv3 as a value for the ssl-protocol setting. 

PKIX path building failed: ...unable to find valid certification path to requested target

• Check that the involved truststores between the server and the client are accessible and configured;
• If 1-way authentication is used, check the Studio's settings;
• For 2-way authentication, check the server's configuration as well.