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 eines PDFs mit HSM in C#-
Installieren Sie IronPDF über NuGet:
Install-Package IronPdf -
Konfigurieren Sie Ihr HSM-Gerät (oder verwenden Sie SoftHSM zum Testen)
-
Erstellen Sie ein
UsbPkcs11HsmSignermit Ihren HSM-Anmeldedaten:-
1Install IronPDF with NuGet Package Manager
-
2Kopieren Sie diesen Codeausschnitt und führen Sie ihn aus.
var hsmSigner = new UsbPkcs11HsmSigner(libraryPath, pin, tokenLabel, keyLabel);C# -
3Bereitstellen zum Testen in Ihrer Live-Umgebung
Beginnen Sie noch heute, IronPDF in Ihrem Projekt zu verwenden, mit einer kostenlosen Testversion
-
-
Generieren Sie Ihr PDF und unterschreiben Sie es:
var pdf = renderer.RenderHtmlAsPdf("<h1>Document</h1>"); pdf.SignAndSave("signed.pdf", hsmSigner);Dim pdf = renderer.RenderHtmlAsPdf("<h1>Document</h1>") pdf.SignAndSave("signed.pdf", hsmSigner) -
Ü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 Hauptschlü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 an, und das HSM bringt das Dokument in das 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.
Wie man PDFs mit HSM digital signiert
- Laden Sie die IronPDF C#-Bibliothek zum Signieren von PDFs mit HSM herunter
- Importieren Sie Ihr bestehendes HSM oder simulieren Sie es mit anderen Bibliotheken
- Erstellen Sie ein neues
UsbPkcs11HsmSignerObjekt - Unterschreiben und speichern Sie die PDF-Datei mit
SignAndSave - Überprüfen Sie die PDF-Ausgabe und das Zertifikat mit einem PDF-Viewer
Wie signiere ich PDFs 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 Verfahren kompatibel, da sowohl die Bibliothek als auch die Standard-HSMs PKCS#11 als gemeinsame API verwenden. Zur Veranschaulichung wird in diesem Leitfaden ein simuliertes HSM anstelle eines physischen HSMs verwendet.
In Produktions- oder Live-Testumgebungen sollten Sie diese Simulation nicht verwenden. Verwenden Sie stattdessen Ihr aktuelles HSM. Für Produktionsumgebungen sollten zusätzliche PDF-Sicherheitsfunktionen wie Passwortschutz und Berechtigungen neben der HSM-Signierung für einen umfassenden Dokumentenschutz implementiert werden.
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 Nutzung von SoftHSM finden Sie in deren öffentlichem GitHub-Repository.
Bevor Sie die HSM-Signierung implementieren, müssen Sie sicherstellen, dass Sie IronPDF ordnungsgemäß installiert und Ihren Lizenzschlüssel für den Produktionseinsatz konfiguriert haben.
Beginnen Sie mit der Erstellung einer PDF-Datei aus einem HTML-String. Im folgenden Beispiel definieren wir die Pfade und Anmeldeinformationen für unser simuliertes SoftHSM. Dazu gehört auch die Angabe des absoluten Pfads zur SoftHSM-Bibliotheksdatei .dll und zur von Ihnen erstellten Zertifikatsdatei .crt.
Geben Sie als Nächstes den Ausgabepfad an, der in diesem Fall output.pdf lautet.
Definieren Sie drei Zeichenfolgen: 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. Initialisieren Sie anschließend das UsbPkcs11HsmSigner-Objekt und übergeben Sie dabei den Pfad zur SoftHSM-Bibliothek, die PIN, die Token-Bezeichnung und die Schlüsselbezeichnung als Parameter.
Erstellen Sie außerdem ein PdfSignatureImage, um eine visuelle Darstellung der Signatur in das Dokument einzufügen. Rufen Sie abschließend SignAndSave auf, das hsmSigner verwendet, um das Dokument zu signieren und im angegebenen Ausgabepfad zu speichern.
Wie sieht der HSM-Signiercode aus?
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)UsbPkcs11HsmSigner akzeptiert zusätzlich zwei optionale Parameter: digestAlgorithm und signingAlgorithm. Standardmäßig sind sie auf SHA256 und RSA gesetzt.
Arbeiten mit verschiedenen HSM-Konfigurationen
Verschiedene HSM-Geräte können spezifische Konfigurationen erfordern. Hier ist ein Beispiel, das zeigt, wie man den Signierer mit benutzerdefinierten Algorithmen konfiguriert und mehrere Signaturen handhabt:
// 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)Dieser Ansatz ist besonders nützlich, wenn Sie mit Beispielen für digitale Signaturen arbeiten, die bestimmte Konformitätsstandards erfordern, oder wenn Sie Metadaten hinzufügen müssen, um Signaturdetails zu verfolgen.
Meine Lieblingsbibliothek dieser Art ist IronPDF. Es ermöglicht eine schnelle und effiziente Bearbeitung von PDF-Dateien. Es verfügt auch über viele wertvolle Funktionen, wie das Exportieren in das PDF/A-Format und das digitale Signieren von PDF-Dokumenten.
IronOCR bedeutet, dass wir jährlich 40.000 $ durch manuelle Verarbeitung einsparen können, während die Produktivität gesteigert wird und Ressourcen für wichtige Aufgaben freigesetzt werden. Ich würde es sehr empfehlen.
Die Iron Suite spielt eine entscheidende Rolle in unseren Operationen. Diese Werkzeuge erhöhen die Effizienz im gesamten Unternehmen, einschließlich der Erstellung von Grundrissen und der Verbesserung des Bestandsmanagements.
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, um mit der 64-Bit-SoftHSM-Bibliothek (CHOOSE_x64) kompatibel zu sein. Ändern Sie in den Eigenschaften Ihres Visual Studio-Projekts die Plattformausrichtung von "Any CPU" oder "x86" auf x64, um die Kompatibilität sicherzustellen.
Einstellung der Umgebungsvariable
Eine weitere häufige Ursache ist, dass das Programm die Datei .conf 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 mit dem Namen SOFTHSM2_CONF und setzen Sie deren 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. softhsm2-x64.dll x64 SOFTHSM2_CONF
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"")}")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:
- 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
- Zertifikatsverwaltung: Regelmäßige Aktualisierung und Rotation von Zertifikaten gemäß den Sicherheitsrichtlinien Ihres Unternehmens
- Sicherungsverfahren: Einrichtung geeigneter Sicherungs- und Wiederherstellungsverfahren für HSM-Konfigurationen
- 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.
Häufig gestellte Fragen
Was ist HSM-Signierung und wie unterscheidet sie sich von der normalen PDF-Signierung?
Die HSM-Signierung (Hardware Security Module) mit IronPDF bietet Sicherheit auf Bankniveau, wobei die privaten Schlüssel das physische Gerät nicht verlassen. Im Gegensatz zur normalen .pfx-Datei-Signierung, bei der die Schlüssel in den Speicher geladen werden und bei einem Angriff auf den Computer kompromittiert werden können, bleibt der private Schlüssel bei der HSM-Signierung im Hardware-Gerät eingeschlossen, so dass er weder kopiert noch gestohlen werden kann.
Wie konfiguriere ich die HSM-Signierung in C# für PDFs?
Um die HSM-Signierung mit IronPDF zu konfigurieren, installieren Sie zunächst die Bibliothek über NuGet mit "Install-Package IronPDF" und erstellen dann ein UsbPkcs11HsmSigner-Objekt mit Ihren HSM-Anmeldedaten, einschließlich des Bibliothekspfads, der PIN, des Token-Labels und des Schlüssel-Labels. Verwenden Sie schließlich die SignAndSave-Methode, um Ihr PDF-Dokument zu signieren.
Welche Sicherheitsvorteile bietet die Verwendung von HSM für PDF-Signaturen?
Die Verwendung von HSM mit IronPDF bietet fälschungssichere digitale Signaturen, die sich ideal für unternehmenskritische Anwendungen eignen. Der Prozess ist vergleichbar mit der Übergabe von Dokumenten an einen Banktresor - die Anwendung gibt eine PIN ein, das HSM signiert das Dokument intern und sendet das signierte Dokument zurück, ohne den privaten Schlüssel preiszugeben, so dass dieser nicht kopiert oder gestohlen werden kann.
Kann ich die HSM-Signierung ohne ein physisches Gerät testen?
Ja, IronPDF ermöglicht es Ihnen, die HSM-Signierung mithilfe von Bibliotheken wie SoftHSM für Entwicklungs- und Testzwecke zu simulieren. Für Produktionsumgebungen müssen Sie jedoch ein tatsächliches physisches HSM-Gerät verwenden, um eine angemessene Sicherheit zu gewährleisten.
Welchen API-Standard verwendet IronPDF für die HSM-Kommunikation?
IronPDF verwendet den PKCS#11-API-Standard für die HSM-Kommunikation und gewährleistet so die Kompatibilität mit Standard-HSM-Geräten. Diese gemeinsame API ermöglicht IronPDF die nahtlose Interaktion mit verschiedenen HSM-Hardware-Tokens und Sicherheitsmodulen.
Wie kann ich überprüfen, ob meine PDF-Datei erfolgreich mit HSM signiert wurde?
Nachdem Sie eine PDF-Datei mit der HSM-Funktion von IronPDF signiert haben, können Sie die Signatur überprüfen, indem Sie die signierte PDF-Datei in einem beliebigen Standard-PDF-Viewer öffnen. Der Viewer zeigt die digitalen Signaturinformationen an und bestätigt die Authentizität und Integrität des Dokuments.
How do I add a trusted timestamp to an HSM-signed PDF?
Set the TimeStampUrl property on the signer to the endpoint of an RFC 3161 Time Stamp Authority before calling SignAndSave. The endpoint is supplied as a string, and the resulting signature carries a timestamp token that readers such as Adobe Acrobat recognize. Leaving the property null or empty skips timestamping entirely and makes no network call.
Which hash algorithm does the HSM timestamp use?
TimestampHashAlgorithm selects the digest requested from the timestamp authority and accepts SHA1, SHA256, or SHA512. The built-in UsbPkcs11HsmSigner defaults to SHA256 through its AHsmSigner base class. A custom signer that implements IHsmSigner directly without deriving from AHsmSigner receives the uninitialized enum value, which is SHA1, so it should set the property explicitly. Note that this is separate from the digestAlgorithm constructor parameter, which governs the signature itself rather than the timestamp.
What causes a TimestampException during HSM signing?
TimestampException is thrown when a timestamp cannot be obtained or embedded. The three causes are an unreachable Time Stamp Authority, an authority that returns an empty token, and a timestamped signature that does not fit the reserved signature space, which can happen when a TSA returns a very large certificate chain. The exception message states the actual size against the reserved size.
Curtis Chau hat einen Bachelor-Abschluss in Informatik von der Carleton University und ist spezialisiert auf Frontend-Entwicklung mit Expertise in Node.js, TypeScript, JavaScript und React. Leidenschaftlich widmet er sich der Erstellung intuitiver und ästhetisch ansprechender Benutzerschnittstellen und arbeitet gerne mit modernen Frameworks sowie der Erstellung gut strukturierter, optisch ansprechender Handbücher.
