💡 完整可運作的範例可在 GitHub 上取得: sign-pdf-with-vault-managed-key-java

舊方式令人痛苦

Java 簽署服務的作業手冊往往會包含一個沒有人願意寫下的步驟:將 signing.pfx 複製到新主機,然後把密碼放入環境變數。從那一刻起,私鑰會出現在至少三個超出預期的地方。它存在於映像層、主機的備份以及載入它的 JVM 記憶體中,堆疊轉儲(heap dump)會輕易地把它顯示給取得轉儲檔的人。

外部簽署是 GroupDocs.Signature 在 Java 中的一項功能,會將文件摘要交給您提供的回呼,而不是使用應用程式載入的私鑰進行簽署。這正是讓您可以刪除那個作業手冊步驟的關鍵。簽署金鑰移入 HashiCorp 金庫,服務只保留一個令牌而非金鑰,簽署過程中唯一跨網路傳遞的值是一個 32 位元組的雜湊。

當審查時有人問出顯而易見的問題——還有誰可以以您的名義簽署——團隊會使用此方式,因為誠實的答案是「任何曾取得該檔案的人」。即使透過權限與加密磁碟限制檔案存取,也只能縮小風險窗口,無法根除副本。

有更好的方法

Vault 的 Transit 引擎提供即服務的密碼學。您將值送給它,它使用持有的金鑰簽署,並回傳結果。透過在 Transit 中建立的金鑰可以標記為不可匯出,根本不需要將金鑰複製到主機上,且 Vault 不會儲存您送出的資料。

這只有在簽署函式庫能委派時才有用,而這正是 GroupDocs.Signature 發揮作用的地方。DigitalSignOptions.setCustomSignHash 接受一個回呼。函式庫負責完成所有簽署前的工作:開啟 PDF、計算簽章覆蓋的位元組範圍、雜湊、呼叫您的回呼取得摘要,最後將回傳的位元組與證書一起嵌入。

您需要 JDK 8 或更新版本、Maven、本機 Vault 的 Docker,以及用於產生證書的 BouncyCastle。此範例在 GroupDocs.Signature for Java 26.10 上執行;未授權時,評估模式僅接受最多 2 頁的文件。

新方式:使用回呼取代金鑰檔案

步驟 1 - 從 Vault 讀取金鑰

服務向 Vault 請求可使用的金鑰,並取得帶有公鑰的版本號。私鑰部分永遠不會出現在回應中。

VaultKey key = vault.readKey(KEY_NAME);
if (key == null) {
    vault.enableTransit();
    vault.createKey(KEY_NAME, "rsa-2048");
    key = vault.readKey(KEY_NAME);
}

Vault 回傳 404 代表金鑰或 Transit 掛載點不存在,範例會將其視為首次設定而非錯誤。正式環境中,管理員會先啟用 Transit 並事先建立金鑰,且應用程式的令牌不被允許執行這兩項操作。

先讀取一次版本號並保存。證書只能包含一個公鑰,因此證書與每筆簽署必須來自同一個版本。

步驟 2 - 以公鑰半部建構證書

PDF 簽章會攜帶 X.509 證書,以便驗證者取得公鑰。JDK 本身無法建構簽章來源於其他地方的證書,但 BouncyCastle 可以:X509v3CertificateBuilder 會委派給 ContentSigner,而以 Vault 為後端的 ContentSigner 只需要約十五行程式碼。

@Override
public byte[] getSignature() {
    try {
        byte[] digest =
            MessageDigest.getInstance("SHA-256").digest(data.toByteArray());
        return vault.signHash(keyName, keyVersion, digest, "sha2-256");
    } catch (IOException e) {
        throw new UncheckedIOException(e);
    }
}

BouncyCastle 會把待簽署的位元組寫入簽署者的串流,然後請求簽章。位元組在本機先雜湊,只有摘要會送到 Vault。介面不拋出受檢查例外,因此 Vault 失敗必須以包裝例外的方式傳遞;若不處理,Vault 回傳的 403 會變成難以理解的執行時錯誤。

步驟 3 - 簽署,然後在同一次執行中驗證

DigitalSignature digitalSignature = new DigitalSignature();
digitalSignature.setX509Certificate(certificate);

