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

IronPDF, HSM'ler (Donanım Güvenliği Modülleri) kullanarak PKCS#11 API üzerinden güvenli PDF imzalama sağlar, burada özel anahtarlar fiziksel cihazdan ayrılmaz, bankacılık seviyesinde güvenlik sunar ve görev açısından kritik uygulamalar için sahtekarlığa karşı dayanıklı dijital imza gerektirir.

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

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

   1. IronPDF aşağıdaki NuGet Paket Yöneticisi ile yükleyin

      PM > Install-Package IronPdf

   2. Bu kod parçacığını kopyalayın ve çalıştırın.

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

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

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

      

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

Bir PDF belgesine imza eklemek birçok uygulamada yaygın bir gereksinimdir. Ancak görev açısından kritik uygulamalar daha yüksek güvenlik gerektirir, burada anahtar değiştirilemez. .pfx dosyasıyla yapılan normal bir imzalama işlemi, evinizde bir ana anahtar bulundurmak gibidir. Uygulama, belgeyi imzalamak için anahtarı belleğe yükler. Bilgisayar tehlikeye girerse, anahtar çalınabilir.

Daha güvenli bir alternatif Donanım Güvenliği Modülü (HSM) kullanmaktır. Bir HSM (USB anahtarı gibi) ile özel anahtar cihazın içinde oluşturulur ve dışarı çıkamaz.

Bu süreç, belgeyi bir bankaya götürmeye benzer. Uygulama bir PIN sağlar ve HSM belgeyi kasaya alır, anahtarla damgalar ve damgalı belgeyi geri döndürür. Anahtar asla kasadan çıkmaz. Bu, ilave 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)

Yaygın HSM Yapılandırma Sorunları Neler

Kod örneğini çalıştırırken aşağıdaki hatayla karşılaşırsanız, yapılandırmanızı hata ayıklamak ve doğrulamak için bu teşhis adımlarını izleyin. Dijital imza sorunları hakkında ek yardım için dijital imza sorun giderme kılavuzumuza bakın.

Bu CKR_GENERAL_ERROR hatası genellikle program SoftHSM yapılandırma dosyasını bulamadığında veya .NET uygulaması 32 bit işlemci olarak çalışırken SoftHSM kütüphanesi 64 bit olduğunda ortaya çıkar.

Platform Hedefini Değiştirme

Bu hatanın yaygın bir nedeni mimari uyumsuzluktur. C# uygulamanız, 64 bit SoftHSM kütüphanesiyle uyumlu olması için 64 bit işlem olarak çalışmalıdır (CHOOSE_x64). Uyumluluğu sağlamak için Visual Studio proje özelliklerinizde Platform hedefini 'Any CPU' veya 'x86'dan x64 olarak değiştirin.

Ortam Değişkeni Ayarlama

Diğer bir yaygın neden ise, programın SoftHSM'de .conf dosyasını bulamamasıdır. Sistemdeki ortam değişkenini ayarlayarak kütüphaneye nerede arayacağını söylemeniz gerekir. SOFTHSM2_CONF adlı yeni bir değişken oluşturun ve değerini yapılandırma dosyanızın tam yoluna ayarlayın (ör. D:\SoftHSM2\etc\softhsm2.conf). Değişiklikleri yaptıktan sonra Visual Studio'yu yeniden başlatmayı unutmayın. softhsm2-x64.dll x64 SOFTHSM2_CONF

Ek olarak, bu satırı ekleyerek değişkenin bulunup bulunmadığını doğrulayabilirsiniz:

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

Konsol çıktısı boş dönerse, program ortam değişkenini bulamaz. Ayarlayın, Visual Studio veya bilgisayarınızı yeniden başlatın ve tekrar deneyin.

Üretim HSM Dağıtımı için En İyi Uygulamalar

Üretim ortamlarında HSM imzalı PDF'leri dağıtırken bu ek güvenlik önlemlerini dikkate alın:

1. Denetim Kaydı: Erişimi izlemek ve uyumluluğu sürdürmek için tüm HSM işlemlerinin kapsamlı kaydını uygulayın
2. Sertifika Yönetimi: Organizasyonunuzun güvenlik politikalarına göre sertifikaları düzenli olarak güncelleyin ve değiştirin
3. Yedekleme Prosedürleri: HSM yapılandırması için doğru yedekleme ve kurtarma prosedürleri oluşturun
4. Performans Optimizasyonu: İmza performansını izleyin ve sık erişilen sertifikalar için önbellek stratejileri uygulayın

Bu uygulamalar, standart PDF imzalama iş akışını tamamlar ve belge güvenlik altyapınızın güçlü kalmasını sağlar ve endüstri standartlarına uyumlu hale getirir.