العقود

لمحة سريعة

يعرض ⁨NextPDF Enterprise⁩ مجموعةً صغيرة من الواجهات العامة التي ترتبط بها مكوّنات ⁨Enterprise⁩ من أجل عكس الاعتمادية وقابلية الاختبار. والأول عقد عميل ⁨TSA⁩ لطلب رموز الطابع الزمني وفق ⁨RFC 3161⁩. وهذه فصول تكامل. وهي لا تؤدّي بنفسها عمليات تشفير ولا تؤكّد أي مطابقة.

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

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

التثبيت

composer require nextpdf/enterprise:^3

نظرة مفاهيمية

يُعلِن TsaClientInterface عملية واحدة: يُرجِع getDocumentTimestamp($documentHash) رمز ⁨TimeStampToken⁩ مُرمَّزًا بـ ⁨DER⁩ وفق ⁨RFC 3161⁩ لتجزئة مستند. وتقبل مكوّنات ⁨Enterprise⁩ هذه الواجهة بدلًا من عميل محدَّد حتى يمكن حقن سلوك الطابع الزمني واستبداله في الاختبارات.

‏TsaClientAdapter غلاف رفيع يُكيِّف عميل الطابع الزمني في ⁨Core⁩ مع هذه الواجهة. وعميل ⁨Core⁩ صنف نهائي ولا يمكنه تنفيذ واجهة ⁨Enterprise⁩ مباشرةً، فيجسر المُحوِّل الاثنين دون تغيير السلوك. احقِن TsaClientInterface في كل مكان؛ ووصّل TsaClientAdapter (أو تنفيذك الخاص) عند جذر التركيب.

ما الذي تؤكّده هذه الوحدة

تتولّى هذه الوحدة تعريف عقود التكامل. وهي لا تؤدّي عملًا بنفسها.

• يصف TsaClientInterface كيفية الحصول على رمز طابع زمني. وهو لا يتحقق من الرمز، ولا يضمن ⁨TSA⁩، ولا يؤكّد أن الرمز يمنح أثرًا قانونيًّا.
• يمرّر TsaClientAdapter الاستدعاءات دون تغيير؛ وهو لا يضيف سلوكًا ولا ضمانات.

الحصول على رمز طابع زمني يدعم مسارات التدقيق والتحقق طويل الأمد؛ وهو ليس تصديقًا قانونيًّا ولا اعتمادًا.

حدّ الدرجة

‏«العقود» سطح تكامل يقتصر على ⁨Enterprise⁩. ويقيم عميل ⁨TSA⁩ المحدَّد في ⁨Core⁩ (NextPDF\Security\Timestamp)؛ وتوفّر هذه الوحدة فقط الواجهة المُوجَّهة لـ ⁨Enterprise⁩ والمُحوِّل حتى تبقى مكوّنات ⁨Enterprise⁩ مفصولة وقابلة للاختبار.

لماذا يعمل بهذه الطريقة

عميل ⁨Core⁩ ‏TsaClient صنف final، لذا لا يمكنه تنفيذ واجهة ⁨Enterprise⁩ مباشرةً. ومع ذلك تظل ⁨Enterprise⁩ بحاجة إلى فصل طابع زمني قابل للحقن وللمحاكاة من أجل عكس الاعتمادية والمكوّنات القابلة للاختبار. ويحل ⁨NextPDF⁩ هذا بامتلاك الواجهة في درجة ⁨Enterprise⁩ وجسر عميل ⁨Core⁩ المحدَّد عبر مُحوِّل رفيع. وتبقى الرحلة كاملةً في ⁨Core⁩؛ وتكسب ⁨Enterprise⁩ عقدًا مستقرًّا دون تكرار العميل أو إضعاف ضمان final. ثم لا يتطلب استبدال تنفيذ زائف في الاختبارات أي تغيير في شيفرة ⁨Core⁩.

خلفية التصميم: ‏الطوابع الزمنية والوقت الموثوق.

سطح واجهة البرمجة

الصنف / الواجهة	المسؤولية
TsaClientInterface	عقد: طلب رمز طابع زمني بترميز ⁨DER⁩ وفق ⁨RFC 3161⁩.
TsaClientAdapter	تكييف عميل الطابع الزمني في ⁨Core⁩ مع TsaClientInterface.

نموذج شيفرة — بداية سريعة

use NextPDF\Enterprise\Contracts\TsaClientInterface;

final class MySigner
{
    public function __construct(private TsaClientInterface $tsa) {}
}

نموذج شيفرة — الإنتاج

use NextPDF\Enterprise\Contracts\TsaClientAdapter;

// Composition root: bridge the Core client into the Enterprise contract.
$tsa = new TsaClientAdapter($coreTsaClient);
$container->set(TsaClientInterface::class, $tsa);
// Components depend on the interface; the adapter is wired once here.

الحالات الحدّية والمزالق

• يمرّر المُحوِّل الاستثناءات من العميل الكامن دون تغيير؛ عالِج إخفاقات ⁨TSA⁩ في موضع الاستدعاء.
• الرمز المُرجَع بايتات، لا حكم؛ تحقّق منه واعتمِده حيث يلزم (راجِع الأدلّة / التوقيع).

الأداء

لا تضيف الواجهة والمُحوِّل أي عبء قابل للقياس؛ والكلفة بالكامل رحلة ⁨TSA⁩ الكامنة.

ملاحظات أمنية

