Giriş ve Motivasyon

Kurumsal düzeyde sistemlerde dijital imzalar uygulanırken güvenlik pazarlık edilemez.
Sertifikanın yerel bir PFX veya P12 dosyasında saklanması kullanışlıdır ancak özel anahtarın çıkarılmasına veya ele geçirilmesine yol açabilir. Buna karşılık, PKCS#11 donanım tokenları (USB dongle’lar, akıllı kartlar ve HSM’ler gibi) anahtarları kırılmaya dayanıklı bir sınır içinde tutar ve anahtarların cihazdan dışarı çıkmasını engeller.

Bu gönderi, GroupDocs.Signature for .NET ile Pkcs11Interop kullanarak PDF belgelerini donanım tokenlarıyla imzalamayı gösterir. Yaklaşım, kullanım kolaylığı ve uyumluluğu birleştirir: GroupDocs, tüm PDF‑seviyesi paketlemeyi (imza alanları, özet hesaplama, gömme) yönetirken, 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 imzalamayı mümkün kılarken, uyumluluk ve güvenlik gereksinimlerinizi karşıladığından emin olmak için kendi ortamınızda ek testler yapmanızı şiddetle öneririz.
Geri bildirimlerinizi, test sonuçlarınızı ve iyileştirme önerilerinizi çok takdir ederiz.

Zorluk: PKCS#11 ile PDF İmzalama Arasındaki Köprü

PKCS#11 tokenlarını belge imzalama iş akışlarına entegre etmek birkaç zorluğu beraberinde getirir:

  1. Düşük‑Seviye Karmaşıklık – PKCS#11 API’si (Cryptoki), doğru özel anahtarı bulmak için slot, oturum, tutamaç ve öznitelik yönetimini gerektirir.
  2. PDF‑Seviyesi Paketleme – PDF imzalamak sadece baytları imzalamak değildir: kütüphane, seçilen bayt aralıkları üzerinde doğru özetleri hesaplamalı, imzaları CMS/PKCS#7 kapsayıcılarına sarmalı, zaman damgaları eklemeli ve doğrulama bilgilerini gömmelidir.
  3. Satıcı Varyasyonları – Farklı token/ satıcı modülleri özel öznitelik eşlemeleri veya ek ara katmanlar gerektirebilir.
  4. Uyumluluk & Denetlenebilirlik – Üretim sistemleri sağlam PIN yönetimi, oturum yaşam döngüsü kontrolü, hata kurtarma ve günlükleme gerektirir.

Bu örnek proje, GroupDocs.Signature içindeki ICustomSignHash arayüzünü Pkcs11Interop ile birleştirerek imzalamayı tokena devreder, PDF yapısını ise GroupDocs yönetir.

Örnek Projenin Yaptıkları

  • PDF belgelerini PKCS#11 tokenları (dongle, akıllı kart, HSM) ile imzalamayı gösterir.
  • Windows sertifika deposu geri dönüşünü destekler: Windows’da bir sertifika yüklüyse kod onu da kullanabilir.
  • Özel özet imzalama uygular: GroupDocs özeti hesaplar; token sadece özeti imzalar.
  • Özel anahtar donanımda kalır — asla dışa aktarılmaz.
  • Token mantığını (oturum, anahtar arama, imzalama) Pkcs11DigitalSigner.cs içinde kapsüller.
  • Helpers.cs içinde yardımcı mantık sağlar (örneğin Windows deposunda sertifika arama).
  • Ayarlar Settings.cs içinde merkezileştirilir.
  • Ortamınıza uyarlayabileceğiniz bir referans uygulama olarak hizmet eder.
Bridging PKCS#11 with PDF Signing

Kurulum & Önkoşullar

