Enterprise edycja

Listy zaufania — szczegółowa referencja

W skrócie

Ta strona to pogłębiony materiał referencyjny dla powierzchni list zaufania w NextPDF Enterprise. Powierzchnię tworzy dwanaście publicznych klas przestrzeni nazw NextPDF\Enterprise\Security\Tsl. NextPDF\Enterprise\Security\Tsl\TslPolicyEnforcer jest zorkiestrowanym punktem wejścia: zwraca TslDocument tylko wtedy, gdy pobieranie HTTP, weryfikacja XMLDSig, parsowanie strukturalne oraz bramka nieaktualności nextUpdate przejdą pomyślnie. TslTrustAnchorProvider::buildBundle() następnie wyprowadza pakiet kotwic zaufania z aktywnych usług CA/QC, ponownie potwierdzając aktualność w podanym przez wywołującego momencie, zanim zostanie wyodrębniona jakakolwiek kotwica. Każde niepowodzenie zgłasza typowany wyjątek; żaden etap nie degraduje się po cichu. Potok obsługuje weryfikację list zaufania państw członkowskich UE oraz kotwic zaufania pochodzących z LOTL (List of Trusted Lists), gdy dostarczy je wywołujący; automatyczne wykrywanie LOTL, odpytywanie i przetwarzanie pivotów są poza zakresem.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się kopertą licencyjną warstwy Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Publiczna powierzchnia API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy niepowodzeniem z	Uwagi
`TslPolicyEnforcer`	`TslFetcher $fetcher`, `TslSignatureVerifier $verifier`, `TslXmlParser $parser`	Łączy pobieranie, weryfikację podpisu, parsowanie i bramkę nieaktualności w jeden punkt wejścia	—	Propaguje wyjątki potoku wymienione poniżej	`final`; fail-closed z założenia konstrukcji
`TslPolicyEnforcer::fetchAndVerify`	`string $url`	Pobiera jedną TSL, następnie uruchamia `verifyXml()` na bajtach	`TslDocument`	`TslFetchException`, `NetworkPolicyViolation`, `TslSignatureException`, `TslParseException`	Zwraca tylko wtedy, gdy wszystkie cztery etapy przejdą pomyślnie
`TslPolicyEnforcer::verifyXml`	`string $xml`	Weryfikuje podpis, parsuje i odrzuca nieaktualną listę	`TslDocument`	`TslSignatureException`, `TslParseException`	Nieaktualność jest oceniana względem bieżącego czasu systemowego
`TslFetcher`	`ClientInterface $httpClient`, `RequestFactoryInterface $requestFactory`, `?CacheInterface $cache = null`, `int $defaultTtlSeconds = 3600`, `int $maxBytes = 16_777_216`, `NetworkPolicy $networkPolicy = NetworkPolicy::ONLINE`	Pobieranie TSL/LOTL wyłącznie po HTTPS z buforowaniem opartym na ETag	—	—	`final`; ochrona SSRF blokuje hosty prywatne, pętli zwrotnej, link-local i metadanych z łagodzeniem DNS-rebinding
`TslFetcher::fetch`	`string $url`	GET z rewalidacją `If-None-Match`; buforuje treść oraz ETag pod skonfigurowanym TTL	`string` (surowe bajty XML)	`TslFetchException`, `NetworkPolicyViolation`	Czyta co najwyżej `$maxBytes` bajtów; pod `STRICT_OFFLINE` serwowana jest wyłącznie treść z bufora
`TslSignatureVerifier`	`array $trustAnchorsPem`, `int $clockTolerance = 0`	Weryfikator XMLDSig przypięty do skonfigurowanych kotwic zaufania	—	`InvalidArgumentException`, gdy lista kotwic jest pusta	`final`; listy dozwolonych w `ALLOWED_SIG_ALG` i `ALLOWED_DIGEST_ALG`
`TslSignatureVerifier::verify`	`string $xml`	Weryfikuje otoczkowy podpis XMLDSig w trybie fail-closed	`string` (PEM certyfikatu podpisującego)	`TslSignatureException` z odczytywalnym maszynowo kodem przyczyny	Certyfikaty z KeyInfo nigdy nie są zaufane same z siebie; podpisujący musi tworzyć łańcuch do skonfigurowanej kotwicy
`TslXmlParser::parse`	`string $xml`	Parsowanie strukturalne do `TslDocument`; niezależne od podpisu	`TslDocument`	`TslParseException`	Odrzuca każdy DOCTYPE w trybie fail-closed przed parsowaniem; ładuje z `LIBXML_NONET`; wywołujący muszą zweryfikować przed zaufaniem wynikowi
`TslTrustAnchorProvider::buildBundle`	`TslDocument $tsl`, `DateTimeImmutable $now`	Najpierw potwierdza aktualność, następnie zbiera certyfikaty aktywnych usług CA/QC	`EnterpriseCaTrustAnchorBundle`	`TslParseException`	Bramka aktualności poprzedza wyodrębnianie kotwic; pusty zbiór wyników zgłasza wyjątek
`TslDocument`	Osiem promowanych właściwości `readonly` (zobacz blok konstruktora)	Niemutowalny sparsowany obiekt wartości TSL	—	—	`final readonly`; adnotacja źródłowa `@api`
`TslDocument::isStale`	`DateTimeImmutable $now`	Porównuje `nextUpdate` z `$now` po fail-closed parsowaniu UTC	`bool`	`TslParseException`	Wymaga jawnego oznacznika `Z` lub numerycznego przesunięcia
`TslDocument::assertFresh`	`DateTimeImmutable $now`	Zgłasza wyjątek, gdy lista jest nieaktualna lub `nextUpdate` jest nieparsowalne	`void`	`TslParseException`	Bramka aktualności na granicy konsumenta
`TslDocument::servicesOfType`	`string $serviceTypeIdentifier`	Filtruje usługi po URI typu usługi ETSI	`list<TspService>`	Nie zgłasza wyjątku	—
`TslDocument::activeServices`	—	Zwraca wyłącznie usługi o statusie granted	`list<TspService>`	Nie zgłasza wyjątku	Granted oznacza `TspService::STATUS_GRANTED`
`TspService`	Osiem promowanych właściwości `readonly`	Jeden wpis usługi zaufania wewnątrz TSL	—	—	`final readonly`; stałe dla statusu i URI typów usług
`TspService::isGranted`	—	Równość statusu z URI granted	`bool`	Nie zgłasza wyjątku	—
`TspService::isQualifiedCa`	—	Równość typu z URI CA/QC	`bool`	Nie zgłasza wyjątku	—
`TspServiceQualifier`	`string $qualifierUri`, `string $criteriaListAssert = 'all'`, `array $policyOidConditions = []`, `array $keyUsageConditions = []`	Jeden kwalifikator usługi ETSI z opcjonalnymi kryteriami	—	—	`final readonly`; stałe `FOR_ESIG`, `FOR_ESEAL`, `FOR_WSA`, `QSCD_STATEMENT`, `NO_QSCD`
`EnterpriseCaTrustAnchorBundle`	`array $anchorsPem`, `string $bundleVersion`, `string $bundleSha256`	Pakiet przypiętych kotwic; waliduje podany skrót względem podanych kotwic przy konstrukcji	—	`InvalidArgumentException`	Uzyskaj z `buildBundle()`; nie konstruuj ręcznie; implementuje `TrustAnchorStoreInterface`
`EnterpriseCaTrustAnchorBundle::containsFingerprint`	`string $anchorDerSha256Hex`	Przynależność kotwicy po szesnastkowym SHA-256 z treści DER	`bool`	Nie zgłasza wyjątku	—
`EnterpriseCaTrustAnchorBundle::computeBundleSha256`	`array $anchorsPem`	Kanoniczny SHA-256 z konkatenacji PEM znormalizowanej po znakach nowej linii	`string`	Nie zgłasza wyjątku	`static`
`TslFetchException`	—	Sygnalizuje nieudane pobranie TSL	—	—	`final`; rozszerza `RuntimeException`
`TslParseException`	—	Sygnalizuje niepowodzenie strukturalne lub aktualności	—	—	`final`; rozszerza `RuntimeException`
`TslSignatureException`	`string $reason`, `string $message`	Sygnalizuje niepowodzenie weryfikacji XMLDSig z kodem przyczyny	—	—	`final`; publiczne `readonly` `$reason` (zobacz kody przyczyn poniżej)

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)

