EncJDBC
To use the always-confidential database feature to encrypt data in protected columns and access the database from a Java application, use the EncJDBC client driver. EncJDBC provides a convenient and cost-effective way to connect to an always-confidential database. This topic describes how to use EncJDBC to access an always-confidential database.
With the master encryption key (MEK) configured, EncJDBC automatically decrypts ciphertext and returns plaintext. This process is transparent to your application. You can connect to the always-confidential database with just a few lines of configuration, which reduces the cost of using the always-confidential database feature.
Prerequisites
-
You have enabled the always-confidential database feature. For more information, see Enable the always-confidential database feature.
-
You have obtained the connection information for the database, such as the hostname, port, database name, username, and password.
-
You have configured a data protection rule. For more information, see Configure column encryption rules using SQL.
Usage notes
-
Store your master encryption key (
MEK) securely. -
Use JDK 1.8 or a later version.
NoteThe examples in this topic use Maven
3.9.2andIntelliJ IDEA Community Edition 2022.3.2.
Procedure
Step 1: Add Maven dependency
You need to add the following dependencies to the pom.xml file in your Maven project.
<dependencies>
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>aliyun-encdb-mysql-jdbc</artifactId>
<version>1.0.9-1</version>
</dependency>
</dependencies>
Step 2: Configure the client and query data
You can use EncJDBC like any other JDBC driver. However, you must first configure security-critical parameters, including the MEK (master encryption key) and ENC_ALGO (encryption algorithm).
The following table describes the parameters and provides example values.
|
Parameter |
Example value |
Description |
|
MEK |
00112233445566778899aabbccddeeff |
A master encryption key that you customize and manage. You can generate an MEK by using a password generation tool such as The value must be a 32-character hexadecimal string (16 bytes). Warning
Your MEK is the root credential for accessing encrypted data. For security reasons, the always-confidential database does not store or manage your MEK, and does not provide generation or backup services for it. You are responsible for generating and backing up your MEK. If you lose the key, you permanently lose access to your data. We recommend that you back up your MEK securely. |
|
ENC_ALGO |
SM4_128_CBC |
The encryption algorithm for protected data. Valid values:
Note
|
Configure MEK and ENC_ALGO
This section describes three ways to configure MEK and ENC_ALGO. If you use more than one configuration method, the following priority order applies: JDBC properties > Configuration file > URL configuration.
-
When using the URL configuration method, you can concatenate multiple parameters by using the
&character. -
In all three connection methods, the
MEKis processed locally on the client. The client uses envelope encryption to protect data keys sent to the server. This ensures that theMEKis never exposed.
JDBC properties
In standard JDBC, you can set custom attributes using a Properties object when you connect. The following example shows how to configure JDBC properties for a connection:
// Prepare the connection details, such as hostname, port, database name, username, and password.
// ...
String mek=...;
String encAlgo=...;
Properties props = new Properties();
props.setProperty("user", username);
props.setProperty("password", password);
props.setProperty("MEK", mek);
props.setProperty("ENC_ALGO", encAlgo);
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s", hostname, port, dbname);
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");
Connection connection = DriverManager.getConnection(dbUrl, props);
// ... Initiate a query ...
Configuration file
You can import parameters such as the 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 driver uses the default file encjdbc.conf.
The configuration file must contain the following content:
MEK=
ENC_ALGO=
Place the configuration file in one of the following locations:
-
Place the
encjdbc.conffile in thesrc/main/resources/directory of your project. -
Place the file in the root directory of your project, which is the working directory at runtime.
After you configure the file, you do not need additional configuration in your code, as shown in the following example:
// Prepare the connection details, such as hostname, port, database name, username, and password.
// ...
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s", hostname, port, dbname);
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");
Connection connection = DriverManager.getConnection(dbUrl, username, password);
// ... Initiate a query ...
URL configuration
You can embed parameters such as MEK and ENC_ALGO in the URL, as shown in the following example:
// Prepare the connection details, such as hostname, port, database name, username, and password.
// ...
String mek=...;
String encAlgo=...;
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s?MEK=%s&ENC_ALGO=%s", hostname, port, dbname, mek, encAlgo);
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");
Connection connection = DriverManager.getConnection(dbUrl, username, password);
// ... Initiate a query ...
Code example
// Replace hostname, port, dbname, username, and password with your instance details.
String hostname = "hostname";
String port = "port";
String dbname = "db";
String username = "user";
String password = "password";
String mek="00112233445566778899aabbccddeeff"; // Example only. Use a more complex key.
String encAlgo="SM4_128_CBC";
Properties props = new Properties();
props.setProperty("user", username);
props.setProperty("password", password);
props.setProperty("MEK", mek);
props.setProperty("ENC_ALGO", encAlgo);
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s", hostname, port, dbname);
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");
Connection connection = DriverManager.getConnection(dbUrl, props);
int[] intData = {1, 2, 3, 4, 5, 6};
String[] strData = {"abc", "bcd", "1", "def", "efg", "fgi"};
// Create a table.
connection.createStatement().executeUpdate("drop table if exists test");
connection.createStatement().executeUpdate("create table test (a int, b text)");
// Insert data.
for (int i = 0; i < 6; i++) {
PreparedStatement pstmt = connection.prepareStatement("insert into test values (?,?)");
pstmt.setInt(1, intData[i]);
pstmt.setString(2, strData[i]);
pstmt.executeUpdate();
}
// Check the plaintext data.
ResultSet rs = connection.createStatement().executeQuery("select * from test");
while (rs.next()) {
for (int i = 0; i < rs.getMetaData().getColumnCount(); i++) {
System.out.print(rs.getString(i + 1));
System.out.print("\t");
}
System.out.print("\n");
}
Expected output:
1 abc
2 bcd
3 1
4 def
5 efg
6 fgi
FAQ
-
Q: Why do I receive the error
Exception in thread "main" java.lang.IllegalAccessError: class com.alibaba.encdb.common.SymCrypto (in unnamed module @0x5c0369c4) cannot access class com.sun.crypto.provider.SunJCE (in module java.base) because module java.base does not export com.sun.crypto.provider to unnamed module @0x5c0369c4when I run the application?A: This error can occur because newer JDK versions restrict cross-module access. To resolve this issue, add the
--add-exports=java.base/com.sun.crypto.provider=ALL-UNNAMEDVM option at runtime. This exportscom.sun.crypto.providerto the unnamed module and resolves the access issue. -
Q: Why do I receive the error
failed in mek provision: you might have an incorrect mek setting. Detail:gcmEncrypt errorwhen I run the application?A: This issue is common with Oracle JDK. Use one of the following methods to resolve it:
-
Use an Amazon Corretto JDK.
-
Manually configure a security provider for your Oracle JDK by following these steps:
-
Locate your JDK installation directory.
-
In the
<jdk_installation_path>/conf/security/directory, locate thejava.securityfile. -
Edit the
java.securityfile. In theList of providers and their preference orders (see above):section, add the following line:security.provider.14=org.bouncycastle.jce.provider.BouncyCastleProvider
-
-