整合EncJDBC - Database Autonomy Service

若您希望使用Java應用程式訪問資料庫中被列加密保護的資料列，可以使用EncJDBC驅動程式串連資料庫。此操作方便便捷，並能夠降低使用全密態功能的成本。本文介紹如何通過EncJDBC訪問資料庫加密列的明文資訊。

在持有使用者密鑰的情況下，資料轉送鏈路全加密。您的用戶端EncJDBC能夠自動解密並返回明文資料，應用程式只需配置幾行代碼就可以展示明文資料。

前提條件

已進行敏感識別的掃描任務，獲得需要加密的敏感性資料列資訊。更多資訊，請參見敏感識別。
已為目標資料庫配置列加密能力，並設定目標資料庫帳號的密文許可權為密文許可權（JDBC解密）。設定資料庫列加密的具體操作和帳號許可權的詳細說明，請參見列加密。
已擷取加密資料庫串連資訊。您首先需要擷取加密資料庫的串連資訊，如網域名稱（host）、連接埠（port）、資料庫執行個體名（dbname）、使用者名稱（username）、密碼（password）等。

產生MEK

阿里雲提供了Java語言的全密態用戶端驅動程式EncJDBC。使用者只需在用戶端側使用該驅動串連資料庫，並在資料庫連接URL中指定主要金鑰（Master Encryption Key，簡稱MEK），即可訪問加密資料庫。該驅動會自動完成密文資料的解密返回明文資料。

MEK：由用戶端通過安全的非對稱式加密協議傳輸給資料庫服務端，使服務端、用戶端具有相同的密鑰，從而通過對稱式加密安全傳輸資料。
取值範圍：長度為16位元組的16進位字串，且長度為32個字元。

警告

MEK是您授權用戶端訪問加密資料的根憑據。出於安全考慮，加密資料庫不持有並管理您的MEK，也不提供MEK的產生和備份服務，您需要自行產生MEK。MEK的儲存和管理對資料庫的安全性非常重要。因此我們建議您妥善備份MEK。

可在資料庫列加密配置中選擇的加密方式，選擇KMS密鑰或產生本地密鑰作為MEK來解密對應資料庫。

KMS密鑰

重要

使用KMS密鑰時，請確保KMS服務可用。否則，全密態用戶端驅動EncJDBC無法使用。

您需要擷取資料庫列加密配置中選擇的KMS密鑰所屬KMS執行個體的訪問地址，以及對應阿里雲帳號或RAM使用者（必須具備KMS解密許可權）的存取金鑰AccessKeyId和AccessKeySecret，以便通過用戶端讀取該KMS密鑰。具體操作如下：

使用阿里雲帳號或RAM使用者登入控制台。
如果是RAM使用者，需要授予RAM使用者KMS解密許可權。
1. 建立自訂權限原則。策略內容如下：
```
{
    "Version": "1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "KMS:Decrypt",
            "Resource": "*"
        }
    ]
}
```
2. 將建立的自訂權限原則授予指定的RAM使用者。具體操作，請參見為RAM使用者授權。
擷取KMS執行個體訪問地址。
- KMS執行個體中的密鑰預設僅允許VPC網路訪問，您可以在KMS的執行個體管理頁面，找到目標KMS執行個體，單擊操作列的詳情，然後在執行個體資訊頁簽，查看執行個體VPC地址。
- 如果需要通過公網存取金鑰，需要在資源共用頁簽，開啟公網訪問後查看公網地址。
擷取存取金鑰。
您需要在建立阿里雲帳號或RAM使用者的AccessKey時，儲存AccessKeyId和AccessKeySecret。具體操作，請參見建立AccessKey。

本地密鑰

資料庫列加密配置中加密方式為本地密鑰時，您需要產生一個MEK。例如，00112233445566778899aabbccddeeff。

常見的產生方法有：密碼產生工具或程式設計語言中的random函數。

例如：

Linux系統內建OpenSSL工具，執行openssl rand -hex 16，產生密鑰。
Windows系統，請安裝OpenSSL軟體包。

用戶端接入說明

重要

Java使用JDK 1.8或以上版本。

在用戶端側將資料庫連接驅動改為EncJDBC，更新資料庫連接URL，指定密鑰MEK，實現對資料庫加密列的明文訪問。

1. 安裝依賴

您需要在自己的Maven專案設定檔pom.xml中加入以下依賴項。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-cls-jdbc</artifactId>
    <version>1.0.10-1</version>
</dependency>

2. 配置`MEK`串連資料庫

