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

Updated: 2026年6月4日

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

快速入門：使用 C# 和 HSM 簽署 PDF

通過 NuGet 安裝 IronPDF：Install-Package IronPdf
配置您的 HSM 裝置（或使用 SoftHSM 進行測試）
使用您的 HSM 憑證建立 UsbPkcs11HsmSigner：
1. 1Install IronPDF with NuGet Package Manager
  PM > Install-Package IronPdf
```
Install-Package IronPdf
```
2. 2複製並運行這段程式碼片段。
  var hsmSigner = new UsbPkcs11HsmSigner(libraryPath, pin, tokenLabel, keyLabel);
  C#
3. 3部署以在您的實時環境中測試
  
  今天就開始在您的專案中使用IronPDF，透過免費試用

生成您的 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)

Dim pdf = renderer.RenderHtmlAsPdf("<h1>Document</h1>")
pdf.SignAndSave("signed.pdf", hsmSigner)

在您的 PDF 檢視器中驗證簽名

在許多應用程式中，為 PDF 文件新增簽名是一個常見的需求。然而，關鍵應用程式需要更高的安全性，以防止密鑰被篡改。正常的使用 .pfx 文件的簽名操作就像在家裡擁有一把主鑰匙。應用程式將密鑰載入到記憶體中以簽署文件。如果電腦遭到入侵，密鑰可能會被竊取。

更安全的替代選擇是使用硬體安全模組 (HSM)。使用 HSM (如 USB 令牌)，私鑰是在裝置內部生成的，無法離開裝置。

此過程就像將文件帶到銀行。應用程式提供一個 PIN，HSM 將文件帶入金庫，使用密鑰蓋章，然後返回蓋章後的文件。密鑰永遠不會離開金庫。這提供了額外的安全性，因為密鑰無法被複製或竊取。

如何使用 HSM 進行 PDF 的數位簽名

下載用於 HSM 簽署 PDF 的 IronPDF C# 程式庫
導入您現有的 HSM 或使用其他程式庫進行模擬
建立一個新的 UsbPkcs11HsmSigner 物件
使用 SignAndSave 簽署並保存 PDF
使用 PDF 檢視器驗證 PDF 輸出和證書

如何使用 HSM 簽署 PDF？

using HSM 簽署通常需要一個物理裝置，如 USB 令牌，應用程式需要與其互動。 IronPDF 與這些操作相容，因為程式庫和標準 HSM 都使用 PKCS#11 作為通用 API。為了演示，本指南使用模擬的 HSM 而不是實體的。

在生產或現場測試環境中，不應該使用這種模擬。而是使用您的實際 HSM。對於生產環境，考慮實施額外的 PDF 安全功能，如密碼保護和許可權，與 HSM 簽名一起為文件提供全面的保護。

要運行此模擬，您必須首先安裝 SoftHSM、OpenSSL 和 OpenSC 來生成必要的密鑰和令牌。有關使用 SoftHSM 的更多資訊，請參閱他們的公共 GitHub 儲存庫。

在實施 HSM 簽名之前，確保已正確安裝 IronPDF 並配置您的授權金鑰以用於生產。

首先從 HTML 字串建立一個 PDF。在下面的範例中，我們為模擬的 SoftHSM 定義路徑和憑證。這包括提供 SoftHSM .dll 程式庫文件的絕對路徑以及您建立的 .crt 證書文件。

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

定義三個字串：hsmPin 和 hsmKeyLabel。這些字串區分大小寫，必須與您使用 SoftHSM 生成令牌和證書時建立的憑證完全匹配。然後，初始化 UsbPkcs11HsmSigner 物件，將 SoftHSM 程式庫路徑、PIN、令牌標籤和密鑰標籤作為參數傳遞。

此外，建立 PdfSignatureImage 以將簽名的視覺表示新增到文件上。最後，調用 SignAndSave，使用 hsmSigner 簽署文件並將其保存到指定的輸出路徑。

HSM 簽名程式碼看起來如何？

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

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)

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)

digestAlgorithm 和 signingAlgorithm。預設情況下，它們設置為 SHA256 和 RSA。

使用不同的 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)

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)

這種方法在使用需要特定合規標準的數位簽名範例或需要新增中繼資料來跟踪簽名詳細資訊時特別有用。

我最喜歡的程式庫是IronPDF。它允許快速高效地操作PDF文件。它還有許多有價值的功能，例如導出到PDF/A格式和數位簽署PDF文件。

Milan Jovanovic

Microsoft MVP

查看案例研究

IronOCR意味著我們每年可以從手動處理中節省$40,000，同時提高生產力，釋放資源以進行高影響的任務。我會強烈推薦它。

Brent Matzelle

首席技術官，OPYN

查看案例研究

常見的 HSM 配置問題是什麼？

如果在運行程式碼範例時遇到以下錯誤，請按照這些故障排除步驟進行除錯並驗證配置。有關解決數位簽名問題的更多幫助，請參閱我們的數位簽名問題解決指南。

該 CKR_GENERAL_ERROR 通常發生在程式無法找到 SoftHSM 配置文件或當. NET 應用程式以 32 位進程運行而 SoftHSM 庫是 64 位時。

PKCS#11 HSM 初始化錯誤顯示 CHR_GENERAL_ERROR 在控制台輸出中，帶有完整堆棧跟踪

更改平台目標

導致此錯誤的常見原因是架構不匹配。您的 C# 應用程式必須以 64 位進程運行，以匹配 64 位的 SoftHSM 程式庫 (CHOOSE_x64)。在您的 Visual Studio 專案屬性中，將平台目標從"任何 CPU"或"x86"更改為 x64 以確保相容性。

Visual Studio 構建配置顯示平台目標設置為 x64 架構，具有條件編譯符號

設置環境變數

另一個常見原因是程式無法在 SoftHSM 中找到 .conf 文件。您必須設定一個系統全域的環境變數來告訴程式庫在哪裡查找。建立一個名為 SOFTHSM2_CONF 的新變數，並將其值設置為配置文件的完整路徑（例如，D:\SoftHSM2\etc\softhsm2.co/nf）。更改後請記得重啟 Visual Studio。 softhsm2-x64.dll x64 SOFTHSM2_CONF

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"")}")

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

如果控制台輸出返回空白，則程式無法找到環境變數。您必須設定它，重啟 Visual Studio 或您的電腦，然後再試一次。

生產環境下部署 HSM 的最佳做法

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

審計日誌：實行全面的日誌記錄所有 HSM 操作以維持合規性和跟踪存取
證書管理：按照組織的安全策略定期更新和輪換證書
備份程式：為 HSM 配置建立正確的備份和恢復程式
性能優化：監控簽名性能並實施快取策略以提高頻繁使用證書的效能

這些做法補充標準的 PDF 簽名流程，並確保您的文件安全架構始終穩定並符合行業標準。

常見問題

HSM簽署是什麼？與常規PDF簽署有何不同？

使用IronPDF的HSM（硬體安全模組）簽署提供了銀行級別的安全性，私密金鑰不會離開實體裝置。與常規的.pfx檔簽署不同，後者會將金鑰載入到記憶體中，如果電腦受到攻擊，可能會被竊取，HSM簽署將私密金鑰鎖定在硬體裝置中，無法複製或竊取。

如何在C#中配置PDF的HSM簽署？

要使用IronPDF配置HSM簽署，首先通過NuGet安裝程式庫，使用'Install-Package IronPdf'，然後使用您的HSM證書，包含程式庫路徑、PIN、token標籤和金鑰標籤，建立一個UsbPkcs11HsmSigner物件。最後，使用SignAndSave方法來簽署您的PDF文件。