القوائم الموثوقة — مرجع متعمّق

في لمحة

هذه الصفحة هي المرجع المتعمّق لسطح القوائم الموثوقة في ⁨NextPDF⁩ Enterprise. السطح هو الفئات العامة الاثنتا عشرة لمساحة الاسم NextPDF\Enterprise\Security\Tsl. الصنف NextPDF\Enterprise\Security\Tsl\TslPolicyEnforcer هو نقطة الدخول المنسَّقة: فهو يُرجع ⁨TslDocument⁩ فقط عندما تنجح جميع مراحل جلب ⁨HTTP⁩ والتحقق بـ ⁨XML⁩DSig والتحليل البنيوي وبوابة تقادم ⁨nextUpdate⁩. ثم يشتق ⁨TslTrustAnchorProvider::buildBundle()⁩ حزمة مراسي ثقة من خدمات CA/QC النشطة، مؤكّدًا الحداثة من جديد عند لحظة يوفّرها المستدعي قبل استخراج أي مرساة. كل إخفاق يرفع استثناءً مُنمَّطًا؛ ولا تتدهور أي مرحلة بصمت. يدعم خط الأنابيب التحقق من القوائم الموثوقة للدول الأعضاء في الاتحاد الأوروبي ومن مراسي الثقة المستمدّة من LOTL (List of Trusted Lists) عندما يوفّرها المستدعي؛ أما اكتشاف LOTL التلقائي والاستطلاع الدوري ومعالجة المحاور (pivot) فهي خارج النطاق.

التوفّر والترخيص

تُشحن هذه القدرة ضمن ⁨NextPDF⁩ Enterprise (nextpdf/enterprise) وتُفعَّل بمظروف ترخيص من فئة Enterprise. أي نشر دون هذا الاستحقاق لا يحمّل أصناف هذه القدرة. قارن الإصدارات واحصل على ترخيص.

سطح الـ ⁨API⁩ العام

