如何在 Java 中使用 GroupDocs.Signature 加密元資料
數位簽章非常好，但隱藏的文件屬性——作者姓名、時間戳記、內部 ID——仍可能以純文字形式洩漏。如果您需要了解如何加密元資料，本指南將會示範，使用 GroupDocs.Signature 彈性的 API。完成本教學後，您將能夠：
- 在 Java 文件中序列化自訂元資料結構。
- 套用加密（範例使用 XOR 以示說明，但您會看到如何改用 AES）。
- 在簽署文件的同時嵌入加密的元資料。
- 將解決方案擴展至生產級的安全性與效能。
讓我們開始吧。
快速解答
- 「加密元資料」是什麼意思？ 它在簽署前以加密轉換保護隱藏的文件屬性。
- 需要哪個函式庫？ GroupDocs.Signature for Java 23.12 或更新版本。
- 需要授權嗎？ 免費試用可用於開發；正式環境必須使用完整授權。
- 我可以將 XOR 換成更強的演算法嗎？ 是的——實作 AES‑GCM 或其他已驗證的方案。
- 此方法是否與格式無關？ GroupDocs.Signature 支援超過 30 種檔案格式，包括 DOCX、PDF、XLSX、PPTX 等。
什麼是 Java 文件元資料加密？
在 Java 中加密文件元資料是指取得隨檔案一起傳遞的隱藏屬性，並套用加密轉換，使只有授權方能讀取。這可保護內部 ID、審閱者備註及其他敏感資料免於隨意檢視。
為何要加密文件元資料？
加密元資料可保護可能用於識別個人或揭露內部流程的敏感資訊。透過將這些隱藏屬性轉換為密文，您可符合 GDPR、HIPAA 等法規，維持稽核追蹤的完整性，並防止競爭者提取關鍵業務資料。此安全層與可見的數位簽章相輔相成，確保整份文件保持機密。
前置條件
必要的函式庫與相依性
- GroupDocs.Signature for Java（版本 23.12 或更新）– 核心簽署函式庫。
- Java Development Kit (JDK) – JDK 8 或以上。
- Maven 或 Gradle 用於相依性管理。
環境設定
建議使用具 Maven/Gradle 專案的 Java IDE（IntelliJ IDEA、Eclipse 或 VS Code）。
知識前提
- 基本的 Java（類別、方法、物件）。
- 了解文件元資料概念。
- 熟悉對稱式加密基礎。
設定 GroupDocs.Signature for Java
選擇您的建置工具並加入相依性。
Maven:
<dependency>
<groupId>com.groupdocs</groupId>
<artifactId>groupdocs-signature</artifactId>
<version>23.12</version>
</dependency>
Gradle:
implementation 'com.groupdocs:groupdocs-signature:23.12'
或者，您也可以直接從 GroupDocs.Signature for Java releases 下載 JAR 檔，手動加入專案（雖然建議使用 Maven/Gradle）。
取得授權步驟
- Free Trial – 限時提供完整功能。
- Temporary License – 延長評估。
- Full Purchase – 正式生產使用。
基本初始化與設定
Signature 類別是 GroupDocs.Signature 的核心物件，用於載入文件、套用簽章，並將結果寫回磁碟。
Signature signature = new Signature("YOUR_DOCUMENT_PATH");
將 "YOUR_DOCUMENT_PATH" 替換為您實際的 DOCX、PDF 或其他支援檔案路徑。
Pro tip: 將
Signature物件包在 try‑with‑resources 區塊中，或明確呼叫close()，以避免記憶體洩漏。
實作指南
如何在 Java 中建立自訂元資料結構
自訂的元資料類別定義了您想要保護的資訊結構，以及 GroupDocs.Signature 如何序列化它。透過在欄位上加上 @FormatAttribute 註解，您告訴函式庫每個元素的順序與格式，從而實現一致的加密與後續的反序列化。此類別成為簽署文件中嵌入的加密負載的藍圖。
class DocumentSignatureData {
@FormatAttribute(propertyName = "SignID")
private String ID;
public String getID() { return ID; }
public void setID(String value) { ID = value; }
@FormatAttribute(propertyName = "SAuth")
private final String Author;
public final String getAuthor() { return Author; }
public DocumentSignatureData(String author) { this.Author = author; }
@FormatAttribute(propertyName = "SDate", propertyFormat = "yyyy-MM-dd")
private Date Signed = new Date();
public final Date getSigned() { return Signed; }
public void setSigned(Date value) { Signed = value; }
@FormatAttribute(propertyName = "SDFact", propertyFormat = "N2")
private BigDecimal DataFactor = new BigDecimal(0.01);
public final BigDecimal getDataFactor() { return DataFactor; }
public void setDataFactor(BigDecimal value) { DataFactor = value; }
}
- @FormatAttribute 告訴 GroupDocs.Signature 如何序列化每個欄位。
- 依需求為此類別擴充任何額外的屬性。
為文件元資料實作自訂加密
實作自訂加密例程讓您能控制元資料位元組在儲存前的轉換方式。透過建立實作 IDataEncryption 介面的類別，您可以插入任何演算法——示範用的 XOR、正式環境的 AES‑GCM，甚至是自有方案。簽署過程會在元資料序列化時自動呼叫您的加密器。
class CustomXOREncryption implements IDataEncryption {
@Override
public byte[] encrypt(byte[] data) {
byte key = 0x5A;
byte[] encryptedData = new byte[data.length];
for (int i = 0; i < data.length; i++) {
encryptedData[i] = (byte) (data[i] ^ key);
}
return encryptedData;
}
@Override
public byte[] decrypt(byte[] data) {
// XOR decryption uses the same logic as encryption
return encrypt(data);
}
}
Important: XOR 不適用於正式環境的安全需求。部署前請改用 AES‑GCM 或其他已驗證的演算法。
如何使用加密元資料簽署文件
在簽署文件的同時嵌入加密的元資料，將隱藏資訊與數位簽章綁定，確保真偽與機密性。使用 MetadataSignOptions，您可指定要包含的元資料欄位並提供加密實作。Signature 物件隨後處理文件、套用簽章，並將加密負載寫入可見簽章元素旁邊。
MetadataSignOptions 是告訴 GroupDocs.Signature 要嵌入哪些元資料以及如何加密的設定物件。
DocumentSignatureData 保存將被序列化與加密的實際值。
WordProcessingMetadataSignature 代表單一元資料項目（例如作者、客製 ID），將附加於 Word 處理文件。
class SignWithMetadataCustomSerialization {
public static void run() throws Exception {
String filePath = "YOUR_DOCUMENT_DIRECTORY/SampleDocument.docx";
String outputFilePath = new File("YOUR_OUTPUT_DIRECTORY", "SignedDocument.docx").getPath();
try {
Signature signature = new Signature(filePath);
// Custom encryption instance
IDataEncryption encryption = new CustomXOREncryption();
MetadataSignOptions options = new MetadataSignOptions();
options.setDataEncryption(encryption);
DocumentSignatureData documentSignature = new DocumentSignatureData(System.getenv("USERNAME"));
documentSignature.setID(java.util.UUID.randomUUID().toString());
documentSignature.setSigned(new Date());
documentSignature.setDataFactor(new BigDecimal("11.22"));
WordProcessingMetadataSignature mdSignature = new WordProcessingMetadataSignature(
"Signature", documentSignature);
WordProcessingMetadataSignature mdAuthor = new WordProcessingMetadataSignature(
"Author", "Mr.Scherlock Holmes");
WordProcessingMetadataSignature mdDocId = new WordProcessingMetadataSignature(
"DocumentId", java.util.UUID.randomUUID().toString());
options.getSignatures().add(mdSignature);
options.getSignatures().add(mdAuthor);
options.getSignatures().add(mdDocId);
signature.sign(outputFilePath, options);
} catch (Exception e) {
throw new Exception(e.getMessage());
}
}
}
步驟說明
- 初始化 使用來源檔案的
Signature。 - 建立
IDataEncryption實作（CustomXOREncryption）。 - 設定
MetadataSignOptions並附加加密實例。 - 填充
DocumentSignatureData以您的自訂欄位。 - 建立 每筆元資料的
WordProcessingMetadataSignature物件。 - 加入 它們至選項集合，並呼叫
sign()。
Pro tip: 使用
System.getenv("USERNAME")可自動取得目前的作業系統使用者，對於稽核追蹤相當便利。
何時使用此方法
當文件包含機密識別碼、內部備註或必須避免未授權讀者取得的法規資料時，加密元資料是理想的做法。情境包括隱藏條款編號的法律合約、含有專有計算的財務報表、帶有患者 ID 的醫療紀錄，以及每個參與者僅能看到自身元資料的多方協議。對於完全公開的文件，此步驟可能不必要。
| 情境 | 為何要加密元資料？ |
|---|---|
| 法律合約 | 隱藏內部工作流程 ID 與審閱者備註。 |
| 財務報告 | 保護計算來源與機密數字。 |
| 醫療紀錄 | 保護患者識別碼與處理備註（HIPAA）。 |
| 多方協議 | 確保只有授權方能檢視嵌入的元資料。 |
對於需要透明的完全公開文件，請避免使用此技術。
安全性考量：超越 XOR 加密
為何 XOR 不足
XOR 加密僅是簡單的資料遮蔽，缺乏保護敏感元資料所需的密碼強度。靜態金鑰可能透過頻率分析被破解，且未內建完整性驗證，使負載易受竄改。為符合合規與安全需求，請將 XOR 換成具驗證功能的加密模式，例如 AES‑GCM，提供機密性與防篡改檢測。
生產級替代方案
AES‑GCM 範例（概念性）：
// Example pattern (not complete implementation)
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
SecretKeySpec keySpec = new SecretKeySpec(keyBytes, "AES");
cipher.init(Cipher.ENCRYPT_MODE, keySpec);
byte[] encrypted = cipher.doFinal(data);
- 同時提供機密性 與 認證。
- 被 NIST 認可，廣泛應用於企業安全。
金鑰管理： 將金鑰存放於安全保管庫（AWS KMS、Azure Key Vault），切勿硬編碼金鑰。
Action item: 將
CustomXOREncryption替換為實作IDataEncryption的 AES 類別。其餘簽署程式碼保持不變。
常見問題與解決方案
元資料未加密
- 確認已呼叫
options.setDataEncryption(encryption)。 - 確認您的加密類別正確實作
IDataEncryption。
文件簽署失敗
- 檢查檔案是否存在以及寫入權限。
- 確保授權已啟用（試用版可能已過期）。
簽署後解密失敗
- 加密與解密操作使用相同的金鑰。
- 確認您讀取的是正確的元資料欄位。
大檔案的效能瓶頸
- 批次處理文件（一次 10–20 份）。
- 及時釋放
Signature物件。 - 分析您的加密演算法；相較於 XOR，AES 只會帶來適度的額外負擔。
疑難排解指南
Signature 初始化失敗：
try {
Signature signature = new Signature(filePath);
} catch (Exception e) {
System.err.println("Failed to load document: " + e.getMessage());
// Verify: file exists, correct format, sufficient permissions
}
加密例外：
if (data == null || data.length == 0) {
throw new IllegalArgumentException("Cannot encrypt empty data");
}
簽署後缺少元資料：
System.out.println("Signatures added: " + options.getSignatures().size());
// Should be > 0
效能考量
- 記憶體： 釋放
Signature物件；大量工作時使用固定大小的執行緒池。 - 速度： 快取加密實例以減少物件建立開銷。
- 基準測試（約）：
- 5 MB DOCX 使用 XOR：200‑500 毫秒
- 同檔案使用 AES‑GCM：約 250‑600 毫秒
生產環境最佳實踐
- 將 XOR 換成 AES（或其他已驗證的演算法）。
- 使用安全金鑰存儲——切勿在原始碼中嵌入金鑰。
- 記錄簽署操作（誰、何時、哪個檔案）。
- 驗證輸入（檔案類型、大小、元資料格式）。
- 實作完整的錯誤處理，提供清晰訊息。
- 在上線前於測試環境測試解密。
- 保留稽核追蹤以符合合規需求。
結論
您現在已掌握使用 GroupDocs.Signature 加密元資料 的完整步驟說明：
- 使用
@FormatAttribute定義具型別的元資料類別。 - 實作
IDataEncryption（示範使用 XOR）。 - 簽署文件時附加加密的元資料。
- 升級至 AES 以達到生產級安全性。
接下來的步驟：嘗試不同的加密演算法、整合安全金鑰管理服務，並擴充元資料模型以符合您的特定業務需求。
常見問答
Q: 我可以使用除 XOR 之外的其他加密演算法嗎？
A: 當然可以。實作任何符合 IDataEncryption 介面的類別——建議使用 AES‑GCM，以獲得強大的機密性與完整性。
Q: 切換至 AES 時需要修改簽署程式碼嗎？
A: 不需要。只要您的自訂 AES 實作符合 IDataEncryption，即可直接將 CustomXOREncryption 實例換成新類別。
Q: 若以一般檢視器開啟已簽署的檔案，會看到加密的元資料嗎？
A: 元資料仍然是檔案的一部份，但會顯示為不可讀的二進位資料。只有您的解密程式能解讀它。
Q: 這會對檔案大小產生什麼影響？
A: 加密僅增加極少的開銷（通常每個元資料欄位只有幾個位元組），對整體文件大小的影響可忽略不計。
Q: 生產環境需要什麼授權？
A: 商業部署必須購買完整的 GroupDocs.Signature 授權。開發與測試階段可使用試用授權。
最後更新： 2026-07-06
測試環境： GroupDocs.Signature 23.12（Java）
作者： GroupDocs
