Enterprise edisistabilitas: Eksperimental

Pratinjau penandatanganan pasca-kuantum — Referensi Mendalam

Sekilas pandang

Halaman ini adalah referensi tingkat kontrak untuk permukaan pratinjau penandatanganan pasca-kuantum (PQS) di NextPDF Enterprise. Halaman ini mencakup tiga simbol publik: enum parameter-set Pkcs11PqsAlgorithm, gerbang proses PqsPreviewFeature, dan deskriptor PqsCapabilityStatus. Halaman ini juga mendokumentasikan gerbang lingkungan NEXTPDF_FEATURE_PREVIEW_PQS_HSM.

Permukaan ini bersifat experimental dan nonaktif secara default. Ia mengenali pengenal algoritma, parameter set, dan panjang tanda tangan ML-DSA (FIPS 204) dan SLH-DSA (FIPS 205). Pengenalan bukanlah putusan validasi. Tidak ada jalur verifikasi pasca-kuantum. Tidak ada klaim AdES, validasi FIPS, atau kesesuaian yang dibuat, dan flag pratinjau tidak dapat menciptakannya. Titik masuk penandatanganan yang mengonsumsinya, Pkcs11Signer::signPqs(), dijelaskan pada halaman kapabilitas.

Ketersediaan & lisensi

Kapabilitas ini disertakan 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.

Lisensi mengaktifkan permukaan PKCS#11 Enterprise secara keseluruhan. Jalur pasca-kuantum di dalamnya tetap berupa pratinjau terlepas dari tingkat lisensi. Dua opt-in independen tetap diperlukan: gerbang proses yang didokumentasikan di sini dan flag konstruktor per-signer pada Pkcs11Signer.

Permukaan API publik

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
`Pkcs11PqsAlgorithm`	enum berbasis string, 15 case	Menamai satu parameter set FIPS 204 / FIPS 205 per case	case enum	Tidak ada saat akses case	Nilai case adalah nama parameter-set, mis. `ML-DSA-65`.
`Pkcs11PqsAlgorithm::isMlDsa()`	tidak ada	Uji keluarga	`bool`	Tidak melempar	`true` untuk `MlDsa44`, `MlDsa65`, `MlDsa87`.
`Pkcs11PqsAlgorithm::isSlhDsa()`	tidak ada	Negasi dari `isMlDsa()`	`bool`	Tidak melempar	`true` untuk dua belas case SLH-DSA.
`Pkcs11PqsAlgorithm::mechanismId()`	tidak ada	Memetakan keluarga ke kandidat id mekanisme PQ PKCS#11 v3.1	`int`	PHP `Error` ketika runtime tidak memiliki konstanta PQ `Pkcs11` sementara	`CKM_ML_DSA` atau `CKM_SLH_DSA`; kedua id bersifat sementara.
`Pkcs11PqsAlgorithm::parameterSetId()`	tidak ada	Memetakan case ke diskriminator parameter-set OASIS	`int`	PHP `Error` ketika runtime tidak memiliki konstanta PQ `Pkcs11` sementara	Nilai `CKP_*`; sementara.
`Pkcs11PqsAlgorithm::signatureLength()`	tidak ada	Panjang byte tanda tangan yang diamanatkan FIPS untuk case tersebut	`int` (positif)	Tidak melempar	Dikonsumsi oleh jalur penandatanganan untuk menolak tanda tangan yang dikembalikan dengan panjang tak terduga.
`Pkcs11PqsAlgorithm::nistCategory()`	tidak ada	Kategori kekuatan-keamanan NIST yang diklaim	`int`	Tidak melempar	Mengembalikan 1, 2, 3, atau 5.
`PqsPreviewFeature`	enum berbasis string, 1 case	Case tunggal `PREVIEW_PQS_HSM`; konstanta `ENV_PREVIEW_PQS_HSM`	case enum	Tidak ada saat akses case	Gerbang pratinjau tingkat proses.
`PqsPreviewFeature::isEnabled()`	tidak ada	Membaca `getenv()` secara langsung; perbandingan ketat terhadap string `1`	`bool`	Tidak melempar	Variabel yang tidak ada atau nilai lain apa pun, termasuk `0`, `true`, `yes`, berarti nonaktif.
`PqsCapabilityStatus::__construct()`	sembilan field readonly bernama	Membangun instance deskriptor sembarang	`PqsCapabilityStatus`	Tidak melempar	`current()` adalah konstruktor kanonis.
`PqsCapabilityStatus::current()`	tidak ada	Membangun deskriptor untuk proses di sekitarnya	`PqsCapabilityStatus`	Tidak melempar	Setiap boolean klaim tetap; hanya `hsmRoundtripPreviewEnabled` yang bervariasi menurut gerbang.
`PqsCapabilityStatus::summary()`	tidak ada	Teks status satu baris	`string`	Tidak melempar	Frasa tidak membawa klaim ketersediaan, arsip, maupun validasi.

