如何使用 C## 使用 HSM 對 PDF 進行數位簽章。

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

IronPDF 可透過 PKCS#11 API 使用硬體安全模組 (HSM) 進行安全的 PDF 簽署,私密金鑰永遠不會離開實體裝置,為需要防篡改數位簽章的關鍵任務應用程式提供銀行等級的安全性。

快速入門:在 C# 中使用 HSM 簽署 PDF

1.透過 NuGet 安裝 IronPdf:Install-Package IronPdf。 2.設定您的 HSM 裝置 (或使用 SoftHSM 進行測試) 3.使用您的 HSM 認證建立 UsbPkcs11HsmSigner

Nuget Icon立即開始使用 NuGet 建立 PDF 檔案:

  1. 使用 NuGet 套件管理器安裝 IronPDF

    PM > Install-Package IronPdf

  2. 複製並運行這段程式碼。

    var hsmSigner = new UsbPkcs11HsmSigner(libraryPath, pin, tokenLabel, keyLabel);
  3. 部署到您的生產環境進行測試

    立即開始在您的專案中使用 IronPDF,免費試用!
    arrow pointer

4.生成您的 PDF 並簽署:

   var pdf = renderer.RenderHtmlAsPdf("<h1>Document</h1>");
   pdf.SignAndSave("signed.pdf", hsmSigner);
   var pdf = renderer.RenderHtmlAsPdf("<h1>Document</h1>");
   pdf.SignAndSave("signed.pdf", hsmSigner);
Dim pdf = renderer.RenderHtmlAsPdf("<h1>Document</h1>")
pdf.SignAndSave("signed.pdf", hsmSigner)
$vbLabelText   $csharpLabel

5.在 PDF 檢視器中驗證簽名

在許多應用程式中,為 PDF 文件添加簽名是一項常見需求。 然而,關鍵任務應用程式需要更高的安全性,其中的金鑰不能被篡改。 使用 .pfx 檔進行一般的 簽署作業就像是在家中擁有一把萬用鑰匙一樣。 應用程式會將金鑰載入記憶體以簽署文件。 如果電腦受到攻擊,金鑰可能會被竊取。

更安全的選擇是使用硬體安全模組 (HSM)。 使用 HSM(如 USB 令牌)時,私密金鑰會在裝置內部產生,無法離開裝置。

這個過程就像是將文件帶到銀行。 應用程式提供 PIN,HSM 將文件帶入儲存庫,用密鑰蓋章,然後將蓋章的文件傳回。 鑰匙從未離開保險庫。 這提供了額外的安全性,因為金鑰無法被複製或竊取。

如何使用 HSM 簽署 PDF?

使用 HSM 進行簽名通常需要一個實體設備,例如 USB 令牌,應用程式需要與該設備進行互動。 IronPdf 與這些作業相容,因為函式庫和標準 HSM 都使用 PKCS#11 作為共同的 API。 為了示範目的,本指南使用模擬 HSM 而非實體 HSM。

在生產或即時測試環境中,您不應該使用此模擬。 相反,請使用您實際的 HSM。 對於生產環境,請考慮實施其他 PDF 安全功能,例如 密碼保護和權限以及 HSM 簽署,以提供全面的文件保護。

要執行此模擬,您必須先安裝SoftHSMOpenSSLOpenSC以產生必要的金鑰和令牌。 如需使用 SoftHSM 的詳細資訊,請參閱其公開的 GitHub 儲存庫。

在實施 HSM 簽署之前,請確保您已正確 安裝 IronPDF 並配置您的 授權金鑰以供生產使用。

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

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

定義三個字串:hsmTokenLabel, hsmPin, 和 hsmKeyLabel. 這些字串區分大小寫,並且必須與您使用 SoftHSM 產生令牌和憑證時建立的憑證完全相符。 之後,初始化 UsbPkcs11HsmSigner 物件,傳入 SoftHSM 函式庫路徑、PIN、令牌標籤和金鑰標籤作為參數。

此外,請建立 PdfSignatureImage 以在文件上加入簽名的視覺表示。 最後,呼叫 SignAndSave 使用 hsmSigner 簽署文件並將其儲存到指定的輸出路徑。

HSM 簽署程式碼是什麼樣子?

: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);
Imports IronPdf
Imports IronPdf.Signing
Imports IronSoftware.Pdfium.Signing
Imports System.Drawing

