Enterprise ediciónestabilidad: Experimental

Vista previa de firma poscuántica — Referencia detallada

De un vistazo

Esta página es la referencia a nivel de contrato de la superficie de vista previa de firma poscuántica (PQS) en NextPDF Enterprise. Cubre tres símbolos públicos: el enum de conjuntos de parámetros Pkcs11PqsAlgorithm, la puerta de proceso PqsPreviewFeature y el descriptor PqsCapabilityStatus. También documenta la puerta de entorno NEXTPDF_FEATURE_PREVIEW_PQS_HSM.

La superficie es experimental y está desactivada de forma predeterminada. Reconoce los identificadores de algoritmo, los conjuntos de parámetros y las longitudes de firma de ML-DSA (FIPS 204) y SLH-DSA (FIPS 205). El reconocimiento no es un veredicto de validación. No existe ninguna ruta de verificación poscuántica. No se hace ninguna afirmación de AdES, validación FIPS ni conformidad, y el indicador de vista previa no puede crear ninguna. El punto de entrada de firma consumidor, Pkcs11Signer::signPqs(), se describe en la página de capacidad.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin esa habilitación no carga las clases de la capacidad. Compare las ediciones y obtenga una licencia.

La licencia activa la superficie PKCS#11 de Enterprise en su conjunto. La ruta poscuántica dentro de ella sigue siendo una vista previa independientemente del nivel de licencia. Aún se requieren dos activaciones independientes: la puerta de proceso documentada aquí y el indicador de constructor por firmante en Pkcs11Signer.

Superficie de API pública

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`Pkcs11PqsAlgorithm`	enum respaldado por string, 15 casos	Nombra un conjunto de parámetros FIPS 204 / FIPS 205 por caso	caso de enum	Nada al acceder a un caso	Los valores de los casos son los nombres de los conjuntos de parámetros, p. ej. `ML-DSA-65`.
`Pkcs11PqsAlgorithm::isMlDsa()`	ninguno	Prueba de familia	`bool`	No lanza	`true` para `MlDsa44`, `MlDsa65`, `MlDsa87`.
`Pkcs11PqsAlgorithm::isSlhDsa()`	ninguno	Negación de `isMlDsa()`	`bool`	No lanza	`true` para los doce casos SLH-DSA.
`Pkcs11PqsAlgorithm::mechanismId()`	ninguno	Asigna la familia al id de mecanismo PQ candidato de PKCS#11 v3.1	`int`	`Error` de PHP cuando el entorno de ejecución carece de las constantes PQ provisionales de `Pkcs11`	`CKM_ML_DSA` o `CKM_SLH_DSA`; ambos ids son provisionales.
`Pkcs11PqsAlgorithm::parameterSetId()`	ninguno	Asigna el caso al discriminador de conjunto de parámetros de OASIS	`int`	`Error` de PHP cuando el entorno de ejecución carece de las constantes PQ provisionales de `Pkcs11`	valores `CKP_*`; provisionales.
`Pkcs11PqsAlgorithm::signatureLength()`	ninguno	Longitud de firma en bytes exigida por FIPS para el caso	`int` (positivo)	No lanza	Lo consume la ruta de firma para rechazar una firma devuelta de longitud inesperada.
`Pkcs11PqsAlgorithm::nistCategory()`	ninguno	Categoría de nivel de seguridad NIST reclamada	`int`	No lanza	Devuelve 1, 2, 3 o 5.
`PqsPreviewFeature`	enum respaldado por string, 1 caso	Único caso `PREVIEW_PQS_HSM`; constante `ENV_PREVIEW_PQS_HSM`	caso de enum	Nada al acceder a un caso	La puerta de vista previa a nivel de proceso.
`PqsPreviewFeature::isEnabled()`	ninguno	Lee `getenv()` en vivo; comparación estricta con la cadena `1`	`bool`	No lanza	Una variable ausente o cualquier otro valor, incluidos `0`, `true`, `yes`, está desactivado.
`PqsCapabilityStatus::__construct()`	nueve campos readonly con nombre	Construye una instancia de descriptor arbitraria	`PqsCapabilityStatus`	No lanza	`current()` es el constructor canónico.
`PqsCapabilityStatus::current()`	ninguno	Construye el descriptor del proceso circundante	`PqsCapabilityStatus`	No lanza	Cada booleano de afirmación es fijo; solo `hsmRoundtripPreviewEnabled` varía con la puerta.
`PqsCapabilityStatus::summary()`	ninguno	Texto de estado de una línea	`string`	No lanza	La redacción no conlleva ninguna afirmación de disponibilidad, archivado ni validación.

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

