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:

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;
```

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

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 runtime environment (for example, the IDE).
2. Load the database driver com.huawei.gaussdb.jdbc.Driver.
```
Class.forName("com.huawei.gaussdb.jdbc.Driver");
```
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:

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;
```

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

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

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

Previous topic: Connecting to a Database in UDS Mode

Next topic: Running SQL Statements