Kody przyczyn TslSignatureException: missing_signature, untrusted_signer, invalid_signature, digest_mismatch, unsupported_algorithm, unsupported_transform, expired_anchor.

Kontrakt zachowania

Kolejność potoku jest ustalona: pobieranie, weryfikacja XMLDSig, parsowanie strukturalne, bramka nieaktualności. TslPolicyEnforcer zwraca TslDocument tylko wtedy, gdy wszystkie cztery etapy zakończą się sukcesem. Listę zaufania podpisuje jej operator schematu, aby strony ufające mogły sprawdzić autentyczność i integralność — ETSI TS 119 612 §5.7.1.
TslXmlParser jest z założenia niezależny od podpisu. Wywołujący muszą zweryfikować podpis przed zaufaniem jakiemukolwiek sparsowanemu polu. TslPolicyEnforcer::verifyXml() wymusza tę kolejność.
Niezmiennik aktualności jest egzekwowany na każdej granicy konsumenta. Lista, której nextUpdate już minął, jest wygasła i zostaje odrzucona — ETSI TS 119 612 §5.3.15. verifyXml() bramkuje względem bieżącego czasu systemowego; TslDocument::assertFresh() i buildBundle() bramkują względem momentu podanego przez wywołującego.
Parsowanie aktualności jest fail-closed. Pola daty i czasu to wartości ISO 8601 w UTC z jawnym oznacznikiem — ETSI TS 119 612 §5.1.3. nextUpdate bez jawnego Z lub numerycznego przesunięcia zgłasza TslParseException; wartość nigdy nie jest reinterpretowana w lokalnej strefie czasowej serwera.
buildBundle() wywołuje assertFresh($now) przed wyodrębnieniem jakiejkolwiek kotwicy, a następnie dopuszcza wyłącznie usługi, które są jednocześnie granted oraz CA/QC. Granted i withdrawn to URI statusu usługi kwalifikowanej — ETSI TS 119 612 §5.5.4. CA/QC to URI typu usługi kwalifikowanego CA — ETSI TS 119 612 §5.5.1.1.
Wersja pakietu jest wyprowadzana z terytorium schematu oraz numeru sekwencji TSL. Numer sekwencji jest monotoniczny między wydaniami — ETSI TS 119 612 §5.3.2. Skrót pakietu to kanoniczny SHA-256 z PEM-ów kotwic, a containsFingerprint() odpowiada na pytanie o przynależność za pomocą DER SHA-256.
Weryfikator ufa wyłącznie skonfigurowanym kotwicom. Certyfikaty znalezione w KeyInfo służą jako liść podpisującego oraz kandydackie pośredniki; łańcuch musi osiągnąć skonfigurowaną kotwicę w głębokości 8, każde ogniwo musi być czasowo ważne, a certyfikat wystawiający musi nieść basicConstraints cA=TRUE (plus keyCertSign, gdy obecne jest keyUsage).
Profil weryfikacji jest listą dozwolonych: RSA lub ECDSA z SHA-256, SHA-384 lub SHA-512; metody skrótu SHA-256, SHA-384 lub SHA-512; wyłącznie kanonikalizacja ekskluzywna; oraz dokładnie para transformacji podpisu otoczkowego plus ekskluzywnego C14N na pokrywającym listę ds:Reference. Wszystko inne kończy się niepowodzeniem z unsupported_algorithm lub unsupported_transform.
TslFetcher odrzuca adresy URL inne niż HTTPS i stosuje ochronę SSRF przed jakimkolwiek wyjściem. Pod NetworkPolicy::STRICT_OFFLINE serwuje wcześniej zbuforowaną treść lub zgłasza NetworkPolicyViolation; żadne żądanie wychodzące nigdy nie jest wysyłane.

