Szybki start NextPDF Enterprise

W skrócie

Ten samouczek prowadzi od pustego projektu do dwóch działających wyników Enterprise. Najpierw zweryfikujesz istniejący podpisany plik PDF i odczytasz jego MainIndication. Następnie podniesiesz podpisany dokument do poziomu PAdES B-LT za pomocą długoterminowego producenta. Każdy krok pokazuje dokładne wyjście lub wyjątek, którego należy oczekiwać. NextPDF dokumentuje możliwości, a nie certyfikację: nie posiada żadnej certyfikacji PAdES ani eIDAS i żadnej nie przyznaje.

Ta funkcjonalność jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się za pomocą koperty licencyjnej poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcjonalności. Porównaj edycje i uzyskaj licencję.

Wymagania wstępne

• Composer jest skonfigurowany dla prywatnego repozytorium NextPDF. Najpierw wykonaj Instalacja i uwierzytelnianie.
• Posiadasz kopertę licencyjną Enterprise, pobraną z konta w app.getnextpdf.com. Licencjonowanie i aktywacja wyjaśnia, czym jest koperta i gdzie ją umieścić.
• Do kroku 3 potrzebujesz podpisanego pliku PDF do weryfikacji. Do części B-LT potrzebujesz także certyfikatu podpisującego oraz dostępu sieciowego do responderów OCSP/CRL.

1. Instalacja i aktywacja

Wymagaj pakietu Enterprise. Zależy on od nextpdf/core i nextpdf/pro, więc Composer pobiera cały stos:

composer require nextpdf/enterprise
composer show nextpdf/enterprise

Jeśli composer show wypisuje pakiet i jego wersję, instalacja się powiodła. Teraz umieść podpisaną kopertę licencyjną tam, gdzie ładuje ją Twoje wdrożenie, dokładnie tak, jak opisuje Licencjonowanie i aktywacja. Sama instalacja pakietu nie przyznaje możliwości Enterprise; to aktywowana licencja wybiera edycję.

2. Weryfikacja uprawnienia

Zapytaj ewaluator uprawnień, co przyznaje Twoja licencja. Podczas aktywacji bootstrap uzyskuje zweryfikowany NextPDF\Enterprise\Licensing\LicenseKey; przekaż go:

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

Przy aktywnej licencji Enterprise zobaczysz:

status:  active
edition: enterprise
runtime: allowed

Metoda stojąca za tym krokiem:

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

Zgłasza lub kończy się niepowodzeniem z: nigdy nie zgłasza wyjątku. Brakująca licencja zwraca EntitlementResult w trybie fail-closed ze statusem EntitlementStatus::NoLicense i wartością runtimeAllowed równą false (zobacz krok 4).

3. Pierwszy wynik

Weryfikacja istniejącego podpisanego pliku PDF

Wyodrębnij podpis z podpisanego pliku PDF, a następnie uruchom podstawową walidację AdES. Silnik implementuje poziomy walidacji ETSI EN 319 102-1; validateBasic() to przepływ klauzuli 5.2 — struktura, skrót, kryptografia podpisu oraz łańcuch certyfikatów:

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

Dla poprawnie sformułowanego podpisu, który przechodzi podstawowe kontrole strukturalne, skrótu, kryptograficzne oraz łańcucha skonfigurowane w tym przykładzie, zobaczysz:

TOTAL_PASSED
(none)

MainIndication ma dokładnie trzy przypadki: TOTAL_PASSED, TOTAL_FAILED oraz INDETERMINATE. Silnik działa w trybie fail-closed: kontrola, której nie może pozytywnie potwierdzić, daje INDETERMINATE, nigdy cichego pozytywnego wyniku. Pozytywny wynik oznacza tutaj rezultat walidacji w ramach kontroli tego silnika, a nie oświadczenie o zaufaniu ani certyfikacji — kotwice zaufania i dowody długoterminowe należą do głębszych poziomów na stronie weryfikacji.

