EncJDBC

Updated at:

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

Usage notes

  • Store your master encryption key (MEK) securely.

  • Use JDK 1.8 or a later version.

    Note

    The examples in this topic use Maven 3.9.2 and IntelliJ 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 openssl rand -hex 16, using a random function in a programming language, or obtaining one from a third-party Key Management Service (KMS).

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:

  • Internationally accepted algorithms:

    • AES_128_GCM

    • AES_128_CTR

    • AES_128_CBC

    • AES_128_ECB (not recommended)

  • Chinese national standard algorithms:

    • SM4_128_GCM (default)

    • SM4_128_CTR

    • SM4_128_CBC

    • SM4_128_ECB (not recommended)

Note
  • The AES_128_ECB and SM4_128_ECB encryption algorithms are less secure. Use them with caution. We recommend that you use other, more secure encryption algorithms.

  • This parameter is optional. The default value is SM4_128_GCM.

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.

Note
  • When using the URL configuration method, you can concatenate multiple parameters by using the & character.

  • In all three connection methods, the MEK is processed locally on the client. The client uses envelope encryption to protect data keys sent to the server. This ensures that the MEK is 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.conf file in the src/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 @0x5c0369c4 when 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-UNNAMED VM option at runtime. This exports com.sun.crypto.provider to 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 error when 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:

      1. Locate your JDK installation directory.

      2. In the <jdk_installation_path>/conf/security/ directory, locate the java.security file.

      3. Edit the java.security file. In the List of providers and their preference orders (see above): section, add the following line:

        security.provider.14=org.bouncycastle.jce.provider.BouncyCastleProvider