Pemetaan baseline PAdES

Sekilas pandang

PDF Advanced Electronic Signatures (PAdES) adalah keluarga profil yang distandarkan dalam ETSI EN 319 142. Standar ini mendefinisikan empat level konformansi baseline — B-B, B-T, B-LT, dan B-LTA — dan setiap level yang lebih tinggi menambahkan materi pada level di bawahnya. Halaman ini memetakan level-level tersebut ke keluaran yang dihasilkan NextPDF. Halaman ini juga memisahkan permukaan Core dari edisi Pro dan Enterprise. Pemetaan ini bersifat perilaku: pemetaan menggambarkan apa yang dipancarkan mesin, bukan kelas internal.

Ringkasnya: NextPDF Core menghasilkan struktur tanda tangan yang selaras dengan B-B dan B-T. Jalur produsen B-LT dan B-LTA disertakan dalam edisi Pro dan Enterprise. Apakah tanda tangan yang dihasilkan diterima sebagai konforman pada level tertentu bergantung pada verifikator dan trust anchor yang dikonfigurasikannya. Produsen tidak dapat menyatakan konformansi atas nama verifikator.

Instalasi

composer require nextpdf/core:^3

Gambaran umum konseptual

Tanda tangan digital PDF adalah struktur Cryptographic Message Syntax (CMS) SignedData yang disimpan dalam entri Contents pada kamus tanda tangan. Larik ByteRange menyebutkan rentang byte yang dicakup oleh digest — ISO 32000-2 §12.8.1. CMS SignerInfo membawa atribut yang ditandatangani, termasuk atribut content-type dan message-digest — RFC 5652 §5.3. Message digest atas atribut-atribut tersebut dihitung melalui proses §5.4. PAdES menggunakan model atribut CMS Advanced Electronic Signatures (CAdES) di dalam kamus tanda tangan PDF.

Keempat level baseline bersifat aditif:

• B-B memuat tanda tangan dasar beserta atribut wajib yang ditandatangani.
• B-T menambahkan atribut time-stamp tanda tangan yang dihitung atas nilai tanda tangan. Atribut time-stamp membuktikan bahwa tanda tangan sudah ada pada saat penandaan waktu — ETSI PAdES §5.4.3. Time-Stamping Authority RFC 3161 menghasilkan token tersebut — RFC 3161 §2.4.1.
• B-LT menambahkan materi validasi jangka panjang — data sertifikat, Online Certificate Status Protocol (OCSP), dan certificate revocation list (CRL) — yang ditempatkan dalam Document Security Store — ETSI PAdES §6.2.2, ISO 32000-2 §12.8.4.3, serta penempatan data validasi yang dijelaskan dalam ETSI EN 319 142-2 §6.3.
• B-LTA menambahkan time-stamp dokumen arsip untuk mempertahankan validitas dalam jangka waktu panjang — ETSI PAdES §6.2.2.

Keempat level bersifat aditif secara ketat — setiap level yang lebih tinggi mempertahankan semua yang dibawa level di bawahnya dan menambahkan tepat satu lapisan materi baru. Label transisi menunjukkan edisi produsen yang menyertakan tiap langkah.

Diagram

Permukaan API

Gunakan enum SignatureLevel untuk memilih sebuah level. Enum ini mendefinisikan case PAdES_B_B, PAdES_B_T, PAdES_B_LT, dan PAdES_B_LTA. Metode requiresTimestamp(), requiresDss(), requiresDocumentTimestamp(), dan isAvailableInEnvironment() melaporkan persyaratan setiap level dan apakah runtime saat ini dapat memenuhinya. Dalam distribusi Core, isAvailableInEnvironment() mengembalikan true untuk B-B dan B-T, serta false untuk B-LT dan B-LTA. Metode ini mengembalikan false untuk B-LT dan B-LTA karena produsen validasi jangka panjang di-resolve pada saat runtime dan bukan bagian dari paket open-source. Kode produksi sebaiknya menggunakan kontrak SignerInterface, bukan tipe internal ini.

Matriks dukungan level

Level	Apa yang ditambahkan	Core (nextpdf/core)	Pro / Enterprise
B-B	Tanda tangan dasar dengan atribut wajib yang ditandatangani	Menghasilkan struktur yang selaras; diuji terhadap golden baseline sintetis	Permukaan yang sama
B-T	Time-stamp tanda tangan atas nilai tanda tangan	Menghasilkan struktur yang selaras ketika layanan timestamp RFC 3161 disediakan	Permukaan yang sama
B-LT	Data validasi dalam Document Security Store	Produsen tidak disertakan dalam Core; memilih B-LT tanpa paket Enterprise akan gagal tertutup	Produsen disertakan
B-LTA	Time-stamp dokumen arsip	Produsen tidak disertakan dalam Core; gagal tertutup seperti di atas	Produsen disertakan

