Giriş ve Motivasyon

Kurumsal ölçekli sistemlerde dijital imzalar uygulanırken, güvenlik pazarlık edilemez.
Yerel bir PFX veya P12 dosyasında sertifika saklamak rahat olsa da özel anahtarın çıkarılması veya ele geçirilmesi riskini artırır. Buna karşı, PKCS#11 donanım tokenları (USB dongle’ları, akıllı kartlar ve HSM’ler gibi) anahtarları, kırılmaya karşı dayanıklı bir sınır içinde tutar ve anahtarların cihazdan dışarı çıkmasını engeller.

Bu gönderide GroupDocs.Signature for .NET ile Pkcs11Interop kullanarak PDF belgelerini donanım tokenlarıyla nasıl imzalayabileceğiniz gösterilmektedir. Yaklaşım, kolaylığı ve uyumluluğu birleştirir: GroupDocs, PDF düzeyinde paketlemeyi (imza alanları, özet hesaplama, gömme) hallederken token gerçek kriptografik imzayı gerçekleştirir.

⚠️ Erken Uygulama Bildirimi
Bu çözüm, PKCS#11 dijital imza dongle’larını GroupDocs.Signature ile kullanmak için şu anda erken bir uygulama olarak sunulmaktadır.
Donanım tokenlarıyla belge imzalama olanağı sağlasa da, uyumluluk ve güvenlik gereksinimlerinizi karşıladığından emin olmak için kendi ortamınızda ek testler yapmanızı şiddetle öneririz.
Geri bildiriminizi, test sonuçlarınızı ve iyileştirme önerilerinizi çok takdir ederiz.

Zorluk: PKCS#11’u PDF İmzalama ile Birleştirmek

PKCS#11 tokenlarını belge imzalama iş akışlarına entegre etmek birkaç önemli zorluk içerir:

  1. Düşük Seviye Karmaşıklık – PKCS#11 API’si (Cryptoki), doğru özel anahtarı bulmak için slot, oturum, tanıtıcı ve niteliklerin yönetilmesini gerektirir.
  2. PDF Düzeyinde Paketleme – Bir PDF’i imzalamak sadece baytları imzalamaktan ibaret değildir: kütüphane, seçili bayt aralıkları üzerinden doğru özetleri hesaplamalı, imzaları CMS/PKCS#7 kapsayıcılarına sarmalı, zaman damgası eklemeli ve doğrulama bilgilerini gömmelidir.
  3. Satıcı Varyasyonları – Farklı token/satıcı modülleri, özel nitelik eşlemeleri ya da ek ara katman yazılımı gerektirebilir.
  4. Uyumluluk ve Denetlenebilirlik – Üretim sistemleri, sağlam PIN yönetimi, oturum yaşam döngüsü kontrolü, hata kurtarma ve kayıt tutma gibi özelliklere ihtiyaç duyar.

Bu örnek proje, GroupDocs.Signature içindeki ICustomSignHash arayüzünü Pkcs11Interop ile birleştirerek imzalamayı tokena devretirken PDF yapısını GroupDocs’un işlemesine olanak tanır.

Örnek Projenin Yaptıkları

  • PKCS#11 tokenları (dongle, akıllı kart, HSM) kullanarak PDF belgelerini imzalama gösterir.
  • Windows sertifika deposu geri dönüş desteği: bir sertifika Windows’a yüklü ise, kod bunun yerine kullanılabilir.
  • Özel özet imzalama uygular: GroupDocs özeti hesaplar; token sadece özeti imzalar.
  • Özel anahtar donanım üzerinde tutulur — hiç dışa aktarılmaz.
  • Token mantığını (oturum, anahtar arama, imzalama) Pkcs11DigitalSigner.cs dosyasında kapsüller.
  • Helpers.cs içinde yardımcı mantık sağlar (örneğin Windows deposunda sertifika arama).
  • Konfigürasyon Settings.cs içinde merkezileştirilir.
  • Ortamınıza uyarlayabileceğiniz bir referans uygulama olarak hizmet verir.
PKCS#11’u PDF İmzalama ile Birleştirme

Kurulum ve Ön Koşullar