DigitalSignOptions options = new DigitalSignOptions();
options.setSignature(digitalSignature);
options.setCustomSignHash(signer::customSignHash);
options.setHashAlgorithm(HashAlgorithm.Sha256);

ByteArrayOutputStream signedPdf = new ByteArrayOutputStream();
signature.sign(signedPdf, options);
Files.write(outputPdf, trimTrailingZeros(signedPdf.toByteArray()));

在回呼內,摘要會送至 transit/sign,並帶有兩個決定結果是否有效的欄位:prehashed = true(因為輸入已是雜湊),以及 signature_algorithm = pkcs1v15(因為 Vault 預設對 RSA 金鑰使用 PSS,而 PDF 簽章使用 sha256WithRSAEncryption)。

接著在檔案送出前先驗證。一次執行中同時完成簽署與驗證,能把唯一的沉默失敗模式轉變為即時錯誤。

並排比較:前後對照

主機上的 PFX Vault Transit 回呼
私鑰的副本 每個主機、映像檔與備份各一份 一份,位於 Vault 內
服務保存的內容 金鑰及其密碼 一個限定於兩項操作的令牌
新主機的部署步驟 複製 PFX,設定密碼 無
每筆簽署的紀錄 應用程式日誌(若有寫入) 一筆 Vault 稽核條目
發現洩漏後 撤銷、重新發行、在所有地方重新部署 在 Vault 中輪換,重新發行一次
誰能以您的名義簽署 任何擁有檔案與密碼的人 任何持有有效 Vault 令牌的人

最後一行值得直白說明:這種做法是將祕密搬移,而非根除。差別在於令牌是短命的、可在單一位置撤銷、僅限讀取單一金鑰並呼叫簽署,且每次使用都會被記錄。

實務範例:對帳單服務

此服務會產生每月對帳單,並在放入客戶入口網站前簽署。舊方式下,容器映像會攜帶證書,且三位人員持有密碼,因為必須有人負責輪換。改用回呼後,映像根本不含任何祕密:Pod 在啟動時取得 AppRole 令牌,vault/sample-signer.hcl 中的政策允許讀取金鑰與簽署,其他任何操作都會回傳 403 permission denied。

當稽核人員詢問三月份簽署了多少文件以及使用了哪個金鑰版本時,答案來自 Vault 的稽核裝置,而不是從應用程式日誌中 grep 出來的。

輪換是此設計發揮價值的地方,同時也是可能出問題的環節。transit/keys/:name/rotate 之後,Vault 會使用最新版本簽署,除非您另有指定。因此,若使用為版本 1 建立的證書卻搭配版本 2 的簽章,產生的 PDF 仍會顯示「無錯誤」但驗證失敗。因為簽署器是以單一版本建構的,這種情況不會意外發生:對帳單服務會持續使用其證書所屬的版本簽署,直到有人為新版本頒發新證書。之後在金鑰上設定 min_encryption_version,舊版本即變為不可用,Vault 會回報「拒絕簽署」而非「簽章錯誤」。

在 26.10 版會遇到哪些怪癖?

在執行此建置時發現了四項怪癖。ICustomSignHash 方法名稱在 jar 中被混淆,因此請傳遞方法參考而非實作介面。簽署後的輸出會在簽章之外留下零位元組,需要將其截除。DigitalVerifyOptions 需要一個證書檔案,而非串流。最後,可見的簽章框需要安裝 Arial 字型。

GroupDocs.Signature 還能做什麼?

回呼本身不關心背後的實作,因此相同的三個步驟同樣適用於硬體模組、智慧卡或雲端 KMS。我將此範例從 .NET 與 Python 版本移植過來,Vault 的請求內容保持不變;證書建構與上述四項怪癖是唯一真正與 Java 相關的部分。除了數位簽章外,函式庫還能在 PDF、Word、Excel、PowerPoint 以及影像格式中加入與搜尋文字、影像、條碼、QR 代碼與中繼資料簽章。

結論

在 Java 中不持有私鑰即可簽署 PDF,需要一個回呼、一個以公鑰為基礎的證書,以及一個具備兩項權限的令牌。此範例可在兩條指令下對開發模式的 Vault 執行,透過變更 VAINT_ADDR 與 VAULT_TOKEN 即可指向正式環境的 Vault。

其他資源