Panduan cepat NextPDF Enterprise

Sekilas pandang

Tutorial ini membawa Anda dari proyek kosong menuju dua hasil Enterprise yang berfungsi. Pertama Anda memverifikasi PDF bertanda tangan yang sudah ada dan membaca MainIndication-nya. Kemudian Anda menaikkan dokumen bertanda tangan ke PAdES B-LT dengan producer jangka-panjang. Setiap langkah menampilkan output atau exception persis yang harus Anda harapkan. NextPDF mendokumentasikan kapabilitas, bukan sertifikasi: NextPDF tidak memegang sertifikasi PAdES maupun eIDAS dan tidak memberikan satu pun.

Kapabilitas ini dikirimkan dalam NextPDF Enterprise (nextpdf/enterprise) dan diaktifkan dengan envelope lisensi tingkat Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Prasyarat

• Composer telah dikonfigurasi untuk private repository NextPDF. Ikuti Instal dan autentikasi terlebih dahulu.
• Anda memiliki envelope lisensi Enterprise, diunduh dari akun Anda di app.getnextpdf.com. Lisensi dan aktivasi menjelaskan apa itu envelope dan ke mana ia diletakkan.
• Untuk langkah 3 Anda memerlukan PDF bertanda tangan untuk diverifikasi. Untuk bagian B-LT Anda juga memerlukan sertifikat penanda tangan Anda dan akses jaringan ke responder OCSP/CRL.

1. Instal dan aktifkan

Require paket Enterprise. Paket ini bergantung pada nextpdf/core dan nextpdf/pro, sehingga Composer membawa seluruh stack:

composer require nextpdf/enterprise
composer show nextpdf/enterprise

Jika composer show mencetak paket dan versinya, instalasi berhasil. Sekarang letakkan envelope lisensi yang telah ditandatangani di tempat deployment Anda memuatnya, persis seperti yang dijelaskan Lisensi dan aktivasi. Menginstal paket saja tidak memberikan kapabilitas Enterprise; lisensi yang diaktifkan menentukan edisinya.

2. Verifikasi entitlement Anda

Tanyakan pada entitlement evaluator apa yang diberikan lisensi Anda. Bootstrap Anda memperoleh NextPDF\Enterprise\Licensing\LicenseKey yang terverifikasi saat aktivasi; teruskan objek itu:

<?php
require __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Licensing\EntitlementEvaluator;
use NextPDF\Enterprise\Licensing\LicenseKey;

/** @var LicenseKey|null $license The verified license from activation. */
$result = (new EntitlementEvaluator())->evaluate($license);

echo 'status:  ' . $result->status->value . PHP_EOL;
echo 'edition: ' . ($result->edition?->value ?? 'none') . PHP_EOL;
echo 'runtime: ' . ($result->runtimeAllowed ? 'allowed' : 'disabled') . PHP_EOL;

Dengan lisensi Enterprise yang aktif Anda melihat:

status:  active
edition: enterprise
runtime: allowed

Metode di balik langkah ini:

public function evaluate(?LicenseKey $license, ?DateTimeImmutable $now = null): EntitlementResult

Melempar atau gagal dengan: metode ini tidak pernah melempar. Lisensi yang hilang mengembalikan EntitlementResult yang fail-closed dengan EntitlementStatus::NoLicense dan runtimeAllowed bernilai false (lihat langkah 4).

3. Hasil pertama

Verifikasi PDF bertanda tangan yang sudah ada

Ekstrak tanda tangan dari PDF bertanda tangan, lalu jalankan validasi AdES dasar. Engine ini mengimplementasikan tingkat validasi ETSI EN 319 102-1; validateBasic() adalah alur klausa 5.2 — struktur, digest, kripto tanda tangan, dan rantai sertifikat:

<?php
require __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Security\Validation\AdESValidationEngine;
use NextPDF\Enterprise\Security\Validation\CmsSignatureDataExtractor;
use NextPDF\Enterprise\Signature\SignatureExtractor;

$pdf = file_get_contents(__DIR__ . '/contract-signed.pdf');
if ($pdf === false) {
    throw new RuntimeException('Could not read contract-signed.pdf');
}

$signatures = (new SignatureExtractor())->extract($pdf);
if ($signatures === []) {
    throw new RuntimeException('The PDF carries no signature dictionary.');
}

$engine = new AdESValidationEngine(extractor: new CmsSignatureDataExtractor());
$report = $engine->validateBasic(
    $signatures[0]['signedBytes'],  // the exact /ByteRange-covered bytes
    $signatures[0]['contents'],     // the DER CMS SignedData from /Contents
);

echo $report->mainIndication->name . PHP_EOL;
echo ($report->subIndication?->name ?? '(none)') . PHP_EOL;

Untuk tanda tangan yang berbentuk baik dan lolos pemeriksaan struktural, digest, kriptografis, dan rantai dasar yang dikonfigurasi dalam contoh ini, Anda melihat:

TOTAL_PASSED
(none)