Ön Koşullar

  • .NET 6.0 veya üzeri (ya da .NET Framework 4.6.2)
  • Token satıcınızdan alınan geçerli bir PKCS#11 kütüphanesi (DLL)
  • Geçerli bir sertifikaya sahip bir donanım tokenı (USB dongle, akıllı kart veya HSM)
  • GroupDocs.Signature for .NET (deneme veya lisanslı)
  • Pkcs11Interop kütüphanesi

Kurulum

git clone https://github.com/groupdocs-signature/esign-documents-with-pkcs11-using-groupdocs-signature-dotnet.git
cd esign-documents-with-pkcs11-using-groupdocs-signature-dotnet
dotnet restore

Çözümü Visual Studio ya da tercih ettiğiniz IDE’de açın, bağımlılıkların çözüldüğünden emin olun.

Depo Yapısının Derin Analizi

GroupDocs.Signature-for-.NET-PKCS11-Sample/
├── GroupDocs.Signature-for-.NET-PKCS11-Sample.csproj      # Proje dosyası
├── Program.cs                                             # Giriş noktası ve kullanım akışı
├── Settings.cs                                            # PKCS#11 / token konfigürasyonu
├── Helpers.cs                                             # Yardımcı fonksiyonlar (Windows deposu, sertifika filtreleme)
├── Pkcs11DigitalSigner.cs                                 # PKCS#11 üzerinden ICustomSignHash uygular
└── README.md                                              # Açıklama ve kullanım talimatları
  • Program.cs – imzalama sürecini yönetir; hem token tabanlı hem de Windows sertifika akışını gösterir.
  • Settings.cs – Pkcs11LibraryPath, TokenPin ve CertificateSubject için sabit/yer tutucular içerir.
  • Helpers.cs – geri dönüş akışı için Windows deposunda konu adıyla sertifika bulma kodunu barındırır.
  • Pkcs11DigitalSigner.cs – çekirdek mantık: PKCS#11 modülünü yükler, oturumları açar, özel anahtar nesnesini bulur, bir özeti imzalar ve X509Certificate2 ya da bir imza geri çağırma implementasyonu döndürür.
  • README.md – bu blogun tamamlayıcı olduğu genel bakış, zorluklar ve kullanım talimatlarını sunar.

Kod Açıklaması ve Yol Haritası

Settings.cs

public static class Settings
{
    public const string Pkcs11LibraryPath = "<PKCS11_LIBRARY_PATH>";
    public const string TokenPin = "<TOKEN_PIN>";
    public const string CertificateSubject = "<CERT_SUBJECT>";
}

Bu sınıf, konfigürasyon detaylarını izole eder; böylece dağıtım ortamınızda kolayca değiştirilebilir.

Pkcs11DigitalSigner.cs — Yüksek Seviyeli Akış

public class Pkcs11DigitalSigner : ICustomSignHash
{
    public byte[] SignHash(byte[] hash)
    {
        // Bu yöntem, GroupDocs.Signature bir özetin token tarafından imzalanması gerektiğinde çağırılır
        using (var pkcs11 = new Pkcs11(Settings.Pkcs11LibraryPath, AppType.SingleThreaded))
        {
            // Modülü yükle, oturum aç, PIN ile giriş yap, anahtarı bul ve imzala
        }
    }

    public X509Certificate2 GetCertificateFromPkcs11()
    {
        // İmza seçeneklerinin doğru yapılandırılması için token içindeki herkese açık sertifikayı alır
    }
}
  • SignHash merkezi yöntemdir: GroupDocs tarafından hesaplanan özeti alır ve PKCS#11 API’lerini kullanarak imzalar.
  • GetCertificateFromPkcs11 token içinde depolanan herkese açık sertifikayı getirir, böylece imza meta verileri doğru olur.

Program.cs — Kullanım Akışı

class Program
{
    static void Main()
    {
        string inputFile = "sample.pdf";
        string outputFile = "signed.pdf";

        // (1) PKCS#11 imzalama
        var tokenSigner = new Pkcs11DigitalSigner();
        var cert = tokenSigner.GetCertificateFromPkcs11();

        using (var signature = new Signature(inputFile))
        {
            var options = new DigitalSignOptions(cert)
            {
                Comments = "PKCS#11 token ile imzalandı",
                SignTime = DateTime.Now,
                CustomSignHash = tokenSigner  // token tabanlı imzalamayı bağla
            };
            signature.Sign(outputFile, options);
        }

        // (2) Windows sertifika deposu geri dönüş (opsiyonel)
        // var storeCert = Helpers.GetCertificateFromWindowsStore(Settings.CertificateSubject);
        // using (var signature2 = new Signature(inputFile))
        // {
        //     var options2 = new DigitalSignOptions(storeCert) { ... };
        //     signature2.Sign("signed_store.pdf", options2);
        // }
    }
}

