Configuração da TSA

Em resumo

O NextPDF contata uma Time Stamp Authority (TSA) somente quando você assina em PAdES B-T ou acima. Em B-B não há timestamp nem chamada de rede; portanto, esta página não se aplica a uma assinatura B-B.

Para que o B-T funcione de imediato, o NextPDF inclui uma TSA padrão embutida. Esse padrão é uma conveniência: ele permite que uma assinatura com timestamp seja bem-sucedida sem configuração adicional. Ele não é confiável publicamente e não é qualificado eIDAS; portanto, não é apropriado para uso em produção ou em conformidade sem uma escolha deliberada. Esta página explica exatamente o que é o padrão, como apontar o NextPDF para a sua própria TSA, como desativar o timestamp e os dois caminhos de atualização.

Três propriedades são independentes e não devem ser confundidas:

self-hosted — quem opera o servidor e a qual raiz o seu certificado encadeia;
confiável publicamente — se o ecossistema de validação que suas partes confiantes usam (o repositório de confiança ou a lista de confiança delas) já confia nessa raiz sem configuração manual, em vez de exigir que uma raiz privada seja instalada manualmente. Isso diz respeito às âncoras de confiança da parte confiante, não a qualquer programa específico como a Web PKI;
qualificado eIDAS — se o timestamp carrega efeito legal qualificado na UE.

O padrão incluído é apenas self-hosted. Uma TSA confiável publicamente adiciona a segunda propriedade. Uma TSA qualificada eIDAS carrega adicionalmente status legal qualificado, validado por meio das Listas Confiáveis da UE, e pode ser operada por um QTSP terceirizado. As três propriedades são independentes — uma não implica a outra.

A TSA padrão embutida

O endpoint padrão é https://timestamp.pateon.com.tw, o próprio servidor de timestamp RFC 3161 do NextPDF. Ele é self-hosted: o certificado da sua unidade de timestamp encadeia a uma raiz PATEON privada, não a um programa de confiança público. Uma parte confiante, portanto, não consegue validar um timestamp emitido pelo padrão a menos que tenha instalado e confiado nessa raiz PATEON fora de banda.

Como um token RFC 3161 não carrega nenhuma evidência externa de que o tempo afirmado é correto, a confiança em qualquer timestamp desse tipo repousa inteiramente em confiar na TSA emissora (ISO/IEC 18014-2 §7.3). Para o padrão incluído, essa âncora de confiança é privada, e é por isso que o padrão é um padrão de conveniência e desenvolvimento, não um padrão de nível de conformidade.

Quando o endpoint padrão está em uso e seu framework tem um logger configurado, o NextPDF emite um aviso único no início do processo, observando que o padrão não é confiável publicamente e apontando para esta configuração. O aviso é informativo; a assinatura ainda assim é bem-sucedida.

Substituindo o padrão

Defina o endpoint da TSA na configuração do adaptador do seu framework. A chave exata difere por adaptador (consulte a tabela por framework): no Laravel é a variável de ambiente NEXTPDF_TSA_URL, no Symfony o nó de bundle nextpdf.tsa.url e no CodeIgniter a chave de ambiente nextPdf.tsa.url.

A TSA efetiva é resolvida com esta precedência, a mais alta primeiro:

Um TsaClient explícito que você constrói e injeta — este sempre prevalece.
A URL configurada no seu adaptador — usada quando você não injeta um cliente.
O padrão embutido — usado somente quando nenhum dos anteriores está definido.

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

Desativando o timestamp

Manter a url da TSA do seu adaptador no padrão (não configurada) preserva o endpoint padrão embutido. Definir essa url como um valor vazio é diferente: isso desativa o timestamp. Sem nenhuma TSA configurada, uma assinatura solicitada em B-T ou acima falha de forma fechada com um erro “TSA required” em vez de rebaixar silenciosamente para 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=

Escolhendo o algoritmo de digest do messageImprint

Uma requisição de timestamp RFC 3161 carrega um messageImprint — um hash dos dados que estão sendo carimbados — e o NextPDF usa SHA-256 para esse imprint por padrão. O padrão é uma escolha deliberada e interoperável; você raramente precisa alterá-lo.

Ao construir um TsaClient manualmente, você pode selecionar um digest de imprint diferente por meio do parâmetro de construtor imprintHashAlgorithm, que recebe um case de TsaImprintHashAlgorithm: Sha256 (o padrão), Sha384, Sha512, Sha3_256, Sha3_384 ou Sha3_512. O padrão mantém cada requisição emitida byte a byte idêntica às versões anteriores, de modo que a atualização não altera nada, a menos que você opte por isso.

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,
);

