Enterprise edisistabilitas: Eksperimental

Status kapabilitas-preview penandatanganan HSM pasca-kuantum (PQS)

Sekilas

Status kapabilitas-preview. Opt-in, default-mati, fail-closed. Ini adalah preview penandatanganan pasca-kuantum yang didelegasikan-HSM. Ini tidak tersedia umum, ini bukan AdES-compliant, ini bukan FIPS-validated, dan ia tidak membuat klaim sertifikasi atau konformitas. Preview mati sampai Anda opt-in; saat mati, panggilan penandatanganan gagal secara fail-closed dengan eksepsi bertipe.

NextPDF Enterprise mengekspos permukaan tanda tangan pasca-kuantum (PQS) eksperimental yang menggerakkan penandatanganan ML-DSA (FIPS 204) dan SLH-DSA (FIPS 205) melalui token perangkat keras PKCS#11. Jalurnya adalah Pkcs11Signer::signPqs(), digerbangi di balik opt-in per-signer yang eksplisit ($enablePostQuantum) dan, secara terpisah, di balik flag env tingkat-proses (NEXTPDF_FEATURE_PREVIEW_PQS_HSM). Keduanya mati secara default.

Halaman ini adalah batas yang jujur. Ia menyatakan apa yang dilakukan preview — ia mendelegasikan operasi penandatanganan pasca-kuantum nyata ke token — dan, dengan kejujuran setara, apa yang bukan: ia bukan GA, bukan AdES, bukan FIPS-validated, dan bukan klaim konformitas terhadap FIPS, OASIS, atau ETSI. Standar yang akan membuat tanda tangan PDF pasca-kuantum dapat-saling-operasi untuk arsip jangka-panjang belum mendarat (lihat Batas standar).

Ketersediaan & lisensi

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

Ia dibangun di atas signer token-perangkat-keras PKCS#11 Enterprise — lihat Penandatanganan HSM. Jalur penandatanganan PKCS#11 klasik (RSA / ECDSA) adalah kapabilitas Enterprise yang didukung dan stabil; jalur pasca-kuantum yang dijelaskan di sini adalah preview eksperimental yang dilapiskan di atasnya. NextPDF Enterprise mencakup himpunan fitur Pro.

Status kapabilitas-preview

Preview menggerakkan operasi penandatanganan sungguhan: saat diaktifkan, signPqs() mengirim ke mekanisme pasca-kuantum PKCS#11 v3.1 kandidat pada token, kunci privat tidak pernah meninggalkan batas token, dan byte yang dikembalikan diperiksa-panjang terhadap panjang tanda tangan yang diwajibkan-FIPS untuk parameter set yang dipilih sebelum diterima.

Pada saat yang sama, ia adalah preview dan bukan kapabilitas produk yang tersedia umum:

Pengenal mekanisme dan parameter-set pasca-kuantum PKCS#11 bersifat provisional — OASIS PKCS#11 v3.1 belum memfinalkan registry mekanisme pasca-kuantum, sehingga nilai yang dipakai dilacak sebagai provisional dan operator HSM harus memastikan firmware PQ token mereka cocok dengannya sebelum mengaktifkan.
Tidak ada jalur verifikasi pasca-kuantum di NextPDF, dan tidak ada suite ETSI yang mendaftarkan tanda tangan pasca-kuantum untuk arsip jangka-panjang AdES, sehingga tanda tangan yang dihasilkan di sini belum dapat-saling-operasi dan sebagian besar penampil PDF akan menolaknya pada waktu validasi.
Sebuah deskriptor pendamping, PqsCapabilityStatus, melaporkan fakta-fakta ini dalam bentuk dapat-dibaca-mesin. Setiap boolean klaim positif — generallyAvailable, adesCompliant, verificationAvailable, conformanceClaimed — di-hardcode ke false dan tetap false bahkan saat flag preview aktif, dan tidak ada konfigurasi yang dapat membalik salah satunya menjadi aktif. (Ia juga membawa flag recognitionOnly, di-hardcode true, yang mencatat bahwa pengenalan algoritma tidak pernah merupakan verdict konformitas; itu tidak berarti permukaan tidak dapat menandatangani — penandatanganan terjadi melalui signPqs() seperti dijelaskan di atas.)

Mengapa ia bekerja seperti ini

NextPDF sudah dapat menghitung tanda tangan ML-DSA atau SLH-DSA nyata melalui token. Meski begitu, setiap boolean konformitas tetap di-hardcode ke false, di balik dua gerbang default-mati. Sebuah tanda tangan hanya berharga sebesar kemampuan untuk memverifikasinya nanti. Untuk pasca-kuantum belum ada jalur verifikasi, tidak ada suite AdES ETSI terdaftar, dan belum ada round-trip HSM yang FIPS-validated. Mengirimkan ini sebagai tersedia umum akan menerbitkan tanda tangan yang tidak dapat divalidasi penampil mana pun dan tidak dapat dipercaya arsip mana pun. Maka desain memisahkan pembuatan byte dari klaim bahwa siapa pun boleh mengandalkannya, dan tidak ada flag preview yang dapat mengaburkan garis itu.