Öne çıkan noktalar:

  • DigitalSignOptions nesnesinin CustomSignHash özelliği tokenSigner olarak ayarlandığında, GroupDocs gerçek hash imzalamayı tokena devreder.
  • Yorum satırları içinde verilen geri dönüş akışı, donanım tokenı mevcut olmadığında Windows deposundaki sertifikaya geçişi gösterir.

Kullanım Senaryoları ve Gerçek Dünya Örnekleri

  • Hindistan & CA Tarafından Verilen USB İmza Dongle’ları
    Hindistan’da yasal bağlayıcılığı olan e‑İmzalar, sertifikaları sertifikalı otoriteler tarafından verilen USB dongle’larda saklamayı gerektirir. Bu örnek, belge geçitleri, portallar gibi uygulamaların doğrudan bu dongle’larla bütünleşmesini sağlar.
  • Kurumsal Belge İş Akışları
    Sözleşme yönetimi ya da onay süreçleri gibi iç sistemlerde, donanım imzalama yetkisiz kişilerin belge imzalarını taklit etmesini engeller.
  • Yasal / Uyumluluk Odaklı İmzalama
    Hükümetler ve düzenlenmiş sektörler, imzaların donanım kontrolündeki anahtarlardan gelmesini şart koşar. Bu entegrasyon, sıkı denetim ve uyumluluk gereksinimlerini karşılamaya yardımcı olur.

Yaygın Hatalar ve Sorun Giderme

  • Yanlış kütüphane yolu → PKCS#11 DLL yolu, token satıcınızın modülüne (ör. softhsm2.dll, cryptoki.dll) tam olarak uymalıdır.
  • PIN kilidi veya hatası → Yanlış PIN girişlerinin tekrarlanması tokenın kilitlenmesine sebep olabilir; satıcı politikalarını kontrol edin.
  • Anahtar bulunamadı → Doğru sertifika konu adının girildiğinden emin olun; token ilgili konu adına sahip sertifikayı içermelidir.
  • Sürücü ya da ara katman eksik → Bazı tokenlar, Pkcs11Interop’un iletişim kurabilmesi için satıcı sürücülerinin yüklü olmasını ister.
  • İş parçacığı (thread) sorunları → PKCS#11 işlemleri çoklu iş parçacığına uygun olmayabilir; satıcı destekliyorsa çoklu, aksi takdirde tek iş parçacıklı bağlam kullanın.
  • Zaman aşımı veya oturum sıfırlamaları → Uzun süren işlemler oturumların kapanmasına ya da zaman aşımına neden olabilir; oturum yönetimini ve temizlik işlemlerini uygun şekilde uygulayın.

Güvenlik ve En İyi Uygulamalar

  • Üretim gizli anahtarlarını (PIN, kütüphane yolları vb.) asla kod içinde sabit olarak tutmayın; güvenli konfigürasyon ya da gizli yönetim sistemleri kullanın.
  • Güçlü PIN’ler kullanın ve politika izin veriyorsa periyodik olarak değiştirin.
  • İşlemleri ve hataları (PIN gibi hassas bilgileri loglamadan) kaydedin.
  • Token oturumlarını sınırlı tutun ve imzalama sonrası hemen çıkış yapın.
  • İmzadan sonra imzayı doğrulayın (zincir kontrolü, zaman damgası).
  • Çeşitli ortamlar ve token tipleri (dongle/akıllı kart/HSM) üzerinde kapsamlı testler yürütün.

Sonraki Adımlar ve Kaynaklar

Kendiniz denemeye hazır mısınız? Depoyu klonlayın, yer tutucuları güncelleyin ve örneği çalıştırın. İleride keşfedebileceğiniz konular:

  • Özel Özet İmzalama (özet ve imzayı tokena devretmek)
  • Zaman Damgası ve LTV / DSS gömme
  • İteratif imzalama (tek bir belgede birden çok imza)
  • Uzak HSM servisleri veya bulut tabanlı token depoları entegrasyonu

Dış Bağlantılar