To access encrypted data in a database column from a Java application, use the column encryption driver (JDBC) provided by Alibaba Cloud. If you have the required key, the driver automatically decrypts the ciphertext and returns plaintext. This process is transparent to the application. To use the column encryption feature, you only need to add a few lines of configuration code to your application.
Prerequisites
You have enabled column encryption and configured the Ciphertext Permission (JDBC Decryption) permission for the database account.
You have the connection information for the encrypted database. This includes the domain name (host), port, database instance name (dbname), username, and password. For more information about how to retrieve the internal or public endpoint of a cluster, see View or change endpoints and ports.
Notes
Save the master key (
MEK) that you set.Use JDK 1.8 or later.
Procedure
This topic uses a Java project built with Maven as an example.
Step 1: Configure Maven dependencies
Add the following dependency to the pom.xml file of your Maven project.
<dependencies>
...
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>aliyun-cls-jdbc</artifactId>
<version>1.0.10-1</version>
</dependency>
...
</dependencies>Step 2: Configure the URL and MEK
Before you access data in encrypted database columns using JDBC, you must configure the required parameters. These include the MEK and the URL (database connection information).
Parameter | Example value (string) | Description |
MEK | 00112233445566778899aabbccddeeff | The customer master key, which is user-defined.
Warning The customer master key is the root credential for accessing encrypted data. For security reasons, the database does not store or manage your master key. The database also does not provide services to generate or back up the customer master key. You must generate the customer master key. If you lose the key, you can no longer access your data. Therefore, back up your customer master key properly. |
URL | jdbc:postgresql:encdb://%s:%s/%s | When you use the column encryption driver, the URL must start with |
Configure the MEK
This topic describes three methods to configure the MEK. If you use more than one method to configure JDBC, the methods are prioritized in the following order: JDBC properties configuration > file configuration > URL configuration.
When you configure the MEK in the URL, you can concatenate multiple parameters with an ampersand (
&).In these three connection methods, the
MEKis processed locally on the client and securely distributed to the server using envelope encryption. This process ensures that theMEKis not exposed.
JDBC properties configuration
When you establish a standard JDBC connection, you can configure custom properties using the Properties class. For example:
// Prepare connection information such as the hostname, port, dbname, username, and password.
// ...
String mek=****;
Properties props = new Properties();
props.setProperty("user", username);
props.setProperty("password", password);
props.setProperty("MEK", mek);
String dbUrl = String.format("jdbc:postgresql:encdb://%s:%s/%s", hostname, port, dbname);
Connection connection = DriverManager.getConnection(dbUrl, props);
// ... Initiate a query ...File configuration
You can import required parameters, such as MEK, from a configuration file. In your project, set a property named encJdbcConfigFile to the path of the configuration file. If you do not set this property, the encjdbc.conf file is used by default.
The configuration file contains the following content:
MEK=****You can place the configuration file in one of the following two locations:
Place the file in the resources directory of your project, as shown in the following figure:
Place the file in the root directory of the project, which is the runtime directory of the program.
After you configure the MEK in the file, no additional configuration is required in the program. For example:
// Prepare connection information such as the hostname, port, dbname, username, and password.
// ...
String dbUrl = String.format("jdbc:postgresql:encdb://%s:%s/%s", hostname, port, dbname);
Connection connection = DriverManager.getConnection(dbUrl, username, password);
// ... Initiate a query ...URL configuration
You can embed parameters such as MEK and ENC_ALGO in a URL. Sample code:
// Prepare connection information such as the hostname, port, dbname, username, and password.
// ...
String mek=****;
String dbUrl = String.format("jdbc:postgresql:encdb://%s:%s/%s?MEK=%s", hostname, port, dbname, mek);
Connection connection = DriverManager.getConnection(dbUrl, username, password);
// ... Initiate a query ...Complete code sample
The following sample code shows how to configure the MEK using JDBC properties. Before you use the JDBC driver to access encrypted columns, you must configure column encryption on your RDS instance.
package org.example;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.Properties;
public class Main {
public static void main(String[] args) throws SQLException {
// Update the following connection information (hostname, port, dbname, username, password) as needed.
String hostname = "pc-***.rwlb.rds.aliyuncs.com"; // The endpoint of the instance. Update it to the actual value.
String port = "5432"; // The database port. Update it to the actual value.
String dbname = "testdb"; // The database name. Update it to the actual value.
String username = "user"; // The database username. Update it to a user that has the Ciphertext Permission (JDBC Decryption).
String password = "password"; // The password for the database username.
// Sample key. Use a more complex key to ensure security.
String MEK = "00112233445566778899aabbccddeeff";
// Create database connection properties.
Properties props = new Properties();
props.setProperty("user", username);
props.setProperty("password", password);
props.setProperty("MEK", MEK);
// Format the database connection URL.
String dbUrl = String.format("jdbc:postgresql:encdb://%s:%s/%s", hostname, port, dbname);
// Use DriverManager to get the database connection.
Connection connection = DriverManager.getConnection(dbUrl, props);
// Execute a query to get data from the test_table.
ResultSet rs = connection.createStatement().executeQuery("SELECT * FROM test_table");
while (rs.next()) {
for (int i = 1; i <= rs.getMetaData().getColumnCount(); i++) { // The column index starts from 1.
System.out.print(rs.getString(i) + "\t");
}
System.out.println(); // Line break.
}
// Close resources.
rs.close(); // Close the result set.
connection.close(); // Close the connection.
}
}