Aplicar una firma digital PAdES en NextPDF Connect (Pro)

De un vistazo

Aplicar una firma digital de línea base PAdES a un PDF en NextPDF Connect. La herramienta es sign_pdf, verificada de nuevo contra el proveedor de herramientas Pro: ese proveedor registra new SignPdfTool(), cuyo nombre de protocolo es sign_pdf. sign_pdf es una herramienta de nivel Pro. El servidor la comprueba con class_exists() durante el arranque y solo la registra cuando el paquete Pro está instalado.

De forma predeterminada, la herramienta produce PAdES B-B. Puede producir PAdES B-T (B-B más una RFC 3161 signature-time-stamp) solo cuando el host ha configurado un proveedor de marca de tiempo en la herramienta; la solicitud no puede apuntar a una TSA. Los niveles de largo plazo (B-LT, B-LTA) y su material de validación (DSS, VRI, LTV) no forman parte de esta herramienta y quedan fuera del alcance de esta página.

Advertencia U-1. NextPDF no declara ninguna certificación independiente conforme a ETSI EN 319 142-1 para PAdES B-T. EN 319 142-1 no está en el corpus de verificación. El requisito de signature-time-stamp de B-T se verifica frente a ETSI EN 319 122-1 §5.3 (la base CAdES que EN 319 142-1/-2 incorporan por referencia), junto con RFC 3161, RFC 5652, RFC 5816 e ISO 32000-2 §12.8. La compatibilidad con el perfil B-T no es una certificación de conformidad ni de validez legal; esa determinación corresponde a un validador independiente.

Instalación

composer require nextpdf/server
composer require nextpdf/pro

Vincular un transporte. Confirmar que sign_pdf existe con diagnostic.capabilities. Para B-T, el host debe construir la herramienta con un proveedor de marca de tiempo. Sin él, una solicitud pades_b_t: true falla con un error tipado en lugar de degradarse silenciosamente.

Visión conceptual

sign_pdf calcula un resumen de rango de bytes del archivo, excluyendo el marcador de posición del valor de la firma (ISO 32000-2 §12.8.1). A continuación, escribe el CMS SignedData codificado en DER en el diccionario de firma Contents (ISO 32000-2 §12.8.1). Algoritmos compatibles: RSA-SHA256 (predeterminado), RSA + SHA-3 (256/384/512) y Ed25519. Una envoltura AES-GCM opcional puede encapsular la carga private_key entrante en transportes que no sean confidenciales de extremo a extremo.

Actualización a B-T. Con pades_b_t: true y un proveedor de marca de tiempo configurado por el host, la firma se actualiza a PAdES B-T: el hash de rango de bytes se envía a una TSA y se incrusta un TimeStampToken (ISO 32000-2 §12.8.5). B-T consiste exactamente en B-B más una RFC 3161 signature-time-stamp transportada como atributo no firmado en el CMS SignerInfo (RFC 5652 §5.3). Los atributos no firmados no están cubiertos por la firma, por lo que el resumen firmado de B-B y su validez no cambian (RFC 5652 §5.3). El valor del atributo es un SignatureTimeStampToken (ETSI EN 319 122-1 §5.3). B-T no añade ningún diccionario DSS, ningún VRI, ningún material de validación ni ningún bucle de archive-timestamp: eso corresponde al delta Enterprise B-LT/B-LTA y queda fuera del alcance de esta herramienta.

Advertencia U-1 (repetida en la afirmación B-T). La compatibilidad con B-T aquí no es una certificación de conformidad con EN 319 142-1 ni de validez legal; lo determina un validador independiente. EN 319 142-1 no está en el corpus de verificación. B-T se fundamenta en ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, RFC 5816 e ISO 32000-2 §12.8.

El flujo de la herramienta —incluidos el punto de integración TSA controlado por el host (la solicitud no puede apuntar a una TSA) y la rama fail-closed de B-T (nunca una degradación silenciosa)— se muestra a continuación.

Diagram

Superficie de la API

Herramienta	Nivel	Rol	Nivel de riesgo
`create_pdf`, `add_text`	Núcleo	Crear contenido	Seguro / Precaución
`sign_pdf`	Pro	Aplicar PAdES B-B (o B-T controlado por el host)	Aprobación requerida
`output_pdf`	Núcleo	Renderizar y devolver el PDF	Aprobación requerida / Revisión (base64)

Los nombres de las herramientas son los nombres de protocolo del registro; el catálogo de herramientas es la referencia. Las herramientas disponibles dependen del nivel instalado, y las herramientas para niveles de largo plazo no están presentes en Pro.

Ejemplo de código — Inicio rápido

