Alur kerja perjanjian yang ditandatangani

Spec Spec: ETSI EN 319 142-2, §5.1 ETSI EN 319 142-2 §5.1 Spec Spec: ISO 32000-2:2020, §12.8 ISO 32000-2:2020 §12.8 Evidence ⊕ Mixed evidence Evidence: Mixed evidence

Sekilas pandang

Perjanjian yang ditandatangani bukan sekadar “PDF yang memiliki tanda tangan.” Dokumen ini disiapkan agar tanda tangan melindungi byte yang tepat. Dokumen ditandatangani pada tingkat yang sesuai dengan kewajibannya, lalu dikemas agar tetap dapat diverifikasi setelah sertifikat penandatangan kedaluwarsa. Halaman ini menelusuri skenario tersebut dari dokumen kosong hingga kontrak berumur panjang, sekaligus menjelaskan secara terbuka langkah mana yang sudah diimplementasikan oleh engine saat ini dan langkah mana yang hanya dipaparkan sebagai antarmuka yang dibekukan.

Mengapa ini penting

Kontrak yang terverifikasi pada hari penandatanganannya tetapi gagal tiga tahun kemudian dalam sebuah sengketa justru lebih buruk daripada kontrak tanpa tanda tangan sama sekali, karena ada pihak yang mengandalkannya. Kegagalannya jarang terletak pada kriptografinya. Biasanya penyebabnya adalah timestamp yang hilang atau bukti pencabutan yang tidak tersedia, dan hal itu baru terungkap lama setelah penandatangan tidak lagi terlibat.

Memilih kewajiban tanda tangan sejak awal dan menghasilkan bukti yang dibutuhkan kewajiban tersebut pada saat penandatanganan menjadi pembeda antara perjanjian yang bertahan dan perjanjian yang diam-diam melemah. Keputusan ini dibuat sekali di dalam alur kerja, bukan ditemukan kembali setiap kali sengketa muncul.

Versi ringkasnya

• Siapkan dahulu, lalu tanda tangani. Tanda tangan mencakup persis rentang byte yang menjadi dasar perhitungannya. Putuskan bahwa dokumen sudah final — termasuk revisi apa pun yang ditambahkan kemudian — sebelum Anda menandatangani, bukan sesudahnya.
• Pilih tingkat sesuai kewajibannya, bukan sebaliknya. PAdES mendefinisikan serangkaian tingkat: tanda tangan dasar, tanda tangan dengan timestamp, tanda tangan dengan materi validasi tertanam, dan tanda tangan yang distempel ulang untuk validitas arsip tanpa batas waktu (ETSI EN 319 142-2 §5.1).
• Validitas jangka panjang adalah struktur, bukan sekadar properti. Ia berupa Document Security Store ditambah timestamp dokumen, yang ditulis ke dalam berkas (ISO 32000-2:2020 §12.8).
• Cermatlah terhadap batas sambungannya. Fungsi tingkat tinggi milik NextPDF, yaitu Document::setSignature(), membekukan API publik tetapi gagal cepat alih-alih menghasilkan berkas yang tidak ditandatangani. Jalur yang sudah diimplementasikan adalah orchestrator tingkat lebih rendah. Halaman ini tidak berpura-pura sebaliknya.

Bagaimana NextPDF menanganinya

NextPDF memisahkan keputusan dari mekanisme. Keputusannya adalah tingkat PAdES mana yang dibutuhkan oleh kewajiban tersebut. Mekanismenya adalah bagaimana byte ditandatangani dan bagaimana materi validasi dimuat. Menyamakan keduanya adalah penyebab tim berakhir dengan tanda tangan yang valid tetapi tidak tahan lama.

Skenario ini memiliki empat tahap.

1. Prepare the document Compose the agreement and treat it as final. The signature will protect this exact byte range and nothing added outside it without a new revision.
2. Choose the obligation B-B proves who. B-T adds trusted time. B-LT embeds the material to validate later. B-LTA re-stamps for indefinite validity.
3. Sign A CMS signature is embedded in the signature dictionary over the byte range; a timestamp is requested from a TSA if the level needs one.
4. Preserve For long-term levels, the Document Security Store and a document timestamp are written so the signature outlives its certificate.

Skenario perjanjian bertanda tangan secara menyeluruh: setiap tahap menambahkan satu jaminan, dan tingkat yang Anda pilih pada tahap dua menentukan seberapa banyak bukti yang harus dihasilkan tahap tiga dan empat.

Enum tingkat ini nyata dan mengodekan kewajibannya secara eksplisit. B-B membuktikan identitas penandatangan. B-T menambahkan timestamp tepercaya. Pertanyaan “kapan” diajukan setegas pertanyaan “siapa”. B-LT menyematkan sertifikat dan respons pencabutan yang dibutuhkan untuk memvalidasi tanda tangan setelah sertifikat penandatangan kedaluwarsa. B-LTA menambahkan timestamp dokumen sehingga rantai kepercayaan dapat diperpanjang tanpa batas waktu dengan menstempel ulang sebelum setiap sertifikat timestamp habis masa berlakunya. Enum ini menyatakan tingkat mana yang memerlukan timestamp dan mana yang memerlukan materi validasi tertanam, sehingga engine dapat menolak kombinasi yang mustahil alih-alih menghasilkan berkas menyesatkan yang seolah-olah “bertanda tangan”.

