Enterprise sürüm

Güvenilir listeler — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF Enterprise içindeki güvenilir liste yüzeyinin derin referansıdır. Bu yüzey, NextPDF\Enterprise\Security\Tsl ad alanının on iki genel sınıfıdır. NextPDF\Enterprise\Security\Tsl\TslPolicyEnforcer orkestrasyonlu giriş noktasıdır: yalnızca HTTP getirme, XMLDSig doğrulama, yapısal ayrıştırma ve nextUpdate bayatlık kapısının tümü geçtiğinde bir TslDocument döndürür. TslTrustAnchorProvider::buildBundle() ardından aktif CA/QC hizmetlerinden bir güven çıpası paketi türetir ve herhangi bir çıpa çıkarılmadan önce çağıranın sağladığı bir anda tazeliği yeniden doğrular. Her başarısızlık, tipli bir istisna yükseltir; hiçbir aşama sessizce bozulmaz. Hat, AB üye devlet güvenilir listelerinin ve çağıran tarafından sağlandığında LOTL (List of Trusted Lists) kaynaklı güven çıpalarının doğrulanmasını destekler; otomatik LOTL keşfi, yoklama ve pivot işleme kapsam dışıdır.

Kullanılabilirlik ve lisanslama

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

Genel API yüzeyi

