Konfigurasi TSA

Sekilas

NextPDF menghubungi Time Stamp Authority (TSA) hanya ketika Anda menandatangani pada PAdES B-T atau lebih tinggi. Pada B-B tidak ada stempel waktu dan tidak ada panggilan jaringan, sehingga halaman ini tidak berlaku untuk tanda tangan B-B.

Agar B-T langsung berfungsi tanpa penyetelan, NextPDF menyertakan TSA bawaan. Bawaan tersebut adalah kemudahan: ia memungkinkan tanda tangan berstempel waktu berhasil tanpa konfigurasi tambahan. Bawaan tersebut bukan publicly-trusted dan bukan eIDAS-qualified, sehingga tidak sesuai untuk penggunaan produksi atau kepatuhan tanpa pilihan yang disengaja. Halaman ini menjelaskan secara persis apa bawaan tersebut, cara mengarahkan NextPDF ke TSA Anda sendiri, cara mematikan stempel waktu, dan dua jalur pemutakhiran.

Tiga properti berikut bersifat independen dan tidak boleh dirancukan:

self-hosted — siapa yang mengoperasikan server dan ke root mana rantai sertifikatnya tertaut;
publicly-trusted — apakah ekosistem validasi yang dipakai relying party Anda (trust store atau trust list mereka) sudah memercayai root tersebut tanpa penyetelan manual, alih-alih mensyaratkan pemasangan root privat secara manual. Ini menyangkut trust anchor milik relying party, bukan program tertentu seperti Web PKI;
eIDAS-qualified — apakah stempel waktu membawa efek hukum qualified di Uni Eropa.

Bawaan yang disertakan hanya bersifat self-hosted. TSA yang publicly-trusted menambahkan properti kedua. TSA yang eIDAS-qualified juga membawa status hukum qualified, divalidasi melalui EU Trusted Lists, dan dapat dioperasikan oleh QTSP pihak ketiga. Ketiga properti tersebut independen — satu tidak menyiratkan yang lain.

TSA bawaan

Endpoint bawaan adalah https://timestamp.pateon.com.tw, server stempel waktu RFC 3161 milik NextPDF sendiri. Server tersebut bersifat self-hosted: sertifikat unit stempel waktunya tertaut ke root PATEON privat, bukan ke program trust publik. Karena itu, sebuah relying party tidak dapat memvalidasi stempel waktu yang diterbitkan oleh bawaan tersebut kecuali ia telah memasang dan memercayai root PATEON itu di luar jalur (out of band).

Karena token RFC 3161 tidak membawa bukti eksternal bahwa waktu yang dinyatakan itu benar, kepercayaan pada stempel waktu semacam itu sepenuhnya bertumpu pada kepercayaan terhadap TSA penerbit (ISO/IEC 18014-2 §7.3). Bagi bawaan yang disertakan, trust anchor tersebut bersifat privat, itulah sebabnya bawaan tersebut merupakan bawaan kemudahan dan pengembangan, bukan kelas kepatuhan (compliance-grade).

Ketika endpoint bawaan sedang digunakan dan framework Anda memiliki logger yang dikonfigurasi, NextPDF memancarkan peringatan satu kali pada awal proses yang menyatakan bahwa bawaan tersebut tidak publicly-trusted dan menunjuk ke konfigurasi ini. Peringatan tersebut bersifat informasional; penandatanganan tetap berhasil.

Mengganti bawaan

Setel endpoint TSA pada konfigurasi adapter framework Anda. Kuncinya berbeda persis per adapter (lihat tabel per-framework): pada Laravel ia adalah variabel lingkungan NEXTPDF_TSA_URL, pada Symfony node bundel nextpdf.tsa.url, dan pada CodeIgniter kunci env nextPdf.tsa.url.

TSA efektif diselesaikan dengan presedensi berikut, tertinggi lebih dulu:

TsaClient eksplisit yang Anda bangun dan suntikkan sendiri — ini selalu menang.
URL yang dikonfigurasikan pada adapter Anda — dipakai ketika Anda tidak menyuntikkan klien.
Bawaan — dipakai hanya ketika kedua opsi di atas tidak disetel.

# Laravel (.env): use your own publicly-trusted TSA instead of the shipped default.
NEXTPDF_TSA_URL=http://timestamp.digicert.com

Menonaktifkan stempel waktu

Membiarkan url TSA adapter Anda pada bawaannya (tidak dikonfigurasi) tetap mempertahankan endpoint bawaan. Menyetel url tersebut ke nilai kosong itu berbeda: ia menonaktifkan stempel waktu. Tanpa TSA yang dikonfigurasi, tanda tangan yang diminta pada B-T atau lebih tinggi gagal secara fail-closed dengan galat “TSA required” alih-alih diam-diam turun ke B-B.

# Laravel (.env):
# NEXTPDF_TSA_URL unset -> use the built-in default (timestamp succeeds against pateon).
# NEXTPDF_TSA_URL empty -> no TSA; a B-T+ request fails closed.
NEXTPDF_TSA_URL=

Memilih algoritma digest messageImprint

Permintaan stempel waktu RFC 3161 membawa sebuah messageImprint — hash dari data yang distempel waktu — dan NextPDF menggunakan SHA-256 untuk imprint tersebut secara bawaan. Bawaan tersebut merupakan pilihan yang disengaja dan interoperabel; Anda jarang perlu mengubahnya.

Ketika Anda membangun sebuah TsaClient secara manual, Anda dapat memilih digest imprint yang berbeda melalui parameter konstruktor imprintHashAlgorithm, yang menerima sebuah case TsaImprintHashAlgorithm: Sha256 (bawaan), Sha384, Sha512, Sha3_256, Sha3_384, atau Sha3_512. Bawaan tersebut menjaga setiap permintaan yang dipancarkan tetap byte-identik dengan rilis-rilis sebelumnya, sehingga pemutakhiran tidak mengubah apa pun kecuali Anda memilihnya secara sadar (opt in).

use NextPDF\Security\Timestamp\TsaClient;
use NextPDF\Security\Timestamp\TsaImprintHashAlgorithm;

// Default — SHA-256 imprint, unchanged from earlier releases:
$tsa = new TsaClient('https://timestamp.example.com/tsa');

// Opt in to a stronger imprint digest:
$tsa = new TsaClient(
    'https://timestamp.example.com/tsa',
    imprintHashAlgorithm: TsaImprintHashAlgorithm::Sha512,
);

Dua batasan berikut perlu Anda ketahui sebelum beralih dari bawaan:

Dukungan ekosistem saat ini adalah SHA-256. Imprint non-SHA-256 dapat berinteroperasi dengan verifier token Core, tetapi gerbang bukti (proof gate) PAdES B-T nextpdf-server dan peta digest validasi Premium untuk saat ini hanya mengenali imprint SHA-256. Karena itu, stempel waktu tanda tangan yang dibangun dengan digest imprint berbeda belum akan membuktikan B-T pada permukaan-permukaan tersebut. Pertahankan bawaan kecuali setiap konsumen stempel waktu Anda diketahui menerima digest yang Anda pilih.
Digest yang telah dihitung sebelumnya harus cocok dengan algoritmanya. getDocumentTimestamp() menerima hash dokumen yang sudah dihitung; ia gagal secara fail-closed, sebelum panggilan jaringan apa pun, ketika panjang hash tersebut tidak cocok dengan algoritma imprint yang dikonfigurasi, alih-alih mengirim permintaan yang tidak cocok.

Jalur pemutakhiran

Untuk apa pun di luar pengembangan atau penggunaan internal, ganti bawaan dengan salah satu dari dua opsi yang lebih kuat.

TSA yang publicly-trusted

