TLS Connections with MariaDB Connector/J

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.

Create Users for TLS Connections

MariaDB Enterprise Server and MariaDB Community Server support TLS requirements for CREATE USERCREATE USER and GRANTGRANT 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 GRANTGRANT 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 GRANTGRANT 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();
        }
    }
}