Enterprise editiestabiliteit: Experimenteel

Post-quantum ondertekeningspreview — Diepe referentie

In één oogopslag

Deze pagina is de referentie op contractniveau voor het post-quantum signing (PQS) preview-oppervlak in NextPDF Enterprise. Ze behandelt drie publieke symbolen: de Pkcs11PqsAlgorithm parameter-set-enum, de PqsPreviewFeature process gate, en de PqsCapabilityStatus descriptor. Ze documenteert ook de NEXTPDF_FEATURE_PREVIEW_PQS_HSM omgevingsgate.

Het oppervlak is experimental en standaard uitgeschakeld. Het herkent ML-DSA (FIPS 204) en SLH-DSA (FIPS 205) algorithm identifiers, parametersets en signatuurlengtes. Herkenning is geen validatieverdict. Er is geen post-quantum-verificatiepad. Er wordt geen AdES-, FIPS-validatie- of conformiteitsclaim gemaakt, en de preview-vlag kan er geen creëren. Het consumerende ondertekeningsingangspunt, Pkcs11Signer::signPqs(), wordt beschreven op de capability-pagina.

Beschikbaarheid & licentiëring

Deze capability wordt geleverd in NextPDF Enterprise (nextpdf/enterprise) en activeert met een licentie-envelop op Enterprise-niveau. Een deployment zonder die entitlement laadt de klassen van de capability niet. Vergelijk edities en verkrijg een licentie.

De licentie activeert het Enterprise PKCS#11-oppervlak als geheel. Het post-quantum-pad daarbinnen blijft een preview, ongeacht het licentieniveau. Er zijn nog steeds twee onafhankelijke opt-ins vereist: de process gate die hier gedocumenteerd is en de per-signer constructor-vlag op Pkcs11Signer.

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`Pkcs11PqsAlgorithm`	string-backed enum, 15 cases	Benoemt per case één FIPS 204 / FIPS 205 parameterset	enum-case	Niets bij case-toegang	Case-waarden zijn de parameter-set-namen, bv. `ML-DSA-65`.
`Pkcs11PqsAlgorithm::isMlDsa()`	geen	Familietest	`bool`	Gooit niet	`true` voor `MlDsa44`, `MlDsa65`, `MlDsa87`.
`Pkcs11PqsAlgorithm::isSlhDsa()`	geen	Negatie van `isMlDsa()`	`bool`	Gooit niet	`true` voor de twaalf SLH-DSA-cases.
`Pkcs11PqsAlgorithm::mechanismId()`	geen	Mapt de familie op de kandidaat-PKCS#11 v3.1 PQ mechanism id	`int`	PHP `Error` wanneer de runtime de voorlopige `Pkcs11` PQ-constanten mist	`CKM_ML_DSA` of `CKM_SLH_DSA`; beide ids zijn voorlopig.
`Pkcs11PqsAlgorithm::parameterSetId()`	geen	Mapt de case op de OASIS parameter-set-discriminator	`int`	PHP `Error` wanneer de runtime de voorlopige `Pkcs11` PQ-constanten mist	`CKP_*` waarden; voorlopig.
`Pkcs11PqsAlgorithm::signatureLength()`	geen	FIPS-voorgeschreven signatuurbytelengte voor de case	`int` (positief)	Gooit niet	Geconsumeerd door het ondertekeningspad om een geretourneerde signatuur met onverwachte lengte af te wijzen.
`Pkcs11PqsAlgorithm::nistCategory()`	geen	Geclaimde NIST security-strength-categorie	`int`	Gooit niet	Retourneert 1, 2, 3 of 5.
`PqsPreviewFeature`	string-backed enum, 1 case	Enkele case `PREVIEW_PQS_HSM`; constante `ENV_PREVIEW_PQS_HSM`	enum-case	Niets bij case-toegang	De preview-gate op procesniveau.
`PqsPreviewFeature::isEnabled()`	geen	Leest `getenv()` live; strikte vergelijking met de string `1`	`bool`	Gooit niet	Een afwezige variabele of elke andere waarde, inclusief `0`, `true`, `yes`, staat uit.
`PqsCapabilityStatus::__construct()`	negen benoemde readonly-velden	Bouwt een willekeurige descriptor-instantie	`PqsCapabilityStatus`	Gooit niet	`current()` is de canonieke constructor.
`PqsCapabilityStatus::current()`	geen	Bouwt de descriptor voor het omringende proces	`PqsCapabilityStatus`	Gooit niet	Elke claim-boolean staat vast; alleen `hsmRoundtripPreviewEnabled` varieert met de gate.
`PqsCapabilityStatus::summary()`	geen	Statustekst van één regel	`string`	Gooit niet	De formulering draagt geen beschikbaarheids-, archiverings- of validatieclaim.

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