Contrato de comportamiento

Catálogo de conjuntos de parámetros. NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm enumera tres conjuntos ML-DSA (FIPS 204) y doce conjuntos SLH-DSA (FIPS 205 §11.p12, Table 2). Cada caso se asigna a un id de mecanismo provisional, un discriminador de conjunto de parámetros, una longitud de firma en bytes exigida por FIPS y una categoría NIST reclamada.
Longitudes de firma. signatureLength() devuelve 2420, 3309 y 4627 bytes para MlDsa44, MlDsa65 y MlDsa87, según FIPS 204 §4.p15 (Table 2). Los casos SLH-DSA devuelven 7856, 17088, 16224, 35664, 29792 y 49856 bytes por nivel y variante, según FIPS 205 §11 (Table 2). El firmante consumidor lanza HsmOperationException cuando una firma devuelta tiene una longitud distinta, reflejando la disciplina de rechazo por longitud de FIPS 204 §x34.
Categorías. nistCategory() devuelve 2, 3 y 5 para los casos ML-DSA, según FIPS 204 §4.p9. Los casos SLH-DSA devuelven 1, 3 y 5 según el nivel de parámetro de seguridad.
Puerta de proceso. PqsPreviewFeature::PREVIEW_PQS_HSM está desactivada de forma predeterminada. isEnabled() devuelve true solo cuando la variable de entorno NEXTPDF_FEATURE_PREVIEW_PQS_HSM es exactamente igual a la cadena 1. La lectura es en vivo en cada llamada; no se memoriza nada.
Control complementario. La puerta de proceso es independiente de la activación de constructor por firmante $enablePostQuantum en Pkcs11Signer. La llamada de firma falla de forma cerrada sin la activación por firmante. La puerta de proceso existe como un único límite auditable para cualquier comportamiento futuro de ida y vuelta o de archivado.
Invariante de honestidad. NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus::current() fija por código generallyAvailable, adesCompliant, verificationAvailable y conformanceClaimed en false, y recognitionOnly en true. Ninguna configuración, opción de constructor ni indicador de entorno activa una afirmación. Solo hsmRoundtripPreviewEnabled refleja la puerta.
Sin ruta de verificación. NextPDF no tiene ninguna ruta de verificación poscuántica. Un identificador de algoritmo reconocido o una longitud de firma bien formada nunca son un veredicto de aceptación.

Casos límite y modos de fallo

Establecer la variable de la puerta en 0, true, yes, on o una cadena vacía deja la puerta desactivada. Solo la cadena exacta 1 la activa.
Los cambios de putenv() surten efecto en la siguiente llamada a isEnabled() porque la lectura es en vivo. Una puerta conmutada a mitad de proceso se observa de inmediato.
mechanismId() y parameterSetId() resuelven constantes del espacio de nombres de la extensión Pkcs11. Un entorno de ejecución sin las constantes provisionales de extensión poscuántica falla con un Error de PHP (constante indefinida) en el momento de la llamada.
Los ids de mecanismo y de conjunto de parámetros son provisionales. OASIS no ha finalizado el registro poscuántico de PKCS#11 v3.1. Un token cuyo firmware asigne ids distintos fallará en la capa PKCS#11; los operadores deben confirmar los ids del firmware antes de activar la vista previa.
El contexto de firma aceptado por el firmante consumidor está acotado en 255 bytes, en concordancia con el contrato de entrada de firma de FIPS 204 (§x43.p2). Un contexto más largo lanza InvalidArgumentException antes de cualquier llamada al token.
PqsCapabilityStatus::__construct() es público, por lo que una instancia construida a mano puede llevar booleanos arbitrarios. Tal instancia es solo un objeto de valor. No altera ningún comportamiento de firma. current() es el constructor canónico y fijado por código.
La elección entre aleatorizado y determinista en el firmante consumidor sigue la semántica de FIPS 205 §x65.p7: la firma con cobertura (hedged) es la predeterminada. El indicador se ignora para ML-DSA, que siempre aleatoriza mediante su propio nonce.

