Mevcut bir imzayı inceleyin ve güven sınırını anlayın

Bir bakışta

Bir PDF’in imza sözlüğü içerip içermediğini algılamak için Core denetleyicisini kullanın. Denetleyici çevrimdışı çalışır ve Spectrum yardımcı bileşenini kullanmaz. Bu tarif güven sınırını da netleştirir: bir imzayı algılamak, onu doğrulamakla aynı şey değildir. Kriptografik doğrulama, güven yolu doğrulaması ve iptal denetimi Premium kapsamındaki ya da harici bileşenlerin sorumluluğudur.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Bir PDF imzası, değeri bir imza sözlüğü olan bir imza alanıdır (ISO 32000-2 §12.7.4). Sözlükteki Contents girdisi DER kodlu Cryptographic Message Syntax (CMS) SignedData tutar (ISO 32000-2 §12.8.1). Inspector Quick yedek yolu, imza işaretçilerini tarayarak bu yapının varlığını algılar. CMS’yi ayrıştırmaz; imza değerini hariç tutarak bayt aralığı özetini (ISO 32000-2 §12.8.1) yeniden hesaplamaz, sertifika zincirini doğrulamaz ve iptal denetimi yapmaz; bu işlemleri yapmaz.

API yüzeyi

Önce new Inspector() ile bir örnek oluşturun, ardından ->inspect(string $pdfData, InspectConfig $config) çağrısını yapın. Çevrimdışı PHP yedek yolu için InspectConfig::quick() kullanın. InspectDepth::Standard/Full Spectrum yardımcı bileşenini gerektirir; bileşen yoksa güvenli biçimde kapanır ve hata verir (INSPECT-SIDECAR-001). Sonuç bir InspectResult değer nesnesidir. Bu iş akışında imza varlığı için $hasSigned değerini, ayrıca $isEncrypted ve $pdfVersion değerlerini kullanın.

Kod örneği — hızlı başlangıç

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Inspect\InspectConfig;
use NextPDF\Inspect\Inspector;

$pdfData = file_get_contents(__DIR__ . '/incoming.pdf');
if ($pdfData === false || $pdfData === '') {
    fwrite(STDERR, "Cannot read incoming.pdf\n");
    exit(1);
}

$result = (new Inspector())->inspect($pdfData, InspectConfig::quick());

// hasSigned reports the PRESENCE of a signature dictionary.
// It does NOT mean the signature verifies.
echo $result->hasSigned
    ? "A signature is present — NOT verified.\n"
    : "No signature found.\n";

Kod örneği — üretim

Bu bağımsız program cookbook çalıştırma ortamında çalışır. examples/37-inspect-existing-signature.php dosyasını yansıtır. İmzalı olduğu bilinen bir corpus örneğini ve yeni oluşturulmuş imzasız bir belgeyi inceler; böylece varlık bayrağının iki dalını da gözlemleyebilirsiniz. Ardından sonucu bir sonraki adıma yönlendirir. Varlık, bir yönlendirme girdisidir; asla bir güven kararı değildir. Dosya, kriptografik bir doğrulayıcıya (Pro ya da harici) teslim edilir. Bu aşamada güvenilir kabul edilmez.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;
use NextPDF\Inspect\InspectConfig;
use NextPDF\Inspect\Inspector;

$inspector = new Inspector();

// --- A known-signed input ---
// The repository corpus carries synthetic PAdES samples. In your
// application this is simply the incoming PDF you received.
$signedPath = __DIR__ . '/tests/Corpus/pades/pades-b-b-bytepattern-synthetic.pdf';
if (is_file($signedPath)) {
    $signed = (string) file_get_contents($signedPath);
    $r = $inspector->inspect($signed, InspectConfig::quick());

    echo "Signed sample:\n";
    echo '  Signature present : ' . ($r->hasSigned ? 'yes' : 'no') . "\n";
    echo '  Encrypted         : ' . ($r->isEncrypted ? 'yes' : 'no') . "\n";
    echo '  PDF version       : ' . ($r->pdfVersion ?? 'unknown') . "\n";
    echo "  Verdict           : presence detected — NOT verified.\n";

    if ($r->hasSigned) {
        // Presence detected. This is routing input, not a trust verdict.
        // Hand the file to a cryptographic verifier (Pro or external)
        // before relying on it. (Pseudo-queue shown; wire your own.)
        // $verifierQueue->enqueue($signed);
        echo "  Next step         : run a cryptographic verifier before trusting it.\n";
    }
} else {
    echo "Signed corpus sample absent; skipping the signed branch.\n";
}

// --- A known-unsigned input ---
$unsigned = Document::createStandalone();
$unsigned->setTitle('Unsigned sample');
$unsigned->addPage();
$unsigned->setFont('helvetica', '', 12);
$unsigned->cell(0, 10, 'This document carries no signature.', newLine: true);
$unsignedBytes = $unsigned->getPdfData();

$ru = $inspector->inspect($unsignedBytes, InspectConfig::quick());
echo "Unsigned sample:\n";
echo '  Signature present : ' . ($ru->hasSigned ? 'yes' : 'no') . "\n";

// The harness sets NEXTPDF_COOKBOOK_OUTPUT and runs this script under the
// semantic profile; emit the unsigned document to the side-channel.
$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
file_put_contents($out !== false && $out !== '' ? $out : __DIR__ . '/inspected.pdf', $unsignedBytes);

Beklenen STDOUT (corpus örneği yoksa imzalı dal atlanır):