“Menghasilkan struktur yang selaras” berarti NextPDF memancarkan tanda tangan yang strukturnya mengikuti klausa yang dikutip. Artefak tests/Corpus/pades/ dan tests/Golden/baselines/ milik proyek menguji struktur tersebut. Ini tidak berarti validator eksternal menyertifikasi keluarannya pada level tersebut. Lihat bagian konformansi.

Contoh kode — Mulai cepat

examples/contracts/signing-quickstart.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\SignerInterface;

/**
 * Sign a byte range with any SignerInterface implementation.
 *
 * @param SignerInterface $signer    A Core or Premium signer.
 * @param string          $byteRange The PDF byte range to sign.
 *
 * @return string Hex-encoded CMS SignedData for the PDF /Contents field.
 */
function signByteRange(SignerInterface $signer, string $byteRange): string
{
    return $signer->sign($byteRange)->toHex();
}

Fungsi ini bergantung pada kontrak SignerInterface, bukan pada kelas konkret. Baik penanda tangan perangkat lunak Core (B-B atau B-T) maupun penanda tangan hardware security module (HSM) Premium memenuhinya. Kode pemanggil tidak berubah ketika edisinya berganti.

Contoh kode — Produksi

examples/contracts/signing-level.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Security\Signature\SignatureLevel;

/**
 * Resolve the highest baseline level the current runtime can produce.
 *
 * B-B and B-T are produced by the Core distribution. B-LT and B-LTA
 * require the Enterprise long-term-validation package; without it the
 * level reports unavailable so callers fail closed rather than emit a
 * structure that does not carry the validation material the level names.
 *
 * @return SignatureLevel The highest level available in this runtime.
 */
function highestAvailableLevel(): SignatureLevel
{
    foreach ([
        SignatureLevel::PAdES_B_LTA,
        SignatureLevel::PAdES_B_LT,
        SignatureLevel::PAdES_B_T,
        SignatureLevel::PAdES_B_B,
    ] as $level) {
        if ($level->isAvailableInEnvironment()) {
            return $level;
        }
    }

    return SignatureLevel::PAdES_B_B;
}

isAvailableInEnvironment() mengembalikan true untuk B-B dan B-T tanpa paket tambahan. Metode ini mengembalikan true untuk B-LT dan B-LTA hanya ketika paket validasi jangka panjang Enterprise terpasang. Jika Anda memilih level yang tidak tersedia tanpa memilih degradasi, NextPDF memunculkan eksepsi unreachable-level bertipe yang pesannya menyebutkan paket yang hilang. Karena itu, deployment yang salah konfigurasi gagal tertutup, bukan diam-diam memancarkan level yang lebih rendah daripada yang diminta pemanggil.

Kasus tepi & jebakan

• Tanda tangan yang secara struktural B-T tidak sama dengan tanda tangan yang divalidasi sebagai B-T. Validasi berjalan di verifikator dengan trust anchor milik verifikator tersebut dan kesegaran data pencabutan. Produsen tidak dapat menyatakan hasilnya.
• PAdES B-LT dan B-LTA memerlukan paket NextPDF Enterprise (nextpdf/enterprise). Jika tidak terpasang, penanda tangan gagal tertutup dan B-LT/B-LTA tidak tersedia. Core menyediakan B-B/B-T melalui NextPDF\Contracts\SignerInterface publik; validasi jangka panjang tetap berada di balik LtvManagerInterface. Memilih level yang tidak tersedia di Core secara default akan gagal tertutup. Eksepsi bertipe tersebut menyebutkan paket publik yang hilang, bukan tipe internal. Degradasi mulus ke level yang lebih rendah bersifat opt-in, dan tidak pernah menjadi default.
• Digest byte-range harus mengecualikan nilai tanda tangan. Jika digest juga mencakup oktet Contents, verifikasi tidak akan pernah berhasil — ISO 32000-2 §12.8.1.
• Pada B-T, time-stamp tanda tangan berlaku atas nilai tanda tangan, bukan atas byte dokumen. Pada B-LTA, time-stamp arsip adalah time-stamp dokumen yang terpisah. Keduanya tidak dapat dipertukarkan — ETSI PAdES §5.4.3 dan §6.2.2.
• ETSI EN 319 142-1 (bagian level baseline) tidak ada dalam korpus bukti proyek ini. Klaim struktur level di sini berdasar pada ETSI EN 319 142-2, dokumen profil pades, ISO 32000-2 §12.8, dan RFC 5652 / RFC 3161. Nama level dan struktur aditif dinyatakan sebagaimana diimplementasikan dalam v3.x. Halaman ini tidak mengklaim hasil uji konformansi atau atestasi pihak ketiga.

