Enterprise Edition

Vertrauenslisten — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die Deep Reference für die Vertrauenslisten-Oberfläche in NextPDF Enterprise. Die Oberfläche umfasst die zwölf öffentlichen Klassen des Namespace NextPDF\Enterprise\Security\Tsl. NextPDF\Enterprise\Security\Tsl\TslPolicyEnforcer ist der orchestrierte Einstiegspunkt: Er gibt ein TslDocument nur dann zurück, wenn HTTP-Abruf, XMLDSig-Verifikation, struktureller Parse und das nextUpdate-Aktualitätsgate allesamt bestehen. TslTrustAnchorProvider::buildBundle() leitet daraufhin ein Vertrauensanker-Bündel aus aktiven CA/QC-Diensten ab und prüft die Aktualität zu einem vom Aufrufer angegebenen Zeitpunkt erneut, bevor irgendein Anker extrahiert wird. Jeder Fehlschlag löst eine typisierte Ausnahme aus; keine Stufe degradiert stillschweigend. Die Pipeline unterstützt die Verifikation von Vertrauenslisten der EU-Mitgliedstaaten sowie von aus einer LOTL (List of Trusted Lists) stammenden Vertrauensankern, sofern diese vom Aufrufer bereitgestellt werden; die automatische LOTL-Erkennung, das Polling und die Pivot-Verarbeitung liegen außerhalb des Rahmens.

Verfügbarkeit & Lizenzierung

