Bắt đầu nhanh với NextPDF Enterprise

Tổng quan nhanh

Hướng dẫn này đưa bạn từ một dự án trống đến hai kết quả Enterprise hoạt động được. Trước tiên bạn xác minh một PDF đã ký sẵn và đọc MainIndication của nó. Sau đó bạn nâng một tài liệu đã ký lên PAdES B-LT bằng bộ tạo dài hạn. Mỗi bước đều cho thấy chính xác kết quả hoặc ngoại lệ bạn nên mong đợi. NextPDF tài liệu hóa năng lực, không phải chứng nhận: nó không nắm giữ chứng nhận PAdES hay eIDAS nào và cũng không cấp chứng nhận nào.

Năng lực này được cung cấp trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt bằng gói giấy phép cấp Enterprise. Một triển khai không có quyền sử dụng đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và nhận giấy phép.

Điều kiện tiên quyết

• Composer đã được cấu hình cho kho lưu trữ NextPDF riêng tư. Trước tiên hãy làm theo Cài đặt và xác thực.
• Bạn có gói giấy phép Enterprise, tải về từ tài khoản tại app.getnextpdf.com. Cấp phép và kích hoạt giải thích gói giấy phép là gì và nó nằm ở đâu.
• Với bước 3 bạn cần một PDF đã ký để xác minh. Với phần B-LT bạn còn cần chứng thư số của người ký và quyền truy cập mạng đến các responder OCSP/CRL.

1. Cài đặt và kích hoạt

Yêu cầu gói Enterprise. Nó phụ thuộc vào nextpdf/core và nextpdf/pro, nên Composer sẽ kéo về toàn bộ ngăn xếp:

composer require nextpdf/enterprise
composer show nextpdf/enterprise

Nếu composer show in ra gói và phiên bản của nó, tức là quá trình cài đặt đã thành công. Bây giờ hãy đặt gói giấy phép đã ký vào nơi mà triển khai của bạn nạp nó, đúng như Cấp phép và kích hoạt mô tả. Chỉ cài gói không cấp năng lực Enterprise; giấy phép đã kích hoạt mới là thứ chọn phiên bản.

2. Xác minh quyền sử dụng của bạn

Hãy hỏi bộ đánh giá quyền sử dụng xem giấy phép của bạn cấp những gì. Quá trình khởi tạo (bootstrap) của bạn thu được NextPDF\Enterprise\Licensing\LicenseKey đã xác minh trong lúc kích hoạt; hãy truyền nó vào:

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

Với một giấy phép Enterprise đang hoạt động bạn sẽ thấy:

status:  active
edition: enterprise
runtime: allowed

Phương thức đứng sau bước này:

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

Ném ngoại lệ hoặc thất bại với: nó không bao giờ ném ngoại lệ. Một giấy phép bị thiếu sẽ trả về một EntitlementResult theo cơ chế fail-closed với EntitlementStatus::NoLicense và runtimeAllowed là false (xem bước 4).

3. Kết quả đầu tiên

Xác minh một PDF đã ký sẵn

Trích xuất chữ ký từ một PDF đã ký, rồi chạy kiểm định AdES cơ bản. Công cụ này hiện thực các mức kiểm định của ETSI EN 319 102-1; validateBasic() là luồng theo điều khoản 5.2 — cấu trúc, digest, mã hóa chữ ký, và chuỗi chứng thư số:

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

Với một chữ ký được định dạng chuẩn vượt qua các kiểm tra cơ bản về cấu trúc, digest, mã hóa và chuỗi được cấu hình trong ví dụ này, bạn sẽ thấy:

TOTAL_PASSED
(none)

MainIndication có đúng ba trường hợp: TOTAL_PASSED, TOTAL_FAILED, và INDETERMINATE. Công cụ hoạt động theo cơ chế fail-closed: một kiểm tra mà nó không thể xác lập một cách khẳng định sẽ cho ra INDETERMINATE, chứ không bao giờ âm thầm cho qua. Một kết quả đạt ở đây là một kết quả kiểm định dưới các kiểm tra của công cụ này, không phải là một tuyên bố về sự tin cậy hay chứng nhận — các neo tin cậy (trust anchor) và bằng chứng dài hạn thuộc về các mức sâu hơn trên trang xác minh.