Signed sample:
  Signature present : yes
  Encrypted         : no
  PDF version       : <version>
  Verdict           : presence detected — NOT verified.
  Next step         : run a cryptographic verifier before trusting it.
Unsigned sample:
  Signature present : no

Uç durumlar ve dikkat edilmesi gerekenler

Varlık, geçerlilik anlamına gelmez. $hasSigned, bir imza sözlüğünün bulunduğunu bildirir. CMS yapısını, bayt aralığı özetini, imzalama sertifikasını, zinciri veya iptali denetlemez. Kurcalanmış bir dosya yine de hasSigned = true bildirebilir. Varlığı asla bütünlük veya yazarlık kanıtı olarak değerlendirmeyin.
Tam doğrulamanın gerektirdikleri. Tam bir karar için bayt aralığı özeti (ISO 32000-2 §12.8.1) yeniden hesaplanır, CMS SignedData doğrulanır, güvenilen bir bağlantı noktasına uzanan X.509 yolu oluşturulup denetlenir ve iptal durumu Online Certificate Status Protocol (OCSP) ya da bir sertifika iptal listesi (CRL) aracılığıyla denetlenir. Bir imza zaman damgası varsa, imza değeri sekizlileri üzerindeki kendi iziyle karşılaştırılarak doğrulanır (ETSI EN 319 122-1 §5.3). Bu işlemler imzalama sözleşmeleri üzerinden sağlanır. Üretime yönelik uygulamalar Pro ve Enterprise sürümlerinde sunulur. Harici bir doğrulayıcı da desteklenen diğer yoldur.
İnceleme derinliği. Spectrum yardımcı bileşeni olmadan kullanılabilen tek derinlik InspectConfig::quick() derinliğidir. Standard/Full, yardımcı bileşen kullanılamadığında INSPECT-SIDECAR-001 hatası fırlatır.
Boş girdi. Boş bir dize, “PDF data must not be empty” mesajıyla bir inceleme istisnası fırlatır. Okuma işlemini güvenceye alın.
Birden çok imza / zaman damgası. Varlık bayrağı imzaları saymaz ve bir onay imzasını bir belge zaman damgasından ayırt etmez (bu da RFC 5652 §5.3 uyarınca unsignedAttrs içinde taşınır). İmza sayısı ya da imza başına sonuç önemliyse özel bir doğrulayıcı kullanın.

Performans

Quick yedek yolu, belge baytları üzerinde sınırlı bir tarama yapar. Tam nesne grafiğini ayrıştırmaz. Gelen dosyaları daha ağır bir doğrulayıcıya yönlendirmeden önce hızlı ön eleme için kullanın.

Güvenlik notları

Denetleyici bir ön eleme aracıdır; bir güven sınırı değildir. Olumlu bir hasSigned değeri asla tek başına bir güven kararını belirlememelidir.

Veri yerleşimi ve PII azaltma önlemleri

İnceleme tamamen aynı süreç içinde çalışır. Hiçbir belge baytı ana makinenin dışına çıkmaz. Quick yedek yolu yalnızca yapısal işaretçileri okur, belge metnini okumaz; bu nedenle kişisel olarak tanımlanabilir bilgileri (PII) ne çıkarır ne de iletir.

Güvenli telemetri ve günlük temizleme

Inspector, isteğe bağlı bir PSR-3 günlükleyici kabul eder. Belge içeriğini değil, seçilen yolu (“Spectrum unavailable, using PHP fallback”) günlüğe kaydeder. Belge hassassa, incelenen PDF baytlarını veya InspectResult nesnesini olduğu gibi günlüğe kaydetmeyin.

Tehdit modeli

Kapsananlar: sözdizimsel olarak geçerli bir imza sözlüğü sunan kurcalanmış bir dosya (denetleyici varlığı bildirir; bütünlüğü açıkça öne sürmez) ve imzası olmayan bir dosya (doğru biçimde yok olarak bildirilir). Öne sürülmeyenler: algılanan herhangi bir imzanın kriptografik olarak geçerli, güvenilir veya iptal edilmemiş olduğu — bunlar doğrulayıcının görevidir.

FIPS modu davranışı

Quick yedek yolu hiçbir kriptografi gerçekleştirmez; bu nedenle Federal Information Processing Standards (FIPS) modu bu tarif için geçerli değildir. FIPS sağlayıcı zincirinin önem kazandığı nokta kriptografik doğrulamadır (Premium/harici).

Uygunluk

İfade	Spesifikasyon	Madde
Bir imza alanının değeri bir imza sözlüğüdür.	ISO 32000-2	§12.7.4
`Contents`, DER CMS SignedData tutar; bir belge zaman damgasının `Contents` girdisi ise bir TimeStampToken tutar.	ISO 32000-2	§12.8.1
Doğrulama, imza değerini hariç tutarak özeti bayt aralığı üzerinden yeniden hesaplar.	ISO 32000-2	§12.8.1
İmza zaman damgası izi, SignerInfo imza değeri sekizlileri üzerindedir.	ETSI EN 319 122-1	§5.3
Zaman damgası, SignerInfo unsignedAttrs içinde taşınır.	RFC 5652	§5.3

Bu tarif bir imzayı algılar. Herhangi bir imzanın geçerli, güvenilir veya iptal edilmemiş olduğunu öne sürmez. Bu kararı kriptografik bir doğrulayıcı verir.

Ticari bağlam

Kriptografik CMS doğrulaması, X.509 yol doğrulaması ve OCSP/CRL iptal denetimi Pro ve Enterprise sürümlerinde imzalama sözleşmeleri üzerinden sunulur. Core denetleyicisi yalnızca varlık algılamayı kapsar.