Firma con respaldo de HSM

Spec PKCS#11 v3.1 Spec Spec: ISO 32000-2, §12.8 ISO 32000-2 §12.8 Spec Spec: FIPS 140-3 FIPS 140-3 Evidence § Standard-backed Evidence: Standard-backed

De un vistazo

Un módulo de seguridad de hardware (HSM) saca la clave de firma del proceso y la coloca detrás de un dispositivo que firma cuando se le solicita, pero que nunca devuelve la clave. Esta página explica el punto de unión PKCS#11 a través del cual firma NextPDF, dónde se sitúa exactamente la frontera de la clave y qué partes del resultado son responsabilidad del motor, y no del dispositivo ni del operador.

Por qué esto importa

Una clave de firma en la memoria del proceso puede ser leída por cualquier actor o componente capaz de leer ese proceso: un volcado de memoria, un depurador, un error de registro o una dependencia con una vulnerabilidad. Una vez copiada una clave privada, quedan en entredicho todas las firmas que haya producido, y la filtración no se puede deshacer. El sentido de un HSM es que no exista ninguna copia que extraer.

Equivocarse con la frontera tiene un costo silencioso. Un flujo que parece respaldado por hardware pero que carga la clave en memoria para firmar tiene el costo operativo de un HSM y el perfil de riesgo de una clave de software. La distinción no es visible en el PDF terminado, así que debe diseñarse y verificarse, no darse por supuesta.

La versión breve

• El estándar PKCS#11 define un objeto de clave marcado como sensible y no extraíble. Su valor privado no puede revelarse en texto claro fuera del token. Spec Spec: PKCS#11, v3.1 §10.9 PKCS#11 v3.1 §10.9
• NextPDF construye la estructura de firma del PDF y el contenedor CMS. Entrega los bytes que se van a firmar a través del punto de unión PKCS#11 y recibe de vuelta la firma. La clave nunca cruza ese punto de unión.
• El punto de unión es un contrato estable. Ese mismo contrato puede satisfacerlo un token de tarjeta inteligente, un HSM USB, un HSM de red y un KMS en la nube. El código del motor no cambia entre ellos.
• NextPDF es software de motor de firma. La garantía de hardware del dispositivo, su estado de validación, la política de PIN y el despliegue no son aspectos que el motor certifique. El motor usa el dispositivo; no responde por él.

Cómo lo aborda NextPDF

El punto de unión, con precisión

NextPDF separa ensamblar una firma de calcular el valor de la firma. El ensamblaje corresponde al motor: colocar el campo de firma, reservar espacio en el archivo, calcular el rango de bytes y construir el CMS SignedData con sus atributos firmados. Spec Spec: ISO 32000-2, §12.8 ISO 32000-2 §12.8

El cálculo del valor de la firma se delega. El motor define un contrato reducido de proveedor de firma: recibe una cadena de bytes opaca (en la práctica, los atributos firmados codificados en DER) y devuelve los octetos de firma en bruto. Ese contrato es el punto de unión. A un lado está el conocimiento de PDF y CMS; al otro, una clave. Un proveedor puede mantener esa clave en el proceso para una clave de software local, en un KMS en la nube o en un token de hardware a través de PKCS#11. El código del motor por encima del punto de unión es idéntico en todos los casos. Solo difiere el proveedor que hay detrás.

Dónde se sitúa realmente la frontera

PKCS#11 —la interfaz de token criptográfico de OASIS, históricamente «Cryptoki»— es la interfaz C estándar para tokens de hardware. La ruta de hardware de NextPDF habla PKCS#11 (directamente o mediante un puente de línea de comandos de OpenSSL para despliegues de engine o provider en los que el enlace en proceso no puede cargar un token).

El objeto de clave en el token se crea con dos atributos que definen la frontera. Cuando la clave se marca como sensible o como no extraíble, ciertos atributos privados no pueden revelarse en texto claro fuera del token. Spec Spec: PKCS#11, v3.1 §10.9 PKCS#11 v3.1 §10.9 La operación de firma en sí se ejecuta en el dispositivo —C_SignInit y luego C_Sign—. Spec Spec: PKCS#11, v3.1 §5.10 PKCS#11 v3.1 §5.10 Lo que entra en NextPDF en texto claro son los bytes que se van a firmar. Lo que regresa es la firma y el certificado. La clave privada no está en ninguna de las dos rutas. Esa es la frontera, y la impone el token, no la biblioteca.