Gedragscontract

Parameter-set-catalogus. NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm somt drie ML-DSA-sets (FIPS 204) en twaalf SLH-DSA-sets op (FIPS 205 §11.p12, Table 2). Elke case mapt op een voorlopige mechanism id, een parameter-set-discriminator, een FIPS-voorgeschreven signatuurbytelengte, en een geclaimde NIST-categorie.
Signatuurlengtes. signatureLength() retourneert 2420, 3309 en 4627 bytes voor MlDsa44, MlDsa65 en MlDsa87, conform FIPS 204 §4.p15 (Table 2). De SLH-DSA-cases retourneren 7856, 17088, 16224, 35664, 29792 en 49856 bytes naar niveau en variant, conform FIPS 205 §11 (Table 2). De consumerende signer gooit HsmOperationException wanneer een geretourneerde signatuur een andere lengte heeft, wat de lengte-afwijzingsdiscipline van FIPS 204 §x34 weerspiegelt.
Categorieën. nistCategory() retourneert 2, 3 en 5 voor de ML-DSA-cases, conform FIPS 204 §4.p9. De SLH-DSA-cases retourneren 1, 3 en 5 naar security-parameter-niveau.
Process gate. PqsPreviewFeature::PREVIEW_PQS_HSM staat standaard uit. isEnabled() retourneert true alleen wanneer de omgevingsvariabele NEXTPDF_FEATURE_PREVIEW_PQS_HSM exact gelijk is aan de string 1. De lezing is live bij elke aanroep; niets wordt gememoïseerd.
Complementaire gating. De process gate staat los van de per-signer $enablePostQuantum constructor-opt-in op Pkcs11Signer. De ondertekeningsaanroep faalt gesloten zonder de per-signer-opt-in. De process gate bestaat als één auditeerbare grens voor toekomstig round-trip- of archiveringsgedrag.
Eerlijkheidsinvariant. NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus::current() codeert generallyAvailable, adesCompliant, verificationAvailable en conformanceClaimed hard op false, en recognitionOnly op true. Geen enkele configuratie, constructor-optie of omgevingsvlag zet een claim aan. Alleen hsmRoundtripPreviewEnabled weerspiegelt de gate.
Geen verificatiepad. NextPDF heeft geen post-quantum-verificatiepad. Een herkende algorithm identifier of een welgevormde signatuurlengte is nooit een acceptatieverdict.

Randgevallen & faalmodi

Het zetten van de gate-variabele op 0, true, yes, on, of een lege string laat de gate uit. Alleen de exacte string 1 schakelt hem in.
putenv()-wijzigingen worden van kracht bij de volgende isEnabled()-aanroep omdat de lezing live is. Een gate die midden in het proces wordt omgeschakeld, wordt onmiddellijk waargenomen.
mechanismId() en parameterSetId() resolven constanten uit de Pkcs11 extensie-namespace. Een runtime zonder de voorlopige post-quantum-extensieconstanten faalt met een PHP Error (undefined constant) op het moment van aanroep.
De mechanism- en parameter-set-ids zijn voorlopig. OASIS heeft het PKCS#11 v3.1 post-quantum-register niet gefinaliseerd. Een token waarvan de firmware andere ids toewijst, faalt op de PKCS#11-laag; operators moeten de firmware-ids bevestigen voordat ze de preview inschakelen.
De ondertekeningscontext die de consumerende signer accepteert, is begrensd op 255 bytes, in lijn met het FIPS 204 signing-input-contract (§x43.p2). Een langere context gooit InvalidArgumentException voordat er enige token-aanroep plaatsvindt.
PqsCapabilityStatus::__construct() is public, dus een handmatig gebouwde instantie kan willekeurige booleans dragen. Zo’n instantie is slechts een value object. Ze verandert geen enkel ondertekeningsgedrag. current() is de canonieke, hard-gecodeerde constructor.
De keuze tussen gerandomiseerd en deterministisch op de consumerende signer volgt de semantiek van FIPS 205 §x65.p7: hedged signing is de standaard. De vlag wordt genegeerd voor ML-DSA, dat altijd randomiseert via zijn eigen nonce.