الرمز	المعاملات	السلوك الافتراضي	القيمة المُرجَعة	يرمي أو يفشل بـ	ملاحظات
TslPolicyEnforcer	TslFetcher $fetcher, TslSignatureVerifier $verifier, TslXmlParser $parser	يجمع الجلب والتحقق من التوقيع والتحليل وبوابة التقادم في نقطة دخول واحدة	—	يمرّر استثناءات خط الأنابيب أدناه	final؛ مغلق-عند-الفشل بحكم البناء
TslPolicyEnforcer::fetchAndVerify	string $url	يجلب قائمة TSL واحدة، ثم يشغّل verifyXml() على البايتات	TslDocument	TslFetchException, NetworkPolicyViolation, TslSignatureException, TslParseException	يُرجع فقط عند نجاح المراحل الأربع جميعها
TslPolicyEnforcer::verifyXml	string $xml	يتحقق من التوقيع، ويحلّل، ويرفض قائمة متقادمة	TslDocument	TslSignatureException, TslParseException	يُقيَّم التقادم مقابل وقت النظام الحالي
TslFetcher	ClientInterface $httpClient, RequestFactoryInterface $requestFactory, ?CacheInterface $cache = null, int $defaultTtlSeconds = 3600, int $maxBytes = 16_777_216, NetworkPolicy $networkPolicy = NetworkPolicy::ONLINE	استرجاع TSL/LOTL عبر HTTPS حصريًا مع تخزين مؤقت قائم على ETag	—	—	final؛ حارس SSRF يحجب المضيفات الخاصة وحلقة الاسترجاع والرابط-المحلي والبيانات-الوصفية مع تخفيف إعادة-ربط DNS
TslFetcher::fetch	string $url	GET مع إعادة تحقق If-None-Match؛ يخزّن الجسم مع ETag تحت الـ TTL المُهيّأ	string (بايتات XML الخام)	TslFetchException, NetworkPolicyViolation	يقرأ $maxBytes بايت كحد أقصى؛ وتحت STRICT_OFFLINE يُقدَّم الجسم المخزَّن مؤقتًا فقط
TslSignatureVerifier	array $trustAnchorsPem, int $clockTolerance = 0	مُتحقِّق XMLDSig مثبَّت على مراسي الثقة المُهيّأة	—	InvalidArgumentException عندما تكون قائمة المراسي فارغة	final؛ قوائم سماح في ALLOWED_SIG_ALG وALLOWED_DIGEST_ALG
TslSignatureVerifier::verify	string $xml	يتحقق من توقيع XMLDSig المغلَّف بأسلوب مغلق-عند-الفشل	string (PEM شهادة الموقِّع)	TslSignatureException برمز سبب قابل للقراءة آليًا	لا يُوثَق بشهادات KeyInfo بمفردها أبدًا؛ يجب أن يتسلسل الموقِّع إلى مرساة مُهيّأة
TslXmlParser::parse	string $xml	تحليل بنيوي إلى TslDocument؛ محايد تجاه التوقيع	TslDocument	TslParseException	يرفض أي DOCTYPE بأسلوب مغلق-عند-الفشل قبل التحليل؛ يحمّل بـ LIBXML_NONET؛ على المستدعين التحقق قبل الوثوق بالنتيجة
TslTrustAnchorProvider::buildBundle	TslDocument $tsl, DateTimeImmutable $now	يؤكّد الحداثة أولًا، ثم يجمع شهادات خدمات CA/QC النشطة	EnterpriseCaTrustAnchorBundle	TslParseException	بوابة الحداثة تسبق أي استخراج للمراسي؛ ومجموعة النتائج الفارغة ترمي استثناءً
TslDocument	ثمانية خصائص readonly مُرقّاة (انظر سياج المنشئ)	كائن قيمة TSL محلَّل وغير قابل للتغيير	—	—	final readonly؛ مُعلَّم في المصدر بـ @api
TslDocument::isStale	DateTimeImmutable $now	يقارن nextUpdate مقابل $now بعد تحليل UTC مغلق-عند-الفشل	bool	TslParseException	يتطلّب مُحدِّد Z صريحًا أو مُحدِّد إزاحة رقمي
TslDocument::assertFresh	DateTimeImmutable $now	يرمي عندما تكون القائمة متقادمة أو nextUpdate غير قابل للتحليل	void	TslParseException	بوابة الحداثة عند حدود المستهلك
TslDocument::servicesOfType	string $serviceTypeIdentifier	يرشّح الخدمات حسب URI نوع الخدمة في ETSI	list<TspService>	لا يرمي	—
TslDocument::activeServices	—	يُرجع الخدمات ذات حالة granted فقط	list<TspService>	لا يرمي	granted تعني TspService::STATUS_GRANTED
TspService	ثمانية خصائص readonly مُرقّاة	مُدخل خدمة ثقة واحدة داخل TSL	—	—	final readonly؛ ثوابت للحالة ولـ URIs نوع الخدمة
TspService::isGranted	—	تساوي الحالة مقابل URI الحالة granted	bool	لا يرمي	—
TspService::isQualifiedCa	—	تساوي النوع مقابل URI الخاص بـ CA/QC	bool	لا يرمي	—
TspServiceQualifier	string $qualifierUri, string $criteriaListAssert = 'all', array $policyOidConditions = [], array $keyUsageConditions = []	مُؤهِّل خدمة ETSI واحد مع معايير اختيارية	—	—	final readonly؛ الثوابت FOR_ESIG, FOR_ESEAL, FOR_WSA, QSCD_STATEMENT, NO_QSCD
EnterpriseCaTrustAnchorBundle	array $anchorsPem, string $bundleVersion, string $bundleSha256	حزمة مراسي مثبَّتة؛ تتحقق من مطابقة البصمة المُقدَّمة للمراسي المُقدَّمة عند البناء	—	InvalidArgumentException	احصل عليها من buildBundle()؛ ولا تبنِها يدويًا؛ تُنفّذ TrustAnchorStoreInterface
EnterpriseCaTrustAnchorBundle::containsFingerprint	string $anchorDerSha256Hex	عضوية المرساة بواسطة SHA-256 ست عشري فوق جسم DER	bool	لا يرمي	—
EnterpriseCaTrustAnchorBundle::computeBundleSha256	array $anchorsPem	SHA-256 قانوني فوق سَلسَلة PEM المُطبَّعة بأسطر جديدة	string	لا يرمي	static
TslFetchException	—	يشير إلى فشل استرجاع TSL	—	—	final؛ يوسّع RuntimeException
TslParseException	—	يشير إلى فشل بنيوي أو فشل حداثة	—	—	final؛ يوسّع RuntimeException
TslSignatureException	string $reason, string $message	يشير إلى فشل التحقق بـ XMLDSig برمز سبب	—	—	final؛ العام readonly $reason (انظر رموز الأسباب أدناه)

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

عقد السلوك

