Úvod a motivace

When implementing digital signatures in enterprise-grade systems, security is non-negotiable.
Storing a certificate in a local PFX or P12 file is convenient but exposes the private key to extraction or compromise. In contrast, PKCS#11 hardware tokens (such as USB dongles, smart cards, and HSMs) keep keys inside a tamper‑resistant boundary, ensuring they never leave the device.

This post demonstrates how to use GroupDocs.Signature for .NET together with Pkcs11Interop to sign PDF documents with hardware tokens. The approach combines convenience and compliance: GroupDocs handles all PDF-level packaging (signature fields, digest calculation, embedding), while the token performs the actual cryptographic signing.

⚠️ Upozornění na ranou implementaci
Toto řešení je momentálně poskytováno jako raná implementace pro
použití PKCS#11 digitálních podpisových donglů s GroupDocs.Signature.
Ačkoli 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 shodu 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 PDF podepisováním

Integrace tokenů PKCS#11 do workflow podepisování dokumentů má několik netriviá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 – Podepisování PDF není jen podepsání bytů: knihovna musí spočítat správné otisky přes vybrané rozsahy bytů, zabalit podpisy do kontejnerů CMS/PKCS#7, zahrnout časová razítka a vložit validační informace.
  3. Variace dodavatelů – Různé tokeny/moduly dodavatelů mohou vyžadovat vlastní mapování atributů nebo doplňkový middleware.
  4. Soulad a auditovatelnost – Produkční systémy potřebují robustní správu PIN, kontrolu životního cyklu relací, obnovu po chybách a logování.

Tento vzorový projekt řeší tyto výzvy kombinací rozhraní ICustomSignHash v GroupDocs.Signature s Pkcs11Interop, které deleguje podepisování na token, zatímco GroupDocs se stará o strukturu PDF.

Co vzorový projekt dělá

  • Ukazuje podepisování PDF dokumentů pomocí tokenů PKCS#11 (dongle, čipová karta, HSM).
  • Podporuje záložní řešení Windows certificate store: pokud je certifikát nainstalován ve Windows, kód jej může použít místo toho.
  • Implementuje vlastní podepisování hashů: GroupDocs spočítá otisk; token pouze podepíše hash.
  • Udržuje soukromý klíč na hardwaru po celou dobu — nikdy neexportován.
  • Zapouzdřuje logiku tokenu (relace, vyhledání klíče, podepisování) v souboru Pkcs11DigitalSigner.cs
  • Poskytuje pomocnou logiku v souboru Helpers.cs (např. vyhledání certifikátu ve Windows store).
  • Konfigurace centralizována v souboru Settings.cs.
  • Slouží jako referenční implementace, kterou můžete přizpůsobit svému prostředí.
Propojení PKCS#11 s PDF podepisováním

Nastavení a předpoklady

Požadavky

  • .NET 6.0 nebo novější (nebo .NET Framework 4.6.2)
  • Platná knihovna PKCS#11 (DLL) od vašeho dodavatele tokenu
  • Hardwarový token (USB dongle, čipová karta nebo HSM) s platným certifikátem
  • GroupDocs.Signature pro .NET (zkouška 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

Open solution in Visual Studio or your preferred IDE, ensure dependencies are resolved.

Podrobný rozbor struktury repozitáře

GroupDocs.Signature-for-.NET-PKCS11-Sample/
├── GroupDocs.Signature-for-.NET-PKCS11-Sample.csproj      # Project file
├── Program.cs                                             # Entry point and usage flow
├── Settings.cs                                            # PKCS#11 / token configuration
├── Helpers.cs                                             # Utility functions (Windows store, certificate filtering)
├── Pkcs11DigitalSigner.cs                                 # Implements ICustomSignHash via PKCS#11
└── README.md                                              # Explanation & usage instructions (which this blog complements)
  • Program.cs – orchestruje podepisování; demonstruje jak tok založený na tokenu, tak tok s certifikátem ve Windows.
  • Settings.cs – obsahuje konstanty/placeholdere pro Pkcs11LibraryPath, TokenPin a CertificateSubject.
  • Helpers.cs – obsahuje kód pro vyhledání certifikátů ve Windows store podle názvu subjektu (použito pro záložní tok).
  • Pkcs11DigitalSigner.cs – hlavní logika: načte modul PKCS#11, otevře relace, najde objekt soukromého klíče, podepíše otisk a vrátí X509Certificate2 nebo implementaci callbacku pro podpis.
  • README.md – poskytuje přehled, výzvy a návod 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>";
}

