1. IronPDF
  2. Guías
  3. Firmar archivos PDF con HSM

Cómo firmar digitalmente archivos PDF con C# usando HSM

Curtis Chau
Curtis Chau
Actualizado:
This article was translated from English: Does it need improvement?
Translated
View the article in English

IronPDF permite la firma segura de PDF mediante Módulos de Seguridad de Hardware (HSM) a través de la API PKCS#11, donde las claves privadas nunca salen del dispositivo físico, proporcionando seguridad de nivel bancario para aplicaciones de misión crítica que requieren firmas digitales a prueba de manipulaciones.

Inicio rápido: Firmar un PDF con HSM en C#

  1. Instale IronPDF a través de NuGet: Install-Package IronPdf
  2. Configure su dispositivo HSM (o utilice SoftHSM para realizar pruebas)
  3. Crea un UsbPkcs11HsmSigner con tus credenciales HSM:

    Nuget IconEmpieza a crear PDF con NuGet ahora:

    1. Instalar IronPDF con el gestor de paquetes NuGet

      PM > Install-Package IronPdf

    2. Copie y ejecute este fragmento de código.

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

    3. Despliegue para probar en su entorno real

      Empieza a utilizar IronPDF en tu proyecto hoy mismo con una prueba gratuita
      arrow pointer
  4. Genere su PDF y fírmelo: 
    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 la firma en su visor de PDF

Añadir una firma a un documento PDF es un requisito común en muchas aplicaciones. Sin embargo, las aplicaciones de misión crítica requieren una mayor seguridad en la que no se pueda manipular la clave. Una operación normal de firma con un archivo .pfx es como tener una llave maestra en casa. La aplicación carga la clave en la memoria para firmar el documento. Si el ordenador se ve comprometido, la clave puede ser robada.

Una alternativa más segura es utilizar un módulo de seguridad de hardware (HSM). Con un HSM (como un token USB), la clave privada se genera dentro del dispositivo y no puede salir de él.

Este proceso es como llevar el documento a un banco. La aplicación proporciona un PIN, y el HSM lleva el documento a la cámara acorazada, lo sella con la clave y devuelve el documento sellado. La llave nunca sale de la cámara acorazada. Esto proporciona seguridad adicional, ya que la clave no se puede copiar ni robar.

## Cómo firmar digitalmente archivos PDF con HSM
  1. Descargue la biblioteca IronPDF C# para firmar archivos PDF con HSM
  2. Importe su HSM existente o simúlelo con otras bibliotecas
  3. Crear un nuevo objeto UsbPkcs11HsmSigner
  4. Firme y guarde el PDF con SignAndSave
  5. Verifique la salida en PDF y el certificado con un visor de PDF

¿Cómo firmo archivos PDF con un HSM?

La firma con un HSM suele requerir un dispositivo físico, como un token USB, con el que interactúa la aplicación. IronPDF es compatible con estas operaciones, ya que tanto la biblioteca como los HSM estándar utilizan PKCS#11 como API común. Para fines demostrativos, esta guía utiliza un HSM simulado en lugar de uno físico.

En entornos de producción o de pruebas en vivo, no debe utilizar esta simulación. En su lugar, utilice su HSM real. Para entornos de producción, considere la posibilidad de implementar funciones adicionales de seguridad de PDF, como protección por contraseña y permisos, junto con la firma HSM para una protección completa de los documentos.

Para ejecutar esta simulación, primero debe instalar SoftHSM, OpenSSL y OpenSC para generar la clave y el token necesarios. Para obtener más información sobre el uso de SoftHSM, consulte su repositorio público de GitHub.

Antes de implementar la firma HSM, asegúrese de haber instalado correctamente IronPDF y configurado su clave de licencia para el uso en producción.

Empiece por crear un PDF a partir de una cadena HTML. En el ejemplo siguiente, definimos las rutas y credenciales para nuestro SoftHSM simulado. Esto incluye proporcionar la ruta absoluta al archivo de biblioteca SoftHSM .dll y al archivo de certificado .crt que ha creado.

A continuación, especifique la ruta de salida, que en este caso es output.pdf.

Defina tres cadenas: hsmTokenLabel, hsmPin y hsmKeyLabel. Estas cadenas distinguen entre mayúsculas y minúsculas y deben coincidir exactamente con las credenciales que creó al generar el token y el certificado con SoftHSM. A continuación, inicialice el objeto UsbPkcs11HsmSigner, pasando como parámetros la ruta de la biblioteca SoftHSM, el PIN, la etiqueta del token y la etiqueta de la clave.

Además, cree un PdfSignatureImage para añadir una representación visual de la firma en el documento. Por último, llama a SignAndSave, que utiliza el hsmSigner para firmar el documento y guardarlo en la ruta de salida especificada.

¿Qué aspecto tiene el código de firma 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)
$vbLabelText   $csharpLabel

El UsbPkcs11HsmSigner toma además dos parámetros opcionales: digestAlgorithm y signingAlgorithm. Por defecto, se establecen en SHA256 y RSA.

Trabajar con diferentes configuraciones de HSM

Los distintos dispositivos HSM pueden requerir configuraciones específicas. He aquí un ejemplo que muestra cómo configurar el firmante con algoritmos personalizados y gestionar firmas múltiples:

// 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)
$vbLabelText   $csharpLabel

Este enfoque es especialmente útil cuando se trabaja con ejemplos de firma digital que requieren normas de cumplimiento específicas o cuando es necesario añadir metadatos para realizar un seguimiento de los detalles de la firma.

¿Cuáles son los problemas comunes de configuración de HSM?

