Timestamp Authority (TSA)

★ Pro — Commercial License Required

L'integrazione TSA RFC 3161 richiede il pacchetto Pro.

TCPDF-Next Pro fornisce un client RFC 3161 Timestamp Authority production-grade (TsaClient) e un helper DocumentTimestamp che incorpora firme /DocTimeStamp per workflow PAdES B-LTA.

TsaClient

Utilizzo Base

use Yeeefang\TcpdfNext\Pro\Tsa\TsaClient;

$tsa = new TsaClient(url: 'https://freetsa.org/tsr');

$token = $tsa->timestamp($pdfHash);

Con Autenticazione

Alcuni server TSA aziendali richiedono credenziali:

$tsa = new TsaClient(
    url:      'https://tsa.corporate.example/rfc3161',
    username: 'api-user',
    password: 'api-secret',
);

Costruzione TimeStampReq RFC 3161

Il client costruisce una struttura ASN.1 TimeStampReq conforme agli standard per ogni richiesta:

1. MessageImprint -- Digest SHA-256 dei dati da timestampare.
2. Nonce -- Valore 64-bit crittograficamente casuale per prevenire attacchi replay.
3. CertReq -- Impostato a true così la TSA include il suo certificato firma nella risposta.

// L'hash deve essere binario grezzo (32 byte per SHA-256)
$hash = hash('sha256', $documentBytes, binary: true);

$token = $tsa->timestamp($hash, algorithm: 'sha256');

Verifica Nonce

Dopo aver ricevuto TimeStampResp, il client automaticamente:

1. Analizza il TSTInfo dalla risposta.
2. Estrae il nonce dal TSTInfo.
3. Lo confronta con il nonce inviato nella richiesta.
4. Lancia TsaNonceMismatchException se differiscono.

try {
    $token = $tsa->timestamp($hash);
} catch (\Yeeefang\TcpdfNext\Pro\Tsa\TsaNonceMismatchException $e) {
    // Nonce mismatch -- possibile attacco MITM o replay
    log_security_event($e->getMessage());
}

Validazione PKIStatus

Il client valida il campo PKIStatus in ogni risposta:

Codice	Significato	Comportamento Client
0	granted	Token accettato
1	grantedWithMods	Token accettato con warning loggato
2	rejection	TsaRejectedException lanciata
3	waiting	Non supportato; eccezione lanciata
4	revocationWarning	Token accettato con warning loggato
5	revocationNotification	TsaCertRevokedException lanciata

DNS Pinning (Protezione SSRF)

Per prevenire Server-Side Request Forgery, puoi pinnare l'hostname TSA a un indirizzo IP specifico. Il client usa CURLOPT_RESOLVE per bypassare completamente la risoluzione DNS:

$tsa = new TsaClient(
    url: 'https://tsa.corporate.example/rfc3161',
);

// Pinna l'hostname a un IP noto -- il DNS non è mai interrogato
$tsa->pinDns('tsa.corporate.example', '203.0.113.42', port: 443);

Questo è critico in ambienti dove l'URL TSA origina da input utente o configurazione esterna e non deve risolversi a indirizzi rete interni.

mTLS (Mutual TLS)

I server TSA aziendali richiedono frequentemente autenticazione certificato client. Passa il tuo certificato client e chiave privata:

$tsa = new TsaClient(
    url: 'https://tsa.bank.example/timestamp',
);

$tsa->clientCertificate(
    certPath: '/etc/pki/tsa-client.pem',
    keyPath:  '/etc/pki/tsa-client.key',
    keyPassword: 'client-key-pass',
);

L'handle cURL sottostante è configurato con CURLOPT_SSLCERT, CURLOPT_SSLKEY e CURLOPT_SSLCERTPASSWD.

DocumentTimestamp (B-LTA)

DocumentTimestamp aggiunge una firma /DocTimeStamp al PDF, che è il passo finale in un workflow PAdES B-LTA. Questo timestamp copre l'intero documento incluse tutte le firme precedenti e il DSS (Document Security Store).

use Yeeefang\TcpdfNext\Pro\Tsa\DocumentTimestamp;
use Yeeefang\TcpdfNext\Pro\Tsa\TsaClient;

$tsa = new TsaClient(url: 'https://freetsa.org/tsr');

$stamper = new DocumentTimestamp(
    tsaClient: $tsa,
    hashAlgorithm: 'sha256',
);

// Applica il timestamp documento (salvataggio incrementale)
$stamper->apply($document);

Riepilogo Workflow B-LTA

1. Firma documento          (PAdES B-B)
2. Aggiungi timestamp firma (PAdES B-T)
3. Incorpora DSS (OCSP + CRL) (PAdES B-LT)
4. Aggiungi /DocTimeStamp       (PAdES B-LTA)  <-- DocumentTimestamp

Server TSA Popolari

Provider	URL	Auth	Note
FreeTSA	https://freetsa.org/tsr	Nessuna	Gratuito; adatto per testing
Sectigo	https://timestamp.sectigo.com	Nessuna	Production-grade; tier gratuito
DigiCert	https://timestamp.digicert.com	Nessuna	Ampiamente fidato
GlobalSign	https://timestamp.globalsign.com/tsa/r6advanced1	Nessuna	SHA-256 predefinito
Custom / Enterprise	Varia	Basic, mTLS, Bearer	Usa pinDns() + clientCertificate()

TIP

Per documenti PAdES B-LTA produzione, usa un provider TSA il cui certificato root è nell'Adobe Approved Trust List (AATL). Questo garantisce che i timestamp siano riconosciuti da Adobe Acrobat senza configurazione fiducia manuale.