Sembol	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
`TslPolicyEnforcer`	`TslFetcher $fetcher`, `TslSignatureVerifier $verifier`, `TslXmlParser $parser`	Getirme, imza doğrulama, ayrıştırma ve bayatlık kapısını tek bir giriş noktasında birleştirir	—	Aşağıdaki hat istisnalarını iletir	`final`; yapı gereği fail-closed
`TslPolicyEnforcer::fetchAndVerify`	`string $url`	Bir TSL getirir, ardından baytlar üzerinde `verifyXml()` çalıştırır	`TslDocument`	`TslFetchException`, `NetworkPolicyViolation`, `TslSignatureException`, `TslParseException`	Yalnızca dört aşamanın tümü geçtiğinde döndürür
`TslPolicyEnforcer::verifyXml`	`string $xml`	İmzayı doğrular, ayrıştırır ve bayat bir listeyi reddeder	`TslDocument`	`TslSignatureException`, `TslParseException`	Bayatlık geçerli sistem saatine göre değerlendirilir
`TslFetcher`	`ClientInterface $httpClient`, `RequestFactoryInterface $requestFactory`, `?CacheInterface $cache = null`, `int $defaultTtlSeconds = 3600`, `int $maxBytes = 16_777_216`, `NetworkPolicy $networkPolicy = NetworkPolicy::ONLINE`	ETag tabanlı önbellekleme ile yalnızca HTTPS TSL/LOTL alımı	—	—	`final`; SSRF koruması özel, loopback, link-local ve metadata ana bilgisayarlarını DNS yeniden bağlama azaltmasıyla engeller
`TslFetcher::fetch`	`string $url`	`If-None-Match` yeniden doğrulaması ile GET; gövdeyi artı ETag’i yapılandırılmış TTL altında önbelleğe alır	`string` (ham XML baytları)	`TslFetchException`, `NetworkPolicyViolation`	En fazla `$maxBytes` bayt okur; `STRICT_OFFLINE` altında yalnızca önbelleğe alınmış bir gövde sunulur
`TslSignatureVerifier`	`array $trustAnchorsPem`, `int $clockTolerance = 0`	Yapılandırılmış güven çıpalarına sabitlenmiş XMLDSig doğrulayıcı	—	Çıpa listesi boş olduğunda `InvalidArgumentException`	`final`; `ALLOWED_SIG_ALG` ve `ALLOWED_DIGEST_ALG` içinde izin listeleri
`TslSignatureVerifier::verify`	`string $xml`	Enveloped XMLDSig imzasını fail-closed doğrular	`string` (imzalayıcı sertifikası PEM)	Makine tarafından okunabilir bir sebep koduyla `TslSignatureException`	KeyInfo sertifikalarına asla tek başlarına güvenilmez; imzalayıcı yapılandırılmış bir çıpaya zincirlenmelidir
`TslXmlParser::parse`	`string $xml`	Bir `TslDocument`’a yapısal ayrıştırma; imzadan bağımsız	`TslDocument`	`TslParseException`	Ayrıştırmadan önce herhangi bir DOCTYPE’ı fail-closed reddeder; `LIBXML_NONET` ile yükler; çağıranlar sonuca güvenmeden önce doğrulamalıdır
`TslTrustAnchorProvider::buildBundle`	`TslDocument $tsl`, `DateTimeImmutable $now`	Önce tazeliği doğrular, ardından aktif CA/QC hizmetlerinin sertifikalarını toplar	`EnterpriseCaTrustAnchorBundle`	`TslParseException`	Tazelik kapısı herhangi bir çıpa çıkarımından önce gelir; boş sonuç kümesi fırlatır
`TslDocument`	Sekiz yükseltilmiş `readonly` özellik (yapıcı çitine bakın)	Değişmez ayrıştırılmış TSL değer nesnesi	—	—	`final readonly`; kaynakta `@api` açıklamalı
`TslDocument::isStale`	`DateTimeImmutable $now`	Fail-closed bir UTC ayrıştırmasından sonra `nextUpdate`’i `$now` ile karşılaştırır	`bool`	`TslParseException`	Açık bir `Z` veya sayısal ofset belirteci gerektirir
`TslDocument::assertFresh`	`DateTimeImmutable $now`	Liste bayat olduğunda veya `nextUpdate` ayrıştırılamadığında fırlatır	`void`	`TslParseException`	Tüketici sınırı tazelik kapısı
`TslDocument::servicesOfType`	`string $serviceTypeIdentifier`	Hizmetleri ETSI hizmet türü URI’sine göre filtreler	`list<TspService>`	Fırlatmaz	—
`TslDocument::activeServices`	—	Yalnızca granted durumundaki hizmetleri döndürür	`list<TspService>`	Fırlatmaz	Granted, `TspService::STATUS_GRANTED` anlamına gelir
`TspService`	Sekiz yükseltilmiş `readonly` özellik	Bir TSL içindeki bir güven hizmeti girişi	—	—	`final readonly`; durum ve hizmet türü URI’leri için sabitler
`TspService::isGranted`	—	Granted URI’sine karşı durum eşitliği	`bool`	Fırlatmaz	—
`TspService::isQualifiedCa`	—	CA/QC URI’sine karşı tür eşitliği	`bool`	Fırlatmaz	—
`TspServiceQualifier`	`string $qualifierUri`, `string $criteriaListAssert = 'all'`, `array $policyOidConditions = []`, `array $keyUsageConditions = []`	İsteğe bağlı ölçütlerle bir ETSI hizmet niteleyicisi	—	—	`final readonly`; `FOR_ESIG`, `FOR_ESEAL`, `FOR_WSA`, `QSCD_STATEMENT`, `NO_QSCD` sabitleri
`EnterpriseCaTrustAnchorBundle`	`array $anchorsPem`, `string $bundleVersion`, `string $bundleSha256`	Sabitlenmiş çıpa paketi; yapım sırasında sağlanan özeti sağlanan çıpalara karşı doğrular	—	`InvalidArgumentException`	`buildBundle()`’dan edinin; elle oluşturmayın; `TrustAnchorStoreInterface` uygular
`EnterpriseCaTrustAnchorBundle::containsFingerprint`	`string $anchorDerSha256Hex`	DER gövdesi üzerinden hex SHA-256 ile çıpa üyeliği	`bool`	Fırlatmaz	—
`EnterpriseCaTrustAnchorBundle::computeBundleSha256`	`array $anchorsPem`	Satır sonu normalleştirilmiş PEM birleştirmesi üzerinden kanonik SHA-256	`string`	Fırlatmaz	`static`
`TslFetchException`	—	Başarısız bir TSL alımını bildirir	—	—	`final`; `RuntimeException`’ı genişletir
`TslParseException`	—	Yapısal veya tazelik başarısızlığını bildirir	—	—	`final`; `RuntimeException`’ı genişletir
`TslSignatureException`	`string $reason`, `string $message`	Bir sebep koduyla XMLDSig doğrulama başarısızlığını bildirir	—	—	`final`; genel `readonly` `$reason` (aşağıdaki sebep kodlarına bakın)

TslPolicyEnforcer

public function fetchAndVerify(string $url): TslDocument
public function verifyXml(string $xml): TslDocument

TslFetcher

public function __construct(
    private readonly ClientInterface $httpClient,
    private readonly RequestFactoryInterface $requestFactory,
    private readonly ?CacheInterface $cache = null,
    private readonly int $defaultTtlSeconds = 3600,
    private readonly int $maxBytes = 16_777_216,
    private readonly NetworkPolicy $networkPolicy = NetworkPolicy::ONLINE,
) {}

