Timestamp Authority (TSA)

★ Pro — Commercial License Required

Integrasi TSA RFC 3161 memerlukan paket Pro.

TCPDF-Next Pro menyediakan client Timestamp Authority RFC 3161 production-grade (TsaClient) dan helper DocumentTimestamp yang menyematkan tanda tangan /DocTimeStamp untuk workflow PAdES B-LTA.

TsaClient

Penggunaan Dasar

use Yeeefang\TcpdfNext\Pro\Tsa\TsaClient;

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

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

Dengan Autentikasi

Beberapa server TSA korporat memerlukan kredensial:

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

Konstruksi TimeStampReq RFC 3161

Client membangun struktur ASN.1 TimeStampReq yang sesuai standar untuk setiap request:

1. MessageImprint -- Digest SHA-256 dari data yang akan di-timestamp.
2. Nonce -- Nilai 64-bit yang acak secara kriptografis untuk mencegah serangan replay.
3. CertReq -- Diset true sehingga TSA menyertakan sertifikat penandatangannya dalam respons.

// Hash harus binary mentah (32 byte untuk SHA-256)
$hash = hash('sha256', $documentBytes, binary: true);

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

Verifikasi Nonce

Setelah menerima TimeStampResp, client secara otomatis:

1. Mem-parse TSTInfo dari respons.
2. Mengekstrak nonce dari TSTInfo.
3. Membandingkannya dengan nonce yang dikirim dalam request.
4. Melempar TsaNonceMismatchException jika berbeda.

try {
    $token = $tsa->timestamp($hash);
} catch (\Yeeefang\TcpdfNext\Pro\Tsa\TsaNonceMismatchException $e) {
    // Nonce tidak cocok -- kemungkinan serangan MITM atau replay
    log_security_event($e->getMessage());
}

Validasi PKIStatus

Client memvalidasi field PKIStatus di setiap respons:

Kode	Arti	Perilaku Client
0	granted	Token diterima
1	grantedWithMods	Token diterima dengan warning di-log
2	rejection	TsaRejectedException dilempar
3	waiting	Tidak didukung; exception dilempar
4	revocationWarning	Token diterima dengan warning di-log
5	revocationNotification	TsaCertRevokedException dilempar

DNS Pinning (Proteksi SSRF)

Untuk mencegah Server-Side Request Forgery, Anda bisa mem-pin hostname TSA ke alamat IP tertentu. Client menggunakan CURLOPT_RESOLVE untuk melewati resolusi DNS sepenuhnya:

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

// Pin hostname ke IP yang diketahui -- DNS tidak pernah dikueri
$tsa->pinDns('tsa.corporate.example', '203.0.113.42', port: 443);

Ini penting di lingkungan di mana URL TSA berasal dari input user atau konfigurasi eksternal dan tidak boleh me-resolve ke alamat jaringan internal.

mTLS (Mutual TLS)

Server TSA korporat sering memerlukan autentikasi sertifikat client. Berikan sertifikat client dan private key Anda:

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

Handle cURL yang mendasari dikonfigurasi dengan CURLOPT_SSLCERT, CURLOPT_SSLKEY, dan CURLOPT_SSLCERTPASSWD.

DocumentTimestamp (B-LTA)

DocumentTimestamp menambahkan tanda tangan /DocTimeStamp ke PDF, yang merupakan langkah terakhir dalam workflow PAdES B-LTA. Timestamp ini mencakup seluruh dokumen termasuk semua tanda tangan sebelumnya dan 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',
);

// Terapkan document timestamp (incremental save)
$stamper->apply($document);

Ringkasan Workflow B-LTA

1. Tanda tangani dokumen       (PAdES B-B)
2. Tambah signature timestamp  (PAdES B-T)
3. Sematkan DSS (OCSP + CRL)  (PAdES B-LT)
4. Tambah /DocTimeStamp        (PAdES B-LTA)  <-- DocumentTimestamp

Server TSA Populer

Provider	URL	Auth	Catatan
FreeTSA	https://freetsa.org/tsr	Tidak ada	Gratis; cocok untuk testing
Sectigo	https://timestamp.sectigo.com	Tidak ada	Production-grade; tier gratis
DigiCert	https://timestamp.digicert.com	Tidak ada	Dipercaya secara luas
GlobalSign	https://timestamp.globalsign.com/tsa/r6advanced1	Tidak ada	SHA-256 default
Kustom / Enterprise	Bervariasi	Basic, mTLS, Bearer	Gunakan pinDns() + clientCertificate()

TIP

Untuk dokumen PAdES B-LTA produksi, gunakan provider TSA yang root certificate-nya ada di Adobe Approved Trust List (AATL). Ini memastikan timestamp dikenali oleh Adobe Acrobat tanpa konfigurasi trust manual.