FIPS-modusgedrag

ML-DSA en SLH-DSA zijn FIPS 204- en FIPS 205-algoritmen, maar deze preview draagt geen FIPS 140-3-validatieclaim. Er is geen FIPS-gevalideerde post-quantum-HSM-round-trip voor dit pad vastgesteld. Het Enterprise FIPS-modus crypto-policy-profiel, gedocumenteerd op de Security deep reference, gate’t de klassieke ondertekeningsalgoritmen; het laat het PQS-oppervlak niet toe tot een gevalideerde set. Het inschakelen van de FIPS-modus maakt post-quantum-ondertekening niet FIPS-gevalideerd. Deploy de preview niet waar een FIPS-gevalideerde signatuur vereist is.

Conformiteit

Claim	Standaard	Clausule
ML-DSA-44/65/87 dragen geclaimde NIST-categorieën 2, 3, 5.	FIPS 204	§4.p9
ML-DSA-signatuurgroottes zijn 2420, 3309, 4627 bytes.	FIPS 204	§4.p15 (Table 2)
De signing-context-bytestring is begrensd op 255 bytes.	FIPS 204	§x43.p2
Een signatuur of sleutel met verkeerde lengte moet worden afgewezen.	FIPS 204	§x34
Twaalf SLH-DSA-parametersets zijn goedgekeurd.	FIPS 205	§11.p12 (Table 2)
SLH-DSA-signatuurgroottes volgen Table 2 (7856 bytes voor 128s).	FIPS 205	§11.p6
Hedged signing is de standaard; er bestaat een deterministische variant.	FIPS 205	§x65.p7
De CAdES/PAdES-suites-catalogus profileert alleen RSA en EC-DSA.	ETSI TS 119 312 V1.5.1	§7.x7.p10 (Table A.1)
De PKCS#11 PQ mechanism-ids zijn voorlopig.	OASIS PKCS#11 v3.1	product-source grounded

Alle clausules zijn geparafraseerd. NextPDF reproduceert geen normatieve tekst. NextPDF houdt geen certificering en verleent er geen. De bovenstaande uitspraken zijn structurele-uitlijningsuitspraken over identifiers, lengtes en grenzen. Het zijn geen conformiteitstestresultaten, geen attestaties van derden, en geen FIPS-, OASIS- of ETSI-conformiteitsclaim. PqsCapabilityStatus codeert deze houding in code: conformanceClaimed is false, adesCompliant is false, en verificationAvailable is false, in elke configuratie. Een signatuur die door deze preview wordt geproduceerd, is niet AdES-compliant voor langetermijnarchivering, en de meeste PDF-viewers wijzen hem af op het moment van validatie.

Ontwikkelnotities

Het OASIS PKCS#11 post-quantum-mechanism-register is niet gefinaliseerd; de CKM_ML_DSA / CKM_SLH_DSA ids en parameter-set-constanten die hier worden gebruikt, zijn voorlopig en zijn grounded vanuit de product-source, niet een spec-citaat.
De huidige mijlpaal is mock-geteste gereedheid. Er is nog geen echte post-quantum-firmware-HSM-round-trip gevalideerd.
Houd beide gates uit in productie. De preview voegt geen productiecapability toe die het klassieke RSA/ECDSA PKCS#11-pad niet heeft.
Bevestig vóór elke evaluatie met echte hardware de mechanism- en parameter-set-ids van de token-firmware tegen de voorlopige waarden. Een mismatch faalt op de PKCS#11-laag, niet binnen NextPDF.
Behandel PqsCapabilityStatus::current() als de enige bron van waarheid bij het tonen van PQS-status in tooling of UI. Herhaal de booleans niet handmatig.
summary()-output is veilig voor logs en status-endpoints; ze is zo geformuleerd dat ze geen beschikbaarheids- of validatieclaim draagt.

Zie ook

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-klassen, mechanism-tabellen, runbook-bestandsnamen en ticket-prefixen vallen buiten de scope.