Connecting to a Database in SM-based TLS Mode

When connecting to a GaussDB server through JDBC, you can enable SM-based TLS to encrypt communication between a client and a 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 the certificates and configure the server, contact an administrator or refer to related OpenSSL documents and commands.

Connect to a database in SM-based TLS mode with one-way authentication as follows:

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 API Reference.
```
import java.sql.Connection;
import java.sql.DriverManager;
import java.util.Properties;
```

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 attribute 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);

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

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

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");
```
Load the driver.
1. Add the gaussdbjdbc.jar package to the code running tool (such as IDE).
2. Load the database driver com.huawei.gaussdb.jdbc.Driver as follows:
```
Class.forName("com.huawei.gaussdb.jdbc.Driver");
```
Establish 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 the certificates and configure the server, contact an administrator or refer to related OpenSSL documents and commands.

The first three steps for connecting to a database in SM-based TLS mode with two-way authentication are the same as those in SM-based TLS mode with one-way authentication. The details are as follows:

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 API Reference.
```
import java.sql.Connection;
import java.sql.DriverManager;
import java.util.Properties;
```

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 attribute 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);

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

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

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 Connection Parameter Reference.

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");

Load the driver.
1. Add the gaussdbjdbc.jar package to the code running tool (such as IDE).
2. Load the database driver com.huawei.gaussdb.jdbc.Driver as follows:
```
Class.forName("com.huawei.gaussdb.jdbc.Driver");
```
Establish 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

Previous topic: Connecting to a Database in UDS Mode

Next topic: Running SQL Statements