เริ่มต้นใช้งาน NextPDF Enterprise อย่างรวดเร็ว

ภาพรวมโดยย่อ

บทช่วยสอนนี้จะพาคุณจากโปรเจกต์เปล่าไปสู่ผลลัพธ์ Enterprise ที่ใช้งานได้สองอย่าง ขั้นแรกคุณตรวจสอบ PDF ที่ลงนามแล้วและอ่านค่า MainIndication ของมัน จากนั้นคุณยกระดับเอกสารที่ลงนามแล้วให้เป็น PAdES B-LT ด้วยตัวสร้างระยะยาว ทุกขั้นตอนจะแสดงผลลัพธ์หรือ exception ที่คุณควรคาดหวังอย่างชัดเจน NextPDF บันทึกความสามารถไว้เป็นเอกสาร ไม่ใช่การรับรอง โดยไม่ถือครองการรับรอง PAdES หรือ eIDAS ใดๆ และไม่มอบการรับรองใดๆ

ความสามารถนี้มาพร้อมกับ NextPDF Enterprise (nextpdf/enterprise) และเปิดใช้งานด้วยซองใบอนุญาตระดับ Enterprise การนำไปใช้งานที่ไม่มีสิทธิ์นั้นจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและรับใบอนุญาต

สิ่งที่ต้องมีก่อน

• Composer ถูกกำหนดค่าไว้สำหรับ private repository ของ NextPDF ให้ทำตาม ติดตั้งและยืนยันตัวตน ก่อน
• คุณมี ซองใบอนุญาต Enterprise ที่ดาวน์โหลดจากบัญชีของคุณที่ app.getnextpdf.com การออกใบอนุญาตและการเปิดใช้งาน จะอธิบายว่าซองคืออะไรและวางไว้ที่ใด
• สำหรับขั้นตอนที่ 3 คุณต้องมี PDF ที่ลงนามแล้วสำหรับตรวจสอบ สำหรับส่วน B-LT คุณยังต้องมีใบรับรองผู้ลงนามและการเข้าถึงเครือข่ายไปยัง responder ของ OCSP/CRL

1. ติดตั้งและเปิดใช้งาน

เรียกใช้แพ็กเกจ Enterprise มันขึ้นอยู่กับ nextpdf/core และ nextpdf/pro ดังนั้น Composer จะดึงทั้งสแตกมาให้:

composer require nextpdf/enterprise
composer show nextpdf/enterprise

ถ้า composer show แสดงแพ็กเกจและเวอร์ชันของมัน แสดงว่าการติดตั้งสำเร็จ ตอนนี้ให้วางซองใบอนุญาตที่ลงนามแล้วในตำแหน่งที่การนำไปใช้งานของคุณโหลดมัน ตรงตามที่ การออกใบอนุญาตและการเปิดใช้งาน อธิบายไว้ การติดตั้งแพ็กเกจเพียงอย่างเดียวไม่ได้มอบความสามารถ Enterprise ใบอนุญาตที่เปิดใช้งานแล้วต่างหากที่เลือกรุ่น

2. ยืนยันสิทธิ์การใช้งานของคุณ

ถามตัวประเมินสิทธิ์ว่าใบอนุญาตของคุณมอบอะไรบ้าง กระบวนการ bootstrap ของคุณจะได้รับ NextPDF\Enterprise\Licensing\LicenseKey ที่ตรวจสอบแล้วระหว่างการเปิดใช้งาน ให้ส่งค่านั้นเข้าไป:

<?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;

ด้วยใบอนุญาต Enterprise ที่ใช้งานอยู่ คุณจะเห็น:

status:  active
edition: enterprise
runtime: allowed

เมธอดที่อยู่เบื้องหลังขั้นตอนนี้:

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

throw หรือ fail ด้วย: มันไม่เคย throw ใบอนุญาตที่ขาดหายไปจะคืนค่า EntitlementResult แบบ fail-closed พร้อม EntitlementStatus::NoLicense และ runtimeAllowed เป็น false (ดูขั้นตอนที่ 4)

3. ผลลัพธ์แรก

ตรวจสอบ PDF ที่ลงนามแล้ว

ดึงลายเซ็นออกจาก PDF ที่ลงนามแล้ว จากนั้นรันการตรวจสอบ AdES พื้นฐาน เอนจินนี้ใช้ระดับการตรวจสอบของ ETSI EN 319 102-1 โดย validateBasic() คือกระบวนการตามข้อ 5.2 ได้แก่ โครงสร้าง ไดเจสต์ การเข้ารหัสของลายเซ็น และห่วงโซ่ใบรับรอง:

<?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;

สำหรับลายเซ็นที่มีรูปแบบถูกต้องซึ่งผ่านการตรวจสอบโครงสร้าง ไดเจสต์ การเข้ารหัส และห่วงโซ่พื้นฐานที่กำหนดค่าไว้ในตัวอย่างนี้ คุณจะเห็น:

TOTAL_PASSED
(none)

MainIndication มีเพียงสามกรณีเท่านั้น ได้แก่ TOTAL_PASSED, TOTAL_FAILED และ INDETERMINATE เอนจินนี้เป็นแบบ fail-closed การตรวจสอบที่ไม่สามารถยืนยันได้ในเชิงบวกจะให้ผลเป็น INDETERMINATE ไม่ใช่การผ่านแบบเงียบๆ การผ่านในที่นี้คือผลลัพธ์การตรวจสอบภายใต้การตรวจสอบของเอนจินนี้ ไม่ใช่คำแถลงเรื่องความน่าเชื่อถือหรือการรับรอง จุดยึดความน่าเชื่อถือและหลักฐานระยะยาวเป็นของระดับที่ลึกกว่าใน หน้าการยืนยัน