MainIndication memiliki tepat tiga kasus: TOTAL_PASSED, TOTAL_FAILED, dan INDETERMINATE. Engine ini fail-closed: pemeriksaan yang tidak dapat ia tetapkan secara positif menghasilkan INDETERMINATE, tidak pernah lolos secara diam-diam. Lolos di sini adalah hasil validasi di bawah pemeriksaan engine ini, bukan pernyataan kepercayaan atau sertifikasi — trust anchor dan bukti jangka-panjang termasuk dalam tingkat yang lebih dalam pada halaman verifikasi.

public function extract(string $pdfData): array

Melempar atau gagal dengan: InvalidArgumentException jika input bukan PDF yang valid. /ByteRange atau /Contents yang cacat menghasilkan string kosong (fail-closed), tidak pernah hasil positif.

public function validateBasic(string $signedData, string $signature): ValidationReport

Melempar atau gagal dengan: metode ini tidak pernah melempar pada kegagalan verifikasi. Setiap cacat dipetakan ke sebuah indikasi ValidationReport, mis. HASH_FAILURE atau SIG_CRYPTO_FAILURE.

Menghasilkan PAdES B-LT

Sekarang tingkatkan dokumen yang baru ditandatangani ke B-LT. Producer jangka-panjang mengumpulkan rantai sertifikat ditambah bukti OCSP/CRL dan menulis Document Security Store (DSS). Producer ini melanjutkan pass penandatanganan yang dijelaskan pada halaman Signature, yang memberi Anda buffer output, object registry, dan hex /Contents tanda tangan:

use NextPDF\Enterprise\Security\Ltv\LtvManager;
use NextPDF\Security\Signature\CertificateInfo;
use NextPDF\Security\Signature\SignatureLevel;

$certInfo = CertificateInfo::fromPkcs12('/secure/signer.p12', $p12Password);

// $httpClient is any PSR-18 client; it fetches OCSP responses and CRLs.
$ltv = new LtvManager($certInfo, $httpClient, level: SignatureLevel::PAdES_B_LT);

// $buffer, $registry, and $signatureContentsHex come from the signing pass.
$dssObjectNumber = $ltv->enableLtv($buffer, $registry, $signatureContentsHex);

Nilai kembalian adalah nomor objek DSS untuk entri /DSS katalog dokumen. Producer secara default menggunakan penegakan pencabutan strict: materi pencabutan yang hilang memunculkan exception alih-alih diam-diam mengeluarkan file “B-LT” yang kosong.

public function enableLtv(BinaryBuffer $buffer, ObjectRegistry $registry, string $signatureContentsHex): int

Melempar atau gagal dengan: NextPDF\Enterprise\Security\Ltv\LtvException ketika validasi rantai gagal, ketika sertifikat dicabut, atau ketika materi pencabutan hilang di bawah default strict.

4. Ketika sesuatu gagal

status: no_license — envelope tidak dimuat

Langkah 2 mencetak status: no_license dan runtime: disabled, dan hasilnya membawa peringatan No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. Panggilan yang di-gate oleh entitlement lalu melempar NextPDF\Accelerator\Exception\SpectrumAuthenticationException dengan kode SPEC-LIC-001, mis. Capability '...' requires a valid license. Perbaikan: letakkan dan aktifkan envelope sesuai Lisensi dan aktivasi, lalu jalankan ulang langkah 2.

InvalidArgumentException: Input does not start with %PDF header

SignatureExtractor::extract() menerima sesuatu yang bukan PDF — jalur yang salah, pembacaan kosong, atau unduhan terkompresi. Periksa file yang Anda muat. Daftar $signatures yang kosong berbeda: file tersebut adalah PDF, tetapi tidak membawa dictionary /Type /Sig, sehingga tidak ada yang dapat diverifikasi.

LtvException: Strict revocation: LTV warning: no revocation data for certificate at chain position 0

enableLtv() tidak dapat memperoleh respons OCSP atau CRL untuk sertifikat rantai, dan default strict menolak menulis klaim B-LT tanpa bukti. Periksa keterjangkauan responder dari host, atau teruskan enforcementMode: RevocationEnforcementMode::PERMISSIVE hanya jika Anda secara eksplisit menerima proses warn-only — jangan pernah melabeli output semacam itu sebagai B-LT untuk alur kerja produksi atau kepatuhan kecuali bukti pencabutan yang hilang diterima dan didokumentasikan secara eksplisit. Terkait: meminta B-LTA tanpa TSA client gagal dengan LtvException: TSA client required for document timestamps.

Ke mana selanjutnya

• Signature: PAdES B-LT / B-LTA, DSS, document timestamps — perilaku producer selengkapnya, aturan pengurutan, dan loop arsip.
• Verifikasi tanda tangan — validasi berbasis-waktu dan jangka-panjang, trust anchor, rantai arsip.
• Lisensi — NextPDF Enterprise — status entitlement, grace, gating kapabilitas.
• Indeks modul NextPDF Enterprise — segala hal lain yang dikirimkan edisi ini.