Önkoşullar

  • .NET 6.0 veya üzeri (veya .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ı Derin İnceleme

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 yapılandırması
├── Helpers.cs                                             # Yardımcı fonksiyonlar (Windows deposu, sertifika filtreleme)
├── Pkcs11DigitalSigner.cs                                 # ICustomSignHash’i PKCS#11 ile uygular
└── README.md                                              # Açıklama & kullanım talimatları
  • Program.cs – imzalamayı yönlendirir; hem token‑tabanlı hem de Windows sertifika akışını gösterir.
  • Settings.cs – Pkcs11LibraryPath, TokenPin ve CertificateSubject için sabit/yer tutucu değerleri içerir.
  • Helpers.cs – Windows deposunda konu adıyla sertifika bulma kodunu barındırır (geri dönüş akışı için kullanılır).
  • Pkcs11DigitalSigner.cs – çekirdek mantık: PKCS#11 modülünü yükler, oturumları açar, özel anahtar nesnesini bulur, bir özeti imzalar ve bir X509Certificate2 ya da imza geri çağırma uygulaması döndürür.
  • README.md – bu blogun tamamlayıcı olduğu genel bakış, zorluklar ve kullanım talimatlarını sunar.

Kod Açıklaması & Adım Adım İnceleme

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, yapılandırma detaylarını izole eder; böylece dağıtım ortamınızda kolayca değiştirilebilir.

Pkcs11DigitalSigner.cs — Yüksek‑Seviye Akış

public class Pkcs11DigitalSigner : ICustomSignHash
{
    public byte[] SignHash(byte[] hash)
    {
        // This method is invoked by GroupDocs.Signature when it needs the token to sign a hash
        using (var pkcs11 = new Pkcs11(Settings.Pkcs11LibraryPath, AppType.SingleThreaded))
        {
            // Load module, open session, login with PIN, find key and perform signing
        }
    }

    public X509Certificate2 GetCertificateFromPkcs11()
    {
        // Retrieves the public certificate from the token so the signing options can be configured
    }
}
  • SignHash, GroupDocs tarafından bir özet (hash) gerektiğinde çağrılan merkezi yöntemdir; ardından PKCS#11 API’leriyle imzayı gerçekleştirir.
  • GetCertificateFromPkcs11, imza meta verilerinin doğru olması için token içinde depolanan genel sertifikayı alır.

Program.cs — Kullanım Akışı

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

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

        using (var signature = new Signature(inputFile))
        {
            var options = new DigitalSignOptions(cert)
            {
                Comments = "Signed with PKCS#11 token",
                SignTime = DateTime.Now,
                CustomSignHash = tokenSigner  // link token-based signing
            };
            signature.Sign(outputFile, options);
        }

        // (2) Windows certificate store fallback (optional)
        // var storeCert = Helpers.GetCertificateFromWindowsStore(Settings.CertificateSubject);
        // using (var signature2 = new Signature(inputFile))
        // {
        //     var options2 = new DigitalSignOptions(storeCert) { ... };
        //     signature2.Sign("signed_store.pdf", options2);
        // }
    }
}

Önemli noktalar:

  • DigitalSignOptions nesnesinin CustomSignHash özelliği tokenSigner olarak ayarlandığında, GroupDocs özeti tokena devreder.
  • Yorum satırına alınmış geri dönüş akışı, donanım tokenı mevcut olmadığında Windows deposundaki sertifikaya geçişi gösterir.

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

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

Yaygın Hatalar & Sorun Giderme

  • Yanlış kütüphane yolu → PKCS#11 DLL yolu, token satıcınızın modülüyle (ör. softhsm2.dll, cryptoki.dll) aynı olmalıdır.
  • PIN kilidi veya hatası → Yanlış PIN girişlerinin tekrarı tokenı kilitleyebilir; satıcının politikasını kontrol edin.
  • Anahtar bulunamadı → Doğru sertifika konusu girildiğinden emin olun; token, aynı konuya sahip sertifikayı içermelidir.
  • Sürücü veya ara katman eksik → Bazı tokenlar, Pkcs11Interop’in iletişim kurabilmesi için satıcı sürücülerinin yüklü olmasını gerektirir.
  • İş parçacığı (thread) sorunları → PKCS#11 işlemleri çoklu iş parçacığına güvenli olmayabilir; satıcı desteklemiyorsa 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 veya zaman aşımına neden olabilir; oturum yönetimi ve temizlik işlemlerini doğru yapın.

Güvenlik & En İyi Uygulamalar

  • Üretim sırlarını (PIN, kütüphane yolları vb.) asla kod içinde sabitlemeyin; güvenli yapılandırma veya 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’leri loglamadan) kaydedin.
  • Token oturumlarını sınırlayın ve imzalama sonrası hemen oturumu kapatın.
  • İmzadan sonra imzayı doğrulayın (zincir kontrolü, zaman damgası vb.).
  • Çeşitli ortamlar ve token tipleri (dongle/akıllı kart/HSM) üzerinde kapsamlı testler yapın.

Sonraki Adımlar & Kaynaklar

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

  • Özel Özet İmzalama (özet + imzayı tokena devretme)
  • Zaman Damgası & LTV / DSS gömme
  • Iteratif imzalama (tek bir belgede birden fazla imza)
  • Uzak HSM servisleri veya bulut‑tabanlı token depoları ile entegrasyon

Dış Bağlantılar