• ترتيب خط الأنابيب ثابت: الجلب، ثم التحقق بـ ⁨XML⁩DSig، ثم التحليل البنيوي، ثم بوابة التقادم. يُرجع ⁨TslPolicyEnforcer⁩ الكائن ⁨TslDocument⁩ فقط عندما تنجح الأربع جميعها. تُوقِّع القائمةَ الموثوقةَ مشغِّلُ مخططها كي يتمكن الأطراف المعتمِدة من فحص الأصالة والسلامة — ETSI TS 119 612 §5.7.1.
• الصنف ⁨TslXmlParser⁩ محايد تجاه التوقيع بحكم التصميم. على المستدعين التحقق من التوقيع قبل الوثوق بأي حقل محلَّل. ويفرض ⁨TslPolicyEnforcer::verifyXml()⁩ هذا الترتيب.
• يُفرَض ثابت الحداثة عند كل حدود مستهلك. أي قائمة انقضى ⁨nextUpdate⁩ الخاص بها تكون منتهية الصلاحية وتُرفض — ETSI TS 119 612 §5.3.15. تُبوِّب ⁨verifyXml()⁩ مقابل وقت النظام الحالي؛ بينما تُبوِّب ⁨TslDocument::assertFresh()⁩ و⁨buildBundle()⁩ مقابل لحظة يوفّرها المستدعي.
• تحليل الحداثة مغلق-عند-الفشل. حقول التاريخ والوقت قيم UTC وفق ISO 8601 مع مُحدِّد صريح — ETSI TS 119 612 §5.1.3. أي ⁨nextUpdate⁩ دون مُحدِّد Z صريح أو إزاحة رقمية يرفع ⁨TslParseException⁩؛ ولا تُعاد تفسير القيمة أبدًا في المنطقة الزمنية المحلية للخادم.
• يستدعي ⁨buildBundle()⁩ الدالة ⁨assertFresh($now)⁩ قبل استخراج أي مرساة، ثم يقبل فقط الخدمات التي هي granted وCA/QC معًا. granted وwithdrawn هما URIs حالة الخدمة المؤهَّلة — ETSI TS 119 612 §5.5.4. وCA/QC هو URI نوع خدمة الجهة المصدِّقة المؤهَّلة — ETSI TS 119 612 §5.5.1.1.
• يُشتق إصدار الحزمة من إقليم المخطط ومن رقم تسلسل TSL. رقم التسلسل رتيب عبر الإصدارات — ETSI TS 119 612 §5.3.2. وبصمة الحزمة هي SHA-256 قانوني فوق PEMs المراسي، وتجيب ⁨containsFingerprint()⁩ عن العضوية بواسطة SHA-256 فوق DER.
• لا يثق المُتحقِّق إلا بالمراسي المُهيّأة. الشهادات الموجودة في ⁨KeyInfo⁩ تعمل كورقة الموقِّع والوسائط المرشَّحة؛ ويجب أن تصل السلسلة إلى مرساة مُهيّأة ضمن عمق 8، وأن يكون كل رابط صالحًا زمنيًا، وأن تحمل الشهادة المُصدِّرة ⁨basicConstraints⁩ بقيمة ⁨cA=TRUE⁩ (مع ⁨keyCertSign⁩ عند وجود ⁨keyUsage⁩).
• ملف التحقق قائمة سماح: RSA أو ECDSA مع SHA-256 أو SHA-384 أو SHA-512؛ وطرق تلخيص SHA-256 أو SHA-384 أو SHA-512؛ والتقنين الحصري (exclusive canonicalization) فقط؛ وتحديدًا زوج تحويل التوقيع المغلَّف مع exclusive-C14N على ⁨ds:Reference⁩ المغطّي للقائمة. وأي شيء آخر يفشل بـ ⁨unsupported_algorithm⁩ أو ⁨unsupported_transform⁩.
• يرفض ⁨TslFetcher⁩ عناوين URL غير ⁨HTTP⁩S ويطبّق حارس SSRF قبل أي خروج. تحت ⁨NetworkPolicy::STRICT_OFFLINE⁩ يُقدِّم جسمًا مخزَّنًا مؤقتًا سابقًا أو يرفع ⁨NetworkPolicyViolation⁩؛ ولا يُرسَل أي طلب صادر إطلاقًا.

الحالات الحدّية وأنماط الفشل

