How to Digitally Sign PDFs with C# using HSM

Signing with an HSM

Signing with an HSM typically requires a physical device, such as a USB token, that the application interacts with. IronPDF is fully compatible with these operations, as both the library and standard HSMs often use PKCS#11 as a common API. For demonstrative purposes regarding IronPDF's functionality with HSMs, this guide will use a simulated HSM instead of a physical one.

In a production or live testing environment, you should not use this simulation. Instead, you must use your actual HSM.

To run this simulation, you must first install SoftHSM, OpenSSL, and OpenSC to generate the necessary key and token. For more information on how to utilize SoftHSM, please refer to their public GitHub repository.

We'll start by creating a PDF from an HTML string. In the example below, we define the paths and credentials for our simulated SoftHSM. This includes providing the absolute path to the SoftHSM .dll library file and the .crt certificate file that you created.

Next, we specify the output path, which in this instance is output.pdf.

Furthermore, we define three strings: hsmTokenLabel, hsmPin, and hsmKeyLabel. These strings are case-sensitive and must exactly match the credentials you created when generating the token and certificate with SoftHSM. Afterwards, we initialize the UsbPkcs11HsmSigner object, passing the SoftHSM library path, PIN, token label, and key label as parameters.

We additionally create a PdfSignatureImage to add a visual representation of the signature onto the document. Finally, we call SignAndSave, which uses the hsmSigner we configured to sign the document and save it to the specified output path.

: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

Output

Below is the output generated. As you can see, it displays the signature field and confirms that it is signed with the certificate we generated.

Troubleshooting

If you encounter the error shown below while running the code example, follow these troubleshooting steps to debug and verify your configuration. This CKR_GENERAL_ERROR commonly occurs when the program cannot find the SoftHSM configuration file or when the .NET application is running as a 32-bit process while the SoftHSM library is 64-bit.

Changing the Platform Target

A common cause for this error is an architecture mismatch. Your C# application must run as a 64-bit process to match the 64-bit SoftHSM library (softhsm2-x64.dll). In your Visual Studio project properties, change the Platform target from 'Any CPU' or 'x86' to 'x64' to ensure compatibility.

Setting the Environment Variable

Another common cause of error is that the program cannot find the .conf file in SoftHSM. You must tell the library where to look by setting a system-wide environment variable. Create a new variable named SOFTHSM2_CONF and set its value to the full path of your configuration file (e.g., D:\SoftHSM2\etc\softhsm2.conf). Afterwards, remember to restart Visual Studio after making the changes.

Additionally, you can verify whether the variable is found by adding this line.

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

If the console output returns blank, then the program can't find the environment variable. You must set it, restart Visual Studio or your computer, and try again.