Updated on 2025-03-13 GMT+08:00

Connecting to a Database in SSL Mode

When establishing connections to the GaussDB server using JDBC, you can enable SSL connections to encrypt client and server communications for security of sensitive data transmission on the Internet. You can use the NonValidatingFactory channel or certificate authentication to connect to the database in SSL mode. In certificate-based authentication mode, a client and a server authenticate each other. In this section, the DriverManager.getConnection(String url, Properties info) API is used to connect to a database.

Method 1: NonValidatingFactory Channel

Prerequisites: You have obtained the certificates and private key file required by the server and configured the server.

For details about how to generate and obtain a certificate, contact an administrator. For details about how to configure the certificate on the server, contact an administrator.

The following uses opengaussjdbc.jar as an example to describe how to connect to a database through the NonValidatingFactory channel as follows:

  1. Import java.sql.Connection, java.sql.DriverManager, and java.util.Properties.

    In addition, you need to import other APIs and classes based on the actual application scenario. For details, see JDBC Interface Reference.
    import java.sql.Connection;
    import java.sql.DriverManager;
    import java.util.Properties;

  2. Specify the database sourceURL (change $ip, $port, and database as required), username, and password.

    Writing the username and password to code has great security risks. You are advised to store the username and password in environment variables.

    String sourceURL = "jdbc:opengauss://$ip:$port/database";
    Properties urlProps = new Properties();
    urlProps.setProperty("user", System.getenv("EXAMPLE_USERNAME_ENV"));
    urlProps.setProperty("password", System.getenv("EXAMPLE_PASSWORD_ENV"));

  3. Set the SSL attribute to true to use the NonValidatingFactory channel.

    urlProps.setProperty("ssl", "true");
    urlProps.setProperty("sslfactory","com.huawei.opengauss.jdbc.ssl.NonValidatingFactory");

  4. Load the driver.

    1. Add the opengaussjdbc.jar package to the code running tool (such as IDE).
    2. Load the database driver com.huawei.opengauss.jdbc.Driver as follows:
    Class.forName("com.huawei.opengauss.jdbc.Driver");

  5. Establish a database connection.

    Call DriverManager.getConnection(String url, Properties info) to connect to the database.
    Connection conn = DriverManager.getConnection(sourceURL,urlProps);

Method 2: Certificate-based Authentication

Prerequisites: You have obtained the certificates and private key file required by the server and configured the server. You have obtained the client.crt client certificate, cacert.pem root certificate, and client.key.pk8 client private key file required by the client. Step 3 describes how to configure the certificates and private key file on the client.

For details about how to generate and obtain a certificate, contact an administrator. For details about how to configure the certificate on the server, contact an administrator.

The following uses opengaussjdbc.jar as an example to describe how to configure certificates on the client to connect to a database as follows:

  1. Import java.sql.Connection, java.sql.DriverManager, and java.util.Properties.

    In addition, you need to import other APIs and classes based on the actual application scenario. For details, see JDBC Interface Reference.
    import java.sql.Connection;
    import java.sql.DriverManager;
    import java.util.Properties;

  2. Specify the database sourceURL (change $ip, $port, and database as required), username, and password.

    Writing the username and password to code has great security risks. You are advised to store the username and password in environment variables.

    String sourceURL = "jdbc:opengauss://$ip:$port/database";
    Properties urlProps = new Properties();
    urlProps.setProperty("user", System.getenv("EXAMPLE_USERNAME_ENV"));
    urlProps.setProperty("password", System.getenv("EXAMPLE_PASSWORD_ENV"));

  3. Set the SSL attribute to true and configure the client.crt client certificate, cacert.pem root certificate, and client.key.pk8 client private key on the client.

    urlProps.setProperty("ssl", "true");
    urlProps.setProperty("sslcert", "client.crt");
    urlProps.setProperty("sslrootcert", "cacert.pem");
    urlProps.setProperty("sslkey", "client.key.pk8");

    Before using the client private key file, convert client.key to client.key.pk8.

     * openssl pkcs8 -topk8 -outform DER -in client.key -out client.key.pk8 -nocrypt
     * openssl pkcs8 -topk8 -inform PEM -in client.key -outform DER -out client.key.der -v1 PBE-MD5-DES
     * openssl pkcs8 -topk8 -inform PEM -in client.key -outform DER -out client.key.der -v1 PBE-SHA1-3DES

    The preceding algorithms are not recommended because they are not that secure.

    If the customer needs to use a higher-level private key encryption algorithm, the following private key encryption algorithms can be used after the bouncycastle or a third-party private key is used to decrypt the password package:

     * openssl pkcs8 -in client.key -topk8  -outform DER -out client.key.der -v2 AES128
     * openssl pkcs8 -in client.key -topk8  -outform DER -out client.key.der -v2 aes-256-cbc -iter 1000000
     * openssl pkcs8 -in client.key -topk8 -out client.key.der  -outform Der -v2 aes-256-cbc -v2prf hmacWithSHA512
     * Enable BouncyCastle: Introduce the bcpkix-jdk15on.jar and bcprov-ext-jdk15on.jar packages for projects that use JDBC. The recommended version is 1.65 or later.

  4. Configure sslmode.

    Set sslmode to require, verify-ca, or verify-full. For details about the parameters, see sslmode. You can select one of them based on the application scenario.
    /* Set sslmode to require. */
    urlProps.setProperty("sslmode", "require");
    /* Set sslmode to verify-ca. */
    urlProps.setProperty("sslmode", "verify-ca");
    /* Set sslmode to verify-full (verification in Linux). */
    urlProps.setProperty("sslmode", "verify-full");

  5. Load the driver.

    1. Add the opengaussjdbc.jar package to the code running tool (such as IDE).
    2. Load the database driver com.huawei.opengauss.jdbc.Driver as follows:
    Class.forName("com.huawei.opengauss.jdbc.Driver");

  6. Establish a database connection.

    Call DriverManager.getConnection(String url, Properties info) to connect to the database.
    Connection conn = DriverManager.getConnection(sourceURL,urlProps);