Enabling TLS in the JDBC Driver

This page provides guidelines for enabling secure connections to NuoDB from Java applications. It should be noted that all client connections to NuoDB are always secure (using SRP by default). This section discusses using TLS instead.

For the JDBC driver to use TLS, the domain first needs to be set up for TLS. For more information, see Configuring NuoDB Admin TLS Encryption.

You must provide both the trustStore and trustStorePassword properties to the JDBC connection and, probably, disable hostname verification.

NuoDB’s JDBC driver only supports PKS12 and JKS format truststores (keys). PEM and other formats are not supported.
If you misspell the names of these connection properties, they will be ignored and an SRP connection will result.

About the key formats:

  • PKS12 format keys are probably the ones in use by your APs if you enabled TLS following the instructions in this section.

    • The file you need will typically be nuoadmin-truststore.p12. By default this file is in /etc/nuodb/keys on any AP server host.

  • JKS is an alternative format and nuocmd create key-pair can create JKS format keys if you prefer. Specify a file with a .jks suffix as the keystore or --storetype JKS.

  • You will probably need to get a DBA or system administrator to give you a copy of the truststore.

  • The trustStore property must specify either a path relative to the client application, or an absolute path accessible by the client.

  • Both formats are password protected, use the trustStorePassword property to provide the password.

  • nuoadmin-truststore.p12 only contains public keys so it is safe to share it with client applications.

Your certificate (ca.p12) is extremely important. It should never be stored on any machine in the NuoDB domain or on any application client machine, otherwise it could be used to sign fake keys. If compromised, the entire domain must be stopped and new keys generated immediately, forcing downtime. NuoDB strongly recommend keeping it in a secure location.

By default, the JDBC driver is set up to match the DN name in the trust-store certificate against the application client hostname. This will typically fail.

  • To disable hostname verification, add the verifyHostname=false connection property.

  • You can find the hostname using keytool, for example:

    keytool -list -v -keystore C:\Work\nuodb-keys\nuoadmin-truststore.jks -storepass changeIt -storetype PKCS12 | grep -i owner
    Owner: CN=ca.nuodb.com, OU=Eng, O=NuoDB, L=Boston, ST=MA, C=US

    • Windows users can use findstr -i if they don’t have grep.

For more information on specifying a truststore, see Connection Properties.

Our keys use a 256-bit cypher. Your Java application must use JDK 11.0.16 or later otherwise it will be unable to use the key. This is a known limitation of the JDK.

Forcing TLS

It is possible to ensure that all client connections use TLS.

  1. Add the connection property allowSRPFallback=false to the JDBC URL.

    • Note that this property is ignored unless trustStore is also specified.

  2. Starting the TEs with --options cipher-suites TLS ensures that only TLS connections are ever possible:

    • nuocmd start process --db-name test --engine-type TE ---options cipher-suites TLS --server-id XXX

  3. Or make this a default option when creating the database:

    • nuocmd create database --db-name test --default-options cipher-suites TLS …​

  4. If using Kubernetes, use the database-wide options in the database chart’s values YAML:

      ## database-wide options.
  # These are applied using the --database-options on the startup command
  # change these to values appropriate for this database
  # these options are applied to all processes in the database.
  options:
    ping-timeout: 60
    max-lost-archives: 0
    cipher-suites: TLS

    • In this example, max-lost-archives only applies to SMs and is ignored by TEs. Similarly, cipher-suites only applies to TEs.

Using a DataSource

public static final String DATABASE_URL = "jdbc:com.nuodb://localhost/test";

/* In keeping with similar Java examples, we use 'changeIt' for the truststore password. */
/* DO NOT use this password for your own keys and stores.                               */
com.nuodb.jdbc.DataSource dataSource = new com.nuodb.jdbc.DataSource();
dataSource.setUrl(DATABASE_URL + "?trustStore=/path/to/nuoadmin-truststore.p12&trustStorePassword=changeIt");
dataSource.setUser(user);
dataSource.setPassword(password);
dataSource.setDefaultSchema("Hockey");

dbConnection = dataSource.getConnection();

Using a DriverManager

The DriverManager supports using a connection Properties instance but is in general not preferred as it does not provide built-in connection pooling.

public static final String DATABASE_URL = "jdbc:com.nuodb://localhost/test";

/* In keeping with similar Java examples, we use 'changeIt' for the truststore password. */
/* DO NOT use this password for your own keys and stores.                               */
Properties properties = new Properties();
properties.put("user", user);
properties.put("password", password);
properties.put("schema", "Hockey");
properties.put("trustStore", "/path/to/nuoadmin-truststore.p12");
properties.put("trustStorePassword", "changeIt");

dbConnection = DriverManager.getConnection(DATABASE_URL, properties);