Diese Funktion wird mit NextPDF Enterprise (nextpdf/enterprise) ausgeliefert und aktiviert sich mit einer Lizenzhülle der Enterprise-Stufe. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und Lizenz erwerben.

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`TslPolicyEnforcer`	`TslFetcher $fetcher`, `TslSignatureVerifier $verifier`, `TslXmlParser $parser`	Vereint Abruf, Signaturverifikation, Parse und Aktualitätsgate in einem Einstiegspunkt	—	Propagiert die unten genannten Pipeline-Ausnahmen	`final`; fail-closed per Konstruktion
`TslPolicyEnforcer::fetchAndVerify`	`string $url`	Ruft eine TSL ab und führt anschließend `verifyXml()` auf den Bytes aus	`TslDocument`	`TslFetchException`, `NetworkPolicyViolation`, `TslSignatureException`, `TslParseException`	Gibt nur zurück, wenn alle vier Stufen bestehen
`TslPolicyEnforcer::verifyXml`	`string $xml`	Verifiziert die Signatur, parst und weist eine veraltete Liste zurück	`TslDocument`	`TslSignatureException`, `TslParseException`	Die Aktualität wird gegen die aktuelle Systemzeit ausgewertet
`TslFetcher`	`ClientInterface $httpClient`, `RequestFactoryInterface $requestFactory`, `?CacheInterface $cache = null`, `int $defaultTtlSeconds = 3600`, `int $maxBytes = 16_777_216`, `NetworkPolicy $networkPolicy = NetworkPolicy::ONLINE`	Ausschließlich HTTPS-basierter TSL/LOTL-Abruf mit ETag-basiertem Caching	—	—	`final`; SSRF-Schutz blockiert private, Loopback-, Link-Local- und Metadaten-Hosts mit DNS-Rebinding-Abwehr
`TslFetcher::fetch`	`string $url`	GET mit `If-None-Match`-Revalidierung; cacht Body plus ETag unter der konfigurierten TTL	`string` (rohe XML-Bytes)	`TslFetchException`, `NetworkPolicyViolation`	Liest höchstens `$maxBytes` Bytes; unter `STRICT_OFFLINE` wird nur ein gecachter Body ausgeliefert
`TslSignatureVerifier`	`array $trustAnchorsPem`, `int $clockTolerance = 0`	XMLDSig-Verifizierer, gepinnt auf die konfigurierten Vertrauensanker	—	`InvalidArgumentException`, wenn die Ankerliste leer ist	`final`; Allowlists in `ALLOWED_SIG_ALG` und `ALLOWED_DIGEST_ALG`
`TslSignatureVerifier::verify`	`string $xml`	Verifiziert die enveloped XMLDSig-Signatur fail-closed	`string` (PEM des Signiererzertifikats)	`TslSignatureException` mit einem maschinenlesbaren Ursachencode	KeyInfo-Zertifikaten wird niemals für sich allein vertraut; der Signierer muss zu einem konfigurierten Anker verketten
`TslXmlParser::parse`	`string $xml`	Struktureller Parse in ein `TslDocument`; signaturagnostisch	`TslDocument`	`TslParseException`	Weist jede DOCTYPE fail-closed vor dem Parsen zurück; lädt mit `LIBXML_NONET`; Aufrufer müssen vor dem Vertrauen in das Ergebnis verifizieren
`TslTrustAnchorProvider::buildBundle`	`TslDocument $tsl`, `DateTimeImmutable $now`	Prüft zunächst die Aktualität, sammelt dann die Zertifikate der aktiven CA/QC-Dienste	`EnterpriseCaTrustAnchorBundle`	`TslParseException`	Das Aktualitätsgate geht jeder Anker-Extraktion voran; eine leere Ergebnismenge wirft
`TslDocument`	Acht promotete `readonly`-Eigenschaften (siehe Konstruktor-Fence)	Unveränderliches geparstes TSL-Wertobjekt	—	—	`final readonly`; quellenannotiert `@api`
`TslDocument::isStale`	`DateTimeImmutable $now`	Vergleicht `nextUpdate` gegen `$now` nach einem fail-closed UTC-Parse	`bool`	`TslParseException`	Erfordert einen expliziten `Z`- oder numerischen Offset-Designator
`TslDocument::assertFresh`	`DateTimeImmutable $now`	Wirft, wenn die Liste veraltet oder `nextUpdate` nicht parsbar ist	`void`	`TslParseException`	Das Aktualitätsgate an der Verbrauchergrenze
`TslDocument::servicesOfType`	`string $serviceTypeIdentifier`	Filtert Dienste nach ETSI-Diensttyp-URI	`list<TspService>`	Wirft nicht	—
`TslDocument::activeServices`	—	Gibt nur Dienste im Status „granted” zurück	`list<TspService>`	Wirft nicht	„Granted” bedeutet `TspService::STATUS_GRANTED`
`TspService`	Acht promotete `readonly`-Eigenschaften	Ein Vertrauensdienst-Eintrag innerhalb einer TSL	—	—	`final readonly`; Konstanten für Status- und Diensttyp-URIs
`TspService::isGranted`	—	Statusgleichheit gegen die granted-URI	`bool`	Wirft nicht	—
`TspService::isQualifiedCa`	—	Typgleichheit gegen die CA/QC-URI	`bool`	Wirft nicht	—
`TspServiceQualifier`	`string $qualifierUri`, `string $criteriaListAssert = 'all'`, `array $policyOidConditions = []`, `array $keyUsageConditions = []`	Ein ETSI-Dienstqualifizierer mit optionalen Kriterien	—	—	`final readonly`; Konstanten `FOR_ESIG`, `FOR_ESEAL`, `FOR_WSA`, `QSCD_STATEMENT`, `NO_QSCD`
`EnterpriseCaTrustAnchorBundle`	`array $anchorsPem`, `string $bundleVersion`, `string $bundleSha256`	Gepinntes Anker-Bündel; validiert den übergebenen Digest gegen die übergebenen Anker bei der Konstruktion	—	`InvalidArgumentException`	Über `buildBundle()` beziehen; nicht von Hand konstruieren; implementiert `TrustAnchorStoreInterface`
`EnterpriseCaTrustAnchorBundle::containsFingerprint`	`string $anchorDerSha256Hex`	Anker-Zugehörigkeit per Hex-SHA-256 über den DER-Body	`bool`	Wirft nicht	—
`EnterpriseCaTrustAnchorBundle::computeBundleSha256`	`array $anchorsPem`	Kanonisches SHA-256 über die zeilennormalisierte PEM-Verkettung	`string`	Wirft nicht	`static`
`TslFetchException`	—	Signalisiert einen fehlgeschlagenen TSL-Abruf	—	—	`final`; erweitert `RuntimeException`
`TslParseException`	—	Signalisiert einen strukturellen oder Aktualitäts-Fehlschlag	—	—	`final`; erweitert `RuntimeException`
`TslSignatureException`	`string $reason`, `string $message`	Signalisiert einen XMLDSig-Verifikationsfehler mit einem Ursachencode	—	—	`final`; öffentliches `readonly` `$reason` (siehe Ursachencodes unten)

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-Ursachencodes: missing_signature, untrusted_signer, invalid_signature, digest_mismatch, unsupported_algorithm, unsupported_transform, expired_anchor.

