如何使用 C## 使用 HSM 对 PDF 进行数字签名

IronPDF 可通过 PKCS#11 API 使用硬件安全模块 (HSM) 实现安全的 PDF 签名，私钥永远不会离开物理设备，为需要防篡改数字签名的关键任务应用程序提供银行级别的安全性。

快速入门：使用 C# 中的 HSM 对 PDF 进行签名

1. 通过 NuGet 安装 IronPDF：Install-Package IronPdf 2.配置您的 HSM 设备（或使用 SoftHSM 进行测试）
2. 使用您的 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 配置问题有哪些？

如果在运行代码示例时遇到以下错误，请按照以下故障排除步骤进行调试和验证您的配置。 有关数字签名问题的其他帮助，请查阅我们的数字签名故障排除指南。

此 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 签名工作流程的补充，可确保您的文档安全基础架构保持稳健并符合行业标准。