Enterprise edizionestabilità: Sperimentale

Anteprima della firma post-quantistica — Riferimento approfondito

In sintesi

Questa pagina è il riferimento a livello di contratto per la superficie di anteprima della firma post-quantistica (PQS) in NextPDF Enterprise. Copre tre simboli pubblici: l’enum di set di parametri Pkcs11PqsAlgorithm, il gate di processo PqsPreviewFeature e il descrittore PqsCapabilityStatus. Documenta inoltre il gate d’ambiente NEXTPDF_FEATURE_PREVIEW_PQS_HSM.

La superficie è sperimentale e disattivata per impostazione predefinita. Riconosce gli identificatori di algoritmo, i set di parametri e le lunghezze di firma ML-DSA (FIPS 204) e SLH-DSA (FIPS 205). Il riconoscimento non è un verdetto di validazione. Non esiste alcun percorso di verifica post-quantistica. Non viene formulata alcuna rivendicazione AdES, di validazione FIPS o di conformità, e il flag di anteprima non può crearne una. Il punto di ingresso di firma consumante, Pkcs11Signer::signPqs(), è descritto nella pagina della capacità.

Disponibilità e licenza

Questa capacità viene fornita in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un involucro di licenza di livello Enterprise. Un’installazione priva di tale entitlement non carica le classi della capacità. Confronta le edizioni e ottieni una licenza.

La licenza attiva la superficie PKCS#11 Enterprise nel suo insieme. Il percorso post-quantistico al suo interno resta un’anteprima indipendentemente dal livello di licenza. Restano necessari due opt-in indipendenti: il gate di processo qui documentato e il flag del costruttore per singolo firmatario su Pkcs11Signer.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
`Pkcs11PqsAlgorithm`	enum basato su string, 15 casi	Nomina un set di parametri FIPS 204 / FIPS 205 per caso	caso enum	Niente all’accesso del caso	I valori dei casi sono i nomi dei set di parametri, ad esempio `ML-DSA-65`.
`Pkcs11PqsAlgorithm::isMlDsa()`	nessuno	Test di famiglia	`bool`	Non solleva	`true` per `MlDsa44`, `MlDsa65`, `MlDsa87`.
`Pkcs11PqsAlgorithm::isSlhDsa()`	nessuno	Negazione di `isMlDsa()`	`bool`	Non solleva	`true` per i dodici casi SLH-DSA.
`Pkcs11PqsAlgorithm::mechanismId()`	nessuno	Mappa la famiglia all’id di meccanismo PQ candidato di PKCS#11 v3.1	`int`	PHP `Error` quando il runtime è privo delle costanti PQ provvisorie `Pkcs11`	`CKM_ML_DSA` o `CKM_SLH_DSA`; entrambi gli id sono provvisori.
`Pkcs11PqsAlgorithm::parameterSetId()`	nessuno	Mappa il caso al discriminatore di set di parametri OASIS	`int`	PHP `Error` quando il runtime è privo delle costanti PQ provvisorie `Pkcs11`	Valori `CKP_*`; provvisori.
`Pkcs11PqsAlgorithm::signatureLength()`	nessuno	Lunghezza di firma in byte imposta da FIPS per il caso	`int` (positivo)	Non solleva	Consumata dal percorso di firma per rifiutare una firma restituita di lunghezza inattesa.
`Pkcs11PqsAlgorithm::nistCategory()`	nessuno	Categoria di forza di sicurezza NIST rivendicata	`int`	Non solleva	Restituisce 1, 2, 3 o 5.
`PqsPreviewFeature`	enum basato su string, 1 caso	Caso singolo `PREVIEW_PQS_HSM`; costante `ENV_PREVIEW_PQS_HSM`	caso enum	Niente all’accesso del caso	Il gate di anteprima a livello di processo.
`PqsPreviewFeature::isEnabled()`	nessuno	Legge `getenv()` in tempo reale; confronto stretto rispetto alla stringa `1`	`bool`	Non solleva	Variabile assente o qualsiasi altro valore, incluso `0`, `true`, `yes`, è disattivato.
`PqsCapabilityStatus::__construct()`	nove campi readonly con nome	Costruisce un’istanza arbitraria del descrittore	`PqsCapabilityStatus`	Non solleva	`current()` è il costruttore canonico.
`PqsCapabilityStatus::current()`	nessuno	Costruisce il descrittore per il processo circostante	`PqsCapabilityStatus`	Non solleva	Ogni booleano di rivendicazione è fisso; solo `hsmRoundtripPreviewEnabled` varia con il gate.
`PqsCapabilityStatus::summary()`	nessuno	Testo di stato su una riga	`string`	Non solleva	La formulazione non porta alcuna rivendicazione di disponibilità, archiviazione o validazione.

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