Latar belakang desain: Validasi jangka-panjang.

Parameter set algoritma

signPqs() memilih algoritma dan parameter set melalui enum Pkcs11PqsAlgorithm. Setiap case memetakan parameter set NIST ke pengenal mekanisme / parameter-set PKCS#11 provisional dan ke panjang byte tanda tangan yang diwajibkan-FIPS yang dipakai untuk pemeriksaan-panjang defence-in-depth.

ML-DSA — FIPS 204 (module-lattice). Tiga parameter set, diklaim pada kategori kekuatan-keamanan NIST yang ditunjukkan:

Parameter set	Kategori NIST	Panjang tanda tangan (byte)
`ML-DSA-44`	2	2420
`ML-DSA-65` (default yang direkomendasikan)	3	3309
`ML-DSA-87`	5	4627

SLH-DSA — FIPS 205 (stateless hash-based). Dua belas parameter set, dibentuk sebagai SHA2 / SHAKE x 128 / 192 / 256 x small (s) / fast (f). Varian s meminimalkan ukuran tanda tangan; varian f meminimalkan latensi penandatanganan:

Keluarga parameter set	Kategori NIST	Panjang tanda tangan (byte)
`SLH-DSA-{SHA2,SHAKE}-128s`	1	7856
`SLH-DSA-{SHA2,SHAKE}-128f`	1	17088
`SLH-DSA-{SHA2,SHAKE}-192s`	3	16224
`SLH-DSA-{SHA2,SHAKE}-192f`	3	35664
`SLH-DSA-{SHA2,SHAKE}-256s`	5	29792
`SLH-DSA-{SHA2,SHAKE}-256f`	5	49856

Mengaktifkan preview

Dua gerbang independen keduanya harus terbuka. Keduanya default mati.

Gerbang proses. Setel NEXTPDF_FEATURE_PREVIEW_PQS_HSM=1 sebelum proses boot (atau melalui putenv() sebelum status dibaca). Kesetaraan ketat dengan string 1 diwajibkan; nilai lain apa pun — termasuk 0, true, yes, atau kosong — diperlakukan sebagai mati.
Opt-in per-signer. Berikan $enablePostQuantum: true ke konstruktor Pkcs11Signer.

use NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11Signer;
use NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm;
use NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus;
use NextPDF\Enterprise\Security\Signature\Hsm\PqsPreviewFeature;

// 1. Open the process-level preview gate (default-off).
putenv(PqsPreviewFeature::ENV_PREVIEW_PQS_HSM . '=1');

// 2. The capability status is honest even with the gate open:
//    generallyAvailable / adesCompliant / verificationAvailable stay false.
$status = PqsCapabilityStatus::current();

// 3. Construct the PKCS#11 signer with the per-signer opt-in.
$signer = new Pkcs11Signer(
    libraryPath: '/usr/lib/softhsm/libsofthsm2.so',
    slotId: 0,
    pin: '1234',
    certLabel: 'my-pqc-signing-cert',
    enablePostQuantum: true,
);

// 4. Sign with a chosen parameter set. The returned bytes are length-checked
//    against Pkcs11PqsAlgorithm::signatureLength() before being accepted.
$signature = $signer->signPqs(
    data: $tbsBytes,
    algorithm: Pkcs11PqsAlgorithm::MlDsa65,
);

isPostQuantumEnabled() melaporkan apakah opt-in per-signer disetel, dan PqsCapabilityStatus::current() melaporkan keadaan tingkat-proses plus boolean klaim yang jujur.

Batasan fail-closed

Permukaan ini fail-closed dan melaporkan kegagalan melalui eksepsi bernama dan bertipe alih-alih fallback diam:

Opt-in tidak ada. Jika signPqs() dipanggil saat $enablePostQuantum bernilai false, ia melempar HsmOperationException. Tidak ada penandatanganan yang terjadi.
Konteks terlalu panjang. Sebuah octet string konteks penandatanganan yang lebih panjang dari 255 byte melempar InvalidArgumentException (sesuai batas konteks FIPS 204 / FIPS 205) sebelum panggilan token apa pun.
Kunci tidak ada. Jika tidak ada kunci privat yang cocok dengan label yang dikonfigurasikan pada token, signPqs() melempar HsmOperationException.
Ketidaksesuaian panjang. Jika token mengembalikan tanda tangan yang panjang byte-nya tidak sama dengan panjang yang diwajibkan-FIPS untuk parameter set, signPqs() melempar HsmOperationException — tanda tangan yang malformed (terpotong atau berlebih) ditolak sebelum dapat mencapai encoding CMS SignedData.
Kesalahan token. Kesalahan PKCS#11 yang mendasari apa pun dibungkus dalam HsmOperationException.

