Configuring TLS for JDBC Clients

To configure TLS for JDBC clients:

  • Set the keystore and truststore properties.
  • Set the TLSmode parameter.
  • (Optional) Run the SSL debug utility to test your configuration.

Setting Keystore/Truststore properties

You can set the keystore and truststore properties in the following ways, each with their own pros and cons:

  • At the driver level.
  • At the JVM level.

Driver-level Configuration

If you use tools like DbVizualizer with many connections, configure the keystore and truststore with the JDBC connection properties. This does, however, expose these values in the connection string:

  • KeyStorePath
  • KeyStorePassword
  • TrustStorePath
  • TrustStorePassword

For example:

Properties props = new Properties();
props.setProperty("KeyStorePath", keystorepath);
props.setProperty("KeyStorePassword", keystorepassword);
props.setProperty("TrustStorePath", truststorepath);
props.setProperty("TrustStorePassword", truststorepassword);

JVM-level Configuration

Setting keystore and truststore parameters at the JVM level excludes them from the connection string, which may be more accommodating for environments with more stringent security requirements:

  • javax.net.ssl.keyStore
  • javax.net.ssl.trustStore
  • javax.net.ssl.keyStorePassword
  • javax.net.ssl.trustStorePassword

For example:

System.setProperty("javax.net.ssl.keyStore","clientKeyStore.key");
System.setProperty("javax.net.ssl.trustStore","clientTrustStore.key");
System.setProperty("javax.net.ssl.keyStorePassword","new_keystore_password")
System.setProperty("javax.net.ssl.trustStorePassword","new_truststore_password");

Set the TLSmode Connection Property

You can set the TLSmode connection property to determine how certificates are handled. TLSmode is disabled by default.

TLSmode identifies the security level that Vertica applies to the JDBC connection. Vertica must be configured to handle TLS connections before you can establish an encrypted connection to it. See TLS Protocol for details. Valid values are:

  • disable: JDBC connects using plain text and implements no security measures.
  • require: JDBC connects using TLS without verifying the CA certificate.
  • verify-ca: JDBC connects using TLS and confirms that the server certificate has been signed by the certificate authority. This setting is equivalent to the deprecated ssl=true property.
  • verify-full: JDBC connects using TLS, confirms that the server certificate has been signed by the certificate authority, and verifies that the host name matches the name provided in the server certificate.

If this property and the SSL property are set, this property takes precedence.

For example, to configure JDBC to connect to the server with TLS without verifying the CA certificate, you can set the TLSmode property to 'require' with the method VerticaConnection.setProperty():

Properties props = new Properties();
props.setProperty("TLSmode", "verify-full");

Run the SSL Debug Utility

After configuring TLS, you can run the following for a debugging utility:

$ java -Djavax.net.debug=ssl

You can use several debug specifiers (options) with the debug utility. The specifiers help narrow the scope of the debugging information that is returned. For example, you could specify one of the options that prints handshake messages or session activity.

For information on the debug utility and its options, see Debugging Utilities in the Oracle document, JSSE Reference Guide.

For information on interpreting debug information, refer to the Oracle document, Debugging SSL/TLS Connections.