Estado de capacidad de vista previa de la firma poscuántica con HSM (PQS)

De un vistazo

Estado de capacidad de vista previa. Opcional, desactivada por defecto, de cierre seguro. Esta es una vista previa de la firma poscuántica delegada en HSM. No está disponible con carácter general, no es compatible con AdES, no está validada según FIPS y no hace ninguna reclamación de certificación ni de conformidad. La vista previa está desactivada hasta que usted opte; cuando está desactivada, la llamada de firma se cierra de forma segura con una excepción tipada.

NextPDF Enterprise expone una superficie experimental de firma poscuántica (PQS) que impulsa la firma ML-DSA (FIPS 204) y SLH-DSA (FIPS 205) a través de un token de hardware PKCS#11. La ruta es Pkcs11Signer::signPqs(), restringida detrás de una opción explícita por firmante ($enablePostQuantum) y, por separado, detrás de un indicador de entorno a nivel de proceso (NEXTPDF_FEATURE_PREVIEW_PQS_HSM). Ambos están desactivados por defecto.

Esta página es el límite honesto. Expone lo que la vista previa hace —delega una operación de firma poscuántica real en el token— y, con igual honestidad, lo que no es: no es GA, no es AdES, no está validada según FIPS y no es una reclamación de conformidad frente a FIPS, OASIS o ETSI. Las normas que harían interoperable una firma PDF poscuántica para el archivado a largo plazo aún no han llegado (consulte Límite de las normas).

Disponibilidad y licencias

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

Se basa en el firmante de token de hardware PKCS#11 de Enterprise —consulte Firma con HSM. La ruta de firma PKCS#11 clásica (RSA / ECDSA) es la capacidad de Enterprise admitida y estable; la ruta poscuántica descrita aquí es una vista previa experimental superpuesta sobre ella. NextPDF Enterprise incluye el conjunto de características de Pro.

Estado de capacidad de vista previa

La vista previa impulsa una operación de firma genuina: cuando está habilitada, signPqs() despacha al mecanismo poscuántico candidato de PKCS#11 v3.1 en el token, la clave privada nunca abandona el límite del token, y los bytes devueltos se verifican en longitud frente a la longitud de firma exigida por FIPS para el conjunto de parámetros elegido antes de aceptarse.

Al mismo tiempo, es una vista previa y no una capacidad de producto disponible con carácter general:

• El mecanismo poscuántico de PKCS#11 y los identificadores de conjunto de parámetros son provisionales: OASIS PKCS#11 v3.1 no ha finalizado un registro de mecanismos poscuánticos, por lo que los valores usados se siguen como provisionales y los operadores de HSM deben confirmar que el firmware PQ de su token coincide con ellos antes de habilitar.
• No existe ninguna ruta de verificación poscuántica en NextPDF, y ninguna suite de ETSI registra una firma poscuántica para el archivado a largo plazo de AdES, por lo que una firma producida aquí aún no es interoperable y la mayoría de los visores de PDF la rechazarán en el momento de la validación.
• Un descriptor complementario, PqsCapabilityStatus, informa de estos hechos en forma legible por máquina. Cada booleano de reclamación positiva — generallyAvailable, adesCompliant, verificationAvailable, conformanceClaimed— está codificado de forma fija como false y permanece en false incluso cuando el indicador de vista previa está activado, y ninguna configuración puede activar uno. (También lleva un indicador recognitionOnly, codificado de forma fija como true, que registra que el reconocimiento de un algoritmo nunca es un veredicto de conformidad; no significa que la superficie no pueda firmar: la firma ocurre a través de signPqs() como se describe arriba.)

Por qué funciona así

NextPDF ya puede calcular una firma ML-DSA o SLH-DSA real a través del token. Aun así, cada booleano de conformidad permanece codificado de forma fija como false, detrás de dos compuertas desactivadas por defecto. Una firma solo vale por la capacidad de verificarla más tarde. Para la poscuántica no hay ninguna ruta de verificación, ninguna suite AdES de ETSI registrada y ningún ciclo completo de HSM validado según FIPS todavía. Enviar esto como disponible con carácter general emitiría firmas que ningún visor puede validar y ningún archivo puede confiar. Por eso el diseño separa la producción de los bytes de la reclamación de que alguien pueda confiar en ellos, y ningún indicador de vista previa puede difuminar esa línea.

Contexto de diseño: Validación a largo plazo.

Conjuntos de parámetros de algoritmo

signPqs() selecciona el algoritmo y el conjunto de parámetros a través de la enumeración Pkcs11PqsAlgorithm. Cada caso asigna un conjunto de parámetros de NIST a un identificador provisional de mecanismo / conjunto de parámetros de PKCS#11 y a la longitud de firma en bytes exigida por FIPS que se usa para la verificación de longitud de defensa en profundidad.

ML-DSA — FIPS 204 (basado en retículos de módulo). Tres conjuntos de parámetros, reclamados en las categorías de fortaleza de seguridad de NIST mostradas:

Conjunto de parámetros	Categoría NIST	Longitud de firma (bytes)
ML-DSA-44	2	2420
ML-DSA-65 (predeterminado recomendado)	3	3309
ML-DSA-87	5	4627

SLH-DSA — FIPS 205 (basado en hash sin estado). Doce conjuntos de parámetros, formados como SHA2 / SHAKE x 128 / 192 / 256 x pequeño (s) / rápido (f). Las variantes s minimizan el tamaño de la firma; las variantes f minimizan la latencia de firma:

Familia de conjunto de parámetros	Categoría NIST	Longitud de firma (bytes)
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

Habilitar la vista previa

Dos compuertas independientes deben estar ambas abiertas. Ambas están desactivadas por defecto.

