Visão Geral de Segurança

O TCPDF-Next é construído sobre uma filosofia de design security-first. Cada componente, desde primitivas criptográficas até parsing de HTML, é projetado para eliminar categorias inteiras de vulnerabilidades em vez de corrigi-las após a descoberta.

Filosofia de Design Security-First

Segurança no TCPDF-Next não é um recurso adicionado sobre uma codebase legada. É uma restrição arquitetural que influenciou cada decisão de design desde o primeiro dia:

• Negar por padrão -- Carregamento de recursos externos, requisições de rede e acesso a arquivos são bloqueados a menos que explicitamente permitidos.
• Falhar fechado -- Quando uma verificação de segurança não pode ser realizada (ex.: OCSP responder inacessível), a operação falha em vez de prosseguir de forma insegura.
• Defesa em profundidade -- Múltiplas camadas independentes de proteção garantem que um único bypass não comprometa o sistema.
• Superfície de ataque mínima -- Zero dependências Composer de runtime. Todas as operações criptográficas usam as extensões embutidas OpenSSL e Sodium do PHP.

Criptografia AES-256 (Sem Algoritmos Legados)

O TCPDF-Next implementa exclusivamente criptografia AES-256 conforme definido no PDF 2.0 (ISO 32000-2, Revision 6). Todos os algoritmos legados e inseguros são permanentemente rejeitados:

Algoritmo	Status	Motivo
AES-256-CBC	Suportado	Padrão PDF 2.0, sem ataques práticos conhecidos
RC4 (40-bit / 128-bit)	Proibido	Cifra de stream com vieses conhecidos e ataques práticos
AES-128	Proibido	Margem insuficiente para confidencialidade de longo prazo
DES / 3DES	Não implementado	Vulnerabilidades de tamanho de bloco e comprimento de chave
MD5 (para derivação de chave)	Proibido	Ataques de colisão desde 2004

use YeeeFang\TcpdfNext\Encryption\EncryptionAlgorithm;
use YeeeFang\TcpdfNext\Encryption\Permissions;

$pdf->setEncryption()
    ->setAlgorithm(EncryptionAlgorithm::AES256)
    ->setUserPassword('reader-password')
    ->setOwnerPassword('admin-password')
    ->setPermissions(
        Permissions::PRINT_HIGH_QUALITY
        | Permissions::COPY
        | Permissions::ACCESSIBILITY
    )
    ->apply();

Assinaturas Digitais PAdES (B-B até B-LTA)

O TCPDF-Next implementa o Baseline Profile PAdES completo (ETSI EN 319 142-1) para assinaturas digitais com níveis crescentes de validade de longo prazo:

Nível	Descrição	Período de Validação
PAdES B-B	Assinatura CMS básica com certificado de assinatura	Validade do certificado (~1-3 anos)
PAdES B-T	+ Timestamp RFC 3161 de uma TSA confiável	Validade do certificado TSA (~10-15 anos)
PAdES B-LT	+ Document Security Store com dados OCSP/CRL	Tempo de vida de segurança do algoritmo (~15-30 anos)
PAdES B-LTA	+ Archive timestamp para revalidação indefinida	Indefinido (com re-timestamping periódico)

Para detalhes de implementação, veja Assinaturas PAdES B-LTA.

Proteção SSRF com DNS Pinning

Todas as requisições de rede externas (busca de imagens, comunicação TSA, consultas OCSP) passam por um cliente HTTP reforçado com proteção SSRF embutida:

• DNS pinning -- Endereços IP resolvidos são validados antes da conexão. Ranges de rede privada (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopback (127.0.0.0/8) e link-local (169.254.0.0/16) são bloqueados.
• Restrição de protocolo -- Apenas https:// é permitido por padrão. http:// simples é rejeitado a menos que explicitamente permitido.
• Allowlist de domínios -- Allowlist configurável para domínios externos permitidos.
• Seguimento de redirecionamentos -- Limitado a um máximo configurável (padrão: 3) com revalidação em cada hop.

Prevenção de Path Traversal

Todas as operações de caminho de arquivo são sanitizadas para prevenir ataques de directory traversal:

• Nomes de arquivos incorporados são limpos de separadores de caminho e sequências ...
• Caminhos de arquivo de fonte são resolvidos para caminhos canônicos absolutos e validados contra diretórios permitidos.
• Caminhos de imagem referenciados em HTML são restritos a diretórios explicitamente configurados via ResourcePolicy.

#[\SensitiveParameter] em Senhas e Chaves

Todos os parâmetros de método que aceitam senhas, passphrases, chaves privadas ou PINs são anotados com o atributo #[\SensitiveParameter] do PHP 8.2. Isso garante que valores sensíveis sejam automaticamente redatados de stack traces, logs de erro e mensagens de exceção:

public function setUserPassword(
    #[\SensitiveParameter] string $password
): self { /* ... */ }

public function setCertificate(
    string $certificate,
    #[\SensitiveParameter] string $privateKey,
    #[\SensitiveParameter] string $passphrase = ''
): self { /* ... */ }

#[\NoDiscard] em Valores de Retorno Críticos

Métodos que retornam resultados críticos de segurança (resultados de validação, verificação de assinatura) são anotados com #[\NoDiscard] para prevenir que chamadores ignorem valores de retorno:

#[\NoDiscard]
public function validate(string $pdfPath): ValidationResult { /* ... */ }

#[\NoDiscard]
public function verify(): SignatureVerificationResult { /* ... */ }

Ignorar esses valores de retorno produz um aviso do compilador, capturando uma classe comum de bugs de segurança no tempo de desenvolvimento.

PHPStan Level 10 (Zero Erros, Sem Baseline)

Toda a codebase passa na análise estática PHPStan no nível mais rigoroso (Level 10) com zero erros e sem arquivo de baseline. Isso significa:

• Sem anotações @phpstan-ignore em lugar algum na codebase.
• Sem categorias de erro suprimidas.
• Todos os tipos são totalmente especificados, incluindo generics e template types.
• Todos os caminhos de código morto são eliminados.

100% declare(strict_types=1)

Cada arquivo PHP no TCPDF-Next começa com declare(strict_types=1). Não há exceções. Isso elimina uma classe inteira de bugs de coerção de tipo que historicamente levaram a vulnerabilidades de segurança em aplicações PHP.

Considerações de Conformidade OWASP

O TCPDF-Next aborda as seguintes categorias OWASP relevantes para bibliotecas de geração de PDF:

Categoria OWASP	Mitigação
A01 -- Broken Access Control	Permissões PDF granulares, criptografia baseada em certificado
A02 -- Cryptographic Failures	Apenas AES-256, sem algoritmos fracos, comparações em tempo constante
A03 -- Injection	Sanitização HTML, prevenção de path traversal, sem eval()
A05 -- Security Misconfiguration	Padrões seguros, políticas de recursos deny-by-default
A06 -- Vulnerable Components	Zero dependências de runtime, crypto embutido via OpenSSL/Sodium
A07 -- Authentication Failures	#[\SensitiveParameter], limpeza segura de memória via sodium_memzero()
A10 -- SSRF	DNS pinning, bloqueio de rede privada, allowlist de domínios

Documentação de Segurança

Explore a documentação completa de segurança:

• Boas Práticas de Segurança -- Validação de entrada, gerenciamento de certificados, segurança de implantação
• Visão Geral de Segurança -- Vetores de ataque de assinatura PDF e mitigações