ApsaraDB RDS:EncJDBC

How it works

EncJDBC uses a two-step process:

1. At connection time, EncJDBC distributes your MEK to the server using envelope encryption, ensuring the key is never transmitted in plaintext.

2. For each query, EncJDBC automatically encrypts parameters targeting encrypted columns and decrypts results before returning them to your application.

Your application code continues to work with plaintext values—no changes to query logic are needed.

Prerequisites

Before you begin, ensure that you have:

• The always-confidential database feature enabled on your ApsaraDB RDS for MySQL instance. See Enable the always-confidential database feature

• Connection details for the instance: hostname, port, database name, username, and password

• A data protection rule configured. See Configure data protection rules

• JDK 1.8 or later

The examples in this topic use Maven 3.9.2 and IntelliJ IDEA Community Edition 2022.3.2.

Add the Maven dependency

Add the following dependency to the pom.xml file of your project:

<dependencies>
  <dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-encdb-mysql-jdbc</artifactId>
    <version>1.0.9-1</version>
  </dependency>
</dependencies>

Configure and connect

EncJDBC uses the JDBC URL format jdbc:mysql:encdb://{hostname}:{port}/{dbname} and the driver class com.aliyun.encdb.mysql.jdbc.EncDriver.

Before connecting, configure two required parameters:

Supported encryption algorithms:

Avoid AES_128_ECB and SM4_128_ECB—these modes do not provide strong security guarantees.

// Replace the placeholders with your instance connection details.
String hostname = "<hostname>";
String port     = "<port>";
String dbname   = "<dbname>";
String username = "<username>";
String password = "<password>";

String mek     = "<your-mek>";   // 32-character hex string
String encAlgo = "<enc-algo>";   // e.g., SM4_128_GCM

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

MEK=<your-mek>
ENC_ALGO=<enc-algo>

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

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

Complete example

The following example uses JDBC properties to connect, insert rows into a table, and query the plaintext results.

// Replace the placeholders with your instance connection details.
String hostname = "hostname";
String port     = "port";
String dbname   = "db";
String username = "user";
String password = "password";

// Use a strong, randomly generated MEK in production.
String mek     = "00112233445566778899aabbccddeeff";
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 the table.
connection.createStatement().executeUpdate("drop table if exists test");
connection.createStatement().executeUpdate("create table test (a int, b text)");

// Insert rows using PreparedStatement.
// EncJDBC automatically encrypts values targeting encrypted columns.
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();
}

// Query rows. EncJDBC automatically decrypts results before returning them.
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	cde
4	def
5	efg
6	fgi

Note the following:

• All reads and writes to encrypted columns go through PreparedStatement. The driver automatically encrypts parameters and decrypts results—no changes to your query logic are required.

• Values passed to non-encrypted columns are not affected.

Troubleshooting

--add-exports=java.base/com.sun.crypto.provider=ALL-UNNAMED