Human-factors note: Human-factors note

Bagian yang jujur: Document::setSignature() ada agar antarmuka API publik dibekukan bagi konsumen hilir, tetapi batas sambungan penulis yang mengubahnya menjadi revisi bertanda tangan yang nyata belum diimplementasikan. Memanggilnya lalu save() tidak akan menghasilkan PDF yang tidak ditandatangani lalu menganggap tugas selesai. Ia gagal cepat dengan diagnostik pemblokir yang menyebutkan jalur yang didukung. Gagal cepat, bukan artefak yang diam-diam salah, adalah pilihan desainnya. Kontrak yang tampak bertanda tangan tetapi sebenarnya tidak adalah persis kegagalan yang dihindari oleh hal ini. Jalur yang sudah diimplementasikan saat ini adalah orchestrator dua fase tingkat lebih rendah, dan kapabilitas arsip jangka panjang bersifat tingkat Premium.

Apa kata buktinya

Tingkat-tingkat ini didukung standar. Evidence § Standard-backed Evidence: Standard-backed Spec Spec: ETSI EN 319 142-2, §5.1 ETSI EN 319 142-2 §5.1 menjelaskan tingkat PAdES yang dilapiskan di atas blok penyusun EN 319 142-1, mulai dari tanda tangan tertanam dasar ke atas. Struktur jangka panjangnya ditetapkan oleh Spec Spec: ISO 32000-2:2020, §12.8 ISO 32000-2:2020 §12.8 : validasi jangka panjang bertumpu pada Document Security Store dan kamus timestamp dokumen yang ditulis ke dalam berkas.

Model tingkatnya didukung kode. Evidence { } Code-backed Evidence: Code-backed Enum SignatureLevel memiliki empat kasus PAdES (B-B, B-T, B-LT, B-LTA) dengan metode predikat untuk “memerlukan timestamp”, “memerlukan materi validasi tertanam”, dan “memerlukan timestamp dokumen”. Fungsi tingkat tinggi Document::setSignature() terhubung ke pengaman gagal cepat yang memunculkan diagnostik pemblokir yang dapat ditindaklanjuti alih-alih menghasilkan dokumen yang tidak ditandatangani — sebuah perilaku yang dapat diverifikasi, bukan sekadar klaim.

Perilaku pemeliharaan jangka panjang didokumentasikan pada tingkat kapabilitas untuk tingkat Premium: antarmuka arsip menulis DSS dan VRI per tanda tangan, memeriksa kelengkapan arsip dengan health check, dan menstempel ulang dengan timestamp dokumen sebelum sertifikat timestamp kedaluwarsa. Dokumentasi menyatakan dengan jelas bahwa pihak pemverifikasi tetap menjadi penentu.

Contoh praktis

Contoh ini menunjukkan keputusan — memilih kewajiban — menggunakan enum yang sebenarnya. Jalur penandatanganan yang sudah diimplementasikan adalah orchestrator tingkat lebih rendah. Pemanggilan tingkat tinggi ditampilkan hanya untuk memperjelas perilaku gagal cepat.

<?php

declare(strict_types=1);

use NextPDF\Security\Signature\SignatureLevel;

/**
 * Map a business obligation to a PAdES level.
 *
 * The obligation drives the level, not the reverse — choosing B-B for a
 * 10-year contract is a decision you do not want to make implicitly.
 */
function levelForObligation(string $obligation): SignatureLevel
{
    return match ($obligation) {
        // Internal sign-off, short retention, signer identity is enough.
        'internal_approval' => SignatureLevel::PAdES_B_B,

        // Counterparty agreement: prove the moment of signing.
        'counterparty_agreement' => SignatureLevel::PAdES_B_T,

        // Regulated contract that must verify after cert expiry.
        'regulated_contract' => SignatureLevel::PAdES_B_LT,

        // Long-lived legal record: indefinite, re-stampable validity.
        'long_term_legal_record' => SignatureLevel::PAdES_B_LTA,

        default => throw new \InvalidArgumentException(
            "Unknown obligation: {$obligation}",
        ),
    };
}

$level = levelForObligation('regulated_contract');

// The enum carries the obligation's implications with it.
$needsTsa     = $level->requiresTimestamp();         // true for B-T+
$needsDss     = $level->requiresDss();               // true for B-LT+
$needsArchive = $level->requiresDocumentTimestamp(); // true only for B-LTA

Objek tingkat tersebut bukan sekadar label. Ia menjawab apa yang dituntut oleh kewajiban tersebut, sehingga implementasi hilir tidak perlu menurunkannya lagi.

Kesalahpahaman umum

