Assinaturas Digitais (HasSecurity)

O trait HasSecurity fornece setSignature() para assinaturas digitais compatíveis com PAdES. O TCPDF-Next suporta quatro níveis de assinatura — de básico (B-B) a arquivístico (B-LTA) — através do PadesOrchestrator, TsaClient e módulos LTV. Todos os métodos de assinatura retornam static para encadeamento.

Referência Rápida

Classe / Enum	Propósito
CertificateInfo	Carregar certificados de assinatura (PEM ou PKCS#12)
SignatureLevel	Enum: PAdES_B_B, PAdES_B_T, PAdES_B_LT, PAdES_B_LTA
TsaClient	Cliente de autoridade de timestamp RFC 3161
SignatureAppearance	Widget de assinatura visível ou invisível
OcspClient	Verificação de revogação online RFC 6960
CrlFetcher	Busca de ponto de distribuição CRL RFC 5280

Níveis de Assinatura

Nível	O que Inclui	Validade
B-B (Básico)	Assinatura + certificado de assinatura	Válido enquanto o certificado não for revogado
B-T (Timestamp)	B-B + timestamp RFC 3161	Prova que a assinatura existia antes de um ponto no tempo
B-LT (Longo Prazo)	B-T + DSS com respostas OCSP/CRL	Verificável após expiração do certificado
B-LTA (Arquivístico)	B-LT + timestamp do documento + loop arquivístico	Verificável indefinidamente

Ciclo de Vida da Assinatura PAdES

sequenceDiagram
    participant App
    participant Core
    participant TSA as Servidor TSA
    participant OCSP as Respondedor OCSP
    App->>Core: sign(certificate, key)
    Core->>Core: PAdES B-B (incorporado)
    Core->>TSA: RFC 3161 timestamp
    TSA-->>Core: Token de timestamp
    Core->>Core: PAdES B-T
    Core->>OCSP: Verificação de certificado
    OCSP-->>Core: Resposta OCSP
    Core->>Core: PAdES B-LT
    Core->>Core: PAdES B-LTA (arquivo)

Carregando Certificados

De Arquivos PEM

use Yeeefang\TcpdfNext\Security\Signature\CertificateInfo;

$cert = CertificateInfo::fromFiles(
    certPath: '/path/to/certificate.pem',
    keyPath: '/path/to/private-key.pem',
    password: 'key-password',
    extraCerts: '/path/to/ca-chain.pem',  // certificados intermediários opcionais
);

De PKCS#12 (.p12 / .pfx)

use Yeeefang\TcpdfNext\Security\Signature\CertificateInfo;

$cert = CertificateInfo::fromPkcs12(
    p12Path: '/path/to/certificate.p12',
    password: 'pkcs12-password',
);

Exemplos de Assinatura

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Security\Signature\CertificateInfo;
use Yeeefang\TcpdfNext\Contracts\SignatureLevel;
use Yeeefang\TcpdfNext\Security\Timestamp\TsaClient;

$cert = CertificateInfo::fromFiles(
    certPath: '/path/to/certificate.pem',
    keyPath: '/path/to/private-key.pem',
    password: 'key-password',
);

// PAdES B-B (Básico) — apenas assinatura
$pdf = Document::create()
    ->setSignature($cert, SignatureLevel::PAdES_B_B)
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Signed document (B-B)')
    ->save('signed-bb.pdf');

// PAdES B-T (Timestamp) — assinatura + timestamp
$tsa = new TsaClient('https://freetsa.org/tsr');
$pdf = Document::create()
    ->setSignature($cert, SignatureLevel::PAdES_B_T, $tsa)
    ->addPage()
    ->cell(0, 10, 'Signed with timestamp (B-T)')
    ->save('signed-bt.pdf');

// PAdES B-LTA (Arquivístico) — validação completa de longo prazo
$pdf = Document::create()
    ->setSignature($cert, SignatureLevel::PAdES_B_LTA, $tsa)
    ->addPage()
    ->cell(0, 10, 'Archival signature (B-LTA)')
    ->save('signed-blta.pdf');

O TsaClient suporta autenticação opcional. A verificação de nonce e o DNS pinning são habilitados por padrão para prevenir ataques de replay e SSRF.

$tsa = new TsaClient(
    url: 'https://tsa.example.com/timestamp',
    user: 'tsa-user',
    pass: 'tsa-password',
);

Validação de Longo Prazo (B-LT / B-LTA)

Para os níveis B-LT e B-LTA, dados de revogação são buscados e incorporados automaticamente:

• OcspClient — consulta respondedores OCSP (RFC 6960) da extensão AIA do certificado
• CrlFetcher — baixa CRLs de pontos de distribuição (RFC 5280)
• DSS — armazena respostas OCSP e CRLs no Document Security Store
• VRI — dados de validação por assinatura (opcional, por recomendação ETSI)

O B-LTA adicionalmente adiciona um timestamp do documento, habilitando o loop arquivístico — o documento pode ser re-timestamped para estender a validade indefinidamente.

Aparência da Assinatura

Por padrão, as assinaturas são invisíveis. Para criar um widget de assinatura visível:

use Yeeefang\TcpdfNext\Security\Signature\SignatureAppearance;

$pdf = Document::create()
    ->setSignature($cert, SignatureLevel::PAdES_B_T, $tsa)
    ->setSignatureAppearance(
        SignatureAppearance::visible(x: 20, y: 250, w: 80, h: 30)
    )
    ->addPage()
    ->cell(0, 10, 'Document with visible signature')
    ->save('visible-signature.pdf');

Para uma assinatura explicitamente invisível:

$pdf->setSignatureAppearance(SignatureAppearance::invisible());

Algoritmos e Referência de Métodos

Algoritmos de assinatura via phpseclib3: RSA PKCS#1 v1.5 (padrão, maior compatibilidade) e RSASSA-PSS (padding mais forte, recomendado para novas implantações).

$pdf->setSignature(
    CertificateInfo   $cert,           // Certificado e chave privada
    SignatureLevel    $level,           // B-B, B-T, B-LT ou B-LTA
    ?TsaClient        $tsa   = null,   // Obrigatório para B-T, B-LT, B-LTA
);

Retorna static para encadeamento. A assinatura é aplicada durante save() ou output().