下面介紹配置MEK的方法：JDBC properties配置、檔案配置和URL配置。如果您的JDBC同時配置了兩種以上的方法，優先順序順序為：JDBC properties配置 > 檔案配置 > URL配置。

說明

URL配置方式中，多個參數可以用&進行拼接。
以下配置和串連方式，MEK均在用戶端本地進行處理，並以安全方式（信封加密）發送到服務端，保證MEK不泄露。

根據資料庫列加密配置中的加密方式，選擇通過本地密鑰或KMS密鑰串連資料庫。

通過KMS密鑰串連資料庫

重要

如果使用STS臨時訪問憑證擷取KMS託管的MEK，您可以使用STS SDK擷取臨時憑據STS Token。STS SDK樣本，請參見STS SDK概覽。
不能直接將存取金鑰（AccessKeyId和AccessKeySecret）寫入程式碼在業務代碼中，本樣本使用配置系統內容變數的方式管理存取金鑰。具體內容，請參見在Linux、macOS和Windows系統配置環境變數。

JDBC properties配置

標準的JDBC在串連時，可以通過Properties設定使用者自訂屬性。以下是通過這種方式配置JDBC屬性並運行JDBC的例子：

// 準備好串連地址（hostname）、連接埠（port）、資料庫執行個體名（dbname）、使用者名稱（username）、密碼（password）等串連資訊。
// ...

String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";

// 從環境變數中擷取存取金鑰（AccessKey ID和AccessKey Secret）。
String accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
// 如果使用STS臨時訪問憑證讀取KMS密鑰，還需要填寫擷取的STS安全性權杖（SecurityToken）。
// String stsToken= "yourSecurityToken";

// KMS執行個體訪問地址，開啟公網訪問使用公網地址。在VPC網路訪問，使用執行個體VPC地址。
String kmsEndpoint = "kms.cn-hangzhou.aliyuncs.com";

Properties props = new Properties();
props.setProperty("user", username);
props.setProperty("password", password);
props.setProperty("ALIBABA_CLOUD_ACCESS_KEY_ID", accessKeyId);
props.setProperty("ALIBABA_CLOUD_ACCESS_KEY_SECRET", accessKeySecret);
props.setProperty("ALIBABA_CLOUD_KMS_ENDPOINT", kmsEndpoint);
// props.setProperty("ALIBABA_CLOUD_STS_TOKEN","stsToken");



// 下面是MySQL版資料庫的串連URL格式"jdbc:mysql:encdb://%s:%s/%s"。
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s", hostname, port, dbname);

// 下面是MySQL版資料庫的載入 EncJDBC 驅動。
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");

// 擷取資料庫連接。
Connection connection = DriverManager.getConnection(dbUrl, props);

// ... 發起查詢 ...

URL配置

支援通過URL連結中嵌入擷取KMS密鑰的參數。如下面所示：

// 準備好串連地址（hostname）、連接埠（port）、資料庫執行個體名（dbname）、使用者名稱（username）、密碼（password）等串連資訊。
// ...
String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";

// 從環境變數中擷取存取金鑰（AccessKey ID和AccessKey Secret）。
String accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
// 如果使用STS臨時訪問憑證讀取KMS密鑰，還需要填寫擷取的STS安全性權杖（SecurityToken）。
// String stsToken= "yourSecurityToken";

// KMS執行個體訪問地址，開啟公網訪問使用公網地址。在VPC網路訪問，使用執行個體VPC地址。
String kmsEndpoint = "kms.cn-hangzhou.aliyuncs.com";

// 下面是MySQL版資料庫的串連URL格式。
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s?ALIBABA_CLOUD_ACCESS_KEY_ID=%s&ALIBABA_CLOUD_ACCESS_KEY_SECRET=%s&ALIBABA_CLOUD_KMS_ENDPOINT=%s", hostname, port, dbname, accessKeyId,accessKeySecret,kmsEndpoint);
// 使用STS Token。
// String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s?ALIBABA_CLOUD_ACCESS_KEY_ID=%s&ALIBABA_CLOUD_ACCESS_KEY_SECRET=%s&ALIBABA_CLOUD_KMS_ENDPOINT=%s&ALIBABA_CLOUD_STS_TOKEN=%s", hostname, port, dbname, accessKeyId,accessKeySecret,kmsEndpoint,stsToken);

// 下面是MySQL版資料庫的載入 EncJDBC 驅動。
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");

// 擷取資料庫連接。
Connection connection = DriverManager.getConnection(dbUrl, username, password);

// ... 發起查詢 ...

通過本地密鑰串連資料庫

JDBC properties配置

