Enterprise edizionestabilità: Sperimentale

Stato della capacità di anteprima della firma HSM post-quantistica (PQS)

In sintesi

Stato della capacità di anteprima. Opt-in, disattivata per impostazione predefinita, fail-closed. Questa è un’anteprima della firma post-quantistica delegata a HSM. Non è generalmente disponibile, non è AdES-compliant, non è FIPS-validated e non avanza alcuna rivendicazione di certificazione o conformità. L’anteprima è spenta finché non si effettua l’opt-in; quando è spenta, la chiamata di firma fallisce in modo fail-closed con un’eccezione tipizzata.

NextPDF Enterprise espone una superficie sperimentale di firma post-quantistica (PQS) che guida la firma ML-DSA (FIPS 204) e SLH-DSA (FIPS 205) attraverso un token hardware PKCS#11. Il percorso è Pkcs11Signer::signPqs(), gestito dietro un opt-in per-signer esplicito ($enablePostQuantum) e, separatamente, dietro un flag d’ambiente a livello di processo (NEXTPDF_FEATURE_PREVIEW_PQS_HSM). Entrambi sono spenti per impostazione predefinita.

Questa pagina è il confine onesto. Dichiara cosa l’anteprima fa — delega un’operazione reale di firma post-quantistica al token — e, con pari onestà, cosa non è: non è GA, non è AdES, non è FIPS-validated e non è una rivendicazione di conformità rispetto a FIPS, OASIS o ETSI. Gli standard che renderebbero interoperabile una firma PDF post-quantistica per l’archiviazione a lungo termine non sono ancora arrivati (vedi Confine normativo).

Disponibilità e licenza

Questa capacità è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di livello Enterprise. Un deployment privo di tale entitlement non carica le classi della capacità. Confronta le edizioni e ottieni una licenza.

Si basa sul signer con token hardware PKCS#11 di Enterprise — vedi Firma HSM. Il percorso di firma PKCS#11 classico (RSA / ECDSA) è la capacità Enterprise supportata e stabile; il percorso post-quantistico qui descritto è un’anteprima sperimentale sovrapposta a esso. NextPDF Enterprise include l’insieme di funzionalità Pro.

Stato della capacità di anteprima

L’anteprima guida un’operazione di firma genuina: quando è abilitata, signPqs() inoltra al meccanismo post-quantistico candidato di PKCS#11 v3.1 sul token, la chiave privata non lascia mai il confine del token, e i byte restituiti sono verificati in lunghezza rispetto alla lunghezza di firma imposta da FIPS per l’insieme di parametri scelto prima di essere accettati.

Al contempo, è un’anteprima e non una capacità di prodotto generalmente disponibile:

Il meccanismo post-quantistico PKCS#11 e gli identificatori dell’insieme di parametri sono provvisori — OASIS PKCS#11 v3.1 non ha finalizzato un registro di meccanismi post-quantistici, perciò i valori usati sono tracciati come provvisori e gli operatori HSM devono confermare che il PQ firmware del loro token corrisponda a essi prima di abilitare.
Non esiste alcun percorso di verifica post-quantistica in NextPDF, e nessuna suite ETSI registra una firma post-quantistica per l’archiviazione a lungo termine AdES, perciò una firma prodotta qui non è ancora interoperabile e la maggior parte dei viewer PDF la rifiuterà al momento della convalida.
Un descrittore complementare, PqsCapabilityStatus, segnala questi fatti in una forma leggibile dalla macchina. Ogni booleano di rivendicazione positiva — generallyAvailable, adesCompliant, verificationAvailable, conformanceClaimed — è hard-coded a false e resta false anche quando il flag di anteprima è attivo, e nessuna configurazione può invertirne uno. (Porta inoltre un flag recognitionOnly, hard-coded true, che registra che il riconoscimento dell’algoritmo non è mai un verdetto di conformità; non significa che la superficie non possa firmare — la firma avviene tramite signPqs() come descritto sopra.)

