Penandatanganan dalam skala besar, tanpa kompromi

SpecSpec: ISO 32000-2, §12.8ISO 32000-2 §12.8SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1SpecSpec: RFC 5652, §5.1RFC 5652 §5.1

Sekilas pandang

Menandatangani satu dokumen adalah sebuah operasi kriptografis. Menandatangani seratus ribu dokumen dalam tenggat adalah operasi yang sama, yang diulang, di mana kegagalan berbahayanya bukan lagi “tadi lambat” melainkan “salah satunya keluar tak ditandatangani dan tidak ada yang menyadari.” Halaman ini tentang melakukan hal kedua tanpa mengorbankan hal pertama: penandatanganan massal dan konkuren di mana setiap tanda tangan tetap benar, jalannya proses menolak memancarkan berkas yang tidak dapat ia tandatangani, dan pekerjaan besar dilanjutkan alih-alih dimulai dari awal.

Mengapa ini penting

Sebuah tanda tangan adalah fakta per dokumen. Digest-nya dihitung atas rentang byte yang dideklarasikan yang mengecualikan nilai tanda tangan itu sendiri (SpecSpec: ISO 32000-2, §12.8ISO 32000-2 §12.8), sehingga tidak ada cara yang jujur untuk menandatangani seribu dokumen “sebagai satu batch” dalam satu sapuan — masing-masing membawa CMS SignedData-nya sendiri atas byte-nya sendiri (SpecSpec: RFC 5652, §5.1RFC 5652 §5.1). Skala karenanya melipatgandakan peluang bagi tepat satu hal untuk diam-diam salah: pegangan kunci yang sesaat gagal, otoritas timestamp yang kehabisan waktu, sebuah worker yang mati sambil memegang berkas yang ditulis separuh.

Hasil yang mahal bukanlah crash. Crash itu lantang dan Anda mencobanya ulang. Hasil yang mahal adalah yang diam — sebuah PDF tak ditandatangani yang tampak selesai tersimpan dalam arsip, ditemukan berbulan-bulan kemudian oleh validator seorang auditor. Dalam volume besar, “sebagian besar ditandatangani” tak terbedakan dari “ditandatangani” sampai persis yang penting itu diperiksa. Inti dari penandatanganan dalam skala besar adalah menjadikan hasil itu mustahil secara struktural, bukan langka secara statistik.

Versi singkatnya

• Setiap dokumen ditandatangani satu per satu, atas rentang byte-nya sendiri. Batch adalah kata penjadwalan, bukan kata kriptografis. Tidak ada tanda tangan bersama.
• Levelnya adalah sebuah kontrak, bukan petunjuk. Anda menyebut sebuah level baseline PAdES dan mesin menghasilkan persis level itu untuk setiap dokumen, atau ia menggagalkan dokumen itu secara lantang (SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1).
• Pipeline-nya fail-closed. Dokumen yang tidak dapat ditandatangani dengan benar tidak diloloskan sebagai byte mentah. Ia ditahan, bukan diteruskan.
• Konkurensinya per dokumen, dan aman secara konstruksi. Unit penandatanganan tidak berbagi state yang dapat berubah, sehingga dua worker tidak dapat merusak keluaran satu sama lain.
• Pekerjaan besar bersifat durabel. Keluaran yang sudah di-commit tidak dipancarkan ulang saat dilanjutkan; sebuah jalannya proses yang crash berlanjut dari checkpoint terakhirnya alih-alih menandatangani ulang segalanya.

Bagaimana NextPDF menanganinya

Desainnya bertumpu pada satu pemisahan: menghasilkan tanda tangan adalah langkah per dokumen yang kecil dan deterministik; menjalankan ribuan di antaranya dengan aman adalah langkah orkestrasi. Memisahkan keduanya itulah yang membuat masing-masing tetap sederhana.

Langkah penandatanganan adalah yang tidak boleh pernah berkompromi. Anda meminta sebuah level — sebuah kasus enum SignatureLevel, bukan string yang harus ditafsirkan mesin — dan level itu diperlakukan sebagai kontrak untuk dokumen itu. Mesin menghasilkan level yang diminta atau berhenti dengan galat yang dapat ditindaklanjuti; ia tidak diam-diam menandatangani pada level yang lebih rendah dan membiarkan sebuah catatan mengklaim level yang lebih tinggi. Kebenaran tidak mengendur karena ada lebih banyak dokumen di belakang yang satu ini. Tanda tangan keseratus ribu dihitung sama cermatnya dengan yang pertama.

