Enterprise edisi

Trusted list — Referensi Mendalam

Sekilas pandang

Halaman ini adalah referensi mendalam untuk permukaan trusted-list di NextPDF Enterprise. Permukaan tersebut adalah dua belas kelas publik dari namespace NextPDF\Enterprise\Security\Tsl. NextPDF\Enterprise\Security\Tsl\TslPolicyEnforcer adalah titik masuk yang diorkestrasi: ia mengembalikan sebuah TslDocument hanya ketika HTTP fetch, verifikasi XMLDSig, parse struktural, dan gate staleness nextUpdate semuanya lolos. TslTrustAnchorProvider::buildBundle() kemudian menurunkan bundle trust-anchor dari layanan CA/QC aktif, menegaskan kembali freshness pada instant yang dipasok oleh pemanggil sebelum anchor apa pun diekstraksi. Setiap kegagalan memunculkan exception bertipe; tidak ada tahap yang terdegradasi secara diam-diam. Pipeline mendukung verifikasi trusted list negara anggota UE dan trust anchor bersumber LOTL (List of Trusted Lists) ketika dipasok oleh pemanggil; penemuan LOTL otomatis, polling, dan pemrosesan pivot berada di luar cakupan.

Ketersediaan & lisensi

Kapabilitas ini dikirimkan dalam NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan envelope lisensi tier Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Permukaan API publik

Symbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
`TslPolicyEnforcer`	`TslFetcher $fetcher`, `TslSignatureVerifier $verifier`, `TslXmlParser $parser`	Menggabungkan fetch, verifikasi tanda tangan, parse, dan gate staleness menjadi satu titik masuk	—	Meneruskan exception pipeline di bawah ini	`final`; fail-closed secara konstruksi
`TslPolicyEnforcer::fetchAndVerify`	`string $url`	Mengambil satu TSL, lalu menjalankan `verifyXml()` pada byte-nya	`TslDocument`	`TslFetchException`, `NetworkPolicyViolation`, `TslSignatureException`, `TslParseException`	Mengembalikan hanya ketika keempat tahap lolos
`TslPolicyEnforcer::verifyXml`	`string $xml`	Memverifikasi tanda tangan, mem-parse, dan menolak daftar yang usang	`TslDocument`	`TslSignatureException`, `TslParseException`	Staleness dievaluasi terhadap waktu sistem saat ini
`TslFetcher`	`ClientInterface $httpClient`, `RequestFactoryInterface $requestFactory`, `?CacheInterface $cache = null`, `int $defaultTtlSeconds = 3600`, `int $maxBytes = 16_777_216`, `NetworkPolicy $networkPolicy = NetworkPolicy::ONLINE`	Pengambilan TSL/LOTL khusus HTTPS dengan caching berbasis ETag	—	—	`final`; SSRF guard memblokir host privat, loopback, link-local, dan metadata dengan mitigasi DNS-rebinding
`TslFetcher::fetch`	`string $url`	GET dengan revalidasi `If-None-Match`; men-cache body plus ETag di bawah TTL yang dikonfigurasi	`string` (byte XML mentah)	`TslFetchException`, `NetworkPolicyViolation`	Membaca paling banyak `$maxBytes` byte; di bawah `STRICT_OFFLINE` hanya body yang di-cache yang dilayani
`TslSignatureVerifier`	`array $trustAnchorsPem`, `int $clockTolerance = 0`	Verifier XMLDSig yang di-pin ke trust anchor yang dikonfigurasi	—	`InvalidArgumentException` ketika daftar anchor kosong	`final`; allowlist di `ALLOWED_SIG_ALG` dan `ALLOWED_DIGEST_ALG`
`TslSignatureVerifier::verify`	`string $xml`	Memverifikasi tanda tangan XMLDSig enveloped secara fail-closed	`string` (PEM sertifikat penanda tangan)	`TslSignatureException` dengan reason code yang dapat dibaca mesin	Sertifikat KeyInfo tidak pernah dipercaya sendirian; penanda tangan harus terangkai ke anchor yang dikonfigurasi
`TslXmlParser::parse`	`string $xml`	Parse struktural menjadi `TslDocument`; agnostik terhadap tanda tangan	`TslDocument`	`TslParseException`	Menolak DOCTYPE apa pun secara fail-closed sebelum parsing; memuat dengan `LIBXML_NONET`; pemanggil harus memverifikasi sebelum memercayai hasilnya
`TslTrustAnchorProvider::buildBundle`	`TslDocument $tsl`, `DateTimeImmutable $now`	Menegaskan freshness terlebih dahulu, lalu mengumpulkan sertifikat layanan CA/QC aktif	`EnterpriseCaTrustAnchorBundle`	`TslParseException`	Gate freshness mendahului ekstraksi anchor apa pun; result set kosong melempar
`TslDocument`	Delapan properti `readonly` yang dipromosikan (lihat fence konstruktor)	Value object TSL yang di-parse dan immutable	—	—	`final readonly`; ber-anotasi sumber `@api`
`TslDocument::isStale`	`DateTimeImmutable $now`	Membandingkan `nextUpdate` terhadap `$now` setelah parse UTC yang fail-closed	`bool`	`TslParseException`	Memerlukan designator `Z` eksplisit atau numeric-offset
`TslDocument::assertFresh`	`DateTimeImmutable $now`	Melempar ketika daftar usang atau `nextUpdate` tidak dapat di-parse	`void`	`TslParseException`	Gate freshness pada batas konsumen
`TslDocument::servicesOfType`	`string $serviceTypeIdentifier`	Menyaring layanan berdasarkan URI service-type ETSI	`list<TspService>`	Tidak melempar	—
`TslDocument::activeServices`	—	Mengembalikan layanan hanya dalam status granted	`list<TspService>`	Tidak melempar	Granted berarti `TspService::STATUS_GRANTED`
`TspService`	Delapan properti `readonly` yang dipromosikan	Satu entri trust-service di dalam sebuah TSL	—	—	`final readonly`; konstanta untuk status dan URI service-type
`TspService::isGranted`	—	Kesetaraan status terhadap URI granted	`bool`	Tidak melempar	—
`TspService::isQualifiedCa`	—	Kesetaraan tipe terhadap URI CA/QC	`bool`	Tidak melempar	—
`TspServiceQualifier`	`string $qualifierUri`, `string $criteriaListAssert = 'all'`, `array $policyOidConditions = []`, `array $keyUsageConditions = []`	Satu qualifier layanan ETSI dengan kriteria opsional	—	—	`final readonly`; konstanta `FOR_ESIG`, `FOR_ESEAL`, `FOR_WSA`, `QSCD_STATEMENT`, `NO_QSCD`
`EnterpriseCaTrustAnchorBundle`	`array $anchorsPem`, `string $bundleVersion`, `string $bundleSha256`	Bundle anchor yang di-pin; memvalidasi digest yang dipasok terhadap anchor yang dipasok saat konstruksi	—	`InvalidArgumentException`	Peroleh dari `buildBundle()`; jangan konstruksi secara manual; mengimplementasikan `TrustAnchorStoreInterface`
`EnterpriseCaTrustAnchorBundle::containsFingerprint`	`string $anchorDerSha256Hex`	Keanggotaan anchor berdasarkan hex SHA-256 atas body DER	`bool`	Tidak melempar	—
`EnterpriseCaTrustAnchorBundle::computeBundleSha256`	`array $anchorsPem`	SHA-256 kanonis atas konkatenasi PEM yang di-normalisasi newline	`string`	Tidak melempar	`static`
`TslFetchException`	—	Menandakan pengambilan TSL yang gagal	—	—	`final`; meng-extend `RuntimeException`
`TslParseException`	—	Menandakan kegagalan struktural atau freshness	—	—	`final`; meng-extend `RuntimeException`
`TslSignatureException`	`string $reason`, `string $message`	Menandakan kegagalan verifikasi XMLDSig dengan reason code	—	—	`final`; `readonly` publik `$reason` (lihat reason code di bawah)

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)

Reason code TslSignatureException: missing_signature, untrusted_signer, invalid_signature, digest_mismatch, unsupported_algorithm, unsupported_transform, expired_anchor.

Kontrak perilaku

