إنتقل إلى المحتوى الرئيسي

تدفّق الاتصال

يساعد فهم تدفّق الاتصال في استكشاف المشكلات وتحسين الأداء. تقدّم هذه الصفحة نظرة عالية المستوى لكيفية تدفّق العمليات عبر النظام من قاعدة بيانات Oracle إلى DuoKey Cockpit والعودة.

مرجع API: تُوثَّق نقاط نهاية API وصيغ الطلب/الاستجابة التفصيلية بشكل منفصل في وثائق المطوّرين.

نظرة عامة​

تدفّق العملية النموذجي​

تدفّق التهيئة​

الخطوات:

  1. يستدعي Oracle الدالة C_Initialize(): تبدأ تهيئة المكتبة
  2. قراءة التكوين: تقرأ المكتبة قيمتَي server_url وaccess_guid من ملف pkcs11.toml
  3. المصادقة: تقدّم المكتبة رمز حامل access_guid الخاص بها إلى Cockpit في أوّل طلب لها
  4. التحقّق من جانب الخادم: يتحقّق Cockpit من الرمز ويحلّ المستأجر انطلاقًا من هوية التطبيق؛ ولا يجري أي تبادل منفصل للرموز
  5. التحقّق من الـ Vault: التحقّق من الوصول إلى الـ Vault المحدّد
  6. إرجاع النجاح: المكتبة جاهزة للعمليات

تدفّق إنشاء الجلسة​

الخطوات:

  1. يستدعي Oracle الدالة C_OpenSession(): طلب جلسة جديدة
  2. التحقّق من الفتحة: التأكّد من صلاحية معرّف الفتحة
  3. إنشاء الجلسة: إنشاء كائن جلسة داخلي
  4. تهيئة الجداول: إنشاء جدول ربط المقابض للجلسة
  5. إرجاع المقبض: إرجاع مقبض الجلسة إلى Oracle

ملاحظة: لا يتطلّب إنشاء الجلسة استدعاءات API. تُدار الجلسات محليًا.

تدفّق تسجيل الدخول​

الخطوات:

  1. يستدعي Oracle الدالة C_Login(): طلب تسجيل الدخول للجلسة
  2. التحقّق من الرمز: التأكّد من أنّ رمز حامل access_guid مُهيّأ في ملف pkcs11.toml
  3. وسم الجلسة: وسم الجلسة على أنها مصادَق عليها
  4. إرجاع النجاح: إرجاع CKR_OK

ملاحظة: بالنسبة لـ DuoKey PKCS#11، تحدث المصادقة أثناء C_Initialize()، عندما تقدّم المكتبة رمز حامل access_guid الخاص بها إلى Cockpit. تؤكّد الدالة C_Login() توفّر الرمز ولكنها لا تجري استدعاءات API إضافية.

تدفّق توليد المفاتيح​

الخطوات:

  1. يستدعي Oracle الدالة C_GenerateKey(): طلب توليد مفتاح
  2. تحليل القالب: استخراج سمات المفتاح (النوع، الحجم، التسمية)
  3. بناء طلب API: إنشاء طلب توليد المفتاح
  4. استدعاء API: إرسال طلب توليد المفتاح إلى Cockpit
  5. التوليد في HSM: يولّد HSM الخلفي المفتاح
  6. استلام UUID: يُرجع Cockpit معرّف UUID للمفتاح
  7. إنشاء المقبض: ربط UUID بمقبض PKCS#11
  8. إرجاع المقبض: إرجاع المقبض إلى Oracle

تدفّق التشفير​

الخطوات:

  1. يستدعي Oracle الدالة C_Encrypt() / C_WrapKey(): طلب تغليف على مسار المفتاح الرئيسي (على سبيل المثال حماية مفتاح مساحة جدولية)
  2. البحث عن المقبض: العثور على UUID لمقبض المفتاح الرئيسي المقدّم
  3. تحليل الآلية: استخراج الخوارزمية (AES-CBC / AES-CBC-PAD) وناقل التهيئة IV
  4. بناء الطلب: إنشاء طلب التغليف
  5. استدعاء API: إرسال طلب التغليف إلى Cockpit
  6. التغليف في HSM: يُجري HSM الخلفي تغليف AES-CBC(-PAD) المحافظ على الطول
  7. استلام المفتاح المغلّف: الحصول على البيانات المغلّفة
  8. إرجاع النتيجة: الإرجاع إلى Oracle

ملاحظة: يستخدم التغليف آلية AES-CBC / AES-CBC-PAD المحافظة على الطول. يجب عدم استخدام مغلّف AES-GCM التوسّعي على هذا المسار — فهو يكسر عملية SET KEY في Oracle مع الخطأ ORA-00600 [kcbtse_populate_tbskey_1]. يُجري Oracle تشفير الجداول والمساحات الجدولية بكميات كبيرة محليًا باستخدام AES-NI، ولا يغادر ذلك قاعدة البيانات أبدًا.

تدفّق فكّ التشفير​

الخطوات:

  1. يستدعي Oracle الدالة C_Decrypt() / C_UnwrapKey(): طلب فكّ تغليف على مسار المفتاح الرئيسي (على سبيل المثال استعادة مفتاح مساحة جدولية عند فتح مخزن المفاتيح / SET KEY)
  2. البحث عن المقبض: العثور على UUID لمقبض المفتاح الرئيسي المقدّم
  3. تحليل الآلية: استخراج الخوارزمية (AES-CBC / AES-CBC-PAD) وناقل التهيئة IV
  4. بناء الطلب: إنشاء طلب فكّ التغليف
  5. استدعاء API: إرسال طلب فكّ التغليف إلى Cockpit
  6. فكّ التغليف في HSM: يُجري HSM الخلفي فكّ تغليف AES-CBC(-PAD) المحافظ على الطول
  7. استلام مفتاح المساحة الجدولية: الحصول على المفتاح المفكوك التغليف
  8. إرجاع النتيجة: الإرجاع إلى Oracle

