本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。
全密态数据库对查询结果中的目标数据进行加密。为了帮助客户Java业务系统零改造、一键式接入全密态数据库系统,全密态数据库推出了与之配套的全密态客户端驱动JDBC(即EncJDBC)。EncJDBC能够自动完成密文数据的解密并返回明文数据,过程对应用透明,业务应用仅需几行配置即可接入全密态数据库,已有业务代码无需任何修改。本文档介绍了如何使用EncJDBC访问数据库。
前提条件
已开通全密态功能,详情请参见如何开通全密态PolarMySQL功能。
已获取加密数据库连接信息。您首先需要获取加密数据库的连接信息,如域名(host)、端口(port)、数据库实例名(dbname)、用户名(username)、密码(password)等。
已配置数据保护规则。具体操作请参见管理加密规则。
注意事项
请保存好您设置的主密钥
MEK
。JAVA版本需要在1.8及以上。
本文中使用的Maven版本为3.9.2
,使用的开发工具为IntelliJ IDEA Community Edition 2022.3.2
。
操作步骤
步骤一:添加Maven依赖
您需要在自己的Maven项目的pom.xml
配置文件中添加以下依赖项:
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>aliyun-encdb-mysql-jdbc</artifactId>
<version>1.0.8</version>
</dependency>
在添加Maven依赖时请根据实际使用场景替换version
的值。您可以在官网上查看aliyun-encdb-mysql-jdbc
的最新版本。
步骤二:通过全密态客户端查询(代码示例)
您可以像使用任意一个JDBC一样使用EncJDBC
。但是您需要预先在EncJDBC
中配置和您数据安全息息相关的MEK
(主密钥)、ENC_ALGO
(加密算法)。具体的参数说明及其示例见下表:
参数 | 说明 | 取值示例(字符串类型) |
MEK | 用户主密钥,由用户自定义指定。 常见的生成方法有:密码生成工具(如openssl, openssl rand -hex 16)、编程语言中的random函数、或者从第三方密钥管理服务(KMS)获取。 取值范围:长度为16字节的16进制字符串,且长度为32个字符。 警告 用户主密钥是您访问加密数据的根凭据,出于安全考虑,全密态数据库不持有并管理您的主密钥,也不提供用户主密钥的生成和备份服务,您需要自行生成用户主密钥。一旦您丢失密钥,将无法再访问已有的数据。因此,建议您妥善备份用户主密钥。 | 00112233445566778899aabbccddeeff |
ENC_ALGO | 被保护数据将要使用的加密算法。取值范围如下:
| SM4_128_CBC |
配置MEK和ENC_ALGO
下面介绍三种配置MEK
和ENC_ALGO
的方法。如果您的JDBC配置了两种以上的方法,优先级顺序为:JDBC properties配置 > 文件配置 > URL配置。
URL配置方式中,多个参数可以用
&
进行拼接。以下三种连接方式,
MEK
均在客户端本地进行处理,并以安全方式分发(信封加密)到服务端,始终保证MEK
不泄露。
JDBC properties配置
标准的JDBC在连接数据库时,可以通过Properties
设置用户自定义属性。以下是一个通过这种方式配置JDBC属性并运行JDBC的示例:
// 准备好域名(hostname)、端口(port)、数据库实例名(dbname)、用户名(username)、密码(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);
// ... 发起查询 ...
文件配置
PolarDB MySQL版支持通过配置文件来导入参数方式,配置需要的MEK等参数。您可以在项目中设置一个名为encJdbcConfigFile的property,将值设置为配置文件路径即可(缺省时,默认使用encjdbc.conf
的文件)。配置文件的内容如下:
MEK=
ENC_ALGO=
您可以通过以下两种方式放置配置文件的位置:
将文件放入项目中的resources目录下,如下图所示:
将文件放入项目根目录,即程序的运行时目录。
通过文件配置方式,在配置完成后,您可以不用在程序中做额外的配置,如下所示:
// 准备好域名(hostname)、端口(port)、数据库实例名(dbname)、用户名(username)、密码(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);
// ... 发起查询 ...
URL配置
PolarDB MySQL版支持通过URL链接中嵌入MEK
、ENC_ALGO
等参数。如下所示:
// 准备好域名(hostname)、端口(port)、数据库实例名(dbname)、用户名(username)、密码(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);
// ... 发起查询 ...
完整代码示例(以JDBC properties配置为例)
// 以下域名(hostname)、端口(port)、数据库实例名(dbname)、用户名(username)、密码(password)等连接信息需要更新为您的实例信息
String hostname = "hostname";
String port = "port";
String dbname = "db";
String username = "user";
String password = "password";
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 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 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");
}
输出结果如下:
1 abc
2 bcd
3 cde
4 def
5 efg
6 fgi
常见问题
Q:运行程序时报错
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
,如何处理?A:该报错可能是因为您的JDK版本较高导致的模块间权限问题,请在运行时添加VM option参数
--add-exports=java.base/com.sun.crypto.provider=ALL-UNNAMED
将com.sun.crypto.provider导出给Unnamed模块,以解决访问权限问题。Q:运行程序时报错
failed in mek provision: you might have an incorrect mek setting. Detail:gcmEncrypt error
,如何处理?A:该问题常见于Oracle系列的JDK,如需解决此问题,您可以任选如下两种方式之一:
使用Amazon Correto系列的JDK。
仍然使用Oracle系列的JDK,但需要手动配置Security provider。具体操作步骤如下:
找到JDK的安装路径。
在
安装路径/conf/security/
路径下,找到java.security
文件。编辑
java.security
文件,在List of providers and their preference orders (see above):
区域,补充如下内容:security.provider.14=org.bouncycastle.jce.provider.BouncyCastleProvider