enum Pkcs11PqsAlgorithm: string

case MlDsa44 = 'ML-DSA-44';
case MlDsa65 = 'ML-DSA-65';
case MlDsa87 = 'ML-DSA-87';

case SlhDsaSha2_128s = 'SLH-DSA-SHA2-128s';
case SlhDsaShake_128s = 'SLH-DSA-SHAKE-128s';
case SlhDsaSha2_128f = 'SLH-DSA-SHA2-128f';
case SlhDsaShake_128f = 'SLH-DSA-SHAKE-128f';

case SlhDsaSha2_192s = 'SLH-DSA-SHA2-192s';
case SlhDsaShake_192s = 'SLH-DSA-SHAKE-192s';
case SlhDsaSha2_192f = 'SLH-DSA-SHA2-192f';
case SlhDsaShake_192f = 'SLH-DSA-SHAKE-192f';

case SlhDsaSha2_256s = 'SLH-DSA-SHA2-256s';
case SlhDsaShake_256s = 'SLH-DSA-SHAKE-256s';
case SlhDsaSha2_256f = 'SLH-DSA-SHA2-256f';
case SlhDsaShake_256f = 'SLH-DSA-SHAKE-256f';

public function isMlDsa(): bool
public function isSlhDsa(): bool
public function mechanismId(): int
public function parameterSetId(): int
public function signatureLength(): int
public function nistCategory(): int

enum PqsPreviewFeature: string

case PREVIEW_PQS_HSM = 'preview_pqs_hsm';

public const string ENV_PREVIEW_PQS_HSM = 'NEXTPDF_FEATURE_PREVIEW_PQS_HSM';

public function isEnabled(): bool

final readonly class PqsCapabilityStatus

public const string MATURITY_PREVIEW_EXPERIMENTAL = 'preview-experimental';
public const string MECHANISM_STATUS_PROVISIONAL = 'provisional';

public function __construct(
    public bool $hsmRoundtripPreviewEnabled,
    public bool $generallyAvailable,
    public bool $adesCompliant,
    public bool $verificationAvailable,
    public bool $conformanceClaimed,
    public bool $recognitionOnly,
    public string $maturity,
    public string $mechanismIdStatus,
    public string $envGate,
)

public static function current(): self
public function summary(): string

Kontrak perilaku

