Help Center/ GaussDB/ Developer Guide(Distributed_V2.0-8.x)/ Application Development Guide/ Development Based on JDBC/ Development Process/ Connecting to a Database/ Connecting to a Database in SM-based TLS Mode
Updated on 2025-08-19 GMT+08:00
View PDF

Connecting to a Database in SM-based TLS Mode

When connecting to the GaussDB server through JDBC, you can enable SM-based TLS to encrypt the communication between the client and server. This mode provides a highly secure channel for sensitive data transmission on the Internet. You can connect to a database in SM-based TLS mode using either of the following methods: SM-based TLS with one-way authentication and SM-based TLS with two-way authentication. In one-way authentication, only the client needs to verify the server identity. In two-way authentication, the client and server need to verify each other.

Method 1: SM-based TLS with One-Way Authentication

Prerequisites: You have obtained the SM-based TLS certificate and private key file required by a server and configured the server. In addition, you have obtained the cacert.pem root certificate required by a client. Step 4 describes how to configure the root certificate 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.

Connect to a database in SM-based TLS mode with one-way authentication 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.

    Obtain the username and password from the environment variables EXAMPLE_USERNAME_ENV and EXAMPLE_PASSWORD_ENV respectively, and set them as property values of the Properties object. 
    String urls = "jdbc:gaussdb://$ip:$port/database";
String userName = System.getenv("EXAMPLE_USERNAME_ENV");
String password = System.getenv("EXAMPLE_PASSWORD_ENV");
Properties urlProps = new Properties();
urlProps.setProperty("user", userName);
urlProps.setProperty("password", password);

  3. Set the SSL attribute to true and sslmode to verify-ca. 

    urlProps.setProperty("ssl", "true");
urlProps.setProperty("sslmode", "verify-ca");

  4. Configure the cacert.pem root certificate on the client and set sslgmcipher to ECC_SM4_SM3 only.

    For details about the sslrootcert and sslgmcipher parameters, see sslrootcert and sslgmcipher. 
    urlProps.setProperty("sslrootcert", "cacert.pem");
urlProps.setProperty("sslgmcipher", "ECC_SM4_SM3");

  5. Load the driver.

    1. Add the gaussdbjdbc.jar package to the runtime environment (for example, the IDE).
    2. Load the database driver com.huawei.gaussdb.jdbc.Driver.
    Class.forName("com.huawei.gaussdb.jdbc.Driver");

  6. Create a database connection.

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

Method 2: SM-based TLS with Two-Way Authentication

Prerequisites: You have obtained the SM-based TLS certificate and private key file required by a server and configured the server. In addition, you have obtained the client.key.pk8, client_enc.key.pk8, client.crt, client_enc.crt, cacert.pem certificates and private key file required by a client. Step 4 describes how to configure the certificates 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.

Connect to a database in SM-based TLS mode with two-way authentication 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.

    Obtain the username and password from the environment variables EXAMPLE_USERNAME_ENV and EXAMPLE_PASSWORD_ENV respectively, and set them as property values of the Properties object. 
    String urls = "jdbc:gaussdb://$ip:$port/database";
String userName = System.getenv("EXAMPLE_USERNAME_ENV");
String password = System.getenv("EXAMPLE_PASSWORD_ENV");
Properties urlProps = new Properties();
urlProps.setProperty("user", userName);
urlProps.setProperty("password", password);

  3. Set the SSL attribute to true and sslmode to verify-ca. 

    urlProps.setProperty("ssl", "true");
urlProps.setProperty("sslmode", "verify-ca");

  4. Configure the client.key.pk8, client_enc.key.pk8, client.crt, client_enc.crt and cacert.pem certificates on the client. Set sslgmcipher to ECC_SM4_SM3 or ECDHE_SM4_SM3. For details, see sslgmcipher. 

    urlProps.setProperty("sslrootcert", "cacert.pem");
urlProps.setProperty("sslgmcipher", "ECDHE_SM4_SM3");
urlProps.setProperty("sslcert", "client.crt");
urlProps.setProperty("sslkey", "client.key.pk8");
urlProps.setProperty("sslenccert", "client_enc.crt");
urlProps.setProperty("sslenckey", "client_enc.key.pk8");

  5. Load the driver.

    1. Add the gaussdbjdbc.jar package to the runtime environment (for example, the IDE).
    2. Load the database driver com.huawei.gaussdb.jdbc.Driver.
    Class.forName("com.huawei.gaussdb.jdbc.Driver");

  6. Create a database connection.

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

  • To use the SM-based TLS capability of the JDBC client, the BGMProvider open-source software (bgmprovider-1.X.X-jar-with-dependencies.jar) of version 1.1 or later is required.
  • To use the SM-based TLS capability of the JDBC client, the JDK version must be 8u302 or later.
  • SM algorithms feature strict principles, complex computing, and high security. Therefore, after SM-based TLS encrypted transmission is configured, the performance deteriorates significantly compared with that during TLS encrypted transmission based on other international algorithms.
Parent topic: Connecting to a Database