1. Step 1 of 4: ISO 32000-2 §12.8 — signature dictionary, ByteRange, Contents ISO 32000-2 §12.8 — signature dictionary, ByteRange, Contents
2. Step 2 of 4: RFC 5652 CMS SignedData — the signature container RFC 5652 CMS SignedData — the signature container
3. PKCS#11 v3.1 — token interface; sensitive, non-extractable key
4. Step 4 of 4: FIPS 140-3 / ISO/IEC 19790 cryptographic module assurance (device-level, deployment-dependent) FIPS 140-3 / ISO/IEC 19790 cryptographic module assurance (device-level, deployment-dependent)

Dónde se fundamenta una firma de PDF respaldada por hardware, en orden: el portador PDF (ISO 32000-2 §12.8), el contenedor CMS que contiene, la interfaz de token a través de la cual firma NextPDF (PKCS#11) y los estándares de garantía de módulo que describen —pero no garantizan por sí mismos— el dispositivo que hay detrás.

Un PIN, una reautenticación

PKCS#11 permite que una clave exija reautenticación en cada uso: cuando el atributo CKA_ALWAYS_AUTHENTICATE está activado, el usuario debe presentar el PIN de nuevo en cada operación criptográfica, no una vez por sesión. Spec Spec: PKCS#11, v3.1 §10.9 PKCS#11 v3.1 §10.9 La ruta PKCS#11 de NextPDF está preparada para esto. El PIN es un parámetro sensible. No se registra ni se serializa. Cuando una sesión informa de un inicio de sesión existente, NextPDF la restablece a un estado limpio para que la siguiente firma solicite una nueva comprobación de PIN. Esto importa para los tokens de tipo PIV cuya política exige un PIN por firma. Es un comportamiento del motor que respeta la política del dispositivo; no la relaja.

Qué dice la evidencia

Evidence § Standard-backed Evidence: Standard-backed La propiedad de clave no extraíble no es una afirmación de NextPDF. Es el modelo de PKCS#11: un objeto de clave cuyo CKA_SENSITIVE es verdadero o CKA_EXTRACTABLE es falso no entrega su valor privado en texto claro fuera del token. Spec Spec: PKCS#11, v3.1 §10.9 PKCS#11 v3.1 §10.9 La contribución de NextPDF es no necesitar nunca ese valor: firma a través de la operación C_Sign del token en lugar de solicitar material de clave.

Evidence § Standard-backed Evidence: Standard-backed El lado del PDF está anclado en Spec Spec: ISO 32000-2, §12.8 ISO 32000-2 §12.8 . El resumen criptográfico del rango de bytes se calcula sobre el archivo excluyendo el valor de la firma. El valor de la firma colocado en la entrada Contents es un objeto CMS SignedData codificado en DER para firmas de clave pública. El HSM produce solo los octetos de firma más internos. NextPDF construye todo lo demás a su alrededor y los escribe en la estructura que define el estándar.

Evidence § Standard-backed Evidence: Standard-backed La garantía del dispositivo se describe mediante Spec Spec: FIPS 140-3 FIPS 140-3 y su estándar base ISO/IEC 19790, que definen cuatro niveles de seguridad cualitativos crecientes a lo largo de once áreas de requisitos —desde la especificación de algoritmos hasta la evidencia física de manipulación—. Estos estándares describen los requisitos que un módulo debe cumplir para declarar un nivel. Son una propiedad del dispositivo y de su validación, no de NextPDF y, según el propio ISO/IEC 19790, la conformidad no es por sí sola suficiente para garantizar que un módulo sea seguro en un despliegue dado.

Human-factors note: Human-factors note

Esta página enuncia deliberadamente la frontera antes que el mecanismo, y sitúa el costo de equivocarse cerca del principio. En un dominio crítico para la seguridad, el orden honesto coloca primero la advertencia y después el cómo. Un flujo que carga silenciosamente una clave en memoria falla de un modo que no se ve en la salida, así que el peligro se nombra antes que la receta. La fila de distintivos ya indica que la página está respaldada por estándares antes de leer una sola frase del texto.

Ejemplo práctico

El patrón que se muestra a continuación es ilustrativo. Muestra el punto de unión, no un despliegue listo para copiar y pegar. Lo importante es que al motor se le entrega un firmante y nunca ve una clave: el sign() del firmante es una llamada al dispositivo.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Sign a PDF where the private key lives on a PKCS#11 token.
 *
 * `$hsm` is a hardware-backed signer. Its sign() delegates to the token;
 * the key never enters this process. Everything that makes the bytes a
 * valid PDF signature — field, byte range, CMS SignedData — is built by
 * the engine around the value the device returns.
 *
 * Token wiring (library path, slot, PIN, key label) is deployment
 * configuration and is intentionally out of scope here: those values are
 * operator-owned secrets, not library inputs to hardcode.
 */
function signWithToken(
    string $pdfPath,
    HsmSignerInterface $hsm,
): string {
    // The engine asks the signer only for: the certificate (to embed in
    // the CMS) and a signature over the bytes it computes. It never asks
    // for, and the contract never exposes, the private key.
    $certificateDer = $hsm->getCertificateDer();
    $chainDer       = $hsm->getCertificateChainDer();

    // Pseudocode for the engine's own assembly step: build the signature
    // dictionary + CMS SignedData, then hand the signed-attributes bytes
    // to $hsm->sign(...) and place the returned octets in /Contents.
    return nextpdf_sign_pdf(
        pdfPath: $pdfPath,
        signer: $hsm,
        certificateDer: $certificateDer,
        chainDer: $chainDer,
    );
}

Dos notas claras sobre este patrón. El enlace PKCS#11 en proceso es una extensión de PHP independiente que las compilaciones estándar de PHP no incluyen. Un despliegue de hardware la instala y verifica (o usa el puente de línea de comandos de OpenSSL) como parte de la plataforma, no como un añadido de última hora. Y el algoritmo que se le pide al dispositivo debe ser uno que la clave pueda realizar realmente. El motor rechaza de forma temprana cuando el algoritmo configurado no tiene correspondencia para el proveedor elegido, en lugar de fallar dentro de una llamada al token.

Idea errónea habitual

«Usar un HSM significa que la firma está validada por FIPS.»

No es así, y confundir ambas cosas es la trampa. Un HSM es el lugar donde reside la clave y donde se ejecuta la operación. La validación FIPS 140-3 / ISO/IEC 19790 es una propiedad que el dispositivo (o una configuración de módulo concreta) puede poseer, establecida por un programa de validación; no es algo que confiera una biblioteca que llama ni algo que NextPDF afirme en nombre de un dispositivo. NextPDF es compatible con la firma a través de un dispositivo PKCS#11 y su ruta de firma se ha probado con tokens representativos de cada categoría. Que un despliegue dado esté validado a nivel de módulo FIPS depende por completo del hardware, de su certificado y de cómo se configura y opera. Conviene usar la palabra precisa para lo que realmente se tiene.

Límites y fronteras

Esta página describe el punto de unión y los estándares en los que se apoya. No es una garantía de despliegue, y la línea merece enunciarse con claridad:

• Responsabilidad del motor. Construir el campo de firma, reservar espacio, calcular el rango de bytes, ensamblar el CMS SignedData, llamar al proveedor de firma y escribir una firma estructuralmente correcta según Spec Spec: ISO 32000-2, §12.8 ISO 32000-2 §12.8 . La ruta de hardware de NextPDF es conforme a la interfaz de firma PKCS#11 para este propósito.
• Responsabilidad del dispositivo y del operador. La resistencia a la manipulación del hardware, su estado de validación FIPS 140-3 / ISO/IEC 19790, la generación y custodia de claves, la política de PIN, la configuración de ranuras, el firmware y la seguridad física. Nada de esto lo certifica el motor.
• «Probado con» no es «certificado». Que NextPDF tenga una ruta verificada frente a categorías representativas de tokens —tarjeta inteligente, USB, red y formas de KMS en la nube alcanzadas a través del mismo contrato PKCS#11— es una declaración de compatibilidad. No es una certificación, ni un recuento de módulos validados, ni una afirmación sobre un dispositivo concreto. Las categorías de hardware que figuran a continuación son formas de integración a través de una interfaz estándar. Deben considerarse como «dónde se ha ejercitado el punto de unión», nunca como una garantía para un modelo que no se haya probado directamente.
• La firma poscuántica es experimental. Cuando el motor expone la firma poscuántica a través de un token, esta es opcional, está restringida y se valida frente a simulaciones en lugar de firmware HSM poscuántico. Los catálogos de suites criptográficas PAdES y AdES todavía no reconocen esas suites para el archivado a largo plazo. No debe considerarse lista para producción.

HSM-backed signing via PKCS#11 — edition availability

Edition	Availability
Core	○ No en esta edición. Core proporciona el motor de firma y el punto de unión del proveedor de firma, con un proveedor de clave de software local.
Pro	○ La gestión de claves en la nube —firmar mediante claves de KMS gestionadas— es una capacidad de Pro, descrita únicamente a nivel de comportamiento.
Enterprise	○ Disponible. La firma con token de hardware a través de la interfaz PKCS#11 (y un puente de línea de comandos de OpenSSL para despliegues de engine/provider) es una capacidad de Enterprise. La disponibilidad es una declaración de capacidad, no una certificación de ningún dispositivo ni despliegue.

Formas de integración a través de una interfaz

Estas son formas con las que se ha ejercitado el punto de unión PKCS#11. La tabla describe «qué aspecto tiene la integración», no «una lista de dispositivos validada, certificada o contabilizada».

Forma de integración	Cómo se alcanza	Frontera de la clave	La garantía es una propiedad de
Tarjeta inteligente / token PIV	Módulo PKCS#11; normalmente, PIN por uso	En la tarjeta; no extraíble	La tarjeta y su operador
HSM USB	Módulo PKCS#11	En el dispositivo; no extraíble	El dispositivo y su operador
HSM de red / appliance	Módulo PKCS#11 hacia un dispositivo de red	En el appliance; no extraíble	El appliance, su configuración y el operador
KMS en la nube	Proveedor de claves gestionadas (Pro)	En el servicio en la nube; nunca se devuelve	El proveedor en la nube y sus atestaciones
Puente de proveedor OpenSSL	PKCS#11 mediante un puente de OpenSSL	En el token; no extraíble	El token y su operador

Mini-FAQ

¿Entra alguna vez la clave en el proceso de PHP? No. Para una clave PKCS#11 no extraíble, el valor privado no puede revelarse en texto claro fuera del token. NextPDF firma a través de la operación del token y solo ve los bytes que hay que firmar y la firma devuelta.

¿Es distinta una firma respaldada por HSM dentro del PDF? No. La estructura de la firma es el mismo CMS SignedData en la misma entrada Contents sobre el mismo rango de bytes. El HSM cambia dónde ocurre la firma, no la forma en disco.

¿Puedo reclamar conformidad con FIPS por haber usado un HSM a través de NextPDF? Solo con prudencia. NextPDF no afirma nada sobre el estado FIPS de un dispositivo. Cualquier reclamación de ese tipo debe provenir de la propia validación del dispositivo y de cómo se despliega, no del hecho de que NextPDF lo haya llamado.

¿Y si el enlace PKCS#11 en proceso no está disponible? El motor informa de que la firma por hardware no está disponible en lugar de recurrir silenciosamente a una clave de software. Existe una ruta de puente de línea de comandos de OpenSSL para los despliegues en los que el enlace en proceso no puede cargar un token.

Documentos relacionados

• Firmas cualificadas, explicadas — por qué una clave de hardware es necesaria pero no suficiente, y los roles que NextPDF no cumple.
• Cómo se ubican las firmas en un PDF — el mecanismo de rango de bytes y diccionario de firma donde se escribe el resultado del HSM.
• Operar NextPDF en producción — la superficie operativa que asume un despliegue de firma por hardware.

Glosario

• HSM (módulo de seguridad de hardware) — un dispositivo reforzado que almacena las claves y realiza operaciones criptográficas de modo que el material de clave nunca lo abandona.
• PKCS#11 — el estándar de interfaz de token criptográfico de OASIS (históricamente «Cryptoki»); la interfaz C que usa NextPDF para comunicarse con los tokens de hardware.
• Clave no extraíble — un objeto de clave PKCS#11 cuyo valor privado no puede revelarse en texto claro fuera del token (CKA_SENSITIVE verdadero o CKA_EXTRACTABLE falso).
• El punto de unión — la frontera del proveedor de firma en NextPDF: bytes opacos de entrada, octetos de firma de salida. El conocimiento de PDF y CMS se sitúa por encima; la clave se sitúa detrás.
• CMS SignedData — la estructura de la sintaxis de mensajes criptográficos (RFC 5652) que transporta la firma y los certificados dentro del PDF.
• FIPS 140-3 / ISO/IEC 19790 — estándares de seguridad de módulos criptográficos que definen cuatro niveles cualitativos; una propiedad de un dispositivo y su validación, no de una biblioteca que llama.