Keamanan — HSM, PKCS#11 dan mode FIPS

Sekilas

NextPDF Enterprise menambahkan jalur penandatanganan token perangkat keras PKCS#11 dan kebijakan kriptografis FIPS-mode di atas permukaan keamanan Core dan Pro. Halaman ini menyatakan perilaku, batasan, serta sikap sertifikasi-FIPS dan custody-kunci yang eksplisit.

Ketersediaan & lisensi

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

Ikhtisar konseptual

Permukaan keamanan Enterprise memiliki tiga bagian: sebuah signer token perangkat keras, sebuah kebijakan kripto FIPS-mode, dan sebuah power-on self-test guard.

Signer token perangkat keras mengadaptasi sebuah token PKCS#11 — sebuah kartu pintar, perangkat USB, atau HSM yang terpasang-jaringan. Signer menemukan sertifikat dan kunci privat pada token berdasarkan label. Lalu ia meminta token menghitung tanda tangan. Kunci privat tidak meninggalkan batas token; operasi berjalan di dalam token. Operasi sign token, sesi, dan login pengguna mengikuti PKCS#11 v3.1 §5. Jalur HSM membutuhkan ekstensi PHP ext-pkcs11. Ekstensi itu bukan bagian dari PHP standar. Pasang secara terpisah. Gunakan pemeriksaan ketersediaan sebelum Anda mengonstruksi signer.

Kebijakan kripto FIPS-mode membatasi pilihan kriptografis ke himpunan yang disetujui. Ia memiliki dua preset. Preset strict mengizinkan hash SHA-256, SHA-384, dan SHA-512; OID tanda tangan RSA dan ECDSA dengan hash tersebut; enkripsi AES-256-CBC; dan ukuran kunci minimum RSA 2048 dan EC 256. Preset standard sama tetapi juga mengizinkan AES-128-CBC untuk interoperabilitas lama. Sebuah guard runtime membungkus kebijakan. Guard memeriksa setiap hash, OID tanda tangan, algoritma enkripsi, dan kekuatan kunci sebelum operasi berjalan. Pilihan yang tidak diizinkan memunculkan pelanggaran bertipe dan menghentikan operasi. Jalurnya fail-closed: kebijakan tidak pernah melonggarkan dirinya sendiri dan tidak pernah menggantikan algoritma yang lebih lemah. Panjang kunci RSA minimum mengikuti NIST SP 800-131A Rev.2 §3. Pasangan kurva dan hash ECDSA mengikuti FIPS 186-5 §6.1.1.

Power-on self-test guard menjalankan sebuah baterai known-answer-test sekali pada awal proses. Baterai mencakup fungsi hash, MAC, enkripsi, tanda tangan, dan random-bit yang disetujui. Jika ada tes yang gagal, Enterprise FIPS guard memasuki keadaan error dan menolak layanan kriptografis sampai direset. Hasil disimpan dalam cache untuk seumur hidup proses; pengulangan on-demand tersedia. Kategori self-test dan pemicu conditional-test mengikuti ISO/IEC 19790:2025 §7.10 dan §7.10.3.

Mengapa ia bekerja seperti ini

Keputusan yang menanggung beban adalah menjaga kunci privat tetap di dalam batas token dan membuat kebijakan kripto fail-closed. Sebuah signer yang bisa mengekspor kunci, atau diam-diam jatuh kembali ke algoritma yang lebih lemah, akan menggagalkan jaminan yang justru menjadi alasan keberadaan HSM. Maka signer meminta token menghitung tanda tangan di tempat, dan FIPS-mode guard menolak setiap hash, OID, atau kekuatan kunci di luar preset yang disetujui sebelum operasi berjalan. Power-on self-test memperluas sikap yang sama ke awal proses: sebuah modul yang belum terverifikasi menolak layanan alih-alih menandatangani dengan primitif yang belum teruji. Hasilnya adalah sebuah batas yang bisa Anda nalar, di mana custody kunci dimiliki oleh operator dan token, bukan oleh perangkat lunak ini.

Latar belakang desain: HSM-backed signing.

Permukaan API

