Penandatanganan hardware security module (PKCS#11)

Sekilas pandang

NextPDF Enterprise menandatangani PDF dengan kunci yang disimpan di dalam hardware security module (HSM). Anda mengarahkan penanda tangan ke token PKCS#11 — smart card, token Universal Serial Bus (USB), atau HSM berbasis-jaringan — dan operasi penandatanganan berjalan di perangkat. Kunci privat tidak pernah keluar dari batas token. Halaman ini bersifat tingkat-perilaku: halaman ini menyatakan apa yang dilakukan penanda tangan, apa yang Anda sediakan, dan di mana kustodi kunci berhenti menjadi tanggung jawab NextPDF.

Penanda tangan HSM ter-resolve melalui kontrak penanda tangan Core, sehingga aplikasi Anda bergantung pada kontrak, bukan pada tipe Enterprise konkret. Ia memperluas jalur penandatanganan Cryptographic Message Syntax (CMS) yang sama yang digunakan Core, kecuali operasi kriptografi didelegasikan ke token.

Prasyarat dinyatakan dalam front matter dan diulang di bawah Prasyarat agar Anda tidak terkejut di tengah-tugas.

Ketersediaan dan pelisensian

Kapabilitas ini disertakan dalam NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan amplop lisensi tingkat-Enterprise. Penerapan tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

NextPDF Core menyertakan penanda tangan CMS perangkat lunak yang menyimpan kunci di dalam proses atau menerima satu melalui kontrak strategi-penandatanganan Core; NextPDF Pro menambahkan strategi penandatanganan remote dan cloud key-management-service (KMS). Kustodi kunci perangkat keras melalui PKCS#11 adalah kapabilitas Enterprise, tidak disediakan oleh Core atau Pro.

Apa yang dilakukan kapabilitas ini

Sebuah token PKCS#11 memaparkan objek kriptografi — sertifikat dan kunci privat — di balik pustaka bersama vendor. Penanda tangan Enterprise mengadaptasi pustaka tersebut:

1. Ia membuka pustaka bersama token sekali per proses dan menyimpan handle modul dalam cache, karena PKCS#11 mensyaratkan modul diinisialisasi tepat sekali per proses.
2. Ia membuka sesi pada slot yang dikonfigurasi dan login dengan PIN yang disediakan. Login mengautentikasi pengguna sebelum operasi kunci-privat apa pun, sesuai PKCS#11 v3.1 §5.6.8.
3. Ia menemukan sertifikat penandatanganan pada token berdasarkan label, membaca sertifikat dalam bentuk Distinguished Encoding Rules (DER), dan mendeteksi algoritma kunci-publik.
4. Pada saat penandatanganan, ia menemukan kunci privat berdasarkan label — yang dapat berbeda dari label sertifikat pada sebagian token — dan meminta token menghitung tanda tangan. Data yang akan ditandatangani diberikan; kunci tetap di perangkat.

Penanda tangan mendukung RSA dengan padding PKCS#1 v1.5 (SHA-256, SHA-384, SHA-512), RSA dengan padding Probabilistic Signature Scheme (PSS) yang panjang salt-nya sama dengan panjang digest, dan Elliptic Curve Digital Signature Algorithm (ECDSA) dengan SHA-256, SHA-384, dan SHA-512. Kurva dan digest ECDSA dipasangkan secara konvensional — P-256 dengan SHA-256, P-384 dengan SHA-384, P-521 dengan SHA-512 — mengikuti pasangan yang direkomendasikan dalam RFC 5480. Sebuah token mengembalikan tanda tangan ECDSA sebagai konkatenasi mentah dua integer; penanda tangan mengonversinya ke bentuk ter-encode-DER yang diharapkan PDF dan OpenSSL.

Untuk pembuatan tanda tangan, kunci RSA minimal 2048 bit dan order kurva ECDSA minimal 224 bit adalah minimum yang dapat diterima sesuai NIST SP 800-131A Rev.2 §3. Sediakan kunci token Anda pada atau di atas ukuran tersebut.

Sebuah jalur OpenSSL-engine alternatif ada untuk token berdukungan-engine. Pada OpenSSL 3.x, ekstensi OpenSSL PHP tidak memaparkan application programming interface (API) engine, sehingga kelas engine ditandai usang; rute berdukungan-engine yang didukung menjalankan binari baris-perintah OpenSSL. Utamakan jalur PKCS#11 langsung jika token Anda memiliki pustaka PKCS#11.

Mengapa ia bekerja seperti ini

Keputusan yang menanggung beban adalah bahwa kunci privat tidak pernah keluar dari token. Jadi penanda tangan mendelegasikan operasi kriptografi ke perangkat dan hanya memindahkan data-yang-akan-ditandatangani melintasi seam PKCS#11. Ia tidak pernah membaca atau merekonstruksi material kunci di memori PHP. Ia ter-resolve melalui kontrak Core HsmSignerInterface alih-alih tipe Enterprise konkret, sehingga kode penandatanganan identik baik kunci berada di perangkat lunak, cloud KMS, maupun token perangkat keras. Ia menyimpan handle modul dalam cache sekali per proses karena PKCS#11 menginisialisasi setiap modul tepat sekali per proses, lalu mengonversi keluaran ECDSA mentah token ke DER sehingga validator melihat encoding yang mereka harapkan. Kustodi, bukan kenyamanan, yang menentukan bentuknya: batas kepercayaan tetap di tepi perangkat.

Latar belakang desain: Penandatanganan berdukungan-HSM.

Prasyarat

Sebelum Anda menandatangani dengan HSM, konfirmasi setiap item:

1. Pasang NextPDF Core dan paket Enterprise: composer require nextpdf/core:^3 dan composer require nextpdf/enterprise.
2. Pertahankan lisensi NextPDF Enterprise yang aktif; resolusikan paket terhadap kredensial lisensi Anda di Private Packagist.
3. Pasang pustaka bersama PKCS#11 vendor token pada host (misalnya .so di Linux atau .dll di Windows) dan catat path absolutnya, nomor slot, dan label objek.
4. Muat ekstensi PHP ext-pkcs11. Ekstensi ini tidak disertakan dengan PHP standar dan harus dipasang secara terpisah. Konstruktor penanda tangan memunculkan galat operasi bertipe ketika ekstensi absen.

Konfigurasi

Sediakan masukan ini ke penanda tangan:

• Path pustaka — path absolut ke pustaka bersama PKCS#11 vendor.
• Pengenal slot — nomor slot token, biasanya 0.
• PIN — PIN token. Perlakukan sebagai rahasia: sediakan dari secret manager Anda, jangan pernah dari sumber atau log. Penanda tangan menandai parameter PIN sensitif sehingga dikecualikan dari stack trace dan serialisasi.
• Label sertifikat — label objek sertifikat pada token.
• Label kunci — label objek kunci-privat, ketika berbeda dari label sertifikat.
• Rantai — sertifikat intermediate opsional dalam bentuk DER, ketika token tidak menyimpannya.

Periksa ketersediaan token sebelum Anda mengonstruksi penanda tangan. Konstruksi membaca sertifikat dari token, sehingga slot atau label yang salah-konfigurasi gagal cepat dengan galat bertipe alih-alih pada saat penandatanganan.

Langkah demi langkah

1. Konfirmasi runtime mendukung PKCS#11 dengan memeriksa ketersediaan ekstensi. Jangan mengonstruksi penanda tangan ketika ekstensi absen.
2. Baca PIN dari secret manager Anda ke dalam variabel yang tidak pernah dicatat.
3. Konstruksi penanda tangan HSM dengan path pustaka, slot, PIN, dan label. Konstruksi melakukan login dan membaca sertifikat.
4. Berikan penanda tangan ke orkestrator penandatanganan Core melalui HsmSignerInterface. Orkestrator menghitung byte range, membangun atribut tertanda CMS, menyerahkan data ke token, dan merakit PDF yang ditandatangani.
5. Tangkap kegagalan yang paling spesifik, catat pesan struktural tanpa PIN, dan lempar ulang.

examples/contracts/hsm-signer-availability.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Build a hardware-token signer only when the runtime supports it.
 *
 * The concrete PKCS#11 signer is resolved through the Core contract so the
 * caller depends on the interface, not the Enterprise implementation type.
 * The PIN arrives from a secret resolver; it is never written to source.
 *
 * @param callable(): bool                $pkcs11Available Reports ext-pkcs11 availability.
 * @param callable(): HsmSignerInterface  $signerFactory   Builds the configured token signer.
 *
 * @throws \RuntimeException When the PKCS#11 extension is not loaded.
 *
 * @return HsmSignerInterface The token signer, ready for the Core orchestrator.
 */
function resolveHsmSigner(callable $pkcs11Available, callable $signerFactory): HsmSignerInterface
{
    if ($pkcs11Available() !== true) {
        throw new \RuntimeException(
            'PKCS#11 signing requires the ext-pkcs11 extension; install it before signing.',
        );
    }

    return $signerFactory();
}

Pengkabelan produksi — daftar argumen konstruktor persis dan tipe eksepsi bertipe — didokumentasikan dalam referensi mendalam HSM.

examples/contracts/hsm-sign-guarded.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\HsmSignerInterface;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

final readonly class HsmSigningService
{
    public function __construct(
        private HsmSignerInterface $signer,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign data on the token through the Core HSM contract.
     *
     * The byte range is computed by the engine, never accepted from the
     * caller. The token performs the signing operation; the private key
     * does not leave the device.
     *
     * @param string $data      The bytes the orchestrator hands to the token.
     * @param string $algorithm The OpenSSL-style signing algorithm identifier.
     *
     * @throws NextPdfException When the token operation fails.
     *
     * @return string The raw signature bytes returned by the token.
     */
    public function sign(string $data, string $algorithm): string
    {
        try {
            return $this->signer->sign($data, $algorithm);
        } catch (NextPdfException $e) {
            // Structural message only — never the PIN or key material.
            $this->logger->error('HSM signing failed', ['reason' => $e->getMessage()]);

            throw $e;
        }
    }
}

Verifikasi

Konfirmasi hasil seperti yang akan dilakukan seorang verifikator:

1. Baca kembali sertifikat penanda tangan dan rantai dalam bentuk DER dari penanda tangan dan pastikan keduanya cocok dengan sertifikat yang disediakan pada token.
2. Buka PDF yang ditandatangani di validator yang dikonfigurasi dengan jangkar kepercayaan Anda dan pastikan tanda tangan dilaporkan utuh secara kriptografi. Tanda tangan yang dihasilkan bukan tanda tangan terverifikasi; keputusan kepercayaan adalah milik verifikator dan jangkar kepercayaannya, bukan produser.
3. Untuk tanda tangan ECDSA, pastikan tanda tangan yang tertanam ter-encode-DER — penanda tangan mengonversi keluaran mentah token untuk Anda, sehingga validator yang menolak bentuk konkatenasi mentah seharusnya tetap menerima tanda tangan yang tertanam.
4. Pastikan tidak ada PIN, label token, atau material kunci yang muncul dalam log aplikasi Anda.

Keamanan dan kepatuhan

• Kunci tetap di token. Data yang akan ditandatangani diserahkan ke token; operasi penandatanganan berjalan di dalam batas token. Kunci privat tidak pernah dimuat ke memori PHP.
• PIN adalah rahasia. Ia adalah parameter konstruktor yang sensitif, dikecualikan dari log dan serialisasi. Sediakan dari secret manager. Re-autentikasi gagal berulang dapat mengunci PIN di token; token, bukan NextPDF, menegakkan kebijakan itu.
• Gagal-tertutup. Galat token atau HSM memunculkan eksepsi bertipe. Penanda tangan tidak menghasilkan hasil yang tak-ditandatangani atau setengah-ditandatangani dan tidak pernah mengganti dengan algoritma yang lebih lemah.
• Kekuatan algoritma. Sediakan kunci RSA minimal 2048 bit dan kurva ECDSA dengan order minimal 224 bit, minimum yang dapat diterima untuk pembuatan tanda tangan sesuai NIST SP 800-131A Rev.2 §3.
• Penandatanganan post-quantum bersifat eksperimental dan nonaktif secara baku. Jalur post-quantum ada di balik flag opt-in eksplisit. Profil arsip jangka-panjang PDF Advanced Electronic Signatures (PAdES) standar belum mengenali suite post-quantum, dan sebagian besar penampil menolaknya saat validasi. Jangan mengaktifkannya untuk tanda tangan PAdES produksi.

Halaman ini berkaitan dengan penandatanganan kriptografi dan integrasi hardware-security-module. Setiap sumber normatif diparafrasakan; tidak ada teks normatif yang direproduksi. ### Batas kustodi kunci

NextPDF Enterprise terintegrasi dengan token PKCS#11 atau HSM. Ia tidak menyimpan, menghasilkan, atau menjamin keamanan kunci penandatanganan. Keamanan kunci bergantung pada token atau HSM, penerapan, dan operator — bukan pada NextPDF Enterprise saja. Anda bertanggung jawab atas penyediaan token, penanganan PIN, konfigurasi slot, dan perlindungan jaringan dari HSM berbasis-jaringan.

Penanganan kegagalan

• Ekstensi absen. Mengonstruksi penanda tangan PKCS#11 memunculkan eksepsi operasi bertipe ketika ext-pkcs11 tidak dimuat. Periksa ketersediaan terlebih dahulu.
• Sertifikat atau kunci tidak ditemukan berdasarkan label. Konstruksi atau penandatanganan memunculkan eksepsi bertipe yang menyebutkan objek yang hilang. Konfirmasi label dan slot.
• Sudah login. Ketika beberapa instans penanda tangan berbagi modul tercache untuk slot yang sama, penanda tangan logout dan login kembali untuk menyediakan verifikasi PIN yang baru — diperlukan oleh token personal-identity-verification dengan kebijakan “PIN setiap kali”.
• Algoritma tidak didukung. Meminta algoritma yang tidak dipetakan penanda tangan memunculkan galat argumen alih-alih menandatangani dengan pengganti.
• HSM jaringan tak terjangkau. Galat jaringan atau perangkat memunculkan eksepsi bertipe; penanda tangan tidak pernah diam-diam menghasilkan dokumen yang tak-ditandatangani.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Path namespace internal, kelas pembantu, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• HSM signing — reference — referensi mendalam untuk penanda tangan PKCS#11.
• Security — NextPDF Enterprise — permukaan keamanan Enterprise gabungan.
• Signature — NextPDF Enterprise — produser jangka panjang PAdES B-LT dan B-LTA.
• FIPS 140 cryptographic policy — kebijakan mode-FIPS dan penjaga swauji.
• Cloud KMS signing — NextPDF Pro — strategi key-management-service AWS, Azure, dan GCP.
• Security / Signing (Core) — penanda tangan CMS Core dan kontrak strategi-penandatanganan.
• HSM · PKCS#11 · CMS · ECDSA — istilah glosarium.