Úvod a motivace

Při implementaci digitálních podpisů v podnikově‑úrovňových systémech je bezpečnost nekompromitovatelná.
Ukládání certifikátu do lokálního souboru PFX nebo P12 je pohodlné, ale vystavuje soukromý klíč riziku vyzrazení nebo kompromitace. Naopak PKCS#11 hardwarové tokeny (např. USB dongly, čipové karty a HSM) uchovávají klíče uvnitř odolné hranice, čímž zajišťují, že klíč nikdy neopustí zařízení.

Tento příspěvek ukazuje, jak použít GroupDocs.Signature for .NET spolu s Pkcs11Interop k podepisování PDF dokumentů pomocí hardwarových tokenů. Přístup kombinuje pohodlí a soulad s předpisy: GroupDocs se stará o veškeré balení na úrovni PDF (pole podpisu, výpočet digestu, vložení), zatímco token provádí samotné kryptografické podepsání.

⚠️ Upozornění na ranou implementaci
Toto řešení je momentálně poskytováno jako raná implementace pro používání PKCS#11 digitálních podpisových donglů s GroupDocs.Signature.
I když umožňuje podepisování dokumentů pomocí hardwarových tokenů, důrazně doporučujeme provést další testování ve vašem vlastním prostředí, aby bylo zajištěno, že splňuje vaše požadavky na soulad a bezpečnost.
Velmi oceníme vaši zpětnou vazbu, výsledky testů a návrhy na vylepšení.

Výzva: Propojení PKCS#11 s podepisováním PDF

Integrace PKCS#11 tokenů do workflow podepisování dokumentů přináší několik ne‑triviálních výzev:

  1. Nízká úroveň složitosti – API PKCS#11 (Cryptoki) vyžaduje správu slotů, relací, handle a atributů pro nalezení správného soukromého klíče.
  2. Balíčkování na úrovni PDF – Podepsání PDF není jen podepsání bajtů: knihovna musí vypočítat správné digesty nad vybranými rozsahy bajtů, zabalit podpisy do kontejnerů CMS/PKCS#7, zahrnout časové razítko a vložit validační informace.
  3. Variace dodavatelů – Různé tokeny/dodavatelské moduly mohou vyžadovat vlastní mapování atributů nebo další middleware.
  4. Soulad a auditovatelnost – Produkční systémy potřebují robustní správu PINu, řízení životního cyklu relací, obnovu po chybách a logování.

Tento ukázkový projekt řeší výše uvedené body kombinací rozhraní ICustomSignHash v GroupDocs.Signature s Pkcs11Interop, čímž deleguje podepisování tokenu a nechává GroupDocs starat se o strukturu PDF.

Co ukázkový projekt dělá

  • Ukazuje podepisování PDF dokumentů pomocí PKCS#11 tokenů (dongle, čipová karta, HSM).
  • Podporuje náhradní řešení Windows Certificate Store: pokud je certifikát nainstalován ve Windows, kód jej může použít místo tokenu.
  • Implementuje vlastní podepisování hashů: GroupDocs vypočítá digest; token pouze podepíše hash.
  • Soukromý klíč zůstává na hardwaru po celou dobu – nikdy není exportován.
  • Logiku tokenu (relace, vyhledání klíče, podepisování) zapouzdřuje třída Pkcs11DigitalSigner.cs.
  • Poskytuje pomocnou logiku v Helpers.cs (např. vyhledávání certifikátu ve Windows Store).
  • Konfigurace je centralizována v Settings.cs.
  • Slouží jako referenční implementace, kterou můžete přizpůsobit svému prostředí.
Bridging PKCS#11 with PDF Signing

Nastavení a předpoklady

Předpoklady

  • .NET 6.0 nebo vyšší (nebo .NET Framework 4.6.2)
  • Platná PKCS#11 knihovna (DLL) od vašeho dodavatele tokenu
  • Hardwarový token (USB dongle, čipová karta nebo HSM) s platným certifikátem
  • GroupDocs.Signature for .NET (zkušební nebo licencovaná verze)
  • Knihovna Pkcs11Interop

Instalace

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

Otevřete řešení ve Visual Studio nebo ve svém oblíbeném IDE a ujistěte se, že jsou všechny závislosti vyřešeny.

Struktura repozitáře – podrobný rozbor

