Tanda Tangan Digital (HasSecurity)

Trait HasSecurity menyediakan setSignature() untuk tanda tangan digital yang sesuai PAdES. TCPDF-Next mendukung empat level tanda tangan — dari basic (B-B) hingga archival (B-LTA) — melalui PadesOrchestrator, TsaClient, dan modul LTV. Semua method tanda tangan mengembalikan static untuk chaining.

Referensi Cepat

Class / Enum	Tujuan
CertificateInfo	Memuat sertifikat penandatangan (PEM atau PKCS#12)
SignatureLevel	Enum: PAdES_B_B, PAdES_B_T, PAdES_B_LT, PAdES_B_LTA
TsaClient	Client timestamp authority RFC 3161
SignatureAppearance	Widget tanda tangan visible atau invisible
OcspClient	Pengecekan revokasi online RFC 6960
CrlFetcher	Pengambilan CRL distribution point RFC 5280

Level Tanda Tangan

Level	Apa yang Termasuk	Validitas
B-B (Basic)	Tanda tangan + sertifikat penandatangan	Valid selama sertifikat tidak dicabut
B-T (Timestamp)	B-B + timestamp RFC 3161	Membuktikan tanda tangan ada sebelum titik waktu tertentu
B-LT (Long-Term)	B-T + DSS dengan respons OCSP/CRL	Dapat diverifikasi setelah sertifikat kedaluwarsa
B-LTA (Archival)	B-LT + document timestamp + archival loop	Dapat diverifikasi tanpa batas waktu

Siklus Hidup Tanda Tangan PAdES

sequenceDiagram
    participant App
    participant Core
    participant TSA as Server TSA
    participant OCSP as OCSP Responder
    App->>Core: sign(certificate, key)
    Core->>Core: PAdES B-B (embedded)
    Core->>TSA: RFC 3161 timestamp
    TSA-->>Core: Token timestamp
    Core->>Core: PAdES B-T
    Core->>OCSP: Pengecekan sertifikat
    OCSP-->>Core: Respons OCSP
    Core->>Core: PAdES B-LT
    Core->>Core: PAdES B-LTA (arsip)

Memuat Sertifikat

Dari File 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',  // sertifikat intermediate opsional
);

Dari PKCS#12 (.p12 / .pfx)

use Yeeefang\TcpdfNext\Security\Signature\CertificateInfo;

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

Contoh Penandatanganan

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 (Basic) — tanda tangan saja
$pdf = Document::create()
    ->setSignature($cert, SignatureLevel::PAdES_B_B)
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Dokumen bertanda tangan (B-B)')
    ->save('signed-bb.pdf');

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

// PAdES B-LTA (Archival) — validasi jangka panjang penuh
$pdf = Document::create()
    ->setSignature($cert, SignatureLevel::PAdES_B_LTA, $tsa)
    ->addPage()
    ->cell(0, 10, 'Tanda tangan arsip (B-LTA)')
    ->save('signed-blta.pdf');

TsaClient mendukung autentikasi opsional. Verifikasi nonce dan DNS pinning diaktifkan secara default untuk mencegah serangan replay dan SSRF.

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

Validasi Jangka Panjang (B-LT / B-LTA)

Untuk level B-LT dan B-LTA, data revokasi diambil dan di-embed secara otomatis:

• OcspClient — query OCSP responder (RFC 6960) dari ekstensi AIA sertifikat
• CrlFetcher — download CRL dari distribution point (RFC 5280)
• DSS — menyimpan respons OCSP dan CRL di Document Security Store
• VRI — data validasi per tanda tangan (opsional, sesuai rekomendasi ETSI)

B-LTA juga menambahkan document timestamp, memungkinkan archival loop — dokumen dapat di-re-timestamp untuk memperpanjang validitas tanpa batas.

Tampilan Tanda Tangan

Secara default, tanda tangan bersifat invisible. Untuk membuat widget tanda tangan visible:

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, 'Dokumen dengan tanda tangan visible')
    ->save('visible-signature.pdf');

Untuk tanda tangan invisible secara eksplisit:

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

Algoritma dan Referensi Method

Algoritma tanda tangan melalui phpseclib3: RSA PKCS#1 v1.5 (default, kompatibilitas terluas) dan RSASSA-PSS (padding lebih kuat, direkomendasikan untuk deployment baru).

$pdf->setSignature(
    CertificateInfo   $cert,           // Sertifikat dan private key
    SignatureLevel    $level,           // B-B, B-T, B-LT, atau B-LTA
    ?TsaClient        $tsa   = null,   // Diperlukan untuk B-T, B-LT, B-LTA
);

Mengembalikan static untuk chaining. Tanda tangan diterapkan selama save() atau output().