TLS Connections with MariaDB Connector/J
This page is part of MariaDB's Documentation.
The parent of this page is: MariaDB Connector/J
Topics on this page:
Overview
Java developers can use MariaDB Connector/J to establish client connections over TLS to MariaDB database products.
TLS Connections
TLS (Transport Layer Security) is a data transfer protocol for ensuring secure communication between a client and a server over a public network using encrypted connections. It is the newer version of the Secure Socket Later (SSL) protocol.
MariaDB Connector/J can establish connections using TLS to ensure Data-in-Transit Encryption between your Java application and MariaDB database products.
User accounts on MariaDB Enterprise Server or MariaDB Community Server can be configured to required a TLS connection.
Related Connection Parameters
The following connection parameters are related to TLS:
Parameter Name | Description | Data Type | Default Value | Version Added | Version Removed |
---|---|---|---|---|---|
| Deprecated in 3.0.3. Use |
|
| 2.1.0 | |
| Forces the TLS protocol to only use the specified comma-separated list of TLS ciphers. |
| 1.5.0 | ||
| Forces the TLS protocol to only use the specified comma-separated list of TLS versions. |
| 1.5.0 | ||
|
| 1.5.3 | 3.0.3 | ||
| File path to the keyStore file that contains the private key store and associated certificates. This parameter is similar to the Java System property javax.net.ssl.keyStore, but ensures that only the private key entries are used. |
| 1.3.4 | ||
| Password for the client certificate keyStore. This parameter is similar to the Java System property javax.net.ssl.keyStorePassword. |
| 1.3.4 | ||
| Defines the keyStore type (JKS/PKCS12). |
| 2.4.0 | ||
| Defines the server certificate or the CA chain. It accepts:
|
| 1.1.3 | ||
| Enables SSL/TLS in a specific mode. The following values are supported:
This new option replaces the deprecated options:
|
|
| 3.0.3 | |
| Deprecated in 3.0.3. Use |
|
| 1.1.1 | |
|
| 1.3.4 | 3.0.3 | ||
|
| 1.3.4 | 3.0.3 | ||
|
|
| 2.4.0 | 3.0.3 | |
| Defines whether TLS is used for the connection. Deprecated in 3.0.3. Use |
|
| 1.1.0 |
Create Users for TLS Connections
MariaDB Enterprise Server and MariaDB Community Server support TLS requirements for
and statements. Requiring TLS enables you to restrict connections or specific operations to user accounts that connect over TLS.One-Way TLS
One-way TLS allows the client to verify the server certificate, but it does not allow the server to verify a client certificate. In one-way TLS, data is still encrypted in transit in both directions.
To enable one-way authentication using certificates grant user privileges with the REQUIRE SSL
clause included in the statement:
GRANT CREATE, ALTER, SELECT, INSERT, UPDATE, DELETE, DROP
ON test.contacts
TO 'db_user'@'192.0.2.1' REQUIRE SSL;
GRANT SELECT, INSERT, UPDATE, DELETE, DROP
ON test.accounts
TO 'db_user'@'192.0.2.1' REQUIRE SSL;
Two-Way TLS
Two-way TLS provides mutual authentication using certificates. Two-way TLS allows the client to verify the server certificate and allows the server to verify the client certificate.
To enable two-way, or mutual, authentication using certificates, grant user privileges with the REQUIRE X509
clause included in the statement:
GRANT CREATE, ALTER, SELECT, INSERT, UPDATE, DELETE, DROP
ON test.contacts
TO 'db_user'@'192.0.2.1' REQUIRE X509;
GRANT SELECT, INSERT, UPDATE, DELETE, DROP
ON test.accounts
TO 'db_user'@'192.0.2.1' REQUIRE X509;
Code Example: Connect with TLS
The following example program opens a single database connection using one-way TLS to a server at the IP address 192.0.2.1
using the user account created in the example setup. If your application requires multiple database connections instead, see Connection Pools for a more appropriate example.
Connector/J 3.x
In MariaDB Connector/J 3.x, TLS is enabled for connections using the sslMode
parameter.
import java.sql.*;
import java.util.Properties;
public class App {
public static void main(String[] argv) {
Properties connConfig = new Properties();
connConfig.setProperty("user", "db_user");
connConfig.setProperty("password", "db_user_password");
connConfig.setProperty("sslMode", "verify-full");
connConfig.setProperty("serverSslCert", "/path/to/ca_chain.pem");
try (Connection conn = DriverManager.getConnection("jdbc:mariadb://HOST:PORT", connConfig)) {
// Use Connection
// ...
} catch (Exception e) {
e.printStackTrace();
}
}
}
Connector/J 2.7
In MariaDB Connector/J 2.7 and before, TLS is enabled for connections using the useSsl
parameter.
import java.sql.*;
import java.util.Properties;
public class App {
public static void main(String[] argv) {
Properties connConfig = new Properties();
connConfig.setProperty("user", "db_user");
connConfig.setProperty("password", "db_user_password");
connConfig.setProperty("useSsl", "true");
connConfig.setProperty("serverSslCert", "/path/to/ca_chain.pem");
try (Connection conn = DriverManager.getConnection("jdbc:mariadb://HOST:PORT", connConfig)) {
// Use Connection
// ...
} catch (Exception e) {
e.printStackTrace();
}
}
}