Configuración de la TSA

De un vistazo

NextPDF contacta con una autoridad de sellado de tiempo (TSA) solo cuando firmas en PAdES B-T o superior. En B-B no hay marca de tiempo ni llamada de red, de modo que esta página no se aplica a una firma B-B.

Para que B-T funcione sin configuración previa, NextPDF incluye una TSA predeterminada integrada. Ese valor predeterminado es una comodidad: permite que una firma con marca de tiempo se complete sin configuración adicional. No es de confianza pública y no está cualificada conforme a eIDAS, por lo que no es adecuada para uso en producción ni de cumplimiento sin una elección deliberada. Esta página explica exactamente qué es el valor predeterminado, cómo apuntar NextPDF a tu propia TSA, cómo desactivar el sellado de tiempo, y las dos rutas de mejora.

Tres propiedades son independientes y no deben confundirse:

autoalojada — quién opera el servidor y a qué raíz encadena su certificado;
de confianza pública — si el ecosistema de validación que usan tus partes de confianza (su almacén de confianza o lista de confianza) ya confía en esa raíz sin configuración manual, en lugar de requerir que se instale una raíz privada a mano. Esto se refiere a las anclas de confianza de la parte de confianza, no a ningún programa concreto como la Web PKI;
cualificada conforme a eIDAS — si la marca de tiempo tiene efecto legal cualificado en la UE.

El valor predeterminado incluido es únicamente autoalojado. Una TSA de confianza pública añade la segunda propiedad. Una TSA cualificada conforme a eIDAS tiene además estatus legal cualificado, validado a través de las Listas de Confianza de la UE, y puede ser operada por un QTSP externo. Las tres propiedades son independientes — una no implica otra.

La TSA predeterminada integrada

El extremo predeterminado es https://timestamp.pateon.com.tw, el propio servidor de sellado de tiempo RFC 3161 de NextPDF. Es autoalojado: el certificado de su unidad de sellado de tiempo encadena a una raíz privada PATEON, no a un programa de confianza pública. Por tanto, una parte de confianza no puede validar una marca de tiempo emitida por el valor predeterminado a menos que haya instalado y confiado en esa raíz PATEON de forma externa.

Como un token RFC 3161 no aporta evidencia externa de que el tiempo afirmado sea correcto, la confianza en cualquier marca de tiempo de este tipo recae por entero en confiar en la TSA emisora (ISO/IEC 18014-2 §7.3). Para el valor predeterminado incluido, ese ancla de confianza es privada, razón por la cual el valor predeterminado es una comodidad y un valor de desarrollo, no uno de grado de cumplimiento.

Cuando el extremo predeterminado está en uso y tu framework tiene un registrador configurado, NextPDF emite una advertencia única al inicio del proceso que señala que el valor predeterminado no es de confianza pública y que apunta a esta configuración. La advertencia es informativa; la firma se completa igualmente.

Sustituir el valor predeterminado

Configura el extremo de la TSA en la configuración del adaptador de tu framework. La clave exacta difiere según el adaptador (consulta la tabla por framework): en Laravel es la variable de entorno NEXTPDF_TSA_URL, en Symfony el nodo de bundle nextpdf.tsa.url, y en CodeIgniter la clave de entorno nextPdf.tsa.url.

La TSA efectiva se resuelve con esta precedencia, de mayor a menor:

Un TsaClient explícito que construyes e inyectas tú mismo — este siempre gana.
La URL configurada en tu adaptador — se usa cuando no inyectas un cliente.
El valor predeterminado integrado — se usa solo cuando no se ha establecido ninguno de los anteriores.

# Laravel (.env): use your own publicly-trusted TSA instead of the shipped default.
NEXTPDF_TSA_URL=http://timestamp.digicert.com

Desactivar la marca de tiempo

Dejar la url de la TSA de tu adaptador en su valor predeterminado (sin configurar) mantiene el extremo predeterminado integrado. Establecer esa url en un valor vacío es distinto: desactiva el sellado de tiempo. Sin ninguna TSA configurada, una firma solicitada en B-T o superior falla en modo cerrado con un error «TSA required» en lugar de degradarse silenciosamente a B-B.

# Laravel (.env):
# NEXTPDF_TSA_URL unset -> use the built-in default (timestamp succeeds against pateon).
# NEXTPDF_TSA_URL empty -> no TSA; a B-T+ request fails closed.
NEXTPDF_TSA_URL=

Elegir el algoritmo de resumen del messageImprint

Una solicitud de marca de tiempo RFC 3161 lleva un messageImprint — un hash de los datos que se sellan — y NextPDF usa SHA-256 para ese imprint de forma predeterminada. El valor predeterminado es una elección deliberada e interoperable; rara vez necesitas cambiarlo.

Cuando construyes un TsaClient a mano, puedes seleccionar un resumen de imprint distinto mediante el parámetro del constructor imprintHashAlgorithm, que toma un caso de TsaImprintHashAlgorithm: Sha256 (el predeterminado), Sha384, Sha512, Sha3_256, Sha3_384 o Sha3_512. El valor predeterminado mantiene cada solicitud emitida byte a byte idéntica a versiones anteriores, de modo que actualizar no cambia nada salvo que optes explícitamente por ello.

