HSM Kullanarak C# ile PDF'leri Dijital Olarak İmzalama

IronPDF, PKCS#11 API üzerinden Donanım Güvenlik Modülleri (HSM'ler) kullanarak güvenli PDF imzalama yapmanızı sağlar, burada özel anahtarlar fiziksel cihazdan ayrılmaz ve bankacılık seviyesinde güvenlik sunarak kırılmaz dijital imzalar gerektiren kritik uygulamalar için koruma sağlar.

Hızlı Başlangıç: C# ile HSM Kullanarak PDF İmzalama

1. IronPDF'i NuGet aracılığıyla yükleyin: Install-Package IronPdf
2. HSM cihazınızı yapılandırın (veya test için SoftHSM kullanın)
3. HSM kimlik bilgilerinizi kullanarak bir UsbPkcs11HsmSigner oluşturun:

   1. NuGet Paket Yöneticisi ile https://www.nuget.org/packages/IronPdf yükleyin

      PM > Install-Package IronPdf

   2. Bu kod parçasını kopyalayıp çalıştırın.

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

   3. Canlı ortamınızda test etmek için dağıtın

      Bugün projenizde IronPDF kullanmaya başlayın ücretsiz deneme ile

      

      Free 30 Day Trial
4. PDF'nizi oluşturun ve imzalayın:

   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. İmzanızı PDF görüntüleyicinizde doğrulayın

PDF belgesine imza eklemek birçok uygulamada yaygın bir gerekliliktir. Ancak, anahtarın kurcalanamayacağı yüksek güvenlik gerektiren kritik uygulamalar için gereklidir. Normal bir .pfx dosyası ile imzalama işlemi, evinizde ustalık anahtarına sahip olmak gibidir. Uygulama, belgeyi imzalamak için anahtarı belleğe yükler. Bilgisayar ele geçirilirse, anahtar çalınabilir.

Daha güvenli bir alternatif olarak Hardware Security Module (HSM) kullanmak önerilir. HSM (bir USB token gibi) ile özel anahtar cihazın içinde oluşturulur ve oradan ayrılamaz.

Bu süreç, belgeyi bir bankaya götürmek gibidir. Uygulama bir PIN sağlar ve HSM belgeyi kasasına alır, anahtarla damgalar ve damgalanmış belgeyi geri verir. Anahtar hiçbir zaman kasadan çıkmaz. Bu, ek güvenlik sağlar, çünkü anahtar kopyalanamaz veya çalınamaz.

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

Yaygin HSM Konfigurasyon Sorunlari Nelerdir?

Kod ornegini calistirirken asagidaki hatayi alirsaniz, bu sorun giderme adimlarini izleyerek konfigurasyonunuzu debug ve dogrulayabilirsiniz. Dijital imza sorunlari ile ilgili ek yardim icin dijital imza sorun giderme rehberimize basvurun.

Bu CKR_GENERAL_ERROR yaygin olarak program SoftHSM konfigurasyon dosyasini bulamadiginda veya .NET uygulamasi 32-bit surec olarak calisirken SoftHSM kutuphanesi 64-bit oldugunda meydana gelir.

Platform Hedefini Değiştirme

Bu hatanin yaygin bir nedeni mimari uyumsuzluktur. C# uygulamanız, 64-bit SoftHSM kütüphanesine (softhsm2-x64.dll) uymak için 64-bit bir işlem olarak çalıştırılmalıdır. Visual Studio proje özelliklerinizde, Platform hedefini 'Any CPU' veya 'x86' dan x64 a değiştirin, böylece uyumluluğu sağlayın.

Ortam Degiskeni Ayarlama

Diğer yaygın bir neden, programın SoftHSM'de .conf dosyasını bulamamasıdır. Kutuphane nereden bakacagini bilmelidir, bu nedenle sistem genelinde bir ortam degiskeni ayarlamalisiniz. Adı SOFTHSM2_CONF olan yeni bir değişken oluşturun ve değerini konfigürasyon dosyanızın tam yoluna ayarlayın (örn. D:\SoftHSM2\etc\softhsm2.conf). Değişiklikleri yaptiktan sonra Visual Studio'yu yeniden başlatmayi unutmayin.

Ayrica, degiskenin bulunup bulunmadigini doğrulamak icin bu satiri ekleyebilirsiniz:

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

Eğer konsol cikisi bos donduruyorsa, program ortam degiskenini bulamiyor. Onu ayarlamali, Visual Studio'yu veya bilgisayarinizi yeniden başlatmali ve yeniden denemelisiniz.

Uretim HSM Kurulumu Icin En Iyi Uygulamalar

Uretim ortamlari icin HSM ile imzalanmis PDF'ler yayinlarken, bu ek guvenlik onlemlerini goz onunde bulundurun:

1. Log Denetimi: Uyumu surdurmek ve erişimi takip etmek icin tüm HSM işlemleri icin kapsamli log tutma uygulayin
2. Sertifika Yonetimi: Organizasyonunuzun guvenlik politikalari dogrultusunda sertifikalari duzenli olarak güncelleyin ve rotruynin
3. Yedekleme Prosedürleri: HSM configurasyonlari icin uygun yedekleme ve kurtarma prosedürleri oluşturun
4. Performans Optimizasyonu: Imzalama performansini izleyin ve sik erisilen sertifikalar icin cacheleme stratejileri uygulayin

Bu uygulamalar standart PDF imzalama akisini tamamlar ve doküman guvenligi altyapinizin guclu ve endustri standartlarina uygun olmasini saglar.