Segurança e operações no compat-legacy

Visão geral

O adaptador usa o modelo de segurança do motor NextPDF e acrescenta alguns reforços deliberados em relação ao TCPDF legado 6.2.13. Esta página declara com precisão o que está disponível e o que não está, sem exageros. Leia a seção de assinatura com atenção; o escopo dela é intencionalmente restrito.

Comportamentos legados reforçados

Por segurança, o adaptador altera três comportamentos históricos do TCPDF 6.2.13. Eles não podem ser reconfigurados para voltar à forma insegura:

Questão	TCPDF legado 6.2.13	Adaptador
Tratamento de erros	`Error()` chama `die()` e encerra o processo	`Error()` lança `RuntimeException`; quem chama pode observar e capturar a falha, sem encerramento silencioso do processo.
Execução de HTML	Uma brecha de escape poderia executar PHP a partir da marcação	A constante `K_TCPDF_CALLS_IN_HTML` fica fixa em `false`; a marcação não consegue acionar a execução de PHP.
Saída direta	`Output()` envia para o buffer de saída ativo	A saída passa por uma ponte segura de destino e não polui um buffer de saída controlado por quem chama.

A mudança no tratamento de erros permite que você observe uma falha em vez de perder o processo por encerramento. O Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) 5.0 §16.5.3 estabelece que uma aplicação deve falhar de forma controlada e segura e evitar condições de fail-open. Lançar uma exceção em vez de encerrar aplica esse princípio. O reforço de HTML remove um ponto de execução de código. Trate o código legado que dependia do comportamento antigo como um defeito a corrigir durante /integrations/tcpdf-compat/migration/. O resumo fixado da cláusula está no front-matter citations da página.

Criptografia

O adaptador expõe SetProtection() do TCPDF e delega ao manipulador de segurança padrão do motor NextPDF.

O manipulador padrão usa AES-256. O parâmetro legado $mode é aceito por compatibilidade com a assinatura do método e ignorado; não há como selecionar uma cifra mais fraca por meio deste método. Quando o modo estrito está ativado, um $mode não padrão lança exceção para obrigar a migração a reconhecê-lo (verificado em tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php).
Se nenhuma senha de proprietário for fornecida, o adaptador gera uma senha de proprietário aleatória e criptograficamente forte, em vez de reutilizar a senha de usuário. Isso impede que detentores de acesso no nível de usuário obtenham controle do documento no nível de proprietário.
A criptografia baseada em certificado (chave pública) não é feita por meio de SetProtection(); o adaptador ignora o parâmetro $pubkeys dele. Use o ponto de entrada moderno para criptografia de chave pública exposto no adaptador (setPublicKeyEncryption()), que delega ao motor.

O comportamento de criptografia reflete o manipulador de segurança padrão descrito na ISO 32000-2 §7. Essa cláusula define as entradas do dicionário de criptografia e o manipulador padrão AES-256 usado pelo motor. Esta documentação não afirma que a saída é “segura por padrão” ou “à prova de adulteração”. Ela declara apenas a cifra usada e o comportamento da senha de proprietário implementado pelo código. O resumo fixado da cláusula está no front-matter citations da página.

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Encrypted document');

// User password set; owner password auto-generated (strong, random).
$pdf->SetProtection([], 'user-secret');

$pdf->Output(__DIR__ . '/encrypted.pdf', 'F');

Assinaturas digitais — declaração de escopo

Leia esta seção literalmente. Ela é deliberadamente conservadora.

Os métodos legados setSignature() e addEmptySignatureAppearance() do TCPDF não são implementados no adaptador sobre o motor core. No modo padrão, eles não fazem nada. No modo estrito, lançam TcpdfNotImplementedException.
A assinatura digital não é um recurso da distribuição core por meio deste adaptador. O suporte a assinatura baseline requer uma edição comercial do NextPDF.
Se houver uma edição comercial, o adaptador expõe um ponto de entrada moderno de assinatura (setSignatureV2()) que delega ao motor. O perfil padrão dele é o perfil baseline (B-B).
Esta documentação não afirma que qualquer edição produza perfis de assinatura com carimbo de tempo, validação de longo prazo ou arquivamento por meio deste adaptador. Especificamente, ela não afirma o comportamento B-T, B-LT ou B-LTA. A especificação baseline PDF Advanced Electronic Signatures (PAdES) §6.1 define quatro níveis baseline distintos: B-B, B-T, B-LT e B-LTA. Cada um tem os próprios requisitos. B-B é o nível baseline, e os níveis superiores (carimbo de tempo, longo prazo, arquivamento) são perfis separados e mais exigentes. Apenas o baseline B-B está no escopo da documentação desta camada de compatibilidade. Os níveis superiores estão explicitamente fora de escopo e não são afirmados para nenhuma edição aqui. O resumo fixado da cláusula está no front-matter citations da página.
Esta documentação não faz nenhuma afirmação de assinatura “certificada”, “garantida”, “juridicamente válida” ou “qualificada eIDAS” em parte alguma. A correção da assinatura, a política de âncora de confiança e a validade jurídica são responsabilidade da edição de assinatura e da Public Key Infrastructure (PKI) de quem chama, não desta camada de compatibilidade.

