如何使用EncJDBC - PolarDB

全密態資料庫對查詢結果中的目標資料進行加密。為了協助客戶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函數、或者從第三方Key Management Service（KMS）擷取。

取值範圍：長度為16位元組的16進位字串，且長度為32個字元。

警告

使用者主要金鑰是您訪問加密資料的根憑據，出於安全考慮，全密態資料庫不持有並管理您的主要金鑰，也不提供使用者主要金鑰的產生和備份服務，您需要自行產生使用者主要金鑰。一旦您丟失密鑰，將無法再訪問已有的資料。因此，建議您妥善備份使用者主要金鑰。

00112233445566778899aabbccddeeff

ENC_ALGO

被保護資料將要使用的密碼編譯演算法。取值範圍如下：

SM4_128_CBC（預設）
SM4_128_ECB（不推薦）
SM4_128_GCM
SM4_128_CTR
AES_128_GCM
AES_128_ECB（不推薦）
AES_128_CBC
AES_128_CTR

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。具體操作步驟如下：
  1. 找到JDK的安裝路徑。
  2. 在安裝路徑/conf/security/路徑下，找到java.security檔案。
  3. 編輯java.security檔案，在List of providers and their preference orders (see above):地區，補充如下內容：
```
security.provider.14=org.bouncycastle.jce.provider.BouncyCastleProvider
```