عامِل نقطة نهاية ⁨TSA⁩ خلف العميل المحدَّد بوصفها حدّ ثقة. ولا يتحقق هذا العقد من الرمز أو من سلسلة شهادة ⁨TSA⁩؛ والتحقق يخصّ سطحَي التوقيع والأدلّة.

إقامة البيانات وتخفيفات البيانات الشخصية

تعبر هذا العقد تجزئة مستند فقط — لا محتوى مستند. وتنطبق اعتبارات الإقامة على تنفيذ عميل ⁨TSA⁩ المحدَّد، لا على هذه الواجهة.

قياسات آمنة وتنقية السجلات

تجزئة المستند آمنة للتسجيل. لا تسجّل بايتات الرمز الخام في مصارف مشتركة؛ عامِلها بوصفها آثارًا حسّاسة للسلامة.

المطابقة

السلوك	المرجع	الحالة
طلب رمز الطابع الزمني وربطه	IETF RFC 3161 §2	شكل العقد فقط (العمل يؤدّيه العميل المحدَّد)

يسجّل هذا الجدول المواصفة التي صِيغ العقد حولها. وتُعرِّف الواجهة فصلًا؛ وهي لا تقدّم أي ادّعاء مطابقة أو تصديق.

سلوك وضع ⁨FIPS⁩

لا تجري هذه الوحدة أي عملية تشفير. ويحكم عميل ⁨TSA⁩ المحدَّد ووحدة الأمان اختيار الخوارزمية وسلوك وضع ⁨FIPS⁩.

نموذج التهديد

سطح العقد بسيط: تجزئة داخلًا، وبايتات رمز خارجًا. التخفيفات: لا يعبر الحدّ أي محتوى، وتُفوَّض مسؤوليات التحقق صراحةً إلى وحدتَي الأدلّة والتوقيع.

عقد السلوك

• تُعلِن واجهة عميل ⁨TSA⁩ عملية واحدة: إرجاع رمز ⁨TimeStampToken⁩ بترميز ⁨DER⁩ وفق ⁨RFC 3161⁩ لتجزئة مستند؛ وتعتمد مكوّنات ⁨Enterprise⁩ على الواجهة، لا على عميل محدَّد.
• المُحوِّل غلاف رفيع يجسر عميل الطابع الزمني في ⁨Core⁩ مع هذه الواجهة دون تغيير السلوك ويمرّر الاستثناءات من العميل الكامن دون تغيير.
• تصف الواجهة كيفية الحصول على رمز؛ وهي لا تتحقق من الرمز، ولا تضمن ⁨TSA⁩، ولا تؤكّد أثرًا قانونيًّا.
• الرمز المُرجَع بايتات، لا حكم — والتحقق والاعتماد يخصّان سطحَي الأدلّة والتوقيع.

حدّ النشر

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

احتياطي ⁨Core⁩

يقيم عميل ⁨TSA⁩ المحدَّد في ⁨Core⁩؛ وتوفّر هذه الوحدة فقط الواجهة المُوجَّهة لـ ⁨Enterprise⁩ والمُحوِّل حتى تبقى مكوّنات ⁨Enterprise⁩ مفصولة وقابلة للاختبار. ولا مكافئ للفصل المُوجَّه لـ ⁨Enterprise⁩ نفسه في درجة ⁨Core⁩ — إذ يعرض ⁨Core⁩ العميل المحدَّد، لا هذه الواجهة.

احتياطي ⁨Pro⁩

احتياطي ⁨Pro⁩ — لا شيء؛ لهذه القدرة لا مكافئ في درجة ⁨Pro⁩. وتُشحَن واجهة عميل ⁨TSA⁩ المُوجَّهة لـ ⁨Enterprise⁩ والمُحوِّل في حزمة nextpdf/enterprise فقط.

ملاحظة حدّ ⁨Enterprise⁩

تُوصَف الواجهة والمُحوِّل على مستوى السلوك. ويمرّر المُحوِّل الاستدعاءات دون تغيير ولا يضيف سلوكًا؛ وعميل ⁨TSA⁩ المحدَّد وبواطنه شأن ⁨Core⁩ وخارج نطاق سطح تكامل ⁨Enterprise⁩ هذا.

حدّ التوزيع

تعبر هذا العقد تجزئة مستند فقط — لا محتوى مستند. ويوصّل المُشغِّل المُحوِّل أو تنفيذًا مخصّصًا عند جذر التركيب ويملك عميل ⁨TSA⁩ المحدَّد خلفه؛ وتنطبق الإقامة، وحدّ ثقة نقطة نهاية ⁨TSA⁩، والتحقق من سلسلة الشهادات على ذلك العميل المحدَّد، لا على هذه الواجهة.

حدّ الامتثال القانوني

لا ينطبق أي قيد لضوابط التصدير على سطح العقد هذا. والحصول على رمز طابع زمني يدعم مسارات التدقيق والتحقق طويل الأمد؛ وهو ليس تصديقًا قانونيًّا ولا اعتمادًا. وهذه الوثيقة ليست رأيًا قانونيًّا؛ استشِر مستشاريك في الامتثال والشؤون القانونية.

انظر أيضًا

• ‏العقود — المرجع العميق — سطح الأصناف والدوال الكامل.
• ‏الأدلّة — يضمّن رموز ⁨RFC 3161⁩ في الحزم.
• ‏التحقق — فحوصات ⁨LTV⁩ البنيوية.
• ‏المواصفات: ⁨PAdES⁩ — سياق الطابع الزمني.