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

Updated: 4 czerwca 2026

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#

Zainstaluj IronPDF przez NuGet: Install-Package IronPdf
Skonfiguruj urządzenie HSM (lub użyj SoftHSM do testów)
Utwórz UsbPkcs11HsmSigner z użyciem swoich poświadczeń HSM:
1. 1Install IronPDF with NuGet Package Manager
  PM > Install-Package IronPdf
```
Install-Package IronPdf
```
2. 2Skopiuj i uruchom ten fragment kodu.
  var hsmSigner = new UsbPkcs11HsmSigner(libraryPath, pin, tokenLabel, keyLabel);
  C#
3. 3Wdrożenie do testowania w środowisku produkcyjnym
  
  Rozpocznij używanie IronPDF w swoim projekcie już dziś z darmową wersją próbną

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)

Dim pdf = renderer.RenderHtmlAsPdf("<h1>Document</h1>")
pdf.SignAndSave("signed.pdf", hsmSigner)

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 podpisania pliku .pfx jest jak posiadanie głównego klucza 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 dostarcza PIN, a HSM zabiera dokument do skarbca, stempluje go kluczem i zwraca ostemplowany dokument. Klucz nigdy nie opuszcza skarbca. Zapewnia to dodatkowe bezpieczeństwo, ponieważ klucza nie można skopiować ani ukraść.

Jak cyfrowo podpisywać pliki PDF za pomocą modułu HSM

Pobierz bibliotekę IronPDF C# do podpisywania plików PDF za pomocą modułu HSM
Zaimportuj istniejący moduł HSM lub zasymuluj go za pomocą innych bibliotek
Utwórz nowy obiekt UsbPkcs11HsmSigner
Podpisz i zapisz plik PDF za pomocą SignAndSave
Sprawdź plik PDF i certyfikat za pomocą przeglądarki plików PDF

Jak podpisywać pliki PDF za pomocą modułu HSM?

Podpisywanie za pomocą modułu HSM zazwyczaj wymaga fizycznego urządzenia, takiego jak token USB, z którym aplikacja wchodzi w interakcję. IronPDF jest kompatybilny z tymi operacjami, ponieważ zarówno biblioteka, jak i standardowe moduły HSM wykorzystują PKCS#11 jako wspólny interfejs API. W celach demonstracyjnych w niniejszym przewodniku wykorzystano symulowany moduł HSM zamiast fizycznego.

W środowiskach produkcyjnych lub testowych na żywo nie należy korzystać z tej symulacji. Zamiast tego użyj swojego rzeczywistego modułu HSM. W środowiskach produkcyjnych warto rozważyć wdrożenie dodatkowych funkcji zabezpieczeń plików PDF, takich jak ochrona hasłem i uprawnienia, a także podpisywanie za pomocą modułu HSM, aby zapewnić kompleksową ochronę dokumentów.

Aby uruchomić tę symulację, należy najpierw zainstalować SoftHSM, OpenSSL i OpenSC w celu wygenerowania niezbędnego klucza i tokenu. Więcej informacji na temat korzystania z SoftHSM można znaleźć w publicznym repozytorium GitHub.

Przed wdrożeniem podpisywania HSM upewnij się, że masz poprawnie zainstalowany IronPDF i skonfigurowany klucz licencyjny do użytku produkcyjnego.

Zacznij od utworzenia pliku PDF na podstawie ciągu znaków HTML. W poniższym przykładzie definiujemy ścieżki i poświadczenia dla naszego symulowanego SoftHSM. Obejmuje to zapewnienie absolutnej ścieżki do pliku biblioteki SoftHSM .dll oraz pliku certyfikatu .crt, który stworzyłeś.

Następnie określ ścieżkę wyjściową, która w tym przypadku to output.pdf.

Zdefiniuj trzy ciągi znaków: hsmTokenLabel, hsmPin i hsmKeyLabel. W tych ciągach znaków rozróżniana jest wielkość liter i muszą one dokładnie odpowiadać danym uwierzytelniającym utworzonym podczas generowania tokenu i certyfikatu za pomocą SoftHSM. Następnie zainicjalizuj obiekt UsbPkcs11HsmSigner, przekazując ścieżkę do biblioteki SoftHSM, PIN, etykietę tokenu i etykietę klucza jako parametry.

Dodatkowo, stwórz PdfSignatureImage, aby dodać wizualną reprezentację podpisu do dokumentu. Na koniec wywołaj SignAndSave, który używa hsmSigner, aby podpisać dokument i zapisać go w określonej ścieżce wyjściowej.

Jak wygląda kod podpisu HSM?

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

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)

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)

Metoda UsbPkcs11HsmSigner przyjmuje dodatkowo dwa opcjonalne parametry: digestAlgorithm i signingAlgorithm. Domyślnie są one ustawione na SHA256 i RSA.

Praca z różnymi konfiguracjami HSM

Różne urządzenia HSM mogą wymagać określonych konfiguracji. Oto przykład pokazujący, jak skonfigurować moduł podpisujący z niestandardowymi algorytmami i obsługiwać wiele podpisów:

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

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)

Takie podejście jest szczególnie przydatne podczas pracy z przykładami podpisów cyfrowych, które wymagają określonych standardów zgodności, lub gdy konieczne jest dodanie metadanych w celu śledzenia szczegółów podpisu.

Moją ulubioną biblioteką tego typu jest IronPDF. Umożliwia ona szybkie i efektywne manipulowanie plikami PDF. Posiada także wiele cennych funkcji, takich jak eksport do formatu PDF/A i cyfrowe podpisywanie dokumentów PDF.

Milan Jovanovic

Microsoft MVP

Zobacz studium przypadku