Contratto di comportamento

Catalogo dei set di parametri. NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm enumera tre set ML-DSA (FIPS 204) e dodici set SLH-DSA (FIPS 205 §11.p12, Table 2). Ogni caso mappa a un id di meccanismo provvisorio, a un discriminatore di set di parametri, a una lunghezza di firma in byte imposta da FIPS e a una categoria NIST rivendicata.
Lunghezze di firma. signatureLength() restituisce 2420, 3309 e 4627 byte per MlDsa44, MlDsa65 e MlDsa87, secondo FIPS 204 §4.p15 (Table 2). I casi SLH-DSA restituiscono 7856, 17088, 16224, 35664, 29792 e 49856 byte per livello e variante, secondo FIPS 205 §11 (Table 2). Il firmatario consumante solleva HsmOperationException quando una firma restituita ha una lunghezza differente, rispecchiando la disciplina di rifiuto per lunghezza di FIPS 204 §x34.
Categorie. nistCategory() restituisce 2, 3 e 5 per i casi ML-DSA, secondo FIPS 204 §4.p9. I casi SLH-DSA restituiscono 1, 3 e 5 per livello del parametro di sicurezza.
Gate di processo. PqsPreviewFeature::PREVIEW_PQS_HSM è disattivato per impostazione predefinita. isEnabled() restituisce true solo quando la variabile d’ambiente NEXTPDF_FEATURE_PREVIEW_PQS_HSM è esattamente uguale alla stringa 1. La lettura è in tempo reale a ogni chiamata; nulla viene memoizzato.
Gating complementare. Il gate di processo è separato dall’opt-in del costruttore $enablePostQuantum per singolo firmatario su Pkcs11Signer. La chiamata di firma fallisce in modo chiuso senza l’opt-in per singolo firmatario. Il gate di processo esiste come singolo confine verificabile per qualsiasi futuro comportamento di round-trip o archiviazione.
Invariante di onestà. NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus::current() imposta in modo cablato generallyAvailable, adesCompliant, verificationAvailable e conformanceClaimed a false, e recognitionOnly a true. Nessuna configurazione, opzione del costruttore o flag d’ambiente attiva una rivendicazione. Solo hsmRoundtripPreviewEnabled riflette il gate.
Nessun percorso di verifica. NextPDF non ha alcun percorso di verifica post-quantistica. Un identificatore di algoritmo riconosciuto o una lunghezza di firma ben formata non è mai un verdetto di accettazione.

Casi limite e modalità di errore

Impostare la variabile del gate a 0, true, yes, on o a una stringa vuota lascia il gate disattivato. Solo la stringa esatta 1 lo abilita.
Le modifiche di putenv() hanno effetto alla successiva chiamata di isEnabled() perché la lettura è in tempo reale. Un gate commutato durante il processo viene osservato immediatamente.
mechanismId() e parameterSetId() risolvono le costanti dallo spazio dei nomi dell’estensione Pkcs11. Un runtime privo delle costanti provvisorie dell’estensione post-quantistica fallisce con un PHP Error (costante non definita) al momento della chiamata.
Gli id di meccanismo e di set di parametri sono provvisori. OASIS non ha finalizzato il registro post-quantistico di PKCS#11 v3.1. Un token il cui firmware assegna id differenti fallirà a livello PKCS#11; gli operatori devono confermare gli id del firmware prima di abilitare l’anteprima.
Il contesto di firma accettato dal firmatario consumante è limitato a 255 byte, in linea con il contratto di input di firma di FIPS 204 (§x43.p2). Un contesto più lungo solleva InvalidArgumentException prima di qualsiasi chiamata al token.
PqsCapabilityStatus::__construct() è pubblico, quindi un’istanza costruita a mano può portare booleani arbitrari. Tale istanza è solo un oggetto valore. Non altera alcun comportamento di firma. current() è il costruttore canonico e cablato.
La scelta tra randomizzato e deterministico sul firmatario consumante segue la semantica di FIPS 205 §x65.p7: la firma hedged è quella predefinita. Il flag viene ignorato per ML-DSA, che randomizza sempre tramite il proprio nonce.

