Digitales Signieren von PDFs mit C# und HSM

Unterzeichnung eines Vertrags mit einem HSM

Die Signierung mit einem HSM erfordert typischerweise ein physisches Gerät, wie beispielsweise einen USB-Token, mit dem die Anwendung interagiert. IronPDF ist mit diesen Operationen vollständig kompatibel, da sowohl die Bibliothek als auch Standard-HSMs häufig PKCS#11 als gemeinsame API verwenden. Um die Funktionalität von IronPDF mit HSMs zu demonstrieren, wird in diesem Leitfaden ein simuliertes HSM anstelle eines physischen verwendet.

In einer Produktions- oder Live-Testumgebung sollten Sie diese Simulation nicht verwenden. Stattdessen müssen Sie Ihr eigentliches HSM verwenden.

Um diese Simulation auszuführen, müssen Sie zuerst SoftHSM , OpenSSL und OpenSC installieren, um den erforderlichen Schlüssel und das Token zu generieren. Weitere Informationen zur Verwendung von SoftHSM finden Sie in deren öffentlichem GitHub-Repository.

Wir beginnen damit, aus einer HTML-Zeichenkette eine PDF-Datei zu erstellen. Im folgenden Beispiel definieren wir die Pfade und Anmeldeinformationen für unser simuliertes SoftHSM. Dies beinhaltet die Angabe des absoluten Pfads zur SoftHSM .dll -Bibliotheksdatei und zur von Ihnen erstellten .crt Zertifikatsdatei.

Als nächstes geben wir den Ausgabepfad an, in diesem Fall output.pdf.

Des Weiteren definieren wir drei Zeichenketten: hsmTokenLabel , hsmPin , und hsmKeyLabel . Bei diesen Zeichenketten wird zwischen Groß- und Kleinschreibung unterschieden, und sie müssen exakt mit den Anmeldeinformationen übereinstimmen, die Sie bei der Generierung des Tokens und des Zertifikats mit SoftHSM erstellt haben. Anschließend initialisieren wir das UsbPkcs11HsmSigner Objekt, indem wir den Pfad zur SoftHSM-Bibliothek, die PIN, die Token-Bezeichnung und die Schlüsselbezeichnung als Parameter übergeben.

Zusätzlich erstellen wir ein PdfSignatureImage , um dem Dokument eine visuelle Darstellung der Signatur hinzuzufügen. Zum Schluss rufen wir SignAndSave auf, das den von uns konfigurierten hsmSigner verwendet, um das Dokument zu signieren und es im angegebenen Ausgabepfad zu speichern.

: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

Ausgabe

Nachfolgend die generierte Ausgabe. Wie Sie sehen können, wird das Signaturfeld angezeigt und bestätigt, dass es mit dem von uns generierten Zertifikat signiert ist.

Fehlerbehebung

Sollten Sie beim Ausführen des Codebeispiels auf den unten angezeigten Fehler stoßen, befolgen Sie diese Schritte zur Fehlerbehebung, um Ihre Konfiguration zu debuggen und zu überprüfen. Dieser CKR_GENERAL_ERROR tritt häufig auf, wenn das Programm die SoftHSM-Konfigurationsdatei nicht finden kann oder wenn die .NET-Anwendung als 32-Bit-Prozess ausgeführt wird, während die SoftHSM-Bibliothek 64-Bit ist.

Änderung des Plattformziels

Eine häufige Ursache für diesen Fehler ist eine Architekturinkompatibilität. Ihre C#-Anwendung muss als 64-Bit-Prozess ausgeführt werden, um mit der 64-Bit-SoftHSM-Bibliothek (softhsm2-x64.dll) kompatibel zu sein. Ändern Sie in den Eigenschaften Ihres Visual Studio-Projekts das Plattformziel von "Beliebige CPU" oder "x86" auf "x64", um die Kompatibilität sicherzustellen.

Festlegen der Umgebungsvariablen

Eine weitere häufige Fehlerursache ist, dass das Programm die .conf Datei in SoftHSM nicht finden kann. Sie müssen der Bibliothek mitteilen, wo sie suchen soll, indem Sie eine systemweite Umgebungsvariable festlegen. Erstellen Sie eine neue Variable namens SOFTHSM2_CONF und setzen Sie ihren Wert auf den vollständigen Pfad Ihrer Konfigurationsdatei (z. B. D:\SoftHSM2\etc\softhsm2.conf). Vergessen Sie anschließend nicht, Visual Studio nach den Änderungen neu zu starten.

Zusätzlich können Sie überprüfen, ob die Variable gefunden wird, indem Sie diese Zeile hinzufügen.

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

Wenn die Konsolenausgabe leer ist, kann das Programm die Umgebungsvariable nicht finden. Sie müssen die Einstellung vornehmen, Visual Studio oder Ihren Computer neu starten und es dann erneut versuchen.