public function extract(string $pdfData): array

throw หรือ fail ด้วย: InvalidArgumentException ถ้าอินพุตไม่ใช่ PDF ที่ถูกต้อง /ByteRange หรือ /Contents ที่มีรูปแบบผิดจะให้ผลเป็นสตริงว่าง (fail-closed) ไม่ใช่ผลลัพธ์เชิงบวก

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

throw หรือ fail ด้วย: มันไม่เคย throw เมื่อการยืนยันล้มเหลว ทุกข้อบกพร่องจะแมปไปยัง indication ของ ValidationReport เช่น HASH_FAILURE หรือ SIG_CRYPTO_FAILURE

สร้าง PAdES B-LT

ตอนนี้ให้ยกระดับเอกสารที่เพิ่งลงนามใหม่ให้เป็น B-LT ตัวสร้างระยะยาวจะรวบรวมห่วงโซ่ใบรับรองพร้อมหลักฐาน OCSP/CRL แล้วเขียน Document Security Store (DSS) มันต่อเนื่องจากกระบวนการลงนามที่อธิบายไว้ใน หน้าลายเซ็น ซึ่งให้บัฟเฟอร์เอาต์พุต รีจิสทรีอ็อบเจกต์ และค่าเลขฐานสิบหกของ /Contents ของลายเซ็นแก่คุณ:

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);

ค่าที่คืนกลับมาคือหมายเลขอ็อบเจกต์ DSS สำหรับรายการ /DSS ของแคตตาล็อกเอกสาร ตัวสร้างมีค่าเริ่มต้นเป็นการบังคับใช้การเพิกถอนแบบ strict วัสดุการเพิกถอนที่ขาดหายไปจะทำให้เกิด exception แทนที่จะปล่อยไฟล์ “B-LT” ที่กลวงเปล่าออกมาอย่างเงียบๆ

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

throw หรือ fail ด้วย: NextPDF\Enterprise\Security\Ltv\LtvException เมื่อการตรวจสอบห่วงโซ่ล้มเหลว เมื่อใบรับรองถูกเพิกถอน หรือเมื่อวัสดุการเพิกถอนขาดหายไปภายใต้ค่าเริ่มต้นแบบ strict

4. เมื่อบางอย่างล้มเหลว

status: no_license — ซองยังไม่ได้ถูกโหลด

ขั้นตอนที่ 2 แสดง status: no_license และ runtime: disabled และผลลัพธ์มีคำเตือน No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing การเรียกที่มีการกั้นด้วยสิทธิ์จะ throw NextPDF\Accelerator\Exception\SpectrumAuthenticationException พร้อมโค้ด SPEC-LIC-001 เช่น Capability '...' requires a valid license. วิธีแก้: วางและเปิดใช้งานซองตาม การออกใบอนุญาตและการเปิดใช้งาน แล้วรันขั้นตอนที่ 2 อีกครั้ง

InvalidArgumentException: Input does not start with %PDF header

SignatureExtractor::extract() ได้รับบางอย่างที่ไม่ใช่ PDF ไม่ว่าจะเป็นพาธที่ผิด การอ่านที่ว่างเปล่า หรือไฟล์ดาวน์โหลดที่ถูกบีบอัด ให้ตรวจสอบไฟล์ที่คุณโหลด รายการ $signatures ที่ว่างเปล่านั้นแตกต่างออกไป กล่าวคือ ไฟล์เป็น PDF แต่ไม่มี dictionary /Type /Sig จึงไม่มีอะไรให้ตรวจสอบ

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

enableLtv() ไม่สามารถรับ OCSP response หรือ CRL สำหรับใบรับรองในห่วงโซ่ได้ และค่าเริ่มต้นแบบ strict ปฏิเสธที่จะเขียนคำอ้าง B-LT โดยไม่มีหลักฐาน ให้ตรวจสอบว่า responder เข้าถึงได้จากโฮสต์หรือไม่ หรือส่ง enforcementMode: RevocationEnforcementMode::PERMISSIVE เฉพาะเมื่อคุณยอมรับการรันแบบเตือนอย่างเดียวอย่างชัดเจนเท่านั้น อย่าติดป้ายเอาต์พุตเช่นนั้นว่าเป็น B-LT สำหรับเวิร์กโฟลว์การผลิตหรือการปฏิบัติตามข้อกำหนด เว้นแต่จะยอมรับและบันทึกหลักฐานการเพิกถอนที่ขาดหายไปอย่างชัดเจน ที่เกี่ยวข้อง: การร้องขอ B-LTA โดยไม่มี TSA client จะล้มเหลวด้วย LtvException: TSA client required for document timestamps

จะไปที่ใดต่อ

• ลายเซ็น: PAdES B-LT / B-LTA, DSS, การประทับเวลาเอกสาร — พฤติกรรมของตัวสร้างทั้งหมด กฎการจัดลำดับ และลูปการเก็บถาวร
• การยืนยันลายเซ็น — การตรวจสอบตามเวลาและระยะยาว จุดยึดความน่าเชื่อถือ ห่วงโซ่การเก็บถาวร
• การออกใบอนุญาต — NextPDF Enterprise — สถานะสิทธิ์ ระยะผ่อนผัน การกั้นความสามารถ
• ดัชนีโมดูล NextPDF Enterprise — ทุกอย่างที่เหลือที่รุ่นนี้มีมาให้