Perché funziona così

NextPDF può già calcolare una firma ML-DSA o SLH-DSA reale attraverso il token. Anche così, ogni booleano di conformità resta hard-coded a false, dietro due gate disattivati per impostazione predefinita. Una firma vale solo per la capacità di verificarla in seguito. Per il post-quantistico non esiste ancora alcun percorso di verifica, nessuna suite AdES ETSI registrata e nessun round-trip HSM FIPS-validated. Distribuire questo come generalmente disponibile emetterebbe firme che nessun viewer può convalidare e nessun archivio può considerare attendibili. Perciò il design separa la produzione dei byte dalla rivendicazione che qualcuno possa farvi affidamento, e nessun flag di anteprima può offuscare quella linea.

Background di progettazione: Convalida a lungo termine.

Insiemi di parametri degli algoritmi

signPqs() seleziona l’algoritmo e l’insieme di parametri attraverso l’enum Pkcs11PqsAlgorithm. Ogni caso mappa un insieme di parametri NIST a un identificatore provvisorio di meccanismo / insieme di parametri PKCS#11 e alla lunghezza in byte della firma imposta da FIPS usata per il controllo di lunghezza defence-in-depth.

ML-DSA — FIPS 204 (module-lattice). Tre insiemi di parametri, rivendicati alle categorie di security-strength NIST mostrate:

Insieme di parametri	Categoria NIST	Lunghezza firma (byte)
`ML-DSA-44`	2	2420
`ML-DSA-65` (predefinito consigliato)	3	3309
`ML-DSA-87`	5	4627

SLH-DSA — FIPS 205 (stateless hash-based). Dodici insiemi di parametri, formati come SHA2 / SHAKE x 128 / 192 / 256 x small (s) / fast (f). Le varianti s minimizzano la dimensione della firma; le varianti f minimizzano la latenza di firma:

Famiglia di insiemi di parametri	Categoria NIST	Lunghezza firma (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

Abilitare l’anteprima

Due gate indipendenti devono essere entrambi aperti. Entrambi sono spenti per impostazione predefinita.

Gate di processo. Impostare NEXTPDF_FEATURE_PREVIEW_PQS_HSM=1 prima che il processo si avvii (o tramite putenv() prima che lo stato venga letto). È richiesta l’uguaglianza rigorosa con la stringa 1; qualsiasi altro valore — incluso 0, true, yes o vuoto — è trattato come spento.
Opt-in per-signer. Passare $enablePostQuantum: true al costruttore di 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() segnala se l’opt-in per-signer è stato impostato, e PqsCapabilityStatus::current() segnala lo stato a livello di processo più i booleani di rivendicazione onesti.

Confine fail-closed

La superficie è fail-closed e segnala i fallimenti attraverso eccezioni nominate e tipizzate anziché con un fallback silenzioso:

Opt-in assente. Se signPqs() viene chiamato quando $enablePostQuantum è false, solleva HsmOperationException. Nessuna firma avviene.
Contesto troppo lungo. Una stringa di ottetti di contesto di firma più lunga di 255 byte solleva InvalidArgumentException (per il limite di contesto di FIPS 204 / FIPS 205) prima di qualsiasi chiamata al token.
Chiave assente. Se nessuna chiave privata corrisponde all’etichetta configurata sul token, signPqs() solleva HsmOperationException.
Discrepanza di lunghezza. Se il token restituisce una firma la cui lunghezza in byte non è uguale alla lunghezza imposta da FIPS per l’insieme di parametri, signPqs() solleva HsmOperationException — una firma malformata (troncata o sovradimensionata) è rifiutata prima di poter raggiungere la codifica CMS SignedData.
Errore del token. Qualsiasi errore PKCS#11 sottostante è incapsulato in HsmOperationException.

Il flag d’ambiente a livello di processo non cambia nulla di questo confine: anche quando il flag è attivo, i booleani di capacità restano false e il percorso di firma resta verificato in lunghezza e fail-closed.

Confine onesto

Le rivendicazioni seguenti non vengono avanzate per questa superficie e non devono comparire in alcuna documentazione, UI o materiale di marketing da essa derivato:

“GA” / “generally available”.
“AdES” / “PAdES-compliant” — nessuna suite ETSI registra una firma post-quantistica per l’archiviazione a lungo termine.
“FIPS-validated” — nessun round-trip HSM post-quantistico FIPS-140-3 validated è stato stabilito per questo percorso.
“certified” o “conformant” rispetto a FIPS, OASIS PKCS#11 v3.1 o ETSI.
“production-ready”.

Cosa la superficie è onestamente: un’anteprima opt-in, disattivata per impostazione predefinita e fail-closed di firma post-quantistica delegata a HSM che guida ML-DSA / SLH-DSA attraverso un token PKCS#11 e verifica in lunghezza il risultato. Cosa non è: una capacità di firma generalmente disponibile, AdES-compliant, FIPS-validated o certified.

Confine normativo

Gli standard coinvolti sono mantenuti da enti esterni, e l’anteprima non prende alcuna posizione sulla conformità a uno qualsiasi di essi:

Gli insiemi di parametri degli algoritmi e le lunghezze di firma seguono FIPS 204 (ML-DSA) e FIPS 205 (SLH-DSA).
Gli identificatori del meccanismo del token seguono OASIS PKCS#11; il registro dei meccanismi post-quantistici in PKCS#11 v3.1 non è ancora finalizzato, perciò NextPDF usa identificatori provvisori.
I profili di archiviazione a lungo termine per le firme PDF sono ETSI EN 319 142-2 (profili estesi PAdES, costruiti su CMS SignerInfo) e il catalogo delle suite crittografiche ETSI TS 119 312, che attualmente profila solo RSA ed ECDSA — nessuna suite post-quantistica è registrata per CAdES/PAdES. Una firma PDF post-quantistica prodotta oggi non è pertanto ancora AdES-compliant per l’archiviazione.

Nessun testo normativo è riprodotto in questa pagina.

Note sulla sicurezza

Un’anteprima non è un controllo di sicurezza. La presenza di una firma post-quantistica prodotta da questo percorso non stabilisce la validità AdES, non implica una chiave attendibile e non è verificabile da NextPDF (non esiste alcun percorso di verifica post-quantistica). Non fare affidamento su questa anteprima per garanzie di firma, e non distribuirla dove è richiesta una firma AdES-compliant o FIPS-validated. Mantenere entrambi i gate spenti in produzione finché gli standard non arrivano.

Superficie API

Simbolo	Ruolo
`Pkcs11Signer::signPqs()`	Firma post-quantistica delegata a HSM opt-in e fail-closed attraverso PKCS#11. Solleva `HsmOperationException` quando è disabilitata, quando la chiave è assente o in caso di discrepanza di lunghezza della firma.
`Pkcs11Signer::isPostQuantumEnabled()`	Se l’opt-in per-signer `$enablePostQuantum` è stato impostato.
`Pkcs11PqsAlgorithm`	Enum degli insiemi di parametri ML-DSA (FIPS 204) e SLH-DSA (FIPS 205); mappa ciascuno a un id di meccanismo provvisorio e alla lunghezza di firma imposta da FIPS.
`PqsPreviewFeature`	Gate d’ambiente a livello di processo, disattivato per impostazione predefinita (`NEXTPDF_FEATURE_PREVIEW_PQS_HSM`).
`PqsCapabilityStatus`	Stato onesto e leggibile dalla macchina: ogni booleano di rivendicazione positiva (generally-available, AdES, verifica, conformità) è hard-coded a `false` indipendentemente dal flag di anteprima.
`HsmOperationException`	L’eccezione tipizzata sollevata sui percorsi fail-closed.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile esternamente e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.