Katalog parameter-set. NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm mengenumerasi tiga set ML-DSA (FIPS 204) dan dua belas set SLH-DSA (FIPS 205 §11.p12, Table 2). Setiap case memetakan ke id mekanisme sementara, diskriminator parameter-set, panjang byte tanda tangan yang diamanatkan FIPS, dan kategori NIST yang diklaim.
Panjang tanda tangan. signatureLength() mengembalikan 2420, 3309, dan 4627 byte untuk MlDsa44, MlDsa65, dan MlDsa87, sesuai FIPS 204 §4.p15 (Table 2). Case SLH-DSA mengembalikan 7856, 17088, 16224, 35664, 29792, dan 49856 byte menurut level dan varian, sesuai FIPS 205 §11 (Table 2). Signer yang mengonsumsinya melempar HsmOperationException ketika tanda tangan yang dikembalikan memiliki panjang berbeda, mencerminkan disiplin penolakan-panjang FIPS 204 §x34.
Kategori. nistCategory() mengembalikan 2, 3, dan 5 untuk case ML-DSA, sesuai FIPS 204 §4.p9. Case SLH-DSA mengembalikan 1, 3, dan 5 menurut level parameter-keamanan.
Gerbang proses. PqsPreviewFeature::PREVIEW_PQS_HSM nonaktif secara default. isEnabled() mengembalikan true hanya ketika variabel lingkungan NEXTPDF_FEATURE_PREVIEW_PQS_HSM sama persis dengan string 1. Pembacaan bersifat langsung pada setiap panggilan; tidak ada yang di-memoisasi.
Gerbang pelengkap. Gerbang proses terpisah dari opt-in konstruktor $enablePostQuantum per-signer pada Pkcs11Signer. Panggilan penandatanganan gagal-tertutup tanpa opt-in per-signer. Gerbang proses ada sebagai satu batas yang dapat diaudit untuk setiap perilaku round-trip atau arsip di masa mendatang.
Invarian kejujuran. NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus::current() mengodekan secara permanen generallyAvailable, adesCompliant, verificationAvailable, dan conformanceClaimed menjadi false, serta recognitionOnly menjadi true. Tidak ada konfigurasi, opsi konstruktor, atau flag lingkungan yang mengaktifkan sebuah klaim. Hanya hsmRoundtripPreviewEnabled yang mencerminkan gerbang.
Tidak ada jalur verifikasi. NextPDF tidak memiliki jalur verifikasi pasca-kuantum. Pengenal algoritma yang dikenali atau panjang tanda tangan yang berbentuk baik tidak pernah merupakan putusan penerimaan.

Kasus khusus & mode kegagalan

Menyetel variabel gerbang ke 0, true, yes, on, atau string kosong membuat gerbang tetap nonaktif. Hanya string persis 1 yang mengaktifkannya.
Perubahan putenv() berlaku pada panggilan isEnabled() berikutnya karena pembacaan bersifat langsung. Gerbang yang diubah di tengah proses langsung teramati.
mechanismId() dan parameterSetId() meresolusi konstanta dari namespace ekstensi Pkcs11. Sebuah runtime tanpa konstanta ekstensi pasca-kuantum sementara gagal dengan PHP Error (undefined constant) pada waktu panggilan.
Id mekanisme dan parameter-set bersifat sementara. OASIS belum memfinalisasi registri pasca-kuantum PKCS#11 v3.1. Sebuah token yang firmware-nya menetapkan id berbeda akan gagal pada lapisan PKCS#11; operator harus mengonfirmasi id firmware sebelum mengaktifkan pratinjau.
Konteks penandatanganan yang diterima oleh signer yang mengonsumsinya dibatasi pada 255 byte, sesuai kontrak input penandatanganan FIPS 204 (§x43.p2). Konteks yang lebih panjang melempar InvalidArgumentException sebelum panggilan token apa pun.
PqsCapabilityStatus::__construct() bersifat publik, sehingga instance yang dibangun secara manual dapat membawa boolean sembarang. Instance semacam itu hanyalah value object. Ia tidak mengubah perilaku penandatanganan apa pun. current() adalah konstruktor kanonis yang dikodekan secara permanen.
Pilihan acak-versus-deterministik pada signer yang mengonsumsinya mengikuti semantik FIPS 205 §x65.p7: penandatanganan hedged adalah default. Flag diabaikan untuk ML-DSA, yang selalu mengacak melalui nonce-nya sendiri.

Perilaku mode FIPS

