Firma HSM para TicketBAI, eIDAS y Crea y Crece: PAdES y XAdES con IronPDF en C

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. En España, la firma con HSM es el mecanismo de referencia para tres casos de uso normativos críticos:

1. TicketBAI en el País Vasco: las empresas en Bizkaia, Gipuzkoa y Araba que generan facturas de alto volumen usan HSMs con certificados FNMT o IZENPE (la autoridad de certificación del País Vasco) para firmar registros XAdES de forma masiva, cumpliendo las especificaciones forales sin exponer las claves privadas.
2. Firma cualificada eIDAS (QES): para documentos que requieren valor probatorio legal bajo eIDAS, la firma mediante HSM con un certificado cualificado emitido por la FNMT proporciona el nivel más alto de firma electrónica reconocida en toda la Unión Europea.
3. Crea y Crece y facturas B2B: la ley Crea y Crece exige firmas PAdES en facturas Facturae para el intercambio B2B. Los ISVs que generan decenas de miles de facturas por hora utilizan HSMs para gestionar las claves de firma sin riesgo de exposición.

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

1. Instala 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:

   1. Instala IronPDF con el Administrador 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

      Comienza a usar IronPDF en tu proyecto hoy mismo con una prueba gratuita

      

      Free 30 Day Trial
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 habitual en aplicaciones de facturación y gestión documental. Sin embargo, las aplicaciones de misión crítica —como los sistemas de facturación certificados para TicketBAI o VeriFactu— requieren mayor seguridad. Una firma normal con un fichero .pfx carga la clave en la memoria: si el servidor se ve comprometido, la clave puede ser robada y usada para generar facturas fraudulentas.

Un HSM mantiene la clave privada generada dentro del dispositivo y nunca permite que salga. La aplicación proporciona un PIN, el HSM lleva a cabo la operación de firma internamente y retorna el documento firmado. La clave nunca sale del dispositivo.

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

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

Si se encuentra con el error mostrado a continuación, siga estos pasos para depurar. Para ayuda adicional, consulte nuestra guía de solución de problemas de firmas digitales.

El error CKR_GENERAL_ERROR ocurre comúnmente cuando el programa no puede encontrar el fichero de configuración de SoftHSM o cuando la aplicación .NET se ejecuta como proceso de 32 bits mientras que la biblioteca de SoftHSM es de 64 bits.

Cambiar la plataforma de destino

Su aplicación C# debe ejecutarse como proceso de 64 bits para coincidir con la biblioteca de 64 bits de SoftHSM (CHOOSE_x64). En las propiedades del proyecto en Visual Studio, cambie el objetivo de la Plataforma de 'Any CPU' o 'x86' a x64.

Configuración de la variable de entorno

Indique a la biblioteca dónde buscar estableciendo una variable de entorno. Cree una nueva variable llamada SOFTHSM2_CONF con la ruta completa a su fichero de configuración (por ejemplo, D:\SoftHSM2\etc\softhsm2.conf). Reinicie Visual Studio después de realizar los cambios. softhsm2-x64.dll x64 SOFTHSM2_CONF

Para verificar que la variable está configurada:

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 aparece en blanco, configure la variable, reinicie Visual Studio y vuelva a intentarlo.

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

Al desplegar PDFs firmados con HSM para TicketBAI, Crea y Crece o eIDAS en entornos de producción:

1. Registro de auditoría: implemente un registro exhaustivo de todas las operaciones HSM para el seguimiento de acceso y la conformidad con la LOPDGDD y los requisitos de auditoría de la AEAT
2. Gestión de certificados FNMT/IZENPE: actualice y rote periódicamente los certificados conforme a las políticas de las autoridades de certificación. Los certificados FNMT tienen validez limitada y deben renovarse antes de su caducidad para evitar interrupciones en la facturación
3. Procedimientos de copia de seguridad: establezca procedimientos adecuados de recuperación para configuraciones HSM. Una clave perdida sin respaldo impide firmar facturas, lo que puede paralizar la operación de facturación bajo VeriFactu o TicketBAI
4. Optimización del rendimiento: supervise el rendimiento de firma e implemente estrategias de caché para certificados de acceso frecuente en sistemas de alta facturación como los requeridos por SII (Suministro Inmediato de Información) ante la AEAT

Estas prácticas complementan el flujo de firma de PDF y garantizan que su infraestructura de seguridad documental permanezca robusta ante inspecciones fiscales.