Flag env tingkat-proses tidak mengubah apa pun tentang batas ini: bahkan saat flag aktif, boolean kapabilitas tetap false dan jalur penandatanganan tetap diperiksa-panjang dan fail-closed.

Batas yang jujur

Klaim berikut tidak dibuat untuk permukaan ini dan tidak boleh muncul dalam dokumentasi, UI, atau pemasaran apa pun yang diturunkan darinya:

“GA” / “generally available”.
“AdES” / “PAdES-compliant” — tidak ada suite ETSI yang mendaftarkan tanda tangan pasca-kuantum untuk arsip jangka-panjang.
“FIPS-validated” — tidak ada round-trip HSM pasca-kuantum yang FIPS-140-3 validated yang telah ditetapkan untuk jalur ini.
“certified” atau “conformant” terhadap FIPS, OASIS PKCS#11 v3.1, atau ETSI.
“production-ready”.

Apa yang secara jujur merupakan permukaan ini: preview yang opt-in, default-mati, fail-closed dari penandatanganan pasca-kuantum yang didelegasikan-HSM yang menggerakkan ML-DSA / SLH-DSA melalui token PKCS#11 dan memeriksa-panjang hasilnya. Apa yang bukan: kapabilitas penandatanganan yang tersedia umum, AdES-compliant, FIPS-validated, atau certified.

Batas standar

Standar yang terlibat dipelihara oleh badan eksternal, dan preview ini tidak mengambil posisi atas konformitas terhadap salah satunya:

Parameter set algoritma dan panjang tanda tangan mengikuti FIPS 204 (ML-DSA) dan FIPS 205 (SLH-DSA).
Pengenal mekanisme token mengikuti OASIS PKCS#11; registry mekanisme pasca-kuantum dalam PKCS#11 v3.1 belum difinalkan, sehingga NextPDF memakai pengenal provisional.
Profil arsip-jangka-panjang tanda-tangan-PDF adalah ETSI EN 319 142-2 (profil PAdES extended, dibangun di atas CMS SignerInfo) dan katalog suite-kriptografi ETSI TS 119 312, yang saat ini hanya memprofilkan RSA dan ECDSA — tidak ada suite pasca-kuantum yang terdaftar untuk CAdES/PAdES. Oleh karena itu sebuah tanda tangan PDF pasca-kuantum yang dihasilkan hari ini belum AdES-compliant untuk arsip.

Tidak ada teks standar yang direproduksi pada halaman ini.

Catatan keamanan

Sebuah preview bukanlah kontrol keamanan. Kehadiran tanda tangan pasca-kuantum yang dihasilkan oleh jalur ini tidak menetapkan validitas AdES, tidak menyiratkan kunci tepercaya, dan tidak dapat-diverifikasi oleh NextPDF (tidak ada jalur verifikasi pasca-kuantum). Jangan mengandalkan preview ini untuk jaminan tanda tangan, dan jangan menyebarkannya di tempat yang membutuhkan tanda tangan AdES-compliant atau FIPS-validated. Jaga kedua gerbang tetap mati dalam produksi sampai standar mendarat.

Permukaan API

Simbol	Peran
`Pkcs11Signer::signPqs()`	Penandatanganan pasca-kuantum yang didelegasikan-HSM melalui PKCS#11 yang opt-in dan fail-closed. Melempar `HsmOperationException` saat dinonaktifkan, saat kunci tidak ada, atau pada ketidaksesuaian panjang-tanda-tangan.
`Pkcs11Signer::isPostQuantumEnabled()`	Apakah opt-in per-signer `$enablePostQuantum` disetel.
`Pkcs11PqsAlgorithm`	Enum parameter set ML-DSA (FIPS 204) dan SLH-DSA (FIPS 205); memetakan masing-masing ke id mekanisme provisional dan panjang tanda tangan yang diwajibkan-FIPS.
`PqsPreviewFeature`	Gerbang env tingkat-proses, default-mati (`NEXTPDF_FEATURE_PREVIEW_PQS_HSM`).
`PqsCapabilityStatus`	Status yang jujur dan dapat-dibaca-mesin: setiap boolean klaim positif (generally-available, AdES, verification, conformance) di-hardcode `false` terlepas dari flag preview.
`HsmOperationException`	Eksepsi bertipe yang dimunculkan pada jalur fail-closed.

Batas publikasi

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