NextPDF Enterprise hızlı başlangıç

Bir bakışta

Bu eğitim sizi boş bir projeden çalışan iki Enterprise sonucuna götürür. Önce mevcut imzalı bir PDF’i doğrular ve onun MainIndication değerini okursunuz. Ardından imzalı bir belgeyi uzun vadeli üreticiyle PAdES B-LT seviyesine yükseltirsiniz. Her adım, beklemeniz gereken tam çıktıyı veya istisnayı gösterir. NextPDF yeteneği belgeler, sertifikasyonu değil: hiçbir PAdES veya eIDAS sertifikasyonuna sahip değildir ve hiçbirini de vermez.

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) ile gelir ve Enterprise katmanı bir lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Ön koşullar

• Composer, özel NextPDF deposu için yapılandırılmıştır. Önce Kurun ve kimlik doğrulaması yapın adımını izleyin.
• Enterprise lisans zarfınıza sahipsiniz; bu, app.getnextpdf.com adresindeki hesabınızdan indirilir. Lisanslama ve etkinleştirme, zarfın ne olduğunu ve nereye gittiğini açıklar.
• Adım 3 için doğrulanacak imzalı bir PDF gerekir. B-LT bölümü için ayrıca imzalayan sertifikanız ve OCSP/CRL yanıtlayıcılarına ağ erişimi gerekir.

1. Kurun ve etkinleştirin

Enterprise paketini gereksinim olarak ekleyin. nextpdf/core ve nextpdf/pro paketlerine bağlıdır, bu nedenle Composer tüm yığını getirir:

composer require nextpdf/enterprise
composer show nextpdf/enterprise

composer show paketi ve sürümünü yazdırırsa kurulum başarılı olmuştur. Şimdi imzalı lisans zarfını, tam olarak Lisanslama ve etkinleştirme bölümünde açıklandığı gibi, dağıtımınızın yüklediği yere yerleştirin. Paketi tek başına kurmak Enterprise yeteneklerini vermez; etkinleştirilen lisans sürümü seçer.

2. Yetkilendirmenizi doğrulayın

Yetkilendirme değerlendiricisine lisansınızın neyi verdiğini sorun. Önyükleyiciniz etkinleştirme sırasında doğrulanmış NextPDF\Enterprise\Licensing\LicenseKey değerini elde eder; onu iletin:

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

Etkin bir Enterprise lisansıyla şunu görürsünüz:

status:  active
edition: enterprise
runtime: allowed

Bu adımın arkasındaki metot:

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

Fırlattığı veya başarısız olduğu durum: asla fırlatmaz. Eksik bir lisans, EntitlementStatus::NoLicense ile ve runtimeAllowed false olarak fail-closed bir EntitlementResult döndürür (bkz. adım 4).

3. İlk sonuç

Mevcut imzalı bir PDF’i doğrulayın

İmzayı imzalı bir PDF’ten çıkarın, ardından temel AdES doğrulamasını çalıştırın. Motor, ETSI EN 319 102-1 doğrulama seviyelerini uygular; validateBasic(), madde 5.2 akışıdır — yapı, özet, imza kriptografisi ve sertifika zinciri:

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

Bu örnekte yapılandırılan temel yapısal, özet, kriptografik ve zincir denetimlerini geçen, iyi biçimlendirilmiş bir imza için şunu görürsünüz:

TOTAL_PASSED
(none)

MainIndication tam olarak üç duruma sahiptir: TOTAL_PASSED, TOTAL_FAILED ve INDETERMINATE. Motor fail-closed’dur: olumlu olarak tespit edemediği bir denetim INDETERMINATE verir, asla sessiz bir geçiş değil. Buradaki bir geçiş, bu motorun denetimleri altındaki bir doğrulama sonucudur; bir güven veya sertifikasyon beyanı değildir — güven bağlantı noktaları ve uzun vadeli kanıt, doğrulama sayfasındaki daha derin seviyelere aittir.