public function extract(string $pdfData): array

Ném ngoại lệ hoặc thất bại với: InvalidArgumentException nếu đầu vào không phải là một PDF hợp lệ. Một /ByteRange hoặc /Contents bị lỗi định dạng sẽ cho ra các chuỗi rỗng (fail-closed), không bao giờ là một kết quả khẳng định.

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

Ném ngoại lệ hoặc thất bại với: nó không bao giờ ném ngoại lệ khi xác minh thất bại. Mọi khiếm khuyết đều ánh xạ đến một chỉ báo ValidationReport, ví dụ HASH_FAILURE hoặc SIG_CRYPTO_FAILURE.

Tạo một PAdES B-LT

Bây giờ hãy nâng cấp một tài liệu vừa được ký lên B-LT. Bộ tạo dài hạn thu thập chuỗi chứng thư số cùng bằng chứng OCSP/CRL và ghi Document Security Store (DSS). Nó tiếp nối lượt ký được mô tả trên trang Chữ ký, nơi cung cấp cho bạn buffer đầu ra, sổ đăng ký đối tượng (object registry), và mã hex /Contents của chữ ký:

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

Giá trị trả về là số đối tượng DSS dành cho mục /DSS trong danh mục (catalog) của tài liệu. Bộ tạo mặc định ở chế độ thực thi kiểm tra thu hồi strict: khi thiếu tài liệu thu hồi, nó ném ngoại lệ thay vì âm thầm phát ra một tệp “B-LT” rỗng ruột.

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

Ném ngoại lệ hoặc thất bại với: NextPDF\Enterprise\Security\Ltv\LtvException khi việc kiểm định chuỗi thất bại, khi chứng thư số bị thu hồi, hoặc khi thiếu tài liệu thu hồi dưới chế độ strict mặc định.

4. Khi có gì đó thất bại

status: no_license — gói giấy phép chưa được nạp

Bước 2 in ra status: no_license và runtime: disabled, và kết quả mang theo cảnh báo No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. Một lời gọi bị chặn theo quyền sử dụng khi đó sẽ ném NextPDF\Accelerator\Exception\SpectrumAuthenticationException với mã SPEC-LIC-001, ví dụ Capability '...' requires a valid license. Cách khắc phục: đặt và kích hoạt gói giấy phép theo Cấp phép và kích hoạt, rồi chạy lại bước 2.

InvalidArgumentException: Input does not start with %PDF header

SignatureExtractor::extract() nhận được thứ gì đó không phải là một PDF — sai đường dẫn, một lần đọc rỗng, hoặc một bản tải về bị nén. Hãy kiểm tra tệp bạn đã nạp. Một danh sách $signatures rỗng thì khác: tệp là một PDF, nhưng nó không mang từ điển /Type /Sig nào, nên không có gì để xác minh.

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

enableLtv() không thể lấy được một phản hồi OCSP hay một CRL cho một chứng thư số trong chuỗi, và chế độ strict mặc định từ chối ghi một tuyên bố B-LT khi không có bằng chứng. Hãy kiểm tra khả năng truy cập responder từ máy chủ, hoặc truyền enforcementMode: RevocationEnforcementMode::PERMISSIVE chỉ khi bạn chấp nhận một cách tường minh một lần chạy chỉ-cảnh-báo — đừng bao giờ gán nhãn kết quả đầu ra như vậy là B-LT cho các quy trình sản xuất hoặc tuân thủ trừ khi bằng chứng thu hồi bị thiếu được chấp nhận và ghi nhận một cách tường minh. Liên quan: yêu cầu B-LTA mà không có một TSA client sẽ thất bại với LtvException: TSA client required for document timestamps.

Đi tiếp đến đâu

• Chữ ký: PAdES B-LT / B-LTA, DSS, dấu thời gian tài liệu — toàn bộ hành vi của bộ tạo, các quy tắc thứ tự, và vòng lặp lưu trữ.
• Xác minh chữ ký — kiểm định dựa trên thời gian và dài hạn, các neo tin cậy, các chuỗi lưu trữ.
• Cấp phép — NextPDF Enterprise — các trạng thái quyền sử dụng, thời gian ân hạn, việc chặn năng lực.
• Chỉ mục module NextPDF Enterprise — mọi thứ khác mà phiên bản này cung cấp.