Verhaltenskontrakt

Die Pipeline-Reihenfolge ist fest: Abruf, XMLDSig-Verifikation, struktureller Parse, Aktualitätsgate. TslPolicyEnforcer gibt ein TslDocument nur zurück, wenn alle vier bestehen. Eine Vertrauensliste wird von ihrem Scheme-Operator signiert, damit sich verlassende Parteien Authentizität und Integrität prüfen können — ETSI TS 119 612 §5.7.1.
TslXmlParser ist per Design signaturagnostisch. Aufrufer müssen die Signatur verifizieren, bevor sie irgendeinem geparsten Feld vertrauen. TslPolicyEnforcer::verifyXml() erzwingt diese Reihenfolge.
Die Aktualitätsinvariante wird an jeder Verbrauchergrenze erzwungen. Eine Liste, deren nextUpdate verstrichen ist, ist abgelaufen und wird verweigert — ETSI TS 119 612 §5.3.15. verifyXml() prüft gegen die aktuelle Systemzeit; TslDocument::assertFresh() und buildBundle() prüfen gegen einen vom Aufrufer angegebenen Zeitpunkt.
Der Aktualitätsparse ist fail-closed. Datum-Zeit-Felder sind ISO-8601-UTC-Werte mit einem expliziten Designator — ETSI TS 119 612 §5.1.3. Ein nextUpdate ohne einen expliziten Z oder numerischen Offset löst TslParseException aus; der Wert wird niemals in der lokalen Zeitzone des Servers reinterpretiert.
buildBundle() ruft assertFresh($now) auf, bevor irgendein Anker extrahiert wird, und lässt dann nur Dienste zu, die sowohl granted als auch CA/QC sind. Granted und withdrawn sind die Status-URIs des qualifizierten Dienstes — ETSI TS 119 612 §5.5.4. CA/QC ist die Diensttyp-URI der qualifizierten CA — ETSI TS 119 612 §5.5.1.1.
Die Bündelversion wird aus dem Scheme-Territorium und der TSL-Sequenznummer abgeleitet. Die Sequenznummer ist über Releases hinweg monoton — ETSI TS 119 612 §5.3.2. Der Bündel-Digest ist ein kanonisches SHA-256 über die Anker-PEMs, und containsFingerprint() beantwortet die Zugehörigkeit per DER-SHA-256.
Der Verifizierer vertraut nur konfigurierten Ankern. In KeyInfo gefundene Zertifikate dienen als Signierer-Leaf und als Kandidaten-Zwischenzertifikate; die Kette muss innerhalb einer Tiefe von 8 einen konfigurierten Anker erreichen, jedes Glied muss zeitlich gültig sein, und ein ausstellendes Zertifikat muss basicConstraints cA=TRUE tragen (plus keyCertSign, wenn keyUsage vorhanden ist).
Das Verifikationsprofil ist eine Allowlist: RSA oder ECDSA mit SHA-256, SHA-384 oder SHA-512; Digest-Methoden SHA-256, SHA-384 oder SHA-512; ausschließlich exklusive Kanonisierung; und exakt das Paar aus enveloped-signature plus exklusivem C14N-Transform auf der listenabdeckenden ds:Reference. Alles andere scheitert mit unsupported_algorithm oder unsupported_transform.
TslFetcher verweigert Nicht-HTTPS-URLs und wendet vor jedem Egress einen SSRF-Schutz an. Unter NetworkPolicy::STRICT_OFFLINE liefert er einen zuvor gecachten Body aus oder löst NetworkPolicyViolation aus; es wird niemals eine ausgehende Anfrage gesendet.