1. Compuerta de proceso. Establezca NEXTPDF_FEATURE_PREVIEW_PQS_HSM=1 antes de que el proceso arranque (o mediante putenv() antes de leer el estado). Se requiere igualdad estricta con la cadena 1; cualquier otro valor —incluido 0, true, yes o vacío— se trata como desactivado.
2. Opción por firmante. Pase $enablePostQuantum: true al constructor de 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() informa de si se estableció la opción por firmante, y PqsCapabilityStatus::current() informa del estado a nivel de proceso más los booleanos de reclamación honestos.

Límite de cierre seguro

La superficie es de cierre seguro e informa de los fallos a través de excepciones con nombre y tipadas en lugar de un repliegue silencioso:

• Opción ausente. Si se llama a signPqs() cuando $enablePostQuantum es false, lanza HsmOperationException. No se produce ninguna firma.
• Contexto demasiado largo. Una cadena de octetos de contexto de firma de más de 255 bytes lanza InvalidArgumentException (según el límite de contexto de FIPS 204 / FIPS 205) antes de cualquier llamada al token.
• Clave ausente. Si ninguna clave privada coincide con la etiqueta configurada en el token, signPqs() lanza HsmOperationException.
• Desajuste de longitud. Si el token devuelve una firma cuya longitud en bytes no es igual a la longitud exigida por FIPS para el conjunto de parámetros, signPqs() lanza HsmOperationException: una firma mal formada (truncada o sobredimensionada) se rechaza antes de poder llegar a la codificación CMS SignedData.
• Error del token. Cualquier error subyacente de PKCS#11 se envuelve en HsmOperationException.

El indicador de entorno a nivel de proceso no cambia nada de este límite: incluso cuando el indicador está activado, los booleanos de capacidad permanecen en false y la ruta de firma permanece verificada en longitud y de cierre seguro.

Límite honesto

Las siguientes reclamaciones no se hacen para esta superficie y no deben aparecer en ninguna documentación, interfaz de usuario o marketing derivado de ella:

• “GA” / “disponible con carácter general”.
• “AdES” / “compatible con PAdES”: ninguna suite de ETSI registra una firma poscuántica para el archivado a largo plazo.
• “Validado según FIPS”: no se ha establecido ningún ciclo completo de HSM poscuántico validado según FIPS 140-3 para esta ruta.
• “Certificado” o “conforme” frente a FIPS, OASIS PKCS#11 v3.1 o ETSI.
• “Listo para producción”.

Lo que la superficie honestamente es: una vista previa opcional, desactivada por defecto y de cierre seguro de la firma poscuántica delegada en HSM que impulsa ML-DSA / SLH-DSA a través de un token PKCS#11 y verifica la longitud del resultado. Lo que no es: una capacidad de firma disponible con carácter general, compatible con AdES, validada según FIPS o certificada.

Límite de las normas

Las normas implicadas las mantienen organismos externos, y la vista previa no toma ninguna posición sobre la conformidad con ninguna de ellas:

• Los conjuntos de parámetros de algoritmo y las longitudes de firma siguen FIPS 204 (ML-DSA) y FIPS 205 (SLH-DSA).
• Los identificadores de mecanismo del token siguen OASIS PKCS#11; el registro de mecanismos poscuánticos en PKCS#11 v3.1 aún no está finalizado, por lo que NextPDF usa identificadores provisionales.
• Los perfiles de archivado a largo plazo de firma PDF son ETSI EN 319 142-2 (perfiles extendidos de PAdES, construidos sobre CMS SignerInfo) y el catálogo de suites criptográficas ETSI TS 119 312, que actualmente solo perfilan RSA y ECDSA: ninguna suite poscuántica está registrada para CAdES/PAdES. Una firma PDF poscuántica producida hoy, por lo tanto, aún no es compatible con AdES para el archivado.

En esta página no se reproduce ningún texto de las normas.

Notas de seguridad

Una vista previa no es un control de seguridad. La presencia de una firma poscuántica producida por esta ruta no establece validez AdES, no implica una clave de confianza y NextPDF no puede verificarla (no hay ninguna ruta de verificación poscuántica). No confíe en esta vista previa para la garantía de firma, y no la despliegue donde se requiera una firma compatible con AdES o validada según FIPS. Mantenga ambas compuertas desactivadas en producción hasta que las normas lleguen.

Superficie de la API

Símbolo	Función
Pkcs11Signer::signPqs()	Firma poscuántica opcional, de cierre seguro y delegada en HSM a través de PKCS#11. Lanza HsmOperationException cuando está deshabilitada, cuando la clave está ausente o ante un desajuste de longitud de firma.
Pkcs11Signer::isPostQuantumEnabled()	Si se estableció la opción por firmante $enablePostQuantum.
Pkcs11PqsAlgorithm	Enumeración de los conjuntos de parámetros de ML-DSA (FIPS 204) y SLH-DSA (FIPS 205); asigna cada uno a un id de mecanismo provisional y a la longitud de firma exigida por FIPS.
PqsPreviewFeature	Compuerta de entorno a nivel de proceso, desactivada por defecto (NEXTPDF_FEATURE_PREVIEW_PQS_HSM).
PqsCapabilityStatus	Estado honesto y legible por máquina: cada booleano de reclamación positiva (disponible con carácter general, AdES, verificación, conformidad) está codificado de forma fija como false independientemente del indicador de vista previa.
HsmOperationException	La excepción tipada que se lanza en las rutas de cierre seguro.

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 internos, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de manuales de operación y los prefijos de tickets quedan fuera del alcance.

Consulte también

• Firma con HSM (PKCS#11)
• Seguridad de Enterprise
• Firma de Core
• Página de conformidad
• Estado de capacidad de vista previa de C2PA