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

Firma 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 totalmente compatible con estas operaciones, ya que tanto la biblioteca como los HSM estándar suelen utilizar PKCS#11 como API común. A efectos de demostración de la funcionalidad de IronPDF con HSM, en esta guía se utilizará un HSM simulado en lugar de uno físico.

En un entorno de producción o de pruebas en vivo, no debe utilizar esta simulación. En su lugar, debe utilizar su HSM real.

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 cómo utilizar SoftHSM, consulte su repositorio público de GitHub.

Empezaremos creando 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, especificamos la ruta de salida, que en este caso es output.pdf.

Además, definimos 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, inicializamos 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, creamos un PdfSignatureImage para añadir una representación visual de la firma en el documento. Por último, llamamos a SignAndSave, que utiliza el hsmSigner que hemos configurado para firmar el documento y guardarlo en la ruta de salida especificada.

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

IRON VB CONVERTER ERROR developers@ironsoftware.com

Resultado

A continuación se muestra el resultado generado. Como puedes ver, muestra el campo de firma y confirma que está firmado con el certificado que hemos generado.

Solución de problemas

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. 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.

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 la variable de entorno

Otra causa común de error 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). A continuación, recuerda reiniciar Visual Studio tras realizar los cambios.

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

IRON VB CONVERTER ERROR developers@ironsoftware.com

$vbLabelText   $csharpLabel

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