Pendahuluan & Motivasi

Saat mengimplementasikan tanda tangan digital pada sistem berskala perusahaan, keamanan tidak dapat dinegosiasikan.
Menyimpan sertifikat dalam file PFX atau P12 lokal memang praktis, tetapi memperlihatkan kunci pribadi ke risiko ekstraksi atau kompromi. Sebaliknya, token perangkat keras PKCS#11 (seperti dongle USB, kartu pintar, dan HSM) menyimpan kunci di dalam batas yang tahan gangguan, memastikan kunci tidak pernah keluar dari perangkat.

Tulisan ini menunjukkan cara menggunakan GroupDocs.Signature untuk .NET bersama Pkcs11Interop untuk menandatangani dokumen PDF dengan token perangkat keras. Pendekatan ini menggabungkan kemudahan dan kepatuhan: GroupDocs menangani semua paket tingkat PDF (bidang tanda tangan, perhitungan digest, penyisipan), sementara token melakukan penandatanganan kriptografis sebenarnya.

⚠️ Pemberitahuan Implementasi Awal
Solusi ini saat ini disediakan sebagai implementasi awal untuk penggunaan dongle tanda tangan digital PKCS#11 dengan GroupDocs.Signature.
Meskipun memungkinkan penandatanganan dokumen dengan token perangkat keras, kami sangat menyarankan Anda melakukan pengujian tambahan di lingkungan Anda sendiri untuk memastikan solusi ini memenuhi persyaratan kepatuhan dan keamanan Anda.
Kami sangat menghargai masukan, hasil pengujian, dan saran perbaikan Anda.

Tantangan: Menjembatani PKCS#11 dengan Penandatanganan PDF

Mengintegrasikan token PKCS#11 ke dalam alur kerja penandatanganan dokumen memiliki beberapa tantangan yang tidak sepele:

  1. Kompleksitas Tingkat Rendah — API PKCS#11 (Cryptoki) memerlukan pengelolaan slot, sesi, handle, dan atribut untuk menemukan kunci pribadi yang tepat.
  2. Pengemasan Tingkat PDF — Menandatangani PDF lebih dari sekadar menandatangani byte: pustaka harus menghitung digest yang tepat pada rentang byte yang dipilih, membungkus tanda tangan dalam kontainer CMS/PKCS#7, menyertakan timestamp, dan menanamkan informasi validasi.
  3. Variasi Vendor — Token/modul vendor yang berbeda dapat memerlukan pemetaan atribut khusus atau middleware tambahan.
  4. Kepatuhan & Auditabilitas — Sistem produksi memerlukan penanganan PIN yang kuat, kontrol siklus hidup sesi, pemulihan kesalahan, dan pencatatan log.

Proyek contoh ini mengatasi hal‑hal tersebut dengan menggabungkan antarmuka ICustomSignHash di GroupDocs.Signature dengan Pkcs11Interop untuk menyerahkan penandatanganan ke token, sementara GroupDocs mengelola struktur PDF.

Apa yang Dilakukan Proyek Contoh Ini

  • Menunjukkan penandatanganan dokumen PDF menggunakan token PKCS#11 (dongle, kartu pintar, HSM).
  • Mendukung fallback ke penyimpanan sertifikat Windows: bila sertifikat terpasang di Windows, kode dapat menggunakannya sebagai alternatif.
  • Mengimplementasikan penandatanganan hash kustom: GroupDocs menghitung digest; token hanya menandatangani hash tersebut.
  • Menjaga kunci pribadi tetap berada di perangkat keras setiap saat — tidak pernah diekspor.
  • Mengenkapsulasi logika token (sesi, pencarian kunci, penandatanganan) dalam Pkcs11DigitalSigner.cs
  • Menyediakan logika bantuan dalam Helpers.cs (misalnya, pencarian sertifikat di penyimpanan Windows).
  • Konfigurasi terpusat dalam Settings.cs.
  • Berfungsi sebagai implementasi referensi yang dapat Anda adaptasikan ke lingkungan Anda.
Menjembatani PKCS#11 dengan Penandatanganan PDF

Penyiapan & Prasyarat

Prasyarat

  • .NET 6.0 atau lebih tinggi (atau .NET Framework 4.6.2)
  • Perpustakaan PKCS#11 (DLL) yang valid dari vendor token Anda
  • Token perangkat keras (dongle USB, kartu pintar, atau HSM) dengan sertifikat yang valid
  • GroupDocs.Signature untuk .NET (versi percobaan atau berlisensi)
  • Perpustakaan Pkcs11Interop

Instalasi

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

Buka solusi di Visual Studio atau IDE pilihan Anda, pastikan semua dependensi terpenuhi.

Struktur Repository: Penjelasan Mendalam

GroupDocs.Signature-for-.NET-PKCS11-Sample/
├── GroupDocs.Signature-for-.NET-PKCS11-Sample.csproj      # File proyek
├── Program.cs                                             # Titik masuk dan alur penggunaan
├── Settings.cs                                            # Konfigurasi PKCS#11 / token
├── Helpers.cs                                             # Fungsi utilitas (penyimpanan Windows, penyaringan sertifikat)
├── Pkcs11DigitalSigner.cs                                 # Mengimplementasikan ICustomSignHash lewat PKCS#11
└── README.md                                              # Penjelasan & instruksi penggunaan
  • Program.cs — mengatur proses penandatanganan; memperlihatkan alur berbasis token maupun alur sertifikat Windows.
  • Settings.cs — berisi konstanta/tempat penampung untuk Pkcs11LibraryPath, TokenPin, dan CertificateSubject.
  • Helpers.cs — berisi kode untuk menemukan sertifikat di penyimpanan Windows berdasarkan nama subjek (digunakan pada alur fallback).
  • Pkcs11DigitalSigner.cs — logika inti: memuat modul PKCS#11, membuka sesi, menemukan objek kunci pribadi, menandatangani digest, dan mengembalikan X509Certificate2 atau implementasi callback tanda tangan.
  • README.md — memberikan gambaran, tantangan, dan instruksi penggunaan (yang melengkapi blog ini).