Randfälle & Fehlermodi

Veraltete Liste. Eine TslParseException aus verifyXml(), assertFresh() oder buildBundle() bedeutet, dass die Vertrauensquelle unbrauchbar ist. Behandeln Sie dies als betrieblichen Aktualisierungsfehler, nicht als Signaturbefund.
Nicht-kanonisches nextUpdate. Ein Wert ohne einen expliziten Z oder numerischen Offset wirft, anstatt nachsichtig zu parsen. ETSI TS 119 612 §5.1.3 schreibt die UTC-Z-Form vor; das Gate akzeptiert zudem einen expliziten numerischen Offset und weist alles andere zurück.
Zeitpunkt-der-Nutzung-Drift. verifyXml() prüft zum Verifikationszeitpunkt; ein über nextUpdate hinaus im Speicher gehaltenes Dokument scheitert dennoch am späteren buildBundle($tsl, $now)-Gate.
Leere Ankerkonfiguration. TslSignatureVerifier verweigert die Konstruktion mit einer leeren Ankerliste (InvalidArgumentException).
Keine nutzbaren Dienste. Eine aktuelle Liste ohne granted CA/QC-Dienste löst eine TslParseException aus buildBundle() aus; ein leeres Bündel wird niemals erzeugt.
Offline-Haltung. STRICT_OFFLINE ohne gecachten Body löst NetworkPolicyViolation aus. Die Cache-Suche geht der Policy-Prüfung voran, sodass eine gecachte Liste die Air-Gap-Validierung funktionsfähig hält.
Übergroße oder leere Antwort. fetch() liest höchstens $maxBytes Bytes (Standard 16 MiB); eine abgeschnittene Liste scheitert dann nachgelagert an der Digest-Verifikation. Ein leerer Body löst TslFetchException aus.
DOCTYPE im XML. Jede DOCTYPE wird zurückgewiesen, bevor libxml eine Entitätstabelle aufbaut, und erneut nach dem Laden. Dies schließt die Eingabeklassen XXE und Entitätsexpansion (Billion-Laughs).
Mehrfache Signaturen. Nur die verifizierte enveloped ds:Signature wird vor der Digest-Berechnung entfernt; Geschwistersignaturen und Gegensignaturen bleiben erhalten. Zusätzliche XAdES-References sind zulässig, aber genau eine ds:Reference muss die Dokumentwurzel abdecken.
Abgelaufenes Kettenmaterial. Ein abgelaufener oder noch nicht gültiger Signierer, ein Zwischenzertifikat oder Anker scheitert mit der Ursache expired_anchor. clockTolerance verbreitert das Akzeptanzfenster symmetrisch und ist standardmäßig 0.

Verhalten im FIPS-Modus

Die Allowlist des Verifizierers ist auf RSA und ECDSA mit der SHA-2-Familie fixiert; SHA-1 und MD5 sind strukturell ausgeschlossen. Die Signaturarithmetik läuft in gebündelter Software-Kryptografie (phpseclib). NextPDF erhebt keinen FIPS-140-3-Validierungsanspruch für diese Arithmetik. Das Enterprise-FIPS-140-3-Krypto-Policy-Profil ist beim Sicherheitsmodul dokumentiert; es schränkt die Algorithmusauswahl ein und verändert weder die Vertrauenslisten-Strukturen noch das fail-closed-Verhalten dieses Moduls.

Konformität

Aussage	Standard	Klausel
Eine Vertrauensliste, deren Next update verstrichen ist, wird als abgelaufen verworfen.	ETSI TS 119 612	§5.3.15
Datum-Zeit-Felder sind ISO-8601-Zeichenketten in UTC mit dem `Z`-Designator.	ETSI TS 119 612	§5.1.3
Der Scheme-Operator signiert die Vertrauensliste für Authentizität und Integrität.	ETSI TS 119 612	§5.7.1
Der Status des qualifizierten Dienstes ist die granted- oder withdrawn-Status-URI.	ETSI TS 119 612	§5.5.4
Eine qualifizierte CA wird durch die `Svctype/CA/QC`-Diensttyp-URI identifiziert.	ETSI TS 119 612	§5.5.1.1
Die TSL-Sequenznummer beginnt bei 1 und inkrementiert bei jedem Release.	ETSI TS 119 612	§5.3.2

