Como assinar PDFs digitalmente com C# usando HSM

O IronPDF permite a assinatura segura de PDFs com assinatura digital usando Módulos de Segurança de Hardware (HSMs) por meio da API PKCS#11, onde as chaves privadas nunca saem do dispositivo físico, fornecendo segurança de nível bancário para aplicações de missão crítica que exigem assinaturas digitais à prova de adulteração.

Início rápido: Assinar um PDF com HSM em C#

1. Instale o IronPDF via NuGet: Install-Package IronPdf
2. Configure seu dispositivo HSM (ou use o SoftHSM para testes)
3. Crie um UsbPkcs11HsmSigner com suas credenciais HSM:

   1. Instale IronPDF com o Gerenciador de Pacotes NuGet

      PM > Install-Package IronPdf

   2. Copie e execute este trecho de código.

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

   3. Implante para testar em seu ambiente de produção.

      Comece a usar IronPDF em seu projeto hoje com uma avaliação gratuita

      

      Free 30 Day Trial
4. Gere seu PDF e assine-o:

   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. Verifique a assinatura no seu visualizador de PDF.

Adicionar uma assinatura a um documento PDF é um requisito comum em muitas aplicações. No entanto, aplicações de missão crítica exigem maior segurança, onde a chave não pode ser adulterada. Uma operação de assinatura normal com um arquivo .pfx é como ter uma chave mestra em casa. O aplicativo carrega a chave na memória para assinar o documento. Se o computador for comprometido, a chave poderá ser roubada.

Uma alternativa mais segura é usar um Módulo de Segurança de Hardware (HSM). Com um HSM (como um token USB), a chave privada é gerada dentro do dispositivo e não pode sair dele.

Esse processo é semelhante a levar o documento a um banco. O aplicativo fornece um PIN, e o HSM leva o documento para o cofre, carimba-o com a chave e devolve o documento carimbado. A chave nunca sai do cofre. Isso proporciona segurança adicional, pois a chave não pode ser copiada ou roubada.

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

Quais são os problemas comuns de configuração de HSM?

Se você encontrar o erro mostrado abaixo ao executar o exemplo de código, siga estas etapas de solução de problemas para depurar e verificar sua configuração. Para obter assistência adicional com problemas de assinatura digital, consulte nosso guia de solução de problemas de assinaturas digitais .

O erro CKR_GENERAL_ERROR geralmente ocorre quando o programa não consegue encontrar o arquivo de configuração do SoftHSM ou quando o aplicativo .NET está sendo executado como um processo de 32 bits, enquanto a biblioteca SoftHSM é de 64 bits.

Alterar o alvo da plataforma

Uma causa comum para esse erro é a incompatibilidade de arquitetura. Seu aplicativo C# deve ser executado como um processo de 64 bits para ser compatível com a biblioteca SoftHSM de 64 bits (softhsm2-x64.dll). Nas propriedades do seu projeto no Visual Studio, altere a Plataforma de destino de 'Any CPU' ou 'x86' para x64 para garantir a compatibilidade.

Definindo a variável de ambiente

Outra causa comum é que o programa não consegue encontrar o arquivo .conf no SoftHSM. Você precisa informar à biblioteca onde procurar, definindo uma variável de ambiente em todo o sistema. Crie uma nova variável chamada SOFTHSM2_CONF e defina seu valor como o caminho completo do seu arquivo de configuração (por exemplo, D:\SoftHSM2\etc\softhsm2.conf). Lembre-se de reiniciar o Visual Studio após fazer as alterações.

Além disso, você pode verificar se a variável foi encontrada adicionando esta linha:

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

Se a saída do console estiver em branco, o programa não conseguiu encontrar a variável de ambiente. Você precisa configurar isso, reiniciar o Visual Studio ou o computador e tentar novamente.

Melhores práticas para implantação de HSM em produção

Ao implementar PDFs assinados por HSM em ambientes de produção, considere estas medidas de segurança adicionais:

1. Registro de auditoria : Implemente um registro abrangente para todas as operações do HSM para manter a conformidade e rastrear o acesso.
2. Gerenciamento de Certificados : Atualize e rotacione os certificados regularmente, de acordo com as políticas de segurança da sua organização.
3. Procedimentos de backup : Estabeleça procedimentos adequados de backup e recuperação para as configurações do HSM.
4. Otimização de desempenho : Monitore o desempenho da assinatura e implemente estratégias de cache para certificados acessados ​​com frequência.

Essas práticas complementam o fluxo de trabalho padrão de assinatura de PDFs e garantem que sua infraestrutura de segurança de documentos permaneça robusta e em conformidade com os padrões do setor.