Aturan fail-closed-lah yang membuatnya tepercaya dalam volume besar. Jalur penandatanganan NextPDF menolak memancarkan artefak yang tampak masuk akal tapi tak ditandatangani sebagai pengganti dari yang Anda minta. Rute aplikasi yang didukung adalah API Document tingkat tinggi: Anda mengonfigurasi tanda tangan dengan Document::setSignature() lalu meminta byte-nya dengan Document::getPdfData() (atau save() / output()), dan jalannya penulisan tunggal itu entah memancarkan PDF yang ditandatangani dengan benar atau melempar galat sebelum mengembalikan byte — tidak pernah berkas tak ditandatangani yang dipercaya pemanggil telah ditandatangani. Diterapkan ke seluruh batch, inilah aturan yang mengubah “satu lolos tanpa ditandatangani” dari cacat laten yang diam menjadi satu pekerjaan yang gagal dan dapat dicoba ulang.

1. Warm the signing material onceOn worker boot, open the key/certificate source and the timestamp client. This cost is paid once per worker, not once per document.
2. Enqueue the documentsA queue holds the per-document jobs. The queue is the throughput dial — signing workers scale horizontally behind it.
3. Render and sign one documentA disposable unit renders the document, then signs it over its own byte range at the requested PAdES level. Nothing is shared with the next document.
4. Commit on success, hold on failureA correctly-signed file commits once. A document that could not be signed is failed and retried — never emitted as unsigned bytes.
5. Checkpoint, and resume on crashA durable run records what has committed. After a crash it continues from the last checkpoint instead of re-signing the whole batch.

A high-volume signing run end to end: shared signing material is warmed once; each document is rendered and signed individually on a disposable unit; a correctly-signed result commits exactly once, while any failure is held for retry, never passed on as unsigned bytes; a crashed run resumes from its checkpoint.

Core memberi Anda kebenaran kriptografisnya: penandatanganan CMS berbasis perangkat lunak dan PAdES B-B (dengan B-T melalui klien timestamp) di mana setiap dokumen ditandatangani satu per satu dan fail-closed. Orkestrasi yang membuat sebuah jalannya proses besar menjadi durabel, konkuren, dan tepat-sekali — mesin render bebas efek samping ditambah committer, checkpoint, idempotensi, dan penyimpanan dead-letter — adalah modul Stream dalam edisi tingkat lanjut; penandatanganan berbasis perangkat keras melalui HSM atau KMS cloud juga merupakan sambungan edisi tingkat lanjut. Core membuktikan setiap tanda tangan benar; edisi tingkat lanjut membuat sejuta di antaranya dapat bertahan.

Human-factors note:Human-factors note

Pembingkaian yang jujur sama dengan yang dibuat halaman pembuatan volume tinggi tentang throughput, diterapkan pada penandatanganan: kegagalan yang harus Anda antisipasi dalam rekayasa adalah yang diam, bukan yang lantang. Pipeline penandatanganan yang melempar galat pada dokumen yang tidak dapat ia tandatangani dengan benar bukanlah “rapuh” — ia memberi tahu Anda kebenarannya pada saat yang paling murah. Pipeline yang menelan kegagalan itu dan mengirim berkas tak ditandatangani terasa lebih mulus dalam demo dan menjadi insiden di produksi. Dalam skala besar Anda tidak sempat memeriksa setiap keluaran dengan tangan, sehingga perilaku default pipeline saat gagal adalah kendali mutu Anda.

Contoh praktis

Bentuk di bawah ini adalah unit penandatanganan per dokumen di dalam sebuah loop batch. Setiap iterasi menandatangani satu dokumen pada level bernama dan entah menghasilkan hasil yang ditandatangani dengan benar atau menggagalkan satu pekerjaan itu — ia tidak pernah mengembalikan byte tak ditandatangani yang didandani sebagai sebuah hasil.

<?php

declare(strict_types=1);

use NextPDF\Contracts\DocumentFactoryInterface;
use NextPDF\Security\Signature\CertificateInfo;
use NextPDF\Security\Signature\SignatureLevel;
use NextPDF\Exception\SignatureException;
use Psr\Log\LoggerInterface;