• قائمة متقادمة. ⁨TslParseException⁩ من ⁨verifyXml()⁩ أو ⁨assertFresh()⁩ أو ⁨buildBundle()⁩ تعني أن مصدر الثقة غير قابل للاستخدام. عامِلها كفشل تحديث تشغيلي، لا كحكم على التوقيع.
• ‏nextUpdate غير قانوني. أي قيمة دون مُحدِّد Z صريح أو إزاحة رقمية ترمي بدلًا من التحليل المتساهل. تفرض ETSI TS 119 612 §⁨5.1.3⁩ صيغة UTC بمُحدِّد Z؛ كما تقبل البوابة إزاحة رقمية صريحة وترفض ما عدا ذلك.
• انحراف وقت-الاستخدام. تُبوِّب ⁨verifyXml()⁩ عند وقت التحقق؛ فأي مستند مُحتفَظ به في الذاكرة بعد ⁨nextUpdate⁩ يظل يفشل في بوابة ⁨buildBundle($tsl, $now)⁩ اللاحقة.
• تهيئة مراسي فارغة. يرفض ⁨TslSignatureVerifier⁩ البناء بقائمة مراسي فارغة (⁨InvalidArgumentException⁩).
• لا خدمات صالحة للاستخدام. قائمة حديثة دون خدمات CA/QC ذات حالة granted ترفع ⁨TslParseException⁩ من ⁨buildBundle()⁩؛ ولا تُنتَج حزمة فارغة أبدًا.
• الوضع دون اتصال. ⁨STRICT_OFFLINE⁩ دون جسم مخزَّن مؤقتًا يرفع ⁨NetworkPolicyViolation⁩. يسبق البحثُ في الذاكرة المؤقتة فحصَ السياسة، فتظل قائمة مخزَّنة مؤقتًا تُبقي التحقق المعزول عن الشبكة يعمل.
• استجابة مفرطة الحجم أو فارغة. يقرأ ⁨fetch()⁩ $maxBytes بايت كحد أقصى (الافتراضي 16 MiB)؛ وأي قائمة مبتورة تفشل عندئذٍ في التحقق من البصمة لاحقًا. والجسم الفارغ يرفع ⁨TslFetchException⁩.
• ‏DOCTYPE في الـ ⁨XML⁩. أي DOCTYPE يُرفض قبل أن يبني libxml جدول كيانات، ومرة أخرى بعد التحميل. يغلق هذا فئتَي إدخال XXE وتوسّع الكيانات (billion-laughs).
• توقيعات متعددة. يُزال فقط ⁨ds:Signature⁩ المغلَّف المُتحقَّق منه قبل حساب البصمة؛ وتُحفظ التوقيعات الشقيقة والتوقيعات المضادة. ويُسمح بمراجع XAdES إضافية، لكن يجب أن يغطّي ⁨ds:Reference⁩ واحد بالضبط جذر المستند.
• مادة سلسلة منتهية الصلاحية. أي موقِّع أو وسيط أو مرساة منتهية الصلاحية أو غير صالحة بعد تفشل بالسبب ⁨expired_anchor⁩. ويوسّع ⁨clockTolerance⁩ نافذة القبول بشكل متناظر وقيمته الافتراضية ⁨0⁩.

السلوك في وضع ⁨FIPS⁩

قائمة سماح المُتحقِّق مثبَّتة على RSA وECDSA مع عائلة SHA-2؛ وSHA-1 وMD5 مُستبعَدان بنيويًا. يُجرى حساب التوقيع في تشفير برمجي مُضمَّن (phpseclib). لا تقدّم ⁨NextPDF⁩ أي ادعاء بمصادقة FIPS 140-3 لذلك الحساب. ملف سياسة التشفير Enterprise FIPS 140-3 مُوثَّق مع وحدة الأمان؛ وهو يقيّد اختيار الخوارزميات ولا يغيّر بنى القوائم الموثوقة ولا سلوك هذه الوحدة المغلق-عند-الفشل.

المطابقة

الادعاء	المعيار	البند
أي قائمة موثوقة انقضى تحديثها التالي تُطرح بوصفها منتهية الصلاحية.	ETSI TS 119 612	§5.3.15
حقول التاريخ والوقت سلاسل ISO 8601 بتوقيت UTC مع مُحدِّد Z.	ETSI TS 119 612	§5.1.3
يوقِّع مشغِّل المخطط القائمة الموثوقة لأجل الأصالة والسلامة.	ETSI TS 119 612	§5.7.1
حالة الخدمة المؤهَّلة هي URI الحالة granted أو withdrawn.	ETSI TS 119 612	§5.5.4
تُعرَّف الجهة المصدِّقة المؤهَّلة بواسطة URI نوع الخدمة Svctype/CA/QC.	ETSI TS 119 612	§5.5.1.1
رقم تسلسل TSL يبدأ من 1 ويتزايد عند كل إصدار.	ETSI TS 119 612	§5.3.2