Permukaan publik	Tipe	Tujuan	Stabilitas	Sejak
Signer token PKCS#11	kelas (mengimplementasikan HsmSignerInterface Core)	Menandatangani dengan token PKCS#11; kunci tetap di token	stable	1.0.0
Kebijakan kripto FIPS	kelas (mengimplementasikan CryptoPolicyInterface Core)	Preset allowed-algorithm dan key-strength	stable	1.9.0
FIPS-mode guard	kelas	Menegaskan sebuah hash, OID tanda tangan, algoritma enkripsi, atau kekuatan kunci diizinkan	stable	1.9.0
FIPS boot guard	kelas	Menjalankan dan menyimpan power-on self-test dalam cache; menegaskan modul operasional	stable	3.2.0
Signer OpenSSL CLI / engine	kelas (mengimplementasikan HsmSignerInterface)	Menandatangani melalui engine OpenSSL atau OpenSSL CLI untuk token berbasis-engine	stable	1.0.0

Konstruktor signer token mengambil jalur pustaka PKCS#11, nomor slot, PIN token, label sertifikat, dan sebuah label kunci terpisah opsional. Parameter PIN ditandai sensitif; ia tidak dicatat dan tidak diserialisasi. Signer juga mengekspos sertifikat signer dan chain sertifikat dalam bentuk DER. Kontrak parameter dan tipe yang otoritatif adalah referensi API yang diterbitkan untuk paket nextpdf/enterprise; perlakukan referensi itu — bukan halaman ini — sebagai kontrak.

Contoh kode — Mulai cepat

composer require nextpdf/core
composer require nextpdf/enterprise:^3

Construct a FIPS-mode guard and assert a hash is allowed

use NextPDF\Enterprise\Security\Fips\FipsCryptoPolicy;
use NextPDF\Enterprise\Security\Fips\FipsModeGuard;

$guard = new FipsModeGuard(FipsCryptoPolicy::strict());

// Throws a typed FIPS violation if the algorithm is not approved.
$guard->assertHashAllowed('sha256');
$guard->assertKeyStrengthAllowed('rsa', 2048);

Contoh kode — Produksi

Run the power-on self-test at container boot, then gate signing

use NextPDF\Enterprise\Security\Fips\FipsBootGuard;
use NextPDF\Enterprise\Security\Fips\FipsSelfTest;

// At application bootstrap (one self-test cycle per worker process):
$bootGuard = new FipsBootGuard(new FipsSelfTest());
$bootGuard->assertOperational(); // throws on a known-answer-test failure
$container->set(FipsBootGuard::class, $bootGuard);

// The PKCS#11 token signer is only available when ext-pkcs11 is loaded.
// Check availability before you construct the signer. The PIN is a secret;
// supply it from your secret manager, never from source or logs.

Daftar argumen konstruktor lengkap, tipe exception, dan konstruksi signer-token PKCS#11 didokumentasikan dalam referensi mendalam Enterprise security.

Kasus tepi & jebakan

• Konstruktor signer token PKCS#11 memunculkan operation exception bertipe ketika ext-pkcs11 tidak dimuat. Periksa ketersediaan lebih dulu.
• Signer token meng-cache satu modul PKCS#11 per jalur pustaka per proses. Ini memenuhi aturan “initialize once per module” dari antarmuka token.
• Mekanisme token ECDSA mengembalikan tanda tangan mentah. Signer mengonversinya ke bentuk DER-encoded untuk interoperabilitas PDF dan OpenSSL.
• FIPS guard menolak tipe kunci yang tidak dikenal secara default. Tipe kunci yang tidak dikenali tidak diterima secara diam-diam.
• Jalur penandatanganan post-quantum bersifat eksperimental, opt-in, dan dinonaktifkan secara default. Profil pengarsipan jangka panjang PAdES standar belum mengenali suite post-quantum. Jangan mengaktifkannya untuk tanda tangan AdES produksi.

Performa

Pemeriksaan FIPS guard adalah pencarian hash-map constant-time. Power-on self-test berjalan sekali per proses; biayanya diamortisasi sepanjang seumur hidup proses, bukan per panggilan penandatanganan. Sebuah operasi penandatanganan PKCS#11 menambahkan satu round trip ke token. HSM yang terpasang-jaringan menambahkan latensi jaringan dari round trip itu.

Catatan keamanan

