如何使用 HSM 透過 C# 對 PDF 進行數位簽名

This article was translated from English: Does it need improvement?
Translated
View the article in English

在許多應用程式中,為 PDF 文件添加簽名是一項常見需求。 然而,關鍵任務型應用需要更高層級的安全性,金鑰本身不能被竄改。 使用.pfx檔案進行正常的簽章操作,就好比擁有一把家裡的萬能鑰匙。 該應用程式需要將密鑰載入到您的電腦記憶體中才能簽署文件。 如果電腦本身遭到入侵,密鑰可能會被盜。

更安全的替代方案是使用Hardware Security Module (HSM) 。 使用 HSM(例如您的 USB 令牌),私鑰在裝置內部生成,並且物理上永遠不可能離開裝置。

這個過程類似於把文件帶到銀行。 該應用程式提供一個 PIN 碼,"銀行經理"(HSM)將文件帶入金庫,用鑰匙蓋章,然後將蓋章後的文件交還給申請人。 關鍵在於鑰匙永遠不會離開金庫。 這提供了額外的安全保障,因為金鑰無法被複製或被盜。

立即開始在您的項目中使用 IronPDF 並免費試用。

第一步:
green arrow pointer

與 HSM 簽約

使用 HSM 進行簽名通常需要一個實體設備,例如 USB 令牌,應用程式需要與該設備進行互動。 IronPDF 與這些操作完全相容,因為該程式庫和標準 HSM 通常使用PKCS#11作為通用 API。 為了示範 IronPDF 與 HSM 的功能,本指南將使用模擬 HSM 而不是物理 HSM。

在生產環境或實際測試環境中,不應使用此模擬環境。 相反,您必須使用您實際的 HSM。

要執行此模擬,您必須先安裝SoftHSMOpenSSLOpenSC以產生必要的金鑰和令牌。 有關如何使用 SoftHSM 的更多信息,請參閱其公開的 GitHub 存儲庫。

我們將首先根據 HTML 字串建立 PDF 檔案。 在下面的範例中,我們定義了模擬 SoftHSM 的路徑和憑證。 這包括提供您建立的 SoftHSM .dll庫檔案和.crt憑證檔案的絕對路徑。

接下來,我們指定輸出路徑,在本例中為 output.pdf。

此外,我們定義了三個字串: hsmTokenLabelhsmPinhsmKeyLabel 。 這些字串區分大小寫,並且必須與您使用 SoftHSM 產生令牌和憑證時建立的憑證完全相符。 之後,我們初始化UsbPkcs11HsmSigner對象,並將 SoftHSM 庫路徑、PIN 碼、令牌標籤和金鑰標籤作為參數傳遞。

此外,我們還建立了一個PdfSignatureImage ,將簽署的視覺表示加入到文件中。 最後,我們呼叫SignAndSave ,它使用我們配置的 hsmSigner 對文件進行簽名並將其儲存到指定的輸出路徑。

程式碼

:path=/static-assets/pdf/content-code-examples/how-to/signing-with-hsm.cs
using IronPdf;
using IronPdf.Signing;
using IronSoftware.Pdfium.Signing;
using System.Drawing;

ChromePdfRenderer renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Testing</h1>");

// Define Paths and Credentials
string softhsmLibraryPath = @"D:\SoftHSM2\lib\softhsm2-x64.dll";
// These MUST match what you created
string hsmTokenLabel = "MyTestToken";
string hsmPin = "123456";
string hsmKeyLabel = "my-key"; // The label for the key *inside* the token

// Create the HsmSigner object.
UsbPkcs11HsmSigner hsmSigner = new UsbPkcs11HsmSigner(
    softhsmLibraryPath,
    hsmPin,
    hsmTokenLabel,
    hsmKeyLabel
);

// Create the Signature Image
string signatureImagePath = "IronSoftware.png";
PdfSignatureImage sigImage = new PdfSignatureImage(signatureImagePath, 0, new Rectangle(50, 50, 150, 150));

// Sign PDF with HSM
pdf.SignAndSave("signedWithHSM.pdf", hsmSigner);
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

UsbPkcs11HsmSigner也接受兩個可選參數,即digestAlgorithmsigningAlgorithm 。 預設情況下,它們設定為SHA256RSA

輸出