Urutan pipeline bersifat tetap: fetch, verifikasi XMLDSig, parse struktural, gate staleness. TslPolicyEnforcer mengembalikan sebuah TslDocument hanya ketika keempatnya berhasil. Sebuah trusted list ditandatangani oleh operator skemanya sehingga relying party dapat memeriksa autentisitas dan integritas — ETSI TS 119 612 §5.7.1.
TslXmlParser secara desain agnostik terhadap tanda tangan. Pemanggil harus memverifikasi tanda tangan sebelum memercayai field yang di-parse mana pun. TslPolicyEnforcer::verifyXml() menegakkan urutan tersebut.
Invarian freshness ditegakkan di setiap batas konsumen. Sebuah daftar yang nextUpdate-nya telah lewat sudah kedaluwarsa dan ditolak — ETSI TS 119 612 §5.3.15. verifyXml() mem-gate terhadap waktu sistem saat ini; TslDocument::assertFresh() dan buildBundle() mem-gate terhadap instant yang dipasok pemanggil.
Parse freshness bersifat fail-closed. Field date-time adalah nilai UTC ISO 8601 dengan designator eksplisit — ETSI TS 119 612 §5.1.3. Sebuah nextUpdate tanpa Z eksplisit atau numeric offset memunculkan TslParseException; nilai tersebut tidak pernah ditafsirkan ulang dalam timezone lokal server.
buildBundle() memanggil assertFresh($now) sebelum mengekstraksi anchor apa pun, lalu hanya menerima layanan yang sekaligus granted dan CA/QC. Granted dan withdrawn adalah URI status layanan berkualifikasi — ETSI TS 119 612 §5.5.4. CA/QC adalah URI service-type CA berkualifikasi — ETSI TS 119 612 §5.5.1.1.
Versi bundle diturunkan dari teritori skema dan nomor urut TSL. Nomor urut bersifat monotonik lintas rilis — ETSI TS 119 612 §5.3.2. Digest bundle adalah SHA-256 kanonis atas PEM anchor, dan containsFingerprint() menjawab keanggotaan berdasarkan SHA-256 DER.
Verifier hanya memercayai anchor yang dikonfigurasi. Sertifikat yang ditemukan di KeyInfo berfungsi sebagai leaf penanda tangan dan kandidat intermediate; rangkaian harus mencapai anchor yang dikonfigurasi dalam kedalaman 8, setiap link harus valid secara temporal, dan sertifikat penerbit harus membawa basicConstraints cA=TRUE (plus keyCertSign ketika keyUsage ada).
Profil verifikasi adalah sebuah allowlist: RSA atau ECDSA dengan SHA-256, SHA-384, atau SHA-512; metode digest SHA-256, SHA-384, atau SHA-512; hanya canonicalization eksklusif; dan tepat pasangan transform enveloped-signature plus exclusive-C14N pada ds:Reference yang mencakup daftar. Apa pun selain itu gagal dengan unsupported_algorithm atau unsupported_transform.
TslFetcher menolak URL non-HTTPS dan menerapkan SSRF guard sebelum egress apa pun. Di bawah NetworkPolicy::STRICT_OFFLINE ia melayani body yang sebelumnya di-cache atau memunculkan NetworkPolicyViolation; tidak ada permintaan keluar yang pernah dikirim.

Edge case & mode kegagalan

Daftar usang. TslParseException dari verifyXml(), assertFresh(), atau buildBundle() berarti sumber trust tidak dapat digunakan. Perlakukan sebagai kegagalan refresh operasional, bukan verdict tanda tangan.
nextUpdate non-kanonis. Sebuah nilai tanpa Z eksplisit atau numeric offset akan melempar alih-alih di-parse secara longgar. ETSI TS 119 612 §5.1.3 mewajibkan bentuk UTC Z; gate juga menerima numeric offset eksplisit dan menolak selain itu.
Drift waktu-pemakaian. verifyXml() mem-gate pada waktu verifikasi; sebuah dokumen yang ditahan di memori melewati nextUpdate tetap gagal pada gate buildBundle($tsl, $now) berikutnya.
Konfigurasi anchor kosong. TslSignatureVerifier menolak konstruksi dengan daftar anchor kosong (InvalidArgumentException).
Tidak ada layanan yang dapat digunakan. Sebuah daftar segar tanpa layanan CA/QC granted memunculkan TslParseException dari buildBundle(); bundle kosong tidak pernah diproduksi.
Postur offline. STRICT_OFFLINE tanpa body yang di-cache memunculkan NetworkPolicyViolation. Pencarian cache mendahului pemeriksaan policy, sehingga daftar yang di-cache menjaga validasi air-gapped tetap berfungsi.
Respons kebesaran atau kosong. fetch() membaca paling banyak $maxBytes byte (default 16 MiB); sebuah daftar yang terpotong lalu gagal verifikasi digest di hilir. Body kosong memunculkan TslFetchException.
DOCTYPE dalam XML. DOCTYPE apa pun ditolak sebelum libxml membangun tabel entitas, dan lagi setelah load. Ini menutup kelas input XXE dan entity-expansion (billion-laughs).
Banyak tanda tangan. Hanya ds:Signature enveloped yang terverifikasi yang dihapus sebelum komputasi digest; tanda tangan sibling dan counter-signature dipertahankan. Reference XAdES tambahan diperbolehkan, tetapi tepat satu ds:Reference harus mencakup root dokumen.
Material rangkaian kedaluwarsa. Penanda tangan, intermediate, atau anchor yang kedaluwarsa atau belum valid gagal dengan reason expired_anchor. clockTolerance memperlebar jendela penerimaan secara simetris dan default-nya 0.