• Jalur penandatanganan bersifat fail-closed. Kegagalan primitif atau celah kebijakan memunculkan exception bertipe. Jalur tidak pernah menurunkan diri secara diam-diam ke algoritma yang lebih lemah.
• Parameter PIN token ditandai sensitif. Ia tidak dicatat dan tidak diserialisasi.
• Kunci privat untuk token PKCS#11 tetap di token. Operasi penandatanganan berjalan di dalam batas token.
• Power-on self-test menempatkan Enterprise FIPS guard ke keadaan error pada ketidakcocokan known-answer-test dan menolak layanan kriptografis sampai direset.
• Penggunaan AES-GCM mensyaratkan initialization vector yang unik per kunci, sesuai NIST SP 800-38D §5.

Residensi Data & Mitigasi PII

Kode penandatanganan dan kebijakan-FIPS berjalan in-process. Tidak ada konten dokumen yang meninggalkan host untuk pemeriksaan kebijakan-FIPS atau power-on self-test. Sebuah token PKCS#11 menerima data untuk ditandatangani, bukan konten dokumen yang tidak terkait. HSM yang terpasang-jaringan menerima data itu melalui channel jaringan yang Anda konfigurasi. Materi kunci tetap di dalam batas token atau HSM.

Telemetri Aman & Pembersihan Log

PIN token adalah parameter konstruktor sensitif dan dikecualikan dari log dan serialisasi. Jangan menambahkan PIN, label token, atau materi kunci ke log aplikasi Anda sendiri. Perlakukan semua kredensial token sebagai secret dalam kebijakan logging dan tracing Anda.

Model ancaman

Ini adalah sebuah batas kriptografis, sehingga model ancaman bersifat eksplisit. Data untuk ditandatangani diserahkan ke token; token memegang kunci. Error token atau HSM memunculkan exception bertipe; signer tidak menghasilkan hasil yang tidak-tertandatangani atau setengah-tertandatangani. Perlindungan kunci bergantung pada token atau HSM, penerapan, dan operator — bukan pada perangkat lunak ini saja. Lihat batas penerapan.

Konformansi

• Model power-on dan conditional self-test selaras dengan ISO/IEC 19790:2025 §7.10 dan §7.10.3.
• Panjang kunci tanda tangan RSA minimum selaras dengan NIST SP 800-131A Rev.2 §3.
• Pasangan kurva dan hash ECDSA yang disetujui selaras dengan FIPS 186-5 §6.1.1.
• Operasi sign token PKCS#11 dan login sesi selaras dengan PKCS#11 v3.1 §5.
• Tanggung jawab perlindungan kunci selaras dengan NIST SP 800-57 Part 1 Rev.5 §5.5.2.
• Keunikan initialization-vector AES-GCM selaras dengan NIST SP 800-38D §5.

Setiap sumber normatif diparafrasakan. Tidak ada teks normatif yang direproduksi pada halaman ini. Halaman ini menyangkut penandatanganan kriptografis.

Perilaku FIPS-mode

Kebijakan FIPS-mode membatasi pilihan kriptografis ke himpunan yang disetujui yang dijelaskan di atas. Ketika dikonfigurasi terhadap penyedia OpenSSL tervalidasi FIPS, primitif yang mendasari berjalan dalam batas tervalidasi tersebut. NextPDF Enterprise sendiri melakukan perakitan struktural, komputasi digest, dan penegakan kebijakan.

NextPDF Enterprise bukan modul kriptografis tervalidasi FIPS dan tidak membuat klaim sertifikasi FIPS. NextPDF Enterprise beroperasi dalam mode kompatibel FIPS hanya ketika dikonfigurasi dengan penyedia kriptografis tervalidasi FIPS — misalnya penyedia OpenSSL tervalidasi FIPS — atau HSM tervalidasi FIPS. Kebijakan FIPS-mode membantu kepatuhan; ia bukan sertifikasi.

Batas edisi