Comportamiento en modo FIPS

ML-DSA y SLH-DSA son algoritmos de FIPS 204 y FIPS 205, pero esta vista previa no conlleva ninguna afirmación de validación FIPS 140-3. No se ha establecido ninguna ida y vuelta de HSM poscuántico validada por FIPS para esta ruta. El perfil de política criptográfica en modo FIPS de Enterprise, documentado en la referencia detallada de seguridad, controla los algoritmos de firma clásicos; no admite la superficie PQS en un conjunto validado. Activar el modo FIPS no hace que la firma poscuántica esté validada por FIPS. No despliegue la vista previa donde se requiera una firma validada por FIPS.

Conformidad

Afirmación	Estándar	Cláusula
ML-DSA-44/65/87 llevan las categorías NIST reclamadas 2, 3, 5.	FIPS 204	§4.p9
Los tamaños de firma ML-DSA son 2420, 3309, 4627 bytes.	FIPS 204	§4.p15 (Table 2)
La cadena de bytes del contexto de firma está acotada en 255 bytes.	FIPS 204	§x43.p2
Una firma o clave de longitud incorrecta debe rechazarse.	FIPS 204	§x34
Se aprueban doce conjuntos de parámetros SLH-DSA.	FIPS 205	§11.p12 (Table 2)
Los tamaños de firma SLH-DSA siguen Table 2 (7856 bytes para 128s).	FIPS 205	§11.p6
La firma con cobertura (hedged) es la predeterminada; existe una variante determinista.	FIPS 205	§x65.p7
El catálogo de suites CAdES/PAdES perfila solo RSA y EC-DSA.	ETSI TS 119 312 V1.5.1	§7.x7.p10 (Table A.1)
Los ids de mecanismo PQ de PKCS#11 son provisionales.	OASIS PKCS#11 v3.1	product-source grounded

Todas las cláusulas están parafraseadas. NextPDF no reproduce texto normativo. NextPDF no posee ninguna certificación ni la concede. Las afirmaciones anteriores son afirmaciones de alineación estructural sobre identificadores, longitudes y límites. No son resultados de pruebas de conformidad, ni atestaciones de terceros, ni una afirmación de conformidad de FIPS, OASIS o ETSI. PqsCapabilityStatus codifica esta postura en código: conformanceClaimed es false, adesCompliant es false y verificationAvailable es false en toda configuración. Una firma producida por esta vista previa no cumple con AdES para el archivado a largo plazo, y la mayoría de los visores de PDF la rechazan en el momento de la validación.

Notas de desarrollo

El registro de mecanismos poscuánticos de OASIS PKCS#11 no está finalizado; los ids CKM_ML_DSA / CKM_SLH_DSA y las constantes de conjunto de parámetros que se usan aquí son provisionales y están fundamentados en el código fuente del producto, no en una cita de especificación.
El hito actual es una preparación probada con simulaciones. Aún no se ha validado ninguna ida y vuelta de HSM con firmware poscuántico real.
Mantenga ambas puertas desactivadas en producción. La vista previa no añade ninguna capacidad de producción de la que carezca la ruta PKCS#11 clásica RSA/ECDSA.
Antes de cualquier evaluación con hardware real, confirme los ids de mecanismo y de conjunto de parámetros del firmware del token frente a los valores provisionales. Una discrepancia falla en la capa PKCS#11, no dentro de NextPDF.
Trate PqsCapabilityStatus::current() como la única fuente de verdad al exponer el estado de PQS en herramientas o UI. No reescriba sus booleanos a mano.
La salida de summary() es segura para registros y endpoints de estado; está redactada para no conllevar ninguna afirmación de disponibilidad ni validación.

Véase también

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de API pública admitida. Las rutas de espacios de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de tickets quedan fuera del alcance.