public function extract(string $pdfData): array

Fırlattığı veya başarısız olduğu durum: girdi geçerli bir PDF değilse InvalidArgumentException. Bozuk bir /ByteRange veya /Contents, olumlu bir sonuç değil, boş dizeler (fail-closed) verir.

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

Fırlattığı veya başarısız olduğu durum: bir doğrulama başarısızlığında asla fırlatmaz. Her kusur bir ValidationReport işaretine eşlenir, ör. HASH_FAILURE veya SIG_CRYPTO_FAILURE.

Bir PAdES B-LT üretin

Şimdi yeni imzalanmış bir belgeyi B-LT seviyesine yükseltin. Uzun vadeli üretici, sertifika zincirini ve OCSP/CRL kanıtını toplar ve Document Security Store (DSS) yazar. İmza sayfasında açıklanan imzalama geçişini sürdürür; bu geçiş size çıktı arabelleğini, nesne kayıt defterini ve imza /Contents onaltılık değerini verir:

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

Dönüş değeri, belge kataloğunun /DSS girdisi için DSS nesne numarasıdır. Üretici varsayılan olarak strict iptal denetimine gelir: eksik iptal materyali, sessizce içi boş bir “B-LT” dosyası yaymak yerine bir istisna fırlatır.

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

Fırlattığı veya başarısız olduğu durum: zincir doğrulaması başarısız olduğunda, sertifika iptal edildiğinde veya strict varsayılan altında iptal materyali eksik olduğunda NextPDF\Enterprise\Security\Ltv\LtvException.

4. Bir şey başarısız olduğunda

status: no_license — zarf yüklenmemiş

Adım 2 status: no_license ve runtime: disabled yazdırır ve sonuç No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing uyarısını taşır. Ardından yetkilendirme kapılı bir çağrı, SPEC-LIC-001 koduyla NextPDF\Accelerator\Exception\SpectrumAuthenticationException fırlatır, ör. Capability '...' requires a valid license. Düzeltme: zarfı Lisanslama ve etkinleştirme uyarınca yerleştirip etkinleştirin, ardından adım 2’yi yeniden çalıştırın.

InvalidArgumentException: Input does not start with %PDF header

SignatureExtractor::extract(), bir PDF olmayan bir şey aldı — yanlış bir yol, boş bir okuma veya sıkıştırılmış bir indirme. Yüklediğiniz dosyayı kontrol edin. Boş bir $signatures listesi farklıdır: dosya bir PDF’tir, ancak hiçbir /Type /Sig sözlüğü taşımaz, dolayısıyla doğrulanacak bir şey yoktur.

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

enableLtv(), zincirdeki bir sertifika için bir OCSP yanıtı veya bir CRL elde edemedi ve strict varsayılan, kanıt olmadan bir B-LT talebi yazmayı reddeder. Ana bilgisayardan yanıtlayıcı erişilebilirliğini kontrol edin veya yalnızca yalnızca-uyarı bir çalıştırmayı açıkça kabul ederseniz enforcementMode: RevocationEnforcementMode::PERMISSIVE iletin — eksik iptal kanıtı açıkça kabul edilip belgelenmedikçe böyle bir çıktıyı üretim veya uyumluluk iş akışları için asla B-LT olarak etiketlemeyin. İlgili: bir TSA istemcisi olmadan B-LTA istemek LtvException: TSA client required for document timestamps ile başarısız olur.

Bundan sonra nereye

• İmza: PAdES B-LT / B-LTA, DSS, belge zaman damgaları — tam üretici davranışı, sıralama kuralları ve arşivleme döngüsü.
• İmza doğrulama — zaman tabanlı ve uzun vadeli doğrulama, güven bağlantı noktaları, arşiv zincirleri.
• Lisanslama — NextPDF Enterprise — yetkilendirme durumları, ödemesiz süre, yetenek kapıları.
• NextPDF Enterprise modül dizini — sürümün getirdiği diğer her şey.