Przypadki brzegowe i tryby awarii

Nieaktualna lista. TslParseException z verifyXml(), assertFresh() lub buildBundle() oznacza, że źródło zaufania jest nieużyteczne. Potraktuj to jako operacyjne niepowodzenie odświeżenia, nie jako werdykt podpisu.
Niekanoniczny nextUpdate. Wartość bez jawnego Z lub numerycznego przesunięcia zgłasza wyjątek zamiast parsować pobłażliwie. ETSI TS 119 612 §5.1.3 nakazuje formę UTC Z; bramka akceptuje również jawne numeryczne przesunięcie i odrzuca wszystko pozostałe.
Dryf czasu użycia. verifyXml() bramkuje w chwili weryfikacji; dokument przechowywany w pamięci poza nextUpdate i tak nie przejdzie późniejszej bramki buildBundle($tsl, $now).
Pusta konfiguracja kotwic. TslSignatureVerifier odmawia konstrukcji z pustą listą kotwic (InvalidArgumentException).
Brak użytecznych usług. Aktualna lista bez usług CA/QC o statusie granted zgłasza TslParseException z buildBundle(); pusty pakiet nigdy nie jest tworzony.
Postawa offline. STRICT_OFFLINE bez zbuforowanej treści zgłasza NetworkPolicyViolation. Odczyt z bufora poprzedza kontrolę polityki, więc zbuforowana lista utrzymuje działanie walidacji w środowisku air-gapped.
Odpowiedź zbyt duża lub pusta. fetch() czyta co najwyżej $maxBytes bajtów (domyślnie 16 MiB); obcięta lista następnie nie przechodzi weryfikacji skrótu w dalszej części potoku. Pusta treść zgłasza TslFetchException.
DOCTYPE w XML. Każdy DOCTYPE jest odrzucany, zanim libxml zbuduje tablicę encji, oraz ponownie po załadowaniu. Zamyka to klasy wejścia XXE i ekspansji encji (billion-laughs).
Wiele podpisów. Tylko zweryfikowany otoczkowy ds:Signature jest usuwany przed obliczeniem skrótu; podpisy równorzędne i kontrasygnaty są zachowywane. Dodatkowe referencje XAdES są dozwolone, ale dokładnie jeden ds:Reference musi pokrywać korzeń dokumentu.
Wygasły materiał łańcucha. Wygasły lub jeszcze nieważny podpisujący, pośrednik lub kotwica kończy się niepowodzeniem z przyczyną expired_anchor. clockTolerance symetrycznie poszerza okno akceptacji i domyślnie wynosi 0.