جميع البنود مُعاد صياغتها؛ ولا تعيد ⁨NextPDF⁩ إنتاج النص المعياري. لا تقدّم ⁨NextPDF⁩ أي ادعاء بمطابقة ETSI TS 119 612 ولا أي ادعاء بمصادقة eIDAS. استهلاك قائمة موثوقة لا يجعل توقيعًا أو شهادة أو مخرَجًا من ⁨NextPDF⁩ “مؤهَّلًا”؛ فالتأهيل يعود إلى مزوّد خدمة الثقة تحت إشراف الدولة العضو، والأثر القانوني خارج هذه الوحدة. قيود نموذج معالجة ⁨XML⁩DSig (تحويل التوقيع المغلَّف، والتقنين الحصري، والمرجع المغطّي للجذر) مُوثَّقة من ملف التحقق الخاص بالمنتج؛ ومواصفة W3C ⁨XML⁩ Signature خارج مجموعة الأدلة المُستشهَد بها. تقرّر هذه الوحدة فقط ما إذا كانت قائمة ما مقبولة كمُدخل ثقة؛ أما التحقق من مسار الشهادة مقابل المراسي الناتجة فيعود إلى طبقة التحقق من الشهادات.

ملاحظات التطوير

• التبعيات هي واجهات PSR: عميل ⁨PSR-18⁩، ومصنع طلبات PSR-17، وذاكرة مؤقتة PSR-16 اختيارية. احقن بدائل داخل الذاكرة في الاختبارات؛ ولا تتطلّب أي مرحلة وصولًا فعليًا للشبكة سوى ⁨fetch()⁩ باردة.
• ثبِّت المرساة العليا خارج النطاق. بالنسبة لقوائم الدول الأعضاء، تخوّل مرساة LOTL موقِّعي القوائم؛ ولا يُمهِّد المُتحقِّق الثقة أبدًا من محتوى ⁨KeyInfo⁩.
• الاستطلاع الدوري في الخلفية، ومعالجة pivot-LOTL، ومصادقة mutual-TLS أو الوكيل خارج نطاق الجالب في هذا الإصدار. جدوِل التحديث خارجيًا وأعِد الجلب قبل كل ⁨nextUpdate⁩.
• مرّر لحظة التحقق، لا لحظة البناء، إلى ⁨buildBundle()⁩. أعِد بناء الحزمة بعد كل تحديث؛ ولا تخزّن حزمة مؤقتًا بعد ⁨nextUpdate⁩ لقائمة المصدر أبدًا.
• الحقل ⁨bundleVersion⁩ له الشكل القابل للملاحظة ⁨tsl-<territory>-seq<sequenceNumber>⁩؛ ويدعم ⁨rawXmlSha256⁩ على ⁨TslDocument⁩ سجلات الأدلة وكشف إعادة التشغيل.
• مُدخلات الخدمة المشوَّهة تُحلَّل بقيم نائبة دفاعية؛ وأي هوية رقمية مشوَّهة تصل إلى بناء الحزمة تفشل مغلقًا بـ ⁨InvalidArgumentException⁩.
• تحمل الأصناف تعليقات مصدرية للحزمة ⁨@since 1.10.0⁩ (⁨TslFetchException⁩: ⁨3.2.0⁩). والأصناف ⁨TslDocument⁩ و⁨TspService⁩ و⁨TspServiceQualifier⁩ مُعلَّمة في المصدر بـ ⁨@api⁩.

انظر أيضًا

• مستويات ضمان eIDAS — صفحة القدرة التي تربط أدلة القائمة الموثوقة بمستويات الضمان.
• حاويات ASiC — مستهلك لـ TslTrustAnchorProvider::buildBundle() لأجل ربط ثقة الحاوية.
• التحقق من التوقيع — جانب التحقق من AdES/⁨PAdES⁩ الذي يستهلك مراسي الثقة.
• الأمان — مرجع متعمّق — سطح أمان Enterprise المُجمَّع.
• التوقيع — مرجع متعمّق — مُنتِج المدى الطويل ⁨PAdES⁩ B-LT وB-LTA.

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح الـ ⁨API⁩ العام المدعوم فقط. مسارات مساحات الاسم الداخلية والأصناف المساعِدة وجداول الآليات وأسماء ملفات كتيّبات التشغيل وبادئات التذاكر خارج النطاق.