Se a migração exigir assinatura, trate isso como uma frente de trabalho separada: adote a application programming interface (API) moderna de assinatura em uma edição comercial e valide a assinatura resultante com um verificador independente. Não dependa da chamada setSignature() do TCPDF; aqui ela não faz nada.

O método legado setTimeStamp() é aceito por compatibilidade com a assinatura do método e emite um aviso; ele não produz uma assinatura com carimbo de tempo por meio deste adaptador.

PDF/A e conformidade

O sinalizador pdfa do construtor é aceito por compatibilidade com a assinatura do método. A conformidade de arquivamento PDF/A requer uma edição comercial do NextPDF. O adaptador expõe enablePdfA(), que delega ao motor, e o motor retorna um erro de configuração acionável quando a edição necessária está ausente. O adaptador não produz silenciosamente um arquivo não conforme enquanto alega PDF/A.

A saída é sempre PDF 2.0 (ISO 32000-2). A ISO 32000-2 §7.5.2 especifica que um escritor conforme identifica a versão do documento como 2.0 e não a rebaixa para uma versão mais antiga ao salvar. Portanto, setPDFVersion() não pode rebaixar para uma versão anterior (consulte /integrations/tcpdf-compat/method-coverage/ §4). O resumo fixado da cláusula está no front-matter citations da página.

Orientação operacional

Sem encerramento de processo. Como Error() lança exceção em vez de die(), envolva os pontos de entrada de renderização em try/catch e mapeie as falhas para o contrato de erro da sua aplicação. Não presuma que uma renderização com falha encerre a requisição.
Segurança do buffer de saída. Output() com S retorna bytes; com F grava um arquivo; com E retorna um corpo Multipurpose Internet Mail Extensions (MIME) em base64; com I/D, ele é roteado pelo caminho de saída do motor. Prefira S ou F em workers e manipuladores Hypertext Transfer Protocol (HTTP) para controlar a resposta diretamente; consulte /integrations/tcpdf-compat/production-usage/.
O modo estrito não é uma configuração de produção. Mantenha-o restrito a um job de continuous integration (CI) ou de auditoria. Uma exceção em um caminho de renderização de produção é pior do que um parâmetro degradado silenciosamente.
Higiene de constantes. Defina as constantes PDF_* / K_* antes da primeira construção do adaptador. Os dois sinalizadores reforçados (K_TCPDF_CALLS_IN_HTML, K_TCPDF_THROW_EXCEPTION_ERROR) não podem ser flexibilizados; não tente flexibilizá-los.
Senhas de proprietário aleatórias. Se você depende de uma senha de proprietário determinística, defina-a explicitamente. Caso contrário, uma senha aleatória forte é gerada por documento e não é recuperável.

Notas sobre o modelo de ameaças

Para os métodos de imagem, o adaptador recusa um caminho com stream wrapper antes de qualquer leitura do sistema de arquivos. A detecção do tipo de imagem (TcpdfImages::getImageFileType) trata qualquer caminho scheme://, incluindo phar://, php:// e outros stream wrappers do PHP, como um wrapper e ignora a sondagem file_get_contents / getimagesize, recorrendo à inferência apenas pela extensão. Isso fecha um vetor de desserialização de metadados phar no alvo de backport PHP 7.4; o motor rejeita por conta própria a incorporação de caminho com wrapper.
O adaptador não adiciona validação nem sanitização de caminhos para os caminhos de arquivo passados aos métodos de imagem ou de saída além do que o motor já faz. Trate caminhos e URLs fornecidos por quem chama como não confiáveis no limite da sua aplicação.
O HTML passado aos métodos de HTML é renderizado pelo motor, não por um analisador de HTML do TCPDF. O antigo ponto de execução de PHP está fechado, mas você ainda deve tratar o HTML fornecido por quem chama como entrada não confiável.
A criptografia protege a confidencialidade do documento em repouso sob o manipulador padrão. Ela não substitui a segurança de transporte nem o controle de acesso na sua aplicação.

Consulte também

/integrations/tcpdf-compat/method-coverage/ — comportamento exato de SetProtection(), setSignature()
/integrations/tcpdf-compat/configuration/ — os dois sinalizadores reforçados e não configuráveis
/integrations/tcpdf-compat/production-usage/ — workers, buffers, tratamento de falhas
docs/TCPDF_COVERAGE.md — matriz de cobertura autoritativa
Pacote NOTICE — declaração de implementação independente