GroupDocs.Signature-for-.NET-PKCS11-Sample/
├── GroupDocs.Signature-for-.NET-PKCS11-Sample.csproj      # Projektový soubor
├── Program.cs                                             # Vstupní bod a tok použití
├── Settings.cs                                            # Konfigurace PKCS#11 / tokenu
├── Helpers.cs                                             # Pomocné funkce (Windows Store, filtrování certifikátů)
├── Pkcs11DigitalSigner.cs                                 # Implementuje ICustomSignHash pomocí PKCS#11
└── README.md                                              # Vysvětlení a instrukce k použití
  • Program.cs – orchestruje podepisování; demonstruje jak tok‑založený, tak Windows cert flow.
  • Settings.cs – obsahuje konstanty/placeholdery pro Pkcs11LibraryPath, TokenPin a CertificateSubject.
  • Helpers.cs – obsahuje kód pro vyhledání certifikátů ve Windows Store podle názvu subjektu (použito v náhradním flow).
  • Pkcs11DigitalSigner.cs – jádro logiky: načte PKCS#11 modul, otevře relaci, najde objekt soukromého klíče, podepíše digest a vrátí X509Certificate2 nebo implementaci callbacku pro podpis.
  • README.md – poskytuje přehled, výzvy a instrukce k použití (které doplňuje tento blog).

Vysvětlení kódu a průchod

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

Tato třída odděluje konfigurační detaily, aby je bylo možné snadno nahradit ve vašem nasazovacím prostředí.

Pkcs11DigitalSigner.cs — vysoká úroveň toku

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 je centrální metoda: přijímá digest vypočítaný GroupDocs a pomocí PKCS#11 API jej podepíše.
  • GetCertificateFromPkcs11 získává certifikát (s veřejným klíčem) uložený v tokenu, aby metadata podpisu byla správná.

Program.cs — tok použití

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

Klíčové body:

  • Vlastnost CustomSignHash objektu DigitalSignOptions je nastavena na tokenSigner, což umožňuje GroupDocs delegovat skutečné podepisování hashů na token.
  • Náhradní tok (zakomentovaný) ukazuje, jak přepnout na certifikát z Windows Store, pokud není hardwarový token k dispozici.

Případy užití a reálné scénáře

  • Indie a certifikáty vydávané USB dongly
    V Indii mnoho právně závazných e‑podpisů vyžaduje certifikáty uložené v USB donglech vydávaných certifikačními autoritami. Tento příklad umožňuje aplikacím (např. bránám dokumentů, portálům) integrovat se přímo s takovými dongly.
  • Podnikové workflow dokumentů
    Pro interní systémy jako správa smluv nebo schvalovací procesy zajišťuje hardwarové podepisování, že neoprávnění uživatelé nemohou padělat podpisy dokumentů.
  • Právní / regulované podepisování
    Vlády a regulované odvětví často vyžadují, aby podpisy pocházely z klíčů řízených hardwarem. Tato integrace pomáhá splnit přísné požadavky na audit a soulad.

Časté problémy a řešení

  • Nesprávná cesta ke knihovně → Cesta k PKCS#11 DLL musí odpovídat modulu vašeho dodavatele (např. softhsm2.dll, cryptoki.dll).
  • Zamčení nebo selhání PINu → Opakované špatné zadání PINu může token zamknout; ověřte politiku dodavatele.
  • Klíč nenalezen → Ujistěte se, že je zadán správný název subjektu; token musí obsahovat certifikát s odpovídajícím subjektem.
  • Chybějící ovladač nebo middleware → Některé tokeny vyžadují instalaci ovladačů dodavatele, než s nimi může Pkcs11Interop komunikovat.
  • Problémy s vlákny → Operace PKCS#11 nemusí být thread‑safe; používejte single‑threaded kontext, pokud dodavatel nepodporuje více vláken.
  • Timeouty nebo reset relací → Dlouhé operace mohou způsobit uzavření nebo vypršení relace; zajistěte správnou správu a úklid relací.

Bezpečnost a osvědčené postupy

  • Nikdy neukládejte produkční tajemství (PINy, cesty) přímo v kódu; používejte zabezpečenou konfiguraci nebo správu tajemství.
  • Používejte silné PINy a rotujte je podle politiky.
  • Logujte operace a chyby (bez logování citlivých PINů).
  • Omezte počet relací tokenu a po podepsání se okamžitě odhlaste.
  • Po podepsání ověřte podpis (kontrola řetězce, časové razítko).
  • Testujte napříč prostředími a typy tokenů (dongle/čipová karta/HSM).

Další kroky a zdroje

Chcete to vyzkoušet? Naklonujte repozitář, aktualizujte placeholdery a spusťte ukázku.
Témata, která můžete dále zkoumat:

  • Vlastní podepisování hashů (delegování digestu a podepisování tokenu)
  • Časové razítko a LTV / DSS vložení
  • Iterativní podepisování (více podpisů v jednom dokumentu)
  • Integrace s remote HSM službami nebo cloudovými úložišti tokenů

Externí odkazy