Perilaku mode-FIPS

Allowlist verifier terpaku pada RSA dan ECDSA dengan keluarga SHA-2; SHA-1 dan MD5 dikecualikan secara struktural. Aritmetika tanda tangan berjalan dalam kriptografi perangkat lunak yang di-bundle (phpseclib). NextPDF tidak membuat klaim validasi FIPS 140-3 untuk aritmetika tersebut. Profil crypto-policy FIPS 140-3 Enterprise didokumentasikan bersama modul security; ia membatasi pemilihan algoritma dan tidak mengubah struktur trusted-list atau perilaku fail-closed modul ini.

Konformansi

Klaim	Standar	Klausa
Sebuah trusted list yang Next update-nya telah lewat dibuang sebagai kedaluwarsa.	ETSI TS 119 612	§5.3.15
Field date-time adalah string ISO 8601 dalam UTC dengan designator `Z`.	ETSI TS 119 612	§5.1.3
Operator skema menandatangani trusted list untuk autentisitas dan integritas.	ETSI TS 119 612	§5.7.1
Status layanan berkualifikasi adalah URI status granted atau withdrawn.	ETSI TS 119 612	§5.5.4
Sebuah CA berkualifikasi diidentifikasi oleh URI service-type `Svctype/CA/QC`.	ETSI TS 119 612	§5.5.1.1
Nomor urut TSL dimulai dari 1 dan bertambah pada setiap rilis.	ETSI TS 119 612	§5.3.2

Semua klausa diparafrasekan; NextPDF tidak mereproduksi teks normatif. NextPDF tidak membuat klaim konformansi ETSI TS 119 612 dan tidak membuat klaim sertifikasi eIDAS. Mengonsumsi sebuah trusted list tidak menjadikan sebuah tanda tangan, sertifikat, atau output NextPDF “qualified”; kualifikasi adalah milik trust service provider di bawah supervisi negara anggota, dan efek hukum berada di luar modul ini. Batasan model-pemrosesan XMLDSig (transform enveloped-signature, canonicalization eksklusif, reference yang mencakup root) didokumentasikan dari profil verifikasi produk; spesifikasi W3C XML Signature berada di luar himpunan bukti yang dikutip. Modul ini hanya memutuskan apakah sebuah daftar dapat diterima sebagai input trust; validasi certificate-path terhadap anchor yang dihasilkan adalah milik lapisan certificate-validation.

Catatan pengembangan

Dependensi adalah interface PSR: klien PSR-18, request factory PSR-17, dan cache PSR-16 opsional. Injeksikan double in-memory dalam test; tidak ada tahap yang memerlukan akses jaringan live kecuali fetch() dingin.
Pin anchor teratas secara out of band. Untuk daftar negara anggota, anchor LOTL mengotorisasi penanda tangan daftar; verifier tidak pernah mem-bootstrap trust dari konten KeyInfo.
Background polling, pemrosesan pivot-LOTL, dan autentikasi mutual-TLS atau proxy berada di luar cakupan fetcher dalam versi ini. Jadwalkan refresh secara eksternal dan fetch ulang sebelum setiap nextUpdate.
Berikan instant validasi, bukan instant konstruksi, ke buildBundle(). Bangun ulang bundle setelah setiap refresh; jangan pernah men-cache sebuah bundle melewati nextUpdate daftar sumber.
bundleVersion memiliki bentuk yang dapat diamati tsl-<territory>-seq<sequenceNumber>; rawXmlSha256 pada TslDocument mendukung record bukti dan deteksi replay.
Entri layanan yang malformed di-parse dengan nilai placeholder defensif; identitas digital yang malformed yang mencapai konstruksi bundle gagal-tertutup dengan InvalidArgumentException.
Kelas-kelas membawa anotasi sumber paket @since 1.10.0 (TslFetchException: 3.2.0). TslDocument, TspService, dan TspServiceQualifier ber-anotasi sumber @api.

Lihat juga

Level assurance eIDAS — halaman kapabilitas yang memetakan bukti trusted-list ke Level of Assurance.
Kontainer ASiC — sebuah konsumen TslTrustAnchorProvider::buildBundle() untuk pengikatan trust kontainer.
Verifikasi tanda tangan — sisi-verify AdES/PAdES yang mengonsumsi trust anchor.
Security — Referensi Mendalam — permukaan security Enterprise gabungan.
Signature — Referensi Mendalam — produser jangka panjang PAdES B-LT dan B-LTA.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Path namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.