Connect to a database Using TLS and LDAP

This section describes how to connect to a NuoDB database using TLS encryption. For information on enabling TLS for NuoDB Admin and for database processes, see Configuring NuoDB Admin TLS Encryption.

To verify that database processes are using TLS, review the log messages in nuoadmin.log to confirm that an entry for TLS Support ENABLED exists.

...
2019-04-18T12:56:29.608-0400 [6486] (test node -1) Starting Storage Manager 4.0: database=test, protocol=1.1310720.5221d76ca2 (4.0)
2019-04-18T12:56:29.608-0400 [6486] (test node -1) Configuration parameters: --archive <archive> --debug --database test --initialize --node-port 48006 --agent-port 48004 --read-stdin
2019-04-18T12:56:29.608-0400 [6486] (test node -1) TLS Support ENABLED:
  Domain CAs:
    Certificate #0 CN nuocmd: expires Feb 24 02:03:23 2119 GMT
    Certificate #1 CN nuoadmin: expires Feb 24 02:03:22 2119 GMT
  Intermediate Certificates:
  Engine Certificate:
    Certificate #2 CN nuoadmin: expires Feb 24 02:03:22 2119 GMT
...

SRP fallback

By default all NuoDB processes support TLS with SRP fallback. This makes it possible to upgrade from a SRP-secured cluster to a TLS-secured cluster without downtime. To disable SRP fallback, use the cipher-suites database option as follows:

nuocmd start process ... --options cipher-suites TLS

The default value for cipher-suites is TLS,LEGACY-SRP. For more information on using cipher-suites, see Database Options.

For more information on SRP security, see Network Encryption.

Using TLS for SQL Driver connections

NuoDB supports TLS encryption for NuoDB’s C, C++, JDBC, and Python client drivers as well as NuoDB SQL. No other NuoDB drivers support TLS encryption.

For information on using NuoDB drivers, see Client Development.

Driver Requirements

Driver Requirement

C, C++

None.

JDBC

Bouncy Castle; Java 8 or 11.

Python

Python compiled with native openSSL and available SSL libraries.

Not all of the drivers listed here support the same settings, but the following connection properties are common to all.

Property Default Description

trustStore (+password)

N/A

The location of a trust store on disk. For the types of supported trust store formats see the next table. Must be readable by the driver process. Must contain valid certificates that can be used to validate both the admin and TE certificate chains.

verifyHostname

true

Validate that the DN in the certificate matches the hostname. Can be disabled for deployments without a stable DNS name.

allowSRPFallback

false

If trustStore has note been specified, all NuoDB drivers will default to SRP. If any of these options is provided NuoDB will default to using TLS. If both modes are required at the same time (such as rolling upgrade with a rolling change of the security protocol), set this property to true. If TLS fails, the driver will attempt to use SRP+AES256. If required, SRP fallback must be enabled on the server as well. For more information, see SRP fallback.

Supported Trust Store Formats

Driver Trust Store Formats

C, C++

PEM file or directory containing PEM files.

JDBC

PKCS12, JKS or the format specifed in <JAVA_HOME>/lib/security/java.security.

Python

Single PEM file containing one or multiple certificates.

Examples

The following examples use certificate files created for a Unique Admin Key trust model. For more information on generating certificates for both the Unique Admin Key trust model and the Shared Admin Key trust model, see Configuring NuoDB Admin TLS Encryption.

Example 1: Creating a TLS connection for the Python driver.
options = {"schema": "test",
           'trustStore': "<NUODB_HOME>/var/etc/nuoadmin.cert",
           'verifyHostname': false,
           }

connect_kw_args = {'database': "test", 'host': "localhost", 'user': "dba", 'password': "dba",'options': options}

connection = pynuodb.connect(**connect_kw_args)
Example 2: Creating a TLS Connection for the C++ driver.
connection = Connection::create(
                    dbName,
                    "dba",
                    "goalie",
                    2,
                    "schema", "hello",
                    "trustStore", "<NUODB_HOME>/var/etc/nuoadmin.cert"
                    );
}
Example 3: Creating a TLS Connection for the JDBC driver.

Using Driver Connection

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

Properties properties = new Properties();
    properties.put("user", user);
    properties.put("password", password);
    properties.put("schema", "hello");
    properties.put("trustStore",
"<NUODB_HOME>/var/etc/nuoadmin-truststore.jks");
    properties.put("trustStorePassword", "changeIt");
    properties.put("verifyHostname", "false")
    properties.put("allowSRPFallback", "false")
    dbConnection = DriverManager.getConnection(DATABASE_URL, properties);

Using DataSource

public static final String DATABASE_URL =
    "jdbc:com.nuodb://localhost/" + dbName +
    "?trustStore=<NUODB_HOME>/var/etc/nuoadmin-truststore.jks" +
    "&trustStorePassword=changeIt" +
    "&allowSRPFallback=false" +
    "&verifyHostname=true";

Properties properties = new Properties();
    properties.put("user", user);
    properties.put("password", password);
    properties.put("schema", "hello");

dbConnection = DriverManager.getConnection(DATABASE_URL, properties);

Configuring LDAP

Use ldap-dn and ldap-pass to connect to the LDAP server, where the ldap-dn user must have search privileges on the ldap-base sub-tree. After connecting to the LDAP server, do the following:

1. Search the ldap-base subtree for a compatible user.
The first user that matches the username is matched.

2. Set ldap-type.
For Active Directory (Windows), select ldap-type windows.
For OpenLDAP derivatives (UNIX), select ldap-type unix.

3. Set ldap-uri to LDAP://<hostname>:<port> or LDAPS://<hostname>:<port>.

To configure LDAP for NuoDB, the Transaction Engines (TEs) and the driver both must use TLS. The settings for each TE are independent. There is no global LDAP configuration that can be changed at runtime, or that is automatically propagated throughout the cluster. If two TEs are configured differently, they will behave differently. If one TE is misconfigured, connections to that TE may fail.

When LDAP connections are being established, LDAP configuration is not checked when the TE is started. To verify that LDAP works correctly, you must log in with an LDAP user. In the event of failure, all (error) messages are logged to nuoadmin.log; all LDAP error messages are logged as WARNINGs in the SECURITY category.

NuoDB supports only LDAP authentication, it does not support authorization. In other words, all user rights need to be configured in NuoDB. Only the password checking is handled by an LDAP server. For more information, see User Authentication Using LDAP.

Configuring LDAPS

Setting up LDAPS is independent of the TLS configuration in the cluster or between the TE and a SQL driver.

When setting up an LDAP instance with SSL support (LDAPS), the LDAP server must present a certificate that is matched against the ldap-ca option provided to NuoDB. ldap-ca can either be the signing certificate authority or the certificate of the specific LDAP instance certificate. In most cases, the CA certificate will be used.

Additional LDAP configuration may be required to set up LDAPS correctly. This follows the standard configuration specification of the OS that the TE is running on and the LDAP server that is being used. On Linux, the usual content of the ldap.conf file is:

TLS_TRUSTED_CERTS <CERT_NAME>
TLS_REQCERT demand

For more information, see Linux online documentation pages using man ldap.conf.