Penjelasan Kode & Walkthrough

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

Bagian ini memisahkan detail konfigurasi sehingga mudah diganti pada lingkungan produksi Anda.

Pkcs11DigitalSigner.cs — Alur Tingkat Tinggi

public class Pkcs11DigitalSigner : ICustomSignHash
{
    public byte[] SignHash(byte[] hash)
    {
        // Metode ini dipanggil oleh GroupDocs.Signature ketika diperlukan penandatanganan hash oleh token
        using (var pkcs11 = new Pkcs11(Settings.Pkcs11LibraryPath, AppType.SingleThreaded))
        {
            // Muat modul, buka sesi, login dengan PIN, temukan kunci, dan lakukan penandatanganan
        }
    }

    public X509Certificate2 GetCertificateFromPkcs11()
    {
        // Mengambil sertifikat publik dari token sehingga opsi penandatanganan dapat dikonfigurasi
    }
}
  • SignHash adalah metode utama: menerima digest yang dihitung oleh GroupDocs, lalu menggunakan API PKCS#11 untuk menandatanganinya.
  • GetCertificateFromPkcs11 mengambil sertifikat (dengan kunci publik) yang disimpan di token sehingga metadata tanda tangan menjadi tepat.

Program.cs — Alur Penggunaan

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

        // (1) Penandatanganan PKCS#11
        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  // hubungkan penandatanganan berbasis token
            };
            signature.Sign(outputFile, options);
        }

        // (2) Fallback ke penyimpanan sertifikat Windows (opsional)
        // var storeCert = Helpers.GetCertificateFromWindowsStore(Settings.CertificateSubject);
        // using (var signature2 = new Signature(inputFile))
        // {
        //     var options2 = new DigitalSignOptions(storeCert) { ... };
        //     signature2.Sign("signed_store.pdf", options2);
        // }
    }
}

Poin penting:

  • Properti CustomSignHash pada DigitalSignOptions diatur ke tokenSigner, sehingga GroupDocs mendelegasikan penandatanganan hash sebenarnya ke token.
  • Alur fallback (dikomentar) memperlihatkan cara beralih ke sertifikat penyimpanan Windows ketika token perangkat keras tidak tersedia.

Kasus Penggunaan & Skenario Dunia Nyata

  • India & Dongle Tanda Tangan USB yang Dikeluarkan CA
    Di India, banyak e‑Signature yang mengikat secara hukum mengharuskan sertifikat disimpan di dongle USB yang dikeluarkan oleh otoritas bersertifikat. Contoh ini memungkinkan aplikasi (mis. portal dokumen, gateway) berintegrasi langsung dengan dongle tersebut.
  • Alur Kerja Dokumen Perusahaan
    Untuk sistem internal seperti manajemen kontrak atau alur persetujuan, penandatanganan berbasis perangkat keras memastikan pengguna yang tidak berwenang tidak dapat memalsukan tanda tangan dokumen.
  • Penandatanganan Legal / Berbasis Kepatuhan
    Pemerintah dan industri yang diatur sering mewajibkan tanda tangan berasal dari kunci yang dikendalikan oleh perangkat keras. Integrasi ini membantu memenuhi tuntutan audit dan kepatuhan yang ketat.

Kesalahan Umum & Pemecahan Masalah

  • Path perpustakaan tidak tepat → Path DLL PKCS#11 harus sesuai dengan modul vendor Anda (mis. softhsm2.dll, cryptoki.dll).
  • PIN terkunci atau gagal → Entri PIN yang salah berulang kali dapat mengunci token; periksa kebijakan vendor.
  • Kunci tidak ditemukan → Pastikan subjek sertifikat yang diberikan sudah tepat; token harus berisi sertifikat dengan subjek yang cocok.
  • Driver atau middleware hilang → Beberapa token memerlukan driver vendor terpasang sebelum Pkcs11Interop dapat berkomunikasi.
  • Masalah threading → Operasi PKCS#11 mungkin tidak thread‑safe; gunakan konteks single‑threaded kecuali vendor mendukung multi‑thread.
  • Timeout atau reset sesi → Operasi yang lama dapat menyebabkan sesi tertutup atau timeout; pastikan penanganan sesi dan pembersihan yang tepat.

Keamanan & Praktik Terbaik

  • Jangan pernah menuliskan rahasia produksi (PIN, path perpustakaan) secara keras; gunakan konfigurasi aman atau manajemen rahasia.
  • Gunakan PIN yang kuat dan rotasi bila kebijakan mengizinkan.
  • Catat operasi dan kesalahan (tanpa menuliskan PIN sensitif).
  • Batasi sesi token dan logout segera setelah penandatanganan selesai.
  • Validasi tanda tangan setelah penandatanganan (pemeriksaan rantai, timestamp).
  • Uji lintas lingkungan dan tipe token (dongle/kartu pintar/HSM).

Langkah Selanjutnya & Sumber Daya

Siap mencobanya? Clone repositori, perbarui placeholder, dan jalankan contoh.
Topik yang mungkin ingin Anda jelajahi selanjutnya:

  • Penandatanganan Hash Kustom (mendelegasikan digest + penandatanganan ke token)
  • Timestamping & penyisipan LTV / DSS
  • Penandatanganan iteratif (banyak tanda tangan dalam satu dokumen)
  • Integrasi dengan layanan HSM remote atau penyimpanan token berbasis cloud

Tautan Eksternal