以下是產生的輸出結果。 如您所見,它顯示了簽名字段,並確認它是使用我們生成的證書簽署的。

輸出
輸出憑證

故障排除

如果在執行程式碼範例時遇到以下錯誤,請依照下列故障排除步驟進行偵錯和驗證您的配置。 當程式找不到 SoftHSM 設定文件,或者 .NET 應用程式以 32 位元進程運行而 SoftHSM 庫為 64 位元時,通常會發生 CKR_GENERAL_ERROR 錯誤。

一般 CKS 錯誤

更改平台目標

導致此錯誤的常見原因是架構不符。 您的 C# 應用程式必須以 64 位元進程運行,才能與 64 位元 SoftHSM 程式庫 (softhsm2-x64.dll) 相符。 在 Visual Studio 專案屬性中,將平台目標從"Any CPU"或"x86"變更為"x64",以確保相容性。

平台目標

設定環境變數

另一個常見的錯誤原因是程式在 SoftHSM 中找不到.conf檔。 您必須透過設定係統範圍的環境變數來告訴庫在哪裡尋找。 建立一個名為SOFTHSM2_CONF的新變量,並將其值設定為設定檔的完整路徑(例如,D:\SoftHSM2\etc\softhsm2.conf)。 之後,請記得在進行變更後重新啟動 Visual Studio。

設定環境變數

此外,您還可以透過新增以下程式碼行來驗證是否找到了該變數。

Console.WriteLine($"Verifying variable: {Environment.GetEnvironmentVariable("SOFTHSM2_CONF")}");
Console.WriteLine($"Verifying variable: {Environment.GetEnvironmentVariable("SOFTHSM2_CONF")}");
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

如果控制台輸出為空,則表示程式找不到該環境變數。 您必須進行設置,重新啟動 Visual Studio 或計算機,然後重試。

常見問題解答

什麼是硬體安全模組 (HSM),為何用於簽署 PDF?

硬體安全模組 (HSM) 是用來管理數位金鑰和執行加密與解密功能的實體裝置。它用於簽署 PDF,以確保簽署過程既安全又符合各種標準,從而提高安全性。

如何在 C# 中配置用於簽署 PDF 的 HSM?

要在 C# 中配置 HSM 以簽章 PDF,您需要使用適當的驅動程式和軟體設定 HSM,確保它已連接至您的系統,並使用 IronPDF 在您的 C# 應用程式中配置簽章程序。

使用 IronPDF 對 PDF 進行數位簽章的步驟是什麼?

要使用 IronPDF 對 PDF 進行數位簽章,您需要先初始化 HSM,在 C# 程式碼中設定數位簽章,並使用 IronPDF 的簽章功能將簽章套用至 PDF 文件。

我可以使用 IronPDF 以其他類型的數位憑證簽署 PDF 嗎?

是的,IronPDF 支援使用各種類型的數位憑證簽署 PDF,不僅限於由 HSM 管理的憑證。這包括儲存於軟體 keystores 的憑證。

使用 IronPDF 進行 PDF 簽署有哪些好處?

IronPDF 提供了直接的 API 來簽署 PDF,讓您可以輕鬆地將數位簽章整合到 C# 應用程式中。它支援各種證書類型,包括由 HSM 管理的證書,確保靈活性與安全性。

是否可以驗證使用 IronPDF 建立的 PDF 簽署?

是的,一旦使用 IronPDF 簽署了 PDF,就可以使用支援數位簽章的標準 PDF 閱讀器驗證簽章,確保文件的完整性和真實性。

使用 IronPDF 簽署 PDF 是否需要有編程經驗?

使用 IronPDF 簽署 PDF,建議具備 C# 的基本程式設計知識,因為這涉及編寫程式碼來管理簽署程序並適當配置 HSM。

在將 HSM 與 IronPDF 整合時,可以獲得哪些支援?

Iron Software 提供文件和技術支援,協助您將 HSM 與 IronPDF 整合,確保數位簽章功能的順利設定和運作。

Curtis Chau
技術作家

Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。

除了開發之外,Curtis 對物聯網 (IoT) 有著濃厚的興趣,探索將硬體和軟體結合的創新方式。在閒暇時間,他喜愛遊戲並構建 Discord 機器人,結合科技與創意的樂趣。

準備好開始了嗎?
Nuget 下載 16,493,056 | Version: 2025.11 剛發表