Dim renderer As New ChromePdfRenderer()
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>Testing</h1>")

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

' Create the HsmSigner object.
Dim hsmSigner As New UsbPkcs11HsmSigner(softhsmLibraryPath, hsmPin, hsmTokenLabel, hsmKeyLabel)

' Create the Signature Image
Dim signatureImagePath As String = "IronSoftware.png"
Dim sigImage As New PdfSignatureImage(signatureImagePath, 0, New Rectangle(50, 50, 150, 150))

' Sign PDF with HSM
pdf.SignAndSave("signedWithHSM.pdf", hsmSigner)
$vbLabelText   $csharpLabel

UsbPkcs11HsmSigner 另外需要兩個可選參數:digestAlgorithmsigningAlgorithm 。 預設情況下,它們設定為SHA256RSA

使用不同的 HSM 組態工作

不同的 HSM 裝置可能需要特定的配置。 以下是一個範例,說明如何使用自訂演算法設定簽章器,以及處理多重簽章:

// Configure with custom algorithms
var customHsmSigner = new UsbPkcs11HsmSigner(
    hsmLibraryPath,
    hsmPin,
    hsmTokenLabel,
    hsmKeyLabel,
    digestAlgorithm: IronPdf.Signing.DigestAlgorithm.SHA512,
    signingAlgorithm: IronPdf.Signing.SigningAlgorithm.RSA
);

// Apply signature with custom location and reason
var signatureOptions = new SignatureOptions
{
    SignerName = "Corporate Signing Authority",
    Location = "Company Headquarters",
    Reason = "Contract Approval"
};

// Load existing PDF for signing
var existingPdf = PdfDocument.FromFile("contract.pdf");
existingPdf.SignAndSave("contract-signed.pdf", customHsmSigner, signatureOptions);
// Configure with custom algorithms
var customHsmSigner = new UsbPkcs11HsmSigner(
    hsmLibraryPath,
    hsmPin,
    hsmTokenLabel,
    hsmKeyLabel,
    digestAlgorithm: IronPdf.Signing.DigestAlgorithm.SHA512,
    signingAlgorithm: IronPdf.Signing.SigningAlgorithm.RSA
);

// Apply signature with custom location and reason
var signatureOptions = new SignatureOptions
{
    SignerName = "Corporate Signing Authority",
    Location = "Company Headquarters",
    Reason = "Contract Approval"
};

// Load existing PDF for signing
var existingPdf = PdfDocument.FromFile("contract.pdf");
existingPdf.SignAndSave("contract-signed.pdf", customHsmSigner, signatureOptions);
Imports IronPdf

' Configure with custom algorithms
Dim customHsmSigner As New UsbPkcs11HsmSigner(
    hsmLibraryPath,
    hsmPin,
    hsmTokenLabel,
    hsmKeyLabel,
    digestAlgorithm:=IronPdf.Signing.DigestAlgorithm.SHA512,
    signingAlgorithm:=IronPdf.Signing.SigningAlgorithm.RSA
)

' Apply signature with custom location and reason
Dim signatureOptions As New SignatureOptions With {
    .SignerName = "Corporate Signing Authority",
    .Location = "Company Headquarters",
    .Reason = "Contract Approval"
}

' Load existing PDF for signing
Dim existingPdf As PdfDocument = PdfDocument.FromFile("contract.pdf")
existingPdf.SignAndSave("contract-signed.pdf", customHsmSigner, signatureOptions)
$vbLabelText   $csharpLabel

當您使用需要特定合規標準的 數位簽章範例,或是需要 新增元資料來追蹤簽章詳細資料時,這種方法特別有用。

哪些是常見的 HSM 組態問題?

如果在執行程式碼範例時遇到以下錯誤,請依照下列故障排除步驟進行偵錯和驗證您的配置。 如需數位簽章問題的其他協助,請參閱我們的 數位簽章疑難排解指南

當程式找不到 SoftHSM 設定文件,或者 .NET 應用程式以 32 位元進程運行而 SoftHSM 庫為 64 位元時,通常會發生 CKR_GENERAL_ERROR 錯誤。

PKCS#11 HSM 初始化錯誤在控制台輸出中顯示 CHR_GENERAL_ERROR,並包含完整堆疊追蹤

變更平台目標

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

