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

IronPDF透過 PKCS#11 API 使用硬體安全模組 (HSM) 實現安全的 PDF 簽名，私鑰永遠不會離開實體設備，為需要防篡改數位簽名的關鍵任務應用程式提供銀行級安全性。

快速入門：使用 C# 中的 HSM 對 PDF 進行簽名

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

   1. 使用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設定問題有哪些？

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

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

更改平台目標

導致此錯誤的常見原因是架構不符。 您的 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")}");

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

$vbLabelText   $csharpLabel

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

生產環境 HSM 部署最佳實踐

在生產環境中部署經 HSM 簽署的 PDF 檔案時，請考慮以下額外的安全措施：

1.審計日誌：對所有 HSM 操作實施全面的日誌記錄，以確保合規性並追蹤存取情況 2.證書管理：根據貴組織的安全策略定期更新和輪調證書。 3.備份程序：為 HSM 設定建立適當的備份和復原程序 4.效能最佳化：監控簽章效能並對常用憑證實施快取策略

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