Arahkan url TSA adapter Anda ke TSA yang sertifikatnya tertaut ke root publik yang sudah dipercaya relying party Anda — misalnya http://timestamp.digicert.com. Tidak ada root privat yang harus didistribusikan. TSA kelas produksi umumnya akan menyatakan kesesuaian dengan kebijakan stempel waktu seperti ETSI EN 319 421 §5 dan mengikuti profil protokol RFC 3161 yang dijelaskan dalam ETSI EN 319 422 §7; konfirmasikan hal ini terhadap kebijakan yang diterbitkan operator alih-alih mengasumsikannya dari kepercayaan publik semata.

TSA yang eIDAS-qualified

Untuk stempel waktu yang harus membawa efek hukum qualified di Uni Eropa, gunakan layanan stempel waktu qualified dari penyedia layanan kepercayaan qualified (QTSP) yang terdaftar pada EU Trusted List. Sebuah stempel waktu elektronik qualified menautkan waktu ke data sehingga secara wajar mencegah perubahan yang tidak terdeteksi, berbasis sumber waktu akurat yang tertaut ke Coordinated Universal Time, dan dilindungi oleh tanda tangan elektronik tingkat lanjut atau segel elektronik tingkat lanjut milik QTSP, atau oleh metode yang setara (Regulation (EU) 910/2014, Art 42). Ini adalah opsi terkuat dan yang harus dipilih ketika suatu regulasi menyebut stempel waktu qualified secara eksplisit.

Konfigurasi per-framework

Bawaan berada di dalam konfigurasi tiap adapter framework, bukan di mesin inti. Core tidak pernah mengarang URL: sebuah TsaClient yang Anda bangun sendiri mensyaratkan endpoint eksplisit dan melempar eksepsi jika kosong. Level jangka panjang (B-LT dan B-LTA) menggunakan kembali TSA terkonfigurasi yang sama dengan B-T.

Integrasi	Di mana bawaan berada	Cara mengganti
Laravel	`config/nextpdf.php` -> `tsa.url`	setel `NEXTPDF_TSA_URL` di `.env`
Symfony	konfigurasi bundel `nextpdf.tsa.url`	setel node, atau ikat ke variabel env
CodeIgniter	`Config\NextPdf::$tsa['url']`	ganti melalui kunci env `nextPdf.tsa.url`
Plain core	tidak ada bawaan implisit	bangun sebuah `TsaClient` dengan URL eksplisit + klien PSR-18 yang diperkeras

Pada setiap adapter, B-B tidak pernah membangun klien TSA, sehingga tanda tangan tanpa stempel waktu tidak terpengaruh oleh konfigurasi apa pun ini.

Model kepercayaan dan standar

Nilai sebuah stempel waktu terletak pada rantai kepercayaan di belakangnya, bukan pada byte-nya sendiri. Token RFC 3161 hanya menyatakan suatu waktu; apakah pernyataan tersebut dapat dipercaya merupakan properti dari TSA yang menandatanganinya (RFC 3161 §2; ISO/IEC 18014-2 §7.3). Ketika Anda mempertahankan bawaan yang disertakan, Anda memilih trust anchor self-hosted berkepercayaan privat — cocok untuk pengembangan dan alur kerja internal di mana setiap relying party dapat memasang root PATEON, tetapi tidak untuk dokumen yang divalidasi pihak ketiga. Untuk dokumen tersebut, beralihlah ke TSA yang publicly-trusted, atau ke TSA yang eIDAS-qualified ketika efek hukum qualified diperlukan.

Jika Anda mengoperasikan bawaan tersebut sendiri, Anda dapat menyematkan (pin) kunci publik TSA pada klien PSR-18 yang Anda suntikkan sendiri. Jangan sematkan bawaan yang disertakan pada kode bersama: rotasi kunci di sisi operator akan merusak setiap pengguna bawaan sekaligus. Kepercayaan pada sebuah stempel waktu adalah rantai sertifikat dan root PATEON, bukan penyematan (pin) transport.