/**
 * One signing-batch iteration: render, sign at a named level, commit or fail.
 *
 * The factory and the certificate source ($certInfo, the warmed signing
 * material) are process-lifetime singletons; the document is disposable. A
 * document that cannot be signed at the requested level fails this job loudly —
 * it is never committed unsigned.
 *
 * @param iterable<int, callable(\NextPDF\Core\Document): \NextPDF\Core\Document> $jobs
 */
function signBatch(
    DocumentFactoryInterface $factory,
    CertificateInfo $certInfo,
    LoggerInterface $logger,
    iterable $jobs,
): void {
    // The level is an explicit, ordered contract — not a flag we hope is honoured.
    $level = SignatureLevel::PAdES_B_T;

    foreach ($jobs as $jobId => $build) {
        // Fresh, disposable unit — shares the warmed signing material only.
        $doc = $factory->create();
        $doc = $build($doc);

        try {
            // Sign over this document's own byte range, at exactly $level,
            // or throw. There is no "signed lower, reported higher" path.
            $doc->setSignature(certInfo: $certInfo, level: $level);
            $signed = $doc->getPdfData();
        } catch (SignatureException $e) {
            // Fail-closed: this document does NOT continue as unsigned bytes.
            // The job is failed and left for retry / dead-letter handling.
            $logger->error('pdf.sign.failed', ['job_id' => $jobId, 'reason' => $e->getMessage()]);
            continue;
        }

        // Only a correctly-signed result reaches the commit step.
        commitSignedOutput($jobId, $signed);
        unset($doc, $signed); // release per-document state before the next iteration

        $logger->info('pdf.sign.committed', ['job_id' => $jobId, 'level' => $level->value]);
    }
}

Baris catch adalah baris yang menanggung beban. Itulah perbedaan antara jalannya proses yang menahan dokumen yang tidak dapat ia tandatangani dan jalannya proses yang tetap mengirimnya. continue tidak menutupi kegagalan — pekerjaan itu dicatat dan disisihkan untuk dicoba ulang, sehingga batch selesai dengan daftar yang diketahui dan lengkap tentang apa yang ditandatangani dan apa yang tidak, tidak pernah dengan celah yang diam.

Kesalahpahaman umum

Kesalahpahaman pertama adalah bahwa “penandatanganan batch” berarti satu tanda tangan diterapkan pada banyak berkas. Tidak demikian, dan sistem mana pun yang mengklaim demikian tidak menghasilkan tanda tangan PAdES yang valid — digest setiap dokumen terikat pada byte-nya sendiri (SpecSpec: ISO 32000-2, §12.8ISO 32000-2 §12.8). Batch murni tentang berapa banyak dan seberapa cepat, tidak pernah tentang berbagi unit kriptografis.

Yang kedua adalah bahwa konkurensi berarti mengendurkan kebenaran demi kecepatan — bahwa penandatangan yang cepat harus memotong sudut yang tidak dipotong yang cermat. Tidak demikian. Karena unit penandatanganan tidak berbagi state yang dapat berubah, menjalankannya secara paralel mengubah jadwalnya, bukan byte-nya. Setiap tanda tangan paralel dihitung dengan ketelitian yang sama seperti tanda tangan tunggal; paralelismenya ada pada orkestrasi di sekitarnya.

Yang ketiga adalah bahwa durabilitas adalah sesuatu yang Anda tempelkan setelah jalannya proses semalaman yang pertama kali gagal. Pada saat itu Anda sudah kehilangan jalannya proses tersebut. Pipeline yang dapat dilanjutkan harus mengetahui, per dokumen, apa yang di-commit dan apa yang tidak sebelum crash — yang justru itulah yang ada untuk dicatat oleh penyimpanan checkpoint dan idempotensi.

Batas dan batasan