Comportamento in modalità FIPS

ML-DSA e SLH-DSA sono algoritmi FIPS 204 e FIPS 205, ma questa anteprima non porta alcuna rivendicazione di validazione FIPS 140-3. Nessun round-trip HSM post-quantistico validato FIPS è stato stabilito per questo percorso. Il profilo della crypto-policy in modalità FIPS di Enterprise, documentato nel Riferimento approfondito sulla sicurezza, effettua il gating degli algoritmi di firma classici; non ammette la superficie PQS in un insieme validato. Abilitare la modalità FIPS non rende la firma post-quantistica validata FIPS. Non implementare l’anteprima laddove sia richiesta una firma validata FIPS.

Conformità

Rivendicazione	Standard	Clausola
ML-DSA-44/65/87 portano le categorie NIST rivendicate 2, 3, 5.	FIPS 204	§4.p9
Le dimensioni di firma ML-DSA sono 2420, 3309, 4627 byte.	FIPS 204	§4.p15 (Table 2)
La stringa di byte del contesto di firma è limitata a 255 byte.	FIPS 204	§x43.p2
Una firma o chiave di lunghezza errata deve essere rifiutata.	FIPS 204	§x34
Dodici set di parametri SLH-DSA sono approvati.	FIPS 205	§11.p12 (Table 2)
Le dimensioni di firma SLH-DSA seguono la Table 2 (7856 byte per 128s).	FIPS 205	§11.p6
La firma hedged è quella predefinita; esiste una variante deterministica.	FIPS 205	§x65.p7
Il catalogo delle suite CAdES/PAdES profila solo RSA ed EC-DSA.	ETSI TS 119 312 V1.5.1	§7.x7.p10 (Table A.1)
Gli id di meccanismo PQ di PKCS#11 sono provvisori.	OASIS PKCS#11 v3.1	fondato sul codice sorgente del prodotto

Tutte le clausole sono parafrasate. NextPDF non riproduce il testo normativo. NextPDF non detiene alcuna certificazione e non ne concede alcuna. Le affermazioni di cui sopra sono affermazioni di allineamento strutturale su identificatori, lunghezze e limiti. Non sono risultati di test di conformità, non sono attestazioni di terze parti e non sono una rivendicazione di conformità FIPS, OASIS o ETSI. PqsCapabilityStatus codifica questa postura nel codice: conformanceClaimed è false, adesCompliant è false e verificationAvailable è false, in ogni configurazione. Una firma prodotta da questa anteprima non è conforme ad AdES per l’archiviazione a lungo termine, e la maggior parte dei visualizzatori PDF la rifiuta al momento della validazione.

Note di sviluppo

Il registro dei meccanismi post-quantistici di OASIS PKCS#11 non è finalizzato; gli id CKM_ML_DSA / CKM_SLH_DSA e le costanti dei set di parametri qui utilizzati sono provvisori e fondati sul codice sorgente del prodotto, non su una citazione di specifica.
Il traguardo attuale è la prontezza testata su mock. Nessun round-trip HSM con firmware post-quantistico reale è ancora stato validato.
Mantieni entrambi i gate disattivati in produzione. L’anteprima non aggiunge alcuna capacità di produzione che manchi al percorso PKCS#11 classico RSA/ECDSA.
Prima di qualsiasi valutazione con hardware reale, conferma gli id di meccanismo e di set di parametri del firmware del token rispetto ai valori provvisori. Un disallineamento fallisce a livello PKCS#11, non all’interno di NextPDF.
Tratta PqsCapabilityStatus::current() come l’unica fonte di verità quando esponi lo stato PQS in strumenti o UI. Non riformulare i suoi booleani manualmente.
L’output di summary() è sicuro per log ed endpoint di stato; è formulato in modo da non portare alcuna rivendicazione di disponibilità o validazione.

Vedi anche

Confine di pubblicazione

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