public function fetch(string $url): string

TslSignatureVerifier

public function __construct(private readonly array $trustAnchorsPem, private readonly int $clockTolerance = 0)

public function verify(string $xml): string

TslXmlParser

public function parse(string $xml): TslDocument

TslTrustAnchorProvider

public function buildBundle(TslDocument $tsl, DateTimeImmutable $now): EnterpriseCaTrustAnchorBundle

TslDocument

public function __construct(
    public string $schemeTerritory,
    public string $schemeOperatorName,
    public string $tslType,
    public int $sequenceNumber,
    public string $issueDateTime,
    public string $nextUpdate,
    public array $tspServices,
    public string $rawXmlSha256,
) {}

public function isStale(DateTimeImmutable $now): bool
public function assertFresh(DateTimeImmutable $now): void
public function servicesOfType(string $serviceTypeIdentifier): array
public function activeServices(): array

TspService

public function __construct(public string $tspName, public string $serviceName, public string $serviceTypeIdentifier, public string $serviceStatus, public string $statusStartingTime, public string $serviceCertificatePem, public array $qualifiers, public array $additionalServiceInformation) {}

public function isGranted(): bool
public function isQualifiedCa(): bool

TspServiceQualifier

public function __construct(public string $qualifierUri, public string $criteriaListAssert = 'all', public array $policyOidConditions = [], public array $keyUsageConditions = []) {}

EnterpriseCaTrustAnchorBundle

public function __construct(public array $anchorsPem, public string $bundleVersion, public string $bundleSha256)

public function containsFingerprint(string $anchorDerSha256Hex): bool
public static function computeBundleSha256(array $anchorsPem): string

TslSignatureException

public function __construct(public readonly string $reason, string $message)

TslSignatureException sebep kodları: missing_signature, untrusted_signer, invalid_signature, digest_mismatch, unsupported_algorithm, unsupported_transform, expired_anchor.

Davranış sözleşmesi

Hat sırası sabittir: getirme, XMLDSig doğrulama, yapısal ayrıştırma, bayatlık kapısı. TslPolicyEnforcer yalnızca dördü de başarılı olduğunda bir TslDocument döndürür. Bir güvenilir liste, dayanan tarafların gerçekliği ve bütünlüğü kontrol edebilmesi için şema operatörü tarafından imzalanır — ETSI TS 119 612 §5.7.1.
TslXmlParser tasarım gereği imzadan bağımsızdır. Çağıranlar, herhangi bir ayrıştırılmış alana güvenmeden önce imzayı doğrulamalıdır. TslPolicyEnforcer::verifyXml() bu sıralamayı zorunlu kılar.
Tazelik değişmezi her tüketici sınırında zorunlu kılınır. nextUpdate’i geçmiş bir liste süresi dolmuştur ve reddedilir — ETSI TS 119 612 §5.3.15. verifyXml() geçerli sistem saatine karşı kapı uygular; TslDocument::assertFresh() ve buildBundle() çağıranın sağladığı bir ana karşı kapı uygular.
Tazelik ayrıştırması fail-closed’dır. Tarih-saat alanları, açık bir belirteci olan ISO 8601 UTC değerleridir — ETSI TS 119 612 §5.1.3. Açık bir Z veya sayısal ofsetsiz bir nextUpdate, TslParseException yükseltir; değer, sunucunun yerel saat diliminde asla yeniden yorumlanmaz.
buildBundle(), herhangi bir çıpa çıkarmadan önce assertFresh($now) çağırır, ardından yalnızca hem granted hem de CA/QC olan hizmetleri kabul eder. Granted ve withdrawn, nitelikli hizmet durumu URI’leridir — ETSI TS 119 612 §5.5.4. CA/QC, nitelikli CA hizmet türü URI’sidir — ETSI TS 119 612 §5.5.1.1.
Paket sürümü, şema bölgesinden ve TSL sıra numarasından türetilir. Sıra numarası sürümler arasında monotondur — ETSI TS 119 612 §5.3.2. Paket özeti, çıpa PEM’leri üzerinden kanonik bir SHA-256’dır ve containsFingerprint() üyeliği DER SHA-256 ile yanıtlar.
Doğrulayıcı yalnızca yapılandırılmış çıpalara güvenir. KeyInfo içinde bulunan sertifikalar, imzalayıcı yaprağı ve aday ara sertifikalar olarak hizmet eder; zincir, 8 derinliği içinde yapılandırılmış bir çıpaya ulaşmalı, her bağlantı zamansal olarak geçerli olmalı ve bir veren sertifika basicConstraints cA=TRUE taşımalıdır (keyUsage mevcut olduğunda artı keyCertSign).
Doğrulama profili bir izin listesidir: SHA-256, SHA-384 veya SHA-512 ile RSA veya ECDSA; özet yöntemleri SHA-256, SHA-384 veya SHA-512; yalnızca özel kanonikleştirme; ve liste kapsayan ds:Reference üzerinde tam olarak enveloped-signature artı özel-C14N dönüşüm çifti. Başka herhangi bir şey unsupported_algorithm veya unsupported_transform ile başarısız olur.
TslFetcher, HTTPS olmayan URL’leri reddeder ve herhangi bir çıkıştan önce bir SSRF koruması uygular. NetworkPolicy::STRICT_OFFLINE altında, önceden önbelleğe alınmış bir gövde sunar veya NetworkPolicyViolation yükseltir; asla giden bir istek gönderilmez.