Si se encuentra con el error que se muestra a continuación mientras ejecuta el ejemplo de código, siga estos pasos de solución de problemas para depurar y verificar su configuración. Para obtener ayuda adicional con problemas de firmas digitales, consulte nuestra guía de solución de problemas de firmas digitales.

Este CKR_GENERAL_ERROR suele producirse cuando el programa no puede encontrar el archivo de configuración de SoftHSM o cuando la aplicación .NET se ejecuta como un proceso de 32 bits mientras que la biblioteca SoftHSM es de 64 bits.

Error de inicialización de PKCS#11 HSM mostrando CHR_GENERAL_ERROR en la salida de consola con seguimiento de pila completo

Cambiar la plataforma de destino

Una causa común de este error es un desajuste de arquitectura. Su aplicación C# debe ejecutarse como un proceso de 64 bits para que coincida con la biblioteca SoftHSM de 64 bits (softhsm2-x64.dll). En las propiedades del proyecto de Visual Studio, cambie el objetivo de plataforma de "Cualquier CPU" o "x86" a x64 para garantizar la compatibilidad.

Configuración de compilación de Visual Studio que muestra el objetivo de plataforma establecido en arquitectura x64 con símbolos de compilación condicional

Configuración de la variable de entorno

Otra causa común es que el programa no puede encontrar el archivo .conf en SoftHSM. Debe indicar a la biblioteca dónde buscar estableciendo una variable de entorno para todo el sistema. Cree una nueva variable llamada SOFTHSM2_CONF y establezca su valor en la ruta completa de su archivo de configuración (por ejemplo, D:\SoftHSM2\etc\softhsm2.conf). Recuerda reiniciar Visual Studio después de realizar los cambios.

Diálogo de variables de sistema de Windows con la variable de entorno SOFTISM2_CONF resaltada mostrando la ruta de configuración de HSM

Además, puede comprobar si se encuentra la variable añadiendo esta línea:

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

Si la salida de la consola aparece en blanco, el programa no puede encontrar la variable de entorno. Debes configurarlo, reiniciar Visual Studio o tu ordenador e intentarlo de nuevo.

Prácticas recomendadas para la implantación de HSM en producción

Al desplegar archivos PDF firmados por HSM en entornos de producción, tenga en cuenta estas medidas de seguridad adicionales:

  1. Registro de auditoría: Implemente un registro exhaustivo de todas las operaciones de HSM para mantener la conformidad y realizar un seguimiento del acceso
  2. Gestión de certificados: Actualice y rote periódicamente los certificados de acuerdo con las políticas de seguridad de su organización
  3. Procedimientos de copia de seguridad: Establecer procedimientos adecuados de copia de seguridad y recuperación para configuraciones HSM
  4. Optimización del rendimiento: Supervisar el rendimiento de la firma e implementar estrategias de almacenamiento en caché para los certificados de acceso frecuente

Estas prácticas complementan el flujo de trabajo estándar de firma de PDF y garantizan que su infraestructura de seguridad de documentos siga siendo sólida y cumpla las normas del sector.

Preguntas Frecuentes

¿Qué es la firma HSM y en qué se diferencia de la firma normal de PDF?

La firma HSM (Hardware Security Module) con IronPDF proporciona seguridad a nivel bancario, donde las claves privadas nunca salen del dispositivo físico. A diferencia de la firma normal de archivos .pfx, en la que las claves se cargan en la memoria y pueden verse comprometidas si se ataca el ordenador, la firma HSM mantiene la clave privada bloqueada dentro del dispositivo de hardware, por lo que es imposible copiarla o robarla.

¿Cómo se configura la firma HSM en C# para PDF?

Para configurar la firma HSM con IronPDF, instale primero la biblioteca a través de NuGet con "Install-Package IronPdf" y, a continuación, cree un objeto UsbPkcs11HsmSigner con sus credenciales HSM, incluida la ruta de la biblioteca, el PIN, la etiqueta de token y la etiqueta de clave. Por último, utilice el método SignAndSave para firmar el documento PDF.

¿Cuáles son las ventajas de seguridad de utilizar HSM para las firmas PDF?

El uso de HSM con IronPDF proporciona firmas digitales a prueba de manipulaciones, ideales para aplicaciones de misión crítica. El proceso es como llevar documentos a la cámara acorazada de un banco: la aplicación proporciona un PIN, el HSM firma el documento internamente y devuelve el documento firmado sin exponer nunca la clave privada, lo que garantiza que no se pueda copiar ni robar.

¿Puedo probar la firma HSM sin un dispositivo físico?

Sí, IronPDF le permite simular la firma HSM utilizando bibliotecas como SoftHSM para fines de desarrollo y pruebas. Sin embargo, para entornos de producción, debe utilizar un dispositivo HSM físico real para garantizar una seguridad adecuada.

¿Qué estándar API utiliza IronPDF para la comunicación HSM?

IronPDF utiliza el estándar API PKCS#11 para la comunicación HSM, lo que garantiza la compatibilidad con los dispositivos HSM estándar. Esta API común permite a IronPDF interactuar sin problemas con varios tokens de hardware HSM y módulos de seguridad.

¿Cómo puedo verificar que mi PDF se ha firmado correctamente con HSM?

Después de firmar un PDF con la funcionalidad HSM de IronPDF, puede verificar la firma abriendo el PDF firmado en cualquier visor de PDF estándar. El visor mostrará la información de la firma digital y confirmará la autenticidad e integridad del documento.

Curtis Chau
Curtis Chau
  Chatea con el equipo de ingeniería ahora
Escritor Técnico

Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien ...

Leer más
¿Listo para empezar?
Nuget Descargas 17,386,124 | Versión: 2026.2 recién lanzado