IronOCR pozwala nam oszczędzić 40 000 USD rocznie na ręcznym przetwarzaniu, jednocześnie zwiększając produktywność i uwalniając zasoby do zadań o wysokim wpływie. Gorąco polecam.

Brent Matzelle

Dyrektor technologiczny, OPYN

Zobacz studium przypadku

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 CKR_GENERAL_ERROR zwykle występuje, 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.

Błąd inicjalizacji modułu HSM PKCS#11 powodujący wyświetlenie komunikatu CHR_GENERAL_ERROR w konsoli wraz z pełnym śladem stosu

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 (CHOOSE_x64). W ustawieniach projektu Visual Studio zmień cel Platformy z 'Any CPU' lub 'x86' na x64, aby zapewnić zgodność.

Konfiguracja kompilacji programu Visual Studio pokazująca platformę docelową ustawioną na architekturę x64 z symbolami kompilacji warunkowej

Ustawianie zmiennej środowiskowej

Innym częstym powodem jest to, że program nie może znaleźć 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.co/nf). Pamietaj, aby zrestartować Visual Studio po wprowadzeniu zmian. softhsm2-x64.dll x64 SOFTHSM2_CONF

Dialog System Variables w Windows z wyróżnioną zmienną środowiskową SOFTISM2_CONF pokazującą ścieżkę konfiguracji HSM

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"")}")

Console.WriteLine($"Verifying variable: {Environment.GetEnvironmentVariable(""SOFTHSM2_CONF"")}")

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:

Dzienniki audytu: Wdrażaj kompleksowe dzienniki dla wszystkich operacji HSM, aby zapewnić zgodność i śledzić dostęp
Zarządzanie certyfikatami: Regularnie aktualizuj i rotuj certyfikaty zgodnie z politykami bezpieczeństwa Twojej organizacji
Procedury tworzenia kopii zapasowych: Ustanów odpowiednie procedury tworzenia kopii zapasowych i odzyskiwania konfiguracji HSM
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.

Często Zadawane Pytania

Czym jest podpisywanie HSM i czym różni się od zwykłego podpisywania plików PDF?

Podpisywanie za pomocą modułu HSM (Hardware Security Module) w IronPDF zapewnia bezpieczeństwo na poziomie bankowym, gdzie klucze prywatne nigdy nie opuszczają fizycznego urządzenia. W przeciwieństwie do zwykłego podpisywania plików .pfx, gdzie klucze są ładowane do pamięci i mogą zostać naruszone w przypadku ataku na komputer, podpisywanie za pomocą modułu HSM utrzymuje klucz prywatny zablokowany wewnątrz urządzenia sprzętowego, uniemożliwiając jego skopiowanie lub kradzież.

Jak skonfigurować podpisywanie HSM w języku C# dla plików PDF?

Aby skonfigurować podpisywanie za pomocą modułu HSM w IronPDF, najpierw zainstaluj bibliotekę za pośrednictwem NuGet, używając polecenia „Install-Package IronPdf”, a następnie utwórz obiekt UsbPkcs11HsmSigner z danymi uwierzytelniającymi modułu HSM, w tym ścieżką do biblioteki, kodem PIN, etykietą tokenu i etykietą klucza. Na koniec użyj metody SignAndSave, aby podpisać dokument PDF.

Jakie są korzyści dla bezpieczeństwa wynikające z użycia modułu HSM do podpisów PDF?

Wykorzystanie modułu HSM wraz z IronPDF zapewnia odporne na manipulacje podpisy cyfrowe, idealne do zastosowań o znaczeniu krytycznym. Proces ten przypomina przeniesienie dokumentów do skarbca bankowego — aplikacja generuje kod PIN, moduł HSM podpisuje dokument wewnętrznie i zwraca podpisany dokument bez ujawniania klucza prywatnego, co gwarantuje, że nie może on zostać skopiowany ani skradziony.

Czy mogę przetestować podpisywanie HSM bez fizycznego urządzenia?

Tak, IronPDF umożliwia symulację podpisywania za pomocą modułu HSM przy użyciu bibliotek takich jak SoftHSM do celów programistycznych i testowych. Jednak w środowiskach produkcyjnych należy używać rzeczywistego fizycznego urządzenia HSM, aby zapewnić odpowiedni poziom bezpieczeństwa.

Jakiego standardu API używa IronPDF do komunikacji z HSM?

IronPDF wykorzystuje standard API PKCS#11 do komunikacji z modułami HSM, zapewniając kompatybilność ze standardowymi urządzeniami HSM. To powszechne API pozwala IronPDF na płynną interakcję z różnymi tokenami sprzętowymi HSM i modułami bezpieczeństwa.

Jak mogę sprawdzić, czy mój plik PDF został pomyślnie podpisany za pomocą modułu HSM?

Po podpisaniu pliku PDF za pomocą funkcji HSM w IronPDF można zweryfikować podpis, otwierając podpisany plik PDF w dowolnej standardowej przeglądarce plików PDF. Przeglądarka wyświetli informacje o podpisie cyfrowym oraz potwierdzi autentyczność i integralność dokumentu.

Curtis Chau

Czat z zespołem inżynierów teraz

Autor tekstów technicznych

Curtis Chau posiada tytuł licencjata z informatyki (Uniwersytet Carleton) i specjalizuje się w front-endowym rozwoju, z ekspertką w Node.js, TypeScript, JavaScript i React. Pasjonuje się tworzeniem intuicyjnych i estetycznie przyjemnych interfejsów użytkownika, Curtis cieszy się pracą z nowoczesnymi frameworkami i tworzeniem dobrze zorganizowanych, atrakcyjnych wizualnie podręczników.

...

Czytaj więcej