Uç durumlar ve başarısızlık modları

Bayat liste. verifyXml(), assertFresh() veya buildBundle()’dan gelen TslParseException, güven kaynağının kullanılamaz olduğu anlamına gelir. Bunu bir imza kararı değil, operasyonel bir yenileme başarısızlığı olarak değerlendirin.
Kanonik olmayan nextUpdate. Açık bir Z veya sayısal ofseti olmayan bir değer, hoşgörülü şekilde ayrıştırmak yerine fırlatır. ETSI TS 119 612 §5.1.3 UTC Z biçimini zorunlu kılar; kapı ayrıca açık bir sayısal ofseti de kabul eder ve diğer her şeyi reddeder.
Kullanım zamanı kayması. verifyXml() doğrulama zamanında kapı uygular; nextUpdate’i geçmiş şekilde bellekte tutulan bir belge, sonraki buildBundle($tsl, $now) kapısında yine başarısız olur.
Boş çıpa yapılandırması. TslSignatureVerifier, boş bir çıpa listesiyle yapımı reddeder (InvalidArgumentException).
Kullanılabilir hizmet yok. Granted CA/QC hizmeti olmayan taze bir liste, buildBundle()’dan TslParseException yükseltir; boş bir paket asla üretilmez.
Çevrimdışı duruş. Önbelleğe alınmış gövde olmadan STRICT_OFFLINE, NetworkPolicyViolation yükseltir. Önbellek araması, ilke kontrolünden önce gelir, böylece önbelleğe alınmış bir liste, hava boşluklu doğrulamayı çalışır tutar.
Aşırı büyük veya boş yanıt. fetch() en fazla $maxBytes bayt okur (varsayılan 16 MiB); kesik bir liste sonrasında hat aşağısında özet doğrulaması başarısız olur. Boş bir gövde TslFetchException yükseltir.
XML içinde DOCTYPE. Herhangi bir DOCTYPE, libxml bir varlık tablosu oluşturmadan önce ve yükleme sonrasında yeniden reddedilir. Bu, XXE ve varlık genişletme (billion-laughs) girdi sınıflarını kapatır.
Birden çok imza. Özet hesaplamasından önce yalnızca doğrulanmış enveloped ds:Signature kaldırılır; kardeş imzalar ve karşı imzalar korunur. Ek XAdES referanslarına izin verilir, ancak tam olarak bir ds:Reference belge kökünü kapsamalıdır.
Süresi dolmuş zincir malzemesi. Süresi dolmuş veya henüz geçerli olmayan bir imzalayıcı, ara sertifika veya çıpa, expired_anchor sebebiyle başarısız olur. clockTolerance, kabul penceresini simetrik olarak genişletir ve varsayılan olarak 0’dır.

FIPS modu davranışı

Doğrulayıcının izin listesi, SHA-2 ailesiyle RSA ve ECDSA’ya sabitlenmiştir; SHA-1 ve MD5 yapısal olarak hariç tutulmuştur. İmza aritmetiği, paketlenmiş yazılım kriptografisinde (phpseclib) çalışır. NextPDF, bu aritmetik için hiçbir FIPS 140-3 doğrulama iddiasında bulunmaz. Enterprise FIPS 140-3 kripto ilkesi profili, güvenlik modülüyle birlikte belgelenmiştir; algoritma seçimini kısıtlar ve güvenilir liste yapılarını veya bu modülün fail-closed davranışını değiştirmez.