This isolates configuration details so they can be easily replaced in your deployment environment.

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 ústřední metoda: přijímá otisk spočítaný GroupDocs a poté používá PKCS#11 API k jeho podepsání.
  • GetCertificateFromPkcs11 získá 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 v DigitalSignOptions je nastavená na tokenSigner, což umožňuje GroupDocs delegovat skutečné podepisování hashů na token.
  • Záložní tok (zakomentováno) ukazuje, jak přepnout na certifikát z Windows store, když není hardwarový token k dispozici.

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

  • Indie a USB dongly certifikované úřady (CA)
    V Indii mnoho právně závazných e-podpisů vyžaduje certifikáty uložené v USB donglech vydaných certifikovanými autoritami. Tento vzor umožňuje aplikacím (např. bránám dokumentů, portálům) integraci přímo s takovými dongly.

  • Podnikové workflow dokumentů
    Pro interní systémy jako správa smluv nebo schvalovací toky, hardwarové podepisování zajišťuje, že neautorizovaní uživatelé nemohou podvrhnout podpisy dokumentů.

  • Právní a compliance‑orientované podepisování
    Vlády a regulované odvětví často vyžadují, aby podpisy pocházely z hardwarově řízených klíčů. Tato integrace pomáhá splnit přísné požadavky na audit a soulad.

Běžné úskalí a řešení problémů

  • Nesprávná cesta k knihovně → Cesta k PKCS#11 DLL musí odpovídat modulu vašeho dodavatele tokenu (např. softhsm2.dll, cryptoki.dll).
  • Zamčení nebo selhání PIN → Opakované špatné zadání PIN může token zamknout; zkontrolujte politiku dodavatele.
  • Klíč nenalezen → Ujistěte se, že je zadán správný subjekt certifikátu; token musí obsahovat certifikát se shodujícím se subjektem.
  • Chybí ovladač nebo middleware → Některé tokeny vyžadují, aby byly nainstalovány ovladače dodavatele před tím, než může Pkcs11Interop komunikovat.
  • Problémy s vlákny → Operace PKCS#11 nemusí být vlákny bezpečné; používejte jednovláknový kontext, pokud dodavatel nepodporuje více.
  • Timeouty nebo resetování relací → Dlouhé operace mohou způsobit uzavření nebo timeout relací; zajistěte správnou správu a úklid relací.

Bezpečnost a nejlepší postupy

  • Nikdy neukládejte do kódu produkční tajemství (PINy, cesty k knihovnám); používejte zabezpečenou konfiguraci nebo správu tajemství.
  • Používejte silné PINy a pravidelně je měňte, pokud to politika dovoluje.
  • Logujte operace a chyby (bez logování citlivých PIN).
  • Omezte relace tokenu a odhlaste se okamžitě po podepsání.
  • Ověřte podpis po podepsání (kontrola řetězce, časového razítka).
  • Testujte napříč prostředími a typy tokenů (dongle/čipová karta/HSM).

Další kroky a zdroje

Jste připraveni to vyzkoušet? Naklonujte repozitář, aktualizujte placeholdery a spusťte ukázku.

Témata, která můžete dál prozkoumat:

  • Vlastní podepisování hashů (delegace výpočtu otisku + podepisování na token)
  • Časové razítkování a vkládání LTV / DSS
  • Iterativní podepisování (více podpisů v jednom dokumentu)
  • Integrace se vzdálenými HSM službami nebo cloudovými úložišti tokenů

Externí odkazy