Zachowanie w trybie FIPS

Lista dozwolonych weryfikatora jest ustalona na RSA i ECDSA z rodziną SHA-2; SHA-1 i MD5 są strukturalnie wykluczone. Arytmetyka podpisu działa w dołączonej programowej kryptografii (phpseclib). NextPDF nie formułuje żadnego roszczenia o walidacji FIPS 140-3 dla tej arytmetyki. Profil polityki kryptograficznej FIPS 140-3 dla Enterprise jest udokumentowany przy module bezpieczeństwa; ogranicza on wybór algorytmów i nie zmienia struktur list zaufania ani fail-closed zachowania tego modułu.

Zgodność

Twierdzenie	Standard	Klauzula
Lista zaufania, której Next update minął, jest odrzucana jako wygasła.	ETSI TS 119 612	§5.3.15
Pola daty i czasu to łańcuchy ISO 8601 w UTC z oznacznikiem `Z`.	ETSI TS 119 612	§5.1.3
Operator schematu podpisuje listę zaufania dla autentyczności i integralności.	ETSI TS 119 612	§5.7.1
Status usługi kwalifikowanej to URI statusu granted lub withdrawn.	ETSI TS 119 612	§5.5.4
Kwalifikowane CA jest identyfikowane przez URI typu usługi `Svctype/CA/QC`.	ETSI TS 119 612	§5.5.1.1
Numer sekwencji TSL zaczyna się od 1 i inkrementuje przy każdym wydaniu.	ETSI TS 119 612	§5.3.2