Vale conhecer duas restrições antes de abandonar o padrão:

O suporte do ecossistema é SHA-256 hoje. Um imprint diferente de SHA-256 interopera com o verificador de token do Core, mas o proof gate PAdES B-T do nextpdf-server e o mapa de digests de validação do Premium reconhecem, no momento, apenas imprints SHA-256. Um timestamp de assinatura construído com um digest de imprint diferente, portanto, ainda não comprova B-T nessas superfícies. Mantenha o padrão a menos que todo consumidor dos seus timestamps seja reconhecidamente capaz de aceitar o digest que você escolher.
Digests pré-computados devem corresponder ao algoritmo. getDocumentTimestamp() recebe um hash de documento já computado; ele falha de forma fechada, antes de qualquer chamada de rede, quando o comprimento desse hash não corresponde ao algoritmo de imprint configurado, em vez de enviar uma requisição incompatível.

Caminhos de atualização

Para qualquer coisa além de desenvolvimento ou uso interno, substitua o padrão por uma de duas opções mais fortes.

TSA confiável publicamente

Aponte a url da TSA do seu adaptador para uma TSA cujo certificado encadeia a uma raiz pública em que suas partes confiantes já confiam — por exemplo http://timestamp.digicert.com. Nenhuma raiz privada precisa ser distribuída. Uma TSA de nível de produção normalmente declarará conformidade com uma política de timestamp como a ETSI EN 319 421 §5 e seguirá o perfil de protocolo RFC 3161 descrito na ETSI EN 319 422 §7; confirme isso em relação à política publicada do operador, em vez de presumi-lo apenas da confiança pública.

TSA qualificada eIDAS

Para timestamps que precisam carregar efeito legal qualificado na União Europeia, use um serviço de timestamp qualificado de um provedor de serviços de confiança qualificado (QTSP) listado em uma Lista Confiável da UE. Um carimbo do tempo eletrônico qualificado vincula o tempo aos dados de modo a impedir razoavelmente alterações não detectáveis, baseia-se em uma fonte de tempo precisa vinculada ao Tempo Universal Coordenado, e é protegido por uma assinatura eletrônica avançada ou selo eletrônico avançado do QTSP, ou por um método equivalente (Regulation (EU) 910/2014, Art 42). Esta é a opção mais forte e a que se deve escolher quando uma regulamentação nomeia explicitamente timestamps qualificados.

Configuração por framework

O padrão reside na configuração de cada adaptador de framework, não no motor central. O Core nunca inventa uma URL: um TsaClient que você constrói manualmente exige um endpoint explícito e lança uma exceção se ele estiver vazio. Os níveis de longo prazo (B-LT e B-LTA) reutilizam a mesma TSA configurada para o B-T.

Integração	Onde reside o padrão	Como substituir
Laravel	`config/nextpdf.php` -> `tsa.url`	defina `NEXTPDF_TSA_URL` no `.env`
Symfony	configuração de bundle `nextpdf.tsa.url`	defina o nó, ou vincule-o a uma variável de ambiente
CodeIgniter	`Config\NextPdf::$tsa['url']`	substitua via a chave de ambiente `nextPdf.tsa.url`
Plain core	nenhum padrão implícito	construa um `TsaClient` com uma URL explícita + um cliente PSR-18 reforçado

Em todo adaptador, B-B nunca constrói um cliente TSA; portanto, uma assinatura sem timestamp não é afetada por nenhuma dessa configuração.

Modelo de confiança e padrões

O valor de um timestamp é a cadeia de confiança por trás dele, não os bytes em si. O token RFC 3161 apenas afirma um tempo; se essa afirmação é crível é uma propriedade da TSA que o assinou (RFC 3161 §2; ISO/IEC 18014-2 §7.3). Quando você mantém o padrão incluído, está escolhendo uma âncora de confiança self-hosted e privada — adequada para desenvolvimento e fluxos de trabalho internos onde toda parte confiante pode instalar a raiz PATEON, mas não para documentos validados por terceiros. Para esses, migre para uma TSA confiável publicamente, ou para uma TSA qualificada eIDAS quando efeito legal qualificado for exigido.

Se você opera o padrão por conta própria, pode fixar a chave pública da TSA no seu próprio cliente PSR-18 injetado. Não fixe o padrão incluído em código compartilhado: uma rotação de chave do lado do operador então quebraria todos os usuários do padrão de uma só vez. A confiança em um timestamp é a cadeia de certificados e a raiz PATEON, não uma fixação de transporte.