create_pdf → crear contenido con add_text.
sign_pdf con certificate (PEM), private_key (PKCS#8 PEM), signer_name opcional, reason y algorithm. Omitir pades_b_t (o establecerlo en false) para B-B.
output_pdf.

La herramienta devuelve la siguiente envoltura de resultado:

{
  "pdf": "<base64 of the signed PDF>",
  "signature_count": 1,
  "is_complete": true,
  "algorithm": "RSA_SHA256",
  "oid": "<algorithm OID>",
  "digest": "<digest algorithm>",
  "level": "PAdES-B-B",
  "timestamped": false
}

Para una firma B-T controlada por el host, enviar pades_b_t: true; level pasa a ser "PAdES-B-T" y timestamped pasa a ser true.

Ejemplo de código — Producción

Firmar como última operación de contenido. Cualquier add_text/add_image después de sign_pdf invalida la firma. En un transporte no confidencial, envolver private_key en la envoltura AES-GCM transport_encryption (nonce de 12 bytes; clave de 16/24/32 bytes). Verificar que el level del resultado coincida con lo solicitado. Una solicitud pades_b_t: true contra una herramienta sin proveedor falla explícitamente: gestionar ese error y no reintentar como B-B de forma silenciosa.

Casos límite y trampas

Discrepancia de certificado/clave. Se rechaza con un error claro; la clave privada debe coincidir con la clave pública del certificado.
PEM mal formado / certificado caducado. Se rechaza; de forma predeterminada, la herramienta no firma con un certificado no analizable o caducado.
Contenido después de firmar. Se rechaza: firmar al final.
B-T solicitado, sin proveedor. Devuelve un error tipado: la firma no se produce y no se degrada silenciosamente a B-B.
Certificado autofirmado. La firma se aplica, pero los lectores muestran confianza desconocida: eso es lo esperado, no un defecto de la herramienta.
Pro ausente. Con solo Core, sign_pdf no se registra.

Rendimiento

La firma añade la construcción CMS y, para B-T, una ida y vuelta a la TSA; el presupuesto lo contempla. El perfil es semantic: un token RFC 3161 es inherentemente no reproducible, y el resumen de rango de bytes de §12.8.1 excluye el valor de la firma, por lo que lo correcto es comparar solo el AST + metadatos de firma.

Notas de seguridad

Una firma proporciona integridad y autenticación vinculadas a la clave de firma. Por sí sola no convierte un documento en «seguro» ni «legalmente válido», ni proporciona una garantía de no repudio: eso depende del certificado, su ancla de confianza, la custodia de la clave y la política del verificador, todo ello fuera del alcance de esta herramienta. El cifrado de la carga de la clave (envoltura AES-GCM) protege la confidencialidad en tránsito, no la integridad. Tratar la clave privada como un secreto y preferir la envoltura de cifrado de transporte en cualquier canal no confidencial.

Conformidad

Declaración	Especificación	Cláusula
El resumen de rango de bytes cubre el archivo y excluye el valor de la firma.	ISO 32000-2	§12.8.1
`Contents` contiene el CMS SignedData codificado en DER.	ISO 32000-2	§12.8.1
Para una marca de tiempo, el hash de rango de bytes va a una TSA y el token se coloca en `Contents`.	ISO 32000-2	§12.8.5
La marca de tiempo de B-T es un atributo no firmado en SignerInfo.	RFC 5652	§5.3
Los atributos no firmados no cambian el resumen firmado de B-B ni su digest/validity.	RFC 5652	§5.3
El valor de signature-time-stamp es un SignatureTimeStampToken.	ETSI EN 319 122-1	§5.3

NextPDF produce la estructura de firma. No declara que ninguna firma resultante sea conforme ni legalmente válida: lo determina un validador independiente. Esta herramienta no produce B-LT/B-LTA.

Contexto comercial

sign_pdf es una herramienta de nivel Pro, registrada solo cuando el paquete Pro se resuelve al arrancar el servidor. Los niveles de largo plazo de PAdES (B-LT, B-LTA) y su material de validación (DSS, VRI, LTV) son exclusivos de Enterprise y no están expuestos ni en esta herramienta ni en esta receta.

Residencia de datos y mitigaciones de PII

El certificado y la clave privada se envían en la solicitud. Usar la envoltura AES-GCM transport_encryption en cualquier canal que no sea confidencial de extremo a extremo. El PDF firmado y la identidad del firmante (signer_name, reason) son contenido del documento, así que deben mantenerse dentro de su perímetro de residencia de datos. La residencia a nivel de despliegue es responsabilidad del integrador.

Telemetría segura y depuración de registros

Nunca registrar la carga private_key, la key/nonce AES-GCM ni el token de confirmación. Registrar el algoritmo, el level resultante y signature_count, no el material de claves. La herramienta no emite bytes de la clave en su resultado.

Modelo de amenazas

Amenazas consideradas: divulgación de la clave en tránsito (mitigada por la envoltura AES-GCM y por el proveedor TSA inyectado por el host y no configurable por la solicitud); un llamador MCP que dirige la marca de tiempo a un endpoint arbitrario (impedido: el proveedor es inyectado por el host, no configurable por la solicitud); y manipulación posterior a la firma (el resumen de rango de bytes detecta la modificación). Un modelo de amenazas documenta las amenazas consideradas y sus mitigaciones; no afirma que no existan vulnerabilidades.

Comportamiento en modo FIPS

La selección del algoritmo (RSA-SHA256, RSA + SHA-3, Ed25519) está dirigida por la solicitud; el OpenSSL del host proporciona las primitivas criptográficas. En un despliegue con restricciones FIPS, restringir el algoritmo en la capa de políticas y confiar en el módulo validado del host. Esta herramienta no declara por sí misma la validación FIPS.

Disponibilidad de transporte

Transporte	Disponible	Notas
MCP (stdio)	Sí (Pro)	Usar la envoltura de clave AES-GCM en stdio.
REST	Sí (Pro)	Preferir TLS más la envoltura de clave.
gRPC	Sí (Pro)	Preferir TLS más la envoltura de clave.

Nivel de riesgo HITL

sign_pdf es Aprobación requerida (una operación destructiva e irreversible: la herramienta anuncia un indicador de operación destructiva). La puerta de confirmación se aplica igual que para cualquier herramienta de Aprobación requerida. output_pdf a un archivo también es Aprobación requerida; el modo base64 es Revisión (niveles de riesgo HITL).

Envoltura JSON de la puerta de confirmación

sign_pdf sin un token válido devuelve la envoltura de desafío:

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: sign_pdf\nDescription: <tool description>\n\nTo proceed, call sign_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

Volver a llamar con _confirmation_token establecido en el token → { "allowed": true }. Flujo completo: output-approval.