Wszystkie klauzule są sparafrazowane; NextPDF nie reprodukuje tekstu normatywnego. NextPDF nie formułuje żadnego roszczenia o zgodności z ETSI TS 119 612 ani żadnego roszczenia o certyfikacji eIDAS. Skonsumowanie listy zaufania nie czyni podpisu, certyfikatu ani wyniku NextPDF „kwalifikowanym”; kwalifikacja należy do dostawcy usług zaufania pod nadzorem państwa członkowskiego, a skutek prawny leży poza tym modułem. Ograniczenia modelu przetwarzania XMLDSig (transformacja podpisu otoczkowego, kanonikalizacja ekskluzywna, referencja pokrywająca korzeń) są udokumentowane z profilu weryfikacji produktu; specyfikacja W3C XML Signature leży poza cytowanym zbiorem dowodów. Ten moduł rozstrzyga wyłącznie, czy lista jest akceptowalna jako wejście zaufania; walidacja ścieżki certyfikacji względem wynikowych kotwic należy do warstwy walidacji certyfikatów.

Uwagi deweloperskie

Zależności to interfejsy PSR: klient PSR-18, fabryka żądań PSR-17 oraz opcjonalny bufor PSR-16. Wstrzykuj atrapy w pamięci w testach; żaden etap nie wymaga dostępu do żywej sieci poza zimnym fetch().
Przypnij górną kotwicę poza pasmem. Dla list państw członkowskich kotwica LOTL autoryzuje podpisujących listy; weryfikator nigdy nie bootstrapuje zaufania z treści KeyInfo.
Odpytywanie w tle, przetwarzanie pivot-LOTL oraz uwierzytelnianie mutual-TLS lub proxy są poza zakresem fetchera w tej wersji. Zaplanuj odświeżanie zewnętrznie i pobieraj ponownie przed każdym nextUpdate.
Przekazuj moment walidacji, nie moment konstrukcji, do buildBundle(). Odbudowuj pakiet po każdym odświeżeniu; nigdy nie buforuj pakietu poza nextUpdate listy źródłowej.
bundleVersion ma obserwowalny kształt tsl-<territory>-seq<sequenceNumber>; rawXmlSha256 w TslDocument wspiera rekordy dowodowe i wykrywanie powtórzeń.
Zniekształcone wpisy usług parsują się z defensywnymi wartościami zastępczymi; zniekształcona tożsamość cyfrowa docierająca do konstrukcji pakietu kończy się fail-closed z InvalidArgumentException.
Klasy niosą adnotacje źródłowe pakietu @since 1.10.0 (TslFetchException: 3.2.0). TslDocument, TspService i TspServiceQualifier mają adnotację źródłową @api.

Zobacz też

Poziomy zaufania eIDAS — strona funkcji, która mapuje dowody list zaufania na Poziomy Zaufania (Levels of Assurance).
Kontenery ASiC — konsument TslTrustAnchorProvider::buildBundle() dla wiązania zaufania kontenera.
Weryfikacja podpisu — strona weryfikacji AdES/PAdES konsumująca kotwice zaufania.
Bezpieczeństwo — pogłębiony materiał referencyjny — połączona powierzchnia bezpieczeństwa Enterprise.
Podpis — pogłębiony materiał referencyjny — producent długoterminowy PAdES B-LT i B-LTA.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz wspieraną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.