ML-DSA dan SLH-DSA adalah algoritma FIPS 204 dan FIPS 205, tetapi pratinjau ini tidak membawa klaim validasi FIPS 140-3. Tidak ada round-trip HSM pasca-kuantum yang tervalidasi FIPS yang telah ditetapkan untuk jalur ini. Profil kebijakan-kripto mode-FIPS Enterprise, yang didokumentasikan pada Referensi mendalam keamanan, menggerbang algoritma penandatanganan klasik; ia tidak memasukkan permukaan PQS ke dalam set yang tervalidasi. Mengaktifkan mode FIPS tidak membuat penandatanganan pasca-kuantum tervalidasi FIPS. Jangan deploy pratinjau ini di tempat yang membutuhkan tanda tangan tervalidasi FIPS.

Kesesuaian

Klaim	Standar	Klausa
ML-DSA-44/65/87 membawa kategori NIST yang diklaim 2, 3, 5.	FIPS 204	§4.p9
Ukuran tanda tangan ML-DSA adalah 2420, 3309, 4627 byte.	FIPS 204	§4.p15 (Table 2)
String byte konteks penandatanganan dibatasi pada 255 byte.	FIPS 204	§x43.p2
Tanda tangan atau kunci dengan panjang yang salah harus ditolak.	FIPS 204	§x34
Dua belas parameter set SLH-DSA disetujui.	FIPS 205	§11.p12 (Table 2)
Ukuran tanda tangan SLH-DSA mengikuti Table 2 (7856 byte untuk 128s).	FIPS 205	§11.p6
Penandatanganan hedged adalah default; varian deterministik ada.	FIPS 205	§x65.p7
Katalog suite CAdES/PAdES hanya memprofil RSA dan EC-DSA.	ETSI TS 119 312 V1.5.1	§7.x7.p10 (Table A.1)
Id mekanisme PQ PKCS#11 bersifat sementara.	OASIS PKCS#11 v3.1	berbasis product-source

Semua klausa diparafrasakan. NextPDF tidak mereproduksi teks normatif. NextPDF tidak memiliki sertifikasi apa pun dan tidak memberikan apa pun. Pernyataan di atas adalah pernyataan penyelarasan-struktural tentang pengenal, panjang, dan batas. Pernyataan tersebut bukan hasil uji kesesuaian, bukan atestasi pihak ketiga, dan bukan klaim kesesuaian FIPS, OASIS, atau ETSI. PqsCapabilityStatus mengodekan postur ini dalam kode: conformanceClaimed adalah false, adesCompliant adalah false, dan verificationAvailable adalah false, dalam setiap konfigurasi. Tanda tangan yang dihasilkan oleh pratinjau ini tidak sesuai AdES untuk pengarsipan jangka panjang, dan sebagian besar penampil PDF menolaknya pada waktu validasi.

Catatan pengembangan

Registri mekanisme pasca-kuantum OASIS PKCS#11 belum difinalisasi; id CKM_ML_DSA / CKM_SLH_DSA dan konstanta parameter-set yang digunakan di sini bersifat sementara dan berbasis product source, bukan kutipan spesifikasi.
Milestone saat ini adalah kesiapan yang diuji secara mock. Belum ada round-trip HSM firmware-pasca-kuantum nyata yang tervalidasi.
Biarkan kedua gerbang tetap nonaktif di produksi. Pratinjau tidak menambahkan kapabilitas produksi yang tidak dimiliki jalur klasik RSA/ECDSA PKCS#11.
Sebelum evaluasi apa pun dengan perangkat keras nyata, konfirmasikan id mekanisme dan parameter-set firmware token terhadap nilai sementara. Ketidakcocokan gagal pada lapisan PKCS#11, bukan di dalam NextPDF.
Perlakukan PqsCapabilityStatus::current() sebagai satu-satunya sumber kebenaran ketika menampilkan status PQS di tooling atau UI. Jangan menyatakan ulang boolean-nya secara manual.
Keluaran summary() aman untuk log dan endpoint status; frasanya dirancang agar tidak membawa klaim ketersediaan atau validasi.

Lihat juga

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.