واجهة الخزائن والمفاتيح
تسجيل خلفيات الخزائن، وربطها بالتطبيقات، وإدارة مادة المفاتيح التي تحملها.
نظرة عامة
يقع كل مسار في هذه الصفحة ضمن واجهة الإدارة المصادَق عليها عند /api/…. يحمل كل طلب رمزاً حاملاً:
Authorization: Bearer <access-token>
تعمل الطلبات ضمن السياق الأمني لـ المستأجر المُشفَّر داخل الرمز — فأنت لا تمرر معرّف مستأجر أبداً، ولا ترى أو تعدّل سوى خزائن ومفاتيح مستأجرك الخاص. تخضع إجراءات الخزائن والمفاتيح أيضاً لبوابة أذونات الخزائن: يجب أن يمتلك المتصل الإذن الذي يتطلبه المسار (مثل تسجيل خزنة، أو مزامنة مفاتيحها، أو تنفيذ عملية تشفير بمفتاح).
راجع نظرة عامة على API لعناوين URL الأساسية وتعدد المستأجرين ونموذج الأخطاء، والمصادقة لمعرفة كيفية الحصول على رمز.
إدارة الخزائن
الخزنة (vault) هي سجل مخزَّن ومحدد النطاق بالمستأجر يصف نسخة واحدة من خلفية (برمجية، أو MPC، أو HSM، أو KMS سحابي). تسجّل هذه المسارات الخزائن، وتفحص سلامة الخلفية وأداءها، وتكتشف أو تستورد المفاتيح التي تحملها الخلفية بالفعل.
| الطريقة + المسار | الغرض |
|---|---|
GET · POST /api/vaults | سرد الخزائن · تسجيل خزنة جديدة |
GET · PUT · DELETE /api/vaults/{id} | الحصول على خزنة واحدة أو تحديثها أو حذفها |
POST /api/vaults/test-connection | اختبار خلفية قبل إنشاء الخزنة |
GET /api/vaults/{id}/health · /version | سلامة الخلفية وإصدارها |
POST /api/vaults/{id}/benchmark · /crypto-test | اختبار أداء مرجعي وفحص عملية تشفير كاملة |
GET /api/vaults/{id}/keys · /remote-key-count | المفاتيح الموجودة في خزنة وعدد المفاتيح في الخلفية البعيدة |
POST /api/vaults/{id}/sync-keys | اكتشاف / استيراد مفاتيح الخلفية الموجودة |
ربط التطبيقات بالخزائن
تُربط التطبيقات بالخزائن التي يجوز لها استخدامها؛ ويُربط المفتاح المُنشأ لتطبيق ما بخزنة محددة.
| الطريقة + المسار | الغرض |
|---|---|
GET /api/apps/{id}/vaults | سرد الخزائن المرتبطة بتطبيق |
POST · DELETE /api/apps/{id}/vaults/{vault_id} | ربط · إلغاء ربط خزنة بتطبيق |
أنواع الخزائن وأنواع المفاتيح
استخدم مسارات القراءة فقط هذه لاكتشاف الخلفيات التي تدعمها المنصة وأنواع المفاتيح التي تقبلها كل خلفية، قبل تسجيل خزنة أو إنشاء مفتاح.
| الطريقة + المسار | الغرض |
|---|---|
GET /api/vaults/types | أنواع الخزائن (الخلفيات) المتاحة |
GET /api/vaults/types/{type}/key-types | أنواع المفاتيح المدعومة لنوع خزنة معيّن |
المفاتيح
تُنشأ المفاتيح التشفيرية داخل خزنة ويُشار إليها عبر vault_id. تدير هذه المسارات دورة حياة المفتاح — الإنشاء، والسرد، والحصول عليه، والتدوير، وانتقالات التفعيل/التعطيل — وتنفّذ عمليات تشفير باستخدامه. تبقى مادة المفاتيح الخاصة والمتماثلة داخل الخلفية؛ ولا يمكن تصدير سوى المفاتيح العامة.
| الطريقة + المسار | الغرض |
|---|---|
GET · POST /api/keys | سرد المفاتيح · إنشاء مفتاح جديد |
GET · PUT · DELETE /api/keys/{id} | الحصول على مفتاح، أو تحديث بياناته الوصفية، أو حذفه |
POST /api/keys/{id}/rotate | تدوير مفتاح إلى إصدار جديد |
POST /api/keys/{id}/activate · /deactivate | تفعيل المفتاح (Active) أو تعطيله (Deactivated) |
POST /api/keys/{id}/revoke | إبطال مفتاح مع تحديد سبب |
GET /api/keys/{id}/public-key | تصدير المفتاح العام بصيغة PEM |
POST /api/keys/{id}/encrypt · /decrypt | تشفير نص صريح · فك تشفير نص مشفَّر باستخدام المفتاح |
GET /api/keys/{id}/apps | سرد التطبيقات التي تستخدم هذا المفتاح |
لا يوجد مسار منفصل لـ enable / disable: ينقل activate المفتاح إلى حالة Active، وينقله deactivate إلى حالة Deactivated. لا يمكن استخدام سوى مفتاح في حالة Active لعمليات التشفير.
لا يمكن إنشاء أنواع مفاتيح ما بعد الكم (ML-KEM، وML-DSA، وSLH-DSA) إلا في خزنة مدعومة بـ Software Vault أو Securosys. استخدم GET /api/vaults/types/{type}/key-types للتأكد من أن الخلفية تقبل نوع المفتاح الذي تحتاجه قبل إنشائه.