NextPDF Core menyertakan signer perangkat lunak, konsumsi timestamp RFC 3161, validasi path RFC 5280, dan pemeriksaan pencabutan OCSP dan CRL. Core menghasilkan level PAdES B-B dan B-T. NextPDF Pro menambahkan masking, deteksi PII text-layer, penandatanganan sekuensial multi-pihak, serta strategi penandatanganan remote dan cloud-KMS (AWS KMS, GCP Cloud KMS, Azure Key Vault). NextPDF Pro tidak menyediakan jalur token perangkat keras PKCS#11 dan tidak menyediakan profil kebijakan-kripto FIPS-mode. Signer token perangkat keras PKCS#11, profil kebijakan-kripto FIPS-mode, power-on self-test guard, dan producer PAdES B-LT dan B-LTA hanya dikapalkan dalam paket nextpdf/enterprise. Penerapan tanpa entitlement Enterprise tidak memuat kelas-kelas Enterprise.

Fallback Pro

Pada penerapan Pro-saja, jalur penandatanganan berbasis-perangkat-keras dan berbasis-cloud yang didukung adalah strategi cloud-KMS Pro: sebuah cloud KMS atau KMS berbasis-HSM memegang kunci, dan Pro mengirim digest signed-attributes, bukan dokumen, ke penyedia. Pro menyediakan integrasi KMS, bukan factory token PKCS#11 Enterprise atau profil FIPS-mode. Konfigurasi yang meminta B-LT, B-LTA, token PKCS#11, atau profil FIPS-mode pada penerapan Pro-saja fail closed dengan pesan yang menyebutkan komponen Enterprise yang hilang. Lihat Security — NextPDF Pro untuk permukaan penandatanganan Pro.

Fallback Core

Pada penerapan Core-saja, signer perangkat lunak menghasilkan PAdES B-B dan B-T dengan kunci lokal atau kunci yang dipasok melalui kontrak signing-strategy Core. Core tidak memiliki jalur token perangkat keras dan tidak memiliki profil FIPS-mode. Lihat Security — NextPDF Core.

Catatan batas Enterprise

Integrasi token PKCS#11, mechanism mapping-nya, dan penanganan sesinya dijelaskan hanya pada tingkat perilaku. Tabel mechanism-mapping internal, logika session-recovery internal, dan materi migrasi post-quantum berada di luar cakupan permukaan publik dan tidak direproduksi di sini.

Batas penerapan

NextPDF Enterprise berintegrasi dengan sebuah token PKCS#11, HSM, atau KMS. NextPDF Enterprise tidak menyimpan, menghasilkan, atau menjamin keamanan kunci penandatanganan sendiri. Keamanan kunci bergantung pada token, HSM, atau KMS, pada penerapan, dan pada operator — bukan pada NextPDF Enterprise saja. Operator bertanggung jawab atas provisioning token, penanganan PIN, konfigurasi slot, perlindungan jaringan dari HSM yang terpasang-jaringan, dan konfigurasi trust. Tanggung jawab perlindungan kunci mengikuti NIST SP 800-57 Part 1 Rev.5 §5.5.2. NextPDF Enterprise tidak mengekspos penanganan PIN token, internal konfigurasi slot, maupun materi kredensial vendor dalam dokumentasi ini.

Batas legal-kepatuhan

Halaman ini menyangkut penandatanganan kriptografis dan integrasi hardware-security-module. Kebijakan FIPS-mode adalah fitur bantuan-kepatuhan. Ia bukan opini hukum dan bukan sertifikasi. Konsultasikan penasihat kepatuhan dan hukum Anda sendiri untuk kewajiban regulatori Anda.

Batas publikasi

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

Kontrak perilaku

• FIPS guard menegaskan setiap hash, OID tanda tangan, algoritma enkripsi, dan kekuatan kunci terhadap preset aktif dan memunculkan pelanggaran bertipe pada pilihan yang tidak diizinkan.
• Power-on self-test berjalan sekali per proses dan menolak layanan kriptografis pada kegagalan known-answer-test sampai direset.
• Signer token PKCS#11 membutuhkan ext-pkcs11; ia memunculkan operation exception bertipe ketika ekstensi tidak ada.
• Jalur penandatanganan bersifat fail-closed dan tidak pernah menggantikan algoritma yang lebih lemah.

Lihat juga

• Security — NextPDF Enterprise (referensi mendalam)
• Security — NextPDF Pro
• Signature — NextPDF Enterprise
• Accelerator — NextPDF Enterprise
• Security — NextPDF Core
• PAdES · HSM · PKCS#11 · FIPS mode · KMS — istilah glosarium.