Connecting 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 AdminAn interface for domain and database management. Introduced in NuoDB 4.0 to supersede NuoAgent, this interface is used to manage an admin domain. Use NuoDB Admin instead of NuoAgent to start and stop APs. When using NuoDB Admin to manage a domain and its databases, use NuoDB Command (nuocmd) instead of the NuoDB Manager (nuodbmgr) Command Line Interface (CLI) tool. See also Admin Process (AP). and for database processes, see Enabling 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 SQLNuoDB SQL (nuosql) is a command line tool for exploring NuoDB databases. It enables you to execute SQL statements interactively, run batch scripts, access database metadata information, and perform DBA functions.. 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 7,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 Enabling 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>.
Note: 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.
Note: 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.