Visual Studio 建立組態顯示 Platform 目標設定為 x64 架構,並有條件編譯符號

設定環境變數

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

Windows 系統變數對話框,高亮顯示 SOFTISM2_CONF 環境變數,顯示 HSM 配置路徑

此外,您可以加入這一行來驗證是否找到變數:

Console.WriteLine($"Verifying variable: {Environment.GetEnvironmentVariable("SOFTHSM2_CONF")}");
Console.WriteLine($"Verifying variable: {Environment.GetEnvironmentVariable("SOFTHSM2_CONF")}");
Console.WriteLine($"Verifying variable: {Environment.GetEnvironmentVariable(""SOFTHSM2_CONF"")}")
$vbLabelText   $csharpLabel

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

生產 HSM 部署的最佳實作

在生產環境中部署 HSM 簽署的 PDF 時,請考慮這些額外的安全措施:

1.稽核記錄:針對所有 HSM 作業執行全面的記錄,以維持合規性並追蹤存取。 2.憑證管理:根據組織的安全政策定期更新和輪換憑證 3.備份程序:為 HSM 配置建立正確的備份和復原程序 4.效能最佳化:監控簽章效能,並針對經常存取的憑證實施快取策略

這些做法可補足標準 PDF 簽署工作流程,並確保您的文件安全基礎架構保持穩健且符合業界標準。

常見問題解答

什麼是 HSM 簽署,它與一般的 PDF 簽署有何不同?

IronPDF 的 HSM(硬體安全模組)簽署提供銀行等級的安全性,私密金鑰永遠不會離開實體裝置。一般的 .pfx 檔案簽章會將金鑰載入記憶體,如果電腦受到攻擊,金鑰就會外洩;HSM 簽章則不同,會將私密金鑰鎖定在硬體裝置中,使其無法複製或竊取。

如何在 C# 中為 PDF 配置 HSM 簽署?

若要使用 IronPDF 配置 HSM 簽署,首先透過 NuGet 以「Install-Package IronPdf」安裝函式庫,然後以您的 HSM 認證(包括函式庫路徑、PIN、令牌標籤和金鑰標籤)建立 UsbPkcs11HsmSigner 物件。最後,使用 SignAndSave 方法簽署 PDF 文件。

使用 HSM 進行 PDF 簽名有哪些安全性優點?

使用 IronPDF 的 HSM 可提供防篡改數位簽章,是關鍵任務應用程式的理想選擇。這個過程就像是將文件帶到銀行保險庫一樣 - 應用程式提供 PIN,HSM 在內部簽署文件,並在不洩露私密金鑰的情況下傳回已簽署的文件,確保文件不會被複製或竊取。

我可以在沒有實體裝置的情況下測試 HSM 簽章嗎?

是的,IronPdf 允許您使用 SoftHSM 之類的函式庫模擬 HSM 簽署,用於開發和測試目的。但是,對於生產環境,您必須使用實際的實體 HSM 裝置,才能確保適當的安全性。

IronPdf 使用何種 API 標準進行 HSM 通訊?

IronPDF 使用 PKCS#11 API 標準進行 HSM 通訊,確保與標準 HSM 裝置相容。此通用 API 可讓 IronPDF 與各種 HSM 硬體令牌和安全模組進行無縫互動。

如何驗證我的 PDF 已成功使用 HSM 簽署?

使用 IronPDF 的 HSM 功能簽署 PDF 之後,您可以在任何標準的 PDF 檢視器中開啟已簽署的 PDF 來驗證簽章。查看器將顯示數位簽章資訊,並確認文件的真實性和完整性。

Curtis Chau
技術撰稿人

Curtis Chau 擁有電腦科學學士學位(卡爾頓大學),專長於前端開發,精通 Node.js、TypeScript、JavaScript 和 React。Curtis 對製作直覺且美觀的使用者介面充滿熱情,他喜歡使用現代化的架構,並製作結構良好且視覺上吸引人的手冊。

除了開發之外,Curtis 對物聯網 (IoT) 也有濃厚的興趣,他喜歡探索整合硬體與軟體的創新方式。在空閒時間,他喜歡玩遊戲和建立 Discord bots,將他對技術的熱愛與創意結合。

準備好開始了嗎?
Nuget 下載 17,386,124 | 版本: 2026.2 剛剛發布