Uygunluk

İddia	Standart	Madde
Next update’i geçmiş bir güvenilir liste, süresi dolmuş olarak atılır.	ETSI TS 119 612	§5.3.15
Tarih-saat alanları, `Z` belirteciyle UTC’deki ISO 8601 dizeleridir.	ETSI TS 119 612	§5.1.3
Şema operatörü, gerçeklik ve bütünlük için güvenilir listeyi imzalar.	ETSI TS 119 612	§5.7.1
Nitelikli hizmet durumu, granted veya withdrawn durum URI’sidir.	ETSI TS 119 612	§5.5.4
Nitelikli bir CA, `Svctype/CA/QC` hizmet türü URI’siyle tanımlanır.	ETSI TS 119 612	§5.5.1.1
TSL sıra numarası 1’de başlar ve her sürümde artar.	ETSI TS 119 612	§5.3.2

Tüm maddeler açımlanmıştır; NextPDF normatif metni yeniden üretmez. NextPDF hiçbir ETSI TS 119 612 uygunluk iddiasında ve hiçbir eIDAS sertifikasyon iddiasında bulunmaz. Bir güvenilir listeyi tüketmek, bir imzayı, bir sertifikayı veya bir NextPDF çıktısını “nitelikli” yapmaz; niteliklendirme, üye devlet denetimi altındaki güven hizmeti sağlayıcısına aittir ve hukuki etki bu modülün dışındadır. XMLDSig işleme modeli kısıtlamaları (enveloped-signature dönüşümü, özel kanonikleştirme, kök kapsayan referans) ürünün doğrulama profilinden belgelenmiştir; W3C XML Signature spesifikasyonu, alıntılanan kanıt kümesinin dışındadır. Bu modül yalnızca bir listenin güven girdisi olarak kabul edilebilir olup olmadığına karar verir; elde edilen çıpalara karşı sertifika yolu doğrulaması, sertifika doğrulama katmanına aittir.

Geliştirme notları

Bağımlılıklar PSR arayüzleridir: bir PSR-18 istemcisi, bir PSR-17 istek fabrikası ve isteğe bağlı bir PSR-16 önbelleği. Testlerde bellek içi çiftler enjekte edin; soğuk bir fetch() dışında hiçbir aşama canlı ağ erişimi gerektirmez.
Üst çıpayı bant dışı sabitleyin. Üye devlet listeleri için, LOTL çıpası liste imzalayıcılarını yetkilendirir; doğrulayıcı asla KeyInfo içeriğinden güven başlatmaz.
Arka plan yoklaması, pivot-LOTL işleme ve karşılıklı TLS veya proxy kimlik doğrulaması, bu sürümde fetcher’ın kapsamı dışındadır. Yenilemeyi harici olarak zamanlayın ve her nextUpdate’ten önce yeniden getirin.
buildBundle()’a yapım anını değil, doğrulama anını geçirin. Her yenilemeden sonra paketi yeniden oluşturun; bir paketi asla kaynak listenin nextUpdate’ini geçirerek önbelleğe almayın.
bundleVersion, gözlemlenebilir tsl-<territory>-seq<sequenceNumber> biçimine sahiptir; TslDocument üzerindeki rawXmlSha256, kanıt kayıtlarını ve tekrar tespitini destekler.
Bozuk hizmet girişleri, savunmacı yer tutucu değerlerle ayrıştırılır; paket yapımına ulaşan bozuk bir dijital kimlik, InvalidArgumentException ile fail-closed olur.
Sınıflar @since 1.10.0 kaynak açıklamaları taşır (TslFetchException: 3.2.0). TslDocument, TspService ve TspServiceQualifier kaynakta @api açıklamalıdır.

Ayrıca bakınız

eIDAS güvence seviyeleri — güvenilir liste kanıtını Güvence Seviyelerine eşleyen yetenek sayfası.
ASiC kapsayıcıları — kapsayıcı güven bağlama için TslTrustAnchorProvider::buildBundle()’ın bir tüketicisi.
İmza doğrulama — güven çıpalarını tüketen AdES/PAdES doğrulama tarafı.
Güvenlik — Derin Referans — birleşik Enterprise güvenlik yüzeyi.
İmza — Derin Referans — PAdES B-LT ve B-LTA uzun vadeli üretici.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.