تدفّق البحث عن الكائنات​

الخطوات:

  1. C_FindObjectsInit(): تهيئة البحث بقالب
  2. تحليل القالب: استخراج معايير البحث (التسمية، الفئة، إلخ)
  3. C_FindObjects(): تنفيذ البحث
  4. استدعاء API: إرسال طلب البحث عن الكائنات إلى Cockpit
  5. استلام UUIDs: الحصول على معرّفات UUID للكائنات المطابقة
  6. إنشاء المقابض: ربط UUIDs بالمقابض
  7. إرجاع المقابض: إرجاع مصفوفة المقابض إلى Oracle
  8. C_FindObjectsFinal(): تنظيف حالة البحث

تدفّق معالجة الأخطاء​

معالجة أخطاء الشبكة​

معالجة أخطاء المصادقة​

ملاحظة: إنّ access_guid هو رمز حامل ساكن مفرد. لا توجد نقطة نهاية للرموز ولا دورة تجديد، لذا فإنّ رفض الرمز هو خطأ نهائي (تحقّق من access_guid في ملف pkcs11.toml) وليس شيئًا تعيد المكتبة محاولته.

معالجة أخطاء HSM​

تحسين الأداء​

إعادة استخدام الاتصال​

الفوائد:

  • يلغي أعباء مصافحة TCP
  • يقلّل وقت إنشاء الاتصال
  • يحسّن الإنتاجية الإجمالية

رمز الحامل​

تصادق المكتبة على كلّ طلب باستخدام رمز حامل access_guid مفرد مضمّن في server_url الخاص بوكيل التطبيق. لا توجد نقطة نهاية للرموز ولا دورة تجديد: يُقدَّم الرمز نفسه في كلّ طلب ويتحقّق منه Cockpit من جانب الخادم، فيحلّ المستأجر انطلاقًا من هوية التطبيق.

الفوائد:

  • لا توجد جولات ذهاب وإياب لتبادل الرموز
  • لا يوجد سرّ زمن تشغيل يجب تدويره (لا client_id / client_secret)
  • تُقلّل استمرارية الاتصال من مصافحات TLS لكلّ عملية

تخزين المقابض مؤقتًا​

الفوائد:

  • يتجنّب استدعاءات API المكرّرة
  • تحليل أسرع للمقابض
  • تقليل حركة مرور الشبكة

المراقبة وتصحيح الأخطاء​

تتبّع الطلبات​

فعّل تسجيل التصحيح لتتبّع الطلبات:

export DKE_PKCS11_LOGGING_LEVEL=debug
export DKE_PKCS11_LOGGING_FOLDER=/var/log/dke-pkcs11

مخرجات السجل:

[2025-12-19 10:30:45] [DEBUG] C_Initialize() called
[2025-12-19 10:30:45] [DEBUG] Reading pkcs11.toml (server_url, access_guid)
[2025-12-19 10:30:45] [INFO] Connecting to DuoKey Cockpit: https://cockpit-api-dev.duokey.cloud
[2025-12-19 10:30:46] [INFO] access_guid bearer token validated by Cockpit
[2025-12-19 10:30:46] [DEBUG] C_Initialize() completed: CKR_OK

مقاييس الأداء​

راقب المقاييس الرئيسية:

  • زمن انتقال الطلب: الوقت من استدعاء Oracle إلى الاستجابة
  • زمن انتقال API: الوقت لاستدعاءات API الخاصة بـ DuoKey Cockpit
  • معدّل الأخطاء: نسبة الطلبات الفاشلة
  • إخفاقات المصادقة: عدد رموز حامل access_guid المرفوضة

مراقبة الشبكة​

راقب حركة مرور الشبكة:

  • اتصالات HTTPS: عدد الاتصالات النشطة
  • أحجام الطلب/الاستجابة: أحجام الحمولات
  • عدد المحاولات: عدد إعادات المحاولة لكل طلب
  • أحداث انتهاء المهلة: تكرار انتهاءات المهلة

أفضل الممارسات​

معالجة الأخطاء​

  1. أعد محاولة الأخطاء العابرة: أخطاء الشبكة، انتهاءات المهلة
  2. لا تعد محاولة أخطاء المصادقة: بيانات الاعتماد غير الصالحة
  3. سجّل جميع الأخطاء: لاستكشاف المشكلات
  4. أرجِع الرموز المناسبة: الترجمة إلى رموز PKCS#11

الأداء​

  1. أعد استخدام الاتصالات: استخدم تجميع الاتصالات
  2. أبقِ الاتصالات نشطة: توزيع مصافحات TLS عبر العمليات
  3. جمّع العمليات: عند الإمكان (مستقبلًا)
  4. راقب زمن الانتقال: تتبّع مقاييس الأداء

الأمن​

  1. استخدم TLS: جميع الاتصالات مشفّرة
  2. تحقّق من الشهادات: تحقّق صارم من الشهادات
  3. أمّن بيانات الاعتماد: لا تسجّل access_guid أبدًا
  4. احمِ ملف pkcs11.toml: تعامل مع رمز حامل access_guid كسرّ؛ وقيّد أذونات الملف

الخطوات التالية​