public function extract(string $pdfData): array

Zgłasza lub kończy się niepowodzeniem z: InvalidArgumentException, jeśli wejście nie jest prawidłowym plikiem PDF. Zniekształcony /ByteRange lub /Contents daje puste ciągi znaków (fail-closed), nigdy pozytywny wynik.

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

Zgłasza lub kończy się niepowodzeniem z: nigdy nie zgłasza wyjątku przy niepowodzeniu weryfikacji. Każdy defekt mapuje się na wskazanie ValidationReport, np. HASH_FAILURE lub SIG_CRYPTO_FAILURE.

Wytworzenie PAdES B-LT

Teraz podnieś świeżo podpisany dokument do poziomu B-LT. Długoterminowy producent zbiera łańcuch certyfikatów oraz dowody OCSP/CRL i zapisuje Document Security Store (DSS). Kontynuuje on przebieg podpisywania opisany na stronie Podpisu, który udostępnia bufor wyjściowy, rejestr obiektów oraz szesnastkowy zapis /Contents podpisu:

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

Zwracaną wartością jest numer obiektu DSS dla wpisu /DSS katalogu dokumentu. Producent domyślnie stosuje ścisłe egzekwowanie unieważnień: brakujący materiał unieważnienia zgłasza wyjątek, zamiast po cichu emitować pusty plik „B-LT”.

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

Zgłasza lub kończy się niepowodzeniem z: NextPDF\Enterprise\Security\Ltv\LtvException, gdy walidacja łańcucha zawiedzie, gdy certyfikat jest unieważniony lub gdy brakuje materiału unieważnienia przy ścisłym trybie domyślnym.

4. Gdy coś zawiedzie

status: no_license — koperta nie jest załadowana

Krok 2 wypisuje status: no_license oraz runtime: disabled, a wynik niesie ostrzeżenie No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. Wywołanie objęte bramką uprawnień zgłasza wtedy NextPDF\Accelerator\Exception\SpectrumAuthenticationException z kodem SPEC-LIC-001, np. Capability '...' requires a valid license. Rozwiązanie: umieść i aktywuj kopertę zgodnie z Licencjonowanie i aktywacja, a następnie ponownie uruchom krok 2.

InvalidArgumentException: Input does not start with %PDF header

SignatureExtractor::extract() otrzymał coś, co nie jest plikiem PDF — błędną ścieżkę, puste odczytanie lub skompresowane pobranie. Sprawdź załadowany plik. Pusta lista $signatures to coś innego: plik jest plikiem PDF, ale nie niesie słownika /Type /Sig, więc nie ma nic do zweryfikowania.

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

enableLtv() nie mógł uzyskać odpowiedzi OCSP ani CRL dla certyfikatu w łańcuchu, a ścisły tryb domyślny odmawia zapisania deklaracji B-LT bez dowodów. Sprawdź osiągalność responderów z hosta lub przekaż enforcementMode: RevocationEnforcementMode::PERMISSIVE tylko wtedy, gdy jawnie akceptujesz przebieg wyłącznie z ostrzeżeniami — nigdy nie oznaczaj takiego wyjścia jako B-LT w przepływach produkcyjnych lub zgodności, chyba że brakujący dowód unieważnienia jest jawnie zaakceptowany i udokumentowany. Powiązane: żądanie B-LTA bez klienta TSA kończy się niepowodzeniem z LtvException: TSA client required for document timestamps.

Dokąd dalej

• Podpis: PAdES B-LT / B-LTA, DSS, znaczniki czasu dokumentu — pełne zachowanie producenta, reguły kolejności oraz pętla archiwizacji.
• Weryfikacja podpisu — walidacja oparta na czasie i długoterminowa, kotwice zaufania, łańcuchy archiwalne.
• Licencjonowanie — NextPDF Enterprise — stany uprawnień, okres karencji, bramkowanie możliwości.
• Indeks modułu NextPDF Enterprise — wszystko inne, co dostarcza edycja.