Alle Klauseln sind paraphrasiert; NextPDF reproduziert keinen normativen Text. NextPDF erhebt keinen ETSI-TS-119-612-Konformitätsanspruch und keinen eIDAS-Zertifizierungsanspruch. Das Konsumieren einer Vertrauensliste macht weder eine Signatur, ein Zertifikat noch eine NextPDF-Ausgabe „qualifiziert”; die Qualifikation obliegt dem Vertrauensdiensteanbieter unter der Aufsicht des Mitgliedstaats, und die Rechtswirkung liegt außerhalb dieses Moduls. Die Einschränkungen des XMLDSig-Verarbeitungsmodells (enveloped-signature transform, exklusive Kanonisierung, wurzelabdeckende Reference) sind aus dem Verifikationsprofil des Produkts dokumentiert; die W3C-XML-Signature-Spezifikation liegt außerhalb des zitierten Evidenzsatzes. Dieses Modul entscheidet nur, ob eine Liste als Vertrauenseingabe akzeptabel ist; die Zertifikatspfad-Validierung gegen die resultierenden Anker obliegt der Zertifikatsvalidierungsschicht.

Entwicklungshinweise

Die Abhängigkeiten sind PSR-Schnittstellen: ein PSR-18-Client, eine PSR-17-Request-Factory und ein optionaler PSR-16-Cache. Injizieren Sie In-Memory-Doubles in Tests; keine Stufe erfordert Live-Netzwerkzugriff außer einem kalten fetch().
Pinnen Sie den obersten Anker out of band. Für Vertrauenslisten von Mitgliedstaaten autorisiert der LOTL-Anker die Listensignierer; der Verifizierer bootstrappt Vertrauen niemals aus KeyInfo-Inhalten.
Hintergrund-Polling, Pivot-LOTL-Verarbeitung sowie Mutual-TLS- oder Proxy-Authentifizierung liegen in dieser Version außerhalb des Rahmens des Fetchers. Planen Sie die Aktualisierung extern und rufen Sie vor jedem nextUpdate erneut ab.
Übergeben Sie an buildBundle() den Validierungszeitpunkt, nicht den Konstruktionszeitpunkt. Bauen Sie das Bündel nach jeder Aktualisierung neu auf; cachen Sie ein Bündel niemals über das nextUpdate der Quellliste hinaus.
bundleVersion hat die beobachtbare Form tsl-<territory>-seq<sequenceNumber>; rawXmlSha256 auf TslDocument unterstützt Evidenzaufzeichnungen und Replay-Erkennung.
Fehlerhafte Dienst-Einträge parsen mit defensiven Platzhalterwerten; eine fehlerhafte digitale Identität, die die Bündelkonstruktion erreicht, scheitert fail-closed mit InvalidArgumentException.
Die Klassen tragen die Paket-Quellenannotation @since 1.10.0 (TslFetchException: 3.2.0). TslDocument, TspService und TspServiceQualifier sind quellenannotiert @api.

Siehe auch

eIDAS-Vertrauensniveaus — die Capability-Seite, die Vertrauenslisten-Evidenz auf Levels of Assurance abbildet.
ASiC-Container — ein Konsument von TslTrustAnchorProvider::buildBundle() für die Container-Vertrauensbindung.
Signaturverifikation — die AdES/PAdES-Verifikationsseite, die Vertrauensanker konsumiert.
Sicherheit — Deep Reference — die kombinierte Enterprise-Sicherheitsoberfläche.
Signatur — Deep Reference — der PAdES-B-LT- und -B-LTA-Langzeitproduzent.

Publikationsgrenze

Diese Seite dokumentiert ausschließlich das extern beobachtbare Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Rahmens.