Jak cyfrowo podpisywać pliki PDF w języku C# przy użyciu modułu HSM

IronPDF umożliwia bezpieczne podpisywanie plików PDF przy użyciu modułów bezpieczeństwa sprzętowego (HSM) poprzez interfejs API PKCS#11, w którym klucze prywatne nigdy nie opuszczają fizycznego urządzenia, zapewniając bezpieczeństwo na poziomie bankowym dla aplikacji o znaczeniu krytycznym, wymagających odpornych na manipulacje podpisów cyfrowych.

Szybki start: Podpisywanie pliku PDF za pomocą modułu HSM w języku C#

1. Zainstaluj IronPDF za pomoca NuGet: Install-Package IronPdf
2. Skonfiguruj urządzenie HSM (lub użyj SoftHSM do testów)
3. Utworz UsbPkcs11HsmSigner z Twoimi poświadczeniami HSM:

   1. Install IronPDF with NuGet Package Manager

      PM > Install-Package IronPdf

   2. Skopiuj i uruchom ten fragment kodu.

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

   3. Wdrożenie do testowania w środowisku produkcyjnym

      Rozpocznij używanie IronPDF w swoim projekcie już dziś z darmową wersją próbną

      

      Free 30 Day Trial
4. Wygeneruj plik PDF i podpisz go:

   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. Zweryfikuj podpis w przeglądarce plików PDF

Dodawanie podpisu do dokumentu PDF jest częstym wymaganiem w wielu aplikacjach. Jednak aplikacje o znaczeniu krytycznym wymagają wyższego poziomu bezpieczeństwa, w którym klucz nie może zostać naruszony. Normalna operacja podpisywania z plikiem .pfx jest jak posiadanie klucza głównego w swoim domu. Aplikacja ładuje klucz do pamięci w celu podpisania dokumentu. Jeśli komputer zostanie zainfekowany, klucz może zostać skradziony.

Bardziej bezpieczną alternatywą jest użycie modułu bezpieczeństwa sprzętowego (HSM). W przypadku modułu HSM (np. tokena USB) klucz prywatny jest generowany wewnątrz urządzenia i nie może go opuścić.

Ten proces przypomina dostarczenie dokumentu do banku. Aplikacja podaje kod PIN, a moduł HSM przenosi dokument do skarbca, opatruje go kluczem i zwraca opatrzony kluczem dokument. Klucz nigdy nie opuszcza skarbca. Zapewnia to dodatkowe bezpieczeństwo, ponieważ klucza nie można skopiować ani ukraść.

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

Jakie są typowe problemy związane z konfiguracją modułów HSM?

Jeśli podczas uruchamiania przykładowego kodu pojawi się błąd pokazany poniżej, wykonaj poniższe kroki, aby go usunąć i sprawdzić konfigurację. Aby uzyskać dodatkową pomoc w kwestiach związanych z podpisami cyfrowymi, zapoznaj się z naszym przewodnikiem dotyczącym rozwiązywania problemów z podpisami cyfrowymi.

Ten błąd CKR_GENERAL_ERROR występuje zazwyczaj, gdy program nie może znaleźć pliku konfiguracyjnego SoftHSM lub gdy aplikacja .NET działa jako proces 32-bitowy, podczas gdy biblioteka SoftHSM jest 64-bitowa.

Zmiana platformy docelowej

Częstą przyczyną tego błędu jest niezgodność architektury. Twoja aplikacja C# musi działać jako proces 64-bitowy, aby pasować do 64-bitowej biblioteki SoftHSM (softhsm2-x64.dll). W właściwościach projektu Visual Studio zmień Platform target z 'Any CPU' lub 'x86' na x64, aby zapewnić kompatybilność.

Ustawianie zmiennej środowiskowej

Inną częstą przyczyną jest to, że program nie może odnaleźć pliku .conf w SoftHSM. Musisz wskazać bibliotece, gdzie ma szukać, ustawiając systemową zmienną środowiskową. Utwórz nową zmienną o nazwie SOFTHSM2_CONF i ustaw jej wartość na pełną ścieżkę do pliku konfiguracyjnego (np. D:\SoftHSM2\etc\softhsm2.conf). Pamietaj, aby zrestartować Visual Studio po wprowadzeniu zmian.

Dodatkowo, możesz zweryfikować, czy zmienna została odnaleziona, dodając tę linię:

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

Jeśli konsola zwraca puste wyjście, program nie może odnaleźć zmiennej środowiskowej. Musisz ją ustawić, zrestartować Visual Studio lub komputer i spróbować ponownie.

Najlepsze praktyki dotyczące wdrożenia HSM w środowiskach produkcyjnych

Podczas wdrażania plików PDF podpisanych przez HSM w środowiskach produkcyjnych, rozważ dodatkowe środki bezpieczeństwa:

1. Dzienniki audytu: Wdrażaj kompleksowe dzienniki dla wszystkich operacji HSM, aby zapewnić zgodność i śledzić dostęp
2. Zarządzanie certyfikatami: Regularnie aktualizuj i rotuj certyfikaty zgodnie z politykami bezpieczeństwa Twojej organizacji
3. Procedury tworzenia kopii zapasowych: Ustanów odpowiednie procedury tworzenia kopii zapasowych i odzyskiwania konfiguracji HSM
4. Optymalizacja wydajności: Monitoruj wydajność podpisywania i wdrażaj strategie buforowania dla często używanych certyfikatów

Te praktyki uzupełniają standardowy przepływ pracy podpisywania plików PDF i zapewniają, że infrastruktura zabezpieczeń dokumentów pozostaje solidna i zgodna ze standardami branżowymi.