Kinerja

Biaya bertambah seiring naiknya level. B-B adalah satu operasi penandatanganan dan memakan waktu milidetik berdigit tunggal untuk kunci perangkat lunak. B-T menambahkan satu round trip jaringan ke Time-Stamping Authority. B-LT menambahkan satu pengambilan data pencabutan per sertifikat dalam rantai. B-LTA menambahkan satu time-stamp dokumen lagi. Anggaran wall 1500 ms mencakup satu tanda tangan B-T dengan Time-Stamping Authority (TSA) jarak jauh pada koneksi yang hangat. B-LT atau B-LTA terhadap endpoint pencabutan yang lambat akan melampaui anggaran itu dan sebaiknya berada di luar jalur permintaan. Profil reproduktibilitasnya adalah structural, bukan bitwise. Time-stamp menyematkan momen penandatanganan, sehingga dua eksekusi berbeda pada byte time-stamp, sementara struktur dokumen tetap identik.

Catatan keamanan

Level yang diklaim sebuah tanda tangan dan level ketika tanda tangan itu divalidasi adalah fakta yang berbeda. Halaman ini hanya menjelaskan permukaan produsen. Validasi jangka panjang bergantung pada data validasi yang dikumpulkan saat penandatanganan dan pada verifikator yang mempercayai anchor yang sama di kemudian hari. Produsen tidak dapat menjamin kedua fakta tersebut. Kepercayaan terhadap time-stamp bermuara pada kepercayaan terhadap Time-Stamping Authority, yang ditetapkan deployment melalui penyedia yang dapat diinjeksikan. Halaman ini ditandai export_control_class: legal-review-required karena berkaitan dengan profil tanda tangan kriptografis. Semua sumber normatif diparafrasekan, dan tidak ada yang direproduksi, sesuai dengan higiene sitasi.

Konformansi

Klaim	Standar	Klausa	Bukti
Nilai tanda tangan disimpan dengan encoding DER sebagai CMS SignedData atau TimeStampToken dalam entri Contents pada kamus tanda tangan.	ISO 32000-2	§12.8.1
Digest dihitung atas rentang ByteRange dan mengecualikan nilai tanda tangan.	ISO 32000-2	§12.8.1
Atribut time-stamp tanda tangan dihitung atas nilai tanda tangan (B-T).	ETSI PAdES (EN 319 142)	§5.4.3
Materi validasi jangka panjang dibawa dalam Document Security Store (B-LT).	ETSI PAdES (EN 319 142) / ISO 32000-2	§6.2.2 / §12.8.4.3	,
Data validasi ditempatkan dalam kamus DSS dan VRI.	ETSI EN 319 142-2	§6.3	,
Time-stamp dokumen arsip mempertahankan validitas dalam jangka waktu panjang (B-LTA).	ETSI PAdES (EN 319 142)	§6.2.2
SignerInfo membawa atribut yang ditandatangani content-type dan message-digest.	RFC 5652	§5.3
Message digest dihitung atas atribut yang ditandatangani dan ber-encoding DER (proses §5.4).	RFC 5652	§5.4
Time-stamp diminta dari TSA RFC 3161 dan mengembalikan struktur TSTInfo.	RFC 3161	§2.4.1

Semua klausa diparafrasekan. NextPDF tidak mereproduksi teks normatif. Rujuk standar yang diterbitkan untuk rumusan otoritatifnya. ETSI EN 319 142-1 tidak ada dalam korpus bukti. Klaim struktural mengenai level baseline berdasar pada sumber di atas dan dinyatakan sebagaimana diimplementasikan dalam v3.x.

Konteks komersial

Core menghasilkan struktur tanda tangan B-B dan B-T. Jalur produsen B-LT dan B-LTA, kustodi kunci HSM dan PKCS#11, serta profil kebijakan kripto FIPS 140-3 disertakan dalam edisi Pro dan Enterprise. Core me-resolve produsen validasi jangka panjang pada saat runtime, sehingga mesin open-source tidak membawa dependensi komersial. API SignerInterface tidak berubah saat pemutakhiran.

Lihat juga

• Security / Signing — permukaan implementasi CMS, timestamp, long-term validation (LTV), rantai kepercayaan, dan pencabutan.
• Contracts / Signing — service provider interface (SPI) SignerInterface dan tingkat stabilitas.
• Security — permukaan implementasi enkripsi dan tanda tangan.
• Conformance — penegakan PDF/A dan profil yang dipasangkan dengan pengarsipan bertanda tangan.
• PAdES · PAdES B-T · DSS · CAdES — istilah glosarium.