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

IronPDF 透過 PKCS#11 API 支援使用硬體安全模組 (HSM) 進行安全的 PDF 簽署，在此過程中私鑰絕不會離開實體裝置，為需要防篡改數位簽名的關鍵任務應用程式提供銀行級的安全性。

快速入門：使用 C# 透過 HSM 簽署 PDF 檔案

1. 透過 NuGet 安裝 IronPDF：Install-Package IronPdf
2. 設定您的 HSM 裝置（或使用 SoftHSM 進行測試）
3. 使用您的 HSM 憑證建立 UsbPkcs11HsmSigner：

   1. using NuGet 套件管理員安裝 https://www.nuget.org/packages/IronPdf

      PM > Install-Package IronPdf

   2. 請複製並執行此程式碼片段。

      var hsmSigner = new UsbPkcs11HsmSigner(libraryPath, pin, tokenLabel, keyLabel);

   3. 部署至您的生產環境進行測試

      立即透過免費試用，在您的專案中開始使用 IronPDF

      

      Free 30 Day Trial
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 會將文件移至儲存庫，使用金鑰進行加蓋，並返回已加蓋的文件。 金鑰絕不離開保管庫。 這提供了額外的安全保障，因為金鑰無法被複製或竊取。

: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)

// 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)

常見的 HSM 配置問題有哪些？

若在執行程式碼範例時遇到以下錯誤，請依照下列疑難排解步驟進行除錯並驗證您的設定。 若需有關數位簽章問題的進一步協助，請參閱我們的數位簽章疑難排解指南。

此 CKR_GENERAL_ERROR 錯誤通常發生於程式無法找到 SoftHSM 設定檔，或是 .NET 應用程式以 32 位元程序執行，而 SoftHSM 函式庫卻是 64 位元的情況。

變更目標平台

此錯誤的常見原因在於架構不匹配。 您的 C# 應用程式必須以 64 位元程序執行，以配合 64 位元的 SoftHSM 函式庫 (CHOOSE_x64)。 請在 Visual Studio 專案屬性中，將"平台目標"從"Any CPU"或"x86"變更為 x64，以確保相容性。

設定環境變數

另一個常見原因在於程式無法在 SoftHSM 中找到 .conf 檔案。 您必須透過設定全系統環境變數，告知函式庫應從何處尋找。 建立一個名為 SOFTHSM2_CONF 的新變數，並將其值設定為您的設定檔完整路徑（例如：D:\SoftHSM2\etc\softhsm2.conf）。 請記得在完成變更後重新啟動 Visual Studio。 softhsm2-x64.dll x64 SOFTHSM2_CONF

此外，您可以透過加入以下這行代碼來驗證是否找到該變數：

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 簽署工作流程，並確保您的文件安全基礎架構保持強健且符合產業標準。