Digitales Signieren von PDFs mit C# HSM

IronPDF ermöglicht die sichere PDF-Signierung mit Hardware-Sicherheitsmodulen (HSMs) über die PKCS#11-API, bei der die privaten Schlüssel das physische Gerät nie verlassen, und bietet damit Sicherheit auf Bankniveau für unternehmenskritische Anwendungen, die fälschungssichere digitale Signaturen erfordern.

Schnellstart: Signieren einer PDF-Datei mit HSM in C#

1. Installieren Sie IronPDF über NuGet: Install-Package IronPdf
2. Konfigurieren Sie Ihr HSM-Gerät (oder verwenden Sie SoftHSM zum Testen)
3. Erstellen Sie einen UsbPkcs11HsmSigner mit Ihren HSM-Anmeldedaten:

   Legen Sie jetzt mit NuGet los, um PDFs zu erstellen:

   1. Installieren Sie IronPDF mit dem NuGet-Paketmanager.

      PM > Install-Package IronPdf

   2. Kopieren Sie diesen Codeausschnitt und führen Sie ihn aus.

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

   3. Bereitstellen zum Testen in Ihrer Live-Umgebung

      Beginnen Sie noch heute mit der Nutzung von IronPDF in Ihrem Projekt – mit einer kostenlosen Testversion.

      

      Kostenlose 30-Tage-Testversion
4. Generieren Sie Ihr PDF und unterschreiben Sie es:

   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. Überprüfen Sie die Signatur in Ihrem PDF-Viewer

Das Hinzufügen einer Signatur zu einem PDF-Dokument ist in vielen Anwendungen eine gängige Anforderung. Unternehmenskritische Anwendungen erfordern jedoch eine höhere Sicherheit, bei der der Schlüssel nicht manipuliert werden kann. Ein normaler Signiervorgang mit einer .pfx-Datei ist so, als hätte man einen Generalschlüssel für sein Haus. Die Anwendung lädt den Schlüssel in den Speicher, um das Dokument zu signieren. Wenn der Computer kompromittiert wird, kann der Schlüssel gestohlen werden.

Eine sicherere Alternative ist die Verwendung eines Hardware-Sicherheitsmoduls (HSM). Bei einem HSM (wie einem USB-Token) wird der private Schlüssel innerhalb des Geräts erzeugt und kann dieses nicht verlassen.

Dieser Prozess ist so, als würde man das Dokument zu einer Bank bringen. Die Anwendung gibt eine PIN ein, und der HSM nimmt das Dokument in den Tresor, stempelt es mit dem Schlüssel und gibt das gestempelte Dokument zurück. Der Schlüssel verlässt nie den Tresor. Dies bietet zusätzliche Sicherheit, da der Schlüssel nicht kopiert oder gestohlen werden kann.

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

Was sind häufige Probleme bei der HSM-Konfiguration?

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. Weitere Unterstützung bei Problemen mit digitalen Signaturen finden Sie in unserem Leitfaden zur Fehlerbehebung bei digitalen Signaturen.

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.

Das Plattformziel ändern

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

Einstellung der Umgebungsvariable

Eine weitere häufige Ursache 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). Denken Sie daran, Visual Studio nach den Änderungen neu zu starten.

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

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

Wenn die Konsolenausgabe leer bleibt, 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.

Best Practices für die produktive HSM-Bereitstellung

Wenn Sie HSM-signierte PDF-Dateien in Produktionsumgebungen einsetzen, sollten Sie diese zusätzlichen Sicherheitsmaßnahmen berücksichtigen:

1. Audit Logging: Implementierung einer umfassenden Protokollierung für alle HSM-Vorgänge, um die Einhaltung von Vorschriften zu gewährleisten und den Zugriff zu verfolgen
2. Zertifikatsverwaltung: Regelmäßige Aktualisierung und Rotation von Zertifikaten gemäß den Sicherheitsrichtlinien Ihres Unternehmens
3. Sicherungsverfahren: Einrichtung geeigneter Sicherungs- und Wiederherstellungsverfahren für HSM-Konfigurationen
4. Performance-Optimierung: Überwachung der Signierleistung und Implementierung von Caching-Strategien für häufig verwendete Zertifikate

Diese Praktiken ergänzen den standardmäßigen PDF-Signatur-Workflow und stellen sicher, dass Ihre Infrastruktur für die Dokumentensicherheit stabil und konform mit den Branchenstandards bleibt.