• Setiap tanda tangan bersifat per dokumen dan terikat standar; tidak ada jalan pintas batch. Volume mengubah penjadwalan, bukan unit kriptografis. NextPDF menandatangani setiap dokumen atas rentang byte-nya sendiri.
• Core melakukan penandatanganan CMS berbasis perangkat lunak dan PAdES B-B (B-T via klien timestamp). Mesin render-dan-tanda-tangan yang durabel, konkuren, dan tepat-sekali adalah modul Stream dalam edisi tingkat lanjut; penyimpanan kunci berbasis HSM/KMS adalah sambungan edisi tingkat lanjut. Halaman ini tidak mengklaim orkestrasi itu sebagai bagian dari Core.
• Fail-closed adalah perilaku mesin, bukan jaminan tentang pengkabelan Anda. NextPDF menolak memancarkan berkas tak ditandatangani-namun-dipercaya-tertandatangani dan menampilkan rute penandatanganan yang didukung. Pipeline yang menangkap galat yang dihasilkan lalu tetap melakukan commit telah memilih untuk mengalahkan jaminan itu — pembingkaian yang justru dicegah oleh keberadaan catch/continue pada contoh.
• Level PAdES ditegakkan per dokumen, bukan disertifikasi untuk jalannya proses. Mesin menghasilkan level baseline yang diminta atau gagal; itu adalah penegakan struktural, bukan vonis konformitas pihak ketiga untuk berkas yang dihasilkan. Progresi level itu sendiri dibahas di PAdES baseline profiles.
• Antrean, penyimpanan kunci, otoritas timestamp, dan object store adalah milik Anda. NextPDF menyediakan kebenaran penandatanganan per dokumen dan, dalam edisi tingkat lanjut, primitif orkestrasi yang durabel. Ia tidak menjalankan infrastruktur Anda atau menjamin TSA Anda.

High-volume and concurrent signing — edition availability

Edition	Availability
Core	○ Per-document software CMS signing, PAdES B-B (B-T with a timestamp client), signed individually over each document’s own byte range, fail-closed against silently-unsigned output. Plain per-document signing needs no commercial tier.
Pro	○ Adds the Stream module: a side-effect-free render engine plus durable committer, checkpoint, idempotency, and dead-letter stores — concurrent, crash-safe, exactly-once batch runs that resume instead of restarting.
Enterprise	○ Adds hardware-backed key custody (HSM via PKCS#11, or a cloud KMS) so the private key never leaves the device, and the long-term PAdES levels (B-LT, B-LTA) that keep a high-volume archive verifiable for decades.

Dokumen terkait

• High-volume document generation — model batch berantrean dan bermemori terbatas yang menjadi landasan penandatanganan halaman ini; baca dulu untuk disiplin throughput dan pengukuran.
• PAdES baseline profiles — apa yang ditambahkan tiap level (B-B sampai B-LTA), agar Anda menandatangani pada level yang dibutuhkan kewajiban.
• How signatures sit in a PDF — fondasi rentang byte dan kamus yang membuat sebuah tanda tangan menjadi per dokumen.
• HSM-backed signing — tempat batas kunci privat berada ketika materi penandatanganan tinggal di perangkat keras.
• Stream (Pro) — mesin render yang durabel, konkuren, dan tepat-sekali yang mengubah satu unit penandatanganan menjadi jalannya proses yang dapat dilanjutkan.

Glosarium

• Batch signing — menandatangani banyak dokumen menurut jadwal. Sebuah konsep penjadwalan; setiap dokumen tetap ditandatangani satu per satu atas byte-nya sendiri.
• Fail-closed — saat terjadi kegagalan yang jika tidak demikian akan menghasilkan keluaran tak ditandatangani atau salah, pipeline menahan dokumen dan melaporkan, alih-alih meneruskannya sebagai byte mentah.
• Exactly-once commit — sebuah properti pipeline durabel di mana keluaran yang ditandatangani dengan benar dipublikasikan satu kali dan tidak dipancarkan ulang ketika jalannya proses yang crash dilanjutkan.
• Checkpoint — catatan durabel per dokumen tentang apa yang telah di-commit, sehingga sebuah jalannya proses dapat berlanjut dari tempat ia berhenti alih-alih menandatangani ulang segalanya.
• CMS SignedData — kontainer kriptografis untuk tanda tangan atas konten (ia dapat membawa beberapa penandatangan); pipeline ini menghasilkan satu tanda tangan PDF dari satu penandatangan per dokumen, unit per dokumen yang dihasilkan sebuah batch.
• PAdES — PDF Advanced Electronic Signatures, keluarga profil ETSI EN 319 142 untuk penandatanganan PDF; level baseline-nya berkisar dari B-B sampai B-LTA.