Kesalahpahaman yang sering berulang adalah “tanda tangan sudah valid, jadi kita sudah selesai.” Validitas hari ini perlu, tetapi tidak cukup. Sebuah tanda tangan dihitung atas suatu rentang byte. Apa pun yang ditambahkan di luar rentang tersebut pada revisi berikutnya tidak tercakup olehnya, dan itulah alasan persis mengapa persiapan harus dilakukan sebelum penandatanganan. Tanda tangan yang terverifikasi sekarang pun bisa gagal kemudian saat sertifikatnya kedaluwarsa, kecuali materi validasi telah disematkan pada saat penandatanganan. “Valid” dan “tahan lama” adalah jaminan yang berbeda, dan hanya kewajiban tersebut yang memberi tahu Anda mana yang sebenarnya Anda butuhkan.

Jebakan terkait yang khas untuk engine ini: mengira bahwa fungsi tingkat tinggi setSignature() menghasilkan berkas bertanda tangan saat ini. Tidak demikian. Ia gagal cepat secara sengaja. Perlakukan diagnostik tersebut sebagai kontrak perilakunya.

Batasan dan ruang lingkup

• Document::setSignature() adalah antarmuka publik yang dibekukan, bukan penanda tangan yang sudah diimplementasikan. Ia gagal cepat dengan diagnostik pemblokir. Ia tidak pernah menghasilkan PDF yang tidak ditandatangani sebagai pengganti PDF yang ditandatangani. Jalur yang sudah diimplementasikan adalah orchestrator dua fase tingkat lebih rendah.
• Pemeliharaan validasi jangka panjang (DSS/VRI, health check, loop timestamp arsip) adalah kapabilitas tingkat Premium. Core tidak menyediakan loop arsip tersebut. Lihat ruang lingkup di bawah.
• Sebuah tanda tangan melindungi persis rentang byte-nya. Revisi yang ditambahkan kemudian bersifat terpisah. Engine tidak memperluas cakupan secara surut.
• NextPDF menghasilkan dan memelihara strukturnya; ia tidak menentukan keabsahan. Apakah sebuah tanda tangan tepercaya bergantung pada trust anchor dan kebijakan pemverifikasi, yang berada di luar engine.
• B-LTA tidak membuat tanda tangan abadi dengan sendirinya. Ia memungkinkan validitas tanpa batas waktu hanya jika loop penstempelan ulang berjalan tepat jadwal sebelum setiap sertifikat timestamp kedaluwarsa.
• Halaman ini menjelaskan antarmuka arsip Premium pada tingkat perilaku. Ia tidak menyatakan adanya penerimaan oleh pengadilan atau otoritas tertentu mana pun.

PAdES signing and long-term validity — edition availability

Edition	Availability
Core	○ Core memaparkan enum SignatureLevel dan antarmuka Document::setSignature() yang dibekukan (gagal cepat). Orchestrator tingkat lebih rendah yang sudah diimplementasikan mencakup penandatanganan baseline. Pemeliharaan arsip jangka panjang tidak ada di Core.
Pro	○ Penandatanganan baseline PAdES (B-B / B-T) melalui orchestrator tersedia.
Enterprise	○ Menambahkan B-LT / B-LTA, Document Security Store dan pemeliharaan VRI per tanda tangan, health check LTV, dan loop arsip timestamp dokumen untuk validitas tanpa batas waktu.

Dokumen terkait

• Profil baseline PAdES — B-B, B-T, B-LT, B-LTA dijelaskan sebagai tingkatan dan cara memilihnya.
• Validasi jangka panjang — mengapa tanda tangan yang terverifikasi hari ini bisa gagal dalam sepuluh tahun, dan bagaimana LTV menyematkan buktinya.
• Panduan keputusan integrasi — paket ekosistem mana yang cocok untuk alur kerja penandatanganan, termasuk batas sambungan persetujuan manusia di NextPDF Connect.

Glosarium

• PAdES — PDF Advanced Electronic Signatures: keluarga profil ETSI yang mendefinisikan cara sebuah tanda tangan elektronik tingkat lanjut dimuat di dalam PDF.
• Byte range — rentang byte berurutan dalam berkas yang menjadi dasar perhitungan sebuah tanda tangan; konten di luarnya tidak dilindungi oleh tanda tangan tersebut.
• Tingkat tanda tangan (B-B / B-T / B-LT / B-LTA) — tingkatan PAdES: siapa yang menandatangani, kapan, dengan materi validasi tertanam, dan dapat distempel ulang untuk validitas arsip tanpa batas waktu.
• TSA — Time-Stamping Authority: layanan RFC 3161 yang menegaskan bahwa suatu keadaan dokumen telah ada pada saat UTC tertentu.
• DSS (Document Security Store) — penyimpanan di dalam berkas berisi sertifikat, respons OCSP, dan CRL yang dibutuhkan untuk memvalidasi sebuah tanda tangan setelah sertifikatnya kedaluwarsa.
• LTV (Long-Term Validation) — menjaga sebuah tanda tangan tetap dapat diverifikasi dari waktu ke waktu dengan menyematkan bukti validasi dan menstempelnya ulang.
• Fail-fast — menolak menghasilkan artefak yang menyesatkan dan justru memunculkan galat yang dapat ditindaklanjuti, alih-alih menghasilkan berkas yang diam-diam salah.