標準的JDBC在串連時，可以通過Properties設定使用者自訂屬性。以下是通過這種方式配置JDBC屬性並運行JDBC的例子：

// 準備好串連地址（hostname）、連接埠（port）、資料庫執行個體名（dbname）、使用者名稱（username）、密碼（password）等串連資訊。
// ...

String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";
// 使用者主要金鑰。
String mek = "00112233445566778899aabbccddeeff"; 

Properties props = new Properties();
props.setProperty("user", username);
props.setProperty("password", password);
props.setProperty("MEK", mek);

// 下面是MySQL版資料庫的串連URL格式"jdbc:mysql:encdb://%s:%s/%s"。PostgreSQL版資料庫的串連URL格式需替換為"jdbc:postgresql:encdb://%s:%s/%s"。
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s", hostname, port, dbname);

// 下面是MySQL版資料庫的載入 EncJDBC 驅動。PostgreSQL版資料庫的載入 EncJDBC 驅動替換為"com.aliyun.encdb.postgresql.jdbc.EncDriver"。
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");

// 擷取資料庫連接。
Connection connection = DriverManager.getConnection(dbUrl, props);

// ... 發起查詢 ...

檔案配置

支援通過設定檔來匯入參數，配置需要的MEK等參數。

說明

檔案配置方式僅適用配置本地密鑰MEK。

您可以在專案中設定一個名為encJdbcConfigFile的property，將值設定為設定檔路徑即可（預設時，預設使用encjdbc.conf的檔案）。設定檔的內容如下：

MEK=00112233445566778899aabbccddeeff

您可以通過以下兩種方式放置設定檔的位置：

將檔案放入專案中的resources目錄下，如下圖所示：
將檔案放入專案根目錄，即程式的運行時目錄。

通過檔案配置方式，在做完檔案配置後，您可以不用在程式中做額外的配置，如下面所示：

// 準備好串連地址（hostname）、連接埠（port）、資料庫執行個體名（dbname）、使用者名稱（username）、密碼（password）等串連資訊。
// ...
String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";

// 下面是MySQL版資料庫的串連URL格式"jdbc:mysql:encdb://%s:%s/%s"。PostgreSQL版資料庫的串連URL格式需替換為"jdbc:postgresql:encdb://%s:%s/%s"。
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s", hostname, port, dbname);

// 下面是MySQL版資料庫的載入 EncJDBC 驅動。PostgreSQL版資料庫的載入 EncJDBC 驅動替換為"com.aliyun.encdb.postgresql.jdbc.EncDriver"。
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");

// 擷取資料庫連接。
Connection connection = DriverManager.getConnection(dbUrl, username, password);

// ... 發起查詢 ...

URL配置

支援通過URL連結中嵌入MEK等參數。如下面所示：

// 準備好串連地址（hostname）、連接埠（port）、資料庫執行個體名（dbname）、使用者名稱（username）、密碼（password）等串連資訊。
// ...
String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";
 // 使用者主要金鑰。
String mek = "00112233445566778899aabbccddeeff";

// 下面是MySQL版資料庫的串連URL格式"jdbc:mysql:encdb://%s:%s/%s?MEK=%s"。PostgreSQL版資料庫的串連URL格式需替換為"jdbc:postgresql:encdb://%s:%s/%s?MEK=%s"。
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s?MEK=%s", hostname, port, dbname, mek);

// 下面是MySQL版資料庫的載入 EncJDBC 驅動。PostgreSQL版資料庫的載入 EncJDBC 驅動替換為"com.aliyun.encdb.postgresql.jdbc.EncDriver"。
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");

// 擷取資料庫連接。
Connection connection = DriverManager.getConnection(dbUrl, username, password);

// ... 發起查詢 ...

3. 查詢加密列的明文資料

串連資料庫成功後，可以像普通JDBC查詢一樣操作資料庫。EncJDBC會自動對加密列進行解密並返回明文資料。

範例程式碼：

// 發起查詢。

// 建立查詢語句。
Statement statement = connection.createStatement();
ResultSet resultSet = statement.executeQuery("SELECT * FROM your_table_name");

// 遍曆結果集。
while (resultSet.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");
}

常見問題

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
```

前提條件

產生MEK

KMS密鑰

本地密鑰

用戶端接入說明

1. 安裝依賴

2. 配置MEK串連資料庫

通過KMS密鑰串連資料庫

JDBC properties配置

URL配置

通過本地密鑰串連資料庫

JDBC properties配置

檔案配置

URL配置

3. 查詢加密列的明文資料

常見問題

2. 配置`MEK`串連資料庫