use NextPDF\Security\Timestamp\TsaClient;
use NextPDF\Security\Timestamp\TsaImprintHashAlgorithm;

// Default — SHA-256 imprint, unchanged from earlier releases:
$tsa = new TsaClient('https://timestamp.example.com/tsa');

// Opt in to a stronger imprint digest:
$tsa = new TsaClient(
    'https://timestamp.example.com/tsa',
    imprintHashAlgorithm: TsaImprintHashAlgorithm::Sha512,
);

Merece la pena conocer dos limitaciones antes de abandonar el valor predeterminado:

El soporte del ecosistema es SHA-256 hoy por hoy. Un imprint distinto de SHA-256 interopera con el verificador de tokens de Core, pero la puerta de prueba PAdES B-T de nextpdf-server y el mapa de resúmenes de validación de Premium reconocen por ahora únicamente los imprints SHA-256. Por tanto, una marca de tiempo de firma construida con un resumen de imprint distinto todavía no probará B-T en esas superficies. Mantén el valor predeterminado salvo que sepas que todos los consumidores de tus marcas de tiempo aceptan el resumen que elijas.
Los resúmenes precalculados deben coincidir con el algoritmo. getDocumentTimestamp() toma un hash de documento ya calculado; falla en modo cerrado, antes de cualquier llamada de red, cuando la longitud de ese hash no coincide con el algoritmo de imprint configurado, en lugar de enviar una solicitud incongruente.

Rutas de mejora

Para cualquier cosa más allá del desarrollo o el uso interno, sustituye el valor predeterminado por una de dos opciones más sólidas.

TSA de confianza pública

Apunta la url de la TSA de tu adaptador a una TSA cuyo certificado encadene a una raíz pública en la que tus partes de confianza ya confíen — por ejemplo http://timestamp.digicert.com. No hay que distribuir ninguna raíz privada. Una TSA de grado de producción normalmente declarará conformidad con una política de sellado de tiempo como ETSI EN 319 421 §5 y seguirá el perfil de protocolo RFC 3161 descrito en ETSI EN 319 422 §7; confirma esto frente a la política publicada del operador en lugar de asumirlo solo a partir de la confianza pública.

TSA cualificada conforme a eIDAS

Para marcas de tiempo que deban tener efecto legal cualificado en la Unión Europea, usa un servicio de sellado de tiempo cualificado de un prestador cualificado de servicios de confianza (QTSP) incluido en una Lista de Confianza de la UE. Una marca de tiempo electrónica cualificada vincula el tiempo a los datos de forma que se evite razonablemente la alteración indetectable, se basa en una fuente de tiempo precisa vinculada al tiempo universal coordinado, y está protegida por una firma electrónica avanzada o un sello electrónico avanzado del QTSP, o por un método equivalente (Regulation (EU) 910/2014, Art 42). Esta es la opción más sólida y la que elegir cuando una norma menciona explícitamente las marcas de tiempo cualificadas.

Configuración por framework

El valor predeterminado reside en la configuración de cada adaptador de framework, no en el motor del núcleo. El núcleo nunca inventa una URL: un TsaClient que construyes a mano requiere un extremo explícito y lanza una excepción si está vacío. Los niveles a largo plazo (B-LT y B-LTA) reutilizan la misma TSA configurada que B-T.

Integración	Dónde reside el valor predeterminado	Cómo sustituirlo
Laravel	`config/nextpdf.php` -> `tsa.url`	establece `NEXTPDF_TSA_URL` en `.env`
Symfony	configuración de bundle `nextpdf.tsa.url`	establece el nodo, o vincúlalo a una variable de entorno
CodeIgniter	`Config\NextPdf::$tsa['url']`	sustituye mediante la clave de entorno `nextPdf.tsa.url`
Plain core	sin valor predeterminado implícito	construye un `TsaClient` con una URL explícita + un cliente PSR-18 reforzado

En todos los adaptadores, B-B nunca construye un cliente TSA, de modo que una firma sin marca de tiempo no se ve afectada por ninguna de estas configuraciones.

Modelo de confianza y estándares

El valor de una marca de tiempo es la cadena de confianza que la respalda, no los bytes en sí. El token RFC 3161 solo afirma un tiempo; que esa afirmación sea creíble es una propiedad de la TSA que lo firmó (RFC 3161 §2; ISO/IEC 18014-2 §7.3). Cuando mantienes el valor predeterminado incluido, estás eligiendo un ancla de confianza autoalojada y de confianza privada — adecuada para flujos de trabajo de desarrollo e internos donde cada parte de confianza puede instalar la raíz PATEON, pero no para documentos validados por terceros. Para esos, pasa a una TSA de confianza pública, o a una TSA cualificada conforme a eIDAS cuando se requiera efecto legal cualificado.

Si operas tú mismo el valor predeterminado, puedes fijar (pin) la clave pública de la TSA en tu propio cliente PSR-18 inyectado. No fijes el valor predeterminado incluido en código compartido: una rotación de clave por parte del operador rompería entonces a todos los usuarios del valor predeterminado a